partforge 0.41.0 → 0.45.0

package/README.md

@@ -103,7 +103,7 @@ const runtime = mount(part, {
     status: { status, busy, phase },        // status chrome
     tabs,                                   // view-tab segmented control
     exports: { stl, step, threeMf },        // export buttons
-    chrome: { pause, reframe, theme, railToggle }, // viewer buttons + rail collapse/restore
+    chrome: { reframe, theme, railToggle }, // viewer buttons + rail collapse/restore
   },
   onBuild: ({ status, ms, error }) => {},   // per accepted build: "success" | "error"
   onPick: ({ selection, label, prompt, token }) => {}, // programmatic click-to-select
@@ -122,10 +122,12 @@ runtime.dispose();     // stops loops, workers, observers, listeners; frees GPU
 `display: none` needs nothing — the container collapses and the ResizeObserver
 shrinks the drawing buffer for free. A host that hides it any other way
 (`visibility: hidden`, an inactive tab, an off-screen pane) gets no such signal:
-the full-resolution MSAA buffer stays resident and the render loop keeps drawing
-an auto-rotating scene at 60fps that nobody can see. On a phone that is tens of
-megabytes plus continuous GPU work, and it has been enough on its own to get a
-tab killed. Call `runtime.setActive(false)` when the viewer goes off-screen and
+the full-resolution MSAA buffer stays resident and the render loop keeps
+redrawing an unchanging scene at 60fps that nobody can see (a part with an
+`autoplay` animation running is the same story, just with something actually
+moving off-screen). On a phone that is tens of megabytes plus continuous GPU
+work, and it has been enough on its own to get a tab killed. Call
+`runtime.setActive(false)` when the viewer goes off-screen and
 `setActive(true)` when it comes back.
 
 Parking releases both large GPU allocations — the drawing buffer and the cached
@@ -137,9 +139,8 @@ first capture after parking just re-allocates its target.
 Every `elements` entry defaults to the legacy global ID (`#app`, `#controls`,
 `#panel` for `rail`, `#status`/`#busy`/`#phase`, `#part`,
 `#download`/`#download-step`/`#download-3mf`,
-`#pause`/`#reframe`/`#theme`/`#rail-toggle`), so a classic host page needs no
-changes. The viewer sizes from its container via ResizeObserver — no window
-coupling.
+`#reframe`/`#theme`/`#rail-toggle`), so a classic host page needs no changes.
+The viewer sizes from its container via ResizeObserver — no window coupling.
 
 `rail` is the full-height controls rail introduced by the resizable-panel
 layout (`docs/superpowers/specs/2026-07-26-controls-rail-layout-design.md`);
@@ -164,6 +165,25 @@ viewer re-poses the meshes it already has — instantly, with no worker rebuild;
 `onBuild` does not fire for those pose-only edits. Anything that changes the
 geometry itself rebuilds as usual.
 
+For parts that declare `animations`, `runtime.animation` exposes the viewer's
+playback engine (`null` otherwise):
+
+```js
+runtime.animation.play("open");   // switch + play (camera cue and all)
+runtime.animation.seek(0.5);      // scrub, normalized 0..1 (pauses)
+runtime.animation.pause();
+runtime.animation.stop();         // reset + restore pre-animation params
+runtime.animation.state();        // { animation, status, t, stepIndex }
+```
+
+A part can mark at most one animation `autoplay: true` to start it
+automatically on first show and again on every view switch — until the user
+touches the transport — or anything writes params (`runtime.setParams`
+included) or calls a `runtime.animation` method; any of those disarms
+auto-start for the session. This replaces the old idle turntable as the
+"something is moving" cue for a part-app; see the authoring guide for the
+full contract.
+
 `onPick` arms click-to-select permanently: `label` is the feature label (falling
 back to the sub-part label/name) for compact UI, `prompt` is the LLM-ready
 sentence, `token` the compact form, `selection` the raw object. When `onPick` is
