partforge 0.93.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/docs/AUTHORING-PARTS.md

@@ -139,6 +139,9 @@ export default {
   grammar and preload timing as `fonts` above — but the source resolves to **JSON** in the
   `partforge-vector` format, never to raw `.svg`. That JSON is either **authored** by hand
   (millimetre coordinates, placed as drawn) or the **ingested** output of `partforge/ingest`.
+  A vector source may additionally be that JSON **already parsed** — the object itself,
+  rather than bytes or a URL pointing at it — which is the form to use when the artwork
+  lives beside the part and is meant to stay hand-editable.
   See "Vector geometry" below for the full contract.
 
 ---
@@ -1553,6 +1556,28 @@ import outside a Vite build, so `partforge lint`/`measure`/`render` can't resolv
 source must resolve to the `.vector.json`, never to a raw `.svg` — `k.vector2d` does no
 SVG parsing at all.
 
+**A source may also be the parsed file itself.** Alongside bytes, a URL and a thunk, a
+`vectors` entry accepts the **contents** of a `.vector.json` — the object a JSON import
+yields, or anything else that already holds it:
+
+```js
+import plate from "./assets/plate.vector.json" with { type: "json" };
+export default { vectors: { plate }, /* … */ };
+```
+
+The `with { type: "json" }` attribute is required — Node refuses a JSON import without it.
+Reach for this form when the artwork is **hand-authored and meant to stay editable**: the
+numbers sit in a file a reader can open and change, next to the part that uses them, with
+nothing to fetch in order to see them. Reach for `new URL(…)` instead when the file is
+**ingested output** — generated, large, and not read by hand. `src/parts/emblem.js`
+declares one of each, side by side, for exactly this contrast.
+
+Two consequences worth knowing. `partforge/lint`'s document-aware rules can read a parsed
+source on the very first lint, before any build has run, because there is nothing to
+resolve — with a URL they stay silent until the bytes arrive. And the object is validated
+on every resolve, so a malformed one fails with the same message its fetched twin would;
+it is read and never written, so `build` stays pure.
+
 **Sizing is against the tight geometric bounding box, not a `viewBox`.** Icon sets pad
 their `viewBox` inconsistently, so sizing relative to `viewBox` makes two icons declared at
 the same nominal size look different on the plate. `width`/`height`/`fit` instead measure
@@ -1583,7 +1608,9 @@ a `"role": "subtract"` shape in the JSON, or `.cut()` it in `build`), and
 
 **What this is not.** `k.shape2d` does **not** accept the JSON dialect — it takes the
 internal contour form the polygon helpers and `pathProfile` produce — and there is no
-inline document form in `build`. The two vocabularies stay separated by the file boundary,
+inline document form in `build`. A parsed source (above) does not change that: it is a
+`vectors` **declaration**, resolved and validated before `build` runs, not a document
+`build` may assemble or hand to the kernel. The two vocabularies stay separated by the file boundary,
 which is what lets `docs/VECTOR-FORMAT.md` be the only place they meet. Inline authoring
 stays `pathProfile` (see § "Geometry: the kernel / `Solid` API" above, where `pathProfile` is
 introduced, for which to reach for).

package/docs/VECTOR-FORMAT.md

@@ -567,9 +567,18 @@ one:
 - **Existing artwork** — an `.svg` someone else made — goes through
   `partforge/ingest` once and is then referenced like any other document.
 
+Wherever it comes from, the file reaches a part through its `vectors` map — as a
+URL, as bytes, or as the parsed contents themselves (`import doc from
+"./x.vector.json" with { type: "json" }`). The last form is the one to prefer for
+authored artwork, because it keeps the numbers in a file a reader can open and
+edit rather than behind a fetch. See "Vector geometry" in
+`docs/AUTHORING-PARTS.md` for the declaration rules.
+
 `k.shape2d` does **not** accept this JSON dialect, and there is no inline
-document form in `build`. The two vocabularies stay separated by the file
-boundary; that separation is what lets this document be the only place they meet.
+document form in `build` — a parsed source is a declaration resolved before the
+build, not something `build` assembles. The two vocabularies stay separated by
+the file boundary; that separation is what lets this document be the only place
+they meet.
 
 ## 6. Converting an SVG to this format by hand
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.93.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/asset-resolve.js

@@ -11,6 +11,15 @@
 // thunk, is content-stable for a session — resolve it once). DOM-free and
 // node:-free so it stays safe in the geometry worker's import closure.
 
