3D engine that AI agents drive
Crucible for coding agents
Read this before you change code in this repository. CONTRIBUTING.md has the full rules; this file is the short path.
To build scenes with Crucible rather than change it, use the MCP server and the skills in skills/ instead (README).
Stance
Crucible makes 3D easy to understand and easy to do. The agent carries the heavy steps, and the person keeps the creative choices and stays active (docs/goal.md). So:
- A change that people can see ships with a still or a clip rendered by Crucible. Put it in the pull request and in its change note.
- Docs and copy show the result first and explain in plain words before code.
- Agent-facing features return previews and choices, and ask on matters of taste instead of deciding them.
Layout
src/is the library, one flat folder.src/agent-*.jsandsrc/mcp*are the MCP tool surface.bin/crucible-mcp.mjsstarts the MCP server.packages/holds the addon packages.- FEATURES.md maps every page, MCP tool and command by the name the code uses.
node scripts/drive.mjs list|shot <id>|console <id>opens a page headless, so use it instead of a throwaway browser script. tests/holds the Node tests, one*.test.jsper area.scripts/holds the build, smoke and gate scripts.docs/holds one guide per feature.skills/holds the agent skills that ship with the package.changes/holds one changelog note per pull request.artifacts/is ignored output for screenshots and logs.
Set up
npm ci
Node 20.19 or later, Node 24 on CI. Chrome is needed for the smoke scripts and the MCP tests.
Before you open a pull request
Open the pull request with node scripts/open-pr.mjs --title ... --body-file ... [--labels ...] [--milestone ...] [--evidence <files>] (CONTRIBUTING.md). It runs the metadata checks locally, creates the PR with its labels and milestone, pushes evidence and verifies the stored description; --dry-run shows what it would do.
npm run preflight
It runs the gates of the Test workflow that apply to the files your branch changed: protected files, the change note, links,
tool schemas, size, tool cost, the build, the unit tests with coverage and the coverage gate. It keeps going after a failure,
writes each log to artifacts/preflight/, prints only the tail of a failing log and ends with one line per check and its fix.
--skip-tests skips the slow test pass while you iterate but still runs the unit tests recorded under half a second (scripts/fast-tests.mjs, about 430 files, 13 s; npm run record:fast-tests refreshes the list), and --json adds a machine-readable summary.
Run the full preflight once before you push. A green preflight covers the PR gates, the site build, size and tool cost; the test workflow also runs npm audit, the package job (prepare:release, check:links:package, check:published-site, smoke:package, smoke:mcp-package), the bun smoke and the COOK_DISABLE=1 leg, which only CI runs.
npm ci installs a pre-push hook that runs npm run preflight -- --skip-tests, which includes those fast tests, and stops a push that would fail those gates.
SKIP_PREFLIGHT=1 git push skips it once; use that only for a push you know the gates do not cover.
For one test file: node --test tests/<area>.test.js.
Between one file and the full pass, while you iterate (each prints at most about 20 lines for 10 failures and writes the full TAP to artifacts/test-logs/):
npm run test:affected -- src/foo.js: every test file that mentions the file, or a module that re-exports it. With no files it uses what your branch changed.npm run test:fast: a deterministic 10 percent of the test files, seeded by the branch name (-- --seed <text> --percent <n>).npm run test:mutation-check -- tests/foo.test.js: reverts yoursrc/,bin/,packages/andscripts/changes, runs the tests, lists the ones that fail and restores the tree. It exits 1 when every test still passes, which means the test does not pin your fix. Stage unstaged edits outside those folders first, andgit add -Nnew files under them.npm test -- --test-reporter=./scripts/test-compact-reporter.mjsgives the full pass the same short output.
Rules that fail a pull request
- Add
changes/<issue>.mdwith one bullet when you changesrc/,bin/,packages/orskills/(changes/README.md has the naming rule). - Name the branch
<issue>-<slug>and the pull request<imperative sentence> (#<issue>). PutCloses #NorPart of #Nin the description and paste the commands you ran with their results. - A bot fills the assignee, the milestone and the linked issue's
priority:*andgoal:*labels on pull requests and issues, so do not hand-edit them; still name the issue in the description. - Put the evidence in the pull request under Evidence: before and after pictures or clips for what can be seen, numbers from old to new for what can be measured, or one line that there is nothing to show. Push pictures to a branch named
evidence-pr-<number>and link the raw URLs (CONTRIBUTING.md). - A change to an MCP tool schema or a skill needs the Haiku bench table in the pull request (CONTRIBUTING.md).
- Look changes (shaders, lighting, materials, default render, post steps) carry
hold:look-approval. Never remove it and never merge: only the maintainer merges. - Never edit
CHANGELOG.md,bench/size/budgets.json,bench/size/baseline.jsonorbench/tool-cost-budgets.json. Maintainers reset them at release. - A bundle that grows past its allowance needs a line in
changes/<issue>.size.mdthat says why the bytes are worth it (bench/size/README.md). The same file accepts tool cost growth (bench/tool-cost/README.md). - Coverage may not drop. Write the tests in the same commit as the code.
- Never weaken or skip a test to make it pass. Find why it fails.
Code
- Descriptive full names, one statement per line, small functions, comments only for a reason the code does not show.
- No new runtime dependency in the core. Optional features go in an addon.
- Scene builders are deterministic for the same seed; tests compare geometry byte for byte.
- Validate input at the public boundary and throw an error that says what failed and what to pass instead. Agents read these errors.
- MCP tools accept no arbitrary code and no remote asset URLs (SECURITY.md). Keep every count and size bounded.
- Update the guide in
docs/for the feature you change.
Checks a person or a GPU runs
Shaders, lighting, skinning, glTF and the frame path need real pixels. npm run preflight names the ones that may apply to your
change; the table in CONTRIBUTING.md says when each one is needed. Say in the pull request which ones you
ran and what you saw. If you cannot run one, say that instead.
Working etiquette
- One change per pull request, on a branch from
main. Mergemaininto it only whengit merge-tree --write-tree origin/main HEADreports a conflict, ormainchanged a file your branch touches (commands in CONTRIBUTING.md).Testalso runs on every push tomain. - Stop only processes you started, by their PID. Other jobs may share the machine.
- Issues and pull requests are public. Keep local paths, tokens and personal data out of them.