partforge 0.149.0 → 0.150.0

package/docs/AUTHORING-PARTS.md

@@ -391,7 +391,9 @@ meta: { title: "…", units: "mm", environment: "studio" },
   treated as declaring one.
 - `color` — the base colour (`0xRRGGBB`). With a preset it is the TINT. Presets
   marked tintable are normally coloured this way (anodizing, plastic, paint);
-  the others have an intrinsic colour (brass) but still accept one.
+  the others have an intrinsic colour (brass) but still accept one. (A viewer
+  user PICKING an untintable preset drops an authored tint for that pick — see
+  the runtime section below.)
 - Overrides — each clamped to its range: `roughness` (0–1), `metalness` (0–1),
   `clearcoat` (0–1), `clearcoatRoughness` (0–1), `anisotropy` (0–1), `textureScale` (0.01–1000).
   Transmission, index of refraction, sheen and iridescence come only from a preset.
@@ -3090,6 +3092,28 @@ instead of (or in addition to) the built-in `#part` bar:
 - `runtime.controlsFor(selection) → string[]` — the param keys relevant to a pick
   (`selection.subPart`): today the picked sub-part's recorded reads plus its show/hide gate
   (`enabled()`) params.
+- **The selection popover.** Pass `selectionPopover: { slot: true | false }` (with `onPick`)
+  and a pick opens a popover at the picked spot: the sub-part's swatch, label and material as
+  one button that opens its appearance card as the popover's second page, an eye that hides
+  it, and ✕. With `slot: true` the popover also holds an empty region the host fills with its
+  own UI (a chat box, say) floated over the frame: tell partforge how tall it must be with
+  `runtime.selection.setSlotHeight(px)` and hear where it is with
+  `runtime.selection.onSlotChange(({ state, rect }) => …)` — `state` is `"open"` (with a
+  rect), `"collapsed"` (the card page is showing) or `"closed"`. The rect is in CSS px from
+  the top-left of the border box of the stage element (`elements.viewer`), not the canvas.
+  When the stage is too short for the height you asked for, the slot is given less and the
+  rect says so — scroll inside your own content; a later `setSlotHeight` or a roomier stage
+  goes back to what you asked for. `runtime.selection.onClose(({ reason }) => …)` says why
+  partforge closed it (`"dismiss"`, `"hide"`, `"gone"`); `"gone"` also fires when anything
+  releases the pick marker, `runtime.pickMarker.release()` included. Closing the popover, for
+  any reason, releases every held marker — including one the host held itself.
+  `runtime.selection.close()` closes it from the host. An open popover rides
+  `getViewerState().selection`, so a remount reopens it, on the page it was showing; whether
+  it did is settled by the time `runtime.ready` resolves, so check
+  `runtime.selection.isOpen()` after `ready`, not straight after `mount()` (a first build
+  that fails tries again on the first one that succeeds). `runtime.selection` is `null`
+  without the option. `runtime.controlsFor(selection)` is the intended source for a future
+  page of the controls that shape the picked spot.
 
 Pass `onViewChange(name)` to `mount()` to be told the active view: it fires once
 synchronously during mount with the initial resolved view (before `runtime.ready` settles),
@@ -3316,7 +3340,11 @@ drive the same state:
 
 - `runtime.setSubPartDisplay(name, patch)` — merges `patch` over the sub-part's
   override and returns the override now held (`null` when nothing is left, or
-  for an unknown `name`). Appearance keys (`material`, `color`, `roughness`,
+  for an unknown `name`). An override `material` that names an untintable
+  preset (brass, oak, …) with no override `color` beside it drops the authored
+  `color` from the effective look — picking brass means brass, not red brass —
+  while a tintable pick keeps the authored colour; a host saving the pick into
+  source should remove `color` alongside writing `material`. Appearance keys (`material`, `color`, `roughness`,
   `metalness`, `clearcoat`, `clearcoatRoughness`, `anisotropy`, `textureScale`)
   merge over the authored `display` for every render — CAD, realistic and the
   `captureView` thumbnail — so a tile picked here is drawn exactly as if it had

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.149.0",
+  "version": "0.150.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/app-materials.js

