judg3d

Local acceptance checks for glTF/GLB assets. An asset and a versioned profile produce a verdict with actionable violations, metrics, hashes and explicit coverage. Format validation uses the official Khronos glTF Validator.

Reusable GitHub Action on main · copy-paste workflow · tester guide

0.2.0 is this source (CLI, MCP, local app, compare, fix). 0.1.0 is the last published npm set (app and judge). The historical judg3d@0.0.1 package was a name reservation only. This page does not claim stars, downloads or adoption.

Commands

Requires Node 22.13.0 or later. No OpenAI account or API key is needed.

npx --yes judg3d@0.2.0 app
npx --yes judg3d@0.2.0 judge model.glb -p web-commerce
npx --yes judg3d@0.2.0 compare before.glb after.glb -p profile.json
npx --yes judg3d@0.2.0 fix model.glb -p profile.json
npx --yes judg3d@0.2.0 fix model.glb -p profile.json --apply

Until 0.2.0 is on npm, run the same commands from a source checkout (pnpm build && pnpm judg3d …) or use judg3d@0.1.0 for app and judge. compare exists only in this 0.2.0 source.

Open the local address printed by app. Your asset is processed on your computer.

From source

Use pnpm 11.22.0 to build the repository and run its examples:

git clone https://github.com/victorsodre/judg3d.git
cd judg3d
pnpm install --frozen-lockfile
pnpm build
pnpm judg3d app
pnpm judg3d judge fixtures/valido.glb --profile profiles/web-commerce.json
pnpm judg3d compare fixtures/valido.glb fixtures/quebrado.glb \
  --profile profiles/web-commerce.json
pnpm judg3d fix fixtures/quebrado.glb --profile profiles/web-commerce.json

The app prints its local address, defaulting to http://127.0.0.1:8787. Choose an asset and profile, then run the analysis. Results show coverage, searchable violations and a downloadable report. Changing the asset or profile clears the previous result. Press Ctrl+C to stop the server.

Related MCP server: MCP Gatekeeper

FAILED → PASSED triangle budget

A format-valid box with 3,072 triangles fails a 1,000-triangle budget. The corrected export has 12 triangles and passes the same profile.

pnpm demo:repair
pnpm judg3d compare artifacts/repair-loop/before.glb artifacts/repair-loop/after.glb \
  -p examples/repair-loop/profile.json

compare prints FAILED → PASSED, 3072 → 12 triangles, and TRIANGLES_OVER_BUDGET as removed. Exit 1 is expected: the before asset failed. Exit 0 would mean both assets passed. Exit 2 is infrastructure (including two different profile hashes). PASS still covers SCHEMA and PROFILE only; skipped layers are not visual or geometric approval. See the repair-loop example.

pnpm demo is the shorter gate: the same Box fails a four-triangle budget, a broken asset returns diagnostics, and a missing profile is infrastructure without a verdict. See the reproduction guide and case study.

The local interface shows exactly which checks ran:

Language

The interface, CLI, API, MCP and generated reports use English. The interface does not offer a language selector or store a language preference. User-supplied filenames and profile values are preserved as supplied.

CLI and automation

# Atomic report write that protects the input files.
pnpm judg3d judge model.glb -p profiles/agent-loop.json -o result.json

# JSON on stdout without creating a report file.
pnpm judg3d judge model.glb -p profiles/agent-loop.json --out -

# Before/after diff against the same profile bytes.
pnpm judg3d compare before.glb after.glb -p profiles/agent-loop.json -o compare-report.json

# Ordered repair plan from the current verdict. --apply only runs safe extras stripping.
pnpm judg3d fix model.glb -p profiles/agent-loop.json --report repair-report.json
pnpm judg3d fix model.glb -p profiles/agent-loop.json --apply --out-asset model.fixed.glb

# Runtime information and installed profile directory.
pnpm judg3d engine
pnpm judg3d profiles

Check the exit code before consuming a report file. An infrastructure failure preserves any existing report, which belongs to an earlier run. --out - is useful for pipelines that do not need persistent files. Human-readable output shows up to 200 occurrences and points to the full JSON for the remainder. --json prints the same JSON written to disk; --timestamp adds an optional date. With timestamps disabled, identical inputs, paths and runtime produce byte-identical reports.

GitHub Action

A composite action runs the same CLI through npx and fails the job when an asset is rejected (exit 1). Exit 2 is a hard error, not an asset verdict. On pull_request it also upserts a summary comment (<!-- judg3d-gate -->) with pass/fail, file list, metrics versus budget, an optional before/after block, and a job-log link. Set comment: false to disable. Grant pull-requests: write.

