partforge 0.101.0 → 0.103.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

@@ -731,9 +731,9 @@ Every control accepts `key`, `type`, `label`, `description`, `hidden`, `when` an
 | `"checkbox"` | an on/off box: ticked writes `on`, cleared writes `0` | `on` (default `1`) |
 | `"select"` | a dropdown | `options` |
 | `"radio"` | a segmented button row | `options` |
-| `"font"` | a typeface picker (or a URL field with no catalog), plus a drop target | `allow`, `preview` |
-| `"image"` | an image picker (or a URL field with no catalog), plus a drop target | `allow` |
-| `"vector"` | a URL field plus a drop target — no catalog exists | — |
+| `"font"` | a typeface picker with a catalog, else a drop target | `allow`, `preview`, `sourceField` |
+| `"image"` | an image picker with a catalog, else a drop target showing the artwork | `allow`, `sourceField` |
+| `"vector"` | a drop target showing the artwork — no catalog exists | `sourceField` |
 
 Numeric controls always show the number box: drag the slider *or* type an exact
 value. Typed values may be finer than `step` and clamp to `[min, max]` on commit.
@@ -748,6 +748,18 @@ each entry is both value and label — or the long form
 types, `12` is not `"12"`). An option's `description` surfaces as a hover tooltip
 on that one option, not as a ⓘ popover.
 
+**`sourceField: true`** (font/image/vector) adds a raw source text box to the
+control. It is **off by default**: the drop target already carries the preview,
+the drag target and click-to-choose, and where a catalog is wired there is a
+picker too, so on a 288 px rail a text box is the affordance earning its space
+least. Turn it on when typing a source by hand is something your users will
+actually do — pasting an `https:` URL they already have, or a host `pfc-asset:`
+token. Hiding it changes nothing else: the same values are accepted by the same
+allow list, and a source set in `defaults` or by the host still applies.
+
+For a `"font"` control with no `fontCatalog` this is the only text entry there
+is, so a standalone app that expects users to paste font URLs should set it.
+
 **`allow` and `preview`** (font) configure the typeface control. `allow` lists the
 source kinds a **param-supplied** value may use — what the picker writes, or what
 arrives in a share link:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.101.0",
+  "version": "0.103.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

@@ -198,6 +198,101 @@ textarea.text-input { min-height: 64px; resize: vertical; }
 .text-input:focus { outline: none; border-color: var(--pf-accent);
   box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent); }
 
