partforge 0.123.0 → 0.125.0

package/src/framework/mount.js

@@ -7,8 +7,9 @@ import { attachRail } from "./rail.js";
 import { declaredSourceLookup } from "./panel/declared-source.js";
 import { attachMobileTabs } from "./mobile-tabs.js";
 import { createTooltipPresenter, attachButtonTooltips } from "./tooltip.js";
-import { loadCamera, loadProjection, saveProjection, loadRenderMode, loadEnvironment } from "./view-state.js";
-import { attachRealisticControls } from "./realistic-controls.js";
+import { loadCamera, loadRenderMode, loadEnvironment } from "./view-state.js";
+import { isFaceAlignedState } from "./projection.js";
+import { attachViewStyleControls } from "./view-style-controls.js";
 import { ENVIRONMENTS } from "./materials/environments.js";
 import { declaresMaterials, resolveMaterial } from "./materials/resolve.js";
 import { printFrameMatrix } from "./materials/print-frame.js";
@@ -200,8 +201,8 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
     // switch while realistic reverts to the one still shown, and onChange hears
     // both); list() is every environment as {id, label}, for a host picker.
     environment: environment ?? { get: () => "studio", set: async (id) => id, onChange: () => () => {}, list: () => [] },
-    // True when any sub-part names a display.material — a host can offer the
-    // realistic toggle only where it shows something a CAD view does not.
+    // True when any sub-part names a display.material — a host can offer
+    // realistic rendering only where it shows something a CAD view does not.
     declaresMaterials: declaresMaterials ?? false,
   };
 }
@@ -315,9 +316,18 @@ function createCleanupStack() {
 //                                 // every stroke/undo/clear, which is what a host driving its
 //                                 // own Send button gates that button on (strokeCount() > 0).
 //   runtime.projection: { get, set, onChange }
-//                                         // "perspective" | "orthographic". Drives the LIVE view
-//                                         // and captureCurrent only — captureCanonicalViews,
-//                                         // renderMeshPayloads and the CLI stay perspective.
+//                                         // "perspective" | "orthographic". AUTOMATIC in the UI
+//                                         // (Fusion 360's "Perspective with Ortho Faces"): a view
+//                                         // cube FACE click settles into orthographic, an edge or
+//                                         // corner click is perspective, and rotating off the face
+//                                         // returns to perspective (pan and zoom keep it). There
+//                                         // is no user control for it. set("orthographic") still
+//                                         // works for a host, and is left the same way — by the
+//                                         // first rotation. Not persisted across reloads; carried
+//                                         // in viewerState only with a face-view camera. Drives
+//                                         // the LIVE view and captureCurrent only —
+//                                         // captureCanonicalViews, renderMeshPayloads and the CLI
+//                                         // stay perspective.
 //   runtime.renderMode: { get, set, onChange }
 //                                         // "cad" | "realistic". set() resolves to the mode in
 //                                         // effect ("cad" if the realistic assets failed);
@@ -325,7 +335,8 @@ function createCleanupStack() {
 //                                         // projection. Drives the live view; captureCurrent
 //                                         // follows it unless given { renderMode }. captureViews
 //                                         // is always CAD — the live mode never changes what
-//                                         // the agent sees.
+//                                         // the agent sees. Feature lines follow it directly:
+//                                         // CAD always draws them, realistic never does.
 //   runtime.environment: { get, set, onChange, list }
 //                                         // the realistic environment ("studio" | "workshop" |
 //                                         // "print-bed" | "outdoor"); list() → [{id, label}].
@@ -358,8 +369,9 @@ function createCleanupStack() {
 //                                         // KB of base64 apiece, so a host should not assume this
 //                                         // 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 and
-//                                         // environment where that mount
+//                                         // resume the camera, projection, cutaway, render mode,
+//                                         // environment and per-style feature-line preferences
+//                                         // 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
@@ -390,13 +402,20 @@ function createCleanupStack() {
 //                                         // not a degraded one). A rejection is reported through the
 //                                         // control's own onError; the widget keeps the converted blob
 //                                         // so a retry costs a network call, not a reconvert.
-// elements.chrome.realistic / .environment  // optional realistic-mode viewbar controls — a
-//                                         // <button> toggle and an (empty) <select> the mount
-//                                         // fills with the environments; default ids #realistic
-//                                         // and #environment. Without them the host drives
-//                                         // runtime.renderMode / runtime.environment itself.
-//                                         // Both preferences persist like the theme (and carry
-//                                         // in viewerState, which outranks what is stored).
+// (view style — no element)              // the view style button (#view-style, an eye) is
+//                                         // GENERATED into the stage's #viewbar, before #theme
+//                                         // behind a divider (the bar's appearance group); a
+//                                         // stage with no #viewbar gets it over the view cube's
+//                                         // bottom-right corner instead. Its popover holds the
+//                                         // style (CAD or a realistic environment, as live
+//                                         // thumbnails). Hosts need no markup
+//                                         // for it — the old elements.chrome.realistic /
+//                                         // .environment (#realistic, #environment) are gone. A
+//                                         // host can still drive runtime.renderMode /
+//                                         // .environment itself. The preferences persist like the
+//                                         // theme (and carry in viewerState, which outranks what
+//                                         // is stored). There is no projection control: see
+//                                         // runtime.projection.
 // Every `elements` entry defaults to the legacy global-ID lookup (below), resolved
 // exactly once here — submodules take element refs and never query the document.
 // `container`/`controls` remain as deprecated aliases for elements.viewer/.controls.
@@ -439,8 +458,6 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       measure: elements.chrome?.measure ?? byId("measure"),
       annotate: elements.chrome?.annotate ?? byId("annotate"),
       railToggle: elements.chrome?.railToggle ?? byId("rail-toggle"),
-      realistic: elements.chrome?.realistic ?? byId("realistic"),
-      environment: elements.chrome?.environment ?? byId("environment"),
     },
   };
 
@@ -646,13 +663,26 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
         }
       }));
     }
