3D assembly manual

Proven on a garden-bed build, then generalised after kitchen and sauna test builds. Copy starter.html: a project-agnostic engine with a four-step shelf example that renders on its own. Edit only the CONFIG block and the PROJECT SCENE block; leave the engine alone.

CONFIG keys (top of the script)

PROJECT SCENE block: context geometry (auto-painted white), wall(side, x0, x1, y0, y1, z0, z1) for rooms, P.* part builders, optional THUMB_ONLY[key] builders (a thicker thumbnail-only variant for thin parts: bands, wires), reg() calls. Groups passed to reg() are re-centred automatically, so parts can be built in absolute coordinates.

Look (BIG evolution diagram)

• White model, ink hairline edges (EdgesGeometry, opacity ~0.72), near-flat light: HemisphereLight 0.9 + sun 0.16, one pale PCFSoft shadow. Toon gradient bands 226/241/255.
• Already-built parts near-white (#ececec). Only this step's new or removed parts in the pale fill; arrows in the dark accent. Parts page shows the whole kit in fill. The starter default is the blue pair #1F4FD8 / #A6C0F6; one orange (#f28c1e) for both also works.
• No people in the scene by default: every figure tried so far (cylinder people, then a flat Modulor cut-out) read as weird. Scale comes from the dimension lines and the live scale bar. modulorFigure() stays in the starter only for an explicit request. Chrome neutral: white paper, ink buttons, grey rules, Geist + Geist Mono, sentence case, square corners. Colour lives only in the picture.

Engine (in starter.html)

• reg(key, obj, {add, remove, only:[pages], from, lag, each, span, part, grow, noGhost, noArrow}); a page's scene is the cumulative state; only parts fade when their page turns.
• Orthographic camera; preset {c, r, v} tweened 900 ms ease-in-out, walls and cutaways tweened with it. Every tween's clock starts on its first rendered frame, so a slow first frame can't eat the opening motion. Landings 700 ms ease-out along an arrow, ghost outline at destination, accelerating stagger span*sqrt(i/(n-1)).
• Per step: parts callout with 3D thumbnails (second renderer, toDataURL; below 760 px one scrolling row of 32 px thumbs, ellipsised names, right-edge fade when it overflows), numbered action marks with screen offsets (clamped below the callout; the leader is redrawn from the clamped position to its point), detail bubble (scissor pass, circular mask with overflow:hidden), dimension lines, live scale bar, plan inset, step number, time, one tip.
• Tap a part = blink + outline flash. Swipe the sheet (pointer events, touch-action:pan-y). #stepN deep-links, #stepN&still freezes for captures.

Process

1. 1Measure or estimate the real space from photos (mark "verify"); list parts grouped by where they come from.
2. 2Write STEPS copy: plain instructions, 2-4 numbered acts, quantities in a mono meta line.
3. 3Build (the starter has no dark-mode tokens: it commits to a light drawing sheet on purpose), then verify at 375 px in a browser over a localhost server (e.g. python3 -m http.server; keep the viewport meta), and capture with headless Chrome through a 390x844 iframe harness at #stepN&still.
4. 4Deliver one .html file: Three.js and fonts load from a CDN, everything else is inline, so it opens by double-click or on any static host. Until you have a capture from the browser the reader will use, call the render unverified.

Gotchas

• MeshToonMaterial in shadow drops the whole directional term: keep ambient high or orange goes brown.
• Keep pulse base colour under its own userData key (opacity code owns userData.base).
• Emissive glow is invisible on white or accent parts; blink opacity instead.
• Touch-only handlers can't be tested with mouse-driven automation; use pointer events.
• Rooms: work on opposite walls (sink run vs nook) needs two presets with different v, each cutting the walls between camera and work (learned on a kitchen build). The pale fill matters: a dark part fill hides the ink edges.
• Numbers derived from another file (plank rows, rips) : port its calculation functions instead of retyping results.
• Captures: run headless Chrome one at a time, each under perl -e 'alarm 50; exec @ARGV' <chrome --headless=new --user-data-dir=<scratch>/st-N --disable-gpu --use-angle=swiftshader --enable-unsafe-swiftshader --window-size=520,880 --timeout=15000 --screenshot=...> (macOS has no timeout; it does not exit on its own), then pkill -f user-data-dir=<scratch>/st-N. Parallel runs give black canvases.

Sources

• Video with no transcript (music-only): read the burned-in captions from frames. Draw the paused video to a canvas at intervals, lay the frames out as a contact sheet on the page, screenshot it. Seeking in a background tab renders black.