@@ -182,8 +202,9 @@ internal params, and keep the interface simple while staying deeply adjustable.
 Locally, `npm run dev` then open `/demo.html`, `/planter.html`, or `/filleted-box.html`.
 
 - **Agent clarification (`request-a-pick`):** an external tool can ask the user to click
-  geometry and get the `Selection` back — serve with `?pickserver`, drive with
-  `partforge pick-serve` + `partforge pick "<prompt>" …`. See
+  geometry and get the `Selection` back — serve with `?pickserver&picktoken=<token>`,
+  drive with `partforge pick-serve` (it prints the token) + `partforge pick "<prompt>" …`.
+  The server is loopback-only and token-gated on every route. See
   `skills/partforge/SKILL.md` and the authoring guide.
 
 ## License

package/bin/cli.js

@@ -7,13 +7,18 @@ import { parseArgs } from "node:util";
 import { pathToFileURL } from "node:url";
 import { resolve, dirname } from "node:path";
 import { writeFileSync, mkdirSync } from "node:fs";
-import { detectBackend } from "../src/framework/geometry/probe.js";
+import { detectBackend } from "../src/framework/backend-select.js";
+import { normalizeAnimation, evaluate, cueAt } from "../src/framework/animation.js";
 import { bootOcctKernel } from "../src/testing/occt.js";
 import { bootManifoldKernel } from "../src/testing/manifold.js";
-import { measure } from "../src/testing/measure.js";
-import { verify } from "../src/testing/verify.js";
+import { measure } from "../src/framework/oracle/measure.js";
+import { verify } from "../src/framework/oracle/verify.js";
 import { renderViews } from "../src/testing/render.js";
-import { createPickServer, requestPicks, formatPickResult } from "../src/framework/pick-request/server.js";
+import {
+  createPickServer, requestPicks, formatPickResult,
+  PICK_SERVER_DEFAULT_PORT, PICK_SERVER_DEFAULT_TIMEOUT_MS,
+} from "../src/framework/pick-request/server.js";
+import { savePickToken, loadPickToken, clearPickToken, pickTokenPath } from "../src/framework/pick-request/token-store.js";
 import { matchPattern } from "../src/testing/error-patterns.js";
 import { lintPart } from "../src/lint.js";
 
@@ -22,12 +27,13 @@ const USAGE = "usage: partforge <lint|measure|render|pick-serve|pick> …";
 
 // Crash contract (issue #27): with --json, a thrown error becomes structured
 // stdout JSON; either way the message is matched against ERROR-PATTERNS.md and
