partforge 0.121.1 → 0.123.0

package/src/framework/materials/resolve.js

@@ -0,0 +1,117 @@
+// src/framework/materials/resolve.js
+// Pure resolution of a sub-part's `display` block against the library. Never
+// throws and never rejects a value: an unknown preset falls back to the default,
+// an out-of-range override clamps, an unknown key is ignored — and every one of
+// those is returned as an `issue` so lint can warn about it. Appearance must
+// never be able to fail a build.
+import { PRESETS, DEFAULT_PRESET_ID } from "./presets.js";
+import { ENVIRONMENTS, DEFAULT_ENVIRONMENT_ID } from "./environments.js";
+
+export const OVERRIDE_RANGES = {
+  roughness: [0, 1],
+  metalness: [0, 1],
+  clearcoat: [0, 1],
+  clearcoatRoughness: [0, 1],
+  anisotropy: [0, 1],
+  textureScale: [0.01, 1000],
+};
+
+export const DISPLAY_KEYS = ["color", "opacity", "material", ...Object.keys(OVERRIDE_RANGES)];
+
+const isColor = (v) => Number.isInteger(v) && v >= 0 && v <= 0xffffff;
+
+export function resolveMaterial(display) {
+  const d = display && typeof display === "object" ? display : {};
+  const issues = [];
+  let preset = PRESETS[DEFAULT_PRESET_ID];
+  if (d.material != null) {
+    if (typeof d.material === "string" && Object.hasOwn(PRESETS, d.material)) preset = PRESETS[d.material];
+    else issues.push({ kind: "unknown-material", key: "material", value: d.material });
+  }
+  const params = {
+    color: preset.color,
+    metalness: preset.metalness,
+    roughness: preset.roughness,
+    clearcoat: preset.clearcoat ?? 0,
+    clearcoatRoughness: preset.clearcoatRoughness ?? 0,
+    anisotropy: preset.anisotropy ?? 0,
+    transmission: preset.transmission ?? 0,
+    thickness: preset.thickness ?? 0,
+    ior: preset.ior ?? 1.5,
+    pattern: preset.pattern ?? null,
+    textureScale: preset.textureScale ?? 1,
+    envIntensity: preset.envIntensity ?? 1,
+    specularIntensity: preset.specularIntensity ?? 1,
+    textures: preset.textures ?? null,
+    opacity: 1,
+  };
+  if (isColor(d.color)) params.color = d.color;
+  if (typeof d.opacity === "number" && Number.isFinite(d.opacity)) params.opacity = Math.min(1, Math.max(0, d.opacity));
+  for (const [key, [lo, hi]] of Object.entries(OVERRIDE_RANGES)) {
+    if (!(key in d)) continue;
+    const v = d[key];
+    if (typeof v !== "number" || !Number.isFinite(v)) {
+      issues.push({ kind: "material-override-clamped", key, value: v, clampedTo: params[key] });
+      continue;
+    }
+    const c = Math.min(hi, Math.max(lo, v));
+    if (c !== v) issues.push({ kind: "material-override-clamped", key, value: v, clampedTo: c });
+    params[key] = c;
+  }
+  for (const key of Object.keys(d)) {
+    if (!DISPLAY_KEYS.includes(key)) issues.push({ kind: "material-key-unknown", key, value: d[key] });
+  }
+  // `tinted`: the author named a colour. A textured preset's colour map carries
+  // its own colour, so only an explicit tint multiplies it (physical.js).
+  return { preset, params, issues, tinted: isColor(d.color) };
+}
+
+// CAD-view appearance: the resolved colour on the CAD MeshStandardMaterial,
+// flattened so it reads without an environment map (a metalness-1 material with
+// no environment renders near-black), and lifted to a minimum luminance so a
+// black-rubber part doesn't hide its geometry in the agent's screenshots.
+const MIN_CAD_LUMA = 60; // 0..255, Rec. 709
+export function cadAppearance(display) {
+  const d = display && typeof display === "object" ? display : {};
+  const { params } = resolveMaterial(d);
+  if (d.material == null) {
+    // Byte-for-byte today's behaviour for a part without `material`.
+    return { color: params.color, metalness: 0.25, roughness: 0.55, opacity: params.opacity };
+  }
+  return {
+    color: liftLuma(params.color, MIN_CAD_LUMA),
+    metalness: Math.min(params.metalness, 0.5),
+    roughness: Math.max(params.roughness, 0.3),
+    opacity: params.opacity,
+  };
+}
+
+function liftLuma(color, min) {
+  let r = (color >> 16) & 255, g = (color >> 8) & 255, b = color & 255;
+  const luma = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+  if (luma >= min) return color;
+  // Mix toward mid-grey just far enough to reach `min`, keeping hue.
+  const t = (min - luma) / (128 - luma || 1);
+  r = Math.round(r + (128 - r) * t); g = Math.round(g + (128 - g) * t); b = Math.round(b + (128 - b) * t);
+  return (r << 16) | (g << 8) | b;
+}
+
+// The colour a 3MF object carries: the explicit tint, else the preset's own
+// colour. Null when the sub-part says nothing about appearance, which is what
+// keeps an appearance-free export byte-for-byte unchanged.
+export function printColor(display) {
+  if (!display || typeof display !== "object") return null;
+  if (isColor(display.color)) return display.color;
+  if (display.material == null) return null;
+  return resolveMaterial(display).params.color;
+}
+
+export function declaresMaterials(part) {
+  return Object.values(part?.parts ?? {}).some((sp) => sp?.display?.material != null);
+}
+
+export function resolveEnvironmentId(id) {
+  if (id == null) return { id: DEFAULT_ENVIRONMENT_ID, known: true };
+  if (typeof id === "string" && Object.hasOwn(ENVIRONMENTS, id)) return { id, known: true };
+  return { id: DEFAULT_ENVIRONMENT_ID, known: false };
+}

