partforge 0.102.0 → 0.104.0

package/README.md

@@ -113,6 +113,15 @@ 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.setRailLayout({ mode: "dock", inset: 380, railHeight: 316 });
+                               // where the rail SITS when the host draws chrome over
+                               // the frame: docked into its bottom sheet (inset = the
+                               // sheet's height, railHeight = the slice of it the rail
+                               // may paint into), or { mode: "overlay" } for a
+                               // right-edge drawer over a full-width stage. null (or
+                               // any shape partforge can't read) restores partforge's
+                               // own layout; resize and collapse are suspended while
+                               // a layout is leased.
 runtime.setActive(false);      // park the viewer: stop the render loop, release the
                                // drawing buffer. setActive(true) restores both.
 runtime.attachTooltips([{ element: myButton }]);  // host chrome buttons join the mount's

package/docs/AUTHORING-PARTS.md

@@ -2057,8 +2057,17 @@ see "Wiring a part into a runnable app", above, for its full signature):
 **The `allow` list, and what bypasses it.** All three controls take the same
 `allow` list already documented for `"font"` in the control-types table above
 (`"https"` — the default; `"gstatic"`, font-only, `https://fonts.gstatic.com`
-exactly; `"asset"`, a `pfc-asset://` token the host has stored for this part),
-gating what a **param-supplied** value may be. It never restricts a source an
+exactly; `"asset"`, a `pfc-asset://` token the host has stored for this part;
+`"tree"`, vector-only, a `pfc-tree://` token naming artwork that lives as a
+**file inside the part itself** rather than in host storage), gating what a
+**param-supplied** value may be.
+
+`"tree"` is vector-only by construction, not by omission: a part's files are
+text, so a `partforge-vector` JSON document can live in one and a PNG or a
+font cannot. Its payoff is that the artwork is versioned *with* the part —
+a host that stores parts as a file tree keeps the document in the same
+snapshot as the code that reads it, so publishing, history and undo carry the
+two together instead of leaving a param pointing at storage that moved on. It never restricts a source an
 author writes into `images`/`fonts`/`vectors` themselves — that's code, not
 user input.
 
@@ -2338,14 +2347,17 @@ yourself (e.g. to download from a different origin) instead of partforge's own D
   where `ImageAsset` is `{ id, label, url, width, height, thumbUrl }`. With no
   provider a `type: "image"` control degrades to a URL field.
 
