partforge 0.41.0 → 0.44.0

package/src/framework/download.js

@@ -1,4 +1,5 @@
 import { zipSync } from "fflate";
+import { safeName } from "./safe-name.js";
 
 // Browser file-download helpers. Pure DOM/Blob utilities with no app state — the
 // worker produces the bytes; these just hand them to the browser as a download.
@@ -23,9 +24,13 @@ export function triggerDownload(data, filename, mime, sink) {
 // Download a set of built parts: a single part downloads directly; multiple parts
 // are bundled into one flat, store-only (level 0) zip named `zipName`. `sink`, if
 // given, is forwarded to triggerDownload so it receives the final bytes.
+//
+// Sub-part names come from the part's `export.name` — untrusted data — and become
+// zip entry names, so they go through safeName(): the zip must stay flat, and an
+// entry like "../evil.stl" would escape the target directory in naive extractors.
 export function downloadParts({ parts, ext, mime }, zipName, sink) {
-  if (parts.length === 1) return triggerDownload(parts[0].data, `${parts[0].name}.${ext}`, mime, sink);
+  if (parts.length === 1) return triggerDownload(parts[0].data, `${safeName(parts[0].name)}.${ext}`, mime, sink);
   const entries = {};
-  for (const p of parts) entries[`${p.name}.${ext}`] = new Uint8Array(p.data);
+  for (const p of parts) entries[`${safeName(p.name)}.${ext}`] = new Uint8Array(p.data);
   triggerDownload(zipSync(entries, { level: 0 }), zipName, "application/zip", sink);
 }

package/src/framework/export-controller.js

@@ -3,6 +3,17 @@
 // replies (progress/download/error) back to the Promise that started them.
 // Pure — no DOM, no worker; `send` and the sink are injected.
 import { triggerDownload, downloadParts } from "./download.js";
+import { safeName } from "./safe-name.js";
+
+// The one place the "which backend does this export format need" policy lives.
+// STEP is always OCCT — only OCCT (OpenCASCADE) emits exact B-rep; Manifold's mesh
+// CSG has no STEP writer. Every other format is free to use whichever backend the
+// caller is already using for preview. Both the UI export buttons (mount.js) and
+// the headless exportParts() API route through this so the rule is never encoded
+// twice.
+export function backendForFormat(format, defaultBackend) {
+  return format === "step" ? "occt" : defaultBackend();
+}
 
 export function createExportController({ send, currentView, title, defaultBackend = () => "manifold", currentParams = () => ({}) }) {
   const pending = new Map(); // jobId -> { resolve, reject, onProgress }
@@ -11,7 +22,7 @@ export function createExportController({ send, currentView, title, defaultBacken
   function exportParts({ parts, format, quality = "print", onProgress } = {}) {
     const jobId = nextId++;
     const type = `export-${format}`;
-    const backend = format === "step" ? "occt" : defaultBackend();
+    const backend = backendForFormat(format, defaultBackend);
     return new Promise((resolve, reject) => {
       pending.set(jobId, { resolve, reject, onProgress });
       send({ type, jobId, parts, view: currentView(), params: currentParams(), name: title(), quality }, backend);
@@ -32,7 +43,7 @@ export function createExportController({ send, currentView, title, defaultBacken
     }
     if (m.type === "download-parts") {
       pending.delete(m.jobId);
-      const zipName = `${title() ?? "parts"}.zip`.toLowerCase().replace(/\s+/g, "-");
+      const zipName = `${safeName(title(), "parts")}.zip`; // title() is the part's meta.title — untrusted
       downloadParts(m, zipName, sink);
       entry.resolve();
       return true;

package/src/framework/geometry/probe.js

@@ -1,7 +1,7 @@
 // Geometry-free build execution. Two consumers share one Proxy implementation:
 //
-//  • createProbeKernel() — records op NAMES so detectBackend() can route a part to
-//    OCCT when it uses fillet/chamfer/shell.
+//  • createProbeKernel() — records op NAMES so ../backend-select.js's
+//    detectBackend() can route a part to OCCT when it uses fillet/chamfer/shell.
 //  • createValidatingProbe() — additionally checks op names against the kernel
 //    contract's op lists and routes options-form calls through the same op-options
 //    normalizers the real backends use, so partforge/lint can catch a bad call in
@@ -14,13 +14,10 @@
 // validating probe DOES need an allowlist, so it takes one from kernel.js's op
 // lists, which test/kernel-contract.test.js pins to both backend implementations.
 import {
-  OCCT_ONLY_OPS, KERNEL_OPS, KERNEL_OPTIONAL_OPS,
+  KERNEL_OPS, KERNEL_OPTIONAL_OPS,
   SOLID_OPS, SOLID_OPTIONAL_OPS, SHAPE2D_OPS,
 } from "./kernel.js";
 import { KERNEL_OP_SPECS, SOLID_OP_SPECS, isPlainOptions } from "./op-options.js";
-import { resolveDerived } from "../derive.js";
-
-const OCCT_ONLY = new Set(OCCT_ONLY_OPS);
 
 // The probe returns ONE chainable handle for every non-query op, so it cannot tell a
 // Solid from a Shape2D — k.box() and k.shape2d() yield the same object. The solid-scope
@@ -145,19 +142,3 @@ export function runValidatingProbe(part, p, d, { maxOps = MAX_PROBE_OPS } = {})
   }
   return { calls: probe.calls, issues: probe.issues, used: probe.used, throws, runaway };
 }
-
-export function detectBackend(part, params = {}) {
-  if (part.meta?.backend) return part.meta.backend;
-  const p = { ...part.defaults, ...params };
-  let d = {};
-  // A throwing derive must not escape here — this runs on the main thread mid
-  // regen (after the busy spinner goes up). Probe with an empty `d`; the worker
-  // build hits the same throw and posts a proper error for the UI.
-  try { d = resolveDerived(part, p); } catch { /* fall through with d = {} */ }
-  const { kernel, used } = createProbeKernel();
-  for (const name of Object.keys(part.parts)) {
-    try { part.parts[name].build(kernel, p, d); } catch { /* probe miss → capability backstop covers it */ }
-  }
-  for (const op of used) if (OCCT_ONLY.has(op)) return "occt";
-  return "manifold";
-}

package/src/framework/jobs.js

@@ -1,45 +1,14 @@
+// The worker's job protocol. The pure part model it runs over — viewSubParts /
+// exportSubParts / resolveParams / buildPosed — lives in part-model.js, a leaf, so
+// the oracle and the collision check can share it without importing this async,
+// kernel-bound module back.
 import { meshTo3MF } from "./geometry/threemf.js";
 import { exportablePartNames } from "./export-select.js";
-import { resolveDerived } from "./derive.js";
 import { resolveFonts } from "./fonts.js";
-import { measure } from "../testing/measure.js";
-import { verify } from "../testing/verify.js";
-
-// Names of the sub-parts a view shows: declared in the view and enabled for these
-// params. Order follows Object.keys(part.parts) (definition order).
-export function viewSubParts(part, view, params) {
-  return Object.keys(part.parts).filter((name) => {
-    const sp = part.parts[name];
-    const inView = sp.views.includes(view);
-    const on = sp.enabled ? !!sp.enabled(params) : true;
-    return inView && on;
-  });
-}
-
-// Sub-parts to include in an EXPORT of this view: the visible sub-parts, minus any
-// flagged `exportable: false` (reference/preview-only parts — motor ghosts, bearing
-// placeholders, etc.). They still show in the viewer; they're just never written to
-// an STL/STEP/3MF file, so the user never has to toggle them off before exporting.
-export function exportSubParts(part, view, params) {
-  return viewSubParts(part, view, params).filter((name) => part.parts[name].exportable !== false);
-}
-
-// Resolve a part's effective params + derived values for a build: the user's params
-// layered over the part defaults, and derive() run once over the result.
-export function resolveParams(part, params) {
-  const p = { ...part.defaults, ...params };
-  return { p, d: resolveDerived(part, p) };
-}
-
-// Build one sub-part and apply its optional place() for the given purpose/view.
-// `p`/`d` come from resolveParams(). This is the SINGLE definition of "a posed
-// sub-part solid" — the worker, the collision check, and the test harness all call
-// it, so display/export poses can never drift between the app and its tests.
-export function buildPosed(kernel, part, name, { purpose, view, p, d, onProgress } = {}) {
-  const sp = part.parts[name];
-  const solid = sp.build(kernel, p, d, onProgress);
-  return sp.place ? sp.place(solid, { view, purpose, p, d }) : solid;
-}
+import { safeName } from "./safe-name.js";
+import { exportSubParts, resolveParams, buildPosed } from "./part-model.js";
+import { measure } from "./oracle/measure.js";
+import { verify } from "./oracle/verify.js";
 
 // Handle one geometry job, posting results/progress via `post(msg, transfer?)`.
 // Backend-agnostic and part-agnostic: every part specific comes through `part`.
@@ -82,7 +51,7 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       msg.parts
         ? exportablePartNames(part, p).filter((name) => msg.parts.includes(name))
         : exportSubParts(part, msg.view, p);
-    const fileBase = msg.name ?? msg.view; // STEP/3MF single-file name base
+    const fileBase = safeName(msg.name ?? msg.view); // STEP/3MF single-file name base (part-derived → untrusted)
 
     if (msg.type === "generate") {
       const t0 = Date.now();

package/src/framework/lint/finding.js

@@ -18,3 +18,7 @@ const make = (severity) => (rule, message, hint, path = "", pattern) => ({
 export const err = make("error");
 // warning → suspicious or lossy, but the part behaves as authored.
 export const warn = make("warning");
+// note → neither broken nor suspicious; informational context an authoring
+// agent should see (e.g. "this animated track rebuilds geometry"). Notes never
+// gate measure or --strict.
+export const note = make("note");

package/src/framework/lint/index.js

@@ -13,8 +13,10 @@ import { SCHEMA_RULES } from "./rules-schema.js";
 import { runValidatingProbe } from "../geometry/probe.js";
 import { BUILD_RULES } from "./rules-build.js";
 import { VERIFY_RULES, resolveExpect } from "./rules-verify.js";
+import { ANIMATION_RULES } from "./rules-animations.js";
+import { PLACE_RULES } from "./rules-place.js";
 
-export const RULES = [...SHAPE_RULES, ...SCHEMA_RULES, ...BUILD_RULES, ...VERIFY_RULES];
+export const RULES = [...SHAPE_RULES, ...SCHEMA_RULES, ...BUILD_RULES, ...VERIFY_RULES, ...ANIMATION_RULES, ...PLACE_RULES];
 
 // Every rule runs inside a guard. lintPart is called on a user-facing hosted path
 // (partforge-cloud's sandbox), and a linter that takes down the preview it exists to
@@ -71,7 +73,7 @@ export function lintContext(part, params) {
  * Lint a PartDefinition. Never throws.
  * @param {object} part   the default-exported PartDefinition
  * @param {{params?: object}} [opts]  params layered over part.defaults for the probe pass
- * @returns {{ok: boolean, errors: object[], warnings: object[]}}
+ * @returns {{ok: boolean, errors: object[], warnings: object[], notes: object[]}}
  */
 export function lintPart(part, opts) {
   // `opts` is defaulted here, not via `= {}` on the parameter, because a default
@@ -95,6 +97,7 @@ export function lintPart(part, opts) {
         "This part is too malformed for lint to analyze safely — make sure `defaults`, `params`, and `verify`/`derive` are plain, side-effect-free data rather than throwing getters or hostile Proxies.",
         "")],
       warnings: [],
+      notes: [],
     };
   }
   const findings = runRules(RULES, ctx);
@@ -110,5 +113,6 @@ export function lintPart(part, opts) {
   }
   const errors = findings.filter((f) => f.severity === "error");
   const warnings = findings.filter((f) => f.severity === "warning");
-  return { ok: errors.length === 0, errors, warnings };
+  const notes = findings.filter((f) => f.severity === "note");
+  return { ok: errors.length === 0, errors, warnings, notes };
 }

package/src/framework/lint/rules-animations.js

@@ -0,0 +1,404 @@
+// Group 5 — the `animations` block (spec 2026-08-02-model-animation-design.md).
+// Everything but the last rule is static data validation: the block is pure
+// keyframe data by design, so lint can hold every track to the schema without
+// executing author code. `animation-track-rebuilds` is the exception — it runs
+// the geometry-free pose probe to classify each track as pose-only or
+// geometry-rebuilding, and reports the latter at the note tier.
+import { err, note } from "./finding.js";
+import { EASINGS } from "../animation.js";
+import { CANONICAL_VIEWS } from "../view-angles.js";
+import { probeSubPartPose } from "../pose-probe-core.js";
+import { resolveDerived } from "../derive.js";
+
+const isPlainObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
+
+// [name, spec] pairs, only when the block is well-shaped enough to walk.
+const animEntries = (part) =>
+  isPlainObject(part?.animations)
+    ? Object.entries(part.animations).filter(([, a]) => isPlainObject(a))
+    : [];
+
+// Steps in normalized-adjacent form for rule walks (does NOT validate — each
+// rule checks its own slice). A bare-tracks animation is one anonymous step.
+const rawSteps = (a) => (Array.isArray(a.steps) ? a.steps.filter(isPlainObject) : [{ ...a, label: null }]);
+
+// The control descriptor ranges, for value-in-range checks. Mirrors
+// rules-schema.js's collectDescriptors walk (not shared: each group owns its
+// own walk by design — see lint/index.js header).
+function paramRanges(part) {
+  const ranges = new Map();
+  const secs = Array.isArray(part?.parameters) ? part.parameters : [];
+  const add = (d) => {
+    if (d && typeof d.key === "string" && !ranges.has(d.key)) ranges.set(d.key, { min: d.min, max: d.max });
+  };
+  for (const sec of secs) {
+    for (const d of Array.isArray(sec?.advanced) ? sec.advanced : []) add(d);
+    for (const f of Array.isArray(sec?.features) ? sec.features : []) {
+      for (const s of Array.isArray(f?.sliders) ? f.sliders : []) add(s);
+    }
+  }
+  return ranges;
+}
+
+const validKeyframes = (kf) =>
+  Array.isArray(kf) && kf.length >= 2
+  && kf.every((e) => Array.isArray(e) && e.length === 2 && Number.isFinite(e[0]) && Number.isFinite(e[1]))
+  && kf[0][0] === 0 && kf[kf.length - 1][0] === 1
+  && kf.every((e, i) => i === 0 || e[0] > kf[i - 1][0]);
+
+export const ANIMATION_RULES = [
+  {
+    id: "animations-not-object",
+    run: ({ part }) => {
+      if (part?.animations === undefined) return [];
+      if (!isPlainObject(part.animations)) {
+        return [err("animations-not-object", "`animations` is not a plain object",
+          "Declare animations as `animations: { <name>: { duration, tracks } }` — see docs/AUTHORING-PARTS.md \"Animations\".",
+          "animations")];
+      }
+      return Object.entries(part.animations)
+        .filter(([, a]) => !isPlainObject(a))
+        .map(([name]) => err("animations-not-object", `animation "${name}" is not a plain object`,
+          "Each animations entry must be an object with `duration` + `tracks`, or `steps`.",
+          `animations.${name}`));
+    },
+  },
+  {
+    id: "animation-tracks-or-steps",
+    run: ({ part }) => {
+      const out = [];
+      for (const [name, a] of animEntries(part)) {
+        const hasTracks = a.tracks !== undefined;
+        const hasSteps = a.steps !== undefined;
+        if (hasTracks === hasSteps) {
+          out.push(err("animation-tracks-or-steps",
+            `animation "${name}" must have exactly one of \`tracks\` or \`steps\``,
+            "A single-phase animation declares `tracks` directly; a stepped one declares `steps: [{ label, duration, tracks }]`. Never both, never neither.",
+            `animations.${name}`));
+          continue;
+        }
+        if (hasSteps && (!Array.isArray(a.steps) || a.steps.length === 0 || !a.steps.every(isPlainObject))) {
+          out.push(err("animation-tracks-or-steps",
+            `animation "${name}" has an empty or malformed \`steps\` array`,
+            "`steps` must be a non-empty array of `{ label, duration, tracks }` objects.",
+            `animations.${name}.steps`));
+          continue;
+        }
+        rawSteps(a).forEach((s, i) => {
+          const path = hasSteps ? `animations.${name}.steps[${i}].tracks` : `animations.${name}.tracks`;
+          if (!isPlainObject(s.tracks) || Object.keys(s.tracks).length === 0) {
+            out.push(err("animation-tracks-or-steps",
+              `animation "${name}"${hasSteps ? ` step ${i}` : ""} has no tracks`,
+              "Every step needs a non-empty `tracks` object mapping a param key to keyframes.",
+              path));
+          }
+        });
+      }
+      return out;
+    },
+  },
+  {
+    id: "animation-unknown-param",
+    run: ({ part }) => {
+      if (!isPlainObject(part?.defaults)) return [];
+      const known = new Set(Object.keys(part.defaults));
+      const out = [];
+      for (const [name, a] of animEntries(part)) {
+        rawSteps(a).forEach((s, i) => {
+          for (const key of Object.keys(isPlainObject(s.tracks) ? s.tracks : {})) {
+            if (!known.has(key)) {
+              out.push(err("animation-unknown-param",
+                `animation "${name}" tracks "${key}", which is not in \`defaults\``,
+                `Animations drive existing params — add "${key}" to \`defaults\` (and a control for it), or correct the key.`,
+                `animations.${name}${a.steps ? `.steps[${i}]` : ""}.tracks.${key}`));
+            }
+          }
+        });
+      }
+      return out;
+    },
+  },
+  {
+    id: "animation-param-not-numeric",
+    run: ({ part }) => {
+      if (!isPlainObject(part?.defaults)) return [];
+      const out = [];
+      for (const [name, a] of animEntries(part)) {
+        rawSteps(a).forEach((s, i) => {
+          for (const key of Object.keys(isPlainObject(s.tracks) ? s.tracks : {})) {
+            if (key in part.defaults && typeof part.defaults[key] !== "number") {
+              out.push(err("animation-param-not-numeric",
+                `animation "${name}" tracks "${key}", whose default is not a number`,
+                "v1 animations interpolate numeric params only — text/choice params cannot be keyframed.",
+                `animations.${name}${a.steps ? `.steps[${i}]` : ""}.tracks.${key}`));
+            }
+          }
+        });
+      }
+      return out;
+    },
+  },
+  {
+    id: "animation-keyframes-invalid",
+    run: ({ part }) => {
+      const out = [];
+      for (const [name, a] of animEntries(part)) {
+        rawSteps(a).forEach((s, i) => {
+          for (const [key, kf] of Object.entries(isPlainObject(s.tracks) ? s.tracks : {})) {
+            if (!validKeyframes(kf)) {
+              out.push(err("animation-keyframes-invalid",
+                `animation "${name}" track "${key}" has invalid keyframes`,
+                "Keyframes are `[[t, value], …]` with finite numbers, at least two entries, `t` strictly ascending from exactly 0 to exactly 1.",
+                `animations.${name}${a.steps ? `.steps[${i}]` : ""}.tracks.${key}`));
+            }
+          }
+        });
+      }
+      return out;
+    },
+  },
+  {
+    id: "animation-value-out-of-range",
+    run: ({ part }) => {
+      const ranges = paramRanges(part);
+      const out = [];
+      for (const [name, a] of animEntries(part)) {
+        rawSteps(a).forEach((s, i) => {
+          for (const [key, kf] of Object.entries(isPlainObject(s.tracks) ? s.tracks : {})) {
+            const r = ranges.get(key);
+            if (!r || !validKeyframes(kf)) continue;
+            for (const [, v] of kf) {
+              if ((typeof r.min === "number" && v < r.min) || (typeof r.max === "number" && v > r.max)) {
+                out.push(err("animation-value-out-of-range",
+                  `animation "${name}" track "${key}" keyframe value ${v}, outside the control's range ${r.min ?? "-∞"}..${r.max ?? "∞"}`,
+                  "Keyframe values are applied as-is (the engine does not clamp) — widen the control's range or move the keyframe inside it.",
+                  `animations.${name}${a.steps ? `.steps[${i}]` : ""}.tracks.${key}`));
+                break; // one finding per track
+              }
+            }
+          }
+        });
+      }
+      return out;
+    },
+  },
+  {
+    id: "animation-duration-invalid",
+    run: ({ part }) => {
+      const out = [];
+      for (const [name, a] of animEntries(part)) {
+        rawSteps(a).forEach((s, i) => {
+          if (!(typeof s.duration === "number" && Number.isFinite(s.duration) && s.duration > 0)) {
+            out.push(err("animation-duration-invalid",
+              `animation "${name}"${a.steps ? ` step ${i}` : ""} has no positive \`duration\``,
+              "Every animation (or step) needs a finite `duration` in seconds, greater than 0.",
+              `animations.${name}${a.steps ? `.steps[${i}]` : ""}.duration`));
+          }
+        });
+      }
+      return out;
+    },
+  },
+  {
+    id: "animation-loop-invalid",
+    run: ({ part }) => animEntries(part)
+      .filter(([, a]) => a.loop === true && Array.isArray(a.steps) && a.steps.length > 1)
+      .map(([name]) => err("animation-loop-invalid",
+        `animation "${name}" sets \`loop: true\` on a multi-step animation`,
+        "Loop is for continuous single-phase motion (gears). A stepped sequence replays via the transport instead — drop `loop` or collapse to one step.",
+        `animations.${name}.loop`)),
+  },
+  {
+    id: "animation-step-label-duplicate",
+    run: ({ part }) => {
+      const out = [];
+      for (const [name, a] of animEntries(part)) {
+        if (!Array.isArray(a.steps)) continue;
+        const seen = new Set();
+        a.steps.forEach((s, i) => {
+          const label = s?.label;
+          if (typeof label !== "string") return;
+          if (seen.has(label)) {
+            out.push(err("animation-step-label-duplicate",
+              `animation "${name}" repeats the step label "${label}"`,
+              "Step labels identify steps in the transport UI and the CLI's `--step <label>` — make each unique.",
+              `animations.${name}.steps[${i}].label`));
+          }
+          seen.add(label);
+        });
+      }
+      return out;
+    },
+  },
+  {
+    id: "animation-easing-unknown",
+    run: ({ part }) => {
+      const out = [];
+      const check = (easing, path) => {
+        if (easing !== undefined && !(easing in EASINGS)) {
+          out.push(err("animation-easing-unknown",
+            `unknown easing "${easing}"`,
+            `Use one of: ${Object.keys(EASINGS).join(", ")}.`,
+            path));
+        }
+      };
+      for (const [name, a] of animEntries(part)) {
+        check(a.easing, `animations.${name}.easing`);
+        if (Array.isArray(a.steps)) a.steps.forEach((s, i) => check(s?.easing, `animations.${name}.steps[${i}].easing`));
+      }
+      return out;
+    },
+  },
+  {
+    id: "animation-camera-invalid",
+    run: ({ part }) => {
+      const out = [];
+      const badName = (v) => typeof v !== "string" || !CANONICAL_VIEWS.includes(v);
+      for (const [name, a] of animEntries(part)) {
+        const stepCameras = Array.isArray(a.steps)
+          ? a.steps.map((s, i) => [s?.camera, i]).filter(([c]) => c !== undefined && c !== null)
+          : [];
+        if (a.camera !== undefined && stepCameras.length) {
+          out.push(err("animation-camera-invalid",
+            `animation "${name}" mixes an animation-level \`camera\` with per-step cameras`,
+            "One camera mechanism per animation: either the animation-level name/cue-list, or per-step names — not both.",
+            `animations.${name}.camera`));
+        }
+        for (const [cam, i] of stepCameras) {
+          if (badName(cam)) {
+            out.push(err("animation-camera-invalid",
+              `animation "${name}" step ${i} camera "${cam}" is not a canonical angle`,
+              `Camera cues use the canonical angles: ${CANONICAL_VIEWS.join(", ")}.`,
+              `animations.${name}.steps[${i}].camera`));
+          }
+        }
+        if (a.camera === undefined) continue;
+        if (typeof a.camera === "string") {
+          if (badName(a.camera)) {
+            out.push(err("animation-camera-invalid",
+              `animation "${name}" camera "${a.camera}" is not a canonical angle`,
+              `Camera cues use the canonical angles: ${CANONICAL_VIEWS.join(", ")}.`,
+              `animations.${name}.camera`));
+          }
+        } else if (Array.isArray(a.camera)) {
+          const cues = a.camera;
+          const wellFormed = cues.length > 0 && cues.every((c) =>
+            Array.isArray(c) && c.length === 2 && Number.isFinite(c[0]) && c[0] >= 0 && c[0] <= 1 && !badName(c[1]));
+          const sorted = cues.every((c, i) => i === 0 || (Array.isArray(c) && Array.isArray(cues[i - 1]) && c[0] > cues[i - 1][0]));
+          if (!wellFormed || !sorted) {
+            out.push(err("animation-camera-invalid",
+              `animation "${name}" has an invalid camera cue list`,
+              `Cues are \`[[t, angle], …]\` with t strictly ascending in 0..1 and angles from: ${CANONICAL_VIEWS.join(", ")}.`,
+              `animations.${name}.camera`));
+          }
+        } else {
+          out.push(err("animation-camera-invalid",
+            `animation "${name}" \`camera\` is neither an angle name nor a cue list`,
+            "Use a canonical angle string, or `[[t, angle], …]` cues.",
+            `animations.${name}.camera`));
+        }
+      }
+      return out;
+    },
+  },
+  {
+    id: "animation-description-invalid",
+    run: ({ part }) => animEntries(part)
+      .filter(([, a]) => a.description !== undefined && typeof a.description !== "string")
+      .map(([name]) => err("animation-description-invalid",
+        `animation "${name}" \`description\` is not a string`,
+        "The description is CommonMark shown behind the ⓘ glyph — supply a string or omit it.",
+        `animations.${name}.description`)),
+  },
+  {
+    // note tier: performance shape, not correctness. A track whose param feeds
+    // real geometry still plays — just best-effort at worker cadence instead
+    // of frame rate — and the authoring agent should know which it wrote.
+    id: "animation-track-rebuilds",
+    run: ({ part, p }) => {
+      const out = [];
+      for (const [name, a] of animEntries(part)) {
+        const steps = rawSteps(a);
+        // value range per key: the min and max across every keyframe value the
+        // key ever takes, over every step that tracks it — not just the first
+        // and last keyframe, so an out-and-back track (e.g. a hinge cycle that
+        // returns to its start) still compares two genuinely different values.
+        const valueRange = new Map();
+        for (const s of steps) {
+          for (const [key, kf] of Object.entries(isPlainObject(s.tracks) ? s.tracks : {})) {
+            if (!validKeyframes(kf)) continue; // keyframes rule already reported it
+            for (const [, v] of kf) {
+              if (!valueRange.has(key)) valueRange.set(key, [v, v]);
+              else {
+                const range = valueRange.get(key);
+                if (v < range[0]) range[0] = v;
+                if (v > range[1]) range[1] = v;
+              }
+            }
+          }
+        }
+        for (const [key, [v0, v1]] of valueRange) {
+          if (typeof part?.defaults?.[key] !== "number") continue; // other rules own that
+          const cls = classifyTrack(part, p, key, v0, v1);
+          if (cls === "pose") continue;
+          out.push(note("animation-track-rebuilds",
+            cls === "rebuild"
+              ? `animation "${name}" track "${key}" rebuilds geometry — playback is best-effort, not frame-rate`
+              : `animation "${name}" track "${key}" cannot use the pose fast path (untrusted probe) — playback is best-effort`,
+            "Frame-rate playback needs the param to feed only rigid placement (translate/rotate in `place()` or at the end of `build`). If that's the intent, restructure so the param never feeds a geometry op, a query, or a function selector; if geometry morphing is the intent, this is expected.",
+            `animations.${name}`));
+        }
+      }
+      return out;
+    },
+  },
+  {
+    id: "animation-autoplay-invalid",
+    run: ({ part }) => {
+      const out = [];
+      let first = null;
+      for (const [name, a] of animEntries(part)) {
+        if (a.autoplay !== undefined && typeof a.autoplay !== "boolean") {
+          out.push(err("animation-autoplay-invalid",
+            `animation "${name}" \`autoplay\` is not a boolean`,
+            "Use `autoplay: true` on the one animation that should start on its own.",
+            `animations.${name}.autoplay`));
+          continue;
+        }
+        if (a.autoplay !== true) continue;
+        if (first == null) { first = name; continue; }
+        out.push(err("animation-autoplay-invalid",
+          `animations "${first}" and "${name}" both declare \`autoplay\``,
+          "Only one animation can auto-start — remove `autoplay` from all but one.",
+          `animations.${name}.autoplay`));
+      }
+      return out;
+    },
+  },
+];
+
+// Classify one animated param by probing every sub-part it can show, at the
+// track's two endpoint values: identical trusted baseHashes at both ends →
+// the param only re-poses ("pose"); differing hashes → real geometry
+// ("rebuild"); any untrusted probe → "untrusted" (the fast path will decline
+// it at runtime too). Mirrors the runtime trust model in pose-probe-core.js.
+function classifyTrack(part, p, key, v0, v1) {
+  let result = "pose";
+  for (const view of Object.keys(isPlainObject(part?.views) ? part.views : {})) {
+    for (const sp of Object.values(isPlainObject(part?.parts) ? part.parts : {})) {
+      if (!Array.isArray(sp?.views) || !sp.views.includes(view)) continue;
+      const probes = [];
+      for (const v of [v0, v1]) {
+        const pv = { ...p, [key]: v };
+        let dv;
+        try { dv = resolveDerived(part, pv) ?? {}; } catch { return "untrusted"; }
+        try { if (sp.enabled && !sp.enabled(pv)) { probes.push(null); continue; } } catch { return "untrusted"; }
+        probes.push(probeSubPartPose(sp, { view, purpose: "display", p: pv, d: dv }));
+      }
+      if (probes.some((x) => x && !x.trusted)) return "untrusted";
+      const [a, b] = probes;
+      if (a && b && a.baseHash !== b.baseHash) result = "rebuild";
+    }
+  }
+  return result;
+}