partforge 0.44.0 → 0.46.0

package/bin/cli.js

@@ -159,15 +159,35 @@ const commands = {
     try {
       const part = await loadPart(partPath, usage);
       const baseParams = flags.params ? JSON.parse(flags.params) : {};
+      // `--params '[1,2]'` or '42' parses fine and then merges into nothing, so the
+      // flag silently does nothing. Only an object can carry param overrides.
+      if (baseParams === null || typeof baseParams !== "object" || Array.isArray(baseParams)) {
+        die(`--params takes a JSON object of param overrides\n${usage}`);
+      }
       const outDir = flags.out || "render";
       const views = flags.views ? flags.views.split(",") : undefined;
-      // Usage check BEFORE the kernel: a flag typo shouldn't pay a WASM boot.
-      if (!flags.animation && (flags.at || flags.step)) {
+      // Usage checks BEFORE the kernel: a flag typo shouldn't pay a WASM boot.
+      // Test `=== undefined`, not falsiness: `--animation ""` is a flag the user
+      // passed and got wrong (an unset shell variable, typically), not one they
+      // omitted, and silently rendering a non-animation still hides the mistake.
+      if (flags.animation !== undefined && flags.animation.trim() === "") {
+        die(`--animation needs an animation name\n${usage}`);
+      }
+      if (flags.animation === undefined && (flags.at || flags.step)) {
         die(`--at/--step require --animation\n${usage}`);
       }
+      if (flags.at != null && flags.step != null) {
+        die(`--at and --step are alternatives — pass one, not both\n${usage}`);
+      }
+      // Own-key test: `part.views?.["constructor"]` resolves through
+      // Object.prototype and would sail past a plain lookup, straight back into
+      // the background-only render this guard exists to stop.
+      if (view !== undefined && !Object.hasOwn(part.views ?? {}, view)) {
+        die(`unknown view "${view}" (have: ${Object.keys(part.views ?? {}).join(", ") || "none"})\n${usage}`);
+      }
       const kernel = await bootKernel(part);
 
-      if (!flags.animation) {
+      if (flags.animation === undefined) {
         const files = await renderViews(kernel, part, view, { views, out: outDir, params: baseParams });
         for (const f of files) console.log(`wrote ${f}`);
         process.exit(0);
@@ -196,11 +216,29 @@ const commands = {
         // step's camera instead of this step's own.
         frames = [{ t: end, cueT: anim.stepStarts[idx], tag: `${flags.animation}-step${idx + 1}` }];
       } else {
-        const ts = (flags.at ?? "1").split(",").map(Number);
+        // Split first and reject blanks: Number("") is 0, so "0.2,,0.8" would
+        // otherwise slip a silent extra frame at t=0 past the range check.
+        const raw = (flags.at ?? "1").split(",");
+        const ts = raw.map((s) => (s.trim() === "" ? Number.NaN : Number(s)));
         if (!ts.length || ts.some((t) => !Number.isFinite(t) || t < 0 || t > 1)) {
           die(`--at takes comma-separated positions in 0..1\n${usage}`);
         }
-        frames = ts.map((t) => ({ t, tag: `${flags.animation}-t${String(Math.round(t * 100)).padStart(3, "0")}` }));
+        // The tag is the only thing distinguishing one frame's file from another.
+        // Two decimals suits the usual `--at 0,0.5,1`, but a dense request like
+        // 0.001,0.004 collides and the later render would silently overwrite the
+        // earlier — one file for two frames asked for. Widen the tag just enough
+        // for THIS request instead of refusing it: ordinary runs keep their
+        // familiar t000/t050/t100 names, dense ones get one file each.
+        const tagsAt = (decimals) =>
+          ts.map((t) => String(Math.round(t * 10 ** decimals)).padStart(decimals + 1, "0"));
+        let decimals = 2;
+        while (decimals < 6 && new Set(tagsAt(decimals)).size !== ts.length) decimals++;
+        const tags = tagsAt(decimals);
+        if (new Set(tags).size !== ts.length) {
+          // No precision separates them: the same position was listed twice.
+          die(`--at lists the same position more than once\n${usage}`);
+        }
+        frames = ts.map((t, i) => ({ t, tag: `${flags.animation}-t${tags[i]}` }));
       }
       for (const frame of frames) {
         const { values } = evaluate(anim, frame.t);

package/docs/AUTHORING-PARTS.md

@@ -167,6 +167,13 @@ Rules (all lint-enforced):
   inside the owning control's min/max (the engine applies them unclamped).
 - Params not tracked anywhere keep their current values; a param tracked in
   one step holds its nearest keyframe value while other steps play.
+- A step may declare a `camera` and **no** `tracks` — an establishing shot that
+  swings the view while the model holds still. At least one step still has to
+  carry tracks, or the animation animates nothing. Note the holding value is the
+  nearest keyframe, not whatever the user last set: a leading camera-only step
+  shows the animation's opening pose, the same one `t = 0` would show.
+- `loop` and `autoplay` must be literal booleans. Anything else is reported by
+  lint and treated as `false` at runtime, so `loop: "false"` never means "loop".
 - Couple motions through `derive` (animate one master param; derive the rest),
   not by tracking dependent params separately.
 - `camera` cues use the seven canonical angles (`iso front back top bottom
@@ -227,7 +234,7 @@ future contract v2 — but are not shown here; see `docs/KERNEL-CONTRACT.md`
 | `k.box({ size, center? })` · `k.box({ min, max })` | `{size:[x,y,z]}` = centered X/Y, base at z=0 (`center:true` also centers Z); `{min,max}` = explicit `[x,y,z]` corners |
 | `k.prism({ points, h, twist?, scaleTop? })` | extrude a 2-D polygon (or an **arc profile** from `roundedProfile`) from z=0; optional `twist` (degrees over the height) and `scaleTop` (uniform top taper: 1 straight, <1 taper in, 0 → point/cone) |
 | `k.extrude({ profile, h, twist?, scaleTop? })` | extrude a **polygon-with-holes** region from z=0 in one op — `profile` is `{ outer, holes? }` where each contour is a points array **or an arc profile** (`roundedProfile`, for true STEP fillets), or a bare points array / arc profile for outer-only; same `twist`/`scaleTop` as `prism` (both backends) |
-| `k.loft({ rings, ruled?, closed? })` | stack polygon cross-sections into a solid — ruled walls between consecutive rings, capped ends (both backends; `closed:true` capless loops are Manifold-only). `ruled:false` (smooth C2 blend) is honoured only by OCCT/STEP export; the Manifold preview always shows faceted straight walls |
+| `k.loft({ rings, ruled?, closed?, shading? })` | stack polygon cross-sections into a solid — ruled walls between consecutive rings, capped ends (both backends; `closed:true` capless loops are Manifold-only). `ruled:false` (smooth C2 blend) is honoured only by OCCT/STEP export; the Manifold preview always shows faceted straight walls. `shading?: "smooth" \| "faceted"` overrides facet/smooth shading inference (default: <32-side rings shade as flat facets, drawing no same-surface lines at all — not even their own cap rims — though cut seams against other solids still draw; ≥32 sides shade smooth) |
 | `k.sweep({ profile, path, cornerRadius?, closed?, ruled?, smooth? })` | sweep a fixed 2-D profile along a 3-D polyline path — sharp mitered corners (or `cornerRadius` fillets), capped ends (both backends). `closed:true` capless loops and `smooth:true` (OCCT-native swept B-rep, STEP-exact / preview-faceted) are backend-specific, like loft's `closed`/`ruled:false`. `closed:true` loops must be **planar** — RMF frame-transport holonomy can seam-twist a non-planar closed loop where the last station rejoins the first, so only planar closed loops are supported/tested |
 | `k.sphere({ r\|d })` | sphere centred at the origin; bare `k.sphere(r)` also stays valid |
 | `k.roundedBox({ size, center?, round })` | box with rounded edges — `round` = number (all edges) or `{ side?, top?, bottom? }` (vertical edges / rims); stays on Manifold (no OCCT routing, unlike `fillet`); `side` must be 0 or ≥ the rim radii (between clamps with a warning); with `side > 0`, `top + bottom` must be strictly `< h` |
@@ -391,6 +398,10 @@ if (p.drain > 0) s = s.cut(k.cylinder({ r: d.drainR, h: p.floor + 4 }).at([0, 0,
   a cutting tool's label lands on the faces it leaves behind (the hole's wall).
 - Label **after** shaping compound tools (e.g. after an `intersect` clip) and
   either before or after transforms — labels ride through `at`/`rotate`/etc.
+  Labeling a compound collapses it to ONE shading surface — the majority
+  policy of its registered surfaces (by triangle count) applies to the whole
+  solid, so a faceted policy also suppresses line-drawing on the compound's
+  internal seams.
 - **Same label merges; distinct siblings need distinct names.** The same label on
   several solids merges into one feature — label a ring of four bolt holes
   `"Mounting holes"` and they hover/highlight as one. Conversely, when two similar
@@ -484,6 +495,12 @@ choosing a preset updates both numeric and text fields.
 Every `key` used must exist in `defaults`. `src/parts/demo.js` is the worked example for
 everything below.
 
+A feature's `on` is **required and must be greater than 0** — it is the real value the
+parameter takes when the box is ticked (a diameter, a count), and the panel reads
+`> 0` as "enabled", so there is nothing sensible to fall back to. `partforge lint`
+reports a missing or non-positive one as `features-requires-on`. A `toggles` entry is
+the exception: its `on` is just a flag and defaults to 1.
+
 **Standalone toggles** (a plain on/off checkbox, no accompanying sliders): add a
 `toggles` array to a preset section — shown below the preset picker, outside the
 Advanced fold, so it stays visible:
@@ -791,6 +808,27 @@ Copy `demo.html` and change the title, the panel heading, and the `<script src>`
 workers are spawned from your one worker entry (`name` = `"manifold"` for preview/STL/3MF,
 `"occt"` for STEP — handled for you).
 
+**View control (the mount handle).** For an embedder driving the view tabs from its own UI
+instead of (or in addition to) the built-in `#part` bar:
+
+- `runtime.getView() → string` — the active view name; never null once the runtime is ready
+  (mount resolves a default before first build — see "Which view the viewer opens on" above).
+- `runtime.setView(name) → boolean` — switch tabs programmatically, the same path as clicking
+  a tab. Returns `false` (and leaves the active tab untouched) for a name the part doesn't
+  declare in `views`; `true` otherwise, including when `name` is already active.
+- `await runtime.captureView(viewName?, opts?) → Promise<string | null>` — a JPEG data URL of
+  `viewName` rendered offscreen (falling back to the resolved default view — see
+  `resolveDefaultView` / `default-view.js` — when `viewName` is omitted or names a view the
+  part doesn't declare). Never disturbs the active tab, the live camera, or the on-screen
+  scene; `opts` forwards to the underlying render (size, quality, angle). Resolves `null` on
+  failure rather than throwing (a build error, a part with no sub-parts in that view, a
+  disposed runtime).
+
+Pass `onViewChange(name)` to `mount()` to be told the active view: it fires once
+synchronously during mount with the initial resolved view (before `runtime.ready` settles),
+then again on every subsequent change — a tab click or a `setView` call — always with the
+new view name.
+
 **Headless export (the mount handle).** The `#download*` buttons above are the built-in,
 view-bound export UI. An embedder that wants its own export UI (e.g. a "pick which parts,
 pick a format" modal) can skip those buttons and drive export off the handle `mount()`
@@ -1083,9 +1121,10 @@ previously didn't; that's the fix working as intended, not a regression.
 `missing-views`, `part-view-unknown` (all errors); `view-unused`,
 `default-view-ambiguous` (warnings).
 
-**Parameter schema** — `features-requires-sliders`, `control-key-not-in-defaults`,
-`preset-key-not-in-defaults` (errors); `slider-range-excludes-default`,
-`unknown-control-field`, `duplicate-control-key`, `default-not-exposed` (warnings).
+**Parameter schema** — `features-requires-sliders`, `features-requires-on`,
+`control-key-not-in-defaults`, `preset-key-not-in-defaults` (errors);
+`slider-range-excludes-default`, `unknown-control-field`, `duplicate-control-key`,
+`default-not-exposed` (warnings).
 
 **Kernel API**, found by executing `build()` against a geometry-free probe —
 `unknown-kernel-op`, `unknown-solid-op`, `invalid-op-options`, `build-throws`,
@@ -1376,6 +1415,13 @@ everything else (so sweep-heavy parts, e.g. helical grooves, stay fast). Force i
 `meta.backend: "occt" | "manifold"` if you ever need to. Because an OCCT part is built
 entirely on OCCT, its fillets are exact in the STEP **and** present in the printed STL.
 
+**Shading intent.** The kernel decides what shades smooth and where edge lines
+draw — spheres, cylinders and fillets are smooth by construction; boolean cut
+seams always shade hard and draw a line; a loft's facets shade flat when its
+rings have fewer than 32 sides (`shading: "smooth"|"faceted"` on `k.loft`
+overrides the inference either way). If your part previews smooth but would
+print faceted — or the reverse — set the hint rather than changing facet counts.
+
 > Trade-off: OCCT is much slower on heavy swept geometry (helical grooves), so don't reach for
 > `fillet`/`chamfer` on a sweep-heavy part — design those edges in, or keep the part on Manifold.
 

package/docs/ERROR-PATTERNS.md

@@ -318,6 +318,25 @@ Variant literals under this entry: `offsetPolygon: delta must be a finite number
 - **Cause:** A track drives a param that feeds real geometry (or a build the pose probe can't trust — a query op or function selector), so every frame is a worker rebuild instead of a pose repair.
 - **Fix:** Run `npx partforge lint <part>` — the `animation-track-rebuilds` note names the track. Restructure so the param only feeds rigid placement (`place()` or a trailing translate/rotate in `build`), or accept best-effort playback if geometry morphing is the intent. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Animations".
 
+## phantom-edges-on-curved-surface
+
+- **Symptom:** edge lines or hard-shaded patches appear scattered on a smooth
+  curved surface (a sphere, fillet, or blend) in the viewer or in `render` PNGs.
+- **Cause:** the mesh reached the viewer without kernel `normals`/`edges`, so a
+  consumer fell back to dihedral-angle guessing on coarse preview tessellation.
+- **Fix:** the backend's `toMesh` must return analytic normals and filtered
+  feature edges ([KERNEL-CONTRACT.md](KERNEL-CONTRACT.md) "Shading intent") —
+  fix the backend or payload plumbing; do not tune viewer angle thresholds.
+
+## faceted-loft-previews-smooth
+
+- **Symptom:** an intentionally faceted loft (low-side-count rings) previews
+  smooth-shaded, but exports/prints show flat facets.
+- **Cause:** the loft's shading policy resolved to smooth — a `shading:
+  "smooth"` hint, `ruled: false`, or rings with 32+ sides.
+- **Fix:** pass `shading: "faceted"` to `k.loft` (or drop the smooth-implying
+  option) per [AUTHORING-PARTS.md](AUTHORING-PARTS.md) shading-intent note.
+
 # Hardware library
 
 Reserved for `hardware-*` patterns (issue #30). No entries yet.

package/docs/KERNEL-CONTRACT.md

@@ -258,7 +258,7 @@ Normative signatures: `kernel.js`'s `@typedef Solid`.
 | `boundingBox()` | `{min, max, center, size}`; `center`/`size` are derived by `addSugar` from the backend's `{min, max}`. |
 | `volume()` | Solid volume in mm³. |
 | `genus()` / `isEmpty()` | Optional (`SOLID_OPTIONAL_OPS`): mesh-topology queries — through-hole count / no-geometry test. The mesh backend provides them; OCCT has no cheap equivalent. |
-| `toMesh({quality?})` | Render mesh: `{positions, normals, indices?, triangles, edges?, featureIds?, features?}`. `indices` optional (a backend may emit soup or indexed); `normals` may be empty (`length 0`) to delegate creasing to the viewer; `edges` (feature-line segments) and the feature fields are optional metadata. |
+| `toMesh({quality?})` | Render mesh: `{positions, normals, indices?, triangles, edges?, featureIds?, features?}`. `indices` optional (a backend may emit soup or indexed); `normals` and `edges` are authoritative shading intent from both backends — see [Shading intent](#shading-intent-tomesh-normals-and-edges) below; `featureIds`/`features` are optional metadata. |
 | `toSTL({quality?})` | `Promise<ArrayBuffer>`, binary STL, outward CCW winding. Stored facet normals may be zero — slicers recompute them (the mesh backend happens to write them). |
 | `toIndexedMesh({quality?})` | `{positions, indices}` indexed mesh (3MF path); defaults to `"print"` like `toSTL`. Coincident vertices need NOT be welded — the 3MF writer welds, because that format reads topology from the indices rather than re-stitching soup by position the way an STL consumer does. |
 | `fillet(r)` · `fillet({r, edges?})` / `chamfer(d)` · `chamfer({d, edges?})` / `shell({t, open})` | B-rep class (core throws `KernelCapabilityError`). Scalar `fillet(3)`/`chamfer(1)` acts on all edges; the options form adds an `edges` selector. `shell` hollows inward, keeping outer dimensions; `open` (face selector) is required. |
@@ -267,6 +267,39 @@ Normative signatures: `kernel.js`'s `@typedef Solid`.
 speed and a backend may bake it at kernel creation (Manifold does). A part must never
 depend on triangle counts, segment counts, or normals being present.
 
+### Shading intent (toMesh normals and edges)
+
+`toMesh` output is the authoritative statement of how a solid SHADES and which
+edges are FEATURE edges — consumers (viewer, CLI renderer) must draw what they
+are given and must not re-derive either from dihedral angles when the fields
+are present:
+
+- `normals` — per-vertex shading normals. Smooth within one surface, hard
+  across boolean-cut seams. OCCT ships analytic B-rep normals; Manifold ships
+  the policy-aware crease pass (`src/framework/geometry/creased-normals.js`).
+- `edges` — flat feature-edge segment pairs (6 floats per segment). An EMPTY
+  array means "this solid has no feature edges"; it is not "unknown". OCCT
+  ships true B-rep edges with tangent edges (fillet blends, seam lines)
+  filtered out; Manifold ships policy-gated sharp/seam segments.
+
+`loft` accepts `shading?: "smooth" | "faceted"` to override facet-vs-smooth
+inference: by default, rings with fewer than 32 sides shade as intentional flat
+facets with no same-surface edge lines, while rings with 32+ sides (and
+`ruled: false` lofts) shade smooth. `shading: "smooth"` forces smooth shading;
+`shading: "faceted"` forces facets; any other non-nullish value throws.
+Thresholds live in `src/framework/geometry/shading-policy.js`.
+
+Known limitation: the OCCT backend ignores `shading` — a loft forced to OCCT
+via `meta.backend` draws its facet corner edges as B-rep feature lines. The
+hint is honored on the Manifold path, which is where lofts preview by default.
+
+`label()`ing a compound solid (one spanning more than one original surface)
+collapses it to a single shading surface that inherits the majority policy of
+its registered constituent surfaces, weighted by triangle count. A constituent
+with no registered policy of its own (e.g. a plain boolean tool) still votes,
+as SMOOTH — the policy it actually renders with — and an exact tie resolves to
+the no-lines (faceted) policy.
+
 **Selectors** (`fillet`/`chamfer` `edges` selector, `shell` `open` face selector) are
 declarative objects, criteria AND-combined:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.44.0",
+  "version": "0.46.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",
@@ -100,7 +100,7 @@
     "@fontsource-variable/geist-mono": "^5.3.0",
     "happy-dom": "^20.10.6",
     "playwright": "^1.49.0",
-    "typescript": "^7.0.2",
+    "typescript": "^5.9.3",
     "vite": "^8.0.16",
     "vitest": "^4.1.9"
   }

package/src/framework/animation-controls.js

@@ -112,6 +112,11 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
   // propagate would take the other listeners down with it. Warn once, then
   // stay quiet so a bad frame can't flood the console 60x a second.
   let frameFailureWarned = false;
+  function warnFrameFailure(err) {
+    if (frameFailureWarned) return;
+    frameFailureWarned = true;
+    console.warn("partforge: animation frame failed", err);
+  }
   function apply(r) {
     if (!r) return;
     try {
@@ -124,18 +129,24 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
           duration: tweenDuration,
           // An intro cue gates playback until the tween settles; mid-timeline
           // cues overlap playback and need no completion signal.
-          onComplete: r.status === "intro" ? () => apply(playback.introDone()) : undefined,
+          onComplete: r.status === "intro" ? () => guarded(() => playback.introDone()) : undefined,
         });
       }
       syncUi();
     } catch (err) {
-      if (!frameFailureWarned) {
-        frameFailureWarned = true;
-        console.warn("partforge: animation frame failed", err);
-      }
+      warnFrameFailure(err);
     }
   }
 
+  // Every transport entry point goes through here so the STATE-MACHINE call is
+  // inside the guard too, not just apply(). playback.tick() is evaluated in the
+  // render loop, and three re-arms requestAnimationFrame only after the frame
+  // callback returns — a throw escaping from there stops the rAF chain and
+  // freezes the viewer permanently instead of costing one frame.
+  function guarded(produce) {
+    try { apply(produce()); } catch (err) { warnFrameFailure(err); }
+  }
+
   function doReset() {
     playback.reset();
     viewer.cancelCameraTween();
@@ -154,14 +165,14 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
     syncUi();
   }
 
-  const offFrame = viewer.onFrame((dt) => apply(playback.tick(dt)));
+  const offFrame = viewer.onFrame((dt) => guarded(() => playback.tick(dt)));
   // User orbit: the viewer has already cancelled any cue tween (its own
   // "start" handler); disarm the remaining cues, and if an intro tween was
   // gating playback, settle the gate — cancel() never fires onComplete, so
   // without this the machine would sit in "intro" forever.
   const offOrbit = viewer.onCameraStart(() => {
     playback.disarmCues();
-    if (playback.state().status === "intro") apply(playback.introDone());
+    if (playback.state().status === "intro") guarded(() => playback.introDone());
   });
 
   const onPlayClick = () => {
@@ -169,14 +180,14 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
     const active = playback.state().status;
     if (active === "playing" || active === "intro") {
       viewer.cancelCameraTween();
-      apply(playback.pause());
+      guarded(() => playback.pause());
     } else {
-      apply(playback.play());
+      guarded(() => playback.play());
     }
   };
-  const onScrub = () => { disarmAutoplay(); apply(playback.seek(Number(scrub.value) / 1000)); };
-  const onPrev = () => { disarmAutoplay(); apply(playback.stepPrev()); };
-  const onNext = () => { disarmAutoplay(); apply(playback.stepNext()); };
+  const onScrub = () => { disarmAutoplay(); guarded(() => playback.seek(Number(scrub.value) / 1000)); };
+  const onPrev = () => { disarmAutoplay(); guarded(() => playback.stepPrev()); };
+  const onNext = () => { disarmAutoplay(); guarded(() => playback.stepNext()); };
   const onPick = () => { disarmAutoplay(); selectAnimation(pick.value); };
   const onResetClick = () => { disarmAutoplay(); doReset(); };
   playBtn.addEventListener("click", onPlayClick);
@@ -200,10 +211,10 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
         return;
       }
       if (name) selectAnimation(name);
-      apply(playback.play());
+      guarded(() => playback.play());
     },
-    pause() { disarmAutoplay(); viewer.cancelCameraTween(); apply(playback.pause()); },
-    seek(t) { disarmAutoplay(); apply(playback.seek(t)); },
+    pause() { disarmAutoplay(); viewer.cancelCameraTween(); guarded(() => playback.pause()); },
+    seek(t) { disarmAutoplay(); guarded(() => playback.seek(t)); },
     stop() { disarmAutoplay(); doReset(); },
     state: () => ({ animation: current.name, ...playback.state() }),
   };
@@ -223,7 +234,7 @@ export function attachAnimationControls(viewer, part, { container, applyValues,
       if (!autoplayArmed || !autoplayAnim) return;
       if (current !== autoplayAnim) selectAnimation(autoplayAnim.name);
       const { status } = playback.state();
-      if (status !== "playing" && status !== "intro") apply(playback.play());
+      if (status !== "playing" && status !== "intro") guarded(() => playback.play());
     },
     detach() {
       offFrame();

package/src/framework/animation.js

@@ -13,6 +13,32 @@ export const EASINGS = {
 };
 export const DEFAULT_EASING = "ease-in-out";
 
+// Look easings up by OWN key only. `EASINGS[name]` / `name in EASINGS` would walk
+// the prototype chain, so "toString" resolves to a function that silently returns
+// garbage and "__proto__" resolves to a non-function that throws — mid-frame, from
+// inside the render loop. Lint applies the same test, so an unknown easing is an
+// authoring error there and a quiet fall back to the default here.
+export const easingFor = (name) =>
+  (Object.hasOwn(EASINGS, name) ? EASINGS[name] : EASINGS[DEFAULT_EASING]);
+
+// A track value has to be a non-empty keyframe array to be evaluable. Lint reports
+// anything else as `animation-keyframes-invalid`; this predicate is what keeps the
+// runtime total when a part reaches it unlinted, and it must stay the single rule
+// both segmentsFor and trackedKeys agree on — if they disagree, evaluate() is asked
+// for a key that has no segment and throws.
+const usableKeyframes = (kf) => Array.isArray(kf) && kf.length > 0;
+
+// t is clamped to [0,1]. Only an unorderable t (NaN, or anything that coerces to
+// it, such as a host calling seek() with no argument) folds to 0 — ±Infinity is
+// ordered and clamps normally. NaN has to be caught rather than clamped because
+// it fails every comparison: `Math.min(1, Math.max(0, NaN))` is still NaN, and an
+// unclamped NaN leaves `t >= 1` permanently false, so playback could never reach
+// `done` and every later cue test would silently fail.
+const clampT = (t) => {
+  const n = Number(t);
+  return Number.isNaN(n) ? 0 : Math.min(1, Math.max(0, n));
+};
+
 // Normalize one animations-map entry to the canonical shape every consumer
 // (playback, transport UI, lint, CLI) works against: a step list (a bare
 // `tracks` form becomes one anonymous step), normalized step starts, and the
@@ -39,10 +65,18 @@ export function normalizeAnimation(name, spec) {
   if (typeof spec.camera === "string") cues = [{ t: 0, view: spec.camera }];
   else if (Array.isArray(spec.camera)) cues = spec.camera.map(([t, view]) => ({ t, view }));
   else cues = steps.flatMap((s, i) => (s.camera ? [{ t: stepStarts[i], view: s.camera }] : []));
-  const trackedKeys = [...new Set(steps.flatMap((s) => Object.keys(s.tracks)))];
+  const trackedKeys = [...new Set(steps.flatMap((s) =>
+    Object.entries(s.tracks).filter(([, kf]) => usableKeyframes(kf)).map(([key]) => key)))];
   return {
     name, label: spec.label ?? name, description: spec.description ?? null,
-    loop: !!spec.loop, autoplay: !!spec.autoplay, steps, stepStarts, totalDuration, cues, trackedKeys,
+    // Fail CLOSED on both flags: only a literal `true` turns them on. Coercing
+    // with `!!` reads `loop: "false"` as "loop forever", which is the worst
+    // available reading of that typo, and nothing downstream would catch it —
+    // lint reports non-booleans, but a part can mount in a browser without ever
+    // having been linted. An invalid flag therefore does the quiet thing here and
+    // is reported there.
+    loop: spec.loop === true, autoplay: spec.autoplay === true,
+    steps, stepStarts, totalDuration, cues, trackedKeys,
   };
 }
 
@@ -52,7 +86,7 @@ export function normalizeAnimations(part) {
 
 // Step containing t. Boundaries belong to the LATER step, and t clamps to [0,1].
 export function stepIndexAt(anim, t) {
-  const tc = Math.min(1, Math.max(0, t));
+  const tc = clampT(t);
   let idx = 0;
   for (let i = 0; i < anim.stepStarts.length; i++) if (tc >= anim.stepStarts[i]) idx = i;
   return idx;
@@ -71,7 +105,7 @@ function segmentsFor(anim, key) {
   const out = [];
   anim.steps.forEach((step, i) => {
     const kf = step.tracks[key];
-    if (!kf) return;
+    if (!usableKeyframes(kf)) return;
     const start = anim.stepStarts[i];
     const end = i + 1 < anim.steps.length ? anim.stepStarts[i + 1] : 1;
     out.push({ start, end, keyframes: kf, easing: step.easing });
@@ -94,12 +128,16 @@ function interpKeyframes(kf, u) {
 
 function evaluateTrack(anim, key, t) {
   const segs = segmentsFor(anim, key);
+  // trackedKeys and segmentsFor share usableKeyframes, so a tracked key always
+  // has a segment. Guard anyway: this runs inside the render loop, where a throw
+  // costs the whole viewer, not just the frame.
+  if (!segs.length) return undefined;
   let prev = null;
   for (const seg of segs) {
     if (t < seg.start) break;
     if (t <= seg.end) {
       const span = seg.end - seg.start || 1;
-      const local = (EASINGS[seg.easing] ?? EASINGS[DEFAULT_EASING])((t - seg.start) / span);
+      const local = easingFor(seg.easing)((t - seg.start) / span);
       return interpKeyframes(seg.keyframes, local);
     }
     prev = seg;
@@ -112,7 +150,7 @@ function evaluateTrack(anim, key, t) {
 // Evaluate the whole animation at normalized position t ∈ [0,1] (over the
 // TOTAL duration — the same t the scrubber, seek(t), and the CLI's --at use).
 export function evaluate(anim, t) {
-  const tc = Math.min(1, Math.max(0, t));
+  const tc = clampT(t);
   const values = {};
   for (const key of anim.trackedKeys) values[key] = evaluateTrack(anim, key, tc);
   return { stepIndex: stepIndexAt(anim, tc), values };
@@ -131,6 +169,7 @@ export function createPlayback(anim) {
   let t = 0;
   let armed = true;       // user orbit disarms cues until reset/replay
   let firedCueT = -1;     // cues with t <= firedCueT already fired this run
+  let pendingCueT = null; // cue handed to an in-flight intro tween, not yet settled
   let stopAt = null;      // stepNext/playStep pause playback on reaching this t
 
   const snapshot = (cue = null) => ({ t, status, ...evaluate(anim, t), cue });
@@ -144,7 +183,11 @@ export function createPlayback(anim) {
 
   function begin() {
     const cue = governingCue();
-    if (cue) { firedCueT = Math.max(firedCueT, cue.t); status = "intro"; }
+    // The cue is NOT counted as fired yet — only introDone() retires it. Pausing
+    // mid-intro cancels the tween and drops its completion callback, so a cue
+    // retired here would never be re-issued on resume and the camera would stay
+    // stranded wherever the cancelled sweep left it.
+    if (cue) { pendingCueT = cue.t; status = "intro"; }
     else status = "playing";
     return snapshot(cue);
   }
@@ -157,17 +200,23 @@ export function createPlayback(anim) {
   }
   function pause() {
     if (status === "playing" || status === "intro") status = "paused";
+    pendingCueT = null; // an unsettled intro cue is abandoned, so resume re-issues it
     return snapshot();
   }
   function introDone() {
-    if (status === "intro") status = "playing";
+    if (status === "intro") {
+      if (pendingCueT != null) firedCueT = Math.max(firedCueT, pendingCueT);
+      status = "playing";
+    }
+    pendingCueT = null;
     return snapshot();
   }
   function seek(v) {
-    t = Math.min(1, Math.max(0, v));
+    t = clampT(v);
     status = "paused";
     stopAt = null;
     firedCueT = -1; // a later play() re-honors the cue governing the new position
+    pendingCueT = null;
     return snapshot();
   }
   function playStep(i) {
@@ -175,6 +224,7 @@ export function createPlayback(anim) {
     t = anim.stepStarts[idx];
     stopAt = idx + 1 < anim.steps.length ? anim.stepStarts[idx + 1] : 1;
     firedCueT = -1;
+    pendingCueT = null;
     return begin();
   }
   function stepNext() {
@@ -185,7 +235,7 @@ export function createPlayback(anim) {
     return playStep(Math.max(0, stepIndexAt(anim, t) - 1));
   }
   function reset() {
-    t = 0; status = "idle"; stopAt = null; firedCueT = -1; armed = true;
+    t = 0; status = "idle"; stopAt = null; firedCueT = -1; pendingCueT = null; armed = true;
     return snapshot();
   }
   function disarmCues() { armed = false; }
@@ -194,10 +244,14 @@ export function createPlayback(anim) {
   function tick(dt) {
     if (status !== "playing" || !(dt > 0)) return null;
     t += dt / anim.totalDuration;
-    if (anim.loop) {
-      if (t >= 1) t -= Math.floor(t);
-    } else if (stopAt != null && t >= stopAt) {
+    // A pending step boundary outranks looping. Lint rejects loop on a stepped
+    // animation, so the two rarely coexist — but when they do, an explicit
+    // "play this step" must still stop where it was told to, rather than being
+    // swallowed by the wrap and running forever.
+    if (stopAt != null && t >= stopAt) {
       t = stopAt; stopAt = null; status = "paused";
+    } else if (anim.loop) {
+      if (t >= 1) t -= Math.floor(t);
     } else if (t >= 1) {
       t = 1; status = "done";
     }

package/src/framework/capture-build.js

@@ -0,0 +1,59 @@
+// Correlated one-shot geometry builds for captureView — a private channel that
+// does NOT go through the regen loop. Same shape as export-controller's pending
+// Map (export-controller.js): allocate a jobId, resolve when the matching
+// reply arrives. Pure — no DOM, no worker; `send` is injected.
+export function createCaptureBuild({ send }) {
+  let nextId = 1;
+  let disposed = false;
+  const pending = new Map(); // jobId -> resolve
+
+  function request({ subparts, view, params, backend }) {
+    // After teardown the workers are gone, so a fresh send would post to a terminated
+    // worker (a silent no-op) and its promise would hang forever. Resolve null instead
+    // — captureView's documented "disposed runtime resolves null" contract.
+    if (disposed) return Promise.resolve(null);
+    // String-namespaced ("cap-N") so a capture jobId can never collide with
+    // export-controller's numeric jobIds — both share the same worker message
+    // space, and exportCtl.handleMessage does a raw pending.get(m.jobId) before
+    // checking type, so a colliding id could otherwise settle the wrong promise.
+    const jobId = `cap-${nextId++}`;
+    return new Promise((resolve) => {
+      pending.set(jobId, resolve);
+      // cache:true so the worker reuses its per-sub-part geometry memo (the
+      // expensive CSG); only the per-view place() + meshing re-run.
+      send({ type: "capture-generate", jobId, subparts, view, params, cache: true }, backend);
+    });
+  }
+
+  // Returns true iff this message was a reply this controller owns (so the
+  // caller — mount.js's onWorkerMessage — can skip it entirely). Keyed on
+  // membership in `pending` first: the namespaced jobId guarantees another
+  // channel's message never matches, so a hit here is always ours. A failed
+  // build (the worker's shared catch posts a generic error/needs-occt, jobId
+  // intact) resolves to null rather than leaving the caller hanging forever —
+  // captureView treats null as "capture failed, skip".
+  function handleMessage(data) {
+    const jobId = data?.jobId;
+    if (jobId == null || !pending.has(jobId)) return false;
+    if (data.type === "capture-meshes") {
+      pending.get(jobId)(data.meshes);
+    } else if (data.type === "error" || data.type === "needs-occt") {
+      pending.get(jobId)(null);
+    } else {
+      return false;
+    }
+    pending.delete(jobId);
+    return true;
+  }
+
+  // Teardown / worker death: settle every in-flight request to null instead
+  // of leaving its promise permanently pending (a caller awaiting captureView
+  // across a viewer dispose must still get an answer, even a negative one).
+  function dispose() {
+    disposed = true;
+    for (const resolve of pending.values()) resolve(null);
+    pending.clear();
+  }
+
+  return { request, handleMessage, dispose };
+}