partforge 0.147.0 → 0.149.0

package/docs/AUTHORING-PARTS.md

@@ -493,6 +493,13 @@ the viewer's blue-grey.
 maple table), `print-bed` (a dim, hard-lit enclosure over a standard-size PEI build plate (180, 220, 256 or 350 mm) marked with its size), `outdoor` (overcast sky,
 concrete).
 
+**Viewers can change a sub-part's look.** The View style popover's Parts
+section lets a user pick a material and colour per sub-part, fade it, or hide
+it, live and without a rebuild (`runtime.setSubPartDisplay` below). Material
+and colour draw exactly as if authored, and a host may write them back into
+`display`; hiding and see-through are only ever how the screen looks — exports,
+`captureViews` and `renderViews` never see them.
+
 ---
 
 ## Geometry: the kernel / `Solid` API
@@ -3299,6 +3306,48 @@ back into the next `mount()` call to resume both where the previous mount
 left them; omit it on a first mount and the viewer restores its own persisted
 choice instead, the same way it does for the camera.
 
+### `runtime.setSubPartDisplay`, `runtime.listSubParts`, `runtime.openAppearance`
+
+A viewer user can change how one sub-part looks, or hide it, without a rebuild.
+The View style popover (the eye) has a **Parts** section — the sub-parts in the
+active view, an eye and a swatch each — and the swatch opens an appearance card
+(material presets, colour for tintable presets, finish, See-through). A host can
+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`,
+  `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
+  been authored. Two **viewing** keys are different: `hidden` (boolean) and
+  `opacity` (0.05–1, a multiplier on an authored `display.opacity`). They are
+  how the user is looking: never part of a material read, an export, lint or
+  `declaresMaterials`, and `captureViews` / `renderViews` (the agent's renders)
+  draw every sub-part as if they were unset. `captureCurrent` follows them,
+  like the screen, unless called with `{ includeHidden: true }`. A `null` value
+  clears a key; `hidden: false` and `opacity: 1` clear theirs.
+- `runtime.getSubPartDisplay(name)` → `{ authored, override, effective, hidden,
+  opacity }`, or `null`.
+- `runtime.clearSubPartDisplay({ viewing?, appearance?, name? })` — Show all is
+  `{ viewing: true }`; the card's Reset is `{ appearance: true, name }`.
+- `runtime.onSubPartDisplayChange(cb)` — `cb({ name, override })` after a
+  change, `cb(null)` after a clear; returns the unsubscribe. A host that
+  persists overrides into source (partforge-cloud writes the sub-part's
+  `display` literal) listens here.
+- `runtime.listSubParts({ view? })` — every sub-part as `{ name, label, inView,
+  hidden, opacity, effective, color, materialLabel, tintable, overridden }`, in
+  definition order, for the active view unless `view` names another.
+- `runtime.openAppearance(name)` — opens the popover on the card for `name`;
+  `runtime.setDisplaySaveState("saved" | "screen-only" | "blocked")` sets the
+  card's footer line ("screen-only" is the default; a host that saves says so).
+
+The override map rides `viewerState.display` and comes back through
+`mount({ viewerState })`, pruned for the new part: an entry for a sub-part the
+part no longer declares is dropped, and an appearance key that now equals the
+authored value is dropped (a host that saved the change into source sees its
+override vanish on the next mount, which is the intended self-clean).
+
 ### The annotation payload's camera block
 
 `onAnnotationSend(payload)` receives a `camera` block in two frames — `world`

package/package.json

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

@@ -774,10 +774,11 @@ button.action:focus-visible, .adv-toggle:focus-visible, .sec-title:focus-visible
 }
 .pf-view-style-popover[hidden] { display: none; }
 .pf-view-style-heading { margin: 0; font-size: 11px; letter-spacing: 0.06em; text-transform: uppercase; color: var(--pf-muted-2); }
-.pf-view-style-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 8px; }
+.pf-view-style-grid { display: grid; grid-template-columns: repeat(5, 1fr); gap: 6px; }
 .pf-view-style-tile {
   display: flex; flex-direction: column; gap: 4px; padding: 0; border: 0;
   background: none; color: var(--pf-muted-2); cursor: pointer; font: inherit; text-align: center;
+  font-size: 10.5px;
 }
 .pf-view-style-thumb {
   display: block; aspect-ratio: 1; border-radius: 8px; overflow: hidden;
@@ -796,6 +797,70 @@ button.action:focus-visible, .adv-toggle:focus-visible, .sec-title:focus-visible
 .pf-view-style-button:focus-visible, .pf-view-style-tile:focus-visible {
   outline: none; box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent);
 }
