Make a single-page interactive diagram: a physical isometric machine on a workbench, where each station corresponds to one step in a process. For example, a request card moves along the carriage frame, a probe descends, and a press stamps the card. A pure state model determines each action so that the visuals, values, and text stay consistent. templates provide a runnable starting point, and kit provides the geometry library.
When to use
- The concept is a process with stations, ordering, and failure modes, such as loops, pipelines, caches, queues, and retry policies.
- The reader can disable a part and observe the failure.
- The diagram is the main body of the page.
When to use something else
- A static diagram is enough to explain it, or the concept has no ordering or state changes: make a flat static SVG.
- A small figure in a course or README: use blueprint-figure.
- A deterministic behavior model cannot be written: find out the behavior first; do not animate guesses.
- More than 150 parts without user approval: confirm the scale first.
Method
-
Conceive the machine and write one sentence: "X moves through Y, and this motion represents Z." If you cannot write it clearly, change the machine; see references/concept.md.
-
Before drawing, count the parts against the checklist and choose the scale.
Scale Part count Confirmation Diagram 40 to 80 Not needed Main figure 80 to 150 Not needed Larger More than 150 Get user approval first -
First write a pure deterministic model.mjs, with no DOM and no clock. simulate(config) returns events and a summary. Test it before geometry; see references/state-model.md.
-
Map each concept to a station, and in the table write the station, the concept name on the nameplate, its role, and the failure when it is missing.
-
Write the parts list, including assembly group, world dimensions, color tone, and whether it moves, then write the geometry.
-
Set a single isometric camera: world units, 30-degree elevation, and an azimuth that turns the working face toward the reader. The projection must fit both the assembled and the extended poses.
-
Build static geometry only once: one SVG group per part with a depth key, and add data-live to moving parts; see references/geometry.md.
-
Translate parts via transform. Rebuild paths only when the shape changes (for example, an extending rod).
-
Draw back to front using the depth key plus the current offset depth. Reorder the DOM only when the order changes.
-
Use a single accent color to mark the active part and nameplate; use four levels of gray and four line weights for everything else.
-
Controls change a real simulate run; run, step, disable, repair, reset, and toggles all take effect, and the config is written to the URL. See references/live.md.
-
Verify in a real browser on desktop and mobile, in light and dark themes, and add 4x close-ups, line-end checks, and a scenario sweep and contact sheet with zero console errors. See references/verify.md.
Rules
Truthfulness:
- The state model is the only source of truth. Motion, readings, trajectories, and result text all come from events.
- The same configuration in simulate returns the same events, and tests cover all configuration combinations.
- Do not fake real models, services, or metrics. Scripted parts must be clearly marked as fixed scripts.
- When simulated time is present, the page must begin with "This is a simulation." and state that the time is a fixed cost, not measured.
- Use real arithmetic, and tests assert the exact values printed by the page.
Geometry:
- Coordinates use world units; pixels appear only in projection.
- Elevation is 30 degrees, with one fixed azimuth across the whole page; the reference page uses 60 degrees.
- Entities use four levels of shading and outlines; lines use hi, mid, lo, and faint.
- Line ends attach to an entity or another line. When intentionally left dangling, mark data-free=start, end, or empty.
- Each station has a conceptual nameplate, such as CACHE or VERIFIER, translated on Chinese pages.
- Parts placed on other parts get a depth offset and are drawn after their support.
Motion:
- Moving parts only change transform. Morph paths reuse cached results where possible.
- A single beat lasts 0.1 to 1.3 seconds; longer displacements take more time.
- The deploy spring has stiffness 64 and damping 14.2, and assembly groups are staggered by 0.04 seconds.
- The per-frame step is capped at 1/20 second, so slow frames do not skip beats.
- With reduced motion, run at 40x speed, and deployment jumps immediately to the final state.
- Stop the animation loop when the stage is offscreen or there is no motion.
Page:
- Desktop workbench shows in one screen: toolbar, stage, and readings are placed within 100svh.
- On mobile, stack vertically with no horizontal scrolling.
- Buttons are at least 44px high. The stage is focusable and supports run, step, deploy, disable, and repair keys.
- The SVG has role=img, and aria-label describes all stations.
- aria-live=polite announces the result when the run ends.
Pre-completion checks
- The page or build notes state a one-sentence machine description.
- The part count matches the confirmed scale.
- Model tests pass and cover all configurations.
- Rebuilding the page produces no diff.
- Each configuration control calls simulate and updates the URL.
- Query parameters restore the same configuration.
- At any moment there is only one accent color, following the active part.
- Nameplates are readable in both light and dark themes on mobile.
- Line-end check finds zero dangling endpoints.
- All configurations run to completion with zero console errors.
- Desktop and mobile light/dark screenshots have no clipping and no horizontal scrolling.
- The deployed pose stays within the stage.
- The page has a simulation note.
Files
- references/concept.md: concept, one-sentence check, concept mapping, scale.
- references/state-model.md: model contract, events, tests, URL state.
- references/geometry.md: units, camera, parts, utility functions, shading, depth, nameplates.
- references/live.md: beats, render loop, ordering, accent color, controls, accessibility, layout.
- references/verify.md: browser verification loop and scripts.
- templates/model.mjs, templates/model.test.mjs, templates/build.mjs, templates/live.js: a runnable cache machine. node templates/build.mjs generates templates/out.html, node --test templates/model.test.mjs runs the tests.
- kit/iso-kit.mjs, kit/lathe.mjs, kit/tube.mjs: projection, solids, solids of revolution, pipes, base CSS, retain kit/LICENSE.
In the repository, scripts/agent-machine/ and site/test_agent_machine.js provide the complete main diagram, containing 57 drawing items sorted by depth.