+// The `{ default: … }` module namespace a dynamic `import()` yields, unwrapped to
+// the value itself; every other value passes through untouched. Exported because
+// vectors.js applies the same rule OUTSIDE this resolver — its synchronous lint
+// path reads a declared source directly, without resolving it — and the rule for
+// what a module wrapper looks like must have exactly one definition.
+export function unwrapModule(v) {
+  return v && typeof v === "object" && "default" in v && !toBuffer(v) && !(v instanceof URL) ? v.default : v;
+}
+
 export function toBuffer(v) {
   if (v instanceof ArrayBuffer) return v;
   // A view may not span its whole backing buffer — slice to its exact range (Node
@@ -33,13 +42,21 @@ function describeSource(v) {
 // async); `errorMessage` is thrown when `source` doesn't match the grammar.
 // Results are cached on the caller-supplied `cache` Map, keyed by source
 // identity, so a repeated declaration resolves (and fetches) only once.
-export function makeAssetResolver(cache, finish, errorMessage) {
+//
+// `adopt(value, source)` is an optional last chance to claim a source that is
+// neither bytes nor fetchable. vectors.js uses it for a source that is ALREADY
+// the parsed contents of its file, where the source IS the asset rather than a
+// way to reach its bytes. It is consulted only for values the grammar is about
+// to refuse, so it can never shadow the bytes/URL/thunk forms; returning
+// `undefined` declines and restores the refusal. Whatever it returns becomes
+// resolveOne's result directly — `finish` takes bytes, and is not called.
+export function makeAssetResolver(cache, finish, errorMessage, adopt = null) {
   return function resolveOne(source) {
     if (cache.has(source)) return cache.get(source);
     const p = (async () => {
       let v = source;
       if (typeof v === "function") v = await v();
-      if (v && typeof v === "object" && "default" in v && !toBuffer(v) && !(v instanceof URL)) v = v.default; // dynamic-import module
+      v = unwrapModule(v);                                          // dynamic-import module
       let bytes = toBuffer(v);
       if (!bytes) {
         if (v instanceof URL || typeof v === "string") {
@@ -53,7 +70,11 @@ export function makeAssetResolver(cache, finish, errorMessage) {
           }
           bytes = await res.arrayBuffer();
         }
-        else throw new Error(errorMessage);
+        else {
+          const claimed = adopt ? adopt(v, source) : undefined;
+          if (claimed !== undefined) return claimed;
+          throw new Error(errorMessage);
+        }
       }
       return finish(bytes, v, source);
     })();

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/vectors.js

@@ -12,7 +12,7 @@
 // argument kernel-front.js:117-121 records for text2d.
 //
 // DOM-free and node:-free.
-import { makeAssetResolver, resolveDecl } from "./asset-resolve.js";
+import { makeAssetResolver, resolveDecl, unwrapModule } from "./asset-resolve.js";
 import { toInternalDocument } from "./geometry/vector-format.js";
 
 const cache = new Map();   // source → Promise<Uint8Array> (raw bytes)
@@ -26,9 +26,32 @@ const cache = new Map();   // source → Promise<Uint8Array> (raw bytes)
 // under the next name that declares it, with that name in the message.
 const parsed = new Map();
 
-function parseDocument(bytes, label) {
+// A source that IS the parsed contents of a partforge-vector file, rather than a
+// way to reach its bytes — the in-tree form, `import doc from "./x.vector.json"`.
+// Returns that object, or null for every other source form.
+//
+// `unwrapModule` first, so a dynamic `import("./x.vector.json")` namespace reads
+// the same as the static default import, matching the rule the resolver applies
+// to bytes and URLs.
+//
+// Deliberately STRUCTURAL, not a format check: anything object-shaped is claimed
+// here and judged afterwards by toInternalDocument, so an object that is not
+// artwork draws the validator's specific complaint (`has format "svg"`) rather
+// than the source grammar's generic one. Arrays are not claimed — an array is
+// never a file, and for it the grammar error names the real mistake.
+function asParsedFile(source) {
+  const v = unwrapModule(source);
+  if (!v || typeof v !== "object" || Array.isArray(v)) return null;
+  if (v instanceof ArrayBuffer || ArrayBuffer.isView(v) || v instanceof URL) return null;
+  return v;
+}
+
+// `payload` is what resolveOne produced: the resolved bytes, or — for a source
+// `asParsedFile` claimed — the file's contents themselves, already parsed.
+function parseDocument(payload, label) {
+  if (!(payload instanceof ArrayBuffer)) return toInternalDocument(payload, label);
   let text;
-  try { text = new TextDecoder().decode(bytes); }
+  try { text = new TextDecoder().decode(payload); }
   catch { throw new Error(`vector2d: "${label}" could not be decoded as UTF-8 text`); }
   let doc;
   try { doc = JSON.parse(text); }
@@ -55,7 +78,9 @@ const rawBySource = new Map();
 const resolveOne = makeAssetResolver(
   cache,
   (bytes, _value, source) => { bytesBySource.set(source, bytes); return bytes; },
-  "resolveVectors: a vector source must be bytes, a URL, or a thunk returning one",
+  "resolveVectors: a vector source must be bytes, a URL, a thunk returning one, "
+    + "or the already-parsed contents of a partforge-vector file",
+  (value) => asParsedFile(value) ?? undefined,
 );
 
 export async function resolveVectors(vectorsDecl) {
@@ -73,9 +98,9 @@ export async function resolveVectors(vectorsDecl) {
   }
   const raw = await resolveDecl(vectorsDecl, resolveOne);
   const out = new Map();
-  for (const [name, bytes] of raw) {
-    let doc = parsed.get(bytes);
-    if (!doc) { doc = parseDocument(bytes, name); parsed.set(bytes, doc); }
+  for (const [name, payload] of raw) {
+    let doc = parsed.get(payload);
+    if (!doc) { doc = parseDocument(payload, name); parsed.set(payload, doc); }
     out.set(name, doc);
   }
   return out;
@@ -99,8 +124,13 @@ export async function resolveVectorDocs(vectorsDecl) {
   const out = new Map();
   await Promise.all(Object.entries(decl).map(async ([name, source]) => {
     try {
-      const bytes = await resolveOne(source);
-      const doc = JSON.parse(new TextDecoder().decode(bytes));
+      const payload = await resolveOne(source);
+      // An adopted source resolves to the raw JSON itself — there is nothing to
+      // decode, and running it through TextDecoder would map a perfectly good
+      // file to null.
+      const doc = payload instanceof ArrayBuffer
+        ? JSON.parse(new TextDecoder().decode(payload))
+        : payload;
       out.set(name, doc && typeof doc === "object" ? doc : null);
     } catch {
       out.set(name, null);
@@ -139,6 +169,11 @@ export function cachedVectorDocs(vectorsDecl) {
   for (const entry of entries) {
     try {
       const [name, source] = entry;
+      // An already-parsed source has nothing to resolve, so unlike bytes and URLs
+      // it is readable on the very first lint — before any build has run. That is
+      // the state a hosted editor spends most of its time in.
+      const inline = asParsedFile(source);
+      if (inline) { out.set(name, inline); continue; }
       if (!bytesBySource.has(source)) continue;        // not resolved yet — stay silent
       if (!rawBySource.has(source)) {
         let doc = null;

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/src/parts/emblem.js

@@ -3,20 +3,32 @@
 // millimetre drawing (`plate`, `units: "mm"`, placed exactly as drawn). The two
 // vectors share one build, composed together with an ordinary boolean.
 //
-// `vectors` is declared with `new URL(..., import.meta.url)`, the same form
-// import-demo.js uses for its STL: Vite turns it into a bundled asset URL, and
-// in Node it is a file: URL that src/testing/assets.js reads off disk. A bare
-// `() => import("./assets/emblem.vector.json")` would work in Vite and fail in the CLI.
+// The two entries also demonstrate the two SOURCE forms, deliberately:
+//
+//   `emblem` is `new URL(..., import.meta.url)` — the form import-demo.js uses
+//   for its STL. Vite turns it into a bundled asset URL; in Node it is a file:
+//   URL src/testing/assets.js reads off disk. Right for ingested output, which is
+//   generated, large, and not meant to be read by hand.
+//
+//   `plate` is the file's parsed CONTENTS, imported directly. Right for artwork
+//   that is hand-authored and meant to STAY hand-editable: the numbers live in a
+//   .json a reader can open, and nothing has to fetch anything to see them —
+//   which is also what lets lint read the file before the first build has run.
+//   The `with { type: "json" }` attribute is required: Node refuses a JSON import
+//   without it, and a bare `() => import("./assets/plate.vector.json")` would
+//   work under Vite and fail in the CLI.
 //
 // The source artwork lives beside it as emblem.svg, and the .json is regenerated
 // with `node scripts/ingest-svg.mjs src/parts/assets/emblem.svg`. plate.vector.json
 // is hand-authored — no ingest step, no source SVG — and is kept legible enough
 // to serve as documentation's worked example of a multi-shape, role-composed file.
+import plate from "./assets/plate.vector.json" with { type: "json" };
+
 export default {
   meta: { title: "Emblem", units: "mm", background: 0x15181d },
   vectors: {
     emblem: new URL("./assets/emblem.vector.json", import.meta.url),
-    plate: new URL("./assets/plate.vector.json", import.meta.url),
+    plate,
   },
   parameters: [
     {

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

package/types/part.d.ts

@@ -257,6 +257,57 @@ export type FontSource =
 
 type FontSourceValue = string | ArrayBuffer | ArrayBufferView | { default: string };
 
+// --- imports and vectors ------------------------------------------------------
+
+/**
+ * One entry of a part's `imports` map: the STEP/STL/3MF file a `k.import()` call
+ * names. Same source grammar and preload timing as {@link FontSource}.
+ */
+export type ImportSource = FontSource;
+
+/**
+ * One entry of a part's `vectors` map: a `partforge-vector` file for `k.vector2d()`
+ * to place — never a raw `.svg`, which nothing in the geometry worker can read.
+ *
+ * Beyond the bytes/URL/thunk forms every asset source accepts, a vector source may
+ * be the file's ALREADY-PARSED contents: the object a `.vector.json` yields when
+ * something has imported or fetched it. That is the form to reach for when the
+ * artwork lives in the part's own tree and is meant to stay readable and editable,
+ * rather than sitting behind an opaque asset token.
+ *
+ * The object is read, never written, and is validated on every resolve — so a
+ * malformed one fails with the same message its on-disk twin would produce.
+ */
+export type VectorSource =
+  | string
+  | ArrayBuffer
+  | ArrayBufferView
+  | VectorDocument
+  | (() => VectorSourceValue | Promise<VectorSourceValue>);
+
+type VectorSourceValue =
+  | string
+  | ArrayBuffer
+  | ArrayBufferView
+  | VectorDocument
+  | { default: string | VectorDocument };
+
+/**
+ * The parsed contents of a `partforge-vector` file. `docs/VECTOR-FORMAT.md` is the
+ * normative spec; this type is deliberately shallow — it pins the envelope every
+ * reader depends on and leaves contour shapes to the runtime validator, which
+ * reports far better errors than a structural type mismatch can.
+ */
+export interface VectorDocument {
+  format: "partforge-vector";
+  version: number;
+  units: "mm" | "artwork";
+  shapes: Record<string, unknown>;
+  source?: unknown;
+  bbox?: unknown;
+  note?: string;
+}
+
 // --- derive -----------------------------------------------------------------
 
 /**
@@ -316,6 +367,11 @@ export interface SubPartDefinition<P = ResolvedParams, D = Derived> {
 
 export interface ViewDefinition {
   label: string;
+  /**
+   * Open this view first. With none flagged, the first key wins — see
+   * `default-view.js`, which also falls back when the flagged view is empty.
+   */
+  default?: boolean;
   /**
    * Named animations belonging to this view — keyframe data driving this view's
    * params and sub-part opacity over time. See `AnimationSpec` below; the
@@ -548,6 +604,10 @@ export interface PartDefinition<P = ResolvedParams, D = Derived> {
   defaults: Defaults;
   /** Outline fonts a part's `k.text2d()` calls need, as `{ name: source }`. */
   fonts?: Record<string, FontSource>;
+  /** STEP/STL/3MF files a part's `k.import()` calls need, as `{ name: source }`. */
+  imports?: Record<string, ImportSource>;
+  /** Vector artwork a part's `k.vector2d()` calls place, as `{ name: source }`. */
+  vectors?: Record<string, VectorSource>;
   /** Dependent values computed once per build. */
   derive?: DeriveSpec<P, D>;
   /** Named sub-parts; each builds exactly one solid. */
@@ -556,4 +616,9 @@ export interface PartDefinition<P = ResolvedParams, D = Derived> {
   views: Record<string, ViewDefinition>;
   /** Self-verification, co-located with the schema. */
   verify?: VerifyBlock<P, D>;
+  /**
+   * Named measurements reported by `measure`/`inspect` — never rendered, never
+   * exported. Each entry returns either a solid to measure or plain JSON.
+   */
+  probes?: Record<string, (k: GeometryKernel, p: P, d: D) => unknown>;
 }