package/src/framework/materials/tonemap-readback.js

@@ -0,0 +1,36 @@
+// three applies tone mapping and output colour space ONLY on the canvas path
+// (r184: a bound render target gets NoToneMapping and linear output). Realistic
+// captures therefore render HDR into a half-float target and finish here, in JS:
+// exposure → Khronos PBR Neutral (the same curve THREE.NeutralToneMapping uses on
+// the live canvas) → sRGB. Pure; no three import.
+const START = 0.8 - 0.04, DESAT = 0.15;
+
+function neutral(r, g, b) {
+  const x = Math.min(r, g, b);
+  const offset = x < 0.08 ? x - 6.25 * x * x : 0.04;
+  r -= offset; g -= offset; b -= offset;
+  const peak = Math.max(r, g, b);
+  if (peak < START) return [r, g, b];
+  const d = 1 - START;
+  const newPeak = 1 - (d * d) / (peak + d - START);
+  const s = newPeak / peak;
+  r *= s; g *= s; b *= s;
+  const t = 1 - 1 / (DESAT * (peak - newPeak) + 1);
+  return [r + (newPeak - r) * t, g + (newPeak - g) * t, b + (newPeak - b) * t];
+}
+
+const srgb = (l) => {
+  const c = Math.min(1, Math.max(0, l));
+  return Math.round(255 * (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055));
+};
+
+// Linear RGBA floats → sRGB RGBA bytes. Alpha is forced opaque: a realistic
+// capture always has the environment backdrop behind it.
+export function neutralToneMapToSrgb8(src, exposure = 1) {
+  const out = new Uint8ClampedArray(src.length);
+  for (let i = 0; i < src.length; i += 4) {
+    const [r, g, b] = neutral(src[i] * exposure, src[i + 1] * exposure, src[i + 2] * exposure);
+    out[i] = srgb(r); out[i + 1] = srgb(g); out[i + 2] = srgb(b); out[i + 3] = 255;
+  }
+  return out;
+}

package/src/framework/materials/uv.js

