partforge 0.147.0 → 0.149.0

package/src/framework/mount.js

@@ -14,6 +14,8 @@ import { ENVIRONMENTS } from "./materials/environments.js";
 import { declaresMaterials, resolveMaterial } from "./materials/resolve.js";
 import { printFrameMatrix } from "./materials/print-frame.js";
 import { burnsFor, realisticDisplay, sheetFrameFor } from "./materials/sheet-look.js";
+import { pruneOverrides } from "./materials/overrides.js";
+import { subPartRows } from "./sub-part-list.js";
 import { buildControls } from "./controls.js";
 import { recordedRelevantKeys, subPartParamKeys } from "./param-deps.js";
 import { createMeshCache } from "./mesh-cache.js";
@@ -70,7 +72,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 }) {
+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 }) {
   return {
     ready, dispose, setParams,
     // Whether the `preview` GLB handed to mount() is on screen (see mount's
@@ -132,7 +134,29 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
       // from meta.environment (or the default) would outrank the part's own
       // meta.environment on the next mount, masking an edit to it.
       ...(viewer.isEnvironmentChosen?.() ? { environment: viewer.getEnvironment() } : {}),
+      // 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 } : {}; })(),
     }),
+    // --- 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
+    // the user is looking and never reach a material read, an export or a
+    // host's save. All of it rides getViewerState().display above.
+    setSubPartDisplay: (name, patch) => viewer.setSubPartDisplay?.(name, patch) ?? null,
+    getSubPartDisplay: (name) => viewer.getSubPartDisplayState?.(name) ?? null,
+    clearSubPartDisplay: (opts) => viewer.clearSubPartDisplay?.(opts),
+    onSubPartDisplayChange: (cb) => viewer.onDisplayChange?.(cb) ?? (() => {}),
+    // Every sub-part as a row (sub-part-list.js), for a host's own list; the
+    // active view unless `view` names another.
+    listSubParts: listSubParts ?? (() => []),
+    // Open the popover on the appearance card for `name`; false when there is
+    // no popover (a host with neither #viewbar nor a view cube stack).
+    openAppearance: openAppearance ?? (() => false),
+    // "saved" | "screen-only" | "blocked": the card's footer copy. A host that
+    // persists overrides into source says "saved"; one that cannot, for this
+    // sub-part, says "blocked"; the default is "screen-only".
+    setDisplaySaveState: setDisplaySaveState ?? (() => {}),
     // Every custom control's transient state (selection, a scroll position),
     // keyed by param, as plain JSON — the panel's twin of getViewerState. Hand
     // it back as mount()'s `panelState` and a remount comes up with the same
@@ -400,8 +424,9 @@ function createCleanupStack() {
 //                                         // payload is small, only that it is bounded.
 // viewerState: ViewerState               // a previous mount's runtime.getViewerState(), handed back to
 //                                         // resume the camera, projection, cutaway, render mode,
-//                                         // environment and per-style feature-line preferences
-//                                         // where that mount
+//                                         // environment, per-style feature-line preferences and
+//                                         // per-sub-part display overrides (`display`, pruned for
+//                                         // this part) where that mount
 //                                         // left them. For a host that applies edits by REMOUNTING: the
 //                                         // part changed, the user's view of it should not. Omit on a
 //                                         // first mount — the viewer then restores its own persisted
@@ -604,6 +629,9 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
 
     // View tabs (generated from part.views) + live params. A tab switch shows the
     // cached assembly instantly if it's current, else auto-builds what's missing.
+    // The popover's Parts section (attachViewStyleControls' `parts` seam) follows
+    // the active view; declared here because tabsCtl's onChange reads it.
+    const viewChangeListeners = new Set();
     const tabsCtl = createViewTabs(els.tabs, part, {
       onChange: (name) => {
         // FIRST: the outgoing animation restores its param snapshot, so the
@@ -616,6 +644,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
         // (and clear the posed ones' matrices) before anything else reads them.
         fastPath.apply(viewSubParts(part, view(), params));
         updateRelevance(); loop.kick(); animCtl?.autoplayKick();
+        for (const cb of [...viewChangeListeners]) { try { cb(name); } catch { /* listener's problem */ } }
         onViewChange?.(name);
       },
     });
@@ -740,6 +769,14 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
     // right rig first time rather than the default and then this one.
     const initialEnv = viewerState?.environment ?? loadEnvironment();
     if (initialEnv) viewer.setEnvironment(initialEnv);
+    // Carried display overrides, pruned for THIS part (materials/overrides.js):
+    // a renamed sub-part's entry goes, and an appearance key that now equals the
+    // authored value goes — which is how an owner's saved change self-cleans
+    // after the remount that applied it. Restored before the first showView so
+    // the first frame already draws the override, hidden pieces included.
+    for (const [name, override] of Object.entries(pruneOverrides(viewerState?.display, part))) {
+      viewer.setSubPartDisplay(name, override);
+    }
     // Realistic mode by the same precedence, requested HERE rather than on the
     // first accepted build: every mount has a fresh renderer, so the
     // environment loads again, and starting now runs that alongside the build
@@ -764,6 +801,15 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
       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),