-- `onAssetUpload(blob, { kind, filename }) → Promise<string>` — the drop target
-  shared by `"image"`/`"vector"`/`"font"` controls (see "Getting files into a
-  part", below) calls this with the converted artifact after a drop, paste, or
-  file-picker choice, and writes whatever it resolves to into the param.
-  `blob` is the CONVERTED artifact — a PNG, a partforge-vector JSON blob, or the
-  original file for a font — never the user's raw drop; `kind` is `"image"`,
-  `"vector"`, or `"font"`. Must resolve to a non-empty source string (an
-  `https:` URL or a host-defined `pfc-asset:` token); anything else is treated
+- `onAssetUpload(blob, { kind, key, filename }) → Promise<string>` — the drop
+  target shared by `"image"`/`"vector"`/`"font"` controls (see "Getting files
+  into a part", below) calls this with the converted artifact after a drop,
+  paste, or file-picker choice, and writes whatever it resolves to into the
+  param. `blob` is the CONVERTED artifact — a PNG, a partforge-vector JSON blob,
+  or the original file for a font — never the user's raw drop; `kind` is
+  `"image"`, `"vector"`, or `"font"`; `key` is the param the drop landed on,
+  which is what lets a host give each control a stable destination of its own
+  rather than reconciling uploads against the part afterwards. Must resolve to
+  a non-empty source string (an `https:` URL, or a host-defined `pfc-asset:` or
+  `pfc-tree:` token); anything else is treated
   as a contract violation and reported through the control's own error line,
   not written into the param. Omit it and the converted bytes land straight in
   the param instead — the path a host that cannot fetch URLs (the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.102.0",
+  "version": "0.104.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/chrome.css

@@ -454,7 +454,74 @@
   .pf-anim-bar { width: calc(100% - 24px); max-width: 520px; bottom: 64px; }
 }
 
-
+/* ---- host-driven rail layouts (partforge-cloud) ---------------------------
+   data-pf-rail-layout is written by mobile-tabs.js from the host's
+   setRailLayout. Two modes, both host-only (nothing in partforge's own UI can
+   enter them):
+
+   DOCK — the host draws a bottom sheet over the iframe. --pf-rail-inset is the
+   sheet's full height: the shell pads by it so the stage (and its bottom
+   chrome) clears the sheet. With a "rail" lease the rail renders INTO the
+   sheet region — but only its bottom --pf-rail-dock-h px, because the host's
+   opaque chrome strip (handle + tabs) covers the top of the region. The spec
+   (2026-08-31-responsive-layout-redesign) has the two-numbers reasoning. Note
+   that a dock lease ABOVE 719px does not enter the block below at all: the
+   rail stays side by side with the stage at its usual --pf-rail-w (rail.js
+   keeps the width there, and only suspends resize/collapse/toggle).
+
+   OVERLAY — the rail is a right-edge drawer OVER the stage, open while
+   data-pf-rail-open is present (rail.js's toggle sets it; mobile-tabs.js's
+   stage pointerdown clears it). The stage never resizes. Width is its own
+   min(288px, 85%) — NOT --pf-rail-w, which rail.js zeroes under an overlay
+   lease at any window width (and under any layout below the breakpoint).
+
+   These come after the narrow block above because they override its one-pane
+   hiding, and before the reduced-motion block below so that block's
+   transition:none wins the tie at equal specificity. */
+.pf-shell[data-pf-rail-layout="dock"] { padding-bottom: var(--pf-rail-inset, 0px); }
+@media (max-width: 719px) {
+  /* pane=rail on a phone: stage above, rail docked in the sheet region. The
+     three rules below override the narrow block's one-pane hiding. */
+  .pf-shell[data-pf-rail-layout="dock"][data-pf-pane="rail"] { padding-bottom: 0; }
+  .pf-shell[data-pf-rail-layout="dock"][data-pf-pane="rail"] .pf-stage { display: block; }
+  .pf-shell[data-pf-rail-layout="dock"][data-pf-pane="rail"] .pf-rail {
+    display: flex;
+    flex: none;
+    height: var(--pf-rail-dock-h, 0px);
+    width: auto;
+    border-left: 0;
+    border-top: 1px solid var(--pf-border);
+    box-shadow: none;
+  }
+}
+.pf-shell[data-pf-rail-layout="dock"] .pf-rail-seam { display: none; }
+
+/* visibility, not just the transform: collapse is suppressed under a host
+   layout (rail.js), so nothing else makes a shut drawer inert — it would sit
+   off-canvas as a run of invisible tab stops. The delay is what keeps it on
+   screen for the 200ms it takes to slide out; opening flips it back at once,
+   which is why the open state restates the transition without it. */
+.pf-shell[data-pf-rail-layout="overlay"] .pf-stage { display: block; }
+.pf-shell[data-pf-rail-layout="overlay"] .pf-rail {
+  display: flex;
+  position: absolute;
+  top: 0; right: 0; bottom: 0;
+  flex: none;
+  width: min(288px, 85%);
+  border-left: 1px solid var(--pf-border);
+  box-shadow: var(--pf-shadow-rail), -16px 0 32px rgb(0 0 0 / .35);
+  transform: translateX(102%);
+  visibility: hidden;
+  transition: transform 200ms ease, visibility 0s 200ms;
+  z-index: 30;
+}
+.pf-shell[data-pf-rail-layout="overlay"][data-pf-rail-open] .pf-rail {
+  transform: translateX(0);
+  visibility: visible;
+  transition: transform 200ms ease;
+}
+.pf-shell[data-pf-rail-layout="overlay"] .pf-rail-seam,
+.pf-shell[data-pf-rail-layout="overlay"] .pf-tabbar { display: none; }
 
 /* ---- reduced motion -----------------------------------------------------
    Collapsing the rail slides 288px of layout across the screen — the first
@@ -465,6 +532,13 @@
    state indicator and is left alone. */
 @media (prefers-reduced-motion: reduce) {
   .pf-rail, .pf-rail-seam > span { transition: none; }
+  /* The overlay drawer states its own transition twice, at higher specificity
+     than the blanket rule above, so both states have to be named here or the
+     drawer would keep sliding. Killing the transition also drops the closing
+     visibility delay, which is right: with no slide there is nothing to wait
+     for, and the drawer leaves the a11y tree the moment it shuts. */
+  .pf-shell[data-pf-rail-layout="overlay"] .pf-rail,
+  .pf-shell[data-pf-rail-layout="overlay"][data-pf-rail-open] .pf-rail { transition: none; }
 }
 
 /* ---- annotation ink layer: a transparent 2D canvas over the viewer --------

package/src/framework/mobile-tabs.js

@@ -4,7 +4,7 @@
 // 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
+// Three 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
@@ -12,6 +12,10 @@
 //   * 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.
+//   * A HOST owns the rail's LAYOUT — setRailLayout() docks the rail into a
+//     bottom sheet or floats it as an overlay drawer, each with its own way in
+//     and out, so a pane tab would be a second, competing control. That lease
+//     is independent of the pane one: either alone hides the bar.
 //
 // 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.
@@ -42,6 +46,26 @@ const ICONS = {
 const LABELS = { stage: "3D", rail: "Controls" };
 const PANES = ["stage", "rail"];
 
+// A host-driven rail layout (partforge-cloud's bottom sheet / overlay drawer).
+// null = partforge's own default layout. Normalization is strict: a shape this
+// module does not recognize is a null, never a guess — the host is trusted to
+// send well-formed layouts and a garbled one must not wedge the shell.
+const MAX_RAIL_INSET = 4096;
+
+function normalizeRailLayout(next) {
+  if (!next || typeof next !== "object") return null;
+  if (next.mode === "overlay") return { mode: "overlay" };
+  if (next.mode !== "dock") return null;
+  if (!Number.isInteger(next.inset) || next.inset < 0 || next.inset > MAX_RAIL_INSET) return null;
+  // A missing or unusable railHeight is a zero, not a rejection: the inset is
+  // what the stage lays out against, and a sheet with no visible collapsed
+  // height is a legitimate state.
+  const railHeight = Number.isInteger(next.railHeight)
+    ? Math.max(0, Math.min(next.inset, next.railHeight))
+    : 0;
+  return { mode: "dock", inset: next.inset, railHeight };
+}
+
 function buildIcon(paths) {
   const svg = document.createElementNS(SVG_NS, "svg");
   svg.setAttribute("viewBox", "0 0 24 24");
@@ -69,15 +93,18 @@ function buildIcon(paths) {
 //
 // 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 } = {}) {
+// itself (embed-test.html) is unaffected — including its setHostPane and
+// setRailLayout, which stay callable no-ops so mount()'s handle shape never
+// varies. `toggle` is rail.js's own rail toggle, passed only so the overlay duck
+// below can recognize it; omitting it costs the drawer its close button.
+export function attachMobileTabs({ shell, stage, rail, toggle, onRailLayout } = {}) {
   if (!shell || !stage || !rail) {
-    return { setHostPane: () => {}, detach: () => {} };
+    return { setHostPane: () => {}, setRailLayout: () => {}, detach: () => {} };
   }
 
   let pane = "stage"; // the standalone user's choice
   let hostPane = null; // a host's lease over that choice, while non-null
+  let railLayout = null; // a host's lease over where the rail sits, while non-null
 
   const bar = document.createElement("div");
   bar.className = "pf-tabbar";
@@ -107,9 +134,23 @@ export function attachMobileTabs({ shell, stage, rail } = {}) {
     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;
+    // chrome.css keys the docked/overlay rail off these; the two lengths are
+    // zero in overlay mode, where the drawer floats over a full-width stage.
+    if (railLayout) {
+      shell.dataset.pfRailLayout = railLayout.mode;
+      shell.style.setProperty("--pf-rail-inset", `${railLayout.mode === "dock" ? railLayout.inset : 0}px`);
+      shell.style.setProperty("--pf-rail-dock-h", `${railLayout.mode === "dock" ? railLayout.railHeight : 0}px`);
+    } else {
+      delete shell.dataset.pfRailLayout;
+      shell.style.removeProperty("--pf-rail-inset");
+      shell.style.removeProperty("--pf-rail-dock-h");
+    }
+    // The drawer-open flag only means anything in overlay mode; entering any
+    // other layout must not leave a stale open state behind.
+    if (railLayout?.mode !== "overlay") shell.removeAttribute("data-pf-rail-open");
+    // A host that owns EITHER pane selection or the layout draws its own
+    // controls; ours would compete.
+    bar.hidden = hostPane !== null || railLayout !== null;
   }
 
   // Delegated, so the icon <svg>/<span> inside a button resolve to the button.
@@ -120,6 +161,31 @@ export function attachMobileTabs({ shell, stage, rail } = {}) {
     apply();
   };
   bar.addEventListener("click", onClick);
+
+  // Overlay mode's "duck": any interaction with the stage slides the drawer
+  // back. Capture phase, because the canvas consumes pointer events.
+  //
+  // Two things the plain "remove the attribute" version got wrong, both because
+  // the rail toggle is a DESCENDANT of the stage (it floats at the stage's
+  // top-right):
+  //   * its own tap arrives here first, so this would close the drawer a moment
+  //     before rail.js's click handler reopened it — the toggle could open the
+  //     drawer but never shut it. Hence the exemption, which needs the element
+  //     itself: nothing in the DOM marks it out for a class/closest() test.
+  //   * a real duck has to be REPORTED. The toggle's chevron, aria-expanded and
+  //     label are derived from the open flag in rail.js's apply(), so a close it
+  //     was never told about leaves the button announcing an open drawer. The
+  //     callback is the same one setRailLayout uses (the host wires it to
+  //     railChrome.layoutChanged), so this is a re-look, not a new channel.
+  const onStagePointerDown = (e) => {
+    if (toggle && (e.target === toggle || toggle.contains?.(e.target))) return;
+    if (shell.dataset.pfRailLayout !== "overlay") return;
+    // Nothing to duck: stay silent rather than nudge on every stage pointerdown.
+    if (!shell.hasAttribute("data-pf-rail-open")) return;
+    shell.removeAttribute("data-pf-rail-open");
+    onRailLayout?.(railLayout);
+  };
+  stage.addEventListener("pointerdown", onStagePointerDown, true);
   apply();
 
   return {
@@ -129,10 +195,24 @@ export function attachMobileTabs({ shell, stage, rail } = {}) {
       hostPane = PANES.includes(next) ? next : null;
       apply();
     },
+    // A dock/overlay layout takes the lease; anything this module cannot read —
+    // null included — releases it and restores partforge's own layout. The
+    // callback reports what was actually applied, so a host never has to guess
+    // whether its request survived normalization.
+    setRailLayout: (next) => {
+      railLayout = normalizeRailLayout(next);
+      apply();
+      onRailLayout?.(railLayout);
+    },
     detach: () => {
       bar.removeEventListener("click", onClick);
+      stage.removeEventListener("pointerdown", onStagePointerDown, true);
       bar.remove();
       delete shell.dataset.pfPane;
+      delete shell.dataset.pfRailLayout;
+      shell.removeAttribute("data-pf-rail-open");
+      shell.style.removeProperty("--pf-rail-inset");
+      shell.style.removeProperty("--pf-rail-dock-h");
     },
   };
 }

package/src/framework/mount.js

@@ -62,7 +62,7 @@ const IMPORT_MESH_BROKEN_MESSAGE = "STEP import tessellation failed to satisfy t
 // carries the worker's own error text. See the correlated "error" case below.
 const importTessellateFailedMessage = (workerMessage) => `STEP import tessellation failed — ${workerMessage}`;
 
-export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, warmExportKernel, setHostPane, animation, getView, setView, captureView, attachTooltips, measure, annotate, projection, pickMarker }) {
+export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, warmExportKernel, setHostPane, setRailLayout, animation, getView, setView, captureView, attachTooltips, measure, annotate, projection, pickMarker }) {
   return {
     ready, dispose, setParams,
     // Part-declared animation playback (spec 2026-08-02): animations are
@@ -122,6 +122,12 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
     // (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 ?? (() => {}),
+    // Where the rail SITS, for a host that draws its own chrome around the
+    // frame: {mode:"dock", inset, railHeight} renders it into the host's bottom
+    // sheet, {mode:"overlay"} floats it as a right-edge drawer over the stage,
+    // and null hands the layout back to partforge. Same no-op default as
+    // setHostPane above, and the same lease semantics.
+    setRailLayout: setRailLayout ?? (() => {}),
     // Join host-owned chrome buttons to this mount's shared hover tooltip, so
     // a host's own viewbar/rail-foot buttons match the built-in ones. Entries
     // are [{ element, getLabel? }] (label falls back to the button's
@@ -211,6 +217,11 @@ function createCleanupStack() {
 //   runtime.setHostPane("rail");  // narrow layout only: show just the controls
 //                                 // rail ('stage' | 'rail'), suppressing the
 //                                 // built-in tab bar. null hands selection back.
+//   runtime.setRailLayout({mode:"dock", inset, railHeight} | {mode:"overlay"} | null)
+//                                 // where the rail sits when the HOST draws chrome
+//                                 // over the frame: into its bottom sheet, or as a
+//                                 // right-edge drawer over the stage. null restores
+//                                 // partforge's own layout.
 //   runtime.attachTooltips([{ element: myButton }]);  // host chrome buttons join the
 //                                 // mount's shared hover tooltip (the viewbar one).
 //                                 // Label = the button's title (or aria-label), or a
@@ -379,6 +390,16 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       shell: els.shell ?? els.rail?.parentElement,
       stage: els.viewer,
       rail: els.rail,
+      // The rail toggle floats INSIDE the stage, so the overlay duck has to know
+      // it by identity or the drawer's own close button would duck it shut and
+      // rail.js would reopen it on the same tap.
+      toggle: els.chrome.railToggle,
+      // rail.js reads the layout lazily in its handlers, but its toggle
+      // visibility (and, in overlay mode, its open/closed reporting) is written
+      // in apply() — tell it to re-look when the host changes the layout, or the
+      // duck closes the drawer. railChrome is created just above, so the closure
+      // is safe.
+      onRailLayout: () => railChrome.layoutChanged?.(),
     });
     cleanup.defer(() => paneTabs.detach());
     const hover = attachHoverLabels(viewer, { part, tooltip }); // always-on hover inspection (no-op on touch-only devices)
@@ -1154,6 +1175,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       ready, dispose, viewer, setParams,
       attachTooltips: attachHostTooltips,
       setHostPane: paneTabs.setHostPane,
+      setRailLayout: paneTabs.setRailLayout,
       getView: view,                         // () => tabsCtl.current()
       setView: (name) => tabsCtl.select(name),
       captureView,

package/src/framework/panel/widgets/file-drop.js

@@ -96,7 +96,7 @@ function el(tag, className, text) {
 // The click path is dropped rather than hidden, deliberately: an invisible
 // overlay that still swallowed clicks would eat the button underneath it, which
 // is the one affordance ambient mode exists to protect.
-export function makeFileDrop({ kind, onSource, onError, onAssetUpload, ambient = false }) {
+export function makeFileDrop({ kind, key, onSource, onError, onAssetUpload, ambient = false }) {
   const row = rowFor(kind);
   const wrap = el("div", ambient ? "file-drop file-drop-ambient" : "file-drop");
   if (!ambient) {
@@ -219,7 +219,14 @@ export function makeFileDrop({ kind, onSource, onError, onAssetUpload, ambient =
 
     if (onAssetUpload) {
       try {
-        const source = await onAssetUpload(artifact.blob, { kind, filename: file.name });
+        // `key` is the PARAM the drop landed on. A host needs it to give a
+        // control a stable destination of its own — partforge-cloud derives
+        // one file path per key, so re-dropping replaces that control's
+        // artwork in place instead of accumulating files it must later
+        // reconcile against the part. Purely informational to partforge:
+        // the hook still answers with a source string and nothing here
+        // reads the key back.
+        const source = await onAssetUpload(artifact.blob, { kind, key, filename: file.name });
         if (stale()) return;
         // A host hook that resolves to anything but a non-empty string —
         // `undefined`, an object, `""` — is a contract violation, not a
@@ -329,6 +336,7 @@ export function mountDrop(kind, { params, node, onAssetUpload, onChange, onCommi
 
   const drop = makeFileDrop({
     kind,
+    key: node.key,
     ambient,
     onAssetUpload,
     onSource: (source) => {

package/src/framework/rail.js

@@ -90,12 +90,17 @@ export function attachRail({ rail, toggle, shell = rail?.parentElement, storage
     // ?pickserver with no #panel/elements.rail hits this path.
     const root = document.documentElement;
     root.style.setProperty("--pf-rail-w", "0px");
-    return { detach: () => root.style.removeProperty("--pf-rail-w") };
+    return { layoutChanged: () => {}, detach: () => root.style.removeProperty("--pf-rail-w") };
   }
 
   const root = document.documentElement;
   const shellBox = () => shell.getBoundingClientRect();
   const shellWidth = () => shellBox().width;
+  // A host that leases the rail's placement through attachMobileTabs'
+  // setRailLayout writes this ("dock" | "overlay"); absent means partforge's own
+  // layout. Read live rather than cached: the lease can move at any moment and
+  // layoutChanged() (below) is only a nudge to re-apply, not the source of truth.
+  const hostLayout = () => shell.dataset.pfRailLayout ?? null;
   let state = readRailPref(storage, shellWidth());
   // Captured before the first apply() mutates the toggle, so detach() can
   // hand back a plain, unwired button rather than a dead "Show controls" one.
@@ -142,11 +147,34 @@ export function attachRail({ rail, toggle, shell = rail?.parentElement, storage
     // 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);
+    // A host layout suspends collapse (and every resize gesture — see
+    // resizeRefused) for the same reason narrow does: the rail's placement is
+    // the host's to decide, so a collapse flag would only make it inert and
+    // invisible where the host is showing it. `state` is left untouched, so
+    // the preference returns intact when the lease ends.
+    const layout = hostLayout();
+    const overlay = layout === "overlay";
+    const suppressed = narrow || layout !== null;
+    const collapsed = state.collapsed && !suppressed;
+    // WIDTH is suppressed on a NARROWER rule than collapse, because only two of
+    // the three layouts stop needing --pf-rail-w:
+    //   - narrow (any layout): chrome.css stacks the panes and shows exactly
+    //     one, so the rail is the whole surface or absent — it reserves no
+    //     width beside the viewer;
+    //   - overlay (any width): the drawer sizes itself (min(288px, 85%)) and
+    //     floats over the stage, reserving nothing;
+    //   - dock at >= RAIL_NARROW_BREAKPOINT: the rail is STILL side by side with
+    //     the stage — the host only leases the bottom inset — so zeroing here
+    //     would leave the card with no controls at all. Keep the width.
+    // Anything centring itself against the rail (app.css's #pf-pick-banner)
+    // reads this token, so a stale 288px in the first two cases would offset it.
+    // A wide dock therefore renders as: rail visible at its remembered width,
+    // no resize, no collapse, and no toggle (hidden just below — a visible one
+    // would be a dead control while collapse is suppressed). That is the
+    // sheet-owns-layout stance: the host decides placement, we only supply the
+    // width it laid the rail out against.
+    const widthSuppressed = narrow || overlay;
+    const width = collapsed || widthSuppressed ? 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
@@ -162,16 +190,26 @@ export function attachRail({ rail, toggle, shell = rail?.parentElement, storage
     seam.setAttribute("aria-valuemax", String(railMaxWidth(sw)));
     if (toggle) {
       // 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));
+      // collapse affordance in the viewbar would be a competing control. In
+      // overlay mode the toggle IS the drawer's open/close control, so it must
+      // stay visible even though the width says "narrow" — and the host hides
+      // its own tab bar under a layout lease, making this the only way back to
+      // the controls. Under dock it stays hidden at EVERY width, including the
+      // wide band that keeps its --pf-rail-w above: collapse is suppressed
+      // there, so a visible toggle would be a control that does nothing.
+      toggle.hidden = suppressed && !overlay;
+      // One button, two meanings: the drawer's open state in overlay mode, the
+      // collapse everywhere else. `shut` is whichever of the two this layout
+      // asks the label, chevron and aria-expanded to report.
+      const shut = overlay ? !shell.hasAttribute("data-pf-rail-open") : collapsed;
+      toggleChevron?.setAttribute("d", shut ? CHEVRON_RAIL_COLLAPSED : CHEVRON_RAIL_OPEN);
+      const label = shut ? "Show controls" : "Hide controls";
+      toggle.setAttribute("aria-expanded", String(!shut));
       toggle.setAttribute("aria-label", label);
       // The shared tooltip reads the aria-label at show time, so a native
       // title would double up as a second, competing tooltip.
       if (!tooltipBinding) toggle.title = label;
-      toggle.classList.toggle("on", collapsed);
+      toggle.classList.toggle("on", shut);
       tooltipBinding?.sync();
     }
     if (persist) writeRailPref(state, storage);
@@ -199,10 +237,18 @@ export function attachRail({ rail, toggle, shell = rail?.parentElement, storage
   }
   const toggleCollapsed = () => commit({ collapsed: !state.collapsed, width: state.width });
 
+  // Neither gesture that sizes the rail may run when the seam is not what
+  // sizes it: chrome.css hides the vertical seam in the stacked layout (the
+  // rail is under the viewer, not beside it), and a host layout sizes the rail
+  // itself, where a width or a collapse we wrote would be invisible at best
+  // and an inert docked rail at worst. The toggle still works in both.
+  const resizeRefused = () => window.innerWidth < RAIL_NARROW_BREAKPOINT || hostLayout() !== null;
+
   // --- keyboard: move the SEPARATOR (standard role="separator" semantics), so
   // ArrowLeft widens a right-hand rail. Arrows clamp at the minimum and never
   // collapse; Enter/Space is the collapse gesture.
   function onKeyDown(e) {
+    if (resizeRefused()) return;
     // Cmd/Alt/Ctrl+Arrow are browser/OS reserved (back, tab switch, ...); don't
     // eat them just because the seam happens to hold focus.
     if (e.metaKey || e.altKey || e.ctrlKey) return;
@@ -247,15 +293,26 @@ export function attachRail({ rail, toggle, shell = rail?.parentElement, storage
   }
 
   const onDoubleClick = () => commit({ collapsed: false, width: RAIL_DEFAULT_WIDTH });
-  const onToggleClick = () => toggleCollapsed();
+  const onToggleClick = () => {
+    // Overlay: the rail is a drawer over the stage, so the toggle slides it in
+    // and out. It must not touch `state` — the collapse preference belongs to
+    // the wide layout the host may hand back at any moment, and persisting a
+    // drawer gesture into it would collapse the rail on a desktop next visit.
+    // The host clears this flag itself when the lease ends or the stage is
+    // touched (mobile-tabs.js), so nothing here has to unwind it.
+    if (hostLayout() === "overlay") {
+      shell.toggleAttribute("data-pf-rail-open");
+      apply();
+      return;
+    }
+    toggleCollapsed();
+  };
 
   // --- drag ---
   let grabOffset = 0;
   function onPointerDown(e) {
     if (e.button !== 0) return;
-    // Stacked layout: the rail is under the viewer, so there is no vertical seam
-    // to drag (chrome.css hides it). The toggle still works.
-    if (window.innerWidth < RAIL_NARROW_BREAKPOINT) return;
+    if (resizeRefused()) return;
     e.preventDefault();
     // setPointerCapture is load-bearing: without it the pointer crosses into the
     // viewer (an iframe, in the cloud editor) whose document eats the move
@@ -321,6 +378,11 @@ export function attachRail({ rail, toggle, shell = rail?.parentElement, storage
   apply();
 
   return {
+    // The host's data-pf-rail-layout / data-pf-rail-open attributes are read
+    // live by apply(), so re-running it is the whole of "the layout moved".
+    // Deliberately unconditional: attachMobileTabs reports every setRailLayout
+    // call, no-change ones included, and a bare re-apply is idempotent.
+    layoutChanged: () => apply(),
     detach: () => {
       settleKeys();
       seam.removeEventListener("pointerdown", onPointerDown);

package/src/framework/vector-source.js

@@ -52,6 +52,14 @@ import { unwrapModule } from "./asset-resolve.js";
 export const VECTOR_ALLOW_DEFAULT = ["https"];
 
 const ASSET_SCHEME = "pfc-asset:";
+// Artwork that lives as a FILE IN THE PART ITSELF, addressed by its path
+// rather than by a host-side storage id. Vector-only, and the asymmetry is
+// structural rather than an omission: a part's files are text, so a JSON
+// document can live in one and a PNG cannot. A host that stores parts as a
+// file tree (partforge-cloud is the motivating case) resolves this scheme
+// against that tree; partforge itself only decides whether a param may carry
+// it, exactly as it does for `pfc-asset:`.
+const TREE_SCHEME = "pfc-tree:";
 
 // The "unset" vector source. An empty value declares NO artwork for that
 // name — mirrors isNoFontSource/isNoImageSource exactly. Never a source to
@@ -94,6 +102,7 @@ export function vectorSourceAllowed(source, allow = VECTOR_ALLOW_DEFAULT) {
     // "pfc-asset://" must not pass, and neither must a lookalike host.
     if (kind === "https" && u.protocol === "https:") return true;
     if (kind === "asset" && u.protocol === ASSET_SCHEME) return true;
+    if (kind === "tree" && u.protocol === TREE_SCHEME) return true;
   }
   return false;
 }

package/types/index.d.ts

@@ -13,6 +13,18 @@ export * from "./part.js";
 /** Which pane a narrow layout shows. `null` hands selection back to partforge. */
 export type HostPane = "stage" | "rail" | null;
 
+/**
+ * Where a HOST wants the controls rail: docked into a bottom sheet the host
+ * draws over the frame (`inset` = the sheet's full height, so the stage clears
+ * it; `railHeight` = the bottom slice of that region the rail renders into,
+ * under the host's own chrome strip), or floated as a right-edge drawer over a
+ * full-width stage. `null` hands the layout back to partforge.
+ */
+export type HostRailLayout =
+  | { mode: "dock"; inset: number; railHeight?: number }
+  | { mode: "overlay" }
+  | null;
+
 /** An export file format. STEP is routed to OCCT automatically. */
 export type ExportFormat = "stl" | "step" | "3mf";
 
@@ -494,6 +506,14 @@ export interface PartRuntime {
    * `null` hands selection back to partforge's built-in bar.
    */
   setHostPane(pane: HostPane): void;
+  /**
+   * Where the rail sits, for a host that draws its own chrome over the frame:
+   * docked into the host's bottom sheet (`inset` is the sheet's full height,
+   * `railHeight` the part of it the rail may paint into), or floated as a
+   * right-edge drawer over an unresized stage. `null` — or any shape partforge
+   * cannot read — restores partforge's own layout.
+   */
+  setRailLayout(layout: HostRailLayout): void;
   /**
    * Part-declared animation playback, or `null` when NO view declares an
    * `animations` block. Non-null while any view does — including while the