partforge 0.142.0 → 0.143.1

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

@@ -1,3 +1,6 @@
+// Lint ids here: views-invalid (a sub-part whose views is neither form), place-not-rigid (legacy views-array + place() form), and for the views-map
+// form view-entry-invalid (an entry that is not true or a pose), views-and-place (an author
+// place beside a map) and view-pose-not-rigid (an entry that reshapes instead of moving).
 // Group 6 — the place() invariant (docs/AUTHORING-PARTS.md "Display vs export
 // placement"), promoted from a doc-only convention to lint because the animation
 // system leans on place() for every pose-only track: display vs export may differ
@@ -15,7 +18,9 @@
 // and stays silent. Readability, not `trusted`, gates the rules: the same reshape
 // on both purposes is allowed, so a reshaping place() must still be compared.
 import { err } from "./finding.js";
-import { probeSubPartPose } from "../pose-probe-core.js";
+import { probeSubPartPose, CANONICAL } from "../pose-probe-core.js";
+import { isViewsMap, inView, formOf } from "../sub-part-views.js";
+import { isSheetPart } from "../sheet/constants.js";
 
 const isPlainObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
 
@@ -24,7 +29,7 @@ const isPlainObject = (x) => x !== null && typeof x === "object" && !Array.isArr
 // imported from jobs.js, which would break the lint purity closure.
 function viewNames(part, view, p) {
   return Object.entries(isPlainObject(part?.parts) ? part.parts : {})
-    .filter(([, sp]) => Array.isArray(sp?.views) && sp.views.includes(view))
+    .filter(([, sp]) => inView(sp, view))
     .filter(([, sp]) => { try { return sp.enabled ? !!sp.enabled(p) : true; } catch { return false; } })
     .map(([name]) => name);
 }
