partforge 0.1.0 → 0.4.0

package/src/framework/mount.js

@@ -1,9 +1,14 @@
 import "./app.css"; // shared chrome styles — every part-app gets them via mount
 import { zipSync } from "fflate";
 import { createViewer } from "./viewer.js";
+import { loadRotating, saveRotating, loadCamera, saveCamera, loadView, saveView } from "./view-state.js";
 import { buildControls } from "./controls.js";
+import { relevantParamKeys, subPartReadKeys, relevanceHash, RELEVANT_ALL } from "./param-deps.js";
 import { createGeometryService } from "./geometry-service.js";
 import { viewSubParts } from "./jobs.js";
+import { detectBackend } from "./geometry/probe.js";
+import { createDebugOverlay } from "./debug-overlay.js";
+import { attachPicker, formatSelection } from "./selection/index.js";
 
 // Mount a full parametric-part app from a PartDefinition: 3-D viewer + control
 // panel + the two geometry workers + the auto-regenerating view/cache loop +
@@ -16,8 +21,19 @@ export function mount(part, { createWorker, container = document.getElementById(
   const names = Object.keys(part.parts);
   const viewer = createViewer(container, part);
 
-  // ?backend=occt routes preview generate through the OCCT worker (dev toggle).
-  const occtPreview = new URLSearchParams(location.search).get("backend") === "occt";
+  // ?backend=occt|manifold forces the backend; otherwise it's detected per part.
+  let forcedBackend = new URLSearchParams(location.search).get("backend");
+  if (forcedBackend !== "occt" && forcedBackend !== "manifold") forcedBackend = null;
+  const backendFor = () => forcedBackend ?? detectBackend(part, params);
+
+  // ?debug shows the cache debug overlay; ?debug&nocache starts with caching off.
+  const qs = new URLSearchParams(location.search);
+  const debug = qs.has("debug");
+  let cachingOn = !(debug && qs.has("nocache"));
+  let lastGen = { skipped: 0, rebuilt: 0 }; // Layer-1 counts for the most recent generate
+  const dbg = debug
+    ? createDebugOverlay({ initialCachingOn: cachingOn, onToggle: (on) => { cachingOn = on; forceRegen(); } })
+    : null;
 
   const statusEl = document.getElementById("status");
   const dlBtn = document.getElementById("download");
@@ -36,20 +52,91 @@ export function mount(part, { createWorker, container = document.getElementById(
   const hideBusy = () => busyEl.classList.remove("show");
 
   // --- per-sub-part mesh cache + auto-regenerating view composition ----------
-  // The host page owns the view-tab markup (#part buttons, data-part = view name);
-  // `part.views` documents the available views and their labels for that page.
-  // The initial view is whichever tab the page marks active (else the first tab).
+  // The view-tab buttons are generated from `part.views` (the single source of truth):
+  // each entry becomes a <button data-part=view>label</button> inside #part, with the
+  // first view marked active by default. (A saved view, below, overrides the default.)
+  if (partSeg && part.views) {
+    partSeg.innerHTML = Object.entries(part.views)
+      .map(([key, v], i) => `<button data-part="${key}"${i === 0 ? ' class="on"' : ""}>${v?.label ?? key}</button>`)
+      .join("");
+  }
+  // The initial view is whichever tab is marked active (else the first tab).
   const params = { ...part.defaults };
-  let view = partSeg.querySelector("button.on")?.dataset.part ?? partSeg.querySelector("button")?.dataset.part;
+  const defaultView = partSeg.querySelector("button.on")?.dataset.part ?? partSeg.querySelector("button")?.dataset.part;
+  const savedView = loadView();
+  const savedBtn = savedView ? [...partSeg.querySelectorAll("button[data-part]")].find((b) => b.dataset.part === savedView) : null;
+  let view = savedBtn ? savedView : defaultView;
+  if (savedBtn) for (const b of partSeg.children) b.classList.toggle("on", b === savedBtn);
+
+  // ?pick enables click-to-select: a toggle button + a transient toast. Off by
+  // default — no button, no listener, no behavior change. Deleting this block and
+  // the selection/ dir reverts the app exactly.
+  if (qs.has("pick")) {
+    const btn = document.createElement("button");
+    btn.id = "pf-pick";
+    btn.textContent = "Pick";
+    btn.title = "Click a surface to copy a selection token";
+    Object.assign(btn.style, {
+      position: "fixed", left: "12px", bottom: "12px", zIndex: 9999,
+      font: "12px system-ui, sans-serif", padding: "6px 10px", cursor: "pointer",
+    });
+    document.body.appendChild(btn);
+
+    const toast = document.createElement("div");
+    Object.assign(toast.style, {
+      position: "fixed", left: "12px", bottom: "48px", zIndex: 9999, maxWidth: "60ch",
+      font: "12px ui-monospace, monospace", padding: "6px 10px", borderRadius: "4px",
+      background: "rgba(20,24,29,0.92)", color: "#d8e0ea", display: "none",
+      whiteSpace: "pre-wrap", wordBreak: "break-word",
+    });
+    document.body.appendChild(toast);
+
+    const picker = attachPicker(viewer, {
+      part,
+      getContext: () => ({ view, params, derived: part.derive ? part.derive({ ...part.defaults, ...params }) : {} }),
+      onPick: (selection) => {
+        const token = formatSelection(selection, { style: "token" });
+        navigator.clipboard?.writeText(token);
+        toast.textContent = `copied: ${token}`;
+        toast.style.display = "block";
+        setTimeout(() => { toast.style.display = "none"; }, 4000);
+      },
+    });
+
+    btn.addEventListener("click", () => {
+      const isActive = btn.classList.toggle("on");
+      picker.setActive(isActive);
+      btn.style.outline = isActive ? "2px solid #ffcc33" : "";
+    });
+  }
+
   let framedView = null; // the view the camera was last framed to (null until first show)
+  let cameraRestored = false; // saved camera applied once, on the first frame after load
   let generating = false;
   let paramsVersion = 0; // bumped on every settings edit
   let genVersion = -1;   // the params version the in-flight generate is building
   let genTimer = null;   // debounce timer for auto-regenerate
-  const cacheVersion = Object.fromEntries(names.map((n) => [n, -1])); // params version each was built at
+  const cacheHash = {}; // n -> relevance hash each sub-part's cached mesh was built at
 
-  // A cached sub-part is current only if it was built at the latest params version.
-  const isCurrent = (n) => viewer._subCache[n] && cacheVersion[n] === paramsVersion;
+  // Memoize the per-sub-part read-key map per (paramsVersion, view): subPartReadKeys
+  // runs probe builds, so we compute it once per change, not per sub-part.
+  let _readsKey = null, _readsMap = null;
+  const readsFor = () => {
+    const key = `${paramsVersion}|${view}`;
+    if (_readsKey !== key) { _readsKey = key; _readsMap = subPartReadKeys(part, view, params); }
+    return _readsMap;
+  };
+  // The relevance hash for one sub-part at the current params (RELEVANT_ALL → hash
+  // over ALL params, so any edit invalidates it — the safe fallback).
+  const hashFor = (n) => {
+    if (!cachingOn) return `v${paramsVersion}`; // caching off: any edit invalidates every sub-part (Layer 1 off)
+    const reads = readsFor();
+    const keys = reads === RELEVANT_ALL ? Object.keys(params) : [...(reads.get(n) ?? Object.keys(params))];
+    return relevanceHash(keys, params);
+  };
+
+  // A cached sub-part is current only if its relevance hash is unchanged.
+  const isCurrent = (n) => !!viewer._subCache[n] && cacheHash[n] === hashFor(n);
   const missingParts = () => viewSubParts(part, view, params).filter((n) => !isCurrent(n));
 
   // Reflect the active view. If every needed part is current, show it and enable
@@ -60,7 +147,14 @@ export function mount(part, { createWorker, container = document.getElementById(
   function showView(needed) {
     const frame = view !== framedView;
     viewer.showAssembly(needed, { frame });
-    if (frame) framedView = view;
+    if (frame) {
+      framedView = view;
+      if (!cameraRestored) {
+        const cam = loadCamera();
+        if (cam) viewer.setCameraState(cam);
+        cameraRestored = true;
+      }
+    }
   }
 
   function refreshView() {
@@ -115,13 +209,14 @@ export function mount(part, { createWorker, container = document.getElementById(
         for (const m of data.meshes) {
           if (viewer._subCache[m.name]) { viewer._subCache[m.name].userData.edges?.dispose(); viewer._subCache[m.name].dispose(); }
           viewer.setSubGeometry(m.name, m);
-          cacheVersion[m.name] = genVersion;
+          cacheHash[m.name] = hashFor(m.name);
         }
         hideBusy();
         refreshView();
         if (data.ms && missingParts().length === 0) {
           setStatus(`${statusEl.textContent} · ${(data.ms / 1000).toFixed(1)} s`);
         }
+        dbg?.update({ ms: data.ms, hits: data.cache?.hits ?? 0, misses: data.cache?.misses ?? 0, skipped: lastGen.skipped, rebuilt: lastGen.rebuilt });
         maybeGenerate(); // active view may still need parts (tab switched during build)
         break;
       }
@@ -135,6 +230,11 @@ export function mount(part, { createWorker, container = document.getElementById(
         triggerDownload(data.data, data.filename, data.mime);
         setStatus(`${data.filename} downloaded`);
         break;
+      case "needs-occt":
+        forcedBackend = "occt"; // probe missed; this part needs OCCT — stick to it
+        generating = false;
+        maybeGenerate();
+        break;
       case "error":
         generating = false;
         hideBusy();
@@ -144,13 +244,16 @@ export function mount(part, { createWorker, container = document.getElementById(
     }
   }
 
-  const service = createGeometryService({ createWorker, onMessage: onWorkerMessage, occtPreview });
+  const service = createGeometryService({ createWorker, onMessage: onWorkerMessage });
 
-  buildControls(controls, part.parameters, params, onParamChange);
+  const panel = buildControls(controls, part.parameters, params, onParamChange);
+  const updateRelevance = () => panel.applyRelevance(relevantParamKeys(part, view, params));
+  updateRelevance(); // initial view
 
   function onParamChange() {
     paramsVersion++; // every edit invalidates the caches (by version)
     refreshView();   // keep showing the now-stale mesh (no flicker); disable export
+    updateRelevance();
     scheduleGenerate();
   }
 
@@ -163,26 +266,38 @@ export function mount(part, { createWorker, container = document.getElementById(
   // Build whatever the active view is missing — automatic, no Generate button.
   function maybeGenerate() {
     if (!kernelReady || generating) return; // retried when the current build finishes
-    const missing = missingParts();
+    const needed = viewSubParts(part, view, params);
+    const missing = needed.filter((n) => !isCurrent(n));
     if (missing.length === 0) return;
     generating = true;
     genVersion = paramsVersion;
+    lastGen = { skipped: needed.length - missing.length, rebuilt: missing.length }; // for the overlay
     showBusy("generating");
-    service.generate({ type: "generate", subparts: missing, view, params });
+    service.generate({ type: "generate", subparts: missing, view, params, cache: cachingOn }, backendFor());
+  }
+
+  // Re-run the active view under the current caching setting, so toggling the
+  // ?debug switch updates the readout for the same design without a param change.
+  function forceRegen() {
+    for (const n of viewSubParts(part, view, params)) delete cacheHash[n];
+    refreshView();
+    maybeGenerate();
   }
 
   partSeg.addEventListener("click", (e) => {
     const btn = e.target.closest("button[data-part]");
     if (!btn) return;
     view = btn.dataset.part;
+    saveView(view);
     for (const b of partSeg.children) b.classList.toggle("on", b === btn);
     refreshView();  // instant if the view's parts are cached + current
+    updateRelevance();
     maybeGenerate(); // else auto-build the missing pieces
   });
 
   dlBtn.addEventListener("click", () => {
     showBusy("exporting STL");
-    service.exportStl({ type: "export-stl", view, params });
+    service.exportStl({ type: "export-stl", view, params }, backendFor());
   });
 
   dlStepBtn.addEventListener("click", () => {
@@ -192,7 +307,7 @@ export function mount(part, { createWorker, container = document.getElementById(
 
   dl3mfBtn?.addEventListener("click", () => {
     showBusy("exporting 3MF");
-    service.export3mf({ type: "export-3mf", view, params });
+    service.export3mf({ type: "export-3mf", view, params }, backendFor());
   });
 
   // --- viewer controls (optional host-page buttons: #pause / #reframe / #theme) --
@@ -214,14 +329,25 @@ export function mount(part, { createWorker, container = document.getElementById(
   themeBtn?.addEventListener("click", () => applyTheme(theme === "light" ? "dark" : "light"));
 
   // Pause/resume the idle auto-rotation.
-  let rotating = true;
+  let rotating = loadRotating();
+  viewer.setAutoRotate(rotating);
+  if (pauseBtn) {
+    pauseBtn.textContent = rotating ? "⏸" : "▶";
+    pauseBtn.title = rotating ? "Pause rotation" : "Resume rotation";
+  }
   pauseBtn?.addEventListener("click", () => {
     rotating = !rotating;
     viewer.setAutoRotate(rotating);
     pauseBtn.textContent = rotating ? "⏸" : "▶";
     pauseBtn.title = rotating ? "Pause rotation" : "Resume rotation";
+    saveRotating(rotating);
   });
 
   // Re-fit the camera to the current view.
   reframeBtn?.addEventListener("click", () => viewer.frame());
+
+  // Persist the camera when the user finishes an orbit/zoom, and right before a
+  // reload (captures the latest pose, including auto-rotation drift).
+  viewer.onCameraEnd(() => saveCamera(viewer.getCameraState()));
+  window.addEventListener("pagehide", () => saveCamera(viewer.getCameraState()));
 }

package/src/framework/param-deps.js

@@ -0,0 +1,81 @@
+// Which raw parameters affect the parts on screen in the active view. A removable
+// relevance layer: the panel uses this to dim controls / hide sections that don't
+// affect what's visible. Pure — no DOM, no real geometry (reuses the geometry-free
+// probe kernel). Errs toward RELEVANT_ALL whenever it can't analyze a build.
+import { createProbeKernel } from "./geometry/probe.js";
+import { viewSubParts } from "./jobs.js";
+
+export const RELEVANT_ALL = Symbol("relevant-all");
+
+// A read-recording Proxy over a shallow clone of `obj`: records each top-level
+// property key read into `seen`, returns the real value so the build's conditionals
+// evaluate correctly, and never mutates the original `obj` (writes hit the clone).
+function recorder(obj, seen) {
+  return new Proxy({ ...obj }, {
+    get(target, key) {
+      if (typeof key === "string") seen.add(key);
+      return Reflect.get(target, key);
+    },
+  });
+}
+
+export function relevantParamKeys(part, view, params) {
+  try {
+    const relevant = new Set();
+
+    // derive: record which raw params feed it; produce real derived values once.
+    const deriveInputs = new Set();
+    const derived = part.derive ? (part.derive(recorder(params, deriveInputs)) ?? {}) : {};
+
+    // gate params: a param read by a view sub-part's enabled() changes what's on screen.
+    for (const name of Object.keys(part.parts)) {
+      const sp = part.parts[name];
+      if (sp.views.includes(view) && sp.enabled) sp.enabled(recorder(params, relevant));
+    }
+
+    // direct build reads across the on-screen (enabled) sub-parts.
+    const { kernel } = createProbeKernel();
+    let anyDerivedRead = false;
+    for (const name of viewSubParts(part, view, params)) {
+      const dSeen = new Set();
+      part.parts[name].build(kernel, recorder(params, relevant), recorder(derived, dSeen));
+      if (dSeen.size > 0) anyDerivedRead = true;
+    }
+    if (anyDerivedRead) for (const k of deriveInputs) relevant.add(k);
+
+    return relevant;
+  } catch {
+    return RELEVANT_ALL; // couldn't analyze — treat everything as relevant
+  }
+}
+
+// Per-sub-part version of relevantParamKeys: which raw params each ON-SCREEN
+// sub-part of the active view reads. Used by Layer 1 (mount.js) to skip
+// regenerating sub-parts whose inputs are unchanged. Errs to RELEVANT_ALL on any
+// analysis failure (caller then treats every param as relevant — safe, just slower).
+export function subPartReadKeys(part, view, params) {
+  try {
+    const deriveInputs = new Set();
+    const derived = part.derive ? (part.derive(recorder(params, deriveInputs)) ?? {}) : {};
+    const { kernel } = createProbeKernel();
+    const map = new Map();
+    for (const name of viewSubParts(part, view, params)) {
+      const sp = part.parts[name];
+      const reads = new Set();
+      const dSeen = new Set();
+      if (sp.enabled) sp.enabled(recorder(params, reads)); // gate params change presence too
+      sp.build(kernel, recorder(params, reads), recorder(derived, dSeen));
+      if (dSeen.size > 0) for (const k of deriveInputs) reads.add(k);
+      map.set(name, reads);
+    }
+    return map;
+  } catch {
+    return RELEVANT_ALL;
+  }
+}
+
+// Stable string of the given param keys' current values — the cache-validity key
+// for one sub-part. Sorted so key order never affects the result.
+export function relevanceHash(keys, params) {
+  return JSON.stringify(keys.slice().sort().map((k) => [k, params[k]]));
+}

package/src/framework/selection/format.js

@@ -0,0 +1,31 @@
+// Pure serializer. No three.js, no DOM. Three styles for the same Selection:
+//   token  — compact clipboard/CLI line
+//   json   — the structured object (embedded tool-call transport)
+//   prompt — one natural-language sentence an LLM ingests well
+const AXIS_LABEL = { "1,0,0": "+X", "-1,0,0": "-X", "0,1,0": "+Y", "0,-1,0": "-Y", "0,0,1": "+Z", "0,0,-1": "-Z" };
+
+const fmtNormal = (n) => AXIS_LABEL[n.join(",")] ?? n.join(",");
+const fmtParams = (p) => Object.entries(p).map(([k, v]) => `${k}:${v}`).join(",");
+
+function tokenStyle(s) {
+  const head = `@${s.subPart}`;
+  const feat = s.feature
+    ? ` · ${s.feature.kind === "cylinder"
+        ? `cyl-face r=${s.feature.radius} axis=${s.feature.axis}`
+        : `${s.feature.kind}-face`}`
+    : "";
+  return `${head}${feat} · pt(${s.point.join(",")}) n(${fmtNormal(s.normal)}) · {${fmtParams(s.params)}}`;
+}
+
+function promptStyle(s) {
+  const params = Object.entries(s.params).map(([k, v]) => `${k}: ${v}`).join(", ");
+  const feat = s.feature ? ` a ${s.feature.kind} face,` : "";
+  return `On sub-part **${s.subPart}**, the user pointed at${feat} local point (${s.point.join(", ")}), `
+    + `normal ${fmtNormal(s.normal)}, with params {${params}}.`;
+}
+
+export function formatSelection(selection, { style = "token" } = {}) {
+  if (style === "json") return selection;
+  if (style === "prompt") return promptStyle(selection);
+  return tokenStyle(selection);
+}

package/src/framework/selection/index.js

@@ -0,0 +1,5 @@
+// Public surface for the click-to-select module. The future agent harness depends
+// only on attachPicker's onPick callback + the Selection contract — nothing else.
+export { resolveSelection, quantizePoint, snapNormal } from "./resolve.js";
+export { formatSelection } from "./format.js";
+export { attachPicker, worldToSubPartLocal } from "./pick.js";

package/src/framework/selection/pick.js

@@ -0,0 +1,48 @@
+// Viewer adapter — the ONLY three.js/DOM-aware file in the selection module.
+// Raycasts a click against the visible sub-meshes, converts the hit to the
+// sub-part's local CAD frame, and hands a resolved Selection to onPick.
+import * as THREE from "three";
+import { resolveSelection } from "./resolve.js";
+
+// Invert the mesh's world transform (pivot rotation + per-view recentring) to recover
+// shared-frame CAD coords — the same frame build() models in.
+export function worldToSubPartLocal(mesh, world) {
+  const v = Array.isArray(world) ? new THREE.Vector3(world[0], world[1], world[2]) : world.clone();
+  mesh.worldToLocal(v);
+  return [v.x, v.y, v.z];
+}
+
+export function attachPicker(viewer, { part, getContext, onPick }) {
+  const raycaster = new THREE.Raycaster();
+  const ndc = new THREE.Vector2();
+  let active = false;
+
+  function onClick(ev) {
+    if (!active) return;
+    const rect = viewer.domElement.getBoundingClientRect();
+    ndc.x = ((ev.clientX - rect.left) / rect.width) * 2 - 1;
+    ndc.y = -((ev.clientY - rect.top) / rect.height) * 2 + 1;
+    raycaster.setFromCamera(ndc, viewer.camera);
+
+    const meshes = Object.values(viewer._subMeshes).filter((m) => m.visible);
+    const hit = raycaster.intersectObjects(meshes, false)[0];
+    if (!hit) return;
+
+    const selection = resolveSelection(part, getContext(), {
+      subPart: hit.object.name,
+      pointLocal: worldToSubPartLocal(hit.object, hit.point),
+      // face.normal is in the geometry's local frame, which equals the CAD frame here
+      // (the mesh carries no local transform; only its parents rotate/recentre).
+      normalLocal: hit.face ? [hit.face.normal.x, hit.face.normal.y, hit.face.normal.z] : [0, 0, 0],
+      // hit.face metadata (kind/axis/radius) is the L1 increment — not populated yet.
+    });
+    viewer.flashPoint([hit.point.x, hit.point.y, hit.point.z]);
+    onPick(selection);
+  }
+
+  viewer.domElement.addEventListener("click", onClick);
+  return {
+    setActive: (on) => { active = !!on; },
+    detach: () => viewer.domElement.removeEventListener("click", onClick),
+  };
+}

package/src/framework/selection/resolve.js

@@ -0,0 +1,54 @@
+// Pure core: turn a backend-agnostic raycast hit into a semantic Selection.
+// No three.js, no DOM, no kernel — only the param-deps read-key analysis.
+import { subPartReadKeys, RELEVANT_ALL } from "../param-deps.js";
+
+const COS_3DEG = 0.99863; // a normal within 3° of an axis snaps to that axis
+const q2 = (x) => { const r = Math.round(x * 100) / 100; return r === 0 ? 0 : r; }; // 0.01mm, kill -0
+
+export function quantizePoint(p) {
+  return [q2(p[0]), q2(p[1]), q2(p[2])];
+}
+
+export function snapNormal(n) {
+  const len = Math.hypot(n[0], n[1], n[2]) || 1;
+  const u = [n[0] / len, n[1] / len, n[2] / len];
+  let ai = 0; // index of the dominant axis
+  if (Math.abs(u[1]) > Math.abs(u[ai])) ai = 1;
+  if (Math.abs(u[2]) > Math.abs(u[ai])) ai = 2;
+  if (Math.abs(u[ai]) >= COS_3DEG) {
+    const axis = [0, 0, 0];
+    axis[ai] = u[ai] > 0 ? 1 : -1;
+    return axis;
+  }
+  return [q2(u[0]), q2(u[1]), q2(u[2])];
+}
+
+// Only the params the clicked sub-part actually reads — "this geometry, at these inputs".
+function scopeParams(part, view, params, subPart) {
+  const reads = subPartReadKeys(part, view, params);
+  const keys = reads === RELEVANT_ALL
+    ? Object.keys(params)
+    : [...(reads.get(subPart) ?? Object.keys(params))];
+  const out = {};
+  for (const k of keys) out[k] = params[k];
+  return out;
+}
+
+export function resolveSelection(part, ctx, hit) {
+  const point = quantizePoint(hit.pointLocal);
+  const selection = {
+    subPart: hit.subPart,
+    point,
+    normal: snapNormal(hit.normalLocal),
+    params: scopeParams(part, ctx.view, ctx.params, hit.subPart),
+  };
+  if (hit.face) {
+    // L1 — feature.selector is the author's own { dir, inPlane, at, near } vocabulary,
+    // so the LLM can drop it straight into a faces(...)/edges(...) call.
+    const feature = { kind: hit.face.kind, selector: { near: point } };
+    if (hit.face.axis != null) { feature.axis = hit.face.axis; feature.selector.dir = hit.face.axis; }
+    if (hit.face.radius != null) feature.radius = hit.face.radius;
+    selection.feature = feature;
+  }
+  return selection;
+}

package/src/framework/view-state.js

@@ -0,0 +1,55 @@
+// Persist a little viewer UI state across browser reloads (notably Vite dev
+// auto-refresh) in localStorage. All keys are global. Reads/writes are guarded:
+// if localStorage is unavailable (private mode, disabled) or a value is corrupt,
+// reads return the documented default and writes are no-ops — persistence never
+// throws. Theme is persisted separately (in mount.js) and is not handled here.
+
+const KEY = {
+  rotating: "partforge:rotating",
+  camera: "partforge:camera",
+  view: "partforge:view",
+};
+
+function read(key) {
+  try { return localStorage.getItem(key); } catch { return null; }
+}
+function write(key, value) {
+  try { localStorage.setItem(key, value); } catch { /* storage unavailable — no-op */ }
+}
+
+const isVec3 = (v) => Array.isArray(v) && v.length === 3 && v.every((n) => Number.isFinite(n));
+
+export function loadRotating() {
+  const raw = read(KEY.rotating);
+  if (raw === "false") return false;
+  if (raw === "true") return true;
+  return true; // default: auto-rotate on (matches the viewer's default)
+}
+
+export function saveRotating(on) {
+  write(KEY.rotating, on ? "true" : "false");
+}
+
+export function loadCamera() {
+  const raw = read(KEY.camera);
+  if (!raw) return null;
+  let parsed;
+  try { parsed = JSON.parse(raw); } catch { return null; }
+  if (parsed && isVec3(parsed.pos) && isVec3(parsed.target)) {
+    return { pos: parsed.pos, target: parsed.target };
+  }
+  return null;
+}
+
+export function saveCamera(state) {
+  if (!state || !isVec3(state.pos) || !isVec3(state.target)) return;
+  write(KEY.camera, JSON.stringify({ pos: state.pos, target: state.target }));
+}
+
+export function loadView() {
+  return read(KEY.view); // raw string or null; caller validates against available tabs
+}
+
+export function saveView(name) {
+  if (typeof name === "string" && name) write(KEY.view, name);
+}

package/src/framework/viewer.js

@@ -61,10 +61,23 @@ export function createViewer(container, part) {
   const partsGroup = new THREE.Group();
   pivot.add(partsGroup);
 
+  // Per-sub-part material: parts share the default material unless they declare
+  // `display: { color?, opacity? }` (e.g. a reference/ghost part shown in a
+  // distinct colour and/or semi-transparent so it reads as "not a printed part").
+  function materialFor(name) {
+    const disp = part.parts[name].display;
+    if (!disp || (disp.color == null && disp.opacity == null)) return material;
+    const m = material.clone();
+    if (disp.color != null) m.color = new THREE.Color(disp.color);
+    if (disp.opacity != null && disp.opacity < 1) { m.transparent = true; m.opacity = disp.opacity; m.depthWrite = false; }
+    return m;
+  }
+
   const subMesh = Object.fromEntries(
-    names.map((n) => [n, new THREE.Mesh(new THREE.BufferGeometry(), material)])
+    names.map((n) => [n, new THREE.Mesh(new THREE.BufferGeometry(), materialFor(n))])
   );
-  for (const m of Object.values(subMesh)) {
+  for (const [n, m] of Object.entries(subMesh)) {
+    m.name = n;
     m.visible = false;
     partsGroup.add(m);
   }
@@ -193,6 +206,20 @@ export function createViewer(container, part) {
     renderer.render(scene, camera);
   });
 
+  // --- camera state (read/write for persistence; mount.js owns storage) -------
+  function getCameraState() {
+    return {
+      pos: [camera.position.x, camera.position.y, camera.position.z],
+      target: [controls.target.x, controls.target.y, controls.target.z],
+    };
+  }
+  function setCameraState({ pos, target }) {
+    camera.position.set(pos[0], pos[1], pos[2]);
+    controls.target.set(target[0], target[1], target[2]);
+    controls.update();
+  }
+  function onCameraEnd(cb) { controls.addEventListener("end", cb); }
+
   // --- dispose --------------------------------------------------------------
   function dispose() {
     renderer.setAnimationLoop(null);
@@ -200,5 +227,17 @@ export function createViewer(container, part) {
     container.removeChild(renderer.domElement);
   }
 
-  return { showAssembly, hideAssembly, setSubGeometry, resize, dispose, frame, setAutoRotate, setTheme, _subCache: subCache };
+  // Transient marker at a world-space point — visual confirmation of a pick.
+  function flashPoint(world) {
+    const dot = new THREE.Mesh(
+      new THREE.SphereGeometry(1.2, 16, 12),
+      new THREE.MeshBasicMaterial({ color: 0xffcc33, depthTest: false })
+    );
+    dot.renderOrder = 999;
+    dot.position.set(world[0], world[1], world[2]);
+    scene.add(dot);
+    setTimeout(() => { scene.remove(dot); dot.geometry.dispose(); dot.material.dispose(); }, 1200);
+  }
+
+  return { showAssembly, hideAssembly, setSubGeometry, resize, dispose, frame, setAutoRotate, setTheme, getCameraState, setCameraState, onCameraEnd, _subCache: subCache, camera, domElement: renderer.domElement, _subMeshes: subMesh, flashPoint };
 }