partforge 0.142.0 → 0.143.0

package/README.md

@@ -193,7 +193,7 @@ runtime.setParams({ openAngle: 45 });   // merges into the live params, syncs th
 
 The partial is merged into the current params and the control panel updates to
 match. Keys the part doesn't define are silently ignored. When every changed
-parameter only moves geometry (a rotation or translation in `place()`), the
+parameter only moves geometry (a rotation or translation in a `views` pose), the
 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.

package/docs/AUTHORING-PARTS.md

@@ -80,8 +80,7 @@ export default {
     <name>: {
       label?,                              // display name (tabs/progress); defaults to the key
       build: (k, p, d, onProgress?) => Solid,   // REQUIRED — see kernel API
-      place?: (solid, { view, purpose, p, d }) => Solid,   // optional reposition; default identity
-      views,                               // string[] — which views show this sub-part
+      views: { <view>: true | (s, p, d) => s },  // each view the piece appears in: true = as built, or a rigid pose — see Rules
       enabled?: (p) => boolean,            // optional — gate a conditional sub-part
       display?: { color?, opacity?, material?, …overrides }, // viewer-only appearance — see "Materials and appearance"
       export?: { name },                   // filename/object name on export; defaults to the key
@@ -96,31 +95,44 @@ export default {
 
 **Rules:**
 
-- `build(k, p, d, onProgress?)` returns the **canonical** solid (e.g. at the origin).
+- `build(k, p, d, onProgress?)` makes the piece **as it prints**: at the origin, flat
+  face on the bed (z = 0). It is the exported solid and the direction layer lines run.
   It is the only required function per sub-part. `p` is `{ ...defaults, ...userParams }`;
   `d` is `derive(p)` (or `{}`). `onProgress?.("phase")` is optional per-feature progress
   shown during export — call it before expensive steps.
-- `place(solid, ctx)` is an optional escape hatch for parts whose **display pose differs
-  from their export pose** (e.g. positioning a sub-part in an assembly). `ctx.purpose` is
-  `"display"` or `"export"`; `ctx.view` is the active view. Default is identity, so simple
-  parts omit it. Display placement may depend on `view`: the viewer re-poses each
-  sub-part when the tab changes, so one sub-part can sit differently in two views.
-  The viewer applies the display pose as a matrix over the canonical mesh, so `build()` may
-  query geometry freely; only `place()` has to stay a rigid motion of its argument, reading
-  `p` and `d`, for a pose-only param to play at frame rate and for layer lines to stay on
-  the part.
-  **Any difference between the display and export pose must be a rigid motion** —
-  `translate`/`rotate`/`rotateAbout`/`along`/`at` only. Never put a `mirror` or a
-  non-identity `scale` on one purpose but not the other: the exported (printed) part is the
-  same physical object you show in the assembly, and a reflection or resize there makes the
-  two silently disagree — you print the mirror image of what the viewer showed
-  ([place-not-rigid](ERROR-PATTERNS.md#place-not-rigid)). If a part genuinely needs a
-  reflected or resized form (e.g. a block that seats flipped), bake that into `build` so
-  both purposes share one canonical solid, then pose it rigidly.
-  Branch on `purpose` so the export pose is the print orientation: an export pose that
-  follows an animated param pins the layer lines to the pose at the last rebuild.
+- `views` maps each view the piece appears in to `true` (shown as built) or a pose
+  `(s, p, d) => s` that only translates or rotates its argument
+  (`translate`/`rotate`/`rotateAbout`/`along`/`at`) — no geometry queries, no
+  `scale`/`mirror`, no new solid. A view missing from the map does not show the piece.
+- One sub-part per physical piece — never separate "print" and "assembled" copies. A
+  piece's own tab is `true`; `assembly` entries move pieces into place; `print` entries
+  spread them on the bed (`p.w + 10`, not a measurement).
+- A param that moves a piece (hinge angle, slide, explode distance) is read only in
+  `views` entries; it then animates at frame rate with no rebuild.
+- List `assembly` first (or flag it `default: true`) among the top-level `views` (the default tab, and what
+  headless `verify` checks), piece tabs next, `print` last.
+- A piece that is not printed (a filament pin, a bearing) is `exportable: false` and
+  appears in `assembly` only.
+- Sheet pieces (`sheetPart`) keep their `pose`; their `views` entries are `true`, and they
+  stay out of `print` — they are cut, not printed, and export assembled.
+- Exports write the checked pieces as built. STL is one file per piece; a 3MF or STEP of
+  several printed (non-sheet) pieces lays them out on the bed automatically, 10 mm apart.
+
+The Lattice Box's `lid` shows all of it (helpers elided — see `src/parts/lattice-box.js` for the whole part, whose `swing` is `(s, p, d) => s.rotate(-p.lidAngle, d.hinge, [1, 0, 0])`):
+
+```js
+lid: {
+  build: (k, p, d) => /* flat plate with the lattice window, as printed */ k.box({ min: [0, 0, 0], max: [p.w, p.d, p.t] }),
+  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]),
+  },
+},
+```
+
 - `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
+- A view's sub-parts are derived, never hard-coded: those whose `views` map has 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
@@ -150,6 +162,36 @@ export default {
   lives beside the part and is meant to stay hand-editable.
   See "Vector geometry" below for the full contract.
 
+### Legacy: views arrays and place()
+
+Parts written before 0.143 list views as an array and pose pieces with `place()`. They keep working unchanged, including their export poses; new parts use the `views` map above. A sub-part may not use both (`views-and-place`).
+
+```js
+<name>: {
+  build: (k, p, d, onProgress?) => Solid,
+  place?: (solid, { view, purpose, p, d }) => Solid,   // optional reposition; default identity
+  views: ["assembly", "print"],                        // string[] — which views show this sub-part
+},
+```
+
+- `place(solid, ctx)` is an optional escape hatch for parts whose **display pose differs
+  from their export pose**. `ctx.purpose` is `"display"` or `"export"`; `ctx.view` is the
+  active view. Default is identity. Display placement may depend on `view`: the viewer
+  re-poses each sub-part when the tab changes. The viewer applies the display pose as a
+  matrix over the canonical mesh, so `build()` may query geometry freely; only `place()`
+  has to stay a rigid motion of its argument, reading `p` and `d`, for a pose-only param
+  to play at frame rate and for layer lines to stay on the part.
+- **Any difference between the display and export pose must be a rigid motion** —
+  `translate`/`rotate`/`rotateAbout`/`along`/`at` only. Never put a `mirror` or a
+  non-identity `scale` on one purpose but not the other: you would print the mirror image
+  of what the viewer showed ([place-not-rigid](ERROR-PATTERNS.md#place-not-rigid)). Bake a
+  reflected or resized form into `build` so both purposes share one canonical solid, then
+  pose it rigidly.
+- Branch on `purpose` so the export pose is the print orientation: an export pose that
+  follows an animated param pins the layer lines to the pose at the last rebuild.
+- A param read only inside `place()` plays at frame rate; `lint` notes a track whose
+  `place()` it cannot read (a query on the solid, a function argument).
+
 ---
 
 ## Animations
@@ -292,10 +334,10 @@ Rules (all lint-enforced):
   ]
   ```
 - Playback drives params through the real param pipeline. A param read only
-  inside `place()` plays at frame rate whatever `build()` does. A param
+  inside a `views` pose plays at frame rate whatever `build()` does. A param
   `build()` reads rebuilds at worker cadence — except through a trailing
   translate/rotate, which the viewer still re-poses by delta. `lint` notes a track whose
-  `place()` it cannot read (a query on the solid, a function argument).
+  pose it cannot read (a query on the solid, a function argument).
 - 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.
@@ -385,8 +427,8 @@ that changes the part's footprint never slides the floor around under it.
 
 **3D-print layer lines** (`pla-print`, `petg-print`) run perpendicular to the
 **export** pose's +Z — the way the part will be printed, not the way it is
-displayed. If the lines run the wrong way, fix the export pose with `place()`
-(`purpose: "export"`), not the material. Wood, carbon fibre and SLS grain are
+displayed. If the lines run the wrong way, fix `build()` so the piece is
+modelled in its print orientation, not the material. Wood, carbon fibre and SLS grain are
 fixed to the sub-part, so they never slide when the camera or an animation
 moves.
 
@@ -396,7 +438,7 @@ moves.
 `plywood` the plies show through), and its engraving and score lines are scorched, while its
 faces stay wood. There is nothing to set, and it is still one material: the char follows
 from the sheet and the wood it is drawn in. It needs the sheet's own frame, so a sheet part
-with a custom `build` or its own `place` shows plain wood. The CAD view and every export are
+with a custom `build` or a `views` pose of its own shows plain wood. The CAD view and every export are
 unchanged.
 
 **`textureScale` is millimetres, and what it measures depends on the preset's
@@ -792,11 +834,11 @@ This holds on **both backends** — and on OCCT, `translate`/`rotate` are additi
 *pose-lazy*: the backend re-poses the cached solid's cached tessellation instead of
 re-running any B-rep work. A parameter that only feeds a final placement rotation (a
 lid's open angle, an exploded-view offset) therefore re-drags in ~0 ms even on the
-slow exact kernel — keep such transforms as the last ops in `build` (or in `place`)
+slow exact kernel — keep such transforms as the last ops in `build` (or in a `views` pose)
 rather than baking them into the geometry earlier. In the app, such pose-only edits
 skip the worker entirely — the viewer re-poses the cached mesh — so they stay smooth
-even at animation rates (see `runtime.setParams`). `place()` needs no geometry: the viewer
-reads its pose off a geometry-free probe of `place()` alone, so `build()` may query freely.
+even at animation rates (see `runtime.setParams`). A `views` pose needs no geometry: the viewer
+reads it off a geometry-free probe of the pose alone, so `build()` may query freely.
 
 ---
 
@@ -1801,7 +1843,7 @@ cleanly tells a facet artifact (close to 180°, barely bent) from a real corner
 away from 180°) — filter on that, or pass a coarser `segs` to the tessellated shape
 before unioning, rather than fighting the selector after the fact.
 
-**Which controls a sub-part depends on** is recorded from its real build. The worker notes every `p` and `d` key that `build()` and `place()` read:
+**Which controls a sub-part depends on** is recorded from its real build. The worker notes every `p` and `d` key that `build()` and the `views` poses read:
 - a derived key expands to the params its `derive` group read. `derive` must return its values, not write them onto `p`: a key `derive` writes onto `p` isn't attributed to anything;
 - a param read by a `fonts`, `images` or `vectors` declaration counts for every sub-part.
 
@@ -1838,7 +1880,7 @@ with pockets, steps or fillets. Mixing is normal — plywood panels, printed hin
 import { sheetPart, sheetHole } from "partforge/geometry";
 
 plate: sheetPart({
-  label: "Plate", views: ["main"], display: { material: "clear-acrylic" },
+  label: "Plate", views: { main: true }, display: { material: "clear-acrylic" },
   material: "clear acrylic",                  // stock label: groups pieces in the kit
   thickness: (p) => p.t,                      // the MEASURED thickness, from a control
   profile: (k, p) => k.shape2d([[0, 0], [p.w, 0], [p.w, p.h], [0, p.h]])
@@ -1847,12 +1889,11 @@ plate: sheetPart({
 }),
 ```
 
-It returns an ordinary sub-part: `build`, `place` and a plain-data `sheet`. A field
+It returns an ordinary sub-part: `build`, the pose's placement and a plain-data `sheet`. A field
 needing the kernel is `(k, p, d) => …`; a plain value is a literal or `(p, d) => …`.
 `material`, `thickness` and `profile` are required; `score`, `engrave`, `pose`,
 `process` (default `"laser"`) are optional; `label`, `views`, `display`, `export`,
-`enabled`, `exportable`, `reference` pass through; your own `place` runs after the
-pose. `build` is supplied — passing one throws, as do `kerf`, `outline`/`cut` and
+`enabled`, `exportable`, `reference` pass through; your `views` poses apply after the `pose`, in the viewer only. `build` is supplied — passing one throws, as do `kerf`, `outline`/`cut` and
 `quantity`; each error names the fix.
 
 ### Cut, score and engrave
@@ -1922,8 +1963,7 @@ front: sheetPart({ ...PLY, profile: (k, p, d) => d.box.front.outline, pose: (p,
 
 `printedTab({ size: [w, h], thickness, clearance = 0.3 })` gives a slot and its printed
 tongue from one spec: `slot` is `(w + c) × (h + c)`, centred (all the play); `tongue`
-is `[w, h, thickness]` for `k.box({ size: tongue })`. Build the printed part in its
-PRINT pose, `place` it for display, and cut the slot where the tongue lands:
+is `[w, h, thickness]` for `k.box({ size: tongue })`. Build the printed part as it prints; its view entry moves it into place; the slot:
 `k.shape2d(tab.slot).translate(worldToSheet(panelPose, tongueCentre))`.
 
 ### What lint and verify check
@@ -1973,7 +2013,7 @@ A host downloads sheet parts as one ZIP, the **cut & print kit** (`format: "bund
 - One thickness per joint: fingers, tabs and T-slots join panels cut from the
   same sheet.
 - Poses are rigid and axis-aligned: `face` and `up` are the six axis words. An
-  angled panel is an author `place` after the pose (realistic mode then shows
+  angled panel is a `views` entry after the pose (realistic mode then shows
   no laser burns), or a printed part.
 - No bends, folds, living hinges or grain direction: `folds`, `bends` and
   `grain` are reserved keys and throw.
@@ -2021,17 +2061,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
@@ -2086,10 +2125,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.
@@ -2456,7 +2495,7 @@ parts: {
   // Ghost overlay: only in "reference" — never coincides with body in "assembly".
   ref: {
     label: "Reference (ghost)",
-    views: ["reference"],
+    views: { reference: true },
     exportable: false,
     display: { opacity: 0.3 },
     build: (k) => k.import("scan"),
@@ -2465,7 +2504,7 @@ parts: {
   // in "reference" for visual alignment checking.
   body: {
     label: "Rebuild",
-    views: ["assembly", "reference"],
+    views: { assembly: true, reference: true },
     reference: "scan",
     build: (k, p) => k.box({ min: [0, 0, 0], max: [p.scanW, p.scanD, p.scanH] }),
   },
@@ -3714,17 +3753,20 @@ key, which the runtime ignores), `animations-not-object`,
 `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 when its `place()` can't be read (it queries the solid or
+real geometry, or when its pose can't be read (it queries the solid or
 passes a function), 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 place probe (the same
-one animation's `animation-track-rebuilds` uses) against each sub-part's
-`place()`, even when `build()` queries the solid — `place-not-rigid` (display vs.
-export placement may differ only by a rigid motion — translate/rotate — never a
-reshape; an error). A `place()` the probe cannot read (it queries the solid or
-passes a function) stays silent for the place rule and earns the
+**View-pose invariants**, found by running the geometry-free pose probe (the same
+one animation's `animation-track-rebuilds` uses) against each `views` entry, even when
+`build()` queries the solid — `view-entry-invalid` (an entry that is neither `true` nor a
+pose function), `views-and-place` (an author `place` beside a `views` map) and
+`view-pose-not-rigid` (an entry that reshapes instead of moving), `views-invalid` (a sub-part
+whose `views` is missing or neither a map nor an array; all errors), and
+`place-not-rigid` (legacy `place()` form: display vs. export placement may differ only by a
+rigid motion — translate/rotate — never a reshape; an error). A pose the probe cannot read
+(it queries the solid or passes a function) stays silent for these rules and earns the
 `animation-track-rebuilds` note.
 
 **Appearance** (all warnings) — `unknown-material` (a `display.material` the
@@ -4007,7 +4049,7 @@ counted: the footprint itself, and faces whose centroid sits within 1 mm of the
 flat underside spanning two supports) and the ceiling of a horizontal bore are
 reported as overhangs — the mesh alone cannot tell a bridge from a ceiling — which
 is why this is a warning and never a gate. Two more limits, stated: it is judged in
-the DISPLAY pose, so a sub-part whose `place` differs for export (a lid that prints
+the DISPLAY pose, so a sub-part whose `assembly` pose stands it differently from how it prints (a lid that prints
 flat beside its base) is measured as displayed, and `exportable: false` sub-parts
 are skipped. Switch it off under an FDM profile with an inline
 `{ base: "fdm-pla", overhang: null }`. **What `expect` gives you:** per-sub-part
@@ -4387,6 +4429,9 @@ symptom first** — it maps error text → cause → fix. The invariants, one li
 - **`build` is a pure function of `(k, p, d)`** — impurity silently defeats the geometry
   cache ([impure-build-stale-preview](ERROR-PATTERNS.md#impure-build-stale-preview)).
 - **Units are millimetres** throughout.
+- **One sub-part per physical piece, built as it prints; `views` poses it.** A `views`
+  entry is `true` or a rigid pose `(s, p, d) => s` — never a second "print" copy, never a
+  reshape ([view-pose-not-rigid](ERROR-PATTERNS.md#view-pose-not-rigid)).
 - **Never sample an arc into points by hand.** A `Math.cos` loop hides the sweep direction
   in a sign, and a wrong sign produces a self-crossing outline that builds with inverted
   fill and no error — only a `profile-self-intersects` warning

package/docs/ERROR-PATTERNS.md

@@ -141,9 +141,33 @@ Variant literals under this entry: `extrude: unknown bevel option`, `extrude: be
 ## place-not-rigid
 
 - **Symptom:** The exported/printed part is a mirror image of — or a different size than — the same part shown in the assembly/display view. Nothing throws: the preview looks right and only the STL/STEP is wrong, or vice-versa.
-- **Cause:** A `place` whose `purpose: "display"` and `"export"` branches differ by a non-rigid transform — `mirror` (flips handedness) or a non-identity `scale` (changes size) — so display and export are no longer the same solid, only its reflection/resize.
+- **Cause:** A legacy-form (`views` array + `place()`; the views-map form is checked by [view-pose-not-rigid](#view-pose-not-rigid)) `place` whose `purpose: "display"` and `"export"` branches differ by a non-rigid transform — `mirror` (flips handedness) or a non-identity `scale` (changes size) — so display and export are no longer the same solid, only its reflection/resize.
 - **Fix:** Keep the display-vs-export `place` difference a rigid motion (`translate`/`rotate`/`rotateAbout`/`along`/`at`) only. If the part genuinely needs a reflected or resized form, bake that into `build` so both purposes share one canonical solid and pose it rigidly. The rule sees a `place()` behind any `build()`, including one that queries the solid; a `place()` it cannot read stays silent. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "The `PartDefinition` contract".
 
+## view-entry-invalid
+
+- **Symptom:** A sub-part is missing from a view it names, and lint reports the entry.
+- **Cause:** A `views` map entry that is not `true` or a pose function — `false`, `null`, a string or an object.
+- **Fix:** Use `true` (shown as built) or `(s, p, d) => s.translate(…)`. To leave the piece out of a view, delete the key.
+
+## views-and-place
+
+- **Symptom:** Lint refuses a sub-part that declares a `views` map and `place`.
+- **Cause:** Two places a pose can live. With a map, each view's entry is its pose and `build()` is the export.
+- **Fix:** Move each view's pose into its entry and delete `place`. If the piece prints in a different orientation from how it is modelled, build it as it prints and move it into place in the `assembly` entry.
+
+## view-pose-not-rigid
+
+- **Symptom:** The piece in one view is a different size or a mirror image of the one exported.
+- **Cause:** A view entry that scales, mirrors or adds geometry instead of only moving the piece.
+- **Fix:** Entries only `translate`/`rotate`/`rotateAbout`/`at` their argument. Bake a resized or reflected form into `build()`.
+
+## views-invalid
+
+- **Symptom:** A sub-part is missing from every view, or lint refuses a sub-part whose `views` is absent, a string or a number.
+- **Cause:** `views` must be a map of view name to `true` or a pose (or, in the legacy form, an array of view names). Anything else shows the piece nowhere.
+- **Fix:** Give the sub-part a `views` map — e.g. `views: { assembly: true }` — naming each view it appears in.
+
 ## wrong-node-version
 
 - **Symptom:** Confusing failures during `npm install`, tests, or CLI runs — WASM load errors, syntax errors in dependencies, or kernels that never boot — on a machine that built fine before.

package/docs/KERNEL-CONTRACT.md

@@ -367,7 +367,7 @@ Normative signatures: `kernel.js`'s `@typedef Solid`.
 | Op | Contract |
 |---|---|
 | `cut(tool)` / `cutAll(tools[])` / `intersect(other)` / `union(other)` | Boolean subtract (single / batched), intersection, and union. |
-| `translate(v)` · `rotate(deg, center, axis)` · `mirror("XY"\|"XZ"\|"YZ")` · `scale(factor, center?)` | Transforms — but only two are **rigid** (pose): `translate`/`rotate` move a solid without altering it (position + orientation, shape and handedness preserved). `mirror` **reflects** — it returns the opposite-handed (chiral) solid, which no rotation can reproduce; `scale` **resizes**. So `mirror`/`scale` change the solid *itself*, not just where it sits — think of them as build operations, and never as the difference between a display pose and an export pose (see AUTHORING-PARTS.md `place`). `translate`/`rotate` are the primitives; the placement sugar below is composed *purely from them* (`solid-sugar.js`), so it is geometry-identical on every backend and a host gets it for free via `addSugar()`. |
+| `translate(v)` · `rotate(deg, center, axis)` · `mirror("XY"\|"XZ"\|"YZ")` · `scale(factor, center?)` | Transforms — but only two are **rigid** (pose): `translate`/`rotate` move a solid without altering it (position + orientation, shape and handedness preserved). `mirror` **reflects** — it returns the opposite-handed (chiral) solid, which no rotation can reproduce; `scale` **resizes**. So `mirror`/`scale` change the solid *itself*, not just where it sits — think of them as build operations, and never as the difference between a display pose and an export pose (see AUTHORING-PARTS.md, the `views` map). `translate`/`rotate` are the primitives; the placement sugar below is composed *purely from them* (`solid-sugar.js`), so it is geometry-identical on every backend and a host gets it for free via `addSugar()`. |
 | `rotateX(deg)` / `rotateY(deg)` / `rotateZ(deg)` · `rotateAbout({axis, deg, through?})` · `along(dir)` · `at(v)` | The readable placement vocabulary parts actually use. `along` maps the canonical +Z build axis to `"±X"\|"±Y"\|"±Z"`. |
 | `clone()` | Independent handle (see value semantics). |
 | `label(name)` | Name this solid's surface for feature attribution; must survive transforms and booleans; equal names merge into one feature. Affects mesh metadata only, never geometry. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.142.0",
+  "version": "0.143.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

package/src/framework/default-view.js

@@ -9,6 +9,7 @@
 // verify / renderViews) deliberately do NOT use this — they stay on
 // Object.keys(part.views)[0], where a mechanically obvious rule matters more than a
 // convenient one.
+import { inView } from "./sub-part-views.js";
 
 const isPlainObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
 
@@ -20,7 +21,7 @@ function placedCount(part, view, defaults) {
   const parts = isPlainObject(part?.parts) ? part.parts : {};
   let n = 0;
   for (const sp of Object.values(parts)) {
-    if (!Array.isArray(sp?.views) || !sp.views.includes(view)) continue;
+    if (!inView(sp, view)) continue;
     if (typeof sp.enabled !== "function") { n++; continue; }
     try { if (sp.enabled(defaults)) n++; } catch { n++; }
   }

package/src/framework/export/bed-layout.js

@@ -0,0 +1,62 @@
+// Where a multi-piece 3MF or STEP puts each views-map piece. Those formats write every
+// selected piece into one file, and a views-map piece exports AS BUILT — at its own
+// origin — so without a layout every piece would sit on top of the others
+// (spec 2026-10-04 "Export layout"). Translation only: orientation, layer lines and
+// the per-piece STL are untouched. Deterministic first-fit-decreasing-height shelves
+// over each piece's XY bounding box — the cut kit's packer (layout.js) without
+// rotation, sheets or margins — `spacing` apart, every piece resting at z = 0.
+// Legacy (array views + place) pieces never come here: their author placed them.
+import { resolveProfile } from "../oracle/dfm-profiles.js";
+import { formOf } from "../sub-part-views.js";
+import { isSheetPart } from "../sheet/constants.js";
+
+const EPS = 1e-9;
+export const BED_SPACING = 10;
+export const DEFAULT_BED_WIDTH = 220;
+const byKey = (a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
+
+export function bedLayout(boxes, { width, spacing = BED_SPACING } = {}) {
+  const items = boxes.map((b) => ({ ...b, w: b.max[0] - b.min[0], h: b.max[1] - b.min[1] }));
+  const W = Math.max(width ?? DEFAULT_BED_WIDTH, ...items.map((it) => it.w));
+  const order = [...items].sort((a, b) => b.h - a.h || b.w - a.w || byKey(a, b));
+  const shelves = []; // { y, h, x: used width, n: pieces }
+  const out = new Map();
+  for (const it of order) {
+    let shelf = shelves.find((s) => (s.n ? s.x + spacing : 0) + it.w <= W + EPS);
+    if (!shelf) {
+      const last = shelves.at(-1);
+      shelf = { y: last ? last.y + last.h + spacing : 0, h: it.h, x: 0, n: 0 };
+      shelves.push(shelf);
+    }
+    const x = shelf.n ? shelf.x + spacing : 0;
+    out.set(it.key, [x - it.min[0], shelf.y - it.min[1], -it.min[2]]);
+    shelf.x = x + it.w;
+    shelf.n++;
+  }
+  return out;
+}
+
+export function bedWidthFor(part) {
+  const process = part?.verify?.process;
+  if (!process) return null;
+  try {
+    const bed = resolveProfile(process)?.bed;
+    return Array.isArray(bed) && Number.isFinite(bed[0]) ? bed[0] : null;
+  } catch {
+    return null;
+  }
+}
+
+// `pieces`: [{ name, solid, ...rest }] in export order. Map-form pieces are laid out
+// together; legacy ones keep their export pose, and so do sheet pieces — a sheet's pose IS
+// its placement, so sheet exports come out assembled. Returns a new array, same order.
+export function layoutExportPieces(part, pieces) {
+  const laidOut = (sp) => formOf(sp) === "map" && !isSheetPart(sp);
+  const mapPieces = pieces.filter(({ name }) => laidOut(part.parts[name]));
+  if (mapPieces.length === 0) return pieces;
+  const offsets = bedLayout(
+    mapPieces.map(({ name, solid }) => ({ key: name, ...solid.boundingBox() })),
+    { width: bedWidthFor(part) },
+  );
+  return pieces.map((pc) => (offsets.has(pc.name) ? { ...pc, solid: pc.solid.translate(offsets.get(pc.name)) } : pc));
+}

package/src/framework/jobs.js

@@ -40,6 +40,9 @@ const loadInspect = () => Promise.all([
 // a session that never downloads a kit. test/worker-layering.test.js keeps every one of
 // them out of worker boot, and test/kit-layering.test.js keeps the kit off ./oracle/*.
 const loadBundle = () => import("./export/bundle.js");
+// The 3MF/STEP bed layout (export/bed-layout.js, which reads the DFM profile table) loads
+// the same way, on the first 3MF/STEP job.
+const loadBedLayout = () => import("./export/bed-layout.js");
 
 // HOST JOBS — the extension seam. A host registers its own job types with
 // `runWorker(part, { jobs: { <type>: handler } })`, threaded here as `opts.jobs`, and
@@ -496,21 +499,28 @@ export async function handle(kernel, part, msg, post, opts = {}) {
       post({ type: "download-parts", ext: "stl", mime: "model/stl", parts: out, jobId: msg.jobId },
            out.map((pp) => bufferOf(pp.data)));
     } else if (msg.type === "export-step") {
+      // 3MF/STEP hold every selected piece in one file; printed views-map pieces export as
+      // built, so they are laid out apart (export/bed-layout.js). Sheet pieces keep their
+      // assembled pose. STL is one file per piece and is never laid out.
       const names = selected();
       if (names.length === 0) throw new Error("no exportable parts selected");
-      const solids = names.map((name) => {
+      const { layoutExportPieces } = await loadBedLayout();
+      const solids = layoutExportPieces(part, names.map((name) => {
         onProgress(`building ${label(name)}`);
-        return { name: exportName(name), solid: posed(name, "export", onProgress), color: printColor(part.parts[name]?.display) };
-      });
+        return { name, solid: posed(name, "export", onProgress) };
+      })).map(({ name, solid }) => ({ name: exportName(name), solid, color: printColor(part.parts[name]?.display) }));
       onProgress("writing STEP file");
       const data = await kernel.toSTEP(solids);
       post({ type: "download", data, filename: `${fileBase}.step`, mime: "application/step", jobId: msg.jobId }, [bufferOf(data)]);
     } else if (msg.type === "export-3mf") {
       const names = selected();
       if (names.length === 0) throw new Error("no exportable parts selected");
-      const meshes = names.map((name) => {
+      const { layoutExportPieces } = await loadBedLayout();
+      const meshes = layoutExportPieces(part, names.map((name) => {
         onProgress(`building ${label(name)}`);
-        const { positions, indices } = posed(name, "export", onProgress).toIndexedMesh({ quality: msg.quality ?? "print" });
+        return { name, solid: posed(name, "export", onProgress) };
+      })).map(({ name, solid }) => {
+        const { positions, indices } = solid.toIndexedMesh({ quality: msg.quality ?? "print" });
         return { name: exportName(name), positions, indices, color: printColor(part.parts[name]?.display) };
       });
       onProgress("writing 3MF file");

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

@@ -13,6 +13,7 @@
 import { err, note } from "./finding.js";
 import { EASINGS } from "../animation.js";
 import { CANONICAL_VIEWS, CAMERA_CUE_VIEWS } from "../view-angles.js";
+import { inView } from "../sub-part-views.js";
 import { probeSubPartPose } from "../pose-probe-core.js";
 import { resolveDerivedAttributed } from "../derive.js";
 import { recorder, expandDerivedReads } from "../read-recorder.js";
@@ -246,8 +247,8 @@ export const ANIMATION_RULES = [
         rawSteps(a).forEach((s, i) => {
           for (const key of Object.keys(isPlainObject(s.opacity) ? s.opacity : {})) {
             const sub = isPlainObject(part?.parts) ? part.parts[key] : undefined;
-            const inView = isPlainObject(sub) && Array.isArray(sub.views) && sub.views.includes(view);
-            if (!inView) {
+            const listed = isPlainObject(sub) && inView(sub, view);
+            if (!listed) {
               out.push(err("animation-opacity-unknown-part",
                 `animation "${name}" fades "${key}", which is not a sub-part of view "${view}"`,
                 `Opacity tracks name sub-parts of the owning view — add "${view}" to \`parts.${key}.views\`, or correct the key.`,
@@ -524,7 +525,7 @@ export const ANIMATION_RULES = [
 function classifyTrack(part, p, key, v0, v1, view) {
   let result = "pose";
   for (const sp of Object.values(isPlainObject(part?.parts) ? part.parts : {})) {
-    if (!Array.isArray(sp?.views) || !sp.views.includes(view)) continue;
+    if (!inView(sp, view)) continue;
     const ends = [];
     for (const v of [v0, v1]) {
       const pv = { ...p, [key]: v };

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;

package/types/part.d.ts

@@ -350,6 +350,7 @@ export type DeriveSpec<P = ResolvedParams, D = Derived> =
 
 // --- sub-parts --------------------------------------------------------------
 
+/** The argument to the LEGACY `place` (views-array form); the `views` map form needs none. */
 export interface PlaceContext<P = ResolvedParams, D = Derived> {
   /** The active view. Display placement must NOT depend on it. */
   view: string;
@@ -367,12 +368,18 @@ export interface SubPartDefinition<P = ResolvedParams, D = Derived> {
    */
   build: (k: GeometryKernel, p: P, d: D, onProgress?: (phase: string) => void) => Solid;
   /**
-   * Optional reposition (default identity), for a part whose display pose
+   * LEGACY form (with a `views` array); with a `views` map put each pose in its
+   * entry instead. Optional reposition (default identity), for a part whose display pose
    * differs from its export pose. Any such difference must be a RIGID motion.
    */
   place?: (solid: Solid, ctx: PlaceContext<P, D>) => Solid;
-  /** Which views show this sub-part. Every name must exist in `views`. */
-  views: string[];
+  /**
+   * Each view the sub-part appears in: a map of view name to `true` (shown as
+   * built) or a rigid pose `(s, p, d) => s.translate(…)`. Every name must exist in
+   * the part's `views`. The legacy form, an array of names (placed by `place`),
+   * still works.
+   */
+  views: string[] | Record<string, true | ((s: Solid, p: P, d: D) => Solid)>;
   /** Gate a conditional sub-part. Coerced with `!!`. */
   enabled?: (p: P) => unknown;
   /** `false` = reference/preview-only: shown in the viewer, never exported. */