@@ -38,7 +43,7 @@ export const PLACE_RULES = [
     run: ({ part, p, d }) => {
       const out = [];
       for (const [name, sp] of Object.entries(isPlainObject(part?.parts) ? part.parts : {})) {
-        if (!sp?.place) continue;
+        if (!sp?.place || formOf(sp) === "map") continue;
         for (const view of Object.keys(isPlainObject(part?.views) ? part.views : {})) {
           if (!viewNames(part, view, p).includes(name)) continue;
           const display = probePlace(sp, { view, purpose: "display", p, d });
@@ -57,4 +62,77 @@ export const PLACE_RULES = [
       return out;
     },
   },
+  {
+    id: "views-invalid",
+    run: ({ part }) => {
+      const out = [];
+      for (const [name, sp] of Object.entries(isPlainObject(part?.parts) ? part.parts : {})) {
+        const v = sp?.views;
+        if (Array.isArray(v) || isPlainObject(v)) continue;
+        out.push(err("views-invalid",
+          `sub-part "${name}" has no usable \`views\` (it is ${v === undefined ? "missing" : JSON.stringify(v) ?? String(v)})`,
+          "Give the sub-part a `views` map — e.g. `views: { assembly: true }` — naming each view it appears in.",
+          `parts.${name}.views`,
+          "views-invalid"));
+      }
+      return out;
+    },
+  },
+  {
+    id: "view-entry-invalid",
+    run: ({ part }) => {
+      const out = [];
+      for (const [name, sp] of Object.entries(isPlainObject(part?.parts) ? part.parts : {})) {
+        if (!isViewsMap(sp?.views)) continue;
+        for (const [view, entry] of Object.entries(sp.views)) {
+          if (entry === true || typeof entry === "function") continue;
+          out.push(err("view-entry-invalid",
+            `sub-part "${name}" has ${JSON.stringify(entry) ?? String(entry)} for view "${view}"`,
+            `Each entry in a sub-part's \`views\` map is \`true\` (shown as built) or a pose \`(s, p, d) => s.translate(…)\`. To leave the piece out of "${view}", delete the key.`,
+            `parts.${name}.views.${view}`,
+            "view-entry-invalid"));
+        }
+      }
+      return out;
+    },
+  },
+  {
+    id: "views-and-place",
+    run: ({ part }) => {
+      const out = [];
+      for (const [name, sp] of Object.entries(isPlainObject(part?.parts) ? part.parts : {})) {
+        if (!isViewsMap(sp?.views) || typeof sp.place !== "function") continue;
+        const generated = isSheetPart(sp) && sp.place === sp.sheet.generatedPlace && sp.sheet.place == null;
+        if (generated) continue;
+        out.push(err("views-and-place",
+          `sub-part "${name}" has both a \`views\` map and \`place\``,
+          "Put each view's pose in its `views` entry and delete `place`. `build()` makes the piece as it prints — that is what exports.",
+          `parts.${name}.place`,
+          "views-and-place"));
+      }
+      return out;
+    },
+  },
+  {
+    id: "view-pose-not-rigid",
+    run: ({ part, p, d }) => {
+      const out = [];
+      for (const [name, sp] of Object.entries(isPlainObject(part?.parts) ? part.parts : {})) {
+        if (!isViewsMap(sp?.views)) continue;
+        for (const [view, entry] of Object.entries(sp.views)) {
+          if (typeof entry !== "function") continue;
+          // Display only: map poses never apply on export, so there is no second purpose to probe.
+          const probe = probePlace(sp, { view, purpose: "display", p, d });
+          if (!readable(probe) || probe.baseHash === CANONICAL) continue;
+          out.push(err("view-pose-not-rigid",
+            `sub-part "${name}"'s pose for view "${view}" reshapes the piece`,
+            "A view's pose may only translate or rotate its argument — no `scale`, `mirror` or boolean. Bake a resized or reflected form into `build()` so every view shows the same physical piece.",
+            `parts.${name}.views.${view}`,
+            "view-pose-not-rigid"));
+          break; // one finding per sub-part
+        }
+      }
+      return out;
+    },
+  },
 ];

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

@@ -3,6 +3,7 @@
 // defaults and build but not `views`, and had already drifted from the eval runner's
 // separate views check. One source of truth ends that split.
 import { err, warn } from "./finding.js";
+import { isViewsMap, viewsOf } from "../sub-part-views.js";
 import { SHEET_DOC_ID } from "../sheet/constants.js";
 
 // A sub-part that carries a `sheet` declaration but no build was meant to be a sheet
@@ -70,7 +71,7 @@ export const SHAPE_RULES = [
     id: "missing-views",
     run: ({ part }) => (isPlainObject(part?.views) && Object.keys(part.views).length > 0 ? [] : [
       err("missing-views", "the part has no `views` map",
-        "Add a top-level `views` object — e.g. `views: { main: { label: \"Main\" } }` — and list each view name in the owning sub-part's `views` array.",
+        "Add a top-level `views` object — e.g. `views: { main: { label: \"Main\" } }` — and give each sub-part a `views` map naming the views it appears in.",
         "views"),
     ]),
   },
@@ -81,15 +82,17 @@ export const SHAPE_RULES = [
       if (known.size === 0) return []; // missing-views already reported it; don't pile on
       const out = [];
       for (const [name, sp] of partEntries(part)) {
-        if (!Array.isArray(sp?.views)) continue;
-        sp.views.forEach((v, i) => {
+        const listed = Array.isArray(sp?.views) ? sp.views.map((v, i) => [v, `parts.${name}.views[${i}]`])
+          : isViewsMap(sp?.views) ? Object.keys(sp.views).map((v) => [v, `parts.${name}.views.${v}`])
+          : [];
+        for (const [v, path] of listed) {
           if (!known.has(v)) {
             out.push(err("part-view-unknown",
               `sub-part "${name}" lists view "${v}", which is not in the \`views\` map`,
               `Add "${v}" to the top-level \`views\` map, or correct the name to one of: ${[...known].join(", ")}.`,
-              `parts.${name}.views[${i}]`));
+              path));
           }
-        });
+        }
       }
       return out;
     },
@@ -100,12 +103,12 @@ export const SHAPE_RULES = [
       if (!isPlainObject(part?.views)) return [];
       const used = new Set();
       for (const [, sp] of partEntries(part)) {
-        if (Array.isArray(sp?.views)) for (const v of sp.views) used.add(v);
+        for (const v of viewsOf(sp)) used.add(v);
       }
       return Object.keys(part.views)
         .filter((v) => !used.has(v))
         .map((v) => warn("view-unused", `view "${v}" is not listed by any sub-part`,
-          `Either add "${v}" to a sub-part's \`views\` array or remove it from the \`views\` map — as it stands the view renders empty.`,
+          `Either add "${v}" to a sub-part's \`views\` or remove it from the \`views\` map — as it stands the view renders empty.`,
           `views.${v}`));
     },
   },

