partforge 0.38.0 → 0.40.0

package/README.md

@@ -109,6 +109,9 @@ const runtime = mount(part, {
   onPick: ({ selection, label, prompt, token }) => {}, // programmatic click-to-select
 });
 await runtime.ready;   // first successful build (rejects on a first-build error)
+runtime.setHostPane("rail");  // narrow layout only: show just the controls
+                               // rail ('stage' | 'rail'), suppressing the
+                               // built-in tab bar. null hands selection back.
 runtime.dispose();     // stops loops, workers, observers, listeners; frees GPU resources
 ```
 

package/docs/ERROR-PATTERNS.md

@@ -215,6 +215,12 @@ Variant literals under this entry: `extrude: unknown bevel option`, `extrude: be
 - **Cause:** Only pages listed in `build.rollupOptions.input` are compiled by the production build; other root `*.html` pages are dev-only conveniences Vite serves without building.
 - **Fix:** Add the page to `build.rollupOptions.input` in `vite.config.js` if it should ship. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Wiring a part into a runnable app".
 
+## cutaway-capture-hatch-flood
+
+- **Symptom:** With cutaway enabled, a `captureCurrent`/`captureViews` image comes back with section hatch flooding a whole quad and burying the part, while the live viewer looks correct; a consumer may instead report the capture being rejected as too large, because full-frame hatch is worst-case JPEG content.
+- **Cause:** Cutaway masks its section caps with the stencil buffer, and a `THREE.WebGLRenderTarget` has none unless it asks for one — so the mask no-ops in offscreen renders even though the visible canvas (created with `stencil: true`) is fine.
+- **Fix:** Allocate offscreen render targets with `stencilBuffer: true` (`renderOffscreen` in `src/framework/viewer.js`); `scripts/check-app.mjs` measures hatch coverage in a real-GL capture to keep it that way.
+
 ## options-unknown-key
 
 - **Symptom:** `unknown option` — e.g. `cylinder: unknown option "radius" — did you mean r?`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.38.0",
+  "version": "0.40.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/app.css

@@ -190,6 +190,12 @@ button.action:focus-visible, .adv-toggle:focus-visible, #viewbar button:focus-vi
   font-size: 15px; line-height: 1;
   display: flex; align-items: center; justify-content: center;
 }
+/* the display: flex above is author-origin and beats the UA's [hidden] rule,
+   so any viewbar button hidden via the `hidden` property (today: #rail-toggle
+   below the narrow breakpoint, where the pane tab bar takes over) needs this
+   to actually disappear — the same trap .pf-cutaway-actions[hidden] below
+   already guards against. */
+#viewbar button[hidden] { display: none; }
 #viewbar .pf-cutaway-actions { display: flex; gap: 4px; }
 #viewbar .pf-cutaway-actions[hidden] { display: none; }
 #viewbar .pf-cutaway-actions button { width: auto; min-width: 56px; padding: 0 8px; }

package/src/framework/chrome.css

@@ -14,8 +14,8 @@
 
    Prerequisite: this sheet consumes --pf-* custom properties (--pf-rail-w,
    --pf-rail-pad, --pf-border, --pf-surface, --pf-bg, --pf-text, --pf-muted,
-   --pf-shadow-rail) but does not import them — a standalone consumer must
-   also load "partforge/tokens.css" (kept separate so the two stay
+   --pf-accent, --pf-shadow-rail) but does not import them — a standalone
+   consumer must also load "partforge/tokens.css" (kept separate so the two stay
    independently composable). The host is also responsible for giving
    .pf-shell a height (e.g. `height: 100%` on an ancestor chain rooted at
    `html, body`, or `position: absolute; inset: 0`); this sheet does not size
@@ -33,11 +33,21 @@
 
 /* ---- stage: the viewer column, which owns its floating chrome ------------
    min-width: 0 lets the column shrink past the canvas's intrinsic width, so
-   dragging the rail wider actually narrows the viewer instead of overflowing. */
+   dragging the rail wider actually narrows the viewer instead of overflowing.
+
+   min-height: 0 is the same escape hatch for the OTHER axis, and it is what
+   the narrow layout needs: there the shell is a column, so the canvas's
+   height — a real pixel height the renderer wrote, not an intrinsic 150px —
+   becomes this flex item's automatic minimum size. Without it the stage
+   refuses to shrink, and the tab bar below it is pushed off the bottom of
+   the screen: still display:flex, still in the DOM, simply not on screen.
+   That failure survived a `display` assertion in the smoke check, which is
+   why that check now asserts the bar is inside the viewport instead. */
 .pf-stage {
   flex: 1;
   position: relative;
   min-width: 0;
+  min-height: 0;
   background: var(--pf-bg);
 }
 
@@ -151,23 +161,78 @@
 .pf-float-tabs { top: 12px; left: 50%; transform: translateX(-50%); }
 .pf-float-viewbar { bottom: 12px; right: 12px; }
 