+/* The Parts section (parts-list.js): under the style grid, behind a rule. */
+.pf-popover-rule { border: 0; border-top: 1px solid var(--pf-border); margin: 0 -12px; }
+.pf-parts { display: flex; flex-direction: column; gap: 6px; }
+.pf-parts-head { display: flex; align-items: baseline; justify-content: space-between; }
+.pf-parts-showall { font: inherit; font-weight: 500; color: var(--pf-accent); background: none; border: 0; padding: 0; cursor: pointer; }
+.pf-parts-showall[hidden] { display: none; }
+.pf-parts-list { display: flex; flex-direction: column; gap: 2px; }
+.pf-parts-row { display: grid; grid-template-columns: 28px minmax(0, 1fr); align-items: center; gap: 4px; padding: 0; border-radius: var(--pf-radius-control); min-width: 0; }
+.pf-parts-open { display: grid; grid-template-columns: 22px minmax(0, 1fr) auto; align-items: center; gap: 8px; min-width: 0; padding: 3px 6px 3px 0; border: 0; border-radius: var(--pf-radius-control); background: none; font: inherit; text-align: left; cursor: pointer; }
+.pf-parts-open:hover { background: var(--pf-surface-2); }
+.pf-parts-eye { width: 28px; height: 28px; border: 0; background: none; color: var(--pf-muted-2); border-radius: 6px; display: grid; place-items: center; cursor: pointer; }
+.pf-parts-eye:hover { background: var(--pf-accent-soft); color: var(--pf-accent); }
+.pf-parts-row.hidden .pf-parts-eye { color: var(--pf-hint); }
+.pf-parts-row.faded .pf-parts-eye { opacity: .55; }
+.pf-parts-row.hidden .pf-parts-name { color: var(--pf-hint); }
+.pf-parts-row.hidden .pf-parts-swatch { opacity: .35; }
+.pf-parts-swatch { width: 22px; height: 22px; border-radius: 50%; background: var(--pf-swatch, var(--pf-surface-2)); box-shadow: inset 0 0 0 1px rgb(0 0 0 / .18); }
+.pf-parts-open:hover .pf-parts-swatch { box-shadow: inset 0 0 0 1px rgb(0 0 0 / .18), 0 0 0 2px var(--pf-surface), 0 0 0 4px var(--pf-accent); }
+.pf-parts-name { font-size: 13px; color: var(--pf-text); min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.pf-parts-mat { font-size: 11.5px; color: var(--pf-muted); white-space: nowrap; }
+.pf-parts-eye:focus-visible, .pf-parts-open:focus-visible, .pf-parts-showall:focus-visible { outline: none; box-shadow: 0 0 0 3px color-mix(in oklab, var(--pf-accent) 35%, transparent); }
+/* The appearance card (appearance-card.js): the popover's second page. The
+   popover shows one page at a time by hiding the other's nodes; the grid and
+   the Parts section set display, which beats the UA's [hidden] rule, so the
+   page switch needs this guard (the #viewbar button[hidden] trap). */
+.pf-view-style-popover > [hidden] { display: none; }
+.pf-card { display: flex; flex-direction: column; gap: 10px; }
+.pf-card[hidden] { display: none; }
+.pf-card-head { display: flex; align-items: center; gap: 4px; }
+.pf-card-title { flex: 1; min-width: 0; font-weight: 600; font-size: 13px; color: var(--pf-text); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.pf-card-back, .pf-card-eye, .pf-card-close { width: 28px; height: 28px; border: 0; background: none; color: var(--pf-muted-2); border-radius: 6px; display: grid; place-items: center; cursor: pointer; }
+.pf-card-back:hover, .pf-card-eye:hover, .pf-card-close:hover { background: var(--pf-surface-2); color: var(--pf-text); }
+.pf-card-eye[aria-pressed="true"] { color: var(--pf-hint); }
+.pf-card-row { display: grid; grid-template-columns: 1fr auto; gap: 2px 8px; align-items: baseline; }
+.pf-card-row input[type="range"] { grid-column: 1 / -1; width: 100%; margin: 0; accent-color: var(--pf-accent); }
+.pf-card-lab-row { display: flex; justify-content: space-between; align-items: baseline; }
+.pf-card-lab { font-size: 12px; color: var(--pf-muted); }
+.pf-card-val { font-size: 12px; color: var(--pf-text-2); font-variant-numeric: tabular-nums; }
+.pf-card-tiles { display: grid; grid-template-columns: repeat(6, minmax(0, 1fr)); gap: 6px; }
+.pf-card-tile { display: grid; justify-items: center; gap: 3px; border: 0; background: none; padding: 3px 0; border-radius: 8px; cursor: pointer; font: inherit; color: var(--pf-muted); }
+.pf-card-tile:hover { background: var(--pf-surface-2); }
+.pf-card-tile[aria-pressed="true"] { background: var(--pf-accent-soft); color: var(--pf-accent); }
+.pf-card-ball { position: relative; width: 30px; height: 30px; border-radius: 50%; overflow: hidden; background: radial-gradient(circle at 35% 30%, color-mix(in oklab, var(--pf-swatch) 72%, white) 0, var(--pf-swatch) 48%, color-mix(in oklab, var(--pf-swatch) 68%, black) 100%); box-shadow: inset 0 -1px 2px rgb(0 0 0 / .25); }
+.pf-card-ball img { position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover; }
+.pf-card-ball img[hidden] { display: none; }
+.pf-card-tile-label { font-size: 9.5px; line-height: 1.1; max-width: 100%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.pf-card-unknown { margin: 0; font-size: 11px; color: var(--pf-err); font-family: var(--pf-mono); }
+.pf-card-unknown[hidden] { display: none; }
+.pf-card-colors { display: grid; grid-template-columns: repeat(10, minmax(0, 1fr)); gap: 6px; }
+.pf-card-colors.disabled { opacity: .35; pointer-events: none; }
+.pf-card-color { width: 100%; aspect-ratio: 1; border-radius: 50%; border: 0; padding: 0; cursor: pointer; background: var(--pf-swatch); box-shadow: inset 0 0 0 1px rgb(0 0 0 / .18); }
+.pf-card-color.on, .pf-card-color:hover { box-shadow: inset 0 0 0 1px rgb(0 0 0 / .18), 0 0 0 2px var(--pf-surface), 0 0 0 4px var(--pf-accent); }
+.pf-card-native { width: 100%; min-width: 0; aspect-ratio: 1; border: 1px solid var(--pf-border); border-radius: 50%; padding: 0; background: none; cursor: pointer; }
+.pf-card-hex { width: 100%; font: 12px var(--pf-mono); padding: 5px 8px; border: 1px solid var(--pf-border); border-radius: var(--pf-radius-control); background: var(--pf-input-bg); color: var(--pf-text); }
+.pf-card-hex:disabled { opacity: .5; }
+.pf-card-tint-note { margin: 0; font-size: 12px; color: var(--pf-muted); }
+.pf-card-tint-note[hidden] { display: none; }
+.pf-card-finish-group summary { cursor: pointer; font-size: 12px; color: var(--pf-muted-2); list-style: none; display: flex; align-items: center; gap: 6px; }
+.pf-card-finish-group summary::before { content: ""; width: 6px; height: 6px; border-right: 1.5px solid currentColor; border-bottom: 1.5px solid currentColor; transform: rotate(-45deg); }
+.pf-card-finish-group[open] summary::before { transform: rotate(45deg); }
+.pf-card-finish-group .pf-card-row { margin-top: 8px; }
+.pf-card-foot { display: flex; align-items: center; justify-content: space-between; gap: 8px; font-size: 11.5px; color: var(--pf-muted); border-top: 1px solid var(--pf-border); padding-top: 10px; }
+.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); }
 
 /* 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

package/src/framework/appearance-card.js

@@ -0,0 +1,331 @@
+// src/framework/appearance-card.js
+// The appearance card: the popover's second page, for one sub-part. Header
+// (Back, label, eye, close), See-through, the material tiles, the colour row,
+// the finish sliders, and a footer that says where a change goes. Every write
+// is one parts.setDisplay(name, patch); the card re-renders from parts.getState
+// on the change event, so what it shows is always the viewer's answer.
+import { PRESETS } from "./materials/presets.js";
+import { OVERRIDE_RANGES } from "./materials/resolve.js";
+import { MIN_USER_OPACITY } from "./materials/overrides.js";
+import { hexColor } from "./parts-list.js";
+
+const COLORS = ["#b3261e", "#e8711a", "#e3b31c", "#2e8b57", "#1f5bd6", "#6f42c1", "#f2f2f0", "#8c8c90", "#1f1f22"];
+const FINISH = [
+  ["roughness", "Roughness"], ["metalness", "Metalness"], ["clearcoat", "Clearcoat"],
+  ["clearcoatRoughness", "Clearcoat roughness"], ["anisotropy", "Anisotropy"], ["textureScale", "Texture scale"],
+];
+const FOOT = {
+  "saved": { note: "Material and colour are saved to this forge. See-through and hiding are only on this screen.", reset: "Reset to authored" },
+  "screen-only": { note: "", reset: "Reset" },
+  "blocked": { note: "This part's look is set by code. Ask the assistant to change it.", reset: "Reset" },
+};
+const ICONS = {
+  back: `<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="m15 18-6-6 6-6"/></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>`,
+  eye: `<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="M2.062 12.348a1 1 0 0 1 0-.696 10.75 10.75 0 0 1 19.876 0 1 1 0 0 1 0 .696 10.75 10.75 0 0 1-19.876 0"/><circle cx="12" cy="12" r="3"/></svg>`,
+  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>`,
+};
+// Texture scale spans 0.01–1000 mm, five decades: a linear slider over that puts
+// ~4 mm under each pixel and cannot land on the print presets' 0.2 mm. The
+// slider moves a POSITION in [0, 1] instead, mapped logarithmically onto
+// OVERRIDE_RANGES.textureScale; values are clamped to the range both ways.
+const [TS_LO, TS_HI] = OVERRIDE_RANGES.textureScale;
+const clampTs = (v) => Math.min(TS_HI, Math.max(TS_LO, v));
+export function textureScaleToPos(value) {
+  const v = Number.isFinite(value) ? clampTs(value) : TS_LO;
+  return Math.log(v / TS_LO) / Math.log(TS_HI / TS_LO);
+}
+export function posToTextureScale(pos) {
+  const p = Number.isFinite(pos) ? Math.min(1, Math.max(0, pos)) : 0;
+  return clampTs(TS_LO * (TS_HI / TS_LO) ** p);
+}
+// Sensible precision for a millimetre scale: 0.2 mm, 4.8 mm, 48 mm, 250 mm.
+function formatTextureScale(v) {
+  const digits = v < 1 ? 2 : v < 10 ? 1 : 0;
+  return `${Number(v.toFixed(digits))} mm`;
+}
+// The tiles' repaint is a pass over ~25 spheres, one per frame; a dragged colour
+// well re-renders the card every frame, so repaints are held to one per this
+// many milliseconds (leading edge, plus one trailing pass for the last state).
+const REPAINT_MS = 150;
+
+const parseHex = (s) => (/^#?[0-9a-f]{6}$/i.test(String(s).trim()) ? parseInt(String(s).trim().replace("#", ""), 16) : null);
+const known = (m) => typeof m === "string" && Object.hasOwn(PRESETS, m);
+
+// Leading-edge, once-per-frame write. The viewer rebuilds the sub-part's
+// material on every appearance write, so a dragged slider or colour well must
+// not write on every input event: the first event in a frame writes at once,
+// later ones in the same frame keep only their latest value, which is written
+// when the frame ends. requestAnimationFrame where there is one; a 16ms timer
+// otherwise (a test DOM, a worker-less host).
+const hasRaf = () => typeof requestAnimationFrame === "function";
+const nextFrame = () => new Promise((res) => (hasRaf() ? requestAnimationFrame(() => res()) : setTimeout(res, 16)));
+function frameThrottle(fn) {
+  const raf = hasRaf() ? requestAnimationFrame : (cb) => setTimeout(cb, 16);
+  const caf = typeof cancelAnimationFrame === "function" && hasRaf() ? cancelAnimationFrame : clearTimeout;
+  let handle = null;
+  let pending = null; // [args] waiting for the frame's end, or null
+  const tick = () => {
+    handle = null;
+    if (!pending) return;
+    const args = pending; pending = null;
+    fn(...args);
+    handle = raf(tick); // this write opened a new frame of its own
+  };
+  const call = (...args) => {
+    if (handle === null) { fn(...args); handle = raf(tick); } else pending = args;
+  };
+  call.cancel = () => { if (handle !== null) caf(handle); handle = null; pending = null; };
+  return call;
+}
+
+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;
+}
+
+// `renderThumb(materialId, display) -> Promise<dataUrl|null>` (Task 7) paints a
+// sphere into a tile; absent, tiles stay flat discs in the preset colour.
+// `onBack(name)` gets the name the card was showing, so the host can put focus
+// back on that row; `onGone(name)` fires when a re-render finds the part gone
+// (dropped by a rebuild), so the host can leave the card for the list.
+export function attachAppearanceCard(parts, { onBack, onClose, onGone, getSaveState, renderThumb = null } = {}) {
+  const root = el("div", "pf-card");
+  let name = null;
+  let row = null;
+
+  // --- static skeleton (rebuilt values only on render) ---
+  const head = el("div", "pf-card-head");
+  const back = el("button", "pf-card-back", { type: "button", "aria-label": "Back to parts" }); back.innerHTML = ICONS.back;
+  const title = el("span", "pf-card-title");
+  const eye = el("button", "pf-card-eye", { type: "button" });
+  const close = el("button", "pf-card-close", { type: "button", "aria-label": "Close" }); close.innerHTML = ICONS.close;
+  head.append(back, title, eye, close);
+
+  const seeRow = el("label", "pf-card-row");
+  const seeLab = el("span", "pf-card-lab"); seeLab.textContent = "See-through";
+  const seeVal = el("span", "pf-card-val");
+  const see = el("input", "pf-card-seethrough", { type: "range", min: String(Math.round(MIN_USER_OPACITY * 100)), max: "100", step: "1", "aria-label": "See-through" });
+  seeRow.append(seeLab, seeVal, see);
+
+  const matHead = el("div", "pf-card-lab-row");
+  const matLab = el("span", "pf-card-lab"); matLab.textContent = "Material";
+  const matVal = el("span", "pf-card-val");
+  matHead.append(matLab, matVal);
+  const tiles = el("div", "pf-card-tiles", { role: "group", "aria-label": "Material" });
+  const tileFor = (id, label, color) => {
+    const t = el("button", "pf-card-tile", { type: "button", "data-material": id, "aria-pressed": "false", title: label });
+    const ball = el("span", "pf-card-ball"); ball.style.setProperty("--pf-swatch", hexColor(color));
+    const img = el("img", "", { alt: "" }); img.hidden = true; ball.append(img);
+    const lab = el("span", "pf-card-tile-label"); lab.textContent = label;
+    t.append(ball, lab);
+    return t;
+  };
+  // One tile per preset. There is no "no material" tile: in the realistic
+  // view a part with no material looks like plain matte in its colour, which
+  // nothing on screen can tell from a neighbouring preset, so the tile read as
+  // dead. A part with no (or an unknown) material presses nothing; Reset is
+  // the way back to the authored look.
+  tiles.append(...Object.values(PRESETS).map((p) => tileFor(p.id, p.label, p.color)));
+  const unknown = el("p", "pf-card-unknown"); unknown.hidden = true;
+
+  const colHead = el("div", "pf-card-lab-row");
+  const colLab = el("span", "pf-card-lab"); colLab.textContent = "Colour";
+  const colVal = el("span", "pf-card-val");
+  colHead.append(colLab, colVal);
+  const colors = el("div", "pf-card-colors");
+  for (const c of COLORS) {
+    const b = el("button", "pf-card-color", { type: "button", "data-color": c, title: c, "aria-label": c });
+    b.style.setProperty("--pf-swatch", c);
+    colors.append(b);
+  }
+  const native = el("input", "pf-card-native", { type: "color", "aria-label": "Custom colour" });
+  colors.append(native);
+  const hexRow = el("div", "pf-card-hexrow");
+  const hex = el("input", "pf-card-hex", { type: "text", "aria-label": "Hex colour", spellcheck: "false", maxlength: "7" });
+  hexRow.append(hex);
+  const tintNote = el("p", "pf-card-tint-note"); tintNote.hidden = true;
+
+  const finish = el("details", "pf-card-finish-group");
+  const summary = el("summary"); summary.textContent = "Finish";
+  finish.append(summary);
+  const finishInputs = new Map();
+  // Each throttle is bound to the part it was started for, so a write still
+  // pending when the card switches part lands on the part it was meant for.
+  const writeFinish = frameThrottle((who, patch) => parts.setDisplay(who, patch));
+  for (const [key, label] of FINISH) {
+    const [lo, hi] = OVERRIDE_RANGES[key];
+    const r = el("label", "pf-card-row");
+    const lab = el("span", "pf-card-lab"); lab.textContent = label;
+    const val = el("span", "pf-card-val");
+    // Texture scale's range input holds a log POSITION (textureScaleToPos), not mm.
+    const logScale = key === "textureScale";
+    const input = el("input", "pf-card-finish", logScale
+      ? { type: "range", "data-key": key, min: "0", max: "1", step: "0.001", "aria-label": label }
+      : { type: "range", "data-key": key, min: String(lo), max: String(hi), step: "0.01", "aria-label": label });
+    r.append(lab, val, input);
+    finish.append(r);
+    finishInputs.set(key, { input, val });
+    input.addEventListener("input", () => {
+      const raw = Number(input.value);
+      if (!name || !Number.isFinite(raw)) return;
+      const v = logScale ? posToTextureScale(raw) : raw;
+      writeFinish(name, { [key]: Math.min(hi, Math.max(lo, v)) });
+    });
+  }
+
+  const foot = el("div", "pf-card-foot");
+  const note = el("span", "pf-card-foot-note");
+  const reset = el("button", "pf-card-reset", { type: "button" });
+  foot.append(note, reset);
+
+  root.append(head, seeRow, matHead, tiles, unknown, colHead, colors, hexRow, tintNote, finish, foot);
+
+  // --- wiring ---
+  back.addEventListener("click", () => onBack?.(name));
+  close.addEventListener("click", () => onClose?.());
+  eye.addEventListener("click", () => { if (name && row) parts.setDisplay(name, { hidden: !row.hidden }); });
+  // See-through rebuilds the fade clone on every write, like the finish sliders:
+  // once per frame, the first event at once.
+  const writeSee = frameThrottle((who, patch) => parts.setDisplay(who, patch));
+  see.addEventListener("input", () => {
+    if (!name) return;
+    const v = Number(see.value) / 100;
+    writeSee(name, { opacity: v >= 1 ? null : v });
+  });
+  tiles.addEventListener("click", (e) => {
+    const t = e.target.closest(".pf-card-tile");
+    if (!t || !name) return;
+    const id = t.dataset.material;
+    // An untintable preset draws its own colour, and the card disables the
+    // colour row under it — so a colour the USER set would be stranded there
+    // (drawn as red brass, with nothing but Reset to clear it). Picking one
+    // clears the override colour. An authored colour is source and persists.
+    const ownColor = known(id) && !PRESETS[id].tintable && typeof parts.getState(name)?.override?.color === "number";
+    parts.setDisplay(name, ownColor ? { material: id, color: null } : { material: id });
+  });
+  colors.addEventListener("click", (e) => {
+    const b = e.target.closest(".pf-card-color");
+    if (!b || !name) return;
+    parts.setDisplay(name, { color: parseHex(b.dataset.color) });
+  });
+  const writeNative = frameThrottle((who, patch) => parts.setDisplay(who, patch));
+  native.addEventListener("input", () => { const c = parseHex(native.value); if (name && c !== null) writeNative(name, { color: c }); });
+  hex.addEventListener("change", () => { const c = parseHex(hex.value); if (name && c !== null) parts.setDisplay(name, { color: c }); else render(); });
+  reset.addEventListener("click", () => { if (name) parts.clear({ appearance: true, name }); });
+
+  function render() {
+    if (!name) return;
+    row = parts.list().find((r) => r.name === name) ?? null;
+    const state = parts.getState(name);
+    if (!row || !state) {
+      // The part went away under the card (a rebuild dropped it): there is
+      // nothing left to show, so hand the page back rather than leave a card
+      // for a part that no longer exists.
+      const gone = name;
+      name = null; row = null; thumbToken++; cancelRepaint();
+      onGone?.(gone);
+      return;
+    }
+    title.textContent = row.label;
+    eye.innerHTML = row.hidden ? ICONS.eyeOff : ICONS.eye;
+    eye.setAttribute("aria-pressed", String(row.hidden));
+    eye.setAttribute("aria-label", `${row.hidden ? "Show" : "Hide"} ${row.label}`);
+    eye.title = eye.getAttribute("aria-label");
+    const pct = Math.round(row.opacity * 100);
+    see.value = String(pct); seeVal.textContent = `${pct}%`;
+    const m = state.effective.material;
+    for (const t of tiles.children) t.setAttribute("aria-pressed", String(known(m) && t.dataset.material === m));
+    matVal.textContent = row.materialLabel ?? "None";
+    unknown.hidden = !(m != null && !known(m));
+    unknown.textContent = unknown.hidden ? "" : String(m);
+    const color = row.color;
+    // An explicit colour under an untintable preset still exists (an override
+    // cannot clear an authored colour, only replace it), so it is shown by
+    // value rather than as "from the material" — the row stays disabled.
+    const ownColor = typeof state.effective.color === "number";
+    colVal.textContent = row.tintable || ownColor ? hexColor(color) : "from the material";
+    colors.classList.toggle("disabled", !row.tintable);
+    // Disabled for real, not only dimmed: pointer-events alone left the
+    // swatches and the colour well reachable by keyboard and screen reader.
+    for (const b of colors.querySelectorAll(".pf-card-color")) b.disabled = !row.tintable;
+    native.disabled = !row.tintable;
+    hex.disabled = !row.tintable;
+    for (const b of colors.querySelectorAll(".pf-card-color")) b.classList.toggle("on", parseHex(b.dataset.color) === color);
+    native.value = hexColor(color);
+    if (document.activeElement !== hex) hex.value = hexColor(color);
+    tintNote.hidden = row.tintable;
+    tintNote.textContent = row.tintable ? "" : `${row.materialLabel} has its own colour. Pick a tintable preset to colour it.`;
+    for (const [key, { input, val }] of finishInputs) {
+      const v = state.effective[key];
+      const shown = typeof v === "number" ? v : (known(m) ? (PRESETS[m][key] ?? 0) : 0);
+      if (key === "textureScale") {
+        const mm = shown > 0 ? clampTs(shown) : null;
+        input.value = String(textureScaleToPos(mm ?? TS_LO));
+        val.textContent = mm === null ? "—" : formatTextureScale(mm);
+      } else {
+        input.value = String(shown); val.textContent = shown.toFixed(2);
+      }
+    }
+    const f = FOOT[getSaveState?.() ?? "screen-only"] ?? FOOT["screen-only"];
+    note.textContent = f.note; note.hidden = !f.note; reset.textContent = f.reset;
+    if (renderThumb) requestPaint(state.effective);
+  }
+
+  // Repaints, held to one per REPAINT_MS: the first at once, then at most one
+  // trailing pass carrying the latest state when the window closes.
+  let repaintTimer = null;
+  let repaintPending = null;
+  function requestPaint(effective) {
+    if (repaintTimer !== null) { repaintPending = effective; return; }
+    paintThumbs(effective);
+    const windowEnd = () => {
+      repaintTimer = null;
+      if (!repaintPending) return;
+      const next = repaintPending; repaintPending = null;
+      paintThumbs(next);
+      repaintTimer = setTimeout(windowEnd, REPAINT_MS);
+    };
+    repaintTimer = setTimeout(windowEnd, REPAINT_MS);
+  }
+  function cancelRepaint() {
+    if (repaintTimer !== null) clearTimeout(repaintTimer);
+    repaintTimer = null; repaintPending = null;
+  }
+
+  // Thumbnails: one per tile, lazily, in order, cached by the renderer (Task 7),
+  // with a frame between tiles so a pass of cold renders never blocks a task
+  // for all ~25 spheres at once.
+  let thumbToken = 0;
+  async function paintThumbs(effective) {
+    const token = ++thumbToken;
+    let first = true;
+    for (const t of tiles.children) {
+      if (token !== thumbToken || !root.isConnected) return;
+      const id = t.dataset.material;
+      if (!first) { await nextFrame(); if (token !== thumbToken || !root.isConnected) return; }
+      first = false;
+      let url = null;
+      try { url = await renderThumb(id, { ...effective, material: id }); } catch { url = null; }
+      if (token !== thumbToken) return;
+      const img = t.querySelector("img");
+      if (url) { img.src = url; img.hidden = false; } else img.hidden = true;
+    }
+  }
+
+  const off = parts.onChange(() => render());
+  return {
+    element: root,
+    show(next) {
+      if (!parts.list().some((r) => r.name === next)) return false;
+      name = next;
+      render();
+      return true;
+    },
+    hide() { name = null; thumbToken++; cancelRepaint(); },
+    render,
+    detach() { writeFinish.cancel(); writeNative.cancel(); writeSee.cancel(); cancelRepaint(); thumbToken++; try { off(); } catch { /* gone */ } root.remove(); },
+  };
+}