@@ -0,0 +1,42 @@
+// Box-projected UVs and brush tangents, added only for realistic mode. three's
+// anisotropy (brushed metal) needs a tangent frame, and CAD meshes carry neither
+// UVs nor tangents. Projection is in OBJECT space along each vertex normal's
+// dominant axis, so it rides with the sub-part and never swims. Nothing samples a
+// texture through these UVs — triplanar patterns (patterns.js) ignore them.
+//
+// The TANGENT attribute is what the brush actually follows. Without one, three
+// derives the frame per pixel from screen-space UV derivatives, which is constant
+// across each triangle: on a fillet or a corner every facet read as its own flat
+// brushed patch, and a triangle whose corners picked different projection axes
+// got a garbage frame outright. The per-vertex tangent is the projection's u-axis
+// (world X, or Y where X dominates the normal) flattened into the tangent plane, so
+// it interpolates smoothly with the (analytic) vertex normals. It turns 90° only
+// across the one facet row where the dominant axis changes, and never through
+// zero — the two candidate axes are orthogonal.
+import * as THREE from "three";
+
+export function ensureBoxUVs(geometry, scaleMm = 20) {
+  if (geometry.userData.boxUVs && geometry.attributes.uv && geometry.attributes.tangent) return geometry;
+  const pos = geometry.attributes.position, nrm = geometry.attributes.normal;
+  const uv = new Float32Array(pos.count * 2);
+  const tangent = new Float32Array(pos.count * 4);
+  for (let i = 0; i < pos.count; i++) {
+    const x = pos.getX(i), y = pos.getY(i), z = pos.getZ(i);
+    const nx = nrm ? nrm.getX(i) : 0, ny = nrm ? nrm.getY(i) : 0, nz = nrm ? nrm.getZ(i) : 1;
+    const ax = Math.abs(nx), ay = Math.abs(ny), az = Math.abs(nz);
+    let u, v;
+    if (az >= ax && az >= ay) { u = x; v = y; } else if (ay >= ax) { u = x; v = z; } else { u = y; v = z; }
+    uv[i * 2] = u / scaleMm; uv[i * 2 + 1] = v / scaleMm;
+    // u-axis minus its normal component; |that| ≥ √½ because the axis is never the
+    // dominant one, so the normalize is always well-conditioned
+    const uxAxis = !(ax > ay && ax > az);
+    const d = uxAxis ? nx : ny;
+    let tx = (uxAxis ? 1 : 0) - d * nx, ty = (uxAxis ? 0 : 1) - d * ny, tz = -d * nz;
+    const L = Math.hypot(tx, ty, tz) || 1;
+    tangent[i * 4] = tx / L; tangent[i * 4 + 1] = ty / L; tangent[i * 4 + 2] = tz / L; tangent[i * 4 + 3] = 1;
+  }
+  geometry.setAttribute("uv", new THREE.BufferAttribute(uv, 2));
+  geometry.setAttribute("tangent", new THREE.BufferAttribute(tangent, 4));
+  geometry.userData.boxUVs = true;
+  return geometry;
+}

package/src/framework/mount.js

@@ -7,12 +7,16 @@ import { attachRail } from "./rail.js";
 import { declaredSourceLookup } from "./panel/declared-source.js";
 import { attachMobileTabs } from "./mobile-tabs.js";
 import { createTooltipPresenter, attachButtonTooltips } from "./tooltip.js";
-import { loadCamera, loadProjection, saveProjection } from "./view-state.js";
+import { loadCamera, loadProjection, saveProjection, loadRenderMode, loadEnvironment } from "./view-state.js";
+import { attachRealisticControls } from "./realistic-controls.js";
+import { ENVIRONMENTS } from "./materials/environments.js";
+import { declaresMaterials, resolveMaterial } from "./materials/resolve.js";
+import { printFrameMatrix } from "./materials/print-frame.js";
 import { buildControls } from "./controls.js";
 import { relevantParamKeys } from "./param-deps.js";
 import { createMeshCache } from "./mesh-cache.js";
 import { createGeometryService } from "./geometry-service.js";
-import { viewSubParts } from "./part-model.js";
+import { viewSubParts, resolveParams } from "./part-model.js";
 import { resolveDerived } from "./derive.js";
 import { createBackendPolicy } from "./backend-select.js";
 import { createDebugOverlay } from "./debug-overlay.js";
@@ -63,7 +67,7 @@ const IMPORT_MESH_BROKEN_MESSAGE = "STEP import tessellation failed to satisfy t
 // carries the worker's own error text. See the correlated "error" case below.
 const importTessellateFailedMessage = (workerMessage) => `STEP import tessellation failed — ${workerMessage}`;
 