-    // Orientation cube + projection toggle. Generated chrome — no host markup
-    // declares it, so an embedder gets it for free. Restored BEFORE any framing
-    // happens so a reload into ortho frames once instead of framing in
-    // perspective and then visibly re-framing.
-    // A carried state outranks the persisted preference: it is this session's
-    // live answer, where the stored one is the last page-reload's.
-    viewer.setProjection(viewerState?.projection ?? loadProjection());
+    // Orientation cube (and the view style button). Generated chrome — no host markup
+    // declares it, so an embedder gets it for free. The projection is restored
+    // BEFORE any framing happens so a remount into ortho frames once instead of
+    // framing in perspective and then visibly re-framing.
+    //
+    // The projection is AUTOMATIC (viewer.js's tweenCameraTo): orthographic
+    // only on a face view, so it is not a preference and is not persisted —
+    // a page reload opens in perspective. What IS restored is a carried
+    // viewerState, because a host that remounts per edit (partforge-cloud)
+    // would otherwise drop the user out of the face view they were in. Only
+    // when the carried camera is itself a face view, though: an orthographic
+    // state carried with a free-orbit camera (an older host's token, from
+    // when projection was a manual toggle) comes back perspective. The camera
+    // itself lands later (showView); setCameraState re-arms the ortho view on
+    // it, so the first rotation still returns to perspective.
+    viewer.setProjection(
+      viewerState?.projection === "orthographic" && isFaceAlignedState(viewerState.camera)
+        ? "orthographic"
+        : "perspective",
+    );
     // The environment by the same precedence (carried, stored, then the part's
     // own meta.environment — which the viewer already starts on, unchosen). A
     // carried or stored one was chosen, so it stays chosen and carries on. In
@@ -671,9 +701,21 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     // getViewerState carries; an explicit mode change supersedes it, and a
     // failed load settles to CAD.
     if ((viewerState?.renderMode ?? loadRenderMode() ?? "cad") === "realistic") viewer.setRenderMode("realistic");