-/* ---- stacked layout: no room for a rail beside the viewer ----------------
-   The seam is hidden and resize is absent at this width (rail.js also refuses
-   to start a drag); the #rail-toggle still collapses and restores. */
+/* ---- the narrow-layout tab bar ------------------------------------------
+   Created by mobile-tabs.js (no host markup declares it). Hidden by default:
+   below the breakpoint the rail sits beside the viewer and needs no tab, so
+   the media query below is what reveals it.
+
+   The [hidden] rule is not redundant. `hidden` is how mobile-tabs.js stands
+   the bar down when a HOST owns pane selection, and the UA's
+   [hidden] { display: none } is a UA-origin rule that the media query's
+   author-origin display:flex would otherwise beat — leaving a second,
+   competing tab bar on screen inside the host's own. */
+.pf-tabbar {
+  display: none;
+  flex: none;
+  border-top: 1px solid var(--pf-border);
+  background: var(--pf-surface);
+  color: var(--pf-text);
+  /* The home indicator on a notched phone. Zero everywhere else. */
+  padding-bottom: env(safe-area-inset-bottom, 0px);
+}
+.pf-tabbar[hidden] { display: none; }
+.pf-tabbar button {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 2px;
+  padding: 6px 0;
+  border: 0;
+  background: transparent;
+  color: var(--pf-muted);
+  font: inherit;
+  font-size: 10px;
+  letter-spacing: 0.02em;
+  cursor: pointer;
+}
+.pf-tabbar button[aria-pressed="true"] { color: var(--pf-accent); }
+
+/* ---- narrow layout: ONE pane at a time, chosen by a tab bar ---------------
+   The old layout here stacked the rail as a 45vh strip under the viewer, which
+   left both panes too cramped to use on a phone. Instead the shell becomes a
+   column of [pane][tab bar] and shows exactly one pane, full height, keyed on
+   data-pf-pane (written by mobile-tabs.js, or by a host through its
+   setHostPane).
+
+   Written as :not([data-pf-pane="rail"]) so a MISSING attribute falls to the
+   stage rather than showing both panes at once — the layout is correct from
+   first paint, before any JS runs.
+
+   The seam stays hidden and resize is absent at this width (rail.js also
+   refuses to start a drag). Collapse has no meaning here either: rail.js
+   suppresses it entirely below this breakpoint, so there is deliberately no
+   .pf-rail[inert] rule left — nothing sets inert at this width. */
 @media (max-width: 719px) {
   .pf-shell { flex-direction: column; }
+  .pf-shell:not([data-pf-pane="rail"]) .pf-rail { display: none; }
+  .pf-shell[data-pf-pane="rail"] .pf-stage { display: none; }
+  /* Whichever pane shows fills the column. --pf-rail-w, the left border, and
+     the inset shadow all existed to make the rail read as a set-back right
+     EDGE; none of that means anything when the rail IS the whole surface. */
   .pf-rail {
-    width: auto; height: 45vh;
-    border-left: 0; border-top: 1px solid var(--pf-border);
+    flex: 1;
+    width: auto;
+    border-left: 0;
     box-shadow: none;
   }
   .pf-rail-seam { display: none; }
-  /* Collapsed, --pf-rail-w has no effect here (width is auto, height is 45vh),
-     so hide the rail outright — otherwise the toggle's first tap leaves a
-     full-size rail on screen that is inert and unresponsive. */
-  .pf-rail[inert] { display: none; }
+  .pf-tabbar { display: flex; }
 }
 