-export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, warmExportKernel, setHostPane, setRailLayout, animation, getView, setView, captureView, attachTooltips, measure, annotate, projection, pickMarker, getPanelState, getPanelErrors }) {
+export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, warmExportKernel, setHostPane, setRailLayout, animation, getView, setView, captureView, attachTooltips, measure, annotate, projection, pickMarker, getPanelState, getPanelErrors, renderMode, environment, declaresMaterials, renderViews }) {
   return {
     ready, dispose, setParams,
     // Part-declared animation playback (spec 2026-08-02): animations are
@@ -77,11 +81,19 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
     setView,
     // Offscreen render of a named view (default when omitted, or on an unknown name).
     captureView,
+    // Always CAD, whatever the live render mode: these are the agent's renders.
     captureViews: (viewNames) => viewer.captureCanonicalViews(viewNames),
+    // captureViews in a chosen appearance: renderMode "cad" (the default) is
+    // exactly captureViews() in either live mode; "realistic" borrows the realistic look for the
+    // capture (waiting on the environment's assets) without switching the live
+    // view. Rejects if realistic's assets fail to load.
+    renderViews: renderViews ?? (async (viewNames) => viewer.captureCanonicalViews(viewNames)),
     // `recenter` reads the sub-part geometry only, so with measurement pins on
     // screen the dimension labels — which sit beside the part, not on it —
     // could land outside the centred window. A dimensioned capture therefore
     // keeps the user's exact framing; a host wanting both re-frames first.
+    // Follows the live render mode unless opts.renderMode pins one ("realistic"
+    // only once the environment has loaded — see viewer.captureCurrent).
     captureCurrent: (opts) => viewer.captureCurrent(
       opts?.recenter && (measure ?? NOOP_MEASURE).isEnabled() && (measure ?? NOOP_MEASURE).pinCount() > 0
         ? { ...opts, recenter: false }
@@ -100,6 +112,15 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
       camera: viewer.getCameraState(),
       projection: viewer.getProjection?.() ?? "perspective",
       cutaway: viewer.getCutawayState?.() ?? null,
+      // The mode the user is headed for, not only the one on screen: a
+      // realistic restore or switch still loading reads "realistic", so a
+      // remount mid-load (the cloud remounts on every edit) doesn't drop it.
+      // A failed load settles back to "cad".
+      renderMode: viewer.isRealisticPending?.() ? "realistic" : viewer.getRenderMode?.() ?? "cad",
+      // Only an environment someone CHOSE: carrying the one merely seeded
+      // 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() } : {}),
     }),
     // Every custom control's transient state (selection, a scroll position),
     // keyed by param, as plain JSON — the panel's twin of getViewerState. Hand
@@ -170,6 +191,18 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
       release: () => {},
       onAnchorChange: () => () => {},
     },
+    // Realistic render mode, a viewer-wide display mode like `projection` and
+    // in the same shape. set() resolves to the mode actually in effect — "cad"
+    // if the realistic assets failed to load; onChange receives the viewer's
+    // {mode, busy, error} event (busy while assets load).
+    renderMode: renderMode ?? { get: () => "cad", set: async () => "cad", onChange: () => () => {} },
+    // The realistic environment. set() resolves to the id in effect (a failed
+    // 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.
+    declaresMaterials: declaresMaterials ?? false,
   };
 }
 
@@ -285,6 +318,24 @@ function createCleanupStack() {
 //                                         // "perspective" | "orthographic". 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);
+//                                         // onChange gets {mode, busy, error}. Same shape as
+//                                         // projection. Drives the live view; captureCurrent
+//                                         // follows it unless given { renderMode }. captureViews
+//                                         // is always CAD — the live mode never changes what
+//                                         // the agent sees.
+//   runtime.environment: { get, set, onChange, list }
+//                                         // the realistic environment ("studio" | "workshop" |
+//                                         // "print-bed" | "outdoor"); list() → [{id, label}].
+//                                         // A failed switch while realistic reverts, and onChange
+//                                         // hears the revert.
+//   runtime.declaresMaterials             // true when any sub-part names a display.material
+//   await runtime.renderViews(["front"], { renderMode: "realistic" });
+//                                         // captureViews in a chosen appearance, without
+//                                         // switching the live view; "cad" is exactly captureViews(),
+//                                         // CAD in either live mode
 //   runtime.dispose();     // full teardown
 // onBuild fires per completed build, so it does NOT fire for a pose-only edit —
 // those are repaired in the viewer and produce no build at all.
@@ -307,7 +358,8 @@ 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 and cutaway where that mount
+//                                         // resume the camera, projection, cutaway, render mode and
+//                                         // environment 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
@@ -338,6 +390,13 @@ 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).
 // 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.
