Full long-form guide for detailed rotatable Three.js dioramas. Narrative scenes are scene-first with no educational UI unless requested. Classic pixel, stroked-toon and pixel+stroke are rendering choi
1---2name: diorama3description: Full long-form guide for detailed rotatable Three.js dioramas. Narrative scenes are scene-first with no…4---56# SKILL.md
D
SKILL.mdAgent skill
Transport
File
Status
Listed
SKILL.md
Install
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
shterminal
1npx skills add sloemo01/diorama -a cursor -y
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
shterminal
1npx skills add sloemo01/diorama -aclaude-code -y
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
shterminal
1npx skills add sloemo01/diorama -acodex-y
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
shterminal
1npx skills add sloemo01/diorama -a grok -y
Send the copied message in a Grok Bot chat. The Bot fetches this SKILL.md from GitHub and adds it to the skills all your Bots share.
txtGrok Bot chat
1Install this skill: https://github.com/sloemo01/diorama
Full long-form guide for detailed rotatable Three.js dioramas. Narrative scenes are scene-first with no educational UI unless requested. Classic pixel, stroked-toon and pixel+stroke are rendering choices, not educational modes. Explanatory commissions use the separate educational contract. Includes composition, cast, animation, craft, sourcing and construction.
FAQ
Questions
Updated
2026-11-08
Stars
352
Agents
3
Categories
—
How do I install diorama?
Download SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does diorama live?
The publisher keeps it at https://github.com/sloemo01/diorama.
Which agents can use diorama?
Claude, Cursor, Codex, and Grok Build can read a SKILL.md you add from the publisher's repository. Grok Bot installs it when you send the skill's GitHub folder link in a chat.
From the publisher
SKILL.md
name
diorama
description
Full long-form guide for detailed rotatable Three.js dioramas. Narrative scenes are scene-first with no educational UI unless requested. Classic pixel, stroked-toon and pixel+stroke are rendering choices, not educational modes. Explanatory commissions use the separate educational contract. Includes composition, cast, animation, craft, sourcing and construction.
version
5.7.0
author
Nehal Kanak (sloemo)
license
MIT
platforms
[linux, macos, windows]
Diorama
Current intake contract (5.7.0 — authoritative)
For a new commission, ask look first, model sourcing second, using the two gates below. These gates override older three-preset lists, automatic internet-first instructions and one-prompt assumptions elsewhere in this long guide and its references. Do not ask setup questions when merely editing the skill. Explicit answers in the brief skip the corresponding question; existing-project repairs retain recorded choices. An unanswered question is pending, not consent. Rendering and sourcing are independent of narrative/educational purpose.
Three looks are available: pixel (Classic Pixel Art; recommended), stroked-toon, pixel-stroke. Generic “pixel art”, “classic”, “old pixel style” and explicit delegation (“you choose”) resolve to pixel. All looks preserve free orbit. An unanswered style gate waits.
Three sourcing modes are available: internet-full, hybrid (recommended), authored-only. Generic “use internet models” resolves to hybrid unless the user requests downloaded models throughout. Older internet-first records map to hybrid on repairs. Sourcing requirements below apply only to modes that acquire external assets; authored-only skips model acquisition, not subject research, quality or geometry/contact checks.
Profile boundary and retained additions (5.0 — read first)
This is the restored full-length guide, not the compact 4.x replacement. Keep its detailed composition, subject recipes, scene furniture, cast, animation, service/queue, vehicle, effects, framing and craft guidance. The following profile/sourcing updates override older wording only where explicitly stated.
Scene purpose is independent of rendering
Default sceneProfile: narrative. A place, landscape, amusement park, town, fantasy scene or interactive scene is not an educational mechanism. Pixel, stroked-toon and pixel+stroke choose the renderer, NOT the profile. Asset choice, a working ride or click interactions do not make a scene educational. Choose educational when the user asks to explain/teach how something works, its anatomy or causal sequence. If intent is genuinely mixed, ask once; otherwise infer and record it without another forced setup question.
Narrative has no educational UI by default. Do not import or instantiate , , an Explore/How it works panel, lesson steps, part picker, explanatory dashboard, floating callout labels or scattered teaching text for an ordinary diorama. This exclusion applies in ALL three render presets. Leave the scene/page visually clean. Free orbit and discreet functional pause/reset/accessibility controls remain permitted; diegetic park signs and shop names are scene geometry, not a teaching overlay. Optional title/readout furniture mentioned later is opt-in, not a toon/hybrid default. No debug panel in delivery.
education-v8.css
education-dock.mjs
Educational only: canonical V8 right card/mobile dock, causal lessons, part inspection and connected explanatory callouts apply to explanatory commissions, not to all scenes. Explicit UI-free requests still override the panel default: explanation can be delivered through the requested scene behavior and accompanying prose. Narrative scenes with explicitly requested ride/part inspection get the requested scoped interaction, not an automatic lesson dashboard. Explicit requested informational labels are allowed, but do not add unrelated teaching surfaces. Record uiMode: none | minimal-controls | requested-inspection | educational and why; never satisfy a UI test by adding unwanted UI.
Regression examples: “amusement park in pixel + stroked toon” → narrative + pixel-stroke + no education UI. “Interactive amusement park” → narrative; interaction alone adds no lessons. “Explain a roller coaster's operation” → educational, chosen style independently. “Amusement park with inspectable rides” → narrative + requested inspection only. A scene with no educational intent must not fail QA for lacking V8, lessons, labels or a card column.
Default occupied-space pass: actions, seating and scenery
Prevent intersections before adding detail or spawning copies, for people, animals, imported rigs, buildings, props and rides in BOTH profiles/all presets. Use references/action-clearance.md, templates/action-clearance.mjs and templates/pose-bounds.mjs with the actual production evaluator; this adds no educational UI.
Reserve full space, not origins: building/awning/door parcels, open access paths, actor swept widths and reach, tails/wings/horns, carried items and neighbouring actors. Reuse fitted rigs/clips from internet assets, but reject an asset/clip that cannot fit the required seat/action without distortion. Split accessible structures into actual wall/door/roof pieces; an enclosing hollow-building AABB is only a broad-phase candidate, not solid occupancy. Use deterministic lanes, queue slots, crossing priorities and seat reservations, not random nudges after overlap.
Solve real contact/action frames: approach → align → bend/lower → supported sit → stand/exit; pelvis, knees, feet and hands follow real seat/ground/handle frames. Don't sit by dropping a standing model through the chair. Ride occupants inherit the seat's moving frame once. Permit only exact named intended body↔support/joint contacts, with action window and bounded depth; never exempt an entire actor, chair, species or same-owner subtree. Check support gaps separately—an allowed collision contact does not prove the person isn't floating.
Check the live pose across the whole action: refresh skeleton/morph vertices and world frames, then use measured conservative body-region capsules/boxes plus structural pieces. Bind-pose bounds/root-point distances miss moving limbs; undersized colliders and omitted tails/carry props are failures. Broad-screen nearby pairs; refine loose bounds instead of deleting objects to lower candidate counts. Production audits supply independently specified requiredIds; missing actors/proxies or unverified coverage cannot pass. Test nonadjacent self-parts too, while explicitly declaring valid anatomical/structural joints. Proxy overlap is not automatically actual mesh penetration.
Test critical times and fixes: sample full cycles, loop seam, approach/contact/departure, largest reach, sitting/standing, crossings and door swing. Include exact events and refine using relative tip motion/clearance, not only endpoints or an attractive frame. sampledOnly:true is bounded sampled evidence, not continuous collision freedom. Move a real wrist/tail/knee into an obstacle, overlap building parcels and synchronize a crossing; the SAME production predicate must flag the fault and pass after repair. Review worst-contact side/back/top crops plus an action strip. Never hide bodies, shrink proxies, fade through walls or freeze the requested action to claim a pass. One source-driven QA runner, cached static obstacles, nearby-pair broad phase and worst-few reporting keep this practical.
Default asset workflow: search, acquire and USE fitting models
Ask the Model Sourcing Gate after the look is resolved, for BOTH profiles. Follow the recorded internet-full, hybrid or authored-only choice; do not silently impose internet-first. In the first two modes, reuse valid local assets but still search for missing major roles. The acquisition requirements in this section apply to those two modes; authored-only intentionally builds geometry and does not need a failed model search to justify it.
A search is not the deliverable. Before detailed hand-modelling, find candidates for the hero and major supporting roles, review the actual per-asset terms and appearance, download the chosen permitted model/dependencies, inspect an actual import, and USE it in the scene when it fits. A fitting, licensed asset must not be ignored in favour of primitive-only reconstruction merely because hand-building is familiar. Nor does importing one token tree satisfy sourcing a park's otherwise hand-built rides/buildings/cast. Record decisions for the main roles in the existing SOURCES/CREDITS/design ledger.
Fit means diorama-quality, not merely downloadable: correct subject/representation and silhouette, coherent kit/palette/proportions, adequate construction detail, usable parts/rig/clips for the requested motion or inspection, viable triangle/draw-call/texture budget, and compatibility with the chosen pixel/toon/hybrid rendering. Judge the real model from more than a thumbnail. Normalize scale/axes/origin, adapt colours/materials without losing important markings, preserve rigs/part identity, fit to the scene and review a rendered close-up. A realistic/PBR asset is not automatically disallowed if it can be adapted well; an unrelated low-poly substitute is not automatically suitable. Follow the original long-form craft, composition and motion standards after importing.
Rights remain mandatory: prefer FREE assets whose explicit terms permit commercial use, modifications and redistribution/embedding in the delivered scene. Read original asset/license evidence; retain credits/license/change notices where required. NC, ND, editorial, personal/educational-only and missing rights do not pass. Custom/ShareAlike/other terms require compatibility review, not a fake CC0 label. No purchases, subscriptions or paid downloads without explicit user approval. Check separately licensed dependencies. Commercial permission is not scientific accuracy or trademark/other-rights clearance.
Source order: use the user's Polyfork-first sweep for narrative kits/props, then the relevant original-author/model-library sources in this guide; if Polyfork misses, continue to appropriate alternatives rather than declare that the internet has none. Educational subjects use their bounded exact-subject search and extra accuracy/structure gate. Reuse a compatible kit for coherence. Do not crawl every provider indiscriminately or repeatedly search the same noun. Actual search/download/import evidence stays on disk; never fabricate searches, licenses or successful loads.
Hand-model only the justified gap: necessary missing/custom geometry, unsuitable candidates after source/fit checks, or interfaces/animation adaptations not supplied by an imported model. Selection or movement alone is NOT a reason to reject an asset: use real part/pivot wrappers where feasible. Retain an all-authored approach when the user explicitly asks for it. If browsing/downloads are unavailable, disclose the limitation and fallback; never say the search found nothing when it never ran. A quality mismatch, unclear license or lack of useful motion is a documented reason to reject, not a reason to force a bad download.
Proof before completion: for each major role record search/source, chosen asset or rejection/fallback reason, license evidence, actual downloaded file/path/hash and import/style/motion result. A compliant matching candidate found → acquired and used; no suitable candidate → honest specific fallback. Verify the chosen asset actually exists in the final scene, not just in assets/. Offline/standalone delivery packages every permitted dependency and is tested without network; a warm cache or CDN loader is not self-contained. Sourcing adds NO education panels, callouts or other UI to narrative scenes.
Preserve the approved 4.x additions without shortening this guide
Representation: actual subject by default, not a classroom surrogate. Follow references/representation.md: Earth means a planet, not a globe on a stand. Ask real subject / physical teaching model / explanatory abstraction / you choose only if materially ambiguous; preserve explicit choices. Keep representation, render preset, purpose, scene/object context and Inside independent. Natural subjects do not acquire invented platforms, frames or machinery merely because this guide contains mechanical examples.
Narrative sourcing: preserve the user's Polyfork-first catalogue sweep, kits/matching, source decisions and scale/palette integration in references/external-models.md. This extends the older model-library section; do not fall back to primitive-only scenery without checking suitable assets.
Educational sourcing: the named teaching object/parts may be verified external geometry. Use the bounded candidate search and accuracy/import wrapper in references/educational-models.md, not a narrative full-catalogue crawl. Add authored semantic IDs, interfaces, pivots and explanation where needed.
Rights: all downloaded assets must permit commercial use, modification and redistribution in the delivered scene. Free download is not permission. Use templates/educational-asset-gate.mjs with reviewed evidence/credits and actual file hashes; CC0/CC-BY can pass, unknown/custom terms require review, NC/ND/editorial/incompatible terms do not pass. Verify dependencies and offline bundling; a remote CDN load is not an offline standalone artifact. This rights gate overrides older library summaries, including casually accepted restrictive licenses.
Construction: retain templates/construction-kit.js and templates/interface-checks.js; reserve working pockets, derive contact stacks from shared datums, check actual geometry and repeats. Keep the original detailed construction/selection chapters. Material/selection/annotation checks apply only to implemented/requested features; no forced annotation system to satisfy QA. AABB overlap is a candidate, not certified penetration. Use scoped real mutations, not bespoke injected-object detectors. Available helpers are supplemental, not proof of a whole scene.
Maintenance: do not mutate the installed skill after each scene automatically. An explicit maintenance request and filesystem approval are required. Preserve original/current backups. Historical changelogs document prior versions; they do not override this release.
A diorama is a tiny staged scene with a resettable three-quarter hero camera and
free user orbit. The default pixel preset uses a white cut-out, palette-snapped
pixel grid and ink contour; the other presets follow their own presentation
contracts. Narrative scenes retain the slab and toy-scale animated cast;
educational scenes use the exception below.
Classic Pixel Art is the recommended new-project look. Stroked toon / illustrated miniature
(stroked-toon) and the pixel + stroke hybrid (pixel-stroke) are optional
rendering presets for any subject, not a coffee-machine genre. Ask which of the
three to build in at the start of every project — see Render Preset Gate —
because the look changes presentation only, never the subject, story, research
requirements, choreography or construction standard, and nobody should have it
chosen silently on their behalf.
Profile precedence (read first): For an educational explanation, read
Educational Mechanism Profile before the narrative defaults. One mechanism and
one causal sequence replace ALL mandatory cast/ritual/multiple-system/story-prop
quotas throughout this guide. Clean off-white and the single V8 right card/mobile dock replace empty
paper or decorative figure UI (explicit placement requests remain supported). Construction and mechanical correctness are never
waived. For EVERY preset, free user orbit is mandatory; fixed/hero views below
refer to deterministic QA/reset poses, not a locked interaction camera.
This file restores the full guide. The supplemental references named in the 5.0 additions carry later approved sourcing/representation rules; copy-in modules and the detailed design sheet remain in templates/.
Execution index — do not read every genre recipe first. Resolve the preset
and profile, then use the fast-path table. Read Research Before You Model and
The Detail Bar (including whole-object completeness) for every build. Narrative
builds additionally use One Prompt, One Build, The Animation Bar and their
chosen rendering recipe; educational builds go directly to the canonical UI/
inspection and construction contracts. The Look Contract is pixel-only.
Construction regression gates: every instance, actual axes/bores and end-plane separation; not one good sample
Requested selection
Canonical educational UI and inspection contract: reuse selection behavior only as requested; no narrative education card/lessons/labels. Verify visible emphasis, keyboard equivalent and exact restoration
Claimed pass
Verification: nonempty actual geometry, expected counts, negative injections and fresh build hash tied to the report
This table indexes existing acceptance rules; detailed tests live only in the
sections named here. Read other subject recipes only when the build uses them.
Render Preset Gate (ask once, every project)
Before the first mesh or presentation work, ask using the structured-choice tool when available. Keep labels and one-sentence consequences visible:
Which look should I build this in?
Classic Pixel Art (Recommended) — The original finer palette-snapped miniature look with ink contours and ordered dither.
Stroked Toon / Illustrated Miniature — Smooth bevelled parts, stepped shading and fine charcoal outlines.
Pixel + Stroke — Toon shading and outlines on a low-resolution pixel grid.
Map answers respectively to pixel, stroked-toon, pixel-stroke. Generic “pixel art”, explicit classic and explicit delegation select pixel; silence waits. A reference image alone does not settle a materially ambiguous request. Do not repeat the question per material or repair. Record the answer verbatim in DESIGN, including the preset ID and renderer implementation. Every preset supports free orbit and deterministic hero reset; no second orbit question. After the look answer, ask the sourcing question next unless already answered. While either is pending, inspect local files and research the subject, but do not start detailed geometry, model downloads or a presentation implementation that commits the unanswered choice.
Model Sourcing Gate (ask next, once per project)
How should I create the models?
Hybrid — source + custom-build (Recommended) — Search for commercially usable models, download and use the ones that fit, then model missing or scene-specific pieces myself.
Internet models throughout — Search for and use commercially usable downloaded models for all major roles; focus my work on assembly, styling, rigging and animation.
Fully agent-modeled — Build all scene geometry myself for a unified custom look, without downloading third-party models.
This is a separate question after style, not a hidden assumption or a confused “pixel hybrid” choice. Use stable question ID asset-strategy, single-select, and map answers to hybrid, internet-full, authored-only. Record exact user wording. Explicit delegation selects hybrid; silence waits. Explicit requests for original/procedural geometry answer authored-only; an offline deliverable alone does NOT mean authored-only (permitted assets can be packaged locally).
Hybrid: actually search for every missing major role and use fitting licensed candidates; fill documented gaps with authored geometry. A token imported prop does not satisfy sourcing the hero/cast/buildings. Do not search and then hand-build suitable assets out of habit.
Internet models throughout: source the hero and all major supporting roles. Scale/material changes, pivots, adapters, collision proxies and simple joining/support geometry are allowed; quietly hand-building a missing hero is not. If no fitting licensed major asset exists, report the specific gap and offer a subject substitute or permission to switch that role to hybrid. Do not guarantee a full matching library before searching, and do not force an unsuitable model just to fill a quota.
Fully agent-modeled: author all visible model geometry, including hero and supporting roles. Subject/photo/motion references and coding/rendering libraries remain allowed; this choice does not mean “no internet research”. Do not download model packs, use an imported model as a hidden starting point, or downgrade the detail/animation/contact bar. User-provided models require an explicit exception if this mode is selected.
Commercially usable, not merely commercially available: in BOTH internet modes verify the actual per-asset license permits commercial use, modification and redistribution/embedding in the delivered scene. Prefer free CC0/compatible CC-BY; preserve required credits, modifications and license notices, check dependencies and package offline. Unknown rights, NC, ND, editorial/personal-only and incompatible licenses fail. Availability for sale is not a rights check. No purchases or subscriptions without separate explicit approval. Explain this briefly with the question; do not overwhelm it with legal boilerplate.
Honest exceptions: unavailable search/download access is not “nothing suitable found”. Disclose the limitation and ask before changing a selected sourcing mode. New choices do not waive subject accuracy or mandatory verification and add no educational UI.
Pre-build decision receipt: after both answers, state one short line such as “Classic Pixel Art · hybrid sourcing · narrative · minimal controls”, then record the choices in DESIGN. Before delivery reconcile each major role against its chosen source mode and record native render dimensions, scaling and style crops. Missing answers, unsupported render-preset claims or unapproved sourcing switches cannot pass QA.
Fast path by scene
If the commission is...
Read next, in this order
explicit explanation / guided how-it-works (not a machine or cutaway view alone)
The narrative shape is place + repeated ritual + interruption + consequence.
Educational scenes instead use mechanism + causal sequence + observable result;
do not add a fictional interruption or cast. The fast path selects the relevant
reference notes, not extra narrative requirements.
When to Use
Educational "how does this work?" mechanisms, cutaways and step-through
causal explanations; use the Educational Mechanism Profile, not cast quotas.
"Make a small diorama / miniature scene / pixel scene of X"
A clip or still shows a flat cut-out scene with chunky pixels and little
people, and the ask is to match that look
An existing 3D scene needs the pixel-art presentation (palette, dither, ink,
reset hero angle plus orbit) rather than a smooth render
The figures need believable motion: walking, climbing into a car, sitting,
swimming, diving, and it has to survive close inspection
The ask is for a staged diorama, not a model: several systems, a cast, a goal or boss,
and a loop that can be frozen at any second
The user gives only one line ("a bakery at closing", "a lighthouse under
siege"); this skill is designed to turn that into a complete commission
without an interview
Don't use for photoreal scenes or full-resolution photographic product renders.
Every scene MUST support free user orbit by default, including pixel, stroked-toon and pixel-stroke. No separate orbit consent exists. Keep a deterministic hero angle for QA/reset, never auto-spin.
Research Before You Model
Four lookups come before the first mesh: the subject by frames, the asset
libraries, the motion itself, and the capture loop. Skipping them is how a build
ends up with a plausible silhouette that matches nothing and animation that reads
as generic. Budget for them, they are usually faster than the modelling they save.
Question the research answers
Where it lands
what does it look like, exactly
refs/<subject>/*.png contact sheets
what does it do, in what order, how fast
refs/SOURCES.md + the beat table
does a rig or clip already exist
CREDITS.md + assets/
is it actually right on screen
qa/ captures, compared to the sheets
1. The subject, by frames
Find the real thing moving, not stills. For games, anime, sport or machinery the
footage is the specification: it settles what the shape is, where the motion
starts, how long each stage lasts and what colour it is at each step.
Read the contact sheets with vision, then write the grammar down in words before
touching geometry: ball leaves the hand on an arc, opens with a white burst, the
creature springs out at full size, the ball snaps shut and returns. A paragraph
like that is the acceptance test for the effect you are about to build.
Rules that come out of doing this repeatedly:
Prefer game footage over fan animation for game subjects; the game is the
canonical grammar, and fan cuts are already an interpretation.
Prefer one clean clip sampled densely over ten clips sampled sparsely.
Twelve frames a second on a 4 second send-out shows the whole sequence.
Keep the sheets in refs/<subject>/ next to the build so the next person can
see what you were matching, and so QA has an image to compare against.
2. Model sourcing: check the libraries before you build
Internet-first sourcing applies to ALL major scene roles, not only creatures. Acquire and use fitting commercially licensed models by default; hand-build only a documented gap or explicit original-geometry request. Hand-building a creature from primitives is the last option, not the first. A
rigged download with real deformation and usable clips beats four hundred lines
of spheres the moment the camera comes within a metre. Search first, and keep a
record of what you searched.
The ladder. Every hero asset walks down it in order.
Already on disk. The user's folder often ships a tools/, assets/ or
model/ directory with GLBs in it. List it before anything else.
A CC0 pack covers it. Import it. No attribution, no negotiation.
A CC-BY model covers it and the page can carry a credit line. Import it,
credit it, done.
Nothing fits the silhouette and the shape has to be exact. Hand-build it
against the reference frames, and say in the log that you searched.
Never: ripped game assets, Models Resource / Spriters Resource downloads
used as geometry, "editorial use only", NC, ND, or anything with no stated
licence. Those are hard stops; ask the user instead of guessing.
a maintained list of CC0 sources when the usual four fail
Searching them without a browser. Three of the libraries have open APIs, so a
build can check them in a single command and read the licence back:
# Sketchfab: downloadable + CC0 only, name and page printed for each hit
curl -s "https://api.sketchfab.com/v3/search?type=models&downloadable=true&license=cc0&q=dragon&count=24" \
| python3 -c "import json,sys;[print(r['name'],'|','https://sketchfab.com/models/'+r['uid']) for r in json.load(sys.stdin)['results']]"
# Poly Haven: models, HDRIs, textures (filter by category)
curl -s "https://api.polyhaven.com/assets?t=models"
curl -s "https://api.polyhaven.com/assets?t=hdris&c=studio"
# ambientCG: materials and HDRIs by keyword
curl -s "https://ambientcg.com/api/v2/full_json?type=Material&limit=20&q=concrete" \
| python3 -c "import json,sys;print([a['assetId'] for a in json.load(sys.stdin)['foundAssets']])"
Poly Pizza, Quaternius, KayKit and Kenney are browsed by search on their own
pages; query them with the noun plus the style (low poly dragon, kaykit skeleton), not with a sentence.
Reference only, never geometry: The Spriters Resource, The Models Resource,
sakugabooru, game rip archives, Pinterest. Use them to learn the shape and the
timing, then build or buy the actual asset.
3. Animation research: how the thing moves
Shape is half the job; the other half is the motion, and it is researched the same
way. Search the verb, not the noun.
# the motion itself, canonical first
web_search: "<subject> <move> animation" # a game doing it
web_search: "<subject> <move> slow motion" # real footage, for weight
web_search: "<subject> sprite sheet" # frame-by-frame timing
yt-dlp "ytsearch6:<subject> <move> animation"
ffmpeg -i clip.mp4 -vf "fps=12,scale=320:-1,tile=6x4" refs/move-%02d.png
Read the sheet, then count frames and convert: seconds = frames / fps, and
scale to the loop length you are building. That is how a 0.42 s anticipation and a
0.18 s contact become the beat table instead of a guess.
Write four lines per action before animating it:
wind-up 0.00 -> 0.42 weight back, head down, tail still
contact 0.42 -> 0.55 fastest frames, one pose held for two frames
follow 0.55 -> 0.90 overshoot, then settle
recover 0.90 -> 1.30 back to idle
Every attack in the beat sheet needs all four. Missing anticipation is why an
effect reads as "it just happens", and missing follow-through is why it reads as
"it snaps back".
For rigs, cross-check the reference against a real clip: if the library has a
punch, a swipe or a jump that is close, retarget it and offset the acting, rather
than keying a pose from scratch.
4. The research log
Every build writes refs/SOURCES.md. It is the proof the searches happened and
the reason the next person does not repeat them.
| Question | Searched | Found | Decision |
| --- | --- | --- | --- |
| what does the send-out look like | yt: "sword shield send out slow motion" | RoUJ_TWvB3g, orb + white burst | matched, timings below |
| hero creature rig | poly.pizza "dragon", quaternius characters | nothing matching the silhouette | hand-built from refs/sendout |
| hit reaction weight | yt: "pokemon take damage animation" | 0.9 s flinch, 1.7 s stagger | HURTS table |
A build with no SOURCES.md has not finished its research step, even if the
scene looks right.
5. Prove it with shots
Every beat gets frozen, captured and compared against the reference sheet before
the next beat is built. The contact sheet of those captures is the review
artifact, not a paragraph describing them.
Freeze the loop at the beats the reference showed: ?t=<second> in the page,
freeze(t) through the debug hook, screenshot the frame element.
Put the captures in a grid next to the reference frames and read them with
vision. Anything that needs a caption to explain is not finished.
Keep numerical checks alongside the pictures: facing dot products, NaN scans
over every geometry, console errors, effect bounding boxes. They catch the
failures the eye forgives at 300 px.
One Prompt, One Build
When the user gives a subject in one line, treat it as a commission, not a
questionnaire. Make the creative decisions, state them in one short assumption
line, and build the whole diorama. Do not stop at a plan, a blockout or a design
sheet and wait for approval.
The only reasons to ask are credentials, a destructive action, a path that
would overwrite the user's work, or the Render Preset Gate. That gate is a
deliberate exception to autonomous assumptions: one question, once per project,
before the first mesh. Everything else is a default.
Step 0, before the assumption line
Ask the Render Preset Gate question first, then run the three lookups in
Research Before You Model:
Step the real subject into frames and write down its motion grammar.
Walk the sourcing ladder for every hero asset (disk, CC0, CC-BY, hand-build),
with a CREDITS.md line per import and the search in refs/SOURCES.md.
Stand up the capture loop (qa/shoot.mjs, a frozen ?t= frame, a contact
sheet) so every beat can be reviewed as a picture.
For an invented subject, spend the same time on reference density instead: find
three images that agree on what the place looks like, list the props they share,
and build those before any invented detail.
The default commission
Use these unless the prompt explicitly says otherwise:
Knob
Default
Slab
21 x 14 x 0.42 m; 16 x 12 for one room, 24 x 16 for a street, port or launch pad
Loop
46 s at 40 Hz; one readable cycle plus a quiet seam
Palette
64 entries
Systems
4 defences/machines/service stations/attractions; 3 is acceptable, 6 is the ceiling
Cast
4 to 6 roles total, including one disruption; 2 ambient loops
3 systems, 3 roles + 1 disruption, 1 hero prop + 1 landmark, 30 s loop; still passes the bars
State the assumption in one line before coding:
Assumption: market archetype, 46 s loop, 4 service systems, 6 roles plus a
late customer, 21 x 14 slab, 64 colours. Say if you want a different scale or
genre.
That line is the contract. State it, then continue in the same turn; do not wait
for approval. It gives the user a chance to redirect after seeing the assumption,
without blocking the build.
Long builds and context
A scene like this runs for hours of agent time and thousands of messages: render
loops, one screenshot per beat, one probe per bug. The session will need to
compress its context, more than once, and compaction is lossy. Build so that a
compact does not cost you the work:
State lives in files, not in the chat.DESIGN.md, refs/SOURCES.md,
CREDITS.md, qa/report.json and the beat table in stage.js must carry every
decision. If a fact only exists in a message, it is already gone.
Write the rule down when you learn it. A fix found at 3 a.m. is worthless if
it only exists in the transcript; put it in the skill or a comment next to the
code, with the reason.
Name the shots.qa/frames/<entity>/sheet.png and shots/t-12.40.png are
stable handles a post-compact agent can re-read without rerunning anything.
Re-derive, do not remember. After a compact, re-run frames.mjs and
shoot.mjs rather than trusting your summary of what the last frame looked
like: the numbers are cheap, and a confident memory of an old build is the
most expensive thing in the session.
Keep one open task list in the repo (a TODO.md or an issue) so the thread
that survives compaction is the plan, not the chat.
Reading the prompt
Prompt shape
What to do
one noun ("a bakery")
pick the closest router row; invent the verb, disruption and goal
one sentence ("a lighthouse under siege")
take its nouns and verbs literally; fill the missing cast/systems from the router
a reference image
match its composition, camera side and palette first; keep this skill's detail/animation bars
"like X but Y"
reuse X's structure, replace the subject and the detail anchors; do not copy X's nouns
"make it detailed"
use the full Detail Bar and five animation layers; do not add more systems
"keep it simple"
cut systems and cast, not detail per hero; two rich objects beat six blockouts
A prompt that names only a place is still a commission. Decide what the place
does, who arrives, and what goes wrong. State the assumption and build.
The scene router
Pick the closest row. Do not invent a new genre from scratch unless none fit.
If the prompt is...
Systems (3–5)
Cast
Goal / disruption
Detail anchor
defence, siege, castle, base, zombies
4 towers + gate guns
defenders, 4 species, boss
boss reaches the gate
gatehouse
heist, bank, museum, casino
drill, lasers, cameras, getaway
3 crew, guards, manager
vault opens / escape
vault door
market, kitchen, bakery, cafe, food truck, night market
If none fit, use the universal shape: **place + repeated ritual + interruption
consequence**. Give it 3 to 5 systems, 4 roles and one goal. A quiet subject
still needs a verb: a library needs a closing, a bakery needs a service, a
lighthouse needs a sweep that fails.
If the router misses
Do not freeze. Answer four questions about the noun:
What does this place produce or repeat? Bread, light, trains, fish, money,
quiet, laundry, coffees.
Who operates it? Baker, keeper, guard, diver, clerk, mechanic.
What interrupts the output? A critic, a storm, a thief, a shutdown, a
delivery, a leak, a closing-time crowd.
What is the visible consequence? Burnt batch, dark lens, missed train,
flooded tank, empty till, closed sign.
Those four answers give you the system, cast, goal and residue. Then use the
five beats: normal output → first interruption → escalation → goal contact →
residue and seam. No combat required. A deadline, an inspection, a storm or a
closing bell is a valid boss.
Worked one-prompt example:
"a tiny bakery at closing time"
Archetype: market/kitchen. Slab 16 x 12. Loop 42 s.
Systems: oven, proofing rack, counter, till. Cast: baker, apprentice, last
customer, food inspector (the disruption).
Goal: the inspector reaches the counter before the last loaf is sold.
Beats: 0 s oven glow and bread out; 8 s first customer; 16 s inspector at the
door; 26 s last loaf contested; 34 s sign turns, flour settles, cat sleeps.
No towers: use machine grammar for the oven and till; field audit for the
oven's heat; death/exit for the inspector's departure.
The autonomous pass
Interpret. Pick the archetype; write the assumption line; fill
DESIGN.md yourself. Do not ask the user to fill it.
Blockout. Grey slab, camera, five beats at 1:1. No palette, no post, no
materials. If the beats do not read, restage before adding detail.
Presentation. Palette, light, post, ink, dither, camera solve.
Set and props. Landmark, two hero props, supporting dressing. Clear the
2 m threshold. No duplicate silhouettes.
Cast and detail. Rig the cast; apply the Detail Bar to every hero object.
Cut a role before cutting detail per role.
Animation and systems. Five layers per hero; tower acquire/fire/impact/
recovery; field ramp/area/affect/decay; machine input/motion/output/residue.
Effects and residue. Contact shadows, species deaths, dropped gear,
stains, ambient loops, loop seam.
QA and package. Detail/animation audit, numbers, 1:1 crops, standalone
file://, README and DESIGN.md agreeing.
If time is tight, cut the number of systems or actors, never the detail per
hero or the animation layers. Two detailed towers with five layers beat six
blockout towers with one fire animation.
Efficiency rules
One project, one build loop. Scaffold once, then build, shoot and fix in
place. Do not rewrite the entry file for a detail that lives in a prop module.
Build for orbit inspection. Prioritise the hero view, but construct every exposed back, support, cavity and joint coherently.
Cut systems before detail. A tight build with two rich towers and five
animation layers reads better than six thin towers with one recoil.
Use the templates. Camera, post, palette, lighting, the cast rig and the
detail helpers are already solved; do not re-derive them from prose.
Shoot known timestamps. Freeze at the five beat times and the five QA
frames; do not scrub for a good frame.
Package last, once. Build the standalone only after the QA frames pass;
rebuilding it after every tweak wastes the pass.
One-prompt acceptance
Do not report "done" until all of these are true:
DESIGN.md exists and matches the build.
Five beats have timestamps and proof frames.
Every system has events; every actor has a death, exit or residue.
Each hero has three detail passes and at least one story detail.
Each hero actor has idle, locomotion, action, reaction and death/exit.
Every carry, handoff, load and mount has a contact timestamp and a nine-frame
strip; palms are on the prop and boots are on the vehicle.
A queue serves after arrival, never before; no standing gesture is blended
into a walking root.
No generic sphere burst, floating prop, clipped landmark or beam on a target
that has already expired.
No fixed deck prop, ammo store, tool or crew member moves with a turret,
flywheel or machine pivot.
Standalone opens over file:// with zero console errors.
The final message gives the path, loop length, system/shot counts and the QA
frames, not a request for feedback.
Starting A New Diorama
When the subject is new, the first deliverable is a design sheet, not a scene.
With a one-line prompt, fill it from the defaults in One Prompt, One Build and
do not ask the user to complete it.
Copy templates/DESIGN.md into the project as DESIGN.md.
Write the premise as a verb, not a noun. Name the place, the repeated action,
who interrupts it, and the payoff.
Fill the cast and system sheets. If a role has no action, cut it. If a system
has no visible consequence, cut it.
Pick five beats and five QA timestamps. A beat without a timestamp is not
staged.
Block out in grey at the reset hero camera and shoot the five beats at 1:1.
This is a staging check, not a production pass: no palette, no post, no
materials. Redesign staging before committing to it.
Once the blockout reads, run the production pipeline below. Palette is the
first production pass; the grey blockout does not count as one. Detail
multiplies a readable blockout; it cannot rescue an unreadable one.
The rest of this file is the recipe for each pass.
UI and inspection authority:Canonical educational UI and inspection contract
below owns placement, controls, lessons, selection, focus and restoration. Follow
it rather than inferring defaults from older screenshots. The render preset gate
and free orbit apply unchanged.
Choose sceneProfile: educational for explicit explanations, guided technical cutaways and how-it-works teaching requests—not a machine subject, rotation or a cutaway view alone. This profile takes precedence over ALL narrative quotas below: no mandatory cast, disruption, ritual, landmark, three systems, ambient loops, five actor layers or decorative story props. One accurately constructed mechanism and one clear causal sequence is sufficient. Do not invent a crowd or combat to satisfy the router. Research and construction accuracy remain mandatory; simple UI never means missing mechanical parts.
UI, selection and lessons: when enabled/requested, use the canonical contract below; explicit UI-free briefs omit panels/lesson controls. No second toolbar, competing material cache or explanatory clock.
Component manifest is a hard delivery artifact: record each essential part's ID, assembly/parent, function, supporting joint/bearing/fastener, input/output connection, motion law, units, source and tolerance, mesh/group mapping, selectable anchor and proof frame. Include otherwise obscured shafts, cams, rods, links, valve gear, ports, supports and housings when functionally relevant. Explicitly state omissions and symbolic simplifications before acceptance; never substitute a label for missing construction.
Mechanics are coupled, not independently looped: derive all driven transforms from a shared phase/driver. Write and test actual ratios, directions, phase offsets, link lengths, kinematic equations, contact/clearance and event timing. For an engine, for example, verify crank:cam 2:1 over a 720° four-stroke cycle, connecting-rod length and piston stroke, valve lift/seat contact and opening order; do not copy these ratios into unrelated mechanisms. Check contacts across motion, not only at the hero frame.
Nothing passes through another solid: this is a hard acceptance rule for EVERY profile and preset, including educational scenes. Test non-contact pairs over the complete motion range and at contact transitions, not just one still. Declare intended joints/contact surfaces and numeric tolerances; all other swept bodies must keep positive clearance. Include complete geometry (tips, tails, bevels, fasteners and attachment arms), not only centres/anchors. In an engine, test actual piston-crown/valve-head/spark-plug bounds and actual cam/follower surfaces at dense phase samples. Do not move independent parts with unrelated sine waves, hide a collision with a cutaway, turn off depth testing, or use transparency/labels to pretend it is fixed. First solve the constraint or alter the geometry. Every shaft, piston, rod or sliding member that crosses a fixed wall/flange needs a REAL bored hole, slot or cutaway opening with measured swept clearance; a solid shelf with a dark circle painted on it is a failure. Test the moving body against the actual structural mesh at the crossing plane, including the lowest/full-travel pose. Ignition flames, gas arrows and pressure indicators must also stay in the moving free volume: their full tips/tails/width must not cross the piston, liner, valves or plug. Keep depth testing on; an explicit x-ray teaching mode must be separately selected and clearly identified, never the default. Capture before/contact/after frames from at least two useful orbit angles. A failed or unrun penetration check blocks acceptance.
Hard acceptance, not promises about agents: reject delivery until the manifest has no unexplained missing essentials; numeric invariant tests pass at boundaries and dense cycle samples; repeated freeze(t) yields identical state; desktop/phone hero frames and front/back/high orbit crops are reviewed; a motion strip proves causal order, contact and no interpenetration; controls, pointer-drag vs click, keyboard selection/focus and reset are tested. Store actual commands/results and tolerances in qa/report.json. An unrun check is UNVERIFIED, never a pass. These gates make omissions detectable; no skill can guarantee every future agent complies.
Profile-aware QA: retain finite geometry, console, deterministic time, contact and motion checks for every preset. Pixel uses palette/dither checks; toon uses native contour/material checks; hybrid checks low-res target + nearest upscale + only one outline pipeline. Educational off-white (and the canonical single UI surface only when enabled) replace white-empty-paper/cast/ritual quotas explicitly; do not silence unrelated failures. Fixed-camera assertions apply only after orbit.reset(), never during user inspection.
Canonical educational UI and inspection contract
This is the single authority for educational UI, selection and lesson behavior. EDUCATIONAL / EXPLICITLY REQUESTED FEATURES ONLY: ordinary narrative scenes skip this chapter and its UI tests. Requested narrative inspection may reuse only its selection behavior; do not add the card, lessons or teaching labels.
The exact V8 tokens/hierarchy below remain the 3.16 visual contract.
Use code, not an interpretation of “shadcn-style”. For new educational scenes WITH the educational UI enabled (not an explicit UI-free brief), copy templates/education-v8.css and build the DOM hierarchy below. UI-free educational scenes skip this chapter's DOM and UI tests; narrative scenes do not inherit it.
This is the canonical visual contract extracted from the V8 explorer, independent
of the chosen 3D render preset. Default to its ONE right card / mobile bottom dock;
do not substitute the older bottom/center examples as new-build defaults.
An explicitly requested bottom/center dock may change placement only, retaining
these tokens, controls and hierarchy. Existing repairs preserve requested placement.
The older education-dock.css is a minimal helper, NOT the V8 visual reference;
do not use it as the visual starting point for new educational builds.
Evidence: the grandfather-clock drift used beige/brass UI, a separate top-left
title, translucent blurred panel and fixed top-to-bottom height. None follows
from a clock subject. Brass belongs on the clock, not on its application chrome.
Exact visual values (copy the CSS; do not restyle per subject)
System sans, base 14px/1.5. Desktop heading 21px/1.35, weight 650,
letter spacing -0.6px; mobile 19px. Supporting copy and buttons 12px.
Desktop .viewer: grid minmax(0,1fr) 360px, right padding 24px,
height 100dvh, vertically centered card. Stage is the first grid cell, NOT
a fullscreen canvas underneath an overlay. Card is content-height, max
calc(100dvh - 48px), 22px padding, 18px gap, 14px radius, 1px border,
shadow 0 1px 3px #18181b08, 0 8px 32px #18181b03.
Below/equal 880px: one column, rows minmax(0,1fr) auto; dock max-height
48dvh, full width, top corners 14px, padding 16px 18px plus safe-area bottom.
Measure the actual remaining stage for camera fit and renderer sizing.
Two segmented tabs: secondary background, 4px inset, 9px outer radius;
selected tab white with subtle shadow. Primary playback is dark ink/white,
not subject-coloured. Controls 36px desktop / 40px mobile; maintain adequate
touch targets (44px hit regions where needed without crowding the row).
No beige/brown UI substitutions, serif/display fonts, uppercase eyebrow,
translucent glass, backdrop blur, heavy shadow, detached title, always-open
technical sections, extra dashboards or full-height panel. Do not grow a short
card to fill its max-height. Subject geometry/materials remain subject-specific.
Adapt subject names, number of lesson steps, part IDs, explanatory text and
physical units only. Omit Inside for a mechanism with no enclosing shell; never
add a fake x-ray toggle. Optional scrubber/Back lives in this same surface, not a
second toolbar. Use line SVG icons matching the supplied CSS in production.
Implement tab click plus ArrowLeft/Right/Home/End roving tabindex, hidden panel
state, and semantic buttons/select/range. Bind controls to the actual evaluator:
play/pause, freeze(step.phase), orbit.reset, reversible inside,
selectPart(id) and clearSelection. A lesson change freezes synchronously and
updates explanation from that state; it must not trigger automatic camera motion.
The skeleton/CSS is not a functioning controller; do not ship inert controls.
Three regression gates
Computed-style/structure: at 1280×800 assert one card, one h1 INSIDE it,
360px card column, opaque white card, exact neutral tokens, no backdrop filter,
content-height card, closed About and Explore selected initially. At 390×844
and 320×640 assert one bottom dock, no horizontal overflow and an uncovered
nonzero stage. Inject beige tokens, detached title and full-height panel; each
must fail the check. Record measured values, not just “V8-like”.
Rendered evidence: review desktop, phone and 200% zoom screenshots plus
selected/restored states. Check actual background pixels against the authored
paper (not merely body CSS), tiny-part readability, stage/card separation and
front/back/high camera fits. For V8 matching use #f7f7f5 consistently in CSS,
renderer clear/scene and ground composition; user-requested white overrides all
those together. A screenshot is not mechanical clearance proof.
Interaction: keyboard-only tabs/steps/picker/reset, paused orbit, drag vs
selection, Inside lifecycle and shared-material restoration must pass existing
per-scene gates. Store commands, values and proof paths in qa/report.json;
missing browser/computed-style/visual checks remain UNVERIFIED.
Selection, focus and lesson adapter
Raycast actual visible geometry: nearest eligible hit wins, respecting nearer
opaque occluders. Map the hit mesh to both its assembly ID and its actual piece
ID; assembly selection and clicked-mesh selection are distinct scopes. The
single labelled keyboard piece picker must expose the same pieces/actions,
including hidden pieces; never silently broaden a click to an entire assembly.
Show one short explanation in the card. An optional single label uses a live
geometry-local anchor and hides behind camera, offscreen or when occluded.
A deliberate canvas/picker Inspect selection may make one short useful camera
AND OrbitControls-target transition to live selected bounds. Avoid end-on shafts
and blocking housings; use an authored reveal/cutaway for hidden pieces and
report remaining occlusion honestly. Save the prior view for Back; Reset restores
the hero. User orbit/pointer/keyboard navigation cancels the tween immediately.
Reduced motion uses an immediate useful view. Never auto-spin, chase moving parts
or restart focus per frame. Lesson step selection instead pauses and synchronously
freezes the real evaluator, highlights its part and updates phase/text/readout
without moving the camera; only an explicit Inspect action focuses. Scrubbing
updates the lesson from evaluated state, not an independent clock. Announce
intentional changes politely, not each frame.
Use semantic buttons/select/range, visible focus and non-colour part-name cues;
canvas arrows orbit and R resets. Tabs implement roving focus and keyboard
navigation; no focus trap. Drag/multitouch is orbit, not click (use the movement
threshold/cancel handling in templates/orbit.js); UI gestures never bubble into
the stage. Paused and reduced-motion modes retain inspection.
Soft glow and holographic inspection — implementation recipe
This is an inspection overlay, not a new render preset, bloom pass or a way to hide modelling errors. Use the same mechanism for a selected gear, valve, pump impeller, drawer slide or anatomical structure. The V8 selection implementation is the calibration evidence: restrained warm material lift, dimmed context, transparent outer castings and selective gold feature edges. Do not interpret “glow” as a white emissive blob.
1. Preserve and derive, never mutate the shared originals. Build a registry once from the actual selectable meshes, BEFORE adding overlays. Store each exact original material reference, including arrays of material slots; a mesh's slot array itself must also be restored by identity. Derive cached variants from each source UUID plus mode. Clone userData and outlineParameters before changing outline alpha, since nested objects may otherwise be shared. Keep toon ramps, texture maps, roughness and existing supported preset properties. Restore the originals before applying each new selection/X-ray state, not by attempting to reverse colour arithmetic.
Use templates/inspection.js rather than duplicating a second material controller.
Its API is createInspection(THREE, {parts, contextMeshes, resolveVisibility, onChange, style}), with select({partId, mesh}), clear(), refresh(),
dispose() and piecePickerEntries(partId, {visibleOnly:false}) (includes hidden
pieces for keyboard inspection). Validate actual mesh membership before selection.
The helper supports rigid meshes only; reject skinned/instanced/morph assumptions.
resolveVisibility returns named hiddenPartIds/hiddenMeshes plus description
for an authored cover removal. Hiding requires shell:true, or an explicit
inspectionOccluder:true part plus an active selection and nonempty cutaway
description; that latter exception may remove an upper gear/bridge to expose a
lower part, never hide construction failures. Optional ghostPartIds/ghostMeshes
are accepted only for shell:true. Selected assemblies/pieces remain visible;
context meshes (floor/stand/UI) cannot hide, ghost or dim.
Unknown parts, duplicate ownership, empty geometry and unsupported material or
deformation paths fail explicitly. Never request a whole-mechanism ghost. The host owns
camera focus, picking and V8 DOM; the helper owns emphasis/restoration, not UI or
mechanical certification. Cached variants derive per original material and mode; never
from the currently displayed variant. Lift colour gently; write emissive values
only where the original material supports them. Dim context as opaque solids.
Only the explicit housing reveal below may change transparency/depth-write.
2. Reveal only manifest-authorized occluders; ghosting is shell-only. Never defeat depth on the selected part. Declare internalPartIds and occludingShellIds per subject in the component manifest. For an internal selection, remove authored covers or optionally ghost only declared outer housings that obscure it; keep the selected part solid, retain non-selected internals as dim solids, and leave floor/stand/UI alone. A global Inside toggle applies that same named reveal plan without dimming all internals. A selected housing stays highlighted rather than ghosting itself. Unlisted opaque solids must still occlude correctly: renderOrder does not override the depth buffer. For an internal blocker, author an explained selection-only inspectionOccluder:true removal plan; the independent Inside toggle still affects shells only. Hidden siblings need a piece-level plan and cannot remove the selected scope. Do not set depthTest=false, use additive whole-body overlays, or fade all solids to pretend a mechanism is correctly constructed. Picker rays ignore generated edges and ghost-shell hits, but respect remaining opaque foreground objects; click and picker share the same selection action.
3. Make the hologram from feature edges, attached to the live part. Do not use wireframe:true: that exposes triangle diagonals. Use EdgesGeometry(source.geometry, 32) and a restrained LineBasicMaterial (color:0xffc35c, opacity:0.5, transparent:true, depthTest:true, depthWrite:false, toneMapped:false). Normal blending, no bloom. Exclude slivers, ring grooves, gaskets and tiny bolts when edges become noise; the V8 thresholds were minimum dimension 0.018 units and, for cast housings, volume 0.006 units³. Those are model-scale-dependent starting values, not universal dimensions. Use one physical edge overlay on the selected component only, not a second full-scene OutlineEffect/Sobel pipeline. Its surface outline may need suppression to avoid doubled contours. WebGL line width is generally one device pixel: do not promise a controllable CSS-pixel width through linewidth.
Attach each owned edge overlay as an identity-transform child of its live source
mesh; mark it as an inspection overlay and exclude it from raycasting. On change,
remove and dispose owned overlays, never source geometry or shared maps.
This child pattern follows moving rigid geometry without copying a stale pose. If an overlay must be a sibling/world-space object, synchronise its transform from the source every evaluation; copying position/quaternion once is insufficient when the source mesh moves. EdgesGeometry does not automatically follow vertex deformation or per-instance transforms: skinned/morphed/instanced subjects need a deformation-aware shader/overlay or a clearly declared unsupported path. Never claim those supported because a rigid V8 example works. Do not dispose the source geometry, shared source maps, shared toon ramps or original materials; dispose only owned variants/edge geometries and owned overlay materials. Keep overlay generation bounded to selection changes, never create/dispose hundreds of edge objects every frame.
State and restoration contract. One selection controller owns this effect. Resolve in order: restore exact originals → remove previous edges → compute selected/internal/Inside state → ghost selected occluding housings → highlight selected meshes → dim remaining mechanism meshes → attach selected edges. Re-apply from originals when Inside changes. Leaving How it works restores its earlier Inside state and removes its tutorial tint; clearing selection retains an independently enabled Inside toggle. Picker, canvas, keyboard and lesson adapters must not compete by writing materials from separate uncoordinated caches. Clear/reset/teardown restores material references, opacity/depth/blending/outline state, selection/readout and authored camera state; only teardown disposes long-lived caches. Respect reduced motion; avoid automatic pulsing, scanlines or flashing. Keep the part name and keyboard focus as non-colour cues.
Historical evidence (not project dependencies):quartz-watch/shots/highlights/dialPost1.png,
quartz-watch/shots/highlights/dialPost2.png, quartz-watch/shots/highlights/dialPost3.png,
quartz-watch/shots/highlights/dialPost4.png, quartz-watch/shots/highlights/individual-piece.png,
quartz-watch/shots/highlights/rotor.png, quartz-watch/shots/highlights/reduction.png,
quartz-watch/qa/highlights-report.json and quartz-watch/qa/construction-report.json.
These record this repair, not files future users must have. Twenty-six assembly
glow states had numerical tests/captures; only a subset received visual review.
Do not present that as universal contrast certification.
Evidence and test — selection contract (3.18). Quartz-watch selection was
almost invisible, posts were end-on/occluded, and adding emitter properties to
MeshBasicMaterial caused a shader.value error. Use templates/inspection.js,
with templates/qa/inspection.test.mjs and
templates/qa/inspection-browser.mjs; use the API above. Assert assembly versus actual clicked-piece identity,
keyboard equivalence, nearest opaque occlusion, and obvious visible glow with
retained shape/colour (never a white blob) in desktop/phone crops. Test shared
and array materials, Basic/toon, two frozen phases, moving/orbiting, rapid changes,
Inside/clear/Back/Reset/lesson exit, interrupted focus and reduced motion. Restore
exact original material AND slot-array identities, shadow flags and visible
state, plus original material properties; test source immutability and owned-only
disposal with stable overlay/material counts. Basic materials must never gain
emissive or emissiveIntensity, even temporarily; feature-test capability before
writing, and assert absent properties remain absent. Verify shader compilation
and no console errors in the fresh browser build. Scalar/material tests alone do
not establish visible contrast, depth correctness or useful focus.
Repair acceptance: enclosure, fit and reference UI (3.15)
Use this short checklist for existing educational scenes before re-reading narrative
recipes. Evidence: the LEAP-1B repair was requested because its permanent section
exposed the core, its fit cropped the model, its beige background and crowded panel
did not match the requested V8 reference. These checks supplement mechanical QA;
passing enclosure rays or a screenshot does not certify a complete mechanism.
Closed first, explicit Inside. Unless a permanent section is commissioned,
cold load and hero Reset show the complete opaque housing, no tutorial tint,
Inside off. Build the missing casing as real connected wall geometry while
preserving inlet/outlet openings; a toggle cannot repair absent geometry.
Inside is a named semantic button in the single surface. Internal picker or
lesson selection may explicitly activate it, but must update its pressed state;
leaving the lesson restores the preceding Inside state. Clearing selection
preserves an independently enabled Inside state. Test: load → Inside on/off
→ internal selection → clear → lesson exit → Reset; check visible ancestors,
nearest opaque ray hits, exact material restoration and open-mouth rays.
Fit the assembly in the space actually available. Measure canvas layout
after the dock/panel; use actual complete assembly bounds including covers,
supports and swept extrema, not a default slab. Fit the safe rectangle with
padding; if UI overlays the canvas, solve its offset as well as distance.
With direction target→camera, depth is distance - along, so each fit bound
contributes abs(transverse)/tanHalf + along (not minus along). Do not clamp
distance below the solved fit or distort portrait aspect. Re-measure on layout,
disclosure, resize/orientation and zoom changes without hijacking user orbit.
Test: project covered/exposed swept bounds at desktop, tablet, 390×844,
320×640 and 200% zoom, with lesson/disclosure open; front/back/high captures;
fail an injected protrusion and verify near-plane/focus fits separately.
UI repair: compare the supplied reference before changing placement;
apply Canonical educational UI and inspection contract, including rendered
background, accessible lesson state and desktop/phone/200% zoom gates. Do not
copy the reference subject or introduce a second surface.
Construction regression gates
These construction rules apply across subjects and all render presets; they supplement, not replace, the style gate and profile-aware verification above. They make known failures testable, not impossible.
Specify the mating interface before decorating the part. Extend the component manifest with units, parent-local frame, shaft/bore/slide axes, shared joint/port anchor IDs, mating surfaces, nominal dimensions and radial/axial tolerances. Derive both mating meshes and their motion from those anchors, not repeated guessed offsets. A bearing eye needs a real through-bore; its beam, cap, bolt and bevel must stop outside that bore. Budget bevel/fillet intrusion in the actual construction method (inward bevels reduce usable bore), axial lane widths, spacers, end float and end stops. Check coaxial alignment and anchor residual after parent transforms. Model the load path through real bearings, brackets, fasteners and a base; route each functional port through an actual connected opening to its destination, not a hose ending inside a solid. Document symbolic/omitted internals. Evidence: V8 running-gear repair found a centred rod beam cutting its crankpin despite an annular eye, bank stagger applied to only one mating member, and fillets facing the wrong local axis. Test: local-axis/anchor tests, measured bore plus bevel allowance and axial stack tests, section crops from two orbit directions, and traced port/support connections. Record geometry revision and proof frames in the manifest. Copy templates/mechanism-contract.mjs and fill the interface and connection sheets in templates/DESIGN.md; the helper validates scalar budgets, not arbitrary mesh bores or load strength.
Audit the complete swept assembly, with narrowly scoped intended contact. Derive every driven pose from one driver and test the actual transformed meshes or documented conservative collision proxies, including beams, caps, fasteners, webs, fillets and supports. Broad-phase boxes alone neither detect holes correctly nor prove clearance. Enumerate potentially interacting pairs and coverage; whitelist only a named pair of mating surfaces with phase window, normal-gap/penetration tolerance and rationale (bearing/journal, meshing teeth, valve/seat), never an entire assembly or all pairs of a part type. All other pairs need the declared positive clearance. Check full travel, extrema, cycle seam, contact transitions and close-approach intervals with refinement; include ports/FX containment. Report method, sample spacing, tolerance, worst phase/pair, exclusions and unresolved regions. Dense sampled vertex/triangle tests are bounded evidence, not continuous exact collision proof: use analytic bounds or conservative continuous checks where available, otherwise retain that limitation explicitly and block unsupported clearance claims. Evidence: the V8 12/12 invariant report omitted rod/crank interference; the later rod probe added bore triangle samples, axial lanes, journal vertices, anchor residual and fillet axes. Test: intentionally inject a beam-through-bore, wrong-axis fillet, too-wide lane, out-of-window contact and a non-whitelisted overlap; each must fail. Run full-cycle probes plus before/contact/after crops from two angles. templates/qa/mechanism-contract.test.mjs tests budget/contact-policy failure detection only; per-scene geometry/sweep checks remain mandatory and UNVERIFIED until run.
Repeated interfaces share anchors and axes (3.18 evidence + test).
Generate ALL repeated mating members from one anchor/axis table, not just the
first working example. Quartz-watch pads at radius 12.6 missed posts at 13;
rotating a native CylinderGeometry about Y did not redirect its native Y axis.
The seconds shaft opposed its hand and the model lacked a physical 60:1 stage.
Coplanar shaft-cap fans z-fought. Use transformed local axes (quaternion maps
native Y to the declared axis), common anchors, real through-bores and a single
end surface or measured axial separation; never hide coplanar caps with depth
overrides. Derive ratio/direction from the actual connected transmission, not
only a display hand formula. Test: with templates/mechanism-contract.mjs
shared anchors/checkRepeatedInterfaces/checkEndPlanes, enumerate every pad,
post, bore, cap and shaft; assert count, transformed axis/anchor residual,
radial/axial clearance and physical ratio/direction across the full cycle.
The repaired watch measured zero residual at all four pad anchors and 0.08
board-bore radial clearance; those are historical measurements, not defaults.
Inject one displaced repeat, wrong native axis, sealed bore, reversed shaft,
missing reduction and coplanar cap; each relevant check must fail. Review
section/end-on and oblique crops; scalars cannot prove real mesh openings.
Evidence: the historical construction report and highlight shots above.
Lesson/UI behavior and its tests are defined once in Canonical educational UI and inspection contract. templates/education-dock.mjs remains a dependency-free
state helper with templates/qa/education-dock.test.mjs; its older CSS is not the
V8 visual authority.
Universal Inspection Controls
Copy templates/orbit.js for EVERY scene and preset. Create it after camera fit with the fitted target; keep animation evaluation independent of camera interaction. Render on control change even when paused. Expose orbit.reset() and have the QA freeze wrapper reset it before capture (freeze(t) evaluates time synchronously). User pause/freeze UI need not reset their chosen inspection angle. Fit zoom/polar limits to real subject bounds without preventing back/high inspection. No auto-rotation, no camera motion driven by the animation clock. Keep reset + a brief drag/keyboard hin