+
+
 /* ---- reduced motion -----------------------------------------------------
    Collapsing the rail slides 288px of layout across the screen — the first
    layout-scale animation in the framework, and the kind of movement a

package/src/framework/cutaway-gizmo.js

@@ -2,6 +2,7 @@ import * as THREE from "three";
 import {
   axisParameterFromRay,
   signedAngleAroundAxis,
+  snapQuaternionToAxis,
 } from "./cutaway-math.js";
 import { CUTAWAY_OVERLAY_RENDER_ORDER } from "./cutaway-render.js";
 
@@ -46,6 +47,7 @@ export function createCutawayGizmo({
   onPoseChange = () => {},
   onActivity = () => {},
   onHandleHoverChange = () => {},
+  onDragChange = () => {},
   pickHandle,
 }) {
   const group = new THREE.Group();
@@ -261,6 +263,7 @@ export function createCutawayGizmo({
   let activeAppearance = true;
   let themeMode = "dark";
   const raycaster = new THREE.Raycaster();
+  const _snapped = new THREE.Quaternion();
   const hitProxies = Object.values(handles);
 
   function rayFromEvent(event) {
@@ -326,6 +329,7 @@ export function createCutawayGizmo({
     drag = null;
     if (orbitControls) orbitControls.enabled = ending.orbitEnabled;
     safeRelease(ending.pointerId);
+    onDragChange(false);
   }
 
   function updateAppearance() {
@@ -361,6 +365,15 @@ export function createCutawayGizmo({
     onHandleHoverChange(normalized);
   }
 
+  // Rotation lands on a canonical axis when it gets close to one. Shift is read
+  // per move rather than latched at pointer-down, so it can be pressed and
+  // released mid-drag; it is unbound during a gizmo drag because orbit controls
+  // are already disabled.
+  function snapRotation(candidate, event) {
+    candidate.normalize();
+    return event.shiftKey ? candidate : snapQuaternionToAxis(candidate, undefined, _snapped);
+  }
+
   function notifyPose() {
     onPoseChange({
       position: group.position.clone(),
@@ -468,6 +481,7 @@ export function createCutawayGizmo({
     setHoveredHandle(handle);
     onActivity();
     drag = nextDrag;
+    onDragChange(true);
     if (orbitControls) orbitControls.enabled = false;
     safeCapture(event.pointerId);
     event.preventDefault();
@@ -512,7 +526,7 @@ export function createCutawayGizmo({
         * SCREEN_ROTATION_RADIANS_PER_PIXEL;
       if (!Number.isFinite(angle)) return;
       const delta = new THREE.Quaternion().setFromAxisAngle(drag.axis, angle);
-      group.quaternion.copy(delta.multiply(drag.startQuaternion)).normalize();
+      group.quaternion.copy(snapRotation(delta.multiply(drag.startQuaternion), event));
       group.position.copy(drag.startPosition);
       syncHandleTransform();
       notifyPose();
@@ -527,7 +541,7 @@ export function createCutawayGizmo({
     const angle = signedAngleAroundAxis(drag.startRadial, radial, drag.axis);
     if (!Number.isFinite(angle)) return;
     const delta = new THREE.Quaternion().setFromAxisAngle(drag.axis, angle);
-    group.quaternion.copy(delta.multiply(drag.startQuaternion)).normalize();
+    group.quaternion.copy(snapRotation(delta.multiply(drag.startQuaternion), event));
     group.position.copy(drag.startPosition);
     syncHandleTransform();
     notifyPose();

package/src/framework/cutaway-math.js

@@ -4,10 +4,38 @@ const PLANE_LOCAL_NORMAL = new THREE.Vector3(0, 0, 1);
 const POINT_EPSILON = 1e-6;
 const PARALLEL_EPSILON = 1e-6;
 
+// Nearest signed canonical axis (+/-X, +/-Y, +/-Z) to `direction`. Axes are
+// scanned X, Y, Z and replaced only on a strictly larger |component|, so a tie
+// resolves to the earlier axis — the default isometric framing is an exact tie
+// between -X and -Z and lands on -X. Degenerate input falls back to +Z.
+export function nearestCanonicalAxis(direction, target = new THREE.Vector3()) {
+  const components = [direction.x, direction.y, direction.z];
+  if (!components.every(Number.isFinite)) return target.set(0, 0, 1);
+
+  let bestIndex = -1;
+  let bestScore = 0;
+  for (let i = 0; i < 3; i++) {
+    const score = Math.abs(components[i]);
+    if (score > bestScore) {
+      bestScore = score;
+      bestIndex = i;
+    }
+  }
+  if (bestIndex < 0) return target.set(0, 0, 1);
+
+  // Built by setComponent rather than negating a unit axis: multiplying a zero
+  // component by -1 yields -0, and toEqual([0, -1, 0]) does not accept -0.
+  return target.set(0, 0, 0).setComponent(bestIndex, components[bestIndex] < 0 ? -1 : 1);
+}
+
 export function initialCutawayPose(box, camera) {
   const position = box.getCenter(new THREE.Vector3());
   const diagonal = Math.max(box.getSize(new THREE.Vector3()).length(), 1);
-  const normal = camera.getWorldDirection(new THREE.Vector3()).normalize();
+  // Square the cut plane up with the part rather than the camera: the axis
+  // nearest the view direction, so the near half is still what gets cut away.
+  const normal = nearestCanonicalAxis(
+    camera.getWorldDirection(new THREE.Vector3()).normalize(),
+  );
   const quaternion = new THREE.Quaternion().setFromUnitVectors(
     PLANE_LOCAL_NORMAL,
     normal,
@@ -20,6 +48,27 @@ export function initialCutawayPose(box, camera) {
   };
 }
 
+export const AXIS_SNAP_RADIANS = (7 * Math.PI) / 180;
+
+// Pull a plane pose onto the nearest canonical axis once its normal is within
+// `maxAngle` of one. The correction is the minimal rotation carrying the normal
+// onto the axis, not a rebuilt quaternion, so the plane's in-plane roll survives
+// and the gizmo rings do not visibly spin at the moment of snapping. Roll does
+// not affect the clip either way.
+export function snapQuaternionToAxis(
+  quaternion,
+  maxAngle = AXIS_SNAP_RADIANS,
+  target = new THREE.Quaternion(),
+) {
+  const normal = PLANE_LOCAL_NORMAL.clone().applyQuaternion(quaternion).normalize();
+  const axis = nearestCanonicalAxis(normal);
+  if (normal.angleTo(axis) > maxAngle) return target.copy(quaternion);
+  return target
+    .setFromUnitVectors(normal, axis)
+    .multiply(quaternion)
+    .normalize();
+}
+
 export function planeFromPose(plane, normalTarget, position, quaternion, flipped) {
   normalTarget.copy(PLANE_LOCAL_NORMAL).applyQuaternion(quaternion).normalize();
   if (flipped) normalTarget.negate();

package/src/framework/cutaway-outline.js

@@ -0,0 +1,233 @@
+import * as THREE from "three";
+import { LineMaterial } from "three/addons/lines/LineMaterial.js";
+import { LineSegments2 } from "three/addons/lines/LineSegments2.js";
+import { LineSegmentsGeometry } from "three/addons/lines/LineSegmentsGeometry.js";
+
+// Matches POINT_EPSILON in cutaway-math.js: a vertex this close to the plane
+// counts as lying on it, so a grazing plane produces neither duplicate nor
+// zero-length segments.
+const ON_PLANE_EPSILON = 1e-6;
+
+const _vertices = [new THREE.Vector3(), new THREE.Vector3(), new THREE.Vector3()];
+const _distances = [0, 0, 0];
+const _signs = [0, 0, 0];
+const _crossing = new THREE.Vector3();
+
+// Plane/triangle intersection over a BufferGeometry, in the geometry's own
+// frame. Emits one segment per crossing triangle. Handles indexed (OCCT) and
+// non-indexed (Manifold) geometry alike.
+//
+// Degenerate contact is resolved so each boundary edge is emitted exactly once:
+//   - a triangle lying in the plane emits nothing; its neighbours bound it;
+//   - a triangle touching the plane at one vertex only emits nothing;
+//   - a triangle with an edge in the plane emits that edge only when its third
+//     vertex is on the clipped side, so the two triangles sharing that edge do
+//     not both emit it.
+//
+// Known limitation: that last rule reads only its own triangle, so it cannot
+// tell "the neighbour is on the other side" (a real crossing, one emission)
+// from "the neighbour is also clipped" (a ridge merely tangent to the plane,
+// two emissions of the same edge). Telling them apart needs per-slice edge
+// bookkeeping on a path that runs every frame of a gizmo drag, and the payoff
+// is small: the duplicates are coincident, so they are invisible on opaque
+// parts and only slightly darken a translucent one, in the measure-zero case
+// where a plane lands exactly on a crease.
+export function sectionSegments(geometry, plane) {
+  const position = geometry?.getAttribute?.("position");
+  if (!position) return new Float32Array(0);
+
+  const index = geometry.getIndex?.() ?? null;
+  const count = index ? index.count : position.count;
+  const out = [];
+
+  for (let i = 0; i + 2 < count; i += 3) {
+    for (let k = 0; k < 3; k++) {
+      _vertices[k].fromBufferAttribute(position, index ? index.getX(i + k) : i + k);
+      const distance = plane.distanceToPoint(_vertices[k]);
+      _distances[k] = distance;
+      _signs[k] = distance > ON_PLANE_EPSILON
+        ? 1
+        : distance < -ON_PLANE_EPSILON ? -1 : 0;
+    }
+
+    const onPlane = (_signs[0] === 0 ? 1 : 0)
+      + (_signs[1] === 0 ? 1 : 0)
+      + (_signs[2] === 0 ? 1 : 0);
+
+    if (onPlane === 3) continue;
+
+    if (onPlane === 2) {
+      const solo = _signs[0] !== 0 ? 0 : _signs[1] !== 0 ? 1 : 2;
+      if (_signs[solo] !== -1) continue;
+      pushPoint(out, _vertices[(solo + 1) % 3]);
+      pushPoint(out, _vertices[(solo + 2) % 3]);
+      continue;
+    }
+
+    if (onPlane === 1) {
+      const zero = _signs[0] === 0 ? 0 : _signs[1] === 0 ? 1 : 2;
+      const a = (zero + 1) % 3;
+      const b = (zero + 2) % 3;
+      if (_signs[a] === _signs[b]) continue;
+      pushPoint(out, _vertices[zero]);
+      pushPoint(out, crossingPoint(a, b));
+      continue;
+    }
+
+    if (_signs[0] === _signs[1] && _signs[1] === _signs[2]) continue;
+    for (let k = 0; k < 3; k++) {
+      const a = k;
+      const b = (k + 1) % 3;
+      if (_signs[a] === _signs[b]) continue;
+      pushPoint(out, crossingPoint(a, b));
+    }
+  }
+
+  return new Float32Array(out);
+}
+
+function crossingPoint(a, b) {
+  const t = _distances[a] / (_distances[a] - _distances[b]);
+  return _crossing.copy(_vertices[a]).lerp(_vertices[b], t);
+}
+
+function pushPoint(out, point) {
+  out.push(point.x, point.y, point.z);
+}
+
+const defaultNow = () => (typeof performance !== "undefined" ? performance.now() : 0);
+
+// One cut-face outline for one subpart. The object is parented to the mesh, the
+// same trick the stencil helpers use, so it inherits every present and future
+// transform including the pose fast path — and it always slices whatever
+// `mesh.geometry` currently draws, so the outline cannot disagree with the
+// surface it bounds.
+//
+// The section moves for four unrelated reasons (plane pose, geometry swap,
+// frameTo recentring the assembly under a world-fixed plane, and setSubPose),
+// and only the first two notify the cutaway. Rather than thread invalidation
+// through all four, refresh() compares a signature and re-slices when it
+// differs — roughly 21 float compares per frame.
+export function createSectionOutline({ mesh, plane, inkColor, now = defaultNow }) {
+  const material = new LineMaterial({
+    color: inkColor,
+    linewidth: 1,
+    // The outline lies exactly in the cap plane; pull it toward the viewer so
+    // the coincident-depth line wins against the cap it sits in.
+    polygonOffset: true,
+    polygonOffsetFactor: -1,
+    polygonOffsetUnits: -1,
+  });
+  material.resolution.set(1, 1);
+  // Deliberately no clippingPlanes: the outline sits at distance ~0 from its
+  // own plane, and clipping it would speckle.
+
+  const object = new LineSegments2(new LineSegmentsGeometry(), material);
+  object.frustumCulled = false;
+  object.visible = false;
+  mesh.add(object);
+
+  const localPlane = new THREE.Plane();
+  const inverse = new THREE.Matrix4();
+  const lastNormal = new THREE.Vector3(NaN, NaN, NaN);
+  const lastMatrix = new THREE.Matrix4();
+  let lastConstant = NaN;
+  let lastGeometry = null;
+  let lastCost = 0;
+  let hasSegments = false;
+  let visible = false;
+  let suppressed = false;
+  let disposed = false;
+  // A show transition (setVisible(true) / setSuppressed(false)) must not put
+  // the last slice on screen if the plane or mesh moved while hidden - that
+  // slice belongs to a pose nobody asked to see. Cleared once slice() has
+  // caught up; markShown() below leaves it alone when nothing moved, so an
+  // ordinary show doesn't wait on a needless re-slice.
+  let needsSlice = true;
+
+  function applyVisibility() {
+    object.visible = visible && hasSegments && !suppressed && !disposed && !needsSlice;
+  }
+
+  // Same signature the plane/mesh state is judged by in refresh(), reused so
+  // a show transition can tell "still matches the last slice" from "moved
+  // while hidden" without duplicating that comparison.
+  function signatureMatches(geometry, matrixWorld) {
+    return geometry === lastGeometry
+      && plane.constant === lastConstant
+      && plane.normal.equals(lastNormal)
+      && matrixWorld.equals(lastMatrix);
+  }
+
+  function markShown() {
+    mesh.updateWorldMatrix(true, false);
+    if (!signatureMatches(mesh.geometry, mesh.matrixWorld)) needsSlice = true;
+  }
+
+  function slice(geometry, matrixWorld) {
+    const start = now();
+    localPlane.copy(plane).applyMatrix4(inverse.copy(matrixWorld).invert());
+    const segments = geometry
+      ? sectionSegments(geometry, localPlane)
+      : new Float32Array(0);
+    hasSegments = segments.length > 0;
+    const previous = object.geometry;
+    const next = new LineSegmentsGeometry();
+    if (hasSegments) next.setPositions(segments);
+    object.geometry = next;
+    previous?.dispose();
+    lastCost = now() - start;
+    needsSlice = false;
+    applyVisibility();
+  }
+
+  function refresh() {
+    if (disposed || !visible || suppressed) return false;
+    mesh.updateWorldMatrix(true, false);
+    const geometry = mesh.geometry;
+    if (signatureMatches(geometry, mesh.matrixWorld)) return false;
+    lastGeometry = geometry;
+    lastConstant = plane.constant;
+    lastNormal.copy(plane.normal);
+    lastMatrix.copy(mesh.matrixWorld);
+    slice(geometry, mesh.matrixWorld);
+    return true;
+  }
+
+  return {
+    object,
+    refresh,
+    sliceCost: () => lastCost,
+    setVisible(on) {
+      if (disposed) return;
+      visible = Boolean(on);
+      if (visible) markShown();
+      applyVisibility();
+    },
+    setSuppressed(on) {
+      if (disposed) return;
+      suppressed = Boolean(on);
+      if (!suppressed) markShown();
+      applyVisibility();
+    },
+    setInk(color) {
+      if (!disposed) material.color.set(color);
+    },
+    setTransparent(on) {
+      if (disposed || material.transparent === Boolean(on)) return;
+      material.transparent = Boolean(on);
+      material.needsUpdate = true;
+    },
+    setViewportSize(width, height) {
+      if (!disposed) material.resolution.set(width, height);
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      object.visible = false;
+      mesh.remove(object);
+      object.geometry?.dispose();
+      material.dispose();
+    },
+  };
+}

package/src/framework/cutaway-render.js

@@ -1,5 +1,7 @@
 import * as THREE from "three";
 
+import { createSectionOutline } from "./cutaway-outline.js";
+
 export const HATCH_PERIOD_CSS_PX = 5;
 export const HATCH_LINE_CSS_PX = 1;
 
@@ -9,6 +11,7 @@ export const HATCH_LINE_CSS_PX = 1;
 const SURFACE_ORDER_BASE = 1_000_000;
 const EDGE_ORDER_BASE = 2_000_000;
 const SECTION_ORDER_STRIDE = 2;
+export const OUTLINE_ORDER_BASE = 2_500_000;
 export const CUTAWAY_OVERLAY_RENDER_ORDER = 3_000_000;
 
 export function createHatchMaterial({ color, opacity, inkColor }) {
@@ -122,6 +125,7 @@ export function createSectionRenderSet({
   capGeometry,
   order,
   inkColor,
+  now,
 }) {
   let originalMeshMaterial = mesh.material;
   let originalEdgeMaterial = edgeLines?.material;
@@ -187,6 +191,13 @@ export function createSectionRenderSet({
   front.renderOrder = stencilOrder;
   cap.renderOrder = stencilOrder + 1;
 
+  // Cut-face outline: real 3D segments sliced from the mesh, drawn with the
+  // same fat-line renderer as the viewer's feature edges. Ordered above the
+  // clipped edges so it wins the coincident depth against its own cap.
+  const outline = createSectionOutline({ mesh, plane, inkColor, now });
+  outline.object.renderOrder = OUTLINE_ORDER_BASE + order;
+  outline.setTransparent(capMaterial.transparent);
+
   let enabled = false;
   let visible = mesh.visible;
   let disposed = false;
@@ -196,6 +207,7 @@ export function createSectionRenderSet({
     back.visible = on;
     front.visible = on;
     cap.visible = on;
+    outline.setVisible(on);
   }
 
   back.visible = false;
@@ -245,12 +257,14 @@ export function createSectionRenderSet({
   function setHatchInk(color) {
     if (disposed) return;
     capMaterial.userData.setInkColor(color);
+    outline.setInk(color);
   }
 
   function setViewportSize(width, height, pixelRatio = 1) {
     if (disposed) return;
     viewportSize = { width, height, pixelRatio };
     setLineResolution(clippedEdgeMaterial, width, height);
+    outline.setViewportSize(width, height);
     capMaterial.userData.setScreenScale(pixelRatio);
   }
 
@@ -302,6 +316,7 @@ export function createSectionRenderSet({
     backMaterial.transparent = capMaterial.transparent;
     frontMaterial.transparent = capMaterial.transparent;
     if (clippedEdgeMaterial && capMaterial.transparent) makeTransparent(clippedEdgeMaterial);
+    outline.setTransparent(capMaterial.transparent);
 
     if (enabled) {
       mesh.material = clippedMeshMaterial;
@@ -319,6 +334,7 @@ export function createSectionRenderSet({
     disposed = true;
     mesh.remove(back, front);
     scene.remove(cap);
+    outline.dispose();
     for (const material of ownedMaterials) material.dispose();
   }
 
@@ -326,6 +342,7 @@ export function createSectionRenderSet({
     back,
     front,
     cap,
+    outline,
     setEnabled,
     setVisible,
     setGeometry,
@@ -333,6 +350,9 @@ export function createSectionRenderSet({
     setHatchInk,
     setViewportSize,
     refreshSourceMaterial,
+    refreshOutline: outline.refresh,
+    outlineSliceCost: outline.sliceCost,
+    setOutlineSuppressed: outline.setSuppressed,
     dispose,
   };
 }

package/src/framework/cutaway.js

@@ -10,6 +10,11 @@ import { createSectionRenderSet } from "./cutaway-render.js";
 
 const IDLE_DELAY_MS = 800;
 
+// Slicing rides on top of everything else in the frame, so the whole visible
+// assembly gets about an eighth of a 60 fps frame before outlines step aside
+// for the duration of a drag.
+export const OUTLINE_SLICE_BUDGET_MS = 2;
+
 function defaultSchedule(callback, delay) {
   const timer = setTimeout(callback, delay);
   return () => clearTimeout(timer);
@@ -33,6 +38,7 @@ export function createCutaway({
   getBounds,
   edgeColor,
   schedule = defaultSchedule,
+  now,
 }) {
   let supported = false;
   try {
@@ -61,6 +67,7 @@ export function createCutaway({
   let previousLocalClippingEnabled;
   let disposed = false;
   let disabling = false;
+  let outlinesSuppressed = false;
   let hoveredHandle = null;
   const handleHoverSubscribers = new Set();
   const pendingHandlePublications = [];
@@ -218,6 +225,7 @@ export function createCutaway({
     onPoseChange,
     onActivity: showActive,
     onHandleHoverChange: publishHandleHover,
+    onDragChange: setDragging,
   });
   gizmo.setVisible(false);
   gizmo.setTheme(theme);
@@ -236,6 +244,7 @@ export function createCutaway({
       capGeometry,
       order,
       inkColor: hatchInk,
+      now,
     });
     renderSets.set(name, { renderSet, mesh, edgeLines, order });
     if (viewportSize) {
@@ -248,6 +257,7 @@ export function createCutaway({
     applyCapPose(renderSet);
     renderSet.setVisible(enabled && selected(name));
     renderSet.setEnabled(enabled);
+    renderSet.setOutlineSuppressed(outlinesSuppressed);
     return true;
   }
 
@@ -402,8 +412,42 @@ export function createCutaway({
     };
   }
 
+  // Per-frame maintenance while the cutaway is on: the gizmo rescales for the
+  // camera, and every visible section re-slices its outline if anything it
+  // depends on moved. Both are cheap no-ops when nothing changed.
+  function refreshSections() {
+    for (const { renderSet } of renderSets.values()) renderSet.refreshOutline();
+  }
+
+  // Outlines re-slice on every frame of a gizmo drag. On heavy assemblies that
+  // is the one place the cost could show, so decide once at drag start — from
+  // costs already measured, so the drag never pays a spike to discover it is
+  // too expensive — and hide all of them or none. Half-outlined assemblies read
+  // as broken. Only sections that are actually showing count toward the budget:
+  // a hidden section's refresh() early-returns without slicing, so its cost
+  // entry is whatever was last measured while it *was* visible — stale, and
+  // irrelevant to what the drag will actually spend time on.
+  function setDragging(active) {
+    if (disposed) return;
+    if (active) {
+      let total = 0;
+      for (const [name, { renderSet }] of renderSets) {
+        if (enabled && selected(name)) total += renderSet.outlineSliceCost();
+      }
+      outlinesSuppressed = total > OUTLINE_SLICE_BUDGET_MS;
+    } else {
+      outlinesSuppressed = false;
+    }
+    for (const { renderSet } of renderSets.values()) {
+      renderSet.setOutlineSuppressed(outlinesSuppressed);
+    }
+    if (!active) refreshSections();
+  }
+
   function updateForCamera() {
-    if (enabled && !disposed) gizmo.updateForCamera();
+    if (!enabled || disposed) return;
+    gizmo.updateForCamera();
+    refreshSections();
   }
 
   function renderOverlay(targetRenderer, targetCamera) {
@@ -465,5 +509,7 @@ export function createCutaway({
     renderOverlay,
     onHandleHoverChange,
     dispose,
+    _renderSetFor: (name) => renderSets.get(name)?.renderSet ?? null,
+    _setDragging: setDragging,
   };
 }

package/src/framework/mobile-tabs.js

@@ -0,0 +1,138 @@
+// The narrow-layout pane tab bar. Below RAIL_NARROW_BREAKPOINT there is no room
+// for a rail beside the viewer, so the shell shows exactly ONE pane and this bar
+// chooses which. chrome.css owns the layout, keyed on the data-pf-pane attribute
+// this module writes onto .pf-shell; a missing attribute reads as "stage", so
+// the layout is already correct before any of this runs.
+//
+// Two independent reasons the bar can be absent, and they are deliberately
+// handled by different mechanisms:
+//   * WIDTH — above the breakpoint the rail sits beside the viewer and no tab is
+//     needed. That is pure CSS (.pf-tabbar { display: none }). There is no JS
+//     media-query bookkeeping in this file at all, and no resize listener.
+//   * A HOST owns pane selection — partforge-cloud draws its own bottom bar at
+//     the window level and drives this layout through setHostPane(). Then our
+//     bar is `hidden` and only the host's choice writes data-pf-pane.
+//
+// State is in-memory: a fresh load starts on the stage, and nothing persists.
+// Which pane you are looking at right now is not a preference.
+//
+// The DOM is created here, so no host markup declares it — same contract as
+// rail.js's seam, and the reason this composes with partforge-cloud's
+// hand-built sandbox scaffold without that scaffold knowing anything about it.
+const SVG_NS = "http://www.w3.org/2000/svg";
+
+// Hand-authored in lucide's 24x24 / 2px-stroke idiom so these sit beside
+// rail.js's toggle icon without introducing a second icon vocabulary (and
+// without a dependency for three glyphs). `stroke="currentColor"` is
+// load-bearing: it is how each icon picks up its button's themed colour, and
+// the accent colour of the pressed state, with no icon-specific CSS anywhere.
+const ICONS = {
+  // A box: the part itself.
+  stage: [
+    "M21 8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16Z",
+    "m3.3 7 8.7 5 8.7-5",
+    "M12 22V12",
+  ],
+  // Three horizontal sliders: the parameter controls.
+  rail: [
+    "M21 4h-7", "M10 4H3", "M21 12h-9", "M8 12H3", "M21 20h-5", "M12 20H3",
+    "M14 2v4", "M8 10v4", "M16 18v4",
+  ],
+};
+const LABELS = { stage: "3D", rail: "Controls" };
+const PANES = ["stage", "rail"];
+
+function buildIcon(paths) {
+  const svg = document.createElementNS(SVG_NS, "svg");
+  svg.setAttribute("viewBox", "0 0 24 24");
+  svg.setAttribute("width", "20");
+  svg.setAttribute("height", "20");
+  svg.setAttribute("fill", "none");
+  svg.setAttribute("stroke", "currentColor");
+  svg.setAttribute("stroke-width", "2");
+  svg.setAttribute("stroke-linecap", "round");
+  svg.setAttribute("stroke-linejoin", "round");
+  // Decorative: every button carries a visible text label already.
+  svg.setAttribute("aria-hidden", "true");
+  for (const d of paths) {
+    const path = document.createElementNS(SVG_NS, "path");
+    path.setAttribute("d", d);
+    svg.append(path);
+  }
+  return svg;
+}
+
+// role="group" + aria-pressed, NOT role="tablist": a real tablist owes its tabs
+// aria-controls'd tabpanels, and .pf-stage / .pf-rail are host-built DOM this
+// module does not own and must not relabel. Two pressed-state buttons describe
+// what this actually is without promising semantics we cannot honour.
+//
+// Everything is optional, like attachRail: with no shell to manage this returns
+// a no-op handle, so a legacy id-only page or a host that lays the framework out
+// itself (embed-test.html) is unaffected — including its setHostPane, which
+// stays a callable no-op so mount()'s handle shape never varies.
+export function attachMobileTabs({ shell, stage, rail } = {}) {
+  if (!shell || !stage || !rail) {
+    return { setHostPane: () => {}, detach: () => {} };
+  }
+
+  let pane = "stage"; // the standalone user's choice
+  let hostPane = null; // a host's lease over that choice, while non-null
+
+  const bar = document.createElement("div");
+  bar.className = "pf-tabbar";
+  bar.setAttribute("role", "group");
+  bar.setAttribute("aria-label", "Viewer panes");
+  const buttons = new Map();
+  for (const p of PANES) {
+    const button = document.createElement("button");
+    button.type = "button";
+    button.dataset.pfPaneTab = p;
+    button.title = LABELS[p];
+    button.append(buildIcon(ICONS[p]));
+    const label = document.createElement("span");
+    label.textContent = LABELS[p];
+    button.append(label);
+    bar.append(button);
+    buttons.set(p, button);
+  }
+  // Last child of the shell: in the narrow layout .pf-shell is a column, so the
+  // bar lands under whichever pane is showing. Above the breakpoint it is
+  // display:none and its position in the flex row is moot.
+  shell.append(bar);
+
+  function apply() {
+    const active = hostPane ?? pane;
+    shell.dataset.pfPane = active;
+    for (const [p, button] of buttons) {
+      button.setAttribute("aria-pressed", String(p === active));
+    }
+    // A host that owns pane selection draws its own control; ours would be a
+    // second, competing one.
+    bar.hidden = hostPane !== null;
+  }
+
+  // Delegated, so the icon <svg>/<span> inside a button resolve to the button.
+  const onClick = (e) => {
+    const next = e.target?.closest?.("[data-pf-pane-tab]")?.dataset?.pfPaneTab;
+    if (!PANES.includes(next)) return;
+    pane = next;
+    apply();
+  };
+  bar.addEventListener("click", onClick);
+  apply();
+
+  return {
+    // 'stage' | 'rail' takes the lease; anything else (including null) releases
+    // it and restores the standalone bar and the user's own last choice.
+    setHostPane: (next) => {
+      hostPane = PANES.includes(next) ? next : null;
+      apply();
+    },
+    detach: () => {
+      bar.removeEventListener("click", onClick);
+      bar.remove();
+      delete shell.dataset.pfPane;
+    },
+  };
+}

package/src/framework/mount.js

@@ -4,6 +4,7 @@ import { createViewer } from "./viewer.js";
 import { attachViewerControls } from "./viewer-controls.js";
 import { attachCutawayControls } from "./cutaway-controls.js";
 import { attachRail } from "./rail.js";
+import { attachMobileTabs } from "./mobile-tabs.js";
 import { createTooltipPresenter } from "./tooltip.js";
 import { loadCamera } from "./view-state.js";
 import { buildControls } from "./controls.js";
@@ -25,13 +26,17 @@ import { createExportController } from "./export-controller.js";
 
 // The mount handle, factored out so its shape is unit-testable without booting
 // the full mount() pipeline (WASM + workers + DOM).
-export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts }) {
+export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane }) {
   return {
     ready, dispose, setParams,
     captureViews: (viewNames) => viewer.captureCanonicalViews(viewNames),
     captureCurrent: (opts) => viewer.captureCurrent(opts),
     listExportableParts,
     exportParts,
+    // Narrow-layout pane selection, for a host that draws its own tab bar
+    // (partforge-cloud does, at the window level). Defaulted to a no-op so the
+    // handle's shape never depends on whether this mount resolved a rail.
+    setHostPane: setHostPane ?? (() => {}),
   };
 }
 
@@ -64,7 +69,7 @@ function createCleanupStack() {
 // mesh-validity cache, and the geometry workers. The app supplies `createWorker(name)`
 // so Vite can bundle the worker (see geometry-service.js).
 //
-// Embedding contract (0.38.0):
+// Embedding contract (0.39.0):
 //   const runtime = mount(part, { createWorker, elements, onBuild, onPick, onDownload });
 //   await runtime.ready;   // first successful build of the default view
 //   runtime.setParams({ openAngle: 45 }); // programmatic edit; pose-only changes apply instantly
@@ -78,6 +83,9 @@ function createCleanupStack() {
 //                                         // headless export of a chosen subset; resolves when the file is
 //                                         // written (handed to your onDownload sink, or downloaded directly
 //                                         // if you don't supply one), rejects on failure
+//   runtime.setHostPane("rail");  // narrow layout only: show just the controls
+//                                 // rail ('stage' | 'rail'), suppressing the
+//                                 // built-in tab bar. null hands selection back.
 //   runtime.dispose();     // full teardown
 // onBuild fires per completed build, so it does NOT fire for a pose-only edit —
 // those are repaired in the viewer and produce no build at all.
@@ -133,6 +141,16 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     // framework itself (no #panel / no elements.rail).
     const railChrome = attachRail({ rail: els.rail, toggle: els.chrome.railToggle, shell: els.shell });
     cleanup.defer(() => railChrome.detach());
+    // Narrow-layout pane tabs. Below RAIL_NARROW_BREAKPOINT the rail cannot sit
+    // beside the viewer, so exactly one pane shows and this bar picks it. Same
+    // resolution and same no-op-when-absent contract as the rail above — the
+    // shell default mirrors attachRail's (rail.parentElement).
+    const paneTabs = attachMobileTabs({
+      shell: els.shell ?? els.rail?.parentElement,
+      stage: els.viewer,
+      rail: els.rail,
+    });
+    cleanup.defer(() => paneTabs.detach());
     const hover = attachHoverLabels(viewer, { part, tooltip }); // always-on hover inspection (no-op on touch-only devices)
     cleanup.defer(() => hover.detach());
     const ui = createStatusUi({ ...els.status, exports: [els.exports.stl, els.exports.step, els.exports.threeMf] });
@@ -448,6 +466,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
 
     return makeHandle({
       ready, dispose, viewer, setParams,
+      setHostPane: paneTabs.setHostPane,
       listExportableParts: () =>
         exportablePartNames(part, params).map((name) => ({ name, label: partLabel(part, name) })),
       exportParts: (opts) => exportCtl.exportParts(opts),

package/src/framework/rail.js

@@ -96,7 +96,9 @@ export function attachRail({ rail, toggle, shell = rail?.parentElement, storage
   // hand back a plain, unwired button rather than a dead "Show controls" one.
   // innerHTML (not textContent) so a host's original content - markup, not
   // just text - genuinely round-trips; the icon apply() writes is markup too.
-  const toggleOriginal = toggle ? { html: toggle.innerHTML, title: toggle.title } : null;
+  const toggleOriginal = toggle
+    ? { html: toggle.innerHTML, title: toggle.title, hidden: toggle.hidden }
+    : null;
   // Built once here rather than inside apply() (which reruns on every resize/
   // key/drag tick); apply() only ever swaps toggleChevron's `d`.
   let toggleChevron = null;
@@ -123,7 +125,17 @@ export function attachRail({ rail, toggle, shell = rail?.parentElement, storage
   // flush, not a cached value.
   function apply({ persist = false, shellW } = {}) {
     const sw = shellW ?? shellWidth();
-    const width = state.collapsed ? 0 : clampRailWidth(state.width, sw);
+    // Below the breakpoint the shell shows exactly ONE pane (chrome.css, keyed
+    // on data-pf-pane) and mobile-tabs.js picks it, so collapse has no meaning:
+    // a persisted `collapsed: true` must not make the Controls tab land on an
+    // inert, invisible rail. `state` is deliberately NOT rewritten — the stored
+    // preference applies again the moment the window widens.
+    const narrow = window.innerWidth < RAIL_NARROW_BREAKPOINT;
+    const collapsed = state.collapsed && !narrow;
+    // Narrow: the rail is either the whole surface or absent, so it reserves no
+    // width beside the viewer — and anything centring itself against the rail
+    // (app.css's #pf-pick-banner) must not be offset by a stale 288px.
+    const width = collapsed || narrow ? 0 : clampRailWidth(state.width, sw);
     // Written on :root, not the rail/shell, so body-appended overlays (the
     // pick banner, the ?debug overlay) inherit it — see spec §4.4. This
     // assumes ONE rail per document: attachRail is written for a single
@@ -133,17 +145,20 @@ export function attachRail({ rail, toggle, shell = rail?.parentElement, storage
     // multiple mount() calls in general (e.g. cross-fade swaps), which is
     // fine as long as at most one has a resolvable rail at a time.
     root.style.setProperty("--pf-rail-w", `${width}px`);
-    rail.toggleAttribute("inert", state.collapsed);
-    seam.toggleAttribute("data-collapsed", state.collapsed);
+    rail.toggleAttribute("inert", collapsed);
+    seam.toggleAttribute("data-collapsed", collapsed);
     seam.setAttribute("aria-valuenow", String(width));
     seam.setAttribute("aria-valuemax", String(railMaxWidth(sw)));
     if (toggle) {
-      toggleChevron?.setAttribute("d", state.collapsed ? CHEVRON_RAIL_COLLAPSED : CHEVRON_RAIL_OPEN);
-      const label = state.collapsed ? "Show controls" : "Hide controls";
-      toggle.setAttribute("aria-expanded", String(!state.collapsed));
+      // The tab bar owns pane selection below the breakpoint, so a second
+      // collapse affordance in the viewbar would be a competing control.
+      toggle.hidden = narrow;
+      toggleChevron?.setAttribute("d", collapsed ? CHEVRON_RAIL_COLLAPSED : CHEVRON_RAIL_OPEN);
+      const label = collapsed ? "Show controls" : "Hide controls";
+      toggle.setAttribute("aria-expanded", String(!collapsed));
       toggle.setAttribute("aria-label", label);
       toggle.title = label;
-      toggle.classList.toggle("on", state.collapsed);
+      toggle.classList.toggle("on", collapsed);
     }
     if (persist) writeRailPref(state, storage);
   }
@@ -312,6 +327,7 @@ export function attachRail({ rail, toggle, shell = rail?.parentElement, storage
       if (toggle) {
         toggle.innerHTML = toggleOriginal.html;
         toggle.title = toggleOriginal.title;
+        toggle.hidden = toggleOriginal.hidden;
         toggle.removeAttribute("aria-expanded");
         toggle.removeAttribute("aria-label");
         toggle.classList.remove("on");

package/src/framework/viewer.js

@@ -175,14 +175,24 @@ export function createViewer(container, part) {
   }
 
   // The cutaway plane lives in world space, so its initial/reset bounds must
-  // include the pivot rotation and the per-view recentering transform.
+  // include the pivot rotation and the per-view recentering transform —
+  // mesh.matrixWorld carries both. Union each visible mesh's own
+  // geometry.boundingBox rather than `Box3.expandByObject`, which recurses into
+  // children: the two stencil-pass meshes share `mesh.geometry` so that
+  // recursion is harmless for them, but the cut-face outline child carries its
+  // own independent geometry that only re-slices while the cutaway is enabled
+  // and visible — while hidden it can keep segments from an older, larger part
+  // and inflate these bounds. A subpart's initial placeholder BufferGeometry
+  // has no boundingBox computed (only buildGeometry computes one), so skip it.
   const _worldBounds = new THREE.Box3();
+  const _meshBounds = new THREE.Box3();
   function getVisibleWorldBounds() {
     _worldBounds.makeEmpty();
     for (const mesh of Object.values(subMesh)) {
-      if (!mesh.visible || !mesh.geometry) continue;
+      if (!mesh.visible || !mesh.geometry?.boundingBox) continue;
       mesh.updateWorldMatrix(true, false);
-      _worldBounds.expandByObject(mesh);
+      _meshBounds.copy(mesh.geometry.boundingBox).applyMatrix4(mesh.matrixWorld);
+      _worldBounds.union(_meshBounds);
     }
     return _worldBounds;
   }
@@ -379,12 +389,19 @@ export function createViewer(container, part) {
   // fov 45, quality 0.9). A custom size (captureCurrent) gets a fresh render
   // target, disposed after the read — those captures are rare, so per-call
   // allocation beats caching one target per size ever requested.
+  //
+  // stencilBuffer is NOT optional: cutaway masks its section caps with the
+  // stencil buffer, and a WebGLRenderTarget defaults to not having one (the
+  // visible canvas does, via the `stencil: true` renderer above). Without it
+  // the mask silently no-ops and every cap floods its whole plane with hatch —
+  // no error, live view unaffected, wrong only in the capture.
+  const RT_OPTIONS = { samples: 4, stencilBuffer: true };
   function renderOffscreen({ position, up, target },
                            { width = _rtSize, height = _rtSize, fov = 45, quality = 0.9 } = {}) {
     const cachedSize = width === _rtSize && height === _rtSize;
     const rt = cachedSize
-      ? (_rt = _rt ?? new THREE.WebGLRenderTarget(_rtSize, _rtSize, { samples: 4 }))
-      : new THREE.WebGLRenderTarget(width, height, { samples: 4 });
+      ? (_rt = _rt ?? new THREE.WebGLRenderTarget(_rtSize, _rtSize, RT_OPTIONS))
+      : new THREE.WebGLRenderTarget(width, height, RT_OPTIONS);
     _capLights = _capLights ?? createCaptureLights();
     const cam = new THREE.PerspectiveCamera(fov, width / height, 0.1, 1000);
     cam.position.set(position[0], position[1], position[2]);