-// the pattern's fix is surfaced. Exit 1 always. NOTE on stdout purity: crash
-// JSON is the only thing on stdout for errors thrown before any report printing
-// (load/boot/measure). But verify() runs after printMeasure and can throw (an
-// unknown metric in verify.expect, or a per-case build crash), so a throw after
-// printing appends the JSON after the human lines — it is not pure. Consumers
-// should prefer --out for robust machine parsing.
+// the pattern's fix is surfaced. Exit 1 always. NOTE on stdout purity: in --json
+// mode every human-readable printer (printLint/printMeasure/printVerify) is
+// gated behind `!flags.json`, so crash JSON is the only thing that ever reaches
+// stdout — including when verify() throws (an unknown metric in verify.expect,
+// or a per-case build crash) after measure's report has already been computed.
+// Without --json there is no purity contract: human lines print as each stage
+// completes, so a later crash's message lands after them, not instead of them.
 function crash(cmd, e, jsonMode) {
   const message = e?.message || String(e);
   const m = matchPattern(message);
@@ -113,7 +119,7 @@ const commands = {
       }
       const kernel = await bootKernel(part);
       const report = measure(kernel, part, view);
-      printMeasure(report);
+      if (!flags.json) printMeasure(report);
       // Write --out right after measure succeeds, then re-write once verify has
       // attached report.verify. If verify throws (unknown metric, per-case build
       // crash) the file already holds the measure half (no `verify` key) — matching
@@ -126,7 +132,7 @@ const commands = {
       let vok = true;
       if ((part.verify || flags.process) && !flags["no-verify"]) {
         const v = verify(kernel, part, { process: flags.process, view });
-        printVerify(v);
+        if (!flags.json) printVerify(v);
         report.verify = v;
         vok = v.ok;
         if (flags.out) writeOut();
@@ -140,17 +146,109 @@ const commands = {
   },
 
   async render(args) {
-    const usage = "usage: partforge render <part-module> [view] [--views iso,front] [--out <dir>]";
+    const usage = "usage: partforge render <part-module> [view] [--views iso,front] [--out <dir>] " +
+      "[--params <json>] [--animation <name>] [--at <t[,t…]>] [--step <index|label>]";
     const { values: flags, positionals: [partPath, view] } = parse(args, {
       views: { type: "string" },
       out: { type: "string" },
+      params: { type: "string" },
+      animation: { type: "string" },
+      at: { type: "string" },
+      step: { type: "string" },
     }, usage);
     try {
       const part = await loadPart(partPath, usage);
-      const kernel = await bootKernel(part);
+      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;
-      const files = await renderViews(kernel, part, view, { views, out: flags.out || "render" });
-      for (const f of files) console.log(`wrote ${f}`);
+      // 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 === 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);
+      }
+
+      const spec = part.animations?.[flags.animation];
+      if (!spec) {
+        throw new Error(`unknown animation "${flags.animation}" (have: ${Object.keys(part.animations ?? {}).join(", ") || "none"})`);
+      }
+      const anim = normalizeAnimation(flags.animation, spec);
+      // Frames: --step renders one still at the END of that step (its fully
+      // applied state); --at takes positions normalized over the animation's
+      // TOTAL duration (same t as the viewer scrubber / runtime seek).
+      let frames;
+      if (flags.step != null) {
+        const byLabel = anim.steps.findIndex((s) => s.label === flags.step);
+        const idx = byLabel >= 0 ? byLabel : Number(flags.step) - 1;
+        if (!(idx >= 0 && idx < anim.steps.length)) {
+          throw new Error(`unknown step "${flags.step}" (use 1..${anim.steps.length} or a label: ${anim.steps.map((s) => JSON.stringify(s.label)).join(", ")})`);
+        }
+        const end = idx + 1 < anim.steps.length ? anim.stepStarts[idx + 1] : 1;
+        // Values come from the END of the step (fully applied), but the cue
+        // lookup uses the step's own START: cue boundaries belong to the LATER
+        // step (see animation.js stepIndexAt/cueAt), and `end` here IS the next
+        // step's start, so querying the cue at `end` would resolve to the next
+        // step's camera instead of this step's own.
+        frames = [{ t: end, cueT: anim.stepStarts[idx], tag: `${flags.animation}-step${idx + 1}` }];
+      } else {
+        // 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}`);
+        }
+        // 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);
+        const cue = cueAt(anim, frame.cueT ?? frame.t);
+        const frameViews = views ?? (cue ? [cue.view] : undefined);
+        const files = await renderViews(kernel, part, view, {
+          views: frameViews, out: outDir, params: { ...baseParams, ...values }, tag: frame.tag,
+        });
+        for (const f of files) console.log(`wrote ${f}`);
+      }
       process.exit(0);
     } catch (e) {
       crash("render", e, false);
@@ -160,19 +258,31 @@ const commands = {
   async "pick-serve"(args) {
     const usage = "usage: partforge pick-serve [--port N] [--timeout <seconds>]";
     const { values: flags } = parse(args, { port: { type: "string" }, timeout: { type: "string" } }, usage);
-    const port = Number(flags.port) || 4518;
-    const timeoutMs = (Number(flags.timeout) || 120) * 1000;
-    const { port: bound } = await createPickServer({ port, timeoutMs }).start();
+    const port = Number(flags.port) || PICK_SERVER_DEFAULT_PORT;
+    const timeoutMs = (Number(flags.timeout) || PICK_SERVER_DEFAULT_TIMEOUT_MS / 1000) * 1000;
+    const srv = createPickServer({ port, timeoutMs });
+    const { port: bound } = await srv.start();
+    // The token is what keeps every other page on the machine out of this server.
+    // `partforge pick` runs in a different process, so drop it in a 0600 file for
+    // that process to find; the browser gets it through the app URL below.
+    savePickToken(bound, srv.token);
+    const stop = () => { clearPickToken(bound); process.exit(0); };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
     console.log(`partforge pick-server listening on http://127.0.0.1:${bound}`);
+    console.log(`token: ${srv.token}  (also at ${pickTokenPath(bound)})`);
+    console.log(`open the app with: ?pickserver=http://127.0.0.1:${bound}&picktoken=${srv.token}`);
     // no exit — the process stays alive serving requests
   },
 
   async pick(args) {
-    const usage = 'usage: partforge pick "<prompt>" ["<prompt>" …] [--port N]';
-    const { values: flags, positionals: prompts } = parse(args, { port: { type: "string" } }, usage);
+    const usage = 'usage: partforge pick "<prompt>" ["<prompt>" …] [--port N] [--token T]';
+    const { values: flags, positionals: prompts } = parse(args, { port: { type: "string" }, token: { type: "string" } }, usage);
     if (prompts.length === 0) die(usage);
-    const port = Number(flags.port) || 4518;
-    const out = await requestPicks({ port, prompts }).catch((e) => die(e.message));
+    const port = Number(flags.port) || PICK_SERVER_DEFAULT_PORT;
+    const token = flags.token || process.env.PARTFORGE_PICK_TOKEN || loadPickToken(port);
+    if (!token) die(`no pick-server token for port ${port} — start one with \`partforge pick-serve\`, or pass --token`);
+    const out = await requestPicks({ port, prompts, token }).catch((e) => die(e.message));
     console.log(formatPickResult(out));
     process.exit(out.status === "done" ? 0 : 1);
   },
@@ -218,16 +328,17 @@ function printVerify(v) {
 }
 
 function printLint(r) {
-  const all = [...r.errors, ...r.warnings];
+  const all = [...r.errors, ...r.warnings, ...(r.notes ?? [])];
   if (all.length === 0) { console.log("lint: clean"); return; }
   console.log("lint:");
   for (const f of all) {
-    console.log(`  ${f.severity === "error" ? "✗" : "⚠"} ${f.rule}${f.path ? `  ${f.path}` : ""}`);
+    const icon = f.severity === "error" ? "✗" : f.severity === "warning" ? "⚠" : "·";
+    console.log(`  ${icon} ${f.rule}${f.path ? `  ${f.path}` : ""}`);
     console.log(`      ${f.message}`);
     console.log(`      hint: ${f.hint}${f.pattern ? ` (ERROR-PATTERNS.md#${f.pattern})` : ""}`);
   }
-  const e = r.errors.length, w = r.warnings.length;
-  console.log(`  result: ${e ? `${e} error(s)` : "no errors"}${w ? `, ${w} warning(s)` : ""}`);
+  const e = r.errors.length, w = r.warnings.length, n = (r.notes ?? []).length;
+  console.log(`  result: ${e ? `${e} error(s)` : "no errors"}${w ? `, ${w} warning(s)` : ""}${n ? `, ${n} note(s)` : ""}`);
 }
 
 const [, , cmd, ...args] = process.argv;

package/docs/AUTHORING-PARTS.md

@@ -85,7 +85,7 @@ export default {
       export?: { name },                   // filename/object name on export; defaults to the key
     },
   },
-  views: { <name>: { label } },            // the view tabs (a view = a set of sub-parts)
+  views: { <name>: { label, default? } },  // the view tabs (a view = a set of sub-parts)
 };
 ```
 
@@ -111,6 +111,14 @@ export default {
 - `enabled(p)` gates a conditional sub-part (e.g. only present when a feature is on).
 - A view's sub-parts are derived, never hard-coded: those whose `views` include the view
   and whose `enabled(p)` is true.
+- **Which view the viewer opens on** is resolved in this order: the first view flagged
+  `default: true`; else the view placing the most sub-parts at `defaults` (counting
+  `enabled(defaults)`), which for a multi-view part is normally the assembly; else the
+  first key in `views`. So flag the assembly view `default: true` when you want it to
+  open but sit last in the tab bar. The chosen tab then persists per part for the rest
+  of the browser session. The headless tools are deliberately different: `measure`,
+  `verify` and `render` all default to the **first key** in `views`, ignoring
+  `default: true`, so a CI gate can't move because a sub-part was added to a view.
 - `fonts` declares the outline fonts a part's `k.text2d()` calls need, as `{ name: source
   }` — a source is inline bytes, a URL string, or a thunk (e.g. a Vite `import('./x.ttf')`,
   which resolves to `{ default: url }`). The framework resolves and parses these into
@@ -121,6 +129,83 @@ export default {
 
 ---
 
+## Animations
+
+A part may declare named animations — pure keyframe data that drives **existing
+params** over time. The viewer shows a transport bar (play/scrub/step); hosts
+drive the same engine via `runtime.animation`; `partforge render` can render
+stills at any position. The reference part is `src/parts/hinged-box.js`.
+
+```js
+animations: {
+  open: {
+    label: "Open lid",
+    description: "Optional **CommonMark**, shown behind the ⓘ glyph.",
+    camera: "front",          // optional: intro angle, cue list, or per-step (below)
+    duration: 1.2,            // seconds
+    loop: false,              // true = wraps continuously (single-step only)
+    easing: "ease-in-out",    // linear | ease-in | ease-out | ease-in-out
+    tracks: { lidAngle: [[0, 0], [1, 110]] },   // param -> [t, value] keyframes
+  },
+  assemble: {
+    label: "Assemble",
+    steps: [                  // steps play in order; prev/next navigate them
+      { label: "Lower the lid", camera: "left", duration: 1.0,
+        tracks: { lidLift: [[0, 40], [1, 0]] } },
+      { label: "Open", camera: "iso", duration: 1.0,
+        tracks: { lidAngle: [[0, 0], [1, 110]] } },
+    ],
+  },
+}
+```
+
+Rules (all lint-enforced):
+
+- An animation has **either** `tracks` (a single anonymous step) **or** `steps`.
+- Tracks reference numeric params from `defaults`. Keyframe `t` is normalized
+  per step, strictly ascending from exactly 0 to exactly 1; values must sit
+  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
+  left right`). One mechanism per animation: an animation-level name (an intro
+  cue at t=0), an animation-level `[[t, angle], …]` list, or per-step names.
+  Cues fire during play only — scrubbing never moves the camera — and a user
+  orbit disarms the remaining cues for that run.
+- Playback drives params through the real param pipeline: a **pose-only**
+  param (feeds only rigid placement — see "Caching & determinism" below) plays
+  at frame rate; anything else rebuilds best-effort at worker cadence. `lint`
+  prints a note per track that can't take the fast path.
+- Playback pauses when the user edits any control; Reset restores the values
+  the animation found. Because animated values are real params, exporting
+  while paused exports the posed state — by design.
+- `autoplay: true` (optional, one animation at most) starts that animation on
+  first show and again on each view switch, until the user touches the
+  transport — or anything writes params (`runtime.setParams` included) or
+  calls a `runtime.animation` method; any of those disarms auto-start for the
+  session. Lint: `animation-autoplay-invalid`. It is not armed when the
+  browser reports `prefers-reduced-motion: reduce` — self-starting motion is
+  exactly what that setting asks a page not to do. An autoplay animation that
+  declares a `camera` cue will sweep the camera away from the user's
+  persisted framing on every page load, so choose cues for autoplay
+  deliberately — the shipped example's `cycle` animation has none.
+
+Headless: `partforge render <part> --animation open --at 0,0.5,1` renders
+tagged stills (`--at` is normalized over the animation's total duration, like
+the scrubber); `--step <index|label>` renders a step's end state; stills
+default to the governing camera cue's angle.
+
+---
+
 ## Geometry: the kernel / `Solid` API
 
 `build` receives a backend-agnostic `kernel` (`k`). It returns and combines `Solid`
@@ -406,6 +491,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:
@@ -702,17 +793,38 @@ stylesheet). `mount` looks up these element IDs:
 |---|---|
 | `#app` | viewer canvas mounts here |
 | `#controls` | control panel is built into this |
-| `#part` | view-tab bar — leave the div **empty**; `mount` generates one button per entry in `part.views` |
+| `#part` | view-tab bar — leave the div **empty**; `mount` generates one button per entry in `part.views` and opens the resolved default (see the "Which view the viewer opens on" rule above) |
 | `#download-step` / `#download` / `#download-3mf` | STEP / STL / 3MF export buttons |
 | `#status`, `#busy`, `#phase` | status line + busy overlay |
-| `#viewbar` with `#pause` / `#reframe` / `#cutaway` / `#theme` | optional viewer controls (omit any you don't want) |
+| `#viewbar` with `#reframe` / `#cutaway` / `#theme` | optional viewer controls (omit any you don't want) |
 | `#panel` | the full-height controls rail (`class="pf-rail"`); programmatic hosts pass `elements.rail` instead |
-| `#rail-toggle` | optional — collapses/restores the rail; resolved the same way as `#pause`/`#theme` |
+| `#rail-toggle` | optional — collapses/restores the rail; resolved the same way as `#reframe`/`#theme` |
 
 Copy `demo.html` and change the title, the panel heading, and the `<script src>`. Two
 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()`
@@ -817,7 +929,6 @@ mount(part, {
   elements: {
     rail,
     chrome: {
-      pause,
       reframe,
       cutaway,
       theme,
@@ -1003,11 +1114,13 @@ previously didn't; that's the fix working as intended, not a regression.
 ### Rule catalog
 
 **Definition shape** — `missing-meta-title`, `missing-defaults`, `no-buildable-parts`,
-`missing-views`, `part-view-unknown` (all errors); `view-unused` (warning).
+`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`,
@@ -1020,6 +1133,30 @@ previously didn't; that's the fix working as intended, not a regression.
 `contacts` / `clearance` keys, which are not scalar view metrics; they are
 validated by `verify-bad-pair-check`, matching `verify.js`'s own handling.
 
+**Animations block** — static validation of `animations`, without executing
+`build`: `animations-not-object`, `animation-tracks-or-steps`,
+`animation-unknown-param`, `animation-param-not-numeric`,
+`animation-keyframes-invalid`, `animation-value-out-of-range`,
+`animation-duration-invalid`, `animation-loop-invalid`,
+`animation-step-label-duplicate`, `animation-easing-unknown`,
+`animation-camera-invalid`, `animation-description-invalid`,
+`animation-autoplay-invalid` (all errors). One
+more rule does execute `build`, geometry-free: `animation-track-rebuilds` probes
+each track's endpoint values and emits a **note** when the animated param feeds
+real geometry (or the probe can't be trusted), because such a track plays
+best-effort rather than at frame rate. Notes are informational — they never
+affect `ok`, `measure`, or `--strict`.
+
+**Place invariants**, found by running the geometry-free pose probe (the same
+one animation's `animation-track-rebuilds` uses) against each sub-part's
+`place()` — `view-dependent-display-place` (display placement must not depend
+on the active view, since display meshes are cached across views) and
+`place-not-rigid` (display vs. export placement may differ only by a rigid
+motion — translate/rotate — never a reshape) (both errors). An untrusted probe
+(a query op or function selector reached during `build`/`place`) proves
+nothing either way and stays silent, matching `animation-track-rebuilds`'s own
+trust handling.
+
 A rule that itself throws yields an `internal-rule-error` **warning** and the run
 continues: `lintPart` never throws and never blocks a part because of a linter bug.
 
@@ -1129,8 +1266,8 @@ verify: {
 **What the profile gives you:** a hard **bed-fit** gate (the view bbox must fit `bed`)
 and a **min-wall** warning. **What `expect` gives you:** per-sub-part assertions on the
 facts `measure` already reports — `holes` (through-bores / genus), `volume`,
-`surfaceArea`, `triangleCount`, `bbox`, `watertight`, `minWall`, `bounds` (per-sub-part
-and aggregate axis-aligned `{min,max}` corner positions — where the geometry sits, vs
+`surfaceArea`, `triangleCount`, `bbox`, `watertight`, `minWall`, `boundsMin` / `boundsMax`
+(the axis-aligned `{min,max}` corner positions — where the geometry sits, vs
 `bbox` which is only its size) and `centerOfMass` (`[x,y,z]`, the volume-weighted
 centroid; `null` for a degenerate/zero-volume sub-part); and `_view` assertions `bbox`,
 `volume`, `overlaps`, `centerOfMass`, `boundsMin`, `boundsMax`, plus the pair-wise
@@ -1367,12 +1504,22 @@ An external tool (e.g. an AI agent editing your part) can ask the *user* to clic
 geometry and receive the `Selection` back, closing the loop in the other direction
 from `?pick`.
 
-- Serve your app with **`?pickserver`** (or `?pickserver=http://host:port`) to enable
-  it. While idle nothing changes; when the local pick-server requests a click, a banner
-  appears ("🤖 Claude needs you to click …") and the picker arms for one click.
-- The agent side runs `partforge pick-serve` once, then `partforge pick "<prompt>" …`
-  for one or more clicks (collected in order, returned together). The CLI blocks until
-  the user clicks, then prints the `Selection`(s) as JSON.
+- Serve your app with **`?pickserver&picktoken=<token>`** (or
+  `?pickserver=http://127.0.0.1:4518&picktoken=<token>`) to enable it. While idle
+  nothing changes; when the local pick-server requests a click, a banner appears
+  ("🤖 Claude needs you to click …") and the picker arms for one click.
+- The agent side runs `partforge pick-serve` once — it prints the token and the exact
+  URL to open — then `partforge pick "<prompt>" …` for one or more clicks (collected in
+  order, returned together). The CLI blocks until the user clicks, then prints the
+  `Selection`(s) as JSON.
+- **The token is required.** Every route on the pick-server (including the SSE stream)
+  is gated by a random per-process token, requests from non-loopback origins are
+  refused, and the server never reflects an arbitrary `Origin`. Without that, any site
+  the user browsed to while the server was running could read the agent's prompts,
+  inject text into the agent's output, or harvest the user's live parameter values.
+  A `?pickserver=` pointing anywhere but loopback is ignored with a console warning.
+  `partforge pick` finds the token automatically via `~/.partforge/pick-<port>.token`;
+  `--token` and `PARTFORGE_PICK_TOKEN` override it.
 
 See the bundled skill `skills/partforge/SKILL.md` for the agent workflow. This is plain
 click-routing — no LLM logic lives in partforge.

package/docs/ERROR-PATTERNS.md

@@ -312,6 +312,12 @@ Variant literals under this entry: `offsetPolygon: delta must be a finite number
 - **Cause:** paper.js returned an unexpected or numerically degenerate path topology for the supplied font outline; the resolver refuses to attach the hole to an arbitrary outer.
 - **Fix:** reduce or normalize degenerate font contours, confirm the correct CFF/TrueType fill rule was selected, and add the glyph as a focused `curve-fill.test.js` regression before changing resolver tolerances.
 
+## animation-plays-choppy
+
+- **Symptom:** An animation stutters or updates a few times a second instead of smoothly; `?debug` shows `rebuilt` counts climbing during playback.
+- **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".
+
 # Hardware library
 
 Reserved for `hardware-*` patterns (issue #30). No entries yet.