-    const viewcube = attachViewcubeControls(viewer, { stage: els.viewer }, { tooltip });
+    const viewcube = attachViewcubeControls(viewer, { stage: els.viewer });
     cleanup.defer(() => viewcube.detach());
-    cleanup.defer(viewer.onProjectionChange((mode) => saveProjection(mode)));
+    // The view style button + popover (the style grid). With a #viewbar
+    // (looked up the same way sketchHides does) it joins the bottom toolbar's
+    // appearance group, before #theme behind a divider, and its popover
+    // closes when the bar hides (Sketch). Without one it falls back to the
+    // 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).
+    const viewStyle = attachViewStyleControls(viewer, {
+      stage: els.viewer,
+      toolbar: els.viewer.querySelector("#viewbar"),
+      anchor: viewcube.element,
+    }, { tooltip });
+    cleanup.defer(() => viewStyle.detach());
     // 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
@@ -870,9 +912,11 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       if (frame) {
         framedView = view();
         if (!cameraRestored) {
-          // A carried camera beats the persisted one for the same reason the
-          // projection above does — and it is also the accurate one, since the
-          // persisted pose is only written at the end of an orbit drag.
+          // A carried camera beats the persisted one: it is this session's live
+          // answer, where the stored one is the last page-reload's — and it is
+          // also the accurate one, since the persisted pose is only written at
+          // the end of an orbit drag. An orthographic restore above was made
+          // only for a face-view camera, and this is the call that re-arms it.
           const cam = viewerState?.camera ?? loadCamera();
           if (cam) viewer.setCameraState(cam);
           // The cutaway goes back on AFTER the camera and only here, on the
@@ -883,6 +927,14 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
           // fallback pose from the wrong view.)
           if (viewerState?.cutaway?.enabled && viewer.setCutawayState?.(viewerState.cutaway)) {
             cutawayChrome.sync(); // the button was not what turned it on
+            // …and place the camera again now the section is back. An ortho
+            // face view's size is matched at the surface on screen, which the
+            // cut decides (the cap, or whatever survives it): the carried pose
+            // was taken WITH the cut, and the first placement above measured
+            // against the uncut part, so without this a sectioned face view
+            // changes zoom on every remount. Same pose, so a perspective
+            // camera does not move.
+            if (cam) viewer.setCameraState(cam);
           }
           cameraRestored = true;
         }
@@ -891,22 +943,42 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
 
     // Print frames for the layer-line pattern: the display → export map of the
     // geometry just delivered, so layers run the way the part is printed rather
-    // than the way it is displayed. Computed at delivery (the frame describes
-    // the delivered mesh, which a later pose-only repair only moves) and only
-    // for sub-parts whose material draws layer lines — each one costs two
-    // geometry-free probe builds.
+    // than the way it is displayed. Each frame describes the delivered mesh
+    // (which a later pose-only repair only moves), and only sub-parts whose
+    // material draws layer lines have one — which includes every
+    // sub-part naming no material, since realistic mode shows those as PLA
+    // (resolve.js). One without a place() is identity at once; one with it
+    // costs two geometry-free probe builds.
     const layerLined = new Set(Object.keys(part.parts).filter((n) => {
       try { return resolveMaterial(part.parts[n].display).params.pattern === "layer-lines"; } catch { return false; }
     }));
+    // LAZY: a delivery only records the view and params it was built at; the
+    // viewer pulls the frames (computePrintFrames) when it is about to draw the
+    // realistic look — live, loading, or borrowed by a capture — so a CAD-only
+    // session never probes (viewer.js setPrintFrameSource). The snapshot keeps
+    // a late computation describing the mesh actually delivered.
     const printFrames = {};
+    const undrawnFrames = new Map(); // sub-part -> { view, params } at its delivery
     function recordPrintFrames(names) {
       const wanted = names.filter((n) => layerLined.has(n));
       if (!wanted.length) return;
-      let resolved;
-      try { resolved = resolveParams(part, params); } catch { return; } // diagnosed by the build
-      for (const n of wanted) printFrames[n] = printFrameMatrix(part.parts[n], { view: view(), ...resolved });
-      viewer.setPrintFrames({ ...printFrames });
+      const at = { view: view(), params: { ...params } };
+      for (const n of wanted) undrawnFrames.set(n, at);
+      viewer.invalidatePrintFrames?.();
     }
+    function computePrintFrames() {
+      const resolvedFor = new Map(); // one resolveParams per delivery, not per sub-part
+      for (const [n, at] of undrawnFrames) {
+        if (!resolvedFor.has(at)) {
+          try { resolvedFor.set(at, resolveParams(part, at.params)); } catch { resolvedFor.set(at, null); } // diagnosed by the build
+        }
+        const resolved = resolvedFor.get(at);
+        if (resolved) printFrames[n] = printFrameMatrix(part.parts[n], { view: at.view, ...resolved });
+      }
+      undrawnFrames.clear();
+      return { ...printFrames };
+    }
+    viewer.setPrintFrameSource?.(computePrintFrames);
 
     // Sub-parts whose latest fresh delivery had zero triangles (see the `meshes` case).
     const emptySubParts = new Set();
@@ -1263,11 +1335,6 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     // Optional host-page viewer chrome (reframe / theme) + camera persistence.
     const chrome = attachViewerControls(viewer, els.chrome, { tooltip });
     cleanup.defer(() => chrome.detach());
-    // Optional realistic-mode chrome: the toggle and the environment picker.
-    const realisticChrome = attachRealisticControls(viewer, {
-      toggle: els.chrome.realistic, envMenu: els.chrome.environment,
-    }, { tooltip });
-    cleanup.defer(() => realisticChrome.detach());
 
     // Full teardown of everything this mount created. Idempotent. A disposed runtime
     // can never surface a late build result (workers are terminated, the loop is

package/src/framework/projection.js

@@ -1,6 +1,7 @@
 // The perspective <-> orthographic framing pair. Pure, so the swap's only
 // interesting property — that the part does not change size the instant the
-// user hits the toggle — is unit-testable without a renderer.
+// projection swaps (a view cube face click settling into ortho, a rotation
+// leaving it) — is unit-testable without a renderer.
 //
 // Perspective frames by DISTANCE; orthographic frames by a frustum height plus
 // a zoom (OrbitControls dollies an ortho camera by changing camera.zoom, not by
@@ -17,3 +18,49 @@ export function orthoFrustum({ fovDeg, distance, aspect = 1 }) {
 export function perspectiveDistance({ halfH, zoom = 1, fovDeg }) {
   return halfH / (zoom * Math.tan((fovDeg * Math.PI) / 360));
 }
+
+// --- automatic projection (Fusion 360's "Perspective with Ortho Faces") -----
+// The live view is orthographic only while it looks straight down one of the
+// six world axes — a view cube FACE view. These are the tests that decide
+// "straight down an axis" and "the user has rotated off it".
+//
+// Half a degree: comfortably above what OrbitControls itself leaves behind (it
+// clamps the polar angle a hair — 1e-6 rad — off the poles, so a settled top
+// view is never exactly on +Y) and far below any rotation a person could make
+// on purpose and expect to see.
+export const FACE_ALIGN_EPS_DEG = 0.5;
+export const FACE_ALIGN_COS = Math.cos((FACE_ALIGN_EPS_DEG * Math.PI) / 180);
+const COS_EPS = FACE_ALIGN_COS;
+
+function unit(v) {
+  const l = Math.hypot(v[0], v[1], v[2]);
+  return l > 0 ? [v[0] / l, v[1] / l, v[2] / l] : null;
+}
+
+// `dir` is any non-zero vector (the target -> camera offset is what callers
+// pass). True when it lies within FACE_ALIGN_EPS_DEG of +/-X, +/-Y or +/-Z.
+export function isFaceAligned(dir) {
+  const d = Array.isArray(dir) ? unit(dir) : null;
+  if (!d || !d.every(Number.isFinite)) return false;
+  return Math.max(Math.abs(d[0]), Math.abs(d[1]), Math.abs(d[2])) >= COS_EPS;
+}
+
+// The same test on a { pos, target } camera state (getCameraState's shape,
+// and what a host carries in viewerState.camera). A missing or malformed state
+// is not aligned — the caller then restores perspective, the safe default.
+export function isFaceAlignedState(state) {
+  const p = state?.pos, t = state?.target;
+  if (!Array.isArray(p) || !Array.isArray(t) || p.length !== 3 || t.length !== 3) return false;
+  return isFaceAligned([p[0] - t[0], p[1] - t[1], p[2] - t[2]]);
+}
+
+// True once `dir` has turned more than FACE_ALIGN_EPS_DEG away from `axis`
+// (both non-zero vectors; neither need be unit length). A pan moves the camera
+// and its target together and an orthographic zoom moves neither, so only a
+// ROTATION trips this — which is why direction, not OrbitControls' "start"
+// event (fired for pan and zoom too), is what ends an ortho face view.
+export function hasLeftAxis(dir, axis) {
+  const a = unit(dir), b = unit(axis);
+  if (!a || !b) return false;
+  return a[0] * b[0] + a[1] * b[1] + a[2] * b[2] < COS_EPS;
+}

package/src/framework/view-state.js

@@ -6,7 +6,10 @@
 // and a fresh session opens on the part's own default (see default-view.js).
 // Reads/writes are guarded: if storage is unavailable (private mode, disabled) or a
 // value is corrupt, reads return the documented default and writes are no-ops —
-// persistence never throws. `renderMode` and `environment` are viewer
+// persistence never throws. The projection is not stored: it is automatic
+// (orthographic only on a view cube face view — viewer.js's tweenCameraTo), so
+// a reload opens in perspective; a stale `partforge:projection` key from when it
+// was a manual toggle is simply never read. `renderMode` and `environment` are viewer
 // preferences like `theme`; in the cloud's opaque-origin sandbox storage throws,
 // so there the host carries them in viewerState instead.
 import { ENVIRONMENTS } from "./materials/environments.js";
@@ -14,7 +17,6 @@ import { ENVIRONMENTS } from "./materials/environments.js";
 const KEY = {
   camera: "partforge:camera",
   theme: "partforge:theme",
-  projection: "partforge:projection",
   renderMode: "partforge:renderMode",
   environment: "partforge:environment",
 };
@@ -61,14 +63,6 @@ export function saveTheme(mode) {
   if (mode === "light" || mode === "dark") write(KEY.theme, mode);
 }
 
-export function loadProjection() {
-  return read(KEY.projection) === "orthographic" ? "orthographic" : "perspective";
-}
-
-export function saveProjection(mode) {
-  if (mode === "perspective" || mode === "orthographic") write(KEY.projection, mode);
-}
-
 // null = nothing (valid) stored — the caller falls back to "cad".
 export function loadRenderMode() {
   const raw = read(KEY.renderMode);

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

@@ -0,0 +1,298 @@
+// src/framework/view-style-controls.js
+// The view style button and its popover: every control that changes HOW the
+// part is drawn, in one place — the style (CAD or a realistic environment, as
+// live thumbnails of this part). Generated into the
+// stage, not declared by the host (the view cube / mobile-tabs.js
+// precedent), so an embedder gets it with no markup.
+//
+// WHERE the button goes is chosen once, at attach time:
+//
+//   - toolbar mode (a `toolbar` was passed — the stage's #viewbar): the
+//     button joins the bottom toolbar's APPEARANCE group, inserted just
+//     before #theme (appended when there is none) behind a divider
+//     (`.pf-viewbar-divider`), so the pill reads "tools | appearance". It is a
+//     plain `#viewbar button` there — no card chrome of its own — and it does
+//     not hide with the view cube (it is not on the cube any more). The
+//     popover opens ABOVE the pill, its right edge flush with the PILL's
+//     right edge. Moved here 2026-09-24 at the user's request after a live
+//     mock, following Fusion 360's display-settings-in-the-nav-bar convention.
+//   - fallback (no toolbar — a host that supplies no #viewbar): the button is
+//     a card-chromed child of the view cube's stack (`anchor`), over the
+//     cube's bottom-right corner (chrome.css), hiding whenever the cube does;
+//     the popover opens above the BUTTON.
+//
+// Either way the popover closes whenever the button's host (#viewbar, or the
+// cube's stack) is hidden — Sketch mode hides both — whether by the `hidden`
+// attribute or by CSS (partforge-cloud hides #viewbar with a class, which is
+// display:none and no attribute at all). One code path for the popover; only
+// its reference rect and the observed host differ.
+//
+// Through 2026-09-24 the popover also held a Projection row (a Perspective /
+// 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.
+//
+// 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";
+
+// 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
+// the move into the toolbar) as recording. One icon in both states: the
+// open popover is signalled by `.on` and aria-expanded, never an eye-off.
+const ICON = `<svg viewBox="0 0 24 24" width="16" height="16" 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 LABEL = "View style";
+
+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 attachViewStyleControls(viewer, { stage, toolbar = null, anchor = 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",
+  });
+  button.innerHTML = ICON;
+  if (!tooltip) button.title = LABEL;
+  // The toolbar wins; see the header. `host` is the element whose `hidden`
+  // closes the popover, `placeRef` the rect the popover is placed from.
+  let divider = null;
+  const host = toolbar ?? anchor;
+  if (toolbar) {
+    divider = el("span", "pf-viewbar-divider", { "aria-hidden": "true" });
+    const theme = [...toolbar.children].find((c) => c.id === "theme") ?? null;
+    toolbar.insertBefore(divider, theme);
+    toolbar.insertBefore(button, theme);
+  } else {
+    (anchor ?? stage).append(button);
+  }
+  const placeRef = toolbar ?? button;
+
+  const pop = el("div", "pf-view-style-popover", { id: "pf-view-style-popover", role: "dialog", "aria-label": LABEL });
+  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" });
+  const tiles = new Map();
+  for (const s of STYLES) {
+    const t = el("button", "pf-view-style-tile", { type: "button", "aria-pressed": "false" });
+    t.dataset.style = s.id;
+    const thumb = el("span", "pf-view-style-thumb");
+    const img = el("img", "", { alt: "" });
+    img.hidden = true;
+    thumb.append(img);
+    const label = el("span", "pf-view-style-label");
+    label.textContent = s.label;
+    t.append(thumb, label);
+    t.addEventListener("click", () => choose(s.id));
+    grid.append(t);
+    tiles.set(s.id, { tile: t, img });
+  }
+
+  pop.append(styleHead, grid);
+  stage.append(pop);
+
+  const tooltipBinding = tooltip ? attachButtonTooltips(tooltip, [{ element: button }]) : null;
+
+  let detached = false;
+
+  // --- state -----------------------------------------------------------------
+  let pendingStyle = null; // a tile clicked whose switch is still loading
+  function render() {
+    const current = styleFor(viewer.getRenderMode(), viewer.getEnvironment());
+    for (const [id, { tile }] of tiles) {
+      tile.setAttribute("aria-pressed", String(id === current));
+      if (id === pendingStyle && id !== current) tile.dataset.busy = "true"; else delete tile.dataset.busy;
+    }
+    tooltipBinding?.sync();
+  }
+
+  // What persists is what the viewer says took effect (the realistic-controls
+  // rule this replaces): a failed load settles to CAD and CAD is saved.
+  async function choose(id) {
+    pendingStyle = id;
+    render();
+    try {
+      if (id === "cad") {
+        saveRenderMode(await viewer.setRenderMode("cad"));
+      } else {
+        saveEnvironment(await viewer.setEnvironment(id));
+        saveRenderMode(await viewer.setRenderMode("realistic"));
+      }
+    } catch { /* the viewer reports failures through its mode event */ }
+    if (pendingStyle === id) pendingStyle = null;
+    render();
+  }
+
+  // --- thumbnails (spec: live, cached; re-rendered on the next OPEN after a change)
+  const cache = createThumbnailCache();
+  function paint(id) {
+    const { img } = tiles.get(id);
+    const url = cache.get(id);
+    if (url) { img.src = url; img.hidden = false; } else { img.hidden = true; }
+  }
+  // A part change WHILE open (a playing animation re-shows the assembly every
+  // frame) does not abort the loop: it only marks the cache stale for the
+  // next open. Aborting on it — the first version — left every tile after the
+  // first empty for as long as an animation played (seen on hinged-box.html).
+  // A slightly older pose is fine here: a thumbnail shows the style, not a
+  // live mirror (spec). What does stop a loop is a close (below), detach, or a
+  // newer loop started by a reopen.
+  let loopToken = 0;
+  async function refreshThumbnails() {
+    if (!cache.isStale()) return;
+    cache.markFresh();
+    const token = ++loopToken;
+    let missed = false;
+    // One at a time: each realistic style may load an environment.
+    for (const s of STYLES) {
+      if (detached || token !== loopToken) return;
+      // Spec: thumbnails render on open, never while closed. A close mid-loop
+      // stops it here and marks the cache stale, so the next open resumes
+      // (re-rendering from the top; the finished ones are cheap to repeat and
+      // keep one freshness flag rather than per-style bookkeeping).
+      if (!isOpen()) { cache.invalidate(); return; }
+      let url = null;
+      try { url = await viewer.renderStyleThumbnail(s.id, { size: 256 }); } catch { url = null; }
+      if (detached || token !== loopToken) return;
+      // A failed or empty render (null) blanks its tile rather than leaving an
+      // older picture up, and leaves the cache stale so the next open tries
+      // again: caching it made one bad moment permanent until a part or theme
+      // change came along.
+      cache.set(s.id, url);
+      if (!url) missed = true;
+      paint(s.id);
+    }
+    if (missed && token === loopToken) cache.invalidate();
+  }
+
+  // --- open / close ------------------------------------------------------------
+  const isOpen = () => !pop.hidden;
+  const onOutside = (e) => {
+    if (!pop.contains(e.target) && !button.contains(e.target)) close({ focus: false });
+  };
+  // Escape is ours only while focus is in the popover or on the button: the
+  // listener sits on those two elements rather than on document, so it runs
+  // BEFORE the stage-level Escape handlers (measure, cutaway — they listen on
+  // the stage and #viewbar) and stopPropagation keeps them from also treating
+  // this key as their exit. Escape pressed anywhere else is left alone.
+  const onKey = (e) => {
+    if (e.key !== "Escape" || !isOpen()) return;
+    e.stopPropagation();
+    e.preventDefault();
+    close();
+  };
+  button.addEventListener("keydown", onKey);
+  pop.addEventListener("keydown", onKey);
+  // Above the reference (the toolbar pill, else the button), right edges
+  // aligned, 8px clear of its top, never past the stage's top — and clamped
+  // so it never runs off the stage's left edge either: a stage narrower than
+  // the popover plus the reference's inset (12px for either placement today)
+  // would otherwise push it out.
+  function place() {
+    const s = stage.getBoundingClientRect(), b = placeRef.getBoundingClientRect();
+    const width = pop.offsetWidth;
+    let right = Math.max(8, s.right - b.right);
+    if (width && s.width - right - width < 8) right = Math.max(8, s.width - width - 8);
+    pop.style.right = `${right}px`;
+    pop.style.bottom = `${Math.max(8, s.bottom - b.top + 8)}px`;
+    pop.style.maxHeight = `${Math.max(160, b.top - s.top - 16)}px`;
+  }
+  function open() {
+    if (isOpen() || button.hidden || host?.hidden) return;
+    // Unhidden before placing so its width can be measured (same frame: no paint between).
+    pop.hidden = false;
+    place();
+    button.setAttribute("aria-expanded", "true");
+    button.classList.add("on");
+    render();
+    document.addEventListener("pointerdown", onOutside, true);
+    refreshThumbnails();
+  }
+  function close({ focus = true } = {}) {
+    if (!isOpen()) return;
+    pop.hidden = true;
+    button.setAttribute("aria-expanded", "false");
+    button.classList.remove("on");
+    document.removeEventListener("pointerdown", onOutside, true);
+    if (focus) button.focus();
+  }
+  const onButton = () => (isOpen() ? close() : open());
+  button.addEventListener("click", onButton);
+
+  const offs = [
+    viewer.onRenderModeChange(() => render()),
+    viewer.onEnvironmentChange(() => render()),
+    viewer.onAssemblyChange?.(() => cache.invalidate()) ?? (() => {}),
+    viewer.onThemeChange?.(() => cache.invalidate()) ?? (() => {}),
+    // 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()) ?? (() => {}),
+  ];
+  render();
+  // The popover closes whenever the button's host is hidden: #viewbar hides
+  // for Sketch mode; the cube's stack (fallback) for Sketch and for a crowded
+  // transport bar. Observing the host actually holding the button means the
+  // toolbar button does NOT go away when the cube hides for crowding.
+  //
+  // Two observers, because there are two ways to hide it. The `hidden`
+  // attribute is what this framework sets; a HOST may instead hide the bar with
+  // its own CSS (partforge-cloud toggles a class on #viewbar), which sets no
+  // attribute. That one is caught by size: a display:none element — or one
+  // inside a display:none ancestor — has no layout box, which a ResizeObserver
+  // reports as a 0x0 resize. Read off the element (getClientRects is empty for
+  // an element with no box) rather than the entry, so the test does not depend
+  // on which box the observer measured. An element that has simply not been
+  // laid out yet is never OPEN, so the early callback a ResizeObserver makes on
+  // observe() closes nothing.
+  const hostHidden = () => host.hidden || host.getClientRects().length === 0;
+  const hideObserver = host && typeof MutationObserver === "function"
+    ? new MutationObserver(() => { if (host.hidden) close({ focus: false }); })
+    : null;
+  hideObserver?.observe(host, { attributes: true, attributeFilter: ["hidden"] });
+  const sizeObserver = host && typeof ResizeObserver === "function"
+    ? new ResizeObserver(() => { if (isOpen() && hostHidden()) close({ focus: false }); })
+    : null;
+  sizeObserver?.observe(host);
+
+  return {
+    element: button,
+    placement: toolbar ? "toolbar" : "anchor",
+    popover: pop,
+    isOpen,
+    open,
+    close,
+    // The divider belongs to the button (it separates the appearance group
+    // the button opens), so it goes with it — else a hidden button leaves a
+    // stray rule at the end of the tools group.
+    setHidden(flag) {
+      if (flag) close({ focus: false });
+      button.hidden = !!flag;
+      if (divider) divider.hidden = !!flag;
+    },
+    sync: render,
+    detach() {
+      if (detached) return;
+      detached = true;
+      close({ focus: false });
+      button.removeEventListener("click", onButton);
+      button.removeEventListener("keydown", onKey);
+      pop.removeEventListener("keydown", onKey);
+      for (const off of offs) { try { off(); } catch { /* already gone */ } }
+      tooltipBinding?.detach();
+      hideObserver?.disconnect();
+      sizeObserver?.disconnect();
+      button.remove();
+      divider?.remove();
+      pop.remove();
+    },
+  };
+}