@@ -380,6 +439,8 @@ 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"),
     },
   };
 
@@ -592,6 +653,24 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     // 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());
+    // 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
+    // CAD this only records the id, so the realistic restore below loads the
+    // right rig first time rather than the default and then this one.
+    const initialEnv = viewerState?.environment ?? loadEnvironment();
+    if (initialEnv) viewer.setEnvironment(initialEnv);
+    // 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
+    // instead of showing CAD until the build lands and only then waiting on
+    // the assets (a CAD flash on every edit for a host that remounts per
+    // edit). Nothing needs a part yet — unbuilt sub-parts compile when first
+    // shown, and showAssembly brings the ground to the part when it arrives.
+    // While it loads the viewer reports it pending, which is what
+    // 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 });
     cleanup.defer(() => viewcube.detach());
     cleanup.defer(viewer.onProjectionChange((mode) => saveProjection(mode)));
@@ -810,6 +889,25 @@ 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.
+    const layerLined = new Set(Object.keys(part.parts).filter((n) => {
+      try { return resolveMaterial(part.parts[n].display).params.pattern === "layer-lines"; } catch { return false; }
+    }));
+    const printFrames = {};
+    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 });
+    }
+
     // Sub-parts whose latest fresh delivery had zero triangles (see the `meshes` case).
     const emptySubParts = new Set();
 
@@ -869,6 +967,7 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
               // delivered, which buildDone() true guarantees is at the live params.
               fastPath.recordDelivered(m.name);
             }
+            recordPrintFrames(data.meshes.map((m) => m.name));
             // A split dispatch answers in two meshes replies; the busy spinner
             // stays up until the view has everything (the other worker's job may
             // still be running — often OCCT, the slow one).
@@ -1164,6 +1263,11 @@ 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
@@ -1244,6 +1348,19 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
         release: () => viewer.releaseFlashPoints(),
         onAnchorChange: (cb) => viewer.onFlashAnchorChange(cb),
       },