+/* ── file drop targets ──────────────────────────────────────────────────────
+   Two forms of the same widget. The LABELLED form is a tile the user is meant
+   to find: it doubles as the thumbnail once there is something to show, so a
+   preview, a drop zone and a click-to-choose occupy one box rather than three.
+   The AMBIENT form is for a control that already has a visible way in (the font
+   control's catalog button) — it covers the control invisibly and only appears
+   while a file is over it, so dropping stays available without spending rail
+   height advertising itself. */
+.file-drop {
+  position: relative; display: flex; flex-direction: column;
+  align-items: center; justify-content: center; gap: 6px;
+  min-height: 56px; margin-top: 6px; padding: 8px;
+  background: var(--pf-input-bg); color: var(--pf-hint);
+  border: 1px dashed var(--pf-border); border-radius: var(--pf-radius-control);
+  text-align: center; cursor: pointer;
+}
+.file-drop:focus-visible { outline: none; border-color: var(--pf-accent);
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent); }
+.file-drop-hint { font: 11px/1.35 var(--pf-sans); }
+
+/* `contain` rather than `cover` because artwork and depth maps are content, not
+   decoration — cropping one to fill the box would misrepresent what is about to
+   be built. The two preview kinds then diverge, because a photograph and a piece
+   of line art want opposite things from the box around them. */
+.file-drop > svg, .file-drop > img {
+  display: block; max-width: 100%; max-height: 96px; object-fit: contain;
+}
+.file-drop > svg { fill: var(--pf-text-2); }
+/* Once there IS a preview, the frame moves off the tile and onto the artwork.
+   The tile stays full width — it is the drop target, and a full-width one is
+   easier to hit — but goes invisible, so what the eye sees is a rounded box
+   hugging the picture with the hint underneath it, rather than a picture
+   floating inside a much larger box. The border stays at 1px and only loses its
+   colour, so nothing shifts when a thumbnail arrives. */
+.file-drop.has-thumb {
+  border-color: transparent; background: none; padding: 0; gap: 4px;
+}
+.file-drop.has-thumb > img, .file-drop.has-thumb > svg {
+  border: 1px solid var(--pf-border);
+  border-radius: var(--pf-radius-control);
+  background: var(--pf-input-bg);
+}
+/* A RASTER is a filled rectangle, so the border sits directly on the pixels —
+   padding around one reads as a mount around a picture. `border-radius` on an
+   `<img>` clips the image itself, which is what rounds the corners. Sized by
+   `max-height` rather than `height` so a small source is shown at its own size
+   instead of being upscaled into a blur.
+   `width: auto` is load-bearing: this element also carries `.image-preview`,
+   which pins it to `width: 100%` and letterboxes the picture inside a
+   rail-width box with `object-fit`. That is the right behaviour for a preview
+   that fills its container and the wrong one for a frame meant to hug, and it
+   is invisible in the markup — the box just silently stops matching the image. */
+.file-drop.has-thumb > img { max-height: 96px; max-width: 100%; width: auto; margin: 0; }
+/* A VECTOR is line art: strokes running into the border would collide with it
+   rather than be framed by it, so it keeps padding inside its own frame. Sizing
+   by height with `width: auto` lets the viewBox's aspect supply the width, so
+   the frame hugs the drawing instead of the SVG's default 300x150 box. */
+.file-drop.has-thumb > svg { height: 96px; width: auto; max-width: 100%; padding: 8px; }
+
+/* The empty-state hint and the replace hint trade places: exactly one is visible
+   in either state, so a tile is never without an instruction. */
+.file-drop-hint-replace { display: none; }
+.file-drop.has-thumb .file-drop-hint { display: none; }
+.file-drop.has-thumb .file-drop-hint-replace { display: block; }
+
+/* Ambient: no box of its own. Laid over the control, inert to the pointer so
+   every click still reaches the button underneath — the one affordance this
+   form exists to protect. */
+/* Only the controls that actually carry an ambient overlay become positioned —
+   `.slider` is shared by every widget in the rail, and making all of them a
+   containing block to serve one would be a wide change for a narrow need. */
+.slider:has(> .file-drop-ambient) { position: relative; }
+
+.file-drop-ambient {
+  position: absolute; inset: 0; margin: 0; padding: 0;
+  min-height: 0; background: none; border: 0; pointer-events: none;
+}
+/* `dragover` is the only thing that reveals it. Pointer events stay off even
+   then: the drop event still fires on the element, and turning them on would
+   swallow a click that merely passed through mid-drag. */
+.file-drop-ambient.file-drop-over {
+  border: 1px dashed var(--pf-accent); border-radius: var(--pf-radius-control);
+  background: color-mix(in oklab, var(--pf-accent) 12%, transparent);
+}
+
+/* Shared drag feedback for the labelled form. */
+.file-drop.file-drop-over {
+  border-color: var(--pf-accent);
+  background: color-mix(in oklab, var(--pf-accent) 12%, transparent);
+}
+
+.file-drop-error {
+  margin-top: 5px; font: 11px/1.35 var(--pf-sans); color: var(--pf-err);
+}
+
 /* the `type: "font"` control — a button that shows the current face IN it */
 .font-btn { width: 100%; display: flex; align-items: center; gap: 8px; text-align: left; cursor: pointer;
   background: var(--pf-input-bg); color: var(--pf-text-strong);

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

@@ -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 { declaredSourceLookup } from "./panel/declared-source.js";
 import { attachMobileTabs } from "./mobile-tabs.js";
 import { createTooltipPresenter, attachButtonTooltips } from "./tooltip.js";
 import { loadCamera, loadProjection, saveProjection } from "./view-state.js";
@@ -61,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
@@ -121,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
@@ -210,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
@@ -378,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)
@@ -976,7 +998,11 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     }, onParamsCommit
       ? (changed) => onParamsCommit({ changed, params: { ...params } })
       : undefined,
