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.

0.1.0 is available on npm. The MIT-licensed release includes the CLI, MCP server and local app. The historical judg3d@0.0.1 package was a name reservation only.

Get started

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

npx --yes judg3d@0.1.0 app

Open the local address printed in the terminal. Your asset is processed on your computer. The tester guide walks through a first trial.

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 judge fixtures/valido.glb --profile profiles/web-commerce.json
pnpm judg3d judge fixtures/quebrado.glb --profile profiles/web-commerce.json
pnpm judg3d app

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.

See what the gate proves

pnpm demo

The same format-valid Box passes SCHEMA and fails a deliberately small triangle budget. A broken asset returns actionable diagnostics; a missing profile returns infrastructure failure without a verdict. The demo checks repeated JSON output and input hashes. See the reproduction guide and case study.

To follow an actual asset correction against an unchanged profile, run pnpm demo:repair. The repair-loop example verifies a 3,072-to-12 triangle reduction and both reports.

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 -

# 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.

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 for reading local files. Configure the published CLI and restrict the workspace to your project:

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

Tool arguments:

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

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

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. Release preparation: 0.1.0 notes. 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.