@@ -16,6 +16,8 @@ import { mount } from "./framework/index.js";
 // scripts/capture-contact-sheet.mjs can switch views and environments and call
 // runtime.renderViews — removing it breaks both.
 window.__pfRuntime = mount(materialSwatchesPart, {
+  onPick: (pick) => { window.__pfLastPick = pick; },
+  selectionPopover: { slot: false },
   createWorker: (name) =>
     new Worker(new URL("./materials-worker.js", import.meta.url), { type: "module", name }),
   onAnnotationSend: (payload) => {

package/src/framework/app.css

@@ -862,6 +862,48 @@ button.action:focus-visible, .adv-toggle:focus-visible, .sec-title:focus-visible
 .pf-card-reset { font: inherit; font-weight: 500; color: var(--pf-accent); background: none; border: 0; padding: 0; cursor: pointer; white-space: nowrap; }
 .pf-card button:focus-visible, .pf-card input:focus-visible { outline: none; box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent); }
 
+/* The selection popover (selection-popover.js): at the picked spot. */
+.pf-selection-popover {
+  position: absolute; z-index: 31;
+  width: min(320px, calc(100% - 24px)); overflow: visible;
+  padding: 8px; display: flex; flex-direction: column;
+  background: var(--pf-surface); border: 1px solid var(--pf-border);
+  border-radius: 16px; box-shadow: var(--pf-shadow-float);
+  color: var(--pf-text); font-size: 12px;
+}
+.pf-selection-popover[hidden], .pf-selection-popover [hidden] { display: none; }
+.pf-selection-tail {
+  position: absolute; width: 12px; height: 12px; transform: rotate(45deg);
+  background: var(--pf-surface); border: 1px solid var(--pf-border);
+}
+.pf-selection-popover[data-side="below"] .pf-selection-tail { top: -7px; border-right: 0; border-bottom: 0; }
+.pf-selection-popover[data-side="above"] .pf-selection-tail { bottom: -7px; border-left: 0; border-top: 0; }
+/* The 4px of padding (taken back by the negative margin) keeps a control's
+   3px focus ring inside the scroller, which would otherwise clip it. */
+.pf-selection-body { display: flex; flex-direction: column; gap: 8px; min-height: 0; overflow: auto; padding: 4px; margin: -4px; }
+.pf-selection-popover:focus { outline: none; }
+.pf-selection-spot { display: flex; flex-direction: column; gap: 6px; }
+.pf-selection-head { display: flex; align-items: center; gap: 2px; }
+.pf-selection-open {
+  flex: 1; min-width: 0; display: grid; grid-template-columns: 22px minmax(0, auto) minmax(0, 1fr);
+  align-items: center; gap: 8px; padding: 3px 6px; border: 0; border-radius: 999px;
+  background: none; font: inherit; color: var(--pf-text); text-align: left; cursor: pointer;
+}
+.pf-selection-open:hover { background: var(--pf-surface-2); }
+.pf-selection-name { font-weight: 600; font-size: 13px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.pf-selection-mat { color: var(--pf-muted-2); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.pf-selection-head .pf-parts-swatch.is-hidden { opacity: .35; }
+.pf-selection-eye, .pf-selection-close {
+  width: 28px; height: 28px; border: 0; background: none; color: var(--pf-muted-2);
+  border-radius: 999px; display: grid; place-items: center; cursor: pointer; margin-left: auto;
+}
+.pf-selection-eye:hover, .pf-selection-close:hover { background: var(--pf-surface-2); color: var(--pf-text); }
+/* The host's slot: an empty, sized region its UI floats over. */
+.pf-selection-slot { flex: none; border-radius: 12px; }
+.pf-selection-open:focus-visible, .pf-selection-eye:focus-visible, .pf-selection-close:focus-visible {
+  outline: none; box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent);
+}
+
 /* At very narrow widths the full-size viewbar (5 icon buttons + cutaway's
    Flip/Reset, ~314px) is wider than a small phone's viewport minus the
    stage's 12px margins, and .pf-shell { overflow: hidden } clips the excess

package/src/framework/materials/overrides.js

@@ -12,6 +12,7 @@
 //     animation opacity already uses), so a ghost can be faded further but not
 //     made solid from here.
 import { DISPLAY_KEYS, OVERRIDE_RANGES } from "./resolve.js";
+import { PRESETS } from "./presets.js";
 
 export const APPEARANCE_OVERRIDE_KEYS = DISPLAY_KEYS.filter((k) => k !== "opacity");
 export const VIEWING_KEYS = ["hidden", "opacity"];
@@ -65,19 +66,33 @@ export function mergeOverride(current, patch) {
   return Object.keys(next).length ? next : null;
 }
 
+// A preset whose colour is its own (brass, oak): an authored `color` still
+// tints it (resolve.js's contract), but a USER picking such a preset means
+// "make it look like that", so the pick drops the authored tint — red PLA
+// picked as brass is brass, not red brass. A tintable pick keeps the colour
+// (red PLA picked as PETG stays red). An explicit override colour wins either
+// way; the card only offers one for tintable presets.
+const untintable = (material) => typeof material === "string" && Object.hasOwn(PRESETS, material) && PRESETS[material].tintable !== true;
+
 // The display every material read sees: authored, with the override's
 // APPEARANCE keys on top. Viewing keys are never in it.
 export function effectiveDisplay(authored, override) {
   const out = isObject(authored) ? { ...authored } : {};
   if (!isObject(override)) return out;
   for (const key of APPEARANCE_OVERRIDE_KEYS) if (key in override) out[key] = override[key];
+  if ("material" in override && untintable(override.material) && !("color" in override)) delete out.color;
   return out;
 }
 
+const sameAppearance = (a, b) => APPEARANCE_OVERRIDE_KEYS.every((key) => a[key] === b[key]);
+
+// True when the override changes nothing about how the part is drawn — judged
+// on the EFFECTIVE display, not key by key, because an untintable material pick
+// with no colour of its own changes the look (the authored tint goes) while
+// naming the authored material.
 export function isAppearanceNoop(authored, override) {
   if (!isObject(override)) return true;
-  const a = isObject(authored) ? authored : {};
-  return APPEARANCE_OVERRIDE_KEYS.every((key) => !(key in override) || override[key] === a[key]);
+  return sameAppearance(effectiveDisplay(authored, null), effectiveDisplay(authored, override));
 }
 
 // A carried map, made safe for THIS part (spec A.4): names the part no longer
@@ -96,8 +111,17 @@ export function pruneOverrides(map, part) {
     if (!sp) continue;
     const clean = mergeOverride(null, sanitizeDisplayPatch(raw));
     if (!clean) continue;
+    // An appearance key goes when dropping it leaves the effective display as
+    // it is — which is "equals the authored value", except that an untintable
+    // material naming the authored material still earns its keep when it is
+    // what drops the authored tint.
     const authored = isObject(sp.display) ? sp.display : {};
-    for (const key of APPEARANCE_OVERRIDE_KEYS) if (key in clean && clean[key] === authored[key]) delete clean[key];
+    for (const key of APPEARANCE_OVERRIDE_KEYS) {
+      if (!(key in clean)) continue;
+      const without = { ...clean };
+      delete without[key];
+      if (sameAppearance(effectiveDisplay(authored, clean), effectiveDisplay(authored, without))) delete clean[key];
+    }
     if (Object.keys(clean).length) out[name] = clean;
   }
   return out;

package/src/framework/mount.js

@@ -10,6 +10,7 @@ import { createTooltipPresenter, attachButtonTooltips } from "./tooltip.js";
 import { loadCamera, loadRenderMode, loadEnvironment } from "./view-state.js";
 import { isFaceAlignedState } from "./projection.js";
 import { attachViewStyleControls } from "./view-style-controls.js";
+import { attachSelectionPopover } from "./selection-popover.js";
 import { ENVIRONMENTS } from "./materials/environments.js";
 import { declaresMaterials, resolveMaterial } from "./materials/resolve.js";
 import { printFrameMatrix } from "./materials/print-frame.js";
@@ -72,7 +73,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, listExportFormats, exportParts, warmExportKernel, setHostPane, setRailLayout, animation, getView, setView, captureView, attachTooltips, measure, annotate, projection, pickMarker, getPanelState, getPanelErrors, controlsFor, renderMode, environment, declaresMaterials, renderViews, isPreviewActive, exportPreview, pendingCutaway, listSubParts, openAppearance, setDisplaySaveState }) {
+export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, listExportFormats, exportParts, warmExportKernel, setHostPane, setRailLayout, animation, getView, setView, captureView, attachTooltips, measure, annotate, projection, pickMarker, getPanelState, getPanelErrors, controlsFor, renderMode, environment, declaresMaterials, renderViews, isPreviewActive, exportPreview, pendingCutaway, listSubParts, openAppearance, setDisplaySaveState, selection, selectionState }) {
   return {
     ready, dispose, setParams,
     // Whether the `preview` GLB handed to mount() is on screen (see mount's
@@ -137,7 +138,12 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
       // Only while something is overridden: an empty map would be noise in a
       // token hosts compare and store.
       ...(() => { const d = viewer.getDisplayOverrides?.(); return d && Object.keys(d).length ? { display: d } : {}; })(),
+      // The open selection popover, so a remount reopens it where it was.
+      ...(() => { const s = selectionState?.(); return s ? { selection: s } : {}; })(),
     }),
+    // The selection popover (mount's `selectionPopover` option), or null:
+    // { setSlotHeight(px), onSlotChange(cb) → off, onClose(cb) → off, close(), isOpen() }.
+    selection: selection ?? null,
     // --- per-sub-part display overrides (spec 2026-10-13 part appearance controls) ---
     // Live, no rebuild: appearance keys (material, colour, finish) merge over
     // the authored `display` for every render; `hidden` and `opacity` are how
@@ -452,6 +458,14 @@ function createCleanupStack() {
 //                                         // message — and calls runtime.annotate.send() itself.
 //                                         // Ignored without onAnnotationSend (there is no toolbar
 //                                         // to place it in).
+// selectionPopover: { slot: boolean }    // opt in to the selection popover: a pick
+//                                         // (onPick required) opens a popover at the
+//                                         // spot — the sub-part's swatch/label/material
+//                                         // (opens its appearance card), an eye, ✕ —
+//                                         // and, with slot: true, an empty slot the
+//                                         // host floats its own UI over (see
+//                                         // runtime.selection). Absent or not an
+//                                         // object: no popover, exactly as before.
 // onAssetUpload(blob, { kind, filename }) // the drop widget's (widgets/file-drop.js) upload hook:
 //                                         // async, resolves to a source string (an https: URL or a
 //                                         // host token) that gets written into the param. `blob` is
@@ -487,6 +501,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
                               viewerState, preview,
                               files, panelState,
                               annotateSend = "viewbar",
+                              selectionPopover,
                               container: legacyContainer, controls: legacyControls } = {}) {
   // --- element resolution (the only getElementById calls in the framework, save the ?pickserver client's optional #viewbar lookup) ----
   const byId = (id) => document.getElementById(id);
@@ -797,21 +812,71 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
     // cube's bottom-right corner, in the stack, hiding with the cube. It is
     // a #viewbar child, so --pf-viewbar-clear below measures it for free (the
     // bar grows wider, not taller).
+    // The Parts seam (view-style-controls.js), shared with the selection
+    // popover below; an older popover ignores it.
+    const partsSeam = {
+      list: () => subPartRows(part, { view: view(), params, overrides: viewer.getDisplayOverrides?.() ?? {} }),
+      setDisplay: (name, patch) => viewer.setSubPartDisplay(name, patch),
+      clear: (opts) => viewer.clearSubPartDisplay(opts),
+      onChange: (cb) => viewer.onDisplayChange?.(cb) ?? (() => {}),
+      onViewChange: (cb) => { viewChangeListeners.add(cb); return () => viewChangeListeners.delete(cb); },
+      getState: (name) => viewer.getSubPartDisplayState(name),
+    };
     const viewStyle = attachViewStyleControls(viewer, {
       stage: els.viewer,
       toolbar: els.viewer.querySelector("#viewbar"),
       anchor: viewcube.element,
-      // The Parts section's seam (view-style-controls.js); an older popover ignores it.
-      parts: {
-        list: () => subPartRows(part, { view: view(), params, overrides: viewer.getDisplayOverrides?.() ?? {} }),
-        setDisplay: (name, patch) => viewer.setSubPartDisplay(name, patch),
-        clear: (opts) => viewer.clearSubPartDisplay(opts),
-        onChange: (cb) => viewer.onDisplayChange?.(cb) ?? (() => {}),
-        onViewChange: (cb) => { viewChangeListeners.add(cb); return () => viewChangeListeners.delete(cb); },
-        getState: (name) => viewer.getSubPartDisplayState(name),
-      },
+      parts: partsSeam,
     }, { tooltip });
     cleanup.defer(() => viewStyle.detach());
+    // The selection popover (spec 2026-10-14): opened by the picker below,
+    // following the held pick marker. Only with onPick, and only for a host
+    // that passed the option as an object.
+    const selectionOpt = onPick && selectionPopover && typeof selectionPopover === "object"
+      ? { slot: selectionPopover.slot === true } : null;
+    let selPopover = null;
+    let pendingSelection = null; // a carried selection waiting for its marker's first anchor
+    // The marker's anchor is in canvas px; the popover lives in the stage.
+    const toStage = (a) => {
+      if (!a) return null;
+      const s = els.viewer.getBoundingClientRect();
+      const c = viewer.domElement.getBoundingClientRect();
+      return { x: a.x + c.left - s.left, y: a.y + c.top - s.top, visible: a.visible !== false };
+    };
+    if (selectionOpt) {
+      selPopover = attachSelectionPopover({
+        stage: els.viewer, canvas: viewer.domElement, slot: selectionOpt.slot, parts: partsSeam,
+        renderThumb: viewer.renderMaterialThumbnail ? (id, display) => viewer.renderMaterialThumbnail(display, { size: 96 }) : null,
+        getSaveState: () => viewStyle.getSaveState?.() ?? "screen-only",
+        // Every close lets the marker go. Its null anchor arrives with the
+        // popover already closed, so the listener below ignores it.
+        onClosed: () => viewer.releaseFlashPoints?.(),
+        // Converted at every placement, not once per anchor: the canvas can
+        // move within the stage (a dock inset) with no new anchor arriving.
+        toStage,
+      });
+      cleanup.defer(() => selPopover.detach());
+      cleanup.defer(viewer.onFlashAnchorChange?.((a) => {
+        if (pendingSelection && a) {
+          const carried = pendingSelection;
+          pendingSelection = null;
+          // Straight onto the carried page: one slot report, not open-then-collapsed.
+          // A refusal lets go of the marker restoreCarriedSelection lit and held.
+          if (!selPopover.open({ subPart: carried.subPart, anchor: a, page: carried.page })) viewer.releaseFlashPoints?.();
+          return;
+        }
+        if (!selPopover.isOpen()) return;
+        if (!a) { selPopover.close("gone"); return; }
+        selPopover.setAnchor(a);
+      }) ?? (() => {}));
+      const closeGone = () => selPopover.close("gone");
+      viewChangeListeners.add(closeGone);
+      cleanup.defer(() => viewChangeListeners.delete(closeGone));
+      // A mode that claims the canvas closes it (measureMode and annotateMode
+      // are both created above).
+      cleanup.defer(measureMode.onModeChange(() => { if (measureMode.isEnabled()) selPopover.close("gone"); }));
+      if (annotateMode) cleanup.defer(annotateMode.onModeChange(() => { if (annotateMode.isEnabled()) selPopover.close("gone"); }));
+    }
     // setHidden takes one boolean, and there are two independent reasons to hide
     // the cube: Sketch mode (below) and a crowded transport bar (wired into the
     // animation controls further down). Applied straight, whichever fires last
@@ -888,16 +953,26 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
         // deliberately not guarded — one is armed by an explicit dev toggle,
         // the other per agent request.
         suppressed: () => previewGate.isActive() || measureMode.isEnabled() || (annotateMode?.isEnabled() ?? false),
-        onPick: (selection, anchor) => onPick({
-          selection,
-          label: selection.feature?.label ?? part.parts[selection.subPart]?.label ?? selection.subPart,
-          prompt: formatSelection(selection, { style: "prompt" }),
-          token: formatSelection(selection, { style: "token" }),
-          // Where the marker is on the canvas, in CSS px from its top-left, so
-          // a host can put its own UI beside the dot on the first frame rather
-          // than a round trip later.
-          anchor,
-        }),
+        onPick: (selection, anchor) => {
+          onPick({
+            selection,
+            label: selection.feature?.label ?? part.parts[selection.subPart]?.label ?? selection.subPart,
+            prompt: formatSelection(selection, { style: "prompt" }),
+            token: formatSelection(selection, { style: "token" }),
+            // Where the marker is on the canvas, in CSS px from its top-left, so
+            // a host can put its own UI beside the dot on the first frame rather
+            // than a round trip later.
+            anchor,
+          });
+          // After the host has its chip: open at the spot, and keep the marker.
+          if (selPopover && selPopover.open({ subPart: selection.subPart ?? null, anchor })) {
+            viewer.holdFlashPoint?.();
+          } else if (selPopover?.isOpen()) {
+            // A pick it cannot show (slot-less, no listed sub-part) moves on from
+            // the open one rather than leaving it, and its held dot, behind.
+            selPopover.close("dismiss");
+          }
+        },
       });
       cleanup.defer(() => picker.detach());
       picker.setActive(true);
@@ -923,6 +998,18 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
     let framedView = null; // the view the camera was last framed to (null until first show)
     let cameraRestored = false; // saved camera applied once, on the first frame after load
     let cutawayRestored = false; // a carried cutaway, applied once — after any preview, never on one
+    let selectionRestored = false; // a carried selection, tried once, after the camera
+    function restoreCarriedSelection() {
+      selectionRestored = true;
+      const c = viewerState?.selection;
+      if (!selPopover || !c || !Array.isArray(c.point) || c.point.length !== 3 || !c.point.every(Number.isFinite)) return;
+      const subPart = typeof c.subPart === "string" ? c.subPart : null;
+      if (subPart !== null && !partsSeam.list().some((r) => r.name === subPart && r.inView)) return;
+      pendingSelection = { subPart, page: c.page === "appearance" ? "appearance" : "spot" };
+      viewer.flashPoint(c.point);
+      // hold() publishes the marker's anchor synchronously; the listener opens us.
+      if (!viewer.holdFlashPoint?.()) pendingSelection = null;
+    }
 
     // Per-sub-part cache-validity tracker (Layer 1): view/version/caching change over
     // time, so they're passed as getters; params is a stable in-place-mutated object.
@@ -1060,6 +1147,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
         // — not the carried one.
         restoreCarriedCutaway(viewer.getCameraState());
       }
+      if (cameraRestored && !selectionRestored && !previewGate.isActive()) restoreCarriedSelection();
     }
 
     // Frames the realistic look reads, for the geometry just delivered:
@@ -1658,7 +1746,19 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
       // `opts` may be null from a host (a destructuring default covers only undefined).
       listSubParts: (opts) => subPartRows(part, { view: opts?.view ?? view(), params, overrides: viewer.getDisplayOverrides?.() ?? {} }),
       openAppearance: (name) => viewStyle.openCard?.(name) ?? false,
-      setDisplaySaveState: (state) => viewStyle.setSaveState?.(state),
+      setDisplaySaveState: (state) => { viewStyle.setSaveState?.(state); selPopover?.refreshSaveState(); },
+      selection: selPopover ? {
+        setSlotHeight: (px) => selPopover.setSlotHeight(px),
+        onSlotChange: (cb) => selPopover.onSlotChange(cb),
+        onClose: (cb) => selPopover.onClose(cb),
+        close: () => selPopover.close(),
+        isOpen: () => selPopover.isOpen(),
+      } : null,
+      selectionState: () => {
+        const st = selPopover?.getState();
+        const point = st ? viewer.getHeldAnchorPoint?.() : null;
+        return st && point ? { subPart: st.subPart, point, page: st.page } : null;
+      },
       setView: (name) => tabsCtl.select(name),
       captureView,
       getPanelState: () => panelRef?.getState() ?? {},

package/src/framework/selection-placement.js

@@ -0,0 +1,40 @@
+// Where the selection popover sits relative to the pick marker. Pure: handed
+// measurements, returns geometry. Moved here from partforge-cloud's
+// pickBubblePlacement.js (2026-10-14) when the pick bubble became partforge's.
+//
+// `tailInset` must stay above the popover's corner radius, or the tail can land
+// on the curve. `gutter` is the clearance kept at each stage edge.
+export const SELECTION_GUTTER = 12;
+
+export function planSelectionPlacement({ anchor, box, stage }, options = {}) {
+  // Destructuring defaults, not a spread: an explicit `undefined` from a caller
+  // forwarding options must fall back, not yield NaN.
+  const { gap = 10, tailInset = 28, gutter = SELECTION_GUTTER } = options;
+  const minLeft = stage.left + gutter;
+  const maxLeft = stage.left + stage.width - gutter - box.width;
+  const centred = anchor.x - box.width / 2;
+  // A box wider than the stage inverts the clamp; pin it to the left gutter.
+  const left = maxLeft < minLeft ? minLeft : Math.min(Math.max(centred, minLeft), maxLeft);
+  const belowTop = anchor.y + gap;
+  const roomBelow = stage.top + stage.height - gutter - belowTop;
+  const roomAbove = anchor.y - gap - (stage.top + gutter);
+  const fitsBelow = box.height <= roomBelow;
+  const fitsAbove = box.height <= roomAbove;
+  // Neither fitting takes the side with more room (ties below); the caller caps
+  // the box's height to `maxHeight` so it scrolls instead of leaving the stage.
+  const side = fitsBelow || (!fitsAbove && roomBelow >= roomAbove) ? "below" : "above";
+  const room = side === "below" ? roomBelow : roomAbove;
+  const aboveTop = anchor.y - gap - Math.min(box.height, Math.max(room, 0));
+  // From the ROUNDED left — the edge actually painted — or an odd width puts
+  // the tail a pixel off the dot.
+  const painted = Math.round(left);
+  const tail = anchor.x - painted;
+  const tailFits = tail >= tailInset && tail <= box.width - tailInset;
+  return {
+    left: painted,
+    top: Math.round(side === "below" ? belowTop : aboveTop),
+    side,
+    maxHeight: Math.max(0, Math.floor(room)),
+    tailOffset: anchor.visible !== false && tailFits ? Math.round(tail) : null,
+  };
+}

package/src/framework/selection-popover.js

@@ -0,0 +1,299 @@
+// src/framework/selection-popover.js
+// The popover a pick opens at the picked spot (spec 2026-10-14 selection
+// popover). Two pages: "spot" — a head row (the sub-part's swatch + label +
+// material as ONE button that opens the appearance page, an eye that hides the
+// part, ✕) and, for a host that asked for one, an empty SLOT the host floats
+// its own UI over (partforge-cloud puts its chat composer there) — and
+// "appearance", the appearance card (Task 3).
+//
+// It never decides anything about the slot's content: the host says how tall
+// it must be (setSlotHeight) and is told where it is (onSlotChange). Mount owns
+// the pick marker; this module is handed the marker's position as the marker
+// reports it, and `toStage` turns that into stage px at every placement (so a
+// canvas that moves within the stage is followed on the next re-place).
+import { attachAppearanceCard } from "./appearance-card.js";
+import { hexColor } from "./parts-list.js";
+import { planSelectionPlacement } from "./selection-placement.js";
+
+const MIN_SLOT = 44;
+const MAX_SLOT = 2000;
+const ICONS = {
+  eyeOff: `<svg viewBox="0 0 24 24" width="15" height="15" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M10.733 5.076a10.744 10.744 0 0 1 11.205 6.575 1 1 0 0 1 0 .696 10.747 10.747 0 0 1-1.444 2.49"/><path d="M14.084 14.158a3 3 0 0 1-4.242-4.242"/><path d="M17.479 17.499a10.75 10.75 0 0 1-15.417-5.151 1 1 0 0 1 0-.696 10.75 10.75 0 0 1 4.446-5.143"/><path d="m2 2 20 20"/></svg>`,
+  close: `<svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg>`,
+};
+
+function el(tag, className, attrs = {}) {
+  const e = document.createElement(tag);
+  if (className) e.className = className;
+  for (const [k, v] of Object.entries(attrs)) e.setAttribute(k, v);
+  return e;
+}
+
+export function attachSelectionPopover({ stage, canvas = null, slot = false, parts, renderThumb = null, getSaveState = () => "screen-only", onClosed = null, toStage = (a) => a } = {}) {
+  const pop = el("div", "pf-selection-popover", { role: "dialog", "aria-label": "Selected spot", tabindex: "-1" });
+  pop.hidden = true;
+  const tail = el("span", "pf-selection-tail", { "aria-hidden": "true" });
+  const spot = el("div", "pf-selection-spot");
+  const head = el("div", "pf-selection-head");
+  const openBtn = el("button", "pf-selection-open", { type: "button" });
+  const swatch = el("span", "pf-parts-swatch", { "aria-hidden": "true" });
+  const nameEl = el("span", "pf-selection-name");
+  const matEl = el("span", "pf-selection-mat");
+  openBtn.append(swatch, nameEl, matEl);
+  const eye = el("button", "pf-selection-eye", { type: "button" });
+  eye.innerHTML = ICONS.eyeOff;
+  const closeBtn = el("button", "pf-selection-close", { type: "button", "aria-label": "Close" });
+  closeBtn.innerHTML = ICONS.close;
+  head.append(openBtn, eye, closeBtn);
+  spot.append(head);
+  const slotEl = slot ? el("div", "pf-selection-slot") : null;
+  if (slotEl) { slotEl.style.height = `${MIN_SLOT}px`; spot.append(slotEl); }
+  // Scrolls in here, not on the popover: the tail pokes out past the popover's edge.
+  const body = el("div", "pf-selection-body");
+  body.append(spot);
+  pop.append(tail, body);
+  stage.append(pop);
+
+  let current = null; // { subPart, anchor } while open; anchor as handed in, before toStage
+  let requestedSlot = MIN_SLOT; // what the host asked for; place() may apply less
+  let page = "spot";
+  let card = null;    // built on first use of the appearance page
+  let lastSlotKey = null;
+  let detached = false;
+  const slotCbs = new Set();
+  const closeCbs = new Set();
+
+  const isOpen = () => !pop.hidden;
+  const rowFor = (n) => (typeof n === "string" ? parts.list().find((r) => r.name === n && r.inView) ?? null : null);
+
+  function renderHead() {
+    const row = rowFor(current?.subPart);
+    openBtn.hidden = !row;
+    eye.hidden = !row;
+    if (!row) { pop.setAttribute("aria-label", "Selected spot"); return null; }
+    swatch.style.setProperty("--pf-swatch", hexColor(row.color));
+    swatch.classList.toggle("is-hidden", !!row.hidden);
+    nameEl.textContent = row.label;
+    matEl.textContent = row.materialLabel ?? "No material";
+    openBtn.setAttribute("aria-label", `Change appearance of ${row.label}`);
+    eye.setAttribute("aria-label", `Hide ${row.label}`);
+    pop.setAttribute("aria-label", row.label);
+    return row;
+  }
+
+  function emitSlot() {
+    if (!slotEl || detached) return;
+    let report;
+    if (!isOpen()) report = { state: "closed" };
+    else if (page !== "spot") report = { state: "collapsed" };
+    else {
+      const s = stage.getBoundingClientRect();
+      const r = slotEl.getBoundingClientRect();
+      report = { state: "open", rect: {
+        x: Math.round(r.left - s.left), y: Math.round(r.top - s.top),
+        width: Math.round(r.width), height: Math.round(r.height),
+      } };
+    }
+    const key = JSON.stringify(report);
+    if (key === lastSlotKey) return;
+    lastSlotKey = key;
+    for (const cb of [...slotCbs]) {
+      try { cb(report); } catch (e) { console.warn("partforge: selection slot listener failed", e); }
+    }
+  }
+
+  function place() {
+    if (!isOpen() || !current?.anchor) return;
+    const anchor = toStage(current.anchor);
+    if (!anchor) return;
+    const s = stage.getBoundingClientRect();
+    const planFor = () => planSelectionPlacement({
+      anchor,
+      box: { width: pop.offsetWidth, height: pop.offsetHeight },
+      stage: { left: 0, top: 0, width: s.width, height: s.height },
+    });
+    // Clearing the cap below stops the body overflowing for a moment, and the
+    // browser answers by resetting its scroll to the top — so every slider
+    // write from the card (each re-places the popover) jumped back up. Keep
+    // the scroll across the measurement.
+    const scrolled = body.scrollTop;
+    // Measure the natural height at the host's REQUESTED slot height, not last
+    // frame's cap — a taller stage or a new request starts from the request.
+    pop.style.maxHeight = "";
+    if (slotEl) slotEl.style.height = `${requestedSlot}px`;
+    let plan = planFor();
+    // Short of room, the slot gives up the difference so the whole popover fits
+    // and the rect reported is the slot's real one: a host UI floated at it then
+    // scrolls inside itself rather than spilling past the popover. The floor
+    // still holds, and only then does the body scroll.
+    const natural = pop.offsetHeight;
+    if (slotEl && page === "spot" && natural > plan.maxHeight) {
+      const laidOut = slotEl.getBoundingClientRect().height;
+      const applied = Math.max(MIN_SLOT, Math.min(requestedSlot, Math.floor(plan.maxHeight - (natural - laidOut))));
+      if (applied < requestedSlot) {
+        slotEl.style.height = `${applied}px`;
+        plan = planFor(); // the smaller box may now fit on a side it did not before
+      }
+    }
+    pop.style.maxHeight = `${plan.maxHeight}px`;
+    pop.style.left = `${plan.left}px`;
+    pop.style.top = `${plan.top}px`;
+    pop.dataset.side = plan.side;
+    tail.hidden = plan.tailOffset === null;
+    if (plan.tailOffset !== null) tail.style.left = `${plan.tailOffset - 6}px`;
+    body.scrollTop = scrolled;
+    emitSlot();
+  }
+
+  // Built on first use, so a popover that never shows a card holds none of its
+  // ~40 controls (the view style popover's rule).
+  function ensureCard() {
+    if (card) return card;
+    card = attachAppearanceCard(parts, {
+      onBack: () => showPage("spot"),
+      onClose: () => close("dismiss"),
+      // A rebuild dropped the part this card was for: the spot it pointed at
+      // is gone too.
+      onGone: () => { if (isOpen() && page === "appearance") close("gone"); },
+      getSaveState,
+      renderThumb,
+    });
+    card.element.hidden = true;
+    body.append(card.element);
+    return card;
+  }
+
+  function showPage(next) {
+    if (!isOpen()) return false;
+    if (next === "appearance") {
+      const n = current?.subPart;
+      if (!rowFor(n)) return false;
+      if (!ensureCard().show(n)) return false;
+    } else if (next !== "spot") {
+      return false;
+    }
+    // A new page starts at its top; place() below keeps whatever this leaves.
+    if (next !== page) body.scrollTop = 0;
+    page = next;
+    pop.dataset.page = page;
+    spot.hidden = page !== "spot";
+    if (card) {
+      card.element.hidden = page !== "appearance";
+      if (page !== "appearance") card.hide();
+    }
+    // Focus the popover itself, never one of its buttons: a pick (or a click
+    // on the head button) is a pointer action, and a button focused from
+    // script draws its keyboard ring in Chromium. On the popover, Escape still
+    // closes it and Tab reaches the first control. A host slot keeps focus on
+    // the spot page (the host's own UI owns it there).
+    if (page === "appearance" || !slot) pop.focus({ preventScroll: true });
+    place();
+    return true;
+  }
+
+  const onOutside = (e) => {
+    const t = e.target;
+    if (pop.contains(t)) return;
+    // A canvas press is a pick (which re-points us) or an orbit (which we
+    // follow) — never a dismiss.
+    if (canvas && canvas.contains(t)) return;
+    if (!stage.contains(t)) return;
+    close("dismiss");
+  };
+  const onKey = (e) => {
+    if (e.key !== "Escape" || !isOpen()) return;
+    e.stopPropagation();
+    e.preventDefault();
+    close("dismiss");
+  };
+  pop.addEventListener("keydown", onKey);
+  openBtn.addEventListener("click", () => showPage("appearance"));
+  eye.addEventListener("click", () => {
+    const n = current?.subPart;
+    if (typeof n === "string") parts.setDisplay(n, { hidden: true });
+    close("hide");
+  });
+  closeBtn.addEventListener("click", () => close("dismiss"));
+
+  // `page: "appearance"` opens straight onto the card (a carried selection
+  // reopening where it was) with one slot report, not an "open" then a
+  // "collapsed"; with no head row to open a card for, it is the spot page.
+  function open({ subPart = null, anchor, page: startPage = "spot" } = {}) {
+    if (detached || !anchor) return false;
+    const n = typeof subPart === "string" ? subPart : null;
+    if (!slot && !rowFor(n)) return false;
+    const wasOpen = isOpen();
+    current = { subPart: n, anchor };
+    pop.hidden = false;
+    renderHead();
+    if (!wasOpen) document.addEventListener("pointerdown", onOutside, true);
+    if (startPage !== "appearance" || !showPage("appearance")) showPage("spot");
+    return true;
+  }
+
+  function setAnchor(anchor) {
+    if (!isOpen() || !anchor) return;
+    current.anchor = anchor;
+    place();
+  }
+
+  function setSlotHeight(px) {
+    if (!slotEl || typeof px !== "number" || !Number.isFinite(px) || px < 0) return;
+    requestedSlot = Math.min(MAX_SLOT, Math.max(MIN_SLOT, Math.round(px)));
+    slotEl.style.height = `${requestedSlot}px`;
+    place();
+  }
+
+  function close(reason) {
+    if (!isOpen()) return;
+    pop.hidden = true;
+    card?.hide?.();
+    if (card) card.element.hidden = true;
+    page = "spot";
+    body.scrollTop = 0; // the next open starts at the top
+    spot.hidden = false;
+    current = null;
+    document.removeEventListener("pointerdown", onOutside, true);
+    emitSlot();
+    onClosed?.();
+    if (reason) for (const cb of [...closeCbs]) {
+      try { cb({ reason }); } catch (e) { console.warn("partforge: selection close listener failed", e); }
+    }
+  }
+
+  const offParts = parts.onChange?.(() => {
+    if (!isOpen()) return;
+    // Without a slot there is nothing to show for a sub-part that left the view.
+    if (!renderHead() && !slot) { close("gone"); return; }
+    place();
+  }) ?? (() => {});
+  const ro = typeof ResizeObserver === "function" ? new ResizeObserver(() => place()) : null;
+  ro?.observe(stage);
+  ro?.observe(pop);
+
+  return {
+    element: pop,
+    open,
+    setAnchor,
+    setSlotHeight,
+    showPage,
+    close: (reason) => close(reason === "dismiss" || reason === "hide" || reason === "gone" ? reason : undefined),
+    isOpen,
+    getState: () => (isOpen() ? { subPart: current.subPart, page } : null),
+    onSlotChange: (cb) => { if (typeof cb !== "function") return () => {}; slotCbs.add(cb); return () => slotCbs.delete(cb); },
+    onClose: (cb) => { if (typeof cb !== "function") return () => {}; closeCbs.add(cb); return () => closeCbs.delete(cb); },
+    refreshSaveState: () => { if (isOpen() && page === "appearance") card?.render(); },
+    detach() {
+      if (detached) return;
+      detached = true;
+      document.removeEventListener("pointerdown", onOutside, true);
+      pop.removeEventListener("keydown", onKey);
+      offParts();
+      ro?.disconnect();
+      card?.detach?.();
+      slotCbs.clear();
+      closeCbs.clear();
+      pop.remove();
+    },
+  };
+}

package/src/framework/viewer.js

@@ -2947,6 +2947,12 @@ export function createViewer(container, part) {
     publishAnchor(null);
   }
 
+  // The world position of the held marker the anchor stream follows, so a host
+  // (mount's selection carry) can put the same marker back after a remount.
+  function getHeldAnchorPoint() {
+    return anchorDot ? [anchorDot.position.x, anchorDot.position.y, anchorDot.position.z] : null;
+  }
+
   function onFlashAnchorChange(cb) {
     // The `disposed` half is the same guard cutaway's onHandleHoverChange takes,
     // and for the same two reasons: a subscribe racing teardown (effect-cleanup
@@ -3092,6 +3098,7 @@ export function createViewer(container, part) {
     projectPoint,
     holdFlashPoint,
     releaseFlashPoints,
+    getHeldAnchorPoint,
     onFlashAnchorChange,
     cutawaySupported: () => cutaway.isSupported,
     cutawayEnabled: () => cutaway.isEnabled,

package/types/index.d.ts

@@ -212,6 +212,8 @@ export interface MountOptions {
    * and takes precedence over the `?pick` and `?pickserver` URL modes.
    */
   onPick?: (event: PickEvent) => void;
+  /** Opt in to the selection popover (requires `onPick`): a pick opens a popover at the spot with the sub-part's appearance controls, and with `slot: true` an empty region the host floats its own UI over (`runtime.selection`). */
+  selectionPopover?: { slot: boolean };
   /** Receive exported bytes instead of partforge's own DOM download. */
   onDownload?: (file: DownloadPayload) => void;
   /** The active view (tab) name — emitted once on mount, then on every change. */
@@ -316,6 +318,8 @@ export interface CutawayState {
  * `MountOptions.viewerState`.
  */
 export interface ViewerState {
+  /** The open selection popover, reopened by the next mount if the sub-part is still in the view. */
+  selection?: { subPart: string | null; point: [number, number, number]; page: "spot" | "appearance" };
   /** The live camera pose, or `null` when the viewer could not report one. */
   camera: { pos: [number, number, number]; target: [number, number, number] } | null;
   /**
@@ -514,6 +518,43 @@ export interface AnnotateRuntime {
   onModeChange(cb: () => void): () => void;
 }
 
+/**
+ * Where the selection popover's host slot is, or why it has none. `rect` is in
+ * CSS px from the top-left of the border box of the stage element
+ * (`elements.viewer`), not the canvas. On a stage too short for the requested
+ * height the slot is given less, and `rect.height` is what it was given.
+ */
+export type SelectionSlotReport =
+  | { state: "open"; rect: { x: number; y: number; width: number; height: number } }
+  | { state: "collapsed" }
+  | { state: "closed" };
+
+/**
+ * The selection popover's host-facing controls (`runtime.selection`). A carried
+ * selection (`viewerState.selection`) has reopened, or not, by the time
+ * `runtime.ready` resolves — check `isOpen()` after `ready`, not right after
+ * `mount()`. (A failed first build tries again on the first successful one.)
+ */
+export interface SelectionRuntime {
+  /**
+   * The height (CSS px, integer, 44–2000) the host's slot content needs. A stage
+   * too short for it applies less (never below 44); the request is kept, so a
+   * roomier stage restores it.
+   */
+  setSlotHeight(px: number): void;
+  /** Where the slot is, relative to the stage element's border box; fires on every change. Never fires for `slot: false`. */
+  onSlotChange(cb: (report: SelectionSlotReport) => void): () => void;
+  /**
+   * Why partforge closed it. A host's own `close()` does not fire this.
+   * `"gone"` also fires when anything releases the pick marker
+   * (`runtime.pickMarker.release()` included). Any close releases every held
+   * marker, including one the host held itself.
+   */
+  onClose(cb: (event: { reason: "dismiss" | "hide" | "gone" }) => void): () => void;
+  close(): void;
+  isOpen(): boolean;
+}
+
 /**
  * The yellow marker a pick flashes, as a thing with a lifetime — for a host
  * that hangs its own UI (a chat bubble, a callout) off the dot. A marker fades
@@ -703,6 +744,8 @@ export interface PartRuntime {
   annotate: AnnotateRuntime;
   /** The pick marker's lifetime — hold it on screen and follow it across the canvas. Always present (a no-op stand-in outside `makeHandle` tests). */
   pickMarker: PickMarkerRuntime;
+  /** The selection popover, or `null` without the `selectionPopover` option. */
+  selection: SelectionRuntime | null;
   /** Realistic render mode (docs "Materials and appearance"). set() resolves to the mode actually in effect — "cad" if assets failed to load. */
   renderMode: {
     get(): RenderMode;