-      { fontCatalog, imageCatalog, onAssetUpload });
+      // What the part is actually using for each asset key, so a control opens
+      // showing the bundled default instead of an empty tile. Rebuilt per panel
+      // build, because the declaration is a function of the current params.
+      { fontCatalog, imageCatalog, onAssetUpload,
+        declaredSource: declaredSourceLookup(part, params) });
     cleanup.defer(() => panel.dispose());
     panelRef = panel;
     const updateRelevance = () => {
@@ -1149,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/author.js

@@ -33,6 +33,17 @@ function authoredControl(c) {
     hidden: !!c.hidden,
     when: c.when,
     whenFalse: c.whenFalse,
+    // Asset-control fields. This list is an explicit allow-list, so anything
+    // missing from it is silently dropped rather than failing loudly — which is
+    // how `allow` came to be ignored: an authored `allow: ["asset"]` never
+    // reached the widget, so its own typed-URL check fell back to the default
+    // list and accepted values the worker then refused and reset underneath the
+    // user. The worker-side gate was never affected (imageControlAllows and its
+    // siblings walk the raw authored tree, not this node), so the enforcement
+    // held throughout — but the panel disagreed with it.
+    allow: c.allow,
+    preview: c.preview,
+    sourceField: c.sourceField,
     preserveOn: false,
     marksCustom: true,
   };

package/src/framework/panel/declared-source.js

@@ -0,0 +1,128 @@
+// What a part is ACTUALLY using for an asset key, when the control's own param
+// is empty.
+//
+// The problem this solves is not cosmetic. A part's bundled default lives in the
+// `images`/`vectors` DECLARATION, never in `defaults` — an author cannot move it
+// there, because the allow list passes only `https` and a bundled asset resolves
+// to a `file:`/dev URL, so `defaults: { relief: new URL(…) }` is refused and
+// reset. The declaration is therefore the only home for it, and the panel could
+// not see the declaration at all: `buildControls` receives `part.parameters`.
+// The result was a control that opened empty while the part was plainly building
+// from an image.
+//
+// Main-thread only, and deliberately import-free beyond what a lookup needs: it
+// runs during panel construction, on every rebuild.
+
+const arr = (v) => (Array.isArray(v) ? v : []);
+
+// `images`/`vectors`/`fonts` may each be a plain map or a function of params —
+// the function form is what a control drives. Resolving it can throw (it is
+// author code running on every panel build), and a broken declaration must not
+// take the panel down: the control simply shows nothing, which is the same thing
+// it showed before this existed.
+function resolveDecl(decl, params) {
+  try {
+    return typeof decl === "function" ? decl(params) : decl;
+  } catch {
+    return undefined;
+  }
+}
+
+const FIELD = { image: "images", vector: "vectors", font: "fonts" };
+
+// URL-shaped for the same reason lint's probes are: a declaration may parse the
+// value it is handed, and an arbitrary string would make it throw for reasons
+// that have nothing to do with which asset the key feeds.
+const SENTINEL = "pf-panel-sentinel://declared-source";
+
+/**
+ * Build `(kind, key) => source | undefined` for one part and its current params.
+ *
+ * Returns `undefined` when the param already holds a value: the param IS the
+ * user's choice, and the declaration for that key is derived from it. Only an
+ * empty param falls through to whatever the part declared.
+ */
+export function declaredSourceLookup(part, params) {
+  return (kind, key) => {
+    const own = params?.[key];
+    if (own !== undefined && own !== null && own !== "") return undefined;
+
+    const decl = part?.[FIELD[kind]];
+    const resolved = resolveDecl(decl, params ?? {});
+    if (!resolved || typeof resolved !== "object") return undefined;
+
+    // A control's param key is NOT necessarily the asset's name. emblem.js
+    // declares `vectors: (p) => ({ emblem: p.art || bundled })` — key `art`,
+    // asset `emblem`. relief.js happens to use the same word for both, which is
+    // what makes the assumption look safe until it is not.
+    //
+    // So probe, the way lint's *-control-not-in-* rules already do: resolve the
+    // declaration once with a sentinel in this key and see which asset name it
+    // came out under. A URL-shaped sentinel, because a declaration is free to
+    // parse what it is handed and an arbitrary string would make it throw for
+    // reasons unrelated to the mapping.
+    let name = key;
+    if (typeof decl === "function" && !(key in resolved)) {
+      const probe = resolveDecl(decl, { ...(params ?? {}), [key]: SENTINEL });
+      const hit = probe && typeof probe === "object"
+        && Object.keys(probe).find((n) => probe[n] === SENTINEL);
+      if (!hit) return undefined;   // this key feeds nothing — not our asset
+      name = hit;
+    }
+
+    const source = resolved[name];
+    return source == null || source === "" ? undefined : source;
+  };
+}
+
+/**
+ * A declared image source -> something an `<img>` can load, or `undefined`.
+ *
+ * The allow list gates PARAMS, not author declarations, so a `file:` or dev URL
+ * is perfectly fine to display here — the browser is loading it, nothing is
+ * being accepted from an untrusted link.
+ */
+export async function declaredImageUrl(source) {
+  try {
+    let v = typeof source === "function" ? await source() : source;
+    // A Vite `() => import("./x.png")` resolves to `{ default: url }`.
+    if (v && typeof v === "object" && !(v instanceof URL) && "default" in v) v = v.default;
+    if (v instanceof URL) return v.href;
+    if (typeof v === "string" && v) return v;
+    if (v instanceof ArrayBuffer || ArrayBuffer.isView(v)) {
+      return URL.createObjectURL(new Blob([v], { type: "image/png" }));
+    }
+    return undefined;
+  } catch {
+    return undefined;   // a thunk that rejects shows nothing, it does not propagate
+  }
+}
+
+/**
+ * A declared vector source -> its parsed document, or `undefined`.
+ *
+ * Unlike an image there is nothing to point at: the thumbnail is drawn from the
+ * document's own contours, so the file has to be fetched and parsed. Results are
+ * memoised per source, because a panel rebuild would otherwise refetch on every
+ * slider drag.
+ */
+const vectorDocs = new Map();
+export async function declaredVectorDoc(source) {
+  if (source == null) return undefined;
+  if (typeof source === "object" && !(source instanceof URL) && !("default" in source)) return source;
+  if (vectorDocs.has(source)) return vectorDocs.get(source);
+  const p = (async () => {
+    try {
+      let v = typeof source === "function" ? await source() : source;
+      if (v && typeof v === "object" && !(v instanceof URL) && "default" in v) v = v.default;
+      if (v && typeof v === "object" && !(v instanceof URL)) return v;   // already parsed
+      const res = await fetch(v instanceof URL ? v.href : v);
+      if (!res.ok) return undefined;
+      return await res.json();
+    } catch {
+      return undefined;   // offline, 404, CORS, malformed JSON — all show nothing
+    }
+  })();
+  vectorDocs.set(source, p);
+  return p;
+}

package/src/framework/panel/render.js

@@ -229,6 +229,7 @@ export function buildControls(root, parameters, params, onDirty, onCommit, opts
       fontCatalog: opts.fontCatalog,
       imageCatalog: opts.imageCatalog,
       onAssetUpload: opts.onAssetUpload,
+      declaredSource: opts.declaredSource,
     });
     nodeEls.set(node.id, widget.el);
     if (node.key && !keyToId.has(node.key)) keyToId.set(node.key, node.id);