package/src/framework/materials/overrides.js

@@ -0,0 +1,120 @@
+// src/framework/materials/overrides.js
+// The viewer-side override of a sub-part's appearance, and the viewing state
+// beside it. Pure: no three, no DOM (lint purity scans this folder).
+//
+// Two kinds of key, deliberately separate (spec A.1):
+//   - APPEARANCE keys merge over the authored `display` into effective(), which
+//     every material read uses — CAD, realistic, the throwaway thumbnail scene.
+//     A host may persist these into source.
+//   - VIEWING keys (`hidden`, `opacity`) are how the user is LOOKING. They never
+//     reach effective(), exports, lint or declaresMaterials, and no host saves
+//     them. `opacity` MULTIPLIES an authored display.opacity (the arithmetic
+//     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";
+
+export const APPEARANCE_OVERRIDE_KEYS = DISPLAY_KEYS.filter((k) => k !== "opacity");
+export const VIEWING_KEYS = ["hidden", "opacity"];
+export const MIN_USER_OPACITY = 0.05;
+
+const isObject = (x) => x !== null && typeof x === "object" && !Array.isArray(x);
+const isColor = (v) => Number.isInteger(v) && v >= 0 && v <= 0xffffff;
+const finite = (v) => typeof v === "number" && Number.isFinite(v);
+
+// Only known keys survive; `null` is the "clear this key" value and survives
+// as-is. Bad values are DROPPED (not clamped) where clamping would invent a
+// choice: a non-string material, a colour out of range. Numeric overrides clamp
+// to OVERRIDE_RANGES exactly as resolve.js clamps authored ones. `opacity`
+// floors at MIN_USER_OPACITY and reads >= 1 as a clear; `hidden` must be a real
+// boolean (a host's "false" string would otherwise read as truthy and hide the
+// part), anything else is dropped.
+export function sanitizeDisplayPatch(patch) {
+  if (!isObject(patch)) return {};
+  const out = {};
+  for (const [key, v] of Object.entries(patch)) {
+    if (v === null) {
+      if (APPEARANCE_OVERRIDE_KEYS.includes(key) || VIEWING_KEYS.includes(key)) out[key] = null;
+      continue;
+    }
+    if (key === "material") { if (typeof v === "string" && v.length > 0) out.material = v; continue; }
+    if (key === "color") { if (isColor(v)) out.color = v; continue; }
+    if (key === "hidden") { if (typeof v === "boolean") out.hidden = v; continue; }
+    if (key === "opacity") {
+      if (!finite(v)) continue;
+      out.opacity = v >= 1 ? null : Math.max(MIN_USER_OPACITY, v);
+      continue;
+    }
+    if (key in OVERRIDE_RANGES) {
+      if (!finite(v)) continue;
+      const [lo, hi] = OVERRIDE_RANGES[key];
+      out[key] = Math.min(hi, Math.max(lo, v));
+    }
+  }
+  return out;
+}
+
+// Merge a SANITIZED patch over the current override. `hidden: false` and
+// `opacity: null` (or >= 1) are clears like any other null. Returns null when nothing is
+// left, so a Map entry can be deleted rather than kept empty.
+export function mergeOverride(current, patch) {
+  const next = { ...(isObject(current) ? current : {}) };
+  for (const [key, v] of Object.entries(patch ?? {})) {
+    if (v === null || (key === "hidden" && v === false) || (key === "opacity" && v >= 1)) delete next[key];
+    else next[key] = v;
+  }
+  return Object.keys(next).length ? next : null;
+}
+
+// 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];
+  return out;
+}
+
+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]);
+}
+
+// A carried map, made safe for THIS part (spec A.4): names the part no longer
+// declares go; appearance keys that now equal the authored value go (an owner's
+// saved change self-cleans this way); every kept entry is re-sanitized, since
+// the token came from a host; empties go.
+export function pruneOverrides(map, part) {
+  const out = {};
+  if (!isObject(map)) return out;
+  for (const [name, raw] of Object.entries(map)) {
+    // Own names only: `parts` is a plain object, so "toString" or "constructor"
+    // would otherwise read as declared sub-parts and be replayed into the viewer.
+    const parts = part?.parts;
+    if (!isObject(parts) || !Object.hasOwn(parts, name)) continue;
+    const sp = parts[name];
+    if (!sp) continue;
+    const clean = mergeOverride(null, sanitizeDisplayPatch(raw));
+    if (!clean) continue;
+    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];
+    if (Object.keys(clean).length) out[name] = clean;
+  }
+  return out;
+}
+
+// The one visibility decision viewer.js's applySubOpacity makes, as a pure
+// function of its inputs. `anim` is the animation driver's opacity (undefined =
+// none), `user` the viewing override's (undefined = none). `fade` is null when
+// the mesh should sit on its base material, else the fade clone's opacity.
+export function subPartVisibility({ shown, anim, user, hidden, renderMode, staticOpacity = 1 }) {
+  const off = { meshVisible: false, linesVisible: false, fade: null };
+  if (!shown || hidden) return off;
+  const a = anim === undefined ? 1 : anim;
+  const u = user === undefined ? 1 : user;
+  const v = a * u;
+  if (v <= 0) return off;
+  const linesVisible = renderMode === "cad";
+  if (v >= 1) return { meshVisible: true, linesVisible, fade: null };
+  return { meshVisible: true, linesVisible, fade: staticOpacity * v };
+}