+      renderMode: {
+        get: () => viewer.getRenderMode(),
+        set: (mode) => viewer.setRenderMode(mode),
+        onChange: (cb) => viewer.onRenderModeChange(cb),
+      },
+      environment: {
+        get: () => viewer.getEnvironment(),
+        set: (id) => viewer.setEnvironment(id),
+        onChange: (cb) => viewer.onEnvironmentChange(cb),
+        list: () => Object.values(ENVIRONMENTS).map(({ id, label }) => ({ id, label })),
+      },
+      declaresMaterials: declaresMaterials(part),
+      renderViews: (viewNames, opts) => viewer.renderViews(viewNames, opts),
     });
   } catch (error) {
     try {

package/src/framework/realistic-controls.js

@@ -0,0 +1,78 @@
+// Viewbar chrome for realistic mode: a toggle button and an environment <select>.
+// Both optional (a host without the elements simply has no built-in controls and
+// drives runtime.renderMode / runtime.environment itself). Same shape as
+// viewer-controls.js. The state shown is always the viewer's: the toggle is
+// pressed only once realistic has actually landed, and the menu shows the
+// environment in effect (a failed switch snaps it back).
+import { ENVIRONMENTS } from "./materials/environments.js";
+import { saveRenderMode, saveEnvironment } from "./view-state.js";
+import { attachButtonTooltips } from "./tooltip.js";
+
+const LABEL = "Realistic view";
+const ERROR_LABEL = "Couldn't load realistic view";
+
+export function attachRealisticControls(viewer, { toggle, envMenu } = {}, { tooltip } = {}) {
+  const binding = tooltip && toggle ? attachButtonTooltips(tooltip, [{ element: toggle }]) : null;
+  if (envMenu && !envMenu.options.length) {
+    for (const env of Object.values(ENVIRONMENTS)) {
+      const o = document.createElement("option");
+      o.value = env.id;
+      o.textContent = env.label;
+      envMenu.append(o);
+    }
+    envMenu.setAttribute("aria-label", "Environment");
+  }
+
+  // The last mode event's busy/error, so an environment event or sync() —
+  // which carry neither — re-render without clearing them.
+  let busy = false;
+  let error = null;
+
+  function render() {
+    const mode = viewer.getRenderMode();
+    if (toggle) {
+      const on = mode === "realistic";
+      toggle.classList.toggle("on", on);
+      toggle.setAttribute("aria-pressed", String(on));
+      if (busy) toggle.dataset.busy = "true"; else delete toggle.dataset.busy;
+      const label = error ? ERROR_LABEL : LABEL;
+      toggle.setAttribute("aria-label", label);
+      if (!tooltip) toggle.title = label;
+    }
+    if (envMenu) {
+      envMenu.hidden = mode !== "realistic";
+      envMenu.value = viewer.getEnvironment();
+    }
+    binding?.sync();
+  }
+
+  // A click while realistic is still loading is a change of mind: back to CAD.
+  // What persists is what the viewer says took effect, not what was asked for.
+  const onToggle = () => {
+    const next = viewer.getRenderMode() === "realistic" || busy ? "cad" : "realistic";
+    viewer.setRenderMode(next).then(saveRenderMode, () => {});
+  };
+  const onEnv = () => {
+    viewer.setEnvironment(envMenu.value).then(saveEnvironment, () => {});
+  };
+  toggle?.addEventListener("click", onToggle);
+  envMenu?.addEventListener("change", onEnv);
+  const offMode = viewer.onRenderModeChange((e) => {
+    busy = !!e?.busy;
+    error = e?.error ?? null;
+    render();
+  });
+  const offEnv = viewer.onEnvironmentChange(() => render());
+  render();
+
+  return {
+    sync: render,
+    detach() {
+      toggle?.removeEventListener("click", onToggle);
+      envMenu?.removeEventListener("change", onEnv);
+      offMode();
+      offEnv();
+      binding?.detach();
+    },
+  };
+}

package/src/framework/selection/feature-highlight.js

@@ -40,6 +40,8 @@ export function createFeatureHighlight(viewer) {
   const overlay = new THREE.Mesh(emptyOverlayGeometry, material);
   overlay.visible = false;
   overlay.renderOrder = CUTAWAY_OVERLAY_RENDER_ORDER;
+  // Pointer feedback, never part of a capture (it tints what it covers).
+  const unregisterCapture = viewer.registerCaptureHidden?.(overlay) ?? (() => {});
   let overlayParent = null;
   // Subset cache per sub-part: rebuilt when the sub-part's geometry object
   // changes (i.e. after a regenerate) — keyed on the geometry instance.
@@ -91,6 +93,7 @@ export function createFeatureHighlight(viewer) {
         () => subsets.clear(),
         () => emptyOverlayGeometry?.dispose(),
         unregisterCutaway,
+        unregisterCapture,
         () => material.dispose(),
       );
       runCleanupSteps(steps, "feature highlight cleanup failed");

package/src/framework/view-state.js

@@ -6,12 +6,17 @@
 // 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.
+// persistence never throws. `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";
 
 const KEY = {
   camera: "partforge:camera",
   theme: "partforge:theme",
   projection: "partforge:projection",
+  renderMode: "partforge:renderMode",
+  environment: "partforge:environment",
 };
 
 const viewKey = (partKey) => `partforge:view:${partKey}`;
@@ -64,6 +69,27 @@ 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);
+  return raw === "realistic" || raw === "cad" ? raw : null;
+}
+
+export function saveRenderMode(mode) {
+  if (mode === "cad" || mode === "realistic") write(KEY.renderMode, mode);
+}
+
+// null = nothing stored, or an id this version doesn't know — the caller falls
+// back to the part's own meta.environment.
+export function loadEnvironment() {
+  const raw = read(KEY.environment);
+  return raw && Object.hasOwn(ENVIRONMENTS, raw) ? raw : null;
+}
+
+export function saveEnvironment(id) {
+  if (typeof id === "string" && Object.hasOwn(ENVIRONMENTS, id)) write(KEY.environment, id);
+}
+
 // `partKey` identifies the part — createViewTabs passes `meta.title`. Without one
 // there is nothing safe to key on, so both calls no-op rather than falling back to a
 // shared key (the cross-part bleed this scoping exists to remove).