+      },
     }, { tooltip });
     cleanup.defer(() => viewStyle.detach());
     // setHidden takes one boolean, and there are two independent reasons to hide
@@ -1027,10 +1073,17 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
     //  - sheet frames for the burn pass (materials/sheet-look.js): a laser sheet in a wood,
     //    mapped back into its canonical frame — from data, no probe.
     // Each describes the delivered mesh (which a later pose-only repair only moves).
-    const layerLined = new Set(Object.keys(part.parts).filter((n) => {
-      try { return resolveMaterial(realisticDisplay(part.parts[n])).params.pattern === "layer-lines"; } catch { return false; }
-    }));
-    const burning = new Set(Object.keys(part.parts).filter((n) => burnsFor(part.parts[n])));
+    // Which sub-parts need frames is read off the EFFECTIVE display at the time
+    // the frames are computed, not fixed at mount: a live material change (the
+    // Parts section) can turn a plain piece into a layer-lined print, and it
+    // must get its print frame without a rebuild. So every delivery's
+    // dispatch record is kept (one small object per sub-part), and computeFrames
+    // decides per name.
+    const effectiveSubPart = (n) => ({ ...part.parts[n], display: viewer.effectiveDisplayOf?.(n) ?? part.parts[n].display });
+    const isLayerLined = (n) => {
+      try { return resolveMaterial(realisticDisplay(effectiveSubPart(n))).params.pattern === "layer-lines"; } catch { return false; }
+    };
+    const isBurning = (n) => burnsFor(effectiveSubPart(n));
     // LAZY: a delivery only records the view and params its job was DISPATCHED with
     // (`dispatched`, set where the loop sends) — not the live ones, which a delivery shown
     // during playback was never built at; the viewer pulls the frames (computeFrames)
@@ -1039,20 +1092,32 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
     // snapshot keeps a late computation describing the mesh actually delivered.
     const printFrames = {};
     const sheetFrames = {};