package/src/framework/materials/print-frame.js

@@ -4,6 +4,7 @@
 // (lint place-not-rigid), and the geometry-free pose probe reports each as a
 // list of rigid steps — so the display→export map is E · D⁻¹, with no geometry.
 // Three-free and DOM-free: the pose probe and pose.js are pure.
+import { placeOf } from "../sub-part-views.js";
 import { probeSubPartPose } from "../pose-probe-core.js";
 import { poseDelta, composePose } from "../geometry/pose.js";
 
@@ -14,7 +15,7 @@ const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
 // build that queries its solid cannot make it untrusted); a "posed" mesh already carries the
 // display pose, so the map is E · D⁻¹.
 export function printFrameMatrix(subPart, { view, p, d, frame = "posed" }) {
-  if (!subPart?.place) return [...IDENTITY];
+  if (!placeOf(subPart)) return [...IDENTITY];
   if (frame === "canonical") {
     const exp = probeSubPartPose(subPart, { view, purpose: "export", p, d }, { scope: "place" });
     return exp.trusted ? composePose(exp.pose) : [...IDENTITY];
@@ -34,7 +35,7 @@ const isIdentity = (m) => m.every((v, i) => Math.abs(v - IDENTITY[i]) < 1e-12);
 // readable, and a build that queries its solid cannot make it untrusted. A place()
 // that only the full-scope probe reads falls back to printFrameMatrix's posed branch.
 export function displayToPrintMatrix(subPart, { view, p, d }) {
-  if (!subPart?.place) return null;
+  if (!placeOf(subPart)) return null;
   const disp = probeSubPartPose(subPart, { view, purpose: "display", p, d }, { scope: "place" });
   const exp = probeSubPartPose(subPart, { view, purpose: "export", p, d }, { scope: "place" });
   const m = disp.trusted && exp.trusted

package/src/framework/materials/sheet-look.js

@@ -17,6 +17,7 @@
 // (resolve.js's default for every other sub-part) but the sheet its stock label names —
 // realisticDisplay, from the ONE keyword table STOCK_LOOKS. Realistic-only, like the PLA
 // default: the CAD view, 3MF colours and declaresMaterials read sp.display itself.
+import { isViewsMap } from "../sub-part-views.js";
 import { isSheetPart, sheetMeta, MARK_DEPTH } from "../sheet/constants.js";
 import { poseSteps, validatePose } from "../sheet/pose.js";
 import { composePose, invertRigid } from "../geometry/pose.js";
@@ -145,6 +146,7 @@ export function burnsFor(sp) {
   if (sp.build !== sp.sheet.generatedBuild) return false;                   // a custom build is not the canonical sheet
   if (sp.sheet.place != null) return false;                                 // an author place moves it off its pose
   if ((sp.place ?? null) !== (sp.sheet.generatedPlace ?? null)) return false; // place replaced after sheetPart
+  if (isViewsMap(sp.views) && Object.values(sp.views).some((v) => typeof v === "function")) return false; // a pose entry moves it off its pose
   try { return lookOf(sp).params.pattern === "wood"; } catch { return false; }
 }
 

package/src/framework/mount.js

@@ -1027,6 +1027,8 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
         // normal is enough to char a whole face. A print frame keeps its last value (the
         // worst it can do is run layer lines the wrong way).
         if (!resolved) { delete sheetFrames[n]; continue; }
+        // For a views-map sub-part the export pose is the build itself (plus a sheet pose), so a canonical
+        // delivery's print frame is identity — no special case, the probe reads the compiled placement.
         if (layerLined.has(n)) printFrames[n] = printFrameMatrix(part.parts[n], { view: at.view, ...resolved, frame });
         if (burning.has(n)) {
           const f = sheetFrameFor(part.parts[n], { ...resolved, frame });

package/src/framework/oracle/verify.js

@@ -290,7 +290,7 @@ export function evaluateCase(facts, { profile, expect, subPartNames, overhang =
       checks.push({ scope: "subpart", subpart: s.name, metric: "bbox", kind: "gate", expr: `<=[${profile.bed.join(",")}]`,
         actual: null, status: "skip", pass: null, unevaluated: true, note: PRINT_POSE_NOTE,
         message: `not measured: its print (export) pose did not build — ${s.printBboxError}`,
-        hint: "This printed part's place() failed for purpose \"export\", so its print size — and its STL/3MF export — is unavailable. Fix place() for the export pose; the bed check then runs." });
+        hint: "build() should make each piece as it prints — a printed piece shown in an assembly gets its assembled pose from its `views` entry, never from build(). Its export pose failed to build, so its print size — and its STL/3MF export — is unavailable. Fix the pose; the bed check then runs." });
     }
     const merged = {
       ...(profile?.minWall != null ? { minWall: `>=${profile.minWall}` } : {}),

package/src/framework/param-deps.js

@@ -3,6 +3,7 @@
 import { recorder, expandDerivedReads } from "./read-recorder.js";
 import { resolveDerivedAttributed } from "./derive.js";
 import { createProbeKernel } from "./geometry/probe.js";
+import { inView, placeOf } from "./sub-part-views.js";
 import { byteAwareReplacer } from "./geometry/solid-hash.js";
 import { viewSubParts } from "./part-model.js";
 
@@ -21,7 +22,7 @@ export function relevantParamKeys(part, view, params) {
     // sub-part is currently hidden (on-screen ones are already in `reads`).
     for (const name of Object.keys(part.parts)) {
       const sp = part.parts[name];
-      if (sp.views.includes(view) && sp.enabled) sp.enabled(recorder(params, relevant));
+      if (inView(sp, view) && sp.enabled) sp.enabled(recorder(params, relevant));
     }
     return relevant;
   } catch {
@@ -48,7 +49,8 @@ export function subPartReadKeys(part, view, params) {
       // place() shapes what's on screen too (display pose is baked into the cached
       // mesh), so its reads count — without this, a param consumed only by place()
       // would let the mesh cache skip a rebuild and leave the sub-part misplaced.
-      if (sp.place) sp.place(built, { view, purpose: "display", p: recorder(params, reads), d: recorder(derived, dSeen) });
+      const place = placeOf(sp);
+      if (place) place(built, { view, purpose: "display", p: recorder(params, reads), d: recorder(derived, dSeen) });
       map.set(name, expandDerivedReads(reads, dSeen, { depsOf, allInputs }));
     }
     return map;
@@ -102,7 +104,7 @@ export function recordedRelevantKeys(part, view, params, readsOf) {
     }
     for (const name of Object.keys(part.parts)) {
       const sp = part.parts[name];
-      if (sp.views.includes(view) && sp.enabled) sp.enabled(recorder(params, relevant));
+      if (inView(sp, view) && sp.enabled) sp.enabled(recorder(params, relevant));
     }
     return relevant;
   } catch {

package/src/framework/part-model.js

@@ -11,15 +11,15 @@
 // oracle depend on the part model without an import cycle back through the job loop.
 import { resolveDerived, resolveDerivedAttributed } from "./derive.js";
 import { recorder } from "./read-recorder.js";
+import { inView, placeOf } from "./sub-part-views.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;
+    return inView(sp, view) && on;
   });
 }
 
@@ -70,12 +70,13 @@ export function resolveParams(part, params, sanitize, reads) {
   return recordedParams(resolved, reads);
 }
 
-// Build one sub-part and apply its optional place() for the given purpose/view.
+// Build one sub-part and apply its placement (sub-part-views.js placeOf — a legacy place() or the compiled views map) 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;
+  const place = placeOf(sp);
+  return place ? place(solid, { view, purpose, p, d }) : solid;
 }

package/src/framework/pose-probe-core.js

@@ -16,6 +16,7 @@
 // same source text at every value of `p.z`, so hashing it would hold baseHash
 // stable while the real geometry changed — precisely the false-positive the fast
 // path must never make. Untrusted subparts simply take the normal regen path.
+import { placeOf } from "./sub-part-views.js";
 import { h } from "./geometry/solid-hash.js";
 import { addSugar } from "./geometry/solid-sugar.js";
 import { SOLID_OPS, SOLID_OPTIONAL_OPS, SHAPE2D_OPS, OCCT_ONLY_OPS } from "./geometry/kernel.js";
@@ -127,15 +128,16 @@ const stepsFinite = (steps) => steps.every((st) =>
 export function probeSubPartPose(sp, { view, purpose = "display", p, d }, { scope = "full" } = {}) {
   try {
     const { kernel, state, token } = makeProbeSession(); // fresh op budget + trust per subpart
+    const place = placeOf(sp);
     if (scope === "place") {
       let s = token(CANONICAL, []);
-      if (!sp.place) return { trusted: true, baseHash: CANONICAL, pose: [] };
-      s = sp.place(s, { view, purpose, p, d });
+      if (!place) return { trusted: true, baseHash: CANONICAL, pose: [] };
+      s = place(s, { view, purpose, p, d });
       if (!(s && s.__poseToken) || state.queried || state.unhashable || !stepsFinite(s._pose)) return { trusted: false };
       return { trusted: s._hash === CANONICAL, baseHash: s._hash, pose: s._pose };
     }
     let s = sp.build(kernel, p, d);
-    if (scope === "full" && sp.place) s = sp.place(s, { view, purpose, p, d });
+    if (scope === "full" && place) s = place(s, { view, purpose, p, d });
     const ok = s && s.__poseToken && !state.queried && !state.unhashable && stepsFinite(s._pose);
     return ok ? { trusted: true, baseHash: s._hash, pose: s._pose } : { trusted: false };
   } catch {

package/src/framework/sheet/part.js

@@ -15,7 +15,11 @@
 // and `sp.place === sp.sheet.generatedPlace`.
 //
 // Placement (decision 10): the pose applies for display AND export, then the author's
-// own `place` — so STEP/3MF/STL files of a sheet forge come out assembled.
+// own `place` — so STEP/3MF/STL files of a sheet forge come out assembled. With a views
+// map, the generated place is the BASE of the compiled placement (sub-part-views.js
+// placeOf): the pose applies for display and export, then the view's entry for display
+// only. Sheet entries are taught as `true`; a pose entry is allowed but drops the burn
+// pass (sheet-look.js burnsFor).
 import { RENAMED_KEYS, RESERVED_KEYS, SHEET_KEYS, SUBPART_PASSTHROUGH_KEYS } from "./constants.js";
 import { validatePose } from "./pose.js";
 import { applyPose, resolveSheet, sheetPreview } from "./resolve.js";

package/src/framework/sub-part-views.js

@@ -0,0 +1,56 @@
+// One sub-part's views and placement, in either authoring form.
+//
+//   map form:    views: { assembly: (s, p, d) => s.translate(…), lid: true }
+//   legacy form: views: ["assembly", "lid"], place: (s, { view, purpose, p, d }) => s
+//
+// Every reader of a sub-part's views or placement asks here, so the map form compiles to
+// the same place(s, { view, purpose, p, d }) the pose probe, the pose ladder, print frames
+// and the oracle already understand (spec 2026-10-04 "Compilation"). A map entry is `true`
+// (shown as built) or a rigid pose; anything else leaves the piece out of that view and is
+// lint's view-entry-invalid. Export never applies an entry: a map-form piece exports as
+// built. A base `place` on a map-form sub-part can only be sheetPart's generated pose
+// (lint's views-and-place refuses an author's), and it runs first for both purposes, as
+// sheet poses always have.
+//
+// Pure and import-free: lint rules import it (test/lint-purity.test.js).
+
+const isPlainObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
+const isEntry = (v) => v === true || typeof v === "function";
+
+export const isViewsMap = (views) => isPlainObject(views);
+
+export function viewsOf(sp) {
+  const v = sp?.views;
+  if (Array.isArray(v)) return v;
+  if (isPlainObject(v)) return Object.keys(v).filter((name) => isEntry(v[name]));
+  return [];
+}
+
+export const inView = (sp, view) => viewsOf(sp).includes(view);
+
+export const formOf = (sp) => (isViewsMap(sp?.views) ? "map" : "legacy");
+
+// Memo only: never identity-compared across module instances (the cloud worker loads two).
+const compiled = new WeakMap();
+
+export function placeOf(sp) {
+  if (!sp) return null;
+  if (compiled.has(sp)) return compiled.get(sp);
+  if (!isViewsMap(sp.views)) {
+    // A wrapper, so a method-style place keeps `this` when callers invoke it detached.
+    const legacy = typeof sp.place === "function" ? (s, ctx) => sp.place(s, ctx) : null;
+    compiled.set(sp, legacy);
+    return legacy;
+  }
+  const base = typeof sp.place === "function" ? sp.place : null;
+  const entries = sp.views;
+  const anyPose = Object.values(entries).some((v) => typeof v === "function");
+  const fn = !base && !anyPose ? null : (s, ctx) => {
+    const posed = base ? base(s, ctx) : s;
+    if (ctx.purpose === "export") return posed;
+    const entry = entries[ctx.view];
+    return typeof entry === "function" ? entry(posed, ctx.p, ctx.d) : posed;
+  };
+  compiled.set(sp, fn);
+  return fn;
+}

package/src/parts/hinged-box.js

@@ -1,7 +1,7 @@
 // Animation reference part — a box with a hinged lid. Worked example for
 // docs/AUTHORING-PARTS.md "Animations": animations are VIEW-OWNED (declared
 // under `views.box.animations`, so the transport bar belongs to that view),
-// they drive pose-only params (lidAngle, lidLift) through place(), and
+// they drive pose-only params (lidAngle, lidLift) through the lid's `views` entry, and
 // `assemble` opens with an OPACITY fade that brings the lid in from nothing
 // before any motion. Also shown: an intro camera + markdown description on
 // `open`, a looping autoplay `cycle`, and per-step cameras on `assemble`.
@@ -39,7 +39,7 @@ export default {
   parts: {
     base: {
       label: "Base",
-      views: ["box"],
+      views: { box: true },
       export: { name: "base" },
       display: { material: "walnut" },
       build: (k, p) =>
@@ -48,19 +48,18 @@ export default {
     },
     lid: {
       label: "Lid",
-      views: ["box"],
       export: { name: "lid" },
       display: { material: "walnut" },
-      build: (k, p) => k.box({ min: [0, 0, p.height], max: [p.width, p.depth, p.height + p.wall] }),
-      // Display: swing about the hinge line (rear top edge, axis +X through
-      // [0, depth, height]; negative angle opens upward), then the assembly
-      // lift. Export: the lid prints flat beside the base. Both poses are
-      // rigid motions of the same solid, and neither reads `view` — the two
-      // invariants lint's place rules hold every part to.
-      place: (s, { purpose, p }) =>
-        purpose === "export"
-          ? s.translate([p.width + 10, 0, -p.height])
-          : s.rotate(-p.lidAngle, [0, p.depth, p.height], [1, 0, 0]).translate([0, 0, p.lidLift]),
+      // Built as it prints: a flat plate at the origin. The `box` view sets it on the
+      // base, swings it about the hinge line (rear top edge, axis +X through
+      // [0, depth, height]; negative angle opens upward) and applies the assembly
+      // lift. lidAngle and lidLift are read only here, so both animate at frame rate.
+      build: (k, p) => k.box({ min: [0, 0, 0], max: [p.width, p.depth, p.wall] }),
+      views: {
+        box: (s, p) => s.translate([0, 0, p.height])
+          .rotate(-p.lidAngle, [0, p.depth, p.height], [1, 0, 0])
+          .translate([0, 0, p.lidLift]),
+      },
     },
   },
   views: {

package/src/parts/laser-box.js

@@ -32,17 +32,16 @@ function hinge(k, p, d) {
   return k.union([fixed, moving]);
 }
 
-// Display: flat hinge against the back panel's outside face, knuckles above the wall.
-// Export: the print pose, untouched — both hinges export the same solid.
-const hingePlace = (i) => (s, { purpose, p, d }) => (purpose === "export" ? s
-  : s.rotateX(90).at([d.hingeX[i], p.depth / 2 + HINGE.leafT, d.axisZ]));
+// Each hinge is built in its PRINT pose (above); the box view stands it up on the back
+// panel. Identical builds, so the kit still prints "hinge" ×2.
+const hingePose = (i) => (s, p, d) => s.rotateX(90).at([d.hingeX[i], p.depth / 2 + HINGE.leafT, d.axisZ]);
 
 // Tongue slots for both hinges, cut where the tongues really land (world → sheet).
 const hingeSlots = (k, p, d, pose, z) => d.hingeX.flatMap((hx) =>
   [hx - HINGE.tongueX, hx + HINGE.tongueX].map((x) =>
     k.shape2d(tab(p).slot).translate(worldToSheet(pose, [x, p.depth / 2, z]))));
 
-const PLY = { views: ["box"], display: { material: "plywood" }, material: "birch plywood", thickness: (p) => p.t };
+const PLY = { views: { box: true }, display: { material: "plywood" }, material: "birch plywood", thickness: (p) => p.t };
 const panel = (name, label, extra = {}) => sheetPart({
   ...PLY, label,
   profile: (k, p, d) => d.box[name].outline,       // drawn as seen from outside
@@ -97,10 +96,10 @@ export default {
         .cutAll(hingeSlots(k, p, d, d.lidPose, d.axisZ + d.tongueY)),
       pose: (p, d) => d.lidPose,
     }),
-    hingeL: { label: "Hinge (left)", views: ["box"], display: { material: "pla-print" },
-      export: { name: "hinge" }, build: hinge, place: hingePlace(0) },
-    hingeR: { label: "Hinge (right)", views: ["box"], display: { material: "pla-print" },
-      build: hinge, place: hingePlace(1) },    // identical solid: the kit prints "hinge" ×2
+    hingeL: { label: "Hinge (left)", views: { box: hingePose(0) }, display: { material: "pla-print" },
+      export: { name: "hinge" }, build: hinge },
+    hingeR: { label: "Hinge (right)", views: { box: hingePose(1) }, display: { material: "pla-print" },
+      build: hinge },    // identical solid: the kit prints "hinge" ×2
   },
   views: { box: { label: "Box" } },
   // `process` = the PRINTED parts' profile; sheet parts get the laser checks instead.

package/src/parts/lattice-box.js

@@ -0,0 +1,110 @@
+// Worked example for the views map (docs/AUTHORING-PARTS.md "The PartDefinition
+// contract"): a storage box with a hinged lid, a lattice insert in the lid window, a
+// nameplate on the front and a filament-offcut hinge pin. Every piece is ONE sub-part,
+// built as it prints; each view entry only moves it — `assembly` puts it together and
+// swings the lid, the piece tabs show it as built, `print` spreads the printed pieces
+// on the bed. lidAngle is read only in view entries, so the Open lid animation never
+// rebuilds geometry, and layer lines follow each piece's print orientation.
+
+// The one hinge every piece that rides on the lid swings about.
+const swing = (s, p, d) => s.rotate(-p.lidAngle, d.hinge, [1, 0, 0]);
+
+export default {
+  meta: { title: "Lattice Box", units: "mm" },
+  parameters: [
+    {
+      id: "box", title: "Box",
+      advanced: [
+        { key: "w", label: "Width", unit: "mm", min: 50, max: 140, step: 1 },
+        { key: "d", label: "Depth", unit: "mm", min: 40, max: 120, step: 1 },
+        { key: "h", label: "Height", unit: "mm", min: 20, max: 80, step: 1 },
+      ],
+    },
+    {
+      id: "pose", title: "Pose",
+      advanced: [{ key: "lidAngle", label: "Lid angle", unit: "°", min: 0, max: 110, step: 1 }],
+    },
+  ],
+  defaults: { w: 80, d: 60, h: 40, wall: 2, t: 2.4, lidAngle: 0 },
+  derive: (p) => ({
+    hinge: [0, p.d + 1, p.h],                         // just behind the rear top edge, along X
+    win: { x: 12, y: 12, w: p.w - 24, d: p.d - 24 },  // the lid's window
+    fit: 0.2,
+    gap: 10,                                          // spacing in the print view
+  }),
+  parts: {
+    body: {
+      label: "Body",
+      display: { color: 0x1e88e5 },
+      // Open-top box; prints open side up, as built.
+      build: (k, p) => k.box({ min: [0, 0, 0], max: [p.w, p.d, p.h] })
+        .cut(k.box({ min: [p.wall, p.wall, p.wall], max: [p.w - p.wall, p.d - p.wall, p.h + 1] })),
+      views: { assembly: true, body: true, print: true },
+    },
+    lid: {
+      label: "Lid",
+      display: { color: 0xe53935 },
+      // A flat plate with the lattice window, printed flat.
+      build: (k, p, d) => k.box({ min: [0, 0, 0], max: [p.w, p.d, p.t] })
+        .cut(k.box({ min: [d.win.x, d.win.y, -1], max: [d.win.x + d.win.w, d.win.y + d.win.d, p.t + 1] })),
+      views: {
+        assembly: (s, p, d) => swing(s.translate([0, 0, p.h]), p, d),
+        lid: true,
+        print: (s, p, d) => s.translate([p.w + d.gap, 0, 0]),
+      },
+    },
+    mesh: {
+      label: "Lattice insert",
+      display: { color: 0x222222 },
+      // Fills the window less the fit, with a staggered grid of round holes; printed flat.
+      build: (k, p, d) => {
+        const W = d.win.w - 2 * d.fit, D = d.win.d - 2 * d.fit;
+        let plate = k.box({ min: [0, 0, 0], max: [W, D, p.t] });
+        let row = 0;
+        for (let y = 4; y <= D - 4; y += 6, row++) {
+          for (let x = 4 + (row % 2) * 3; x <= W - 4; x += 6) {
+            plate = plate.cut(k.cylinder({ r: 2.2, h: p.t + 2 }).translate([x, y, -1]));
+          }
+        }
+        return plate;
+      },
+      views: {
+        assembly: (s, p, d) => swing(s.translate([d.win.x + d.fit, d.win.y + d.fit, p.h]), p, d),
+        mesh: true,
+        print: (s, p, d) => s.translate([p.w + d.gap, p.d + d.gap, 0]),
+      },
+    },
+    plate: {
+      label: "Nameplate",
+      display: { color: 0xffd400 },
+      // A thin plate, printed flat; stands just off the front of the box (0.2 mm clear) in the assembly.
+      build: (k) => k.box({ min: [0, 0, 0], max: [40, 12, 1.6] }),
+      views: {
+        assembly: (s, p) => s.rotateX(90).translate([(p.w - 40) / 2, -0.2, p.h / 2 - 6]),
+        plate: true,
+        print: (s, p, d) => s.translate([0, p.d + d.gap, 0]),
+      },
+    },
+    pin: {
+      label: "Hinge pin (1.75 mm filament)",
+      exportable: false,
+      display: { color: 0x9e9e9e },
+      build: (k, p) => k.cylinder({ r: 0.875, h: p.w }).rotate(90, [0, 0, 0], [0, 1, 0]),
+      views: { assembly: (s, p, d) => s.translate(d.hinge) },
+    },
+  },
+  views: {
+    assembly: {
+      label: "Assembly",
+      animations: {
+        open: { label: "Open lid", duration: 1.2, tracks: { lidAngle: [[0, 0], [1, 110]] } },
+      },
+    },
+    body: { label: "Body" },
+    lid: { label: "Lid" },
+    mesh: { label: "Lattice insert" },
+    plate: { label: "Nameplate" },
+    print: { label: "Print bed" },
+  },
+  verify: { process: "fdm-pla", expect: { _view: { overlaps: 0 } } },
+};

package/src/parts/mixed-smoke.js

@@ -21,7 +21,7 @@ export default {
   parts: {
     body: {
       label: "Body",
-      views: ["assembly"],
+      views: { assembly: true },
       export: { name: "body" },
       // The t > 0 branch is what drives the routing: the probe re-runs with live
       // params, so the shell call is only seen (and OCCT only engaged) when the
@@ -33,10 +33,9 @@ export default {
     },
     lid: {
       label: "Lid",
-      views: ["assembly"],
+      views: { assembly: (s) => s.at([0, 0, 12]) },
       export: { name: "lid" },
       build: (k, p) => k.box({ min: [0, 0, 0], max: [p.w, p.w, 2] }),
-      place: (s) => s.at([0, 0, 12]),
     },
   },
   views: { assembly: { label: "Assembly" } },

package/types/geometry.d.ts

@@ -317,7 +317,7 @@ export interface SheetPartSpec<P = ResolvedParams, D = Derived> {
   pose?: SheetPose | ((p: P, d: D) => SheetPose | null) | null;
   process?: "laser";
   label?: string;
-  views: string[];
+  views: string[] | Record<string, true | ((s: Solid, p: P, d: D) => Solid)>;
   display?: SubPartDefinition<P, D>["display"];
   export?: { name: string };
   enabled?: (p: P) => unknown;