partforge 0.38.0 → 0.39.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.39.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/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

@@ -379,12 +379,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]);