-    const undrawnFrames = new Map(); // sub-part -> { at: { view, params } its delivered mesh was built at, frame }
+    const deliveredAt = new Map(); // sub-part -> { at: { view, params }, frame } of its delivered mesh (kept, not consumed)
+    const undrawnFrames = new Set(); // sub-part names whose frames are stale
+    // The (print, burn) pair each name's frames were last computed for. A display
+    // change re-stales a name only when its pair flips — hide, show, opacity and a
+    // swap between two layer-lined (or two burning) materials leave the frames
+    // valid, so a see-through drag in realistic mode never re-probes a placed piece.
+    const frameNeeds = new Map();
+    const needsKey = (n) => `${isLayerLined(n) ? 1 : 0}${isBurning(n) ? 1 : 0}`;
     // `meshes` are the reply's deliveries: each one's `frame` ("canonical" | "posed"; an older
     // worker sends none, so posed) rides beside the view/params so the frames describe it.
     function recordFrames(meshes) {
-      const wanted = meshes.filter((m) => layerLined.has(m.name) || burning.has(m.name));
-      if (!wanted.length) return;
-      for (const m of wanted) {
-        undrawnFrames.set(m.name, { at: dispatched.get(m.name) ?? null, frame: m.frame ?? "posed" }); // at null: built at params nobody recorded
+      for (const m of meshes) {
+        deliveredAt.set(m.name, { at: dispatched.get(m.name) ?? null, frame: m.frame ?? "posed" }); // at null: built at params nobody recorded
+        undrawnFrames.add(m.name);
       }
       viewer.invalidateFrames?.();
     }
     function computeFrames() {
       const resolvedFor = new Map(); // one resolveParams per delivery, not per sub-part
-      for (const [n, { at, frame }] of undrawnFrames) {
+      for (const n of undrawnFrames) {
+        const rec = deliveredAt.get(n);
+        if (!rec) continue;
+        const { at, frame } = rec;
+        const needPrint = isLayerLined(n), needBurn = isBurning(n);
+        frameNeeds.set(n, `${needPrint ? 1 : 0}${needBurn ? 1 : 0}`);
+        if (!needPrint && !needBurn) { delete sheetFrames[n]; continue; }
         if (at && !resolvedFor.has(at)) {
           try { resolvedFor.set(at, resolveParams(part, at.params)); } catch { resolvedFor.set(at, null); } // diagnosed by the build
         }
@@ -1064,8 +1129,8 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
         if (!resolved) { delete sheetFrames[n]; continue; }
         // For a views-map sub-part the export pose is the build itself (plus a sheet pose), so a canonical
         // delivery's print frame is identity — no special case, the probe reads the compiled placement.
-        if (layerLined.has(n)) printFrames[n] = printFrameMatrix(part.parts[n], { view: at.view, ...resolved, frame });
-        if (burning.has(n)) {
+        if (needPrint) printFrames[n] = printFrameMatrix(part.parts[n], { view: at.view, ...resolved, frame });
+        if (needBurn) {
           const f = sheetFrameFor(part.parts[n], { ...resolved, frame });
           if (f) sheetFrames[n] = f; else delete sheetFrames[n];
         }
@@ -1073,6 +1138,20 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
       undrawnFrames.clear();
       return { print: { ...printFrames }, sheet: { ...sheetFrames } };
     }
+    // A display change re-stales a delivered sub-part's frames when it changes
+    // WHICH frames that piece needs (frameNeeds above); a `null` event (a clear)
+    // re-checks every delivered name. computeFrames stays lazy (viewer.js
+    // syncFrames), so a CAD-only session still computes nothing.
+    cleanup.defer(viewer.onDisplayChange?.((evt) => {
+      let stale = false;
+      for (const n of evt?.name ? [evt.name] : deliveredAt.keys()) {
+        if (!deliveredAt.has(n) || undrawnFrames.has(n)) continue; // nothing drawn yet, or already stale
+        if (frameNeeds.get(n) === needsKey(n)) continue;
+        undrawnFrames.add(n);
+        stale = true;
+      }
+      if (stale) viewer.invalidateFrames?.();
+    }) ?? (() => {}));
     viewer.setFrameSource?.(computeFrames);
 
     // Sub-parts whose latest fresh delivery had zero triangles (see the `meshes` case).
@@ -1576,6 +1655,10 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, pick
       setHostPane: paneTabs.setHostPane,
       setRailLayout: paneTabs.setRailLayout,
       getView: view,                         // () => tabsCtl.current()
+      // `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),
       setView: (name) => tabsCtl.select(name),
       captureView,
       getPanelState: () => panelRef?.getState() ?? {},

package/src/framework/parts-list.js

@@ -0,0 +1,116 @@
+// src/framework/parts-list.js
+// The View style popover's Parts section: the sub-parts in the active view,
+// one row each with an eye (hide / show) and a swatch + name (opens the appearance
+// card), plus Show all. DOM only; the row model is sub-part-list.js's and the
+// state is the viewer's — this module renders `parts.list()` and calls
+// `parts.setDisplay` / `parts.clear`, nothing more.
+const 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>`;
+const EYE_OFF = `<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>`;
+
+export const hexColor = (int) => `#${(int >>> 0).toString(16).padStart(6, "0").slice(-6)}`;
+
+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;
+}
+
+// `onSwatch(name)` opens the card. Returns { element, render, detach }.
+export function attachPartsList(parts, { onSwatch } = {}) {
+  const section = el("div", "pf-parts");
+  const head = el("div", "pf-parts-head");
+  const heading = el("p", "pf-view-style-heading pf-parts-heading");
+  heading.textContent = "Parts";
+  const showAll = el("button", "pf-parts-showall", { type: "button" });
+  showAll.textContent = "Show all";
+  showAll.hidden = true;
+  showAll.addEventListener("click", () => { parts.clear({ viewing: true }); render(); });
+  head.append(heading, showAll);
+  const list = el("div", "pf-parts-list", { role: "list" });
+  section.append(head, list);
+
+  // Every render rebuilds the rows, so the control that had focus (an eye
+  // just clicked from the keyboard) and the scroll position would be lost
+  // with the old nodes. Both are remembered here and put back afterwards: the
+  // focus by row name and control kind, the scroll on the list and on its
+  // scrolling container (the popover, which is what actually scrolls).
+  function focusedControl() {
+    const a = document.activeElement;
+    if (!a || !list.contains(a)) return null;
+    const row = a.closest(".pf-parts-row");
+    if (!row) return null;
+    return { name: row.dataset.name, kind: a.classList.contains("pf-parts-open") ? "open" : "eye" };
+  }
+  function restoreFocus(was) {
+    if (!was) return;
+    const row = [...list.children].find((r) => r.dataset.name === was.name);
+    row?.querySelector(was.kind === "open" ? ".pf-parts-open" : ".pf-parts-eye")?.focus({ preventScroll: true });
+  }
+
+  // One render path. Clicks render synchronously (a host whose `onChange`
+  // never fires still updates); a display change from anywhere schedules a
+  // render for the next microtask, and a synchronous render in between
+  // cancels it — so a click whose setDisplay also emits renders once.
+  let pending = false;
+  function schedule() {
+    if (pending) return;
+    pending = true;
+    queueMicrotask(() => { if (pending) render(); });
+  }
+
+  // What the list last drew, as one string over every field a row or the
+  // Show all button reads. A render whose rows read the same leaves the DOM
+  // alone: a playing animation re-shows the assembly every frame, and each
+  // one reaches here through the popover's assembly hook, so rebuilding the
+  // rows unconditionally replaced the node under the pointer sixty times a
+  // second — a press landed on a row that was gone before the release, and no
+  // click ever fired (seen on hinged-box.html).
+  let drawn = null;
+  const keyOf = (all) => JSON.stringify(all.map((r) => [r.name, r.label, r.inView, r.hidden, r.opacity, r.color, r.materialLabel]));
+
+  function render() {
+    pending = false;
+    const all = parts.list();
+    const key = keyOf(all);
+    if (key === drawn) return;
+    drawn = key;
+    const rows = all.filter((r) => r.inView);
+    const was = focusedControl();
+    const scroller = section.parentElement;
+    const listTop = list.scrollTop, outerTop = scroller?.scrollTop ?? 0;
+    list.replaceChildren(...rows.map((r) => {
+      const row = el("div", "pf-parts-row", { role: "listitem", "data-name": r.name });
+      if (r.hidden) row.classList.add("hidden");
+      else if (r.opacity < 1) row.classList.add("faded");
+      const eye = el("button", "pf-parts-eye", { type: "button", "aria-pressed": String(r.hidden), "aria-label": `${r.hidden ? "Show" : "Hide"} ${r.label}` });
+      eye.title = eye.getAttribute("aria-label");
+      eye.innerHTML = r.hidden ? EYE_OFF : EYE;
+      eye.addEventListener("click", () => { parts.setDisplay(r.name, { hidden: !r.hidden }); render(); });
+      // Swatch, name and material are ONE button: the whole row past the eye
+      // opens the card, not just the 22px disc.
+      const open = el("button", "pf-parts-open", { type: "button", "aria-label": `Change appearance of ${r.label}` });
+      open.title = open.getAttribute("aria-label");
+      const swatch = el("span", "pf-parts-swatch");
+      swatch.style.setProperty("--pf-swatch", hexColor(r.color));
+      const name = el("span", "pf-parts-name"); name.textContent = r.label;
+      const mat = el("span", "pf-parts-mat"); mat.textContent = r.materialLabel ?? "";
+      open.append(swatch, name, mat);
+      open.addEventListener("click", () => onSwatch?.(r.name));
+      row.append(eye, open);
+      return row;
+    }));
+    list.scrollTop = listTop;
+    if (scroller) scroller.scrollTop = outerTop;
+    restoreFocus(was);
+    // Show all hides itself once it has done its job; if it held focus, hand
+    // focus to the first row's eye rather than dropping it on the page.
+    const showAllHadFocus = document.activeElement === showAll;
+    showAll.hidden = !all.some((r) => r.hidden || r.opacity < 1);
+    if (showAllHadFocus && showAll.hidden) list.querySelector(".pf-parts-eye")?.focus({ preventScroll: true });
+  }
+
+  const offs = [parts.onChange(() => schedule()), parts.onViewChange?.(() => render()) ?? (() => {})];
+  render();
+  return { element: section, render, detach() { for (const off of offs) { try { off(); } catch { /* gone */ } } section.remove(); } };
+}

package/src/framework/sub-part-list.js

@@ -0,0 +1,44 @@
+// src/framework/sub-part-list.js
+// The row model behind the popover's Parts section and the runtime's
+// listSubParts(): one row per sub-part, in definition order, saying whether it
+// is in the view, how it is overridden, and what its swatch should look like.
+// Pure (no DOM, no three) so the popover, a host and the tests read one model.
+import { viewSubParts } from "./part-model.js";
+import { partLabel } from "./export-select.js";
+import { resolveMaterial, NO_MATERIAL_COLOR } from "./materials/resolve.js";
+import { PRESETS } from "./materials/presets.js";
+import { effectiveDisplay, APPEARANCE_OVERRIDE_KEYS } from "./materials/overrides.js";
+
+const known = (m) => typeof m === "string" && Object.hasOwn(PRESETS, m);
+const isColor = (v) => Number.isInteger(v) && v >= 0 && v <= 0xffffff;
+
+// The swatch colour: the explicit colour wins (it tints any preset, resolve.js),
+// else a known preset's own colour, else the drafting blue-grey.
+function swatchColor(effective) {
+  if (isColor(effective.color)) return effective.color;
+  if (known(effective.material)) return resolveMaterial(effective).params.color;
+  return NO_MATERIAL_COLOR;
+}
+
+export function subPartRows(part, { view, params, overrides = {} } = {}) {
+  const inViewNames = new Set(viewSubParts(part, view, params ?? part.defaults ?? {}));
+  return Object.keys(part.parts).map((name) => {
+    const sp = part.parts[name];
+    const override = overrides?.[name] ?? null;
+    const effective = effectiveDisplay(sp.display, override);
+    const m = effective.material;
+    const materialLabel = m == null ? null : known(m) ? PRESETS[m].label : "unknown";
+    return {
+      name,
+      label: partLabel(part, name),
+      inView: inViewNames.has(name),
+      hidden: override?.hidden === true,
+      opacity: typeof override?.opacity === "number" ? override.opacity : 1,
+      effective,
+      color: swatchColor(effective),
+      materialLabel,
+      tintable: m == null || !known(m) || PRESETS[m].tintable === true,
+      overridden: !!override && APPEARANCE_OVERRIDE_KEYS.some((k) => k in override),
+    };
+  });
+}

package/src/framework/view-style-controls.js

@@ -31,13 +31,19 @@
 // Orthographic segmented control). It went when the projection became
 // AUTOMATIC — orthographic on a view cube face view, perspective everywhere
 // else (Fusion 360's "Perspective with Ortho Faces"; viewer.js's
-// tweenCameraTo) — so the popover is the style grid alone.
+// tweenCameraTo). Since 2026-10-13 a host that passes a `parts` seam also
+// gets a Parts section under the grid (parts-list.js), and a swatch there opens
+// that sub-part's appearance card as the popover's second page
+// (appearance-card.js); without one the popover is the style grid alone,
+// exactly as before.
 //
 // The state shown is always the viewer's: a tile is pressed once the viewer
 // reports that style, and a runtime change made elsewhere shows up here.
 import { STYLES, styleFor, createThumbnailCache } from "./view-style-state.js";
 import { saveRenderMode, saveEnvironment } from "./view-state.js";
 import { attachButtonTooltips } from "./tooltip.js";
+import { attachPartsList } from "./parts-list.js";
+import { attachAppearanceCard } from "./appearance-card.js";
 
 // An eye (lucide "eye"): the button is about how the part is SEEN — a
 // palette read as a paint/colour picker, and a movie camera (its icon until
@@ -53,7 +59,7 @@ function el(tag, className, attrs = {}) {
   return e;
 }
 
-export function attachViewStyleControls(viewer, { stage, toolbar = null, anchor = null } = {}, { tooltip } = {}) {
+export function attachViewStyleControls(viewer, { stage, toolbar = null, anchor = null, parts = null } = {}, { tooltip } = {}) {
   const button = el("button", "pf-view-style-button", {
     type: "button", id: "view-style", "aria-label": LABEL,
     "aria-haspopup": "dialog", "aria-expanded": "false", "aria-controls": "pf-view-style-popover",
@@ -78,8 +84,8 @@ export function attachViewStyleControls(viewer, { stage, toolbar = null, anchor
   pop.hidden = true;
 
   const styleHead = el("p", "pf-view-style-heading");
-  styleHead.textContent = "Style";
-  const grid = el("div", "pf-view-style-grid", { role: "group", "aria-label": "Style" });
+  styleHead.textContent = "Environment";
+  const grid = el("div", "pf-view-style-grid", { role: "group", "aria-label": "Environment" });
   const tiles = new Map();
   for (const s of STYLES) {
     const t = el("button", "pf-view-style-tile", { type: "button", "aria-pressed": "false" });
@@ -97,6 +103,83 @@ export function attachViewStyleControls(viewer, { stage, toolbar = null, anchor
   }
 
   pop.append(styleHead, grid);
+
+  // The Parts section (parts-list.js) — only for a host that passes the seam.
+  // Separated from the style grid by a rule so the popover reads as two
+  // things: how the scene is drawn, then what is in it.
+  let partsList = null;
+  let divider2 = null;
+  if (parts) {
+    divider2 = el("hr", "pf-popover-rule");
+    partsList = attachPartsList(parts, { onSwatch: (name) => openCard(name) });
+    pop.append(divider2, partsList.element);
+  }
+
+  // The appearance card (appearance-card.js): the popover's second page, for
+  // one sub-part. The popover holds one page at a time — "list" (the style
+  // grid and the Parts section) or "card" — on `data-page`; placement, the
+  // close rules and the host-hidden observers are the same for both, and a
+  // close always returns to the list, so the next open starts there.
+  let saveState = "screen-only";
+  let card = null;
+  const listNodes = () => [styleHead, grid, divider2, partsList?.element].filter(Boolean);
+  // Pages exist only with the `parts` seam: without it the popover carries no
+  // data-page and its style nodes are never touched, so its DOM is exactly the
+  // pre-parts popover's.
+  function showPage(page) {
+    if (!parts) return;
+    pop.dataset.page = page;
+    for (const n of listNodes()) n.hidden = page !== "list";
+    if (card) card.element.hidden = page !== "card";
+    if (page === "list") card?.hide();
+    if (isOpen()) place();
+  }
+  // Built on the first openCard, not at attach: until a card is wanted the
+  // document holds none of its ~40 controls (a host or test querying the page's
+  // range inputs or buttons would otherwise find the hidden card's first).
+  function ensureCard() {
+    if (card || !parts) return card;
+    card = attachAppearanceCard(parts, {
+      onBack: (name) => backToList(name),
+      onClose: () => close(),
+      onGone: () => { if (pop.dataset.page === "card") backToList(null); },
+      getSaveState: () => saveState,
+      renderThumb: viewer.renderMaterialThumbnail ? (id, display) => viewer.renderMaterialThumbnail(display, { size: 96 }) : null,
+    });
+    card.element.hidden = true;
+    pop.append(card.element);
+    return card;
+  }
+  // Back to the list, with focus on the row the card was for (its swatch), else
+  // the first row's eye, else the first style tile. The control that had focus
+  // (Back) is about to be hidden, and focus dropping to <body> would also take
+  // Escape away: its listener is on the popover and the button, not document.
+  function backToList(name) {
+    const hadFocus = card?.element.contains(document.activeElement);
+    showPage("list");
+    if (!hadFocus) return;
+    const rowFor = name != null
+      ? [...pop.querySelectorAll(".pf-parts-row")].find((r) => r.dataset.name === name)
+      : null;
+    const target = rowFor?.querySelector(".pf-parts-open")
+      ?? pop.querySelector(".pf-parts-row .pf-parts-eye")
+      ?? pop.querySelector(".pf-view-style-tile");
+    target?.focus({ preventScroll: true });
+  }
+  if (parts) pop.dataset.page = "list";
+  // Open the popover (if it is closed) on the card for `name`. False when there
+  // is no card (no `parts` seam), the host is hidden, or `name` is not a sub-part.
+  function openCard(name) {
+    if (!parts) return false;
+    // A bad name must leave a closed popover closed.
+    if (!parts.list().some((r) => r.name === name)) return false;
+    if (!isOpen()) open();
+    if (!isOpen()) return false; // the host is hidden: nothing to show on
+    if (!ensureCard().show(name)) return false;
+    showPage("card");
+    card.element.querySelector(".pf-card-back")?.focus();
+    return true;
+  }
   stage.append(pop);
 
   const tooltipBinding = tooltip ? attachButtonTooltips(tooltip, [{ element: button }]) : null;
@@ -213,12 +296,14 @@ export function attachViewStyleControls(viewer, { stage, toolbar = null, anchor
     button.setAttribute("aria-expanded", "true");
     button.classList.add("on");
     render();
+    partsList?.render();
     document.addEventListener("pointerdown", onOutside, true);
     refreshThumbnails();
   }
   function close({ focus = true } = {}) {
     if (!isOpen()) return;
     pop.hidden = true;
+    showPage("list");
     button.setAttribute("aria-expanded", "false");
     button.classList.remove("on");
     document.removeEventListener("pointerdown", onOutside, true);
@@ -230,12 +315,24 @@ export function attachViewStyleControls(viewer, { stage, toolbar = null, anchor
   const offs = [
     viewer.onRenderModeChange(() => render()),
     viewer.onEnvironmentChange(() => render()),
+    // The card's sphere thumbnails show the look itself: a new one re-renders them.
+    viewer.onRenderModeChange(() => { viewer.invalidateMaterialThumbnails?.(); if (pop.dataset.page === "card") card?.render(); }),
+    viewer.onEnvironmentChange(() => { viewer.invalidateMaterialThumbnails?.(); if (pop.dataset.page === "card") card?.render(); }),
     viewer.onAssemblyChange?.(() => cache.invalidate()) ?? (() => {}),
-    viewer.onThemeChange?.(() => cache.invalidate()) ?? (() => {}),
+    // A theme change also clears the viewer's material thumbnails (setTheme):
+    // repaint an open card's tiles, or CAD tiles keep the old theme's backdrop.
+    viewer.onThemeChange?.(() => { cache.invalidate(); if (pop.dataset.page === "card") card?.render(); }) ?? (() => {}),
     // A thumbnail shows the section as it was when it was taken, so turning
     // the cutaway on or off, or moving its plane, stales them all — without
     // this a set taken with the cutaway on outlived the cutaway itself.
     viewer.onCutawayChange?.(() => cache.invalidate()) ?? (() => {}),
+    // A material or hide change shows in the thumbnails too (spec A.3), so it
+    // stales them for the next open the same way.
+    viewer.onDisplayChange?.(() => cache.invalidate()) ?? (() => {}),
+    // An assembly rebuild changes the Parts rows (a sub-part enabled or
+    // dropped, a label or material that follows a param), and the seam has no
+    // assembly hook of its own — so the popover re-renders the list here.
+    viewer.onAssemblyChange?.(() => partsList?.render()) ?? (() => {}),
   ];
   render();
   // The popover closes whenever the button's host is hidden: #viewbar hides
@@ -279,6 +376,12 @@ export function attachViewStyleControls(viewer, { stage, toolbar = null, anchor
       if (divider) divider.hidden = !!flag;
     },
     sync: render,
+    openCard: (name) => openCard(name),
+    setSaveState(state) {
+      saveState = state;
+      if (pop.dataset.page === "card") card?.render();
+    },
+    getSaveState: () => saveState,
     detach() {
       if (detached) return;
       detached = true;
@@ -287,6 +390,8 @@ export function attachViewStyleControls(viewer, { stage, toolbar = null, anchor
       button.removeEventListener("keydown", onKey);
       pop.removeEventListener("keydown", onKey);
       for (const off of offs) { try { off(); } catch { /* already gone */ } }
+      partsList?.detach();
+      card?.detach();
       tooltipBinding?.detach();
       hideObserver?.disconnect();
       sizeObserver?.disconnect();