- uses: victorsodre/judg3d/.github/actions/judg3d-gate@main
  with:
    assets: assets/product.glb
    profile: web-commerce
    version: "0.1.0"
    comment: auto

Copy the example workflow, pin the action to a commit SHA, and replace the asset paths. Bundled names web-commerce and agent-loop resolve through judg3d profiles. Copy a profile when you need your own budgets. This repository exercises pass and fail fixtures in .github/workflows/judg3d-gate.yml.

Coverage and profiles

PASS applies to coverage.ran; it does not certify appearance or visual fitness. coverage.skipped lists checks that did not run. External glTF resources are never fetched or read. Set PROFILE requireSelfContained: true to require a portable file with embedded resources.

web-commerce enables SCHEMA only; its name does not imply universal commerce budgets. agent-loop enables SCHEMA and PROFILE with limits from a specific pipeline. Copy it and choose limits for your project. See profiles/README.md.

failOn determines rejection. report controls verbosity without changing the verdict or hiding the severity that caused rejection. Information and Hint retain their original Khronos severity in got.severity; the contract presents them as warn, but they do not cause rejection on their own. maxPerCode summarizes occurrences after validation. A truncated validation caused by maxIssues returns infrastructure failure. Disabling all layers, requesting inheritance through extends, or enabling PROFILE without SCHEMA also returns exit 2.

MCP for agents

The MCP server exposes judge_asset, compare_assets and fix_asset for reading local files. fix_asset returns a repair plan and does not write files. Configure the published CLI and restrict the workspace to your project:

{
  "mcpServers": {
    "judg3d": {
      "command": "npx",
      "args": ["--yes", "judg3d@0.2.0", "mcp", "--root", "/path/to/project"]
    }
  }
}

Tool arguments for judge_asset:

{ "asset": "assets/product.glb", "profile": "profiles/product.json" }

compare_assets takes { "before", "after", "profile" }. Both sides must use the same profile bytes. The compare document records verdicts, metric deltas, violations added/removed/unchanged by code, and a coverage note. Differing coverage never turns an unperformed layer into PASS.

fix_asset takes { "asset", "profile" } and returns structuredContent.repair with an ordered plan (schema, extras, textures, budgets). It does not remesh or mutate the workspace. Use the CLI --apply path to strip unused extras and then compare.

Both paths, including symlink targets, must remain inside the workspace. The tools do not write reports or access URLs. They return structuredContent with ok, exitHint and either report or compare. Asset rejection is a normal result (exitHint: 1); infrastructure failures use isError: true and exitHint: 2. Stdout is reserved for the protocol.

judg3d@0.1.0 on npm includes judge_asset only. This 0.2.0 source adds compare / compare_assets and fix / fix_asset. Use the repository until 0.2.0 is published.

Limits and privacy

CLI, MCP and HTTP analysis use workers with a 30-second deadline and a V8 old generation limit of 256 MiB per analysis; this is not a total RSS cap. Assets are limited to 64 MiB and profiles to 1 MiB. MCP and HTTP allow at most two concurrent analyses. Exceeding processing limits returns infrastructure failure.

The app binds to 127.0.0.1, validates hostname and origin, blocks framing, and prevents static-file access to dotfiles and symlinks outside its root. There is no telemetry, remote upload or external font request. Uploads are processed in memory; reports are written only by the CLI or an explicit download. Configure the app with --port and --profiles. For development:

pnpm app:dev
# UI :5173 and API :8787, with local development origins allowed.

The HTTP API is local, without hosted accounts or authentication. @judg3d/judge also exports an in-process judge() without worker isolation; applications processing untrusted assets should use judgeIsolated().

Verification and release

pnpm typecheck && pnpm lint && pnpm test
pnpm docs:check
pnpm release:pack
pnpm release:check

Packing creates five tarballs and a SHA-256 manifest in artifacts/release/. The check installs them in a clean temporary directory and verifies CLI exit codes, determinism, MCP over stdio, HTTP UI and uploaded asset analysis. It does not publish to npm or change GitHub. CI is configured for Node 22.13, 24 and 26.

Product decisions: specification. Published 0.1.0 notes: docs/release-0.1.0.md. Contributor conventions: AGENTS.md. Historical specification and calibration notes are in Portuguese.

Contribute and integrate

Start with CONTRIBUTING.md, the architecture and agent integration guide. Useful contributions include reproducible edge cases, downstream integration feedback and onboarding improvements. See the roadmap, security policy, support and governance.

Trying judg3d for the first time? Start with the tester guide.

License

MIT for judg3d's original source and documentation. Dependencies and sample assets retain their own licenses; see third-party notices and fixture attribution. Sample assets are excluded from npm packages.