package/src/framework/materials/thumb-cache.js

@@ -0,0 +1,33 @@
+// Keys and bounds for the appearance card's sphere thumbnails. A tile depicts
+// the PRESET, tinted: finish overrides (and see-through) are neither in the key
+// nor in the render — re-rendering 25 spheres on every slider tick would make
+// the card unusable, and a render that read them would cache one part's finish
+// under a key every other part shares. thumbDisplay is what the render builds
+// from, so it can depend on exactly what the key holds.
+//
+// An UNTINTABLE preset (brass, oak, ...) draws its own colour whatever the
+// part's colour is, so its colour is dropped from both the render and the key:
+// every part shares one sphere for it, and a colour pick re-renders only the
+// tintable tiles. No material (and an unknown id) counts as tintable.
+import { PRESETS } from "./presets.js";
+
+const CAP = 120;
+const tintable = (material) =>
+  typeof material !== "string" || !Object.hasOwn(PRESETS, material) || PRESETS[material].tintable === true;
+export function thumbDisplay(display) {
+  const out = { material: display?.material };
+  if (display?.color !== undefined && tintable(display?.material)) out.color = display.color;
+  return out;
+}
+export function createMaterialThumbCache() {
+  const map = new Map();
+  return {
+    key: (display, env, theme, mode) => {
+      const look = thumbDisplay(display);
+      return `${look.material ?? ""}|${look.color ?? ""}|${env}|${theme}|${mode}`;
+    },
+    get(k) { const v = map.get(k); if (v !== undefined) { map.delete(k); map.set(k, v); } return v; },
+    set(k, url) { map.delete(k); map.set(k, url); if (map.size > CAP) map.delete(map.keys().next().value); },
+    clear() { map.clear(); },
+  };
+}