partforge 0.142.0 → 0.143.1

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.1",
   "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/geometry/probe.js

@@ -51,6 +51,29 @@ function makeProbe(onCall) {
     toSTL: () => new ArrayBuffer(0),
     toIndexedMesh: () => ({ positions: new Float32Array(9), indices: new Uint32Array(3) }),
   };
+  // Solid's optional mesh-topology queries return numbers/booleans, not a handle.
+  Object.assign(solidQueries, { genus: () => 0, isEmpty: () => false });
+  // Shape2D ops that return DATA rather than another Shape2D. Without an entry here an
+  // op falls through to the chaining branch and hands back the Shape2D handle itself,
+  // so ordinary array/number use of the result (`.corners().map(…)`, `.area() * 2`)
+  // was recorded as an unknown Shape2D op and failed lint as `unknown-solid-op`.
+  // `regions()` returns live Shape2Ds, so its dummy is an array holding the handle.
+  // The dummy region is a unit square in the contour IR (closed: last point = first).
+  const square = [[0, 0], [1, 0], [1, 1], [0, 1], [0, 0]];
+  const shape2dQueries = {
+    ...solidQueries,
+    isEmpty: () => false,
+    area: () => 1,
+    boundingBox: () => ({ min: [0, 0], max: [1, 1], center: [0.5, 0.5], size: [1, 1] }),
+    toRegions: () => [{ outer: square.map((p) => [...p]), holes: [] }],
+    simple: () => ({ outer: square.map((p) => [...p]), holes: [] }),
+    toContours: () => [{ outer: { start: [0, 0], segments: square.slice(1).map((p) => ({ to: [...p] })) }, holes: [] }],
+    corners: () => [0, 1, 2, 3].map((i) => ({
+      index: i, position: i, point: [...square[i]], interiorAngleDeg: 90, convex: true, segTypes: ["line", "line"],
+    })),
+    contains: () => false,
+    regions: () => [shape2d],
+  };
   const kernelQueries = {
     toSTEP: () => Promise.resolve(new ArrayBuffer(0)),
     cleanup: () => {},
@@ -82,10 +105,8 @@ function makeProbe(onCall) {
     },
   });
 
-  // Shape2D handles reuse solidQueries: boundingBox/volume/… dummies chain the same
-  // either way, and a 3-component bbox is as good a dummy as a 2-component one.
   const proxy = opProxy(solidQueries, "solid", () => proxy);   // a solid handle: every op chains back to itself
-  const shape2d = opProxy(solidQueries, "shape2d",
+  const shape2d = opProxy(shape2dQueries, "shape2d",
     (key) => (SOLID_YIELDING_SHAPE2D_OPS.has(key) ? proxy : shape2d));
   const kernel = opProxy(kernelQueries, "kernel",             // factory ops (cylinder/box/prism/…) return a solid
     (key) => (SHAPE2D_YIELDING_KERNEL_OPS.has(key) ? shape2d : proxy));

package/src/framework/imports.js

@@ -10,11 +10,21 @@ import { parse3MF } from "./geometry/threemf-parse.js";
 
 const EXT = { step: "step", stp: "step", stl: "stl", "3mf": "3mf" };
 
+// Font files declared as an import. Without this a TTF fell through to the STL
+// fallback below and failed as "binary STL truncated: header says 3848966777
+// triangles" — an error about a mesh the author never meant (cloud feedback #148).
+const FONT_EXT = new Set(["ttf", "otf", "woff", "woff2"]);
+const FONT_MAGIC = ["\x00\x01\x00\x00", "OTTO", "true", "ttcf", "wOFF", "wOF2"];
+
 export function detectFormat(source, bytes) {
   const path = source instanceof URL ? source.pathname : typeof source === "string" ? source.split("?")[0] : null;
   const ext = path?.match(/\.([A-Za-z0-9]+)$/)?.[1]?.toLowerCase();
-  if (ext && EXT[ext]) return EXT[ext];
   const u8 = bytes instanceof ArrayBuffer ? new Uint8Array(bytes) : bytes;
+  const magic = u8 && u8.length >= 4 ? String.fromCharCode(...u8.slice(0, 4)) : "";
+  if ((ext && FONT_EXT.has(ext)) || FONT_MAGIC.includes(magic)) {
+    throw new Error(`a font file${path ? ` ("${path}")` : ""} is declared under \`imports\` — declare it under \`fonts\` and use it with text2d`);
+  }
+  if (ext && EXT[ext]) return EXT[ext];
   if (u8 && u8.length > 0) {
     const head = String.fromCharCode(...u8.slice(0, 64));
     if (head.startsWith("ISO-10303-21")) return "step";

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 };