partforge 0.94.0 → 0.95.0

package/README.md

@@ -120,9 +120,25 @@ runtime.attachTooltips([{ element: myButton }]);  // host chrome buttons join th
                                // aria-label, or a per-entry getLabel()); returns
                                // { sync, hide, detach }, auto-detached on dispose()
 const off = runtime.onContextLost(() => {});  // WebGL context loss; returns an unsubscribe
+const carried = runtime.getViewerState();  // camera + projection + cutaway, as plain JSON
 runtime.dispose();     // stops loops, workers, observers, listeners; frees GPU resources
+mount(nextPart, { createWorker, elements, viewerState: carried });  // resumes the view
 ```
 
+**Carry the view across a remount.** A host that applies edits by mounting a
+new part — rather than by `setParams` — starts each mount from the part's
+default framing, so the camera snaps back and the cutaway closes every time the
+user changes anything. Snapshot with `runtime.getViewerState()` *before*
+`dispose()` and hand the result to the next `mount()` as `viewerState`: the
+part changes, the user's view of it does not.
+
+Restore is best-effort per field, so a state that no longer fits is dropped
+rather than fatal. The cut plane's world pose is restored exactly; its
+on-screen size is re-derived from the new geometry, since that is a property of
+the part rather than of the user's choice. Omit `viewerState` on a first mount
+— the viewer then restores its own persisted camera and projection, as it
+always has.
+
 **Park the viewer when you hide it.** A host that hides the canvas with
 `display: none` needs nothing — the container collapses and the ResizeObserver
 shrinks the drawing buffer for free. A host that hides it any other way

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.94.0",
+  "version": "0.95.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",

package/src/framework/cutaway-controls.js

@@ -25,7 +25,7 @@ function actionButton(label, title) {
 // Wire the optional cutaway button to the viewer and create its contextual
 // actions. Hosts that omit the primary button opt out of all DOM behavior.
 export function attachCutawayControls(viewer, { cutaway: button } = {}, { tooltip, escapeGuard } = {}) {
-  if (!button) return { reset: noop, detach: noop };
+  if (!button) return { reset: noop, sync: noop, detach: noop };
 
   const canvas = viewer.domElement;
   const addedCanvasTabIndex = !canvas.hasAttribute("tabindex");
@@ -109,6 +109,12 @@ export function attachCutawayControls(viewer, { cutaway: button } = {}, { toolti
 
   return {
     reset: disable,
+    // Re-read the viewer and repaint the button. Every path in here that
+    // changes the mode already calls it; this exposes it for the one caller
+    // that turns the cutaway on from OUTSIDE the button — mount()'s restore of
+    // a carried viewer state, which would otherwise come back sliced open under
+    // a button still reading "off", with its Flip/Reset row missing.
+    sync,
     detach() {
       if (detached) return;
       detached = true;

package/src/framework/cutaway-math.js

@@ -28,9 +28,16 @@ export function nearestCanonicalAxis(direction, target = new THREE.Vector3()) {
   return target.set(0, 0, 0).setComponent(bestIndex, components[bestIndex] < 0 ? -1 : 1);
 }
 
+// The plane's on-screen extent, as a function of the part's bounds ALONE.
+// Split out of initialCutawayPose so a restored pose can be re-sized against
+// whatever geometry it is landing on without inheriting anything else from the
+// pose it came from — see the cutaway's setState.
+export function cutawayPoseSize(box) {
+  return Math.max(box.getSize(new THREE.Vector3()).length(), 1) * 1.25;
+}
+
 export function initialCutawayPose(box, camera) {
   const position = box.getCenter(new THREE.Vector3());
-  const diagonal = Math.max(box.getSize(new THREE.Vector3()).length(), 1);
   // Square the cut plane up with the part rather than the camera: the axis
   // nearest the view direction, so the near half is still what gets cut away.
   const normal = nearestCanonicalAxis(
@@ -44,7 +51,7 @@ export function initialCutawayPose(box, camera) {
   return {
     position,
     quaternion,
-    size: diagonal * 1.25,
+    size: cutawayPoseSize(box),
   };
 }
 

package/src/framework/cutaway.js

@@ -2,6 +2,7 @@ import * as THREE from "three";
 
 import { createCutawayGizmo } from "./cutaway-gizmo.js";
 import {
+  cutawayPoseSize,
   initialCutawayPose,
   planeFromPose,
   pointSurvivesPlane,
@@ -362,6 +363,62 @@ export function createCutaway({
     return true;
   }
 
+  // --- state carry-over ------------------------------------------------------
+  // The cutaway lives and dies with its mount, and an embedder that applies
+  // every edit by REMOUNTING (partforge-cloud does — the agent's edits, undo,
+  // redo, a settings commit) would otherwise close the user's slice on every
+  // turn. These two carry it across; mount.js owns the handoff.
+  //
+  // The snapshot is plain JSON on purpose. It outlives the mount that produced
+  // it, so a live THREE object would hand the next mount a reference into a
+  // disposed scene — and a host free to store or post it needs something
+  // structured-cloneable either way.
+  const isFiniteTuple = (value, length) =>
+    Array.isArray(value) && value.length === length && value.every(Number.isFinite);
+
+  function getState() {
+    // `size` is deliberately absent. It is a function of the part's bounds, and
+    // the part is exactly what changed between the snapshot and the restore —
+    // carrying it would size the cap and the gizmo for geometry that no longer
+    // exists. What the user actually chose is where the plane sits, which way
+    // it faces, and the flip; setState re-derives the rest.
+    if (!enabled || !pose) return { enabled: false, flipped: false, pose: null };
+    return {
+      enabled: true,
+      flipped,
+      pose: {
+        position: pose.position.toArray(),
+        quaternion: pose.quaternion.toArray(),
+      },
+    };
+  }
+
+  function setState(state) {
+    if (disposed || disabling) return false;
+    // A snapshot taken with the cutaway off carries nothing to restore. This is
+    // not an instruction to disable — setState only ever turns the mode ON, so
+    // restoring into a fresh mount (already off) is correctly a no-op.
+    if (!state?.enabled) return true;
+    // Enable first: this is the path that refuses when the restore is
+    // impossible (no stencil, no geometry yet), and it seeds a pose against the
+    // CURRENT bounds for the malformed-snapshot fallback below to land on.
+    if (!setEnabled(true)) return false;
+    if (!isFiniteTuple(state.pose?.position, 3) || !isFiniteTuple(state.pose?.quaternion, 4)) {
+      return true; // enabled at the fresh pose, which beats refusing the restore outright
+    }
+    const bounds = validBounds(getBounds);
+    flipped = Boolean(state.flipped); // read by applyPose, through planeFromPose and gizmo.setFlipped
+    applyPose({
+      position: new THREE.Vector3().fromArray(state.pose.position),
+      quaternion: new THREE.Quaternion().fromArray(state.pose.quaternion).normalize(),
+      // Re-derived, never carried — see getState above. The fallback covers
+      // setState on an ALREADY-enabled cutaway, where setEnabled returned early
+      // and bounds may since have gone away.
+      size: bounds ? cutawayPoseSize(bounds) : pose.size,
+    }, { activeAppearance: true });
+    return true;
+  }
+
   function setTheme(mode, edgeColor) {
     if (disposed) return false;
     theme = mode;
@@ -526,6 +583,8 @@ export function createCutaway({
     resyncSubpart,
     reset,
     flip,
+    getState,
+    setState,
     setTheme,
     setViewportSize,
     isPointVisible,

package/src/framework/mount.js

@@ -85,6 +85,20 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
         ? { ...opts, recenter: false }
         : opts,
     ),
+    // Everything about the CURRENT VIEW that a host would lose by remounting,
+    // as one plain-JSON token: pass it back as mount()'s `viewerState` and the
+    // remount comes up where the user left it. An embedder that applies edits
+    // by remounting (partforge-cloud applies every one that way) needs this or
+    // the camera snaps and the cutaway closes on every turn.
+    //
+    // Read at teardown time, so it is the LIVE pose — unlike the camera the
+    // viewer persists for a page reload, which only records the end of a drag
+    // and so misses a view-cube click, Reframe, or an animation cue.
+    getViewerState: () => ({
+      camera: viewer.getCameraState(),
+      projection: viewer.getProjection?.() ?? "perspective",
+      cutaway: viewer.getCutawayState?.() ?? null,
+    }),
     // Park/unpark the viewer: stops the render loop and frees the drawing
     // buffer and the cached capture target. For an embedder that hides the
     // canvas without unmounting it — `visibility: hidden`, an off-screen tab —
@@ -264,6 +278,13 @@ function createCleanupStack() {
 //                                         // rather than at its own hi-DPI size. Still hundreds of
 //                                         // 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
+//                                         // 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
+//                                         // camera as before. Restore is best-effort per field: a pose
+//                                         // this part cannot support is dropped, never fatal.
 // annotateSend: "viewbar" | "host"       // who owns the Send affordance. "viewbar" (default) puts
 //                                         // Send in the sketch toolbar alongside the other tools.
 //                                         // "host" drops it: the host draws its own send control —
@@ -276,6 +297,7 @@ function createCleanupStack() {
 // `container`/`controls` remain as deprecated aliases for elements.viewer/.controls.
 export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDownload, onViewChange, onParamsCommit, onAnnotationSend,
                               fontCatalog,
+                              viewerState,
                               annotateSend = "viewbar",
                               container: legacyContainer, controls: legacyControls } = {}) {
   // --- element resolution (the only getElementById calls in the framework, save the ?pickserver client's optional #viewbar lookup) ----
@@ -508,7 +530,9 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
     // 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.
-    viewer.setProjection(loadProjection());
+    // 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());
     const viewcube = attachViewcubeControls(viewer, { stage: els.viewer }, { tooltip });
     cleanup.defer(() => viewcube.detach());
     cleanup.defer(viewer.onProjectionChange((mode) => saveProjection(mode)));
@@ -710,8 +734,20 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
       if (frame) {
         framedView = view();
         if (!cameraRestored) {
-          const cam = loadCamera();
+          // 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.
+          const cam = viewerState?.camera ?? loadCamera();
           if (cam) viewer.setCameraState(cam);
+          // The cutaway goes back on AFTER the camera and only here, on the
+          // first accepted build: enabling it needs the sub-parts registered
+          // and real bounds to size the plane against, neither of which exists
+          // until showAssembly above has run. (Its initial pose also reads the
+          // camera direction, so a restore before the camera would seed the
+          // fallback pose from the wrong view.)
+          if (viewerState?.cutaway?.enabled && viewer.setCutawayState?.(viewerState.cutaway)) {
+            cutawayChrome.sync(); // the button was not what turned it on
+          }
           cameraRestored = true;
         }
       }

package/src/framework/viewer-controls.js

@@ -50,6 +50,13 @@ export function attachViewerControls(
 
   return {
     detach: () => {
+      // Third save site, and the one that catches what the other two miss: the
+      // `end` event above fires for an orbit or a wheel-zoom, but NOT for a
+      // view-cube click, Reframe, or an animation camera cue, so a session that
+      // finished on one of those used to persist a pose the user had already
+      // moved away from. Taking the live pose at teardown makes the stored
+      // camera honest whatever last moved it.
+      saveCamera(viewer.getCameraState());
       themeBtn?.removeEventListener("click", onThemeClick);
       reframeBtn?.removeEventListener("click", onReframeClick);
       window.removeEventListener("pagehide", onPageHide);

package/src/framework/viewer.js

@@ -765,6 +765,16 @@ export function createViewer(container, part) {
     return result;
   }
 
+  // Restoring a snapshot enables the mode, so it reassigns sub-part materials
+  // exactly the way setCutawayEnabled above does — and therefore has to
+  // re-assert live fades for the same reason a paused mid-fade part would
+  // otherwise stick at full opacity.
+  function setCutawayState(state) {
+    const result = cutaway.setState(state);
+    reassertLiveFades();
+    return result;
+  }
+
   // Swap the scene background, grid, and edge-line colors for the given theme.
   function setTheme(mode) {
     const t = THEME[mode] ?? THEME.dark;
@@ -1386,6 +1396,9 @@ export function createViewer(container, part) {
     cutawaySupported: () => cutaway.isSupported,
     cutawayEnabled: () => cutaway.isEnabled,
     setCutawayEnabled,
+    // Carry the slice across a remount — see cutaway.js's getState/setState.
+    getCutawayState: cutaway.getState,
+    setCutawayState,
     flipCutaway: cutaway.flip,
     resetCutaway: cutaway.reset,
     isWorldPointVisible: cutaway.isPointVisible,

package/types/index.d.ts

@@ -132,12 +132,52 @@ export interface MountOptions {
    * the sketch with a typed message — and calls `runtime.annotate.send()`.
    */
   annotateSend?: "viewbar" | "host";
+  /**
+   * A previous mount's `runtime.getViewerState()`, handed back so this mount
+   * resumes the camera, projection and cutaway where that one 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 camera
+   * and projection as before. Restore is best-effort per field: a pose this
+   * part cannot support is dropped, never fatal.
+   */
+  viewerState?: ViewerState | null;
   /** @deprecated alias for `elements.viewer`. */
   container?: HTMLElement | null;
   /** @deprecated alias for `elements.controls`. */
   controls?: HTMLElement | null;
 }
 
+/** A cut plane, as `ViewerState` carries it across a remount. */
+export interface CutawayState {
+  /** Whether the cutaway was on. `false` means there is nothing to restore. */
+  enabled: boolean;
+  /** Which half the plane keeps. */
+  flipped: boolean;
+  /**
+   * The plane's world pose: `position` as `[x, y, z]`, `quaternion` as
+   * `[x, y, z, w]`. `null` while disabled. The plane's on-screen SIZE is
+   * deliberately absent — it follows the part's bounds, and the part is what
+   * changed, so a restore re-derives it from the geometry it lands on.
+   */
+  pose: { position: [number, number, number]; quaternion: [number, number, number, number] } | null;
+}
+
+/**
+ * Everything about the current view that a remount would otherwise lose. Plain
+ * JSON: it outlives the mount that produced it, so nothing in it points into a
+ * disposed scene, and a host may store or post it rather than only handing it
+ * straight back. Read it with `runtime.getViewerState()`; hand it back as
+ * `MountOptions.viewerState`.
+ */
+export interface ViewerState {
+  /** The live camera pose, or `null` when the viewer could not report one. */
+  camera: { pos: [number, number, number]; target: [number, number, number] } | null;
+  projection: "perspective" | "orthographic";
+  cutaway: CutawayState | null;
+}
+
 export interface ExportPartsOptions {
   /** Sub-part names, as `listExportableParts()` reports them. */
   parts: string[];
@@ -346,6 +386,14 @@ export interface PartRuntime {
    * unmounting it. Captures still work while parked. Safe after `dispose()`.
    */
   setActive(active: boolean): void;
+  /**
+   * Snapshot the camera, projection and cutaway so a REMOUNT can resume them —
+   * pass the result as the next `mount()`'s `viewerState`. Read at teardown
+   * time, so it is the live pose, unlike the camera the viewer persists for a
+   * page reload (which only records the end of an orbit drag, and so misses a
+   * view-cube click, Reframe, or an animation cue).
+   */
+  getViewerState(): ViewerState;
   /**
    * Subscribe to WebGL context loss — i.e. the GPU or the OS gave up — so a host
    * can say so rather than showing a dead canvas. The listener takes no