partforge 0.90.0 → 0.92.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.90.0",
+  "version": "0.92.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.js

@@ -387,6 +387,14 @@ export function createCutaway({
     return !enabled || pointSurvivesPlane(plane, point);
   }
 
+  // The live clip plane, for a caller that has to reason about the CUT itself
+  // rather than test a point against it — clicking the cut face is the only one
+  // today. Null while disabled, and a copy either way, so no caller can hold a
+  // stale plane or move ours.
+  function getPlane(target = new THREE.Plane()) {
+    return enabled ? target.copy(plane) : null;
+  }
+
   function registerClippableMaterial(material) {
     if (disposed || !material) return () => {};
     let entry = auxiliaryMaterials.get(material);
@@ -521,6 +529,7 @@ export function createCutaway({
     setTheme,
     setViewportSize,
     isPointVisible,
+    getPlane,
     registerClippableMaterial,
     updateForCamera,
     renderOverlay,

package/src/framework/mount.js

@@ -61,7 +61,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, setHostPane, animation, getView, setView, captureView, attachTooltips, measure, annotate, projection }) {
+export function makeHandle({ ready, dispose, viewer, setParams, listExportableParts, exportParts, setHostPane, animation, getView, setView, captureView, attachTooltips, measure, annotate, projection, pickMarker }) {
   return {
     ready, dispose, setParams,
     // Part-declared animation playback (spec 2026-08-02): animations are
@@ -123,6 +123,16 @@ export function makeHandle({ ready, dispose, viewer, setParams, listExportablePa
       set: () => {},
       onChange: () => () => {},
     },
+    // The pick marker as a thing with a lifetime, for a host that hangs its own
+    // UI off it: hold() keeps the newest marker on screen (earlier held ones
+    // stay held), release() clears them all, and onAnchorChange reports where
+    // the newest one is on the canvas as the camera moves. Same shape
+    // convention as `measure`, `annotate` and `projection`.
+    pickMarker: pickMarker ?? {
+      hold: () => false,
+      release: () => {},
+      onAnchorChange: () => () => {},
+    },
   };
 }
 
@@ -188,6 +198,15 @@ function createCleanupStack() {
 //                                 // { sync, hide, detach } — call sync() after you
 //                                 // toggle a button's disabled state. Detached
 //                                 // automatically on dispose().
+//   runtime.pickMarker.hold();    // keep the marker from the last pick on screen
+//                                 // (earlier held markers stay held), and start
+//                                 // reporting where it is. False when there is
+//                                 // nothing to hold — a marker's flash has a
+//                                 // lifetime, so hold promptly after a pick.
+//   runtime.pickMarker.onAnchorChange((a) => …);  // {x, y, visible} in CSS px from the
+//                                 // canvas's top-left, as the camera moves; null when
+//                                 // nothing is held. Returns an unsubscribe.
+//   runtime.pickMarker.release(); // clear every held marker
 //   runtime.setActive(false);     // park the viewer: stop the render loop and release
 //                                 // both large GPU allocations (the drawing buffer and
 //                                 // the cached capture target). For a host that hides the
@@ -580,11 +599,15 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
         // deliberately not guarded — one is armed by an explicit dev toggle,
         // the other per agent request.
         suppressed: () => measureMode.isEnabled() || (annotateMode?.isEnabled() ?? false),
-        onPick: (selection) => onPick({
+        onPick: (selection, anchor) => onPick({
           selection,
           label: selection.feature?.label ?? part.parts[selection.subPart]?.label ?? selection.subPart,
           prompt: formatSelection(selection, { style: "prompt" }),
           token: formatSelection(selection, { style: "token" }),
+          // Where the marker is on the canvas, in CSS px from its top-left, so
+          // a host can put its own UI beside the dot on the first frame rather
+          // than a round trip later.
+          anchor,
         }),
       });
       cleanup.defer(() => picker.detach());
@@ -1098,6 +1121,11 @@ export function mount(part, { createWorker, elements = {}, onBuild, onPick, onDo
         set: (mode) => viewer.setProjection(mode),
         onChange: (cb) => viewer.onProjectionChange(cb),
       },
+      pickMarker: {
+        hold: () => viewer.holdFlashPoint(),
+        release: () => viewer.releaseFlashPoints(),
+        onAnchorChange: (cb) => viewer.onFlashAnchorChange(cb),
+      },
     });
   } catch (error) {
     try {

package/src/framework/pick-flash.js

@@ -0,0 +1,75 @@
+// Sizing for the transient pick marker (viewer.flashPoint).
+//
+// The marker used to be a fixed 1.2 mm sphere — a constant WORLD size, so it
+// swelled to cover the very feature it was pointing at as soon as you zoomed
+// in, and shrank to nothing on a large part. Sizing it from the camera each
+// frame keeps it a constant handful of CSS pixels under both projections.
+import * as THREE from "three";
+
+export const FLASH_PIXEL_RADIUS = 5; // CSS px — a ~10px dot, the size it read as at default framing
+
+const MIN_RADIUS = 1e-6; // never a zero-scale matrix
+
+const _offset = new THREE.Vector3();
+const _forward = new THREE.Vector3();
+
+// World units spanned by one CSS pixel at `worldPoint`, for `camera`.
+//
+// Perspective: the frustum widens with view depth, so the answer is measured
+// along the view direction rather than as a straight distance to the camera —
+// an off-axis point is farther from the eye than it is deep, and would size a
+// fraction too large. Orthographic: depth does not enter into it at all; the
+// frustum height (as zoom leaves it) is the whole story.
+export function worldPerPixel(camera, worldPoint, viewportHeightPx) {
+  const height = viewportHeightPx > 0 ? viewportHeightPx : 1;
+  if (camera.isOrthographicCamera) {
+    const extent = Math.abs(camera.top - camera.bottom) / (camera.zoom || 1);
+    return extent / height;
+  }
+  camera.getWorldDirection(_forward);
+  const depth = Math.abs(_offset.copy(worldPoint).sub(camera.position).dot(_forward));
+  const fov = ((camera.fov ?? 50) * Math.PI) / 180;
+  return (2 * Math.tan(fov / 2) * depth) / height;
+}
+
+// Radius, in world units, for a marker that should read as `pixelRadius` CSS px.
+export function flashWorldRadius(
+  camera,
+  worldPoint,
+  viewportHeightPx,
+  pixelRadius = FLASH_PIXEL_RADIUS,
+) {
+  const radius = worldPerPixel(camera, worldPoint, viewportHeightPx) * pixelRadius;
+  return Number.isFinite(radius) && radius > MIN_RADIUS ? radius : MIN_RADIUS;
+}
+
+const _projected = new THREE.Vector3();
+
+// Where a world point lands on the canvas, in CSS px from its top-left.
+//
+// `visible` is the answer to "is the marker actually on screen", which is two
+// questions: is it in FRONT of the camera (a point behind a perspective eye
+// projects to a mirrored position with no warning — `ndc.z > 1` is what
+// catches it), and is it inside the canvas. The position is reported either
+// way: an off-screen anchor is information, and the caller decides what to do
+// with it.
+export function projectToScreen(camera, worldPoint, width, height) {
+  _projected.copy(worldPoint).project(camera);
+  const x = (_projected.x * 0.5 + 0.5) * width;
+  // NDC y grows upward, screen y downward — the flip is the whole reason this
+  // is a named function rather than two lines at each call site.
+  const y = (0.5 - _projected.y * 0.5) * height;
+  const inFront = _projected.z >= -1 && _projected.z <= 1;
+  const onCanvas = x >= 0 && x <= width && y >= 0 && y <= height;
+  return { x, y, visible: inFront && onCanvas };
+}
+
+// Is `next` different enough from `previous` to be worth telling anyone about?
+// A still camera re-projects to the same pixel every frame, and publishing that
+// 60 times a second across a postMessage boundary is pure noise.
+export function anchorMoved(previous, next, epsilon = 0.5) {
+  if (!previous || !next) return previous !== next;
+  return previous.visible !== next.visible
+    || Math.abs(previous.x - next.x) >= epsilon
+    || Math.abs(previous.y - next.y) >= epsilon;
+}

package/src/framework/selection/format.js

@@ -10,13 +10,18 @@ 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.label}` : "";
-  return `${head}${feat} · pt(${s.point.join(",")}) n(${fmtNormal(s.normal)}) · {${fmtParams(s.params)}}`;
+  const cut = s.onCutPlane ? " · section" : "";
+  return `${head}${feat}${cut} · 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 ? ` **${s.feature.label}**,` : "";
-  return `On sub-part **${s.subPart}**, the user pointed at${feat} local point (${s.point.join(", ")}), `
+  // The section wording is load-bearing: without it the point reads as a spot
+  // on the part's surface, when it is a spot inside the material that the
+  // cutaway happens to have opened up.
+  const cut = s.onCutPlane ? " the cutaway section face at" : "";
+  return `On sub-part **${s.subPart}**, the user pointed at${feat}${cut} local point (${s.point.join(", ")}), `
     + `normal ${fmtNormal(s.normal)}, with params {${params}}.`;
 }
 

package/src/framework/selection/pick.js

@@ -3,6 +3,7 @@
 import { raycastViewer, worldToSubPartLocal } from "./raycast.js";
 import { resolveSelection } from "./resolve.js";
 import { createDragTracker } from "./drag-tracker.js";
+import { projectToScreen } from "../pick-flash.js";
 
 export { worldToSubPartLocal };
 
@@ -10,6 +11,8 @@ export { worldToSubPartLocal };
 // whose suppression condition lives elsewhere (mount passes measure mode's
 // isEnabled): while it returns true a click neither raycasts, flashes, nor
 // picks — no resync bookkeeping the way an event-driven setActive would need.
+// onPick receives (selection, anchor): where the marker this click flashed
+// landed on the canvas, in CSS px from its top-left.
 export function attachPicker(viewer, { part, getContext, onPick, suppressed }) {
   let active = false;
   const drag = createDragTracker();
@@ -19,11 +22,25 @@ export function attachPicker(viewer, { part, getContext, onPick, suppressed }) {
     // a suppressed click must still clear its just-dragged flag.
     const wasDragged = drag.consumeClick();
     if (!active || wasDragged || suppressed?.()) return;
-    const hit = raycastViewer(viewer, ev.clientX, ev.clientY);
+    // includeSection: in a cutaway the flat cut face is the biggest thing on
+    // screen, and it is the one surface with no geometry behind it to hit.
+    const hit = raycastViewer(viewer, ev.clientX, ev.clientY, { includeSection: true });
     if (!hit) return;
     const selection = resolveSelection(part, getContext(), hit);
     viewer.flashPoint([hit.pointWorld.x, hit.pointWorld.y, hit.pointWorld.z]);
-    onPick(selection);
+    // The anchor is the MARKER's projection, not the pointer's position, even
+    // though the two coincide at this instant: the host's follow-the-camera
+    // stream projects the same world point through the same function every
+    // frame after, so the first answer is of a piece with the rest.
+    // Sized from the rect the raycast just used, which is what makes this
+    // anchor land back on the pixel the user clicked. The stream sizes from the
+    // renderer's last setSize instead — also CSS px, but the CONTAINER's
+    // integer clientWidth/Height as of the last ResizeObserver call, and 1x1
+    // while the viewer is parked. They agree in steady state; the divergence is
+    // staleness, never units.
+    const rect = viewer.domElement.getBoundingClientRect();
+    const anchor = projectToScreen(viewer.camera, hit.pointWorld, rect.width, rect.height);
+    onPick(selection, { x: anchor.x, y: anchor.y });
   }
 
   viewer.domElement.addEventListener("pointerdown", drag.onDown);

package/src/framework/selection/raycast.js

@@ -26,6 +26,18 @@ function normalInSubPartFrame(mesh, normal) {
   return [_normal.x, _normal.y, _normal.z];
 }
 
+const _inverseWorld = new THREE.Matrix4();
+
+// The same trip for a WORLD direction: back through the mesh's world transform
+// into the geometry frame, then forward by its local matrix like any other
+// geometry-frame direction. The cut plane's normal is the only one that arrives
+// this way — it belongs to the scene, not to a triangle.
+function worldNormalInSubPartFrame(mesh, worldNormal) {
+  _inverseWorld.copy(mesh.matrixWorld).invert();
+  _normal.copy(worldNormal).transformDirection(_inverseWorld).transformDirection(mesh.matrix);
+  return [_normal.x, _normal.y, _normal.z];
+}
+
 // The feature carried by a mesh triangle, or null (unlabeled / no attribution data).
 export function featureAt(mesh, triIndex) {
   const { featureIds, features } = mesh.geometry.userData;
@@ -33,7 +45,84 @@ export function featureAt(mesh, triIndex) {
   return id > 0 ? { id, label: features[id - 1] } : null;
 }
 
-export function raycastViewer(viewer, clientX, clientY) {
+const SECTION_EPSILON = 1e-6;
+const _sectionPoint = new THREE.Vector3();
+const _sectionNormal = new THREE.Vector3();
+const _reverseDirection = new THREE.Vector3();
+const _cutPlane = new THREE.Plane();
+
+// The cut FACE under the pointer, when a cutaway is showing one.
+//
+// Nothing real is there to hit: a section view removes the near half by
+// clipping, which the raycaster knows nothing about, so every triangle along
+// that ray is either on the discarded side (rejected by isWorldPointVisible) or
+// a back face three does not report at all. Clicking the largest surface in the
+// view therefore selected nothing.
+//
+// What IS there is solid material, sliced open at the plane. So: find where the
+// ray crosses into the retained half, and ask whether the sub-part is solid at
+// that crossing. It is solid when the ray has entered it more often than it has
+// left it — and the exits of a ray are the entries of the same ray reversed,
+// which is how this stays inside three's front-face raycasting rather than
+// flipping every material to DoubleSide behind the renderer's back.
+function sectionHit(viewer, meshes, forwardHits, surfaceHit) {
+  const plane = viewer.getCutawayPlane?.(_cutPlane);
+  if (!plane) return null;
+  const ray = raycaster.ray;
+  // Only a ray crossing INTO the retained half can reveal a cut face; if the
+  // camera is already on that side, nothing in front of it was removed.
+  if (plane.normal.dot(ray.direction) <= SECTION_EPSILON) return null;
+  const distance = ray.distanceToPlane(plane);
+  if (distance == null || distance <= 0) return null;
+  // A retained surface nearer than the crossing is simply in front of the cut.
+  if (surfaceHit && surfaceHit.distance <= distance) return null;
+  // Nothing entered before the plane can be solid at it, so the reverse
+  // raycast below is pure cost on the common miss — a click on the backdrop.
+  if (!forwardHits.some((hit) => hit.distance < distance)) return null;
+  ray.at(distance, _sectionPoint);
+
+  raycaster.set(_sectionPoint, _reverseDirection.copy(ray.direction).negate());
+  const exitHits = raycaster.intersectObjects(meshes, false);
+
+  let best = null;
+  for (const mesh of meshes) {
+    let net = 0;
+    let entry = null;
+    for (const hit of forwardHits) {
+      if (hit.object !== mesh || hit.distance >= distance) continue;
+      net += 1;
+      entry ??= hit; // hits arrive sorted, so this is the nearest entry
+    }
+    for (const hit of exitHits) {
+      if (hit.object === mesh && hit.distance < distance) net -= 1;
+    }
+    if (net > 0 && (best == null || entry.distance < best.entry.distance)) best = { mesh, entry };
+  }
+  if (!best) return null;
+
+  const { mesh, entry } = best;
+  return {
+    mesh,
+    subPart: mesh.name,
+    // The triangle the ray entered through. It is not the one under the
+    // pointer — a cut face has no triangles — but it is the material the cut
+    // opened, and callers that index by triangle need something real.
+    triIndex: entry.faceIndex,
+    pointWorld: _sectionPoint.clone(),
+    pointLocal: worldToSubPartLocal(mesh, _sectionPoint),
+    // The cut face looks back at the discarded half, opposite the plane normal.
+    normalLocal: worldNormalInSubPartFrame(mesh, _sectionNormal.copy(plane.normal).negate()),
+    // Deliberately unattributed: a cut face is an artefact of the section, not
+    // a surface the part's build ever labelled.
+    feature: null,
+    onCutPlane: true,
+  };
+}
+
+// `includeSection` opts into the cut-face pick above. It is off by default so
+// hover labels and measurement mode keep hitting real geometry only — a
+// dimension pinned to a plane the user can move is not a dimension.
+export function raycastViewer(viewer, clientX, clientY, { includeSection = false } = {}) {
   const rect = viewer.domElement.getBoundingClientRect();
   ndc.x = ((clientX - rect.left) / rect.width) * 2 - 1;
   ndc.y = -((clientY - rect.top) / rect.height) * 2 + 1;
@@ -43,6 +132,13 @@ export function raycastViewer(viewer, clientX, clientY) {
   const hit = hits.find((candidate) =>
     viewer.isWorldPointVisible?.(candidate.point) ?? true
   );
+  // Ordered before the surface answer, not after: the crossing into the
+  // retained half is nearer than anything retained, so when a cut face is
+  // there it is what the pointer is over.
+  if (includeSection) {
+    const section = sectionHit(viewer, meshes, hits, hit);
+    if (section) return section;
+  }
   if (!hit) return null;
   return {
     mesh: hit.object,

package/src/framework/selection/resolve.js

@@ -45,5 +45,9 @@ export function resolveSelection(part, ctx, hit) {
   // Feature attribution from the mesh payload (Solid.label() in the part's build) —
   // the same name the hover tooltip shows, so user, agent, and viewer share vocabulary.
   if (hit.feature) selection.feature = { label: hit.feature.label };
+  // A cutaway section pick: the point is inside the material, on the cut face,
+  // not on a surface the part was built with. Callers that describe the click
+  // in words need to say so — the coordinates alone read as a normal surface.
+  if (hit.onCutPlane) selection.onCutPlane = true;
   return selection;
 }

package/src/framework/viewer.js

@@ -5,6 +5,8 @@ import { LineSegments2 } from "three/addons/lines/LineSegments2.js";
 import { LineSegmentsGeometry } from "three/addons/lines/LineSegmentsGeometry.js";
 import { LineMaterial } from "three/addons/lines/LineMaterial.js";
 import { createCutaway } from "./cutaway.js";
+import { CUTAWAY_OVERLAY_RENDER_ORDER } from "./cutaway-render.js";
+import { flashWorldRadius, projectToScreen, anchorMoved } from "./pick-flash.js";
 import { createCameraTween } from "./camera-tween.js";
 import { orbitPose } from "./camera-orbit.js";
 import { orthoFrustum, perspectiveDistance } from "./projection.js";
@@ -869,6 +871,17 @@ export function createViewer(container, part) {
     liveLights.key.visible = false;
     liveLights.fill.visible = false;
     scene.add(capKey, capKey.target, capFill, capFill.target);
+    // A pick marker is transient UI feedback about a click, never part of the
+    // part, so it belongs in no capture. It used to be near enough true that a
+    // capture would miss one — a dot faded after 1200ms — but a HELD dot lives
+    // as long as the host's UI hangs off it, so any capture taken during a pick
+    // would now bake the yellow sphere into an agent-facing render or a
+    // published thumbnail. Hidden HERE, at the one offscreen chokepoint, rather
+    // than via canonicalCaptureHidden: captureCurrent deliberately ignores that
+    // set. Only dots that were actually shown are restored, so this cannot
+    // resurrect one the live canvas had hidden for its own reasons.
+    const reshowFlashDots = [];
+    for (const dot of flashDots) if (dot.visible) { dot.visible = false; reshowFlashDots.push(dot); }
     try {
       renderer.setRenderTarget(rt);
       renderer.render(renderScene, cam);
@@ -876,11 +889,13 @@ export function createViewer(container, part) {
       // reads antialiased pixels.
       renderer.readRenderTargetPixels(rt, 0, 0, width, height, buf);
     } finally {
-      // Never leave the user's own view unlit or pointed at the offscreen target.
+      // Never leave the user's own view unlit, pointed at the offscreen target,
+      // or missing a marker the user is still looking at.
       renderer.setRenderTarget(null);
       scene.remove(capKey, capKey.target, capFill, capFill.target);
       liveLights.key.visible = true;
       liveLights.fill.visible = true;
+      for (const dot of reshowFlashDots) dot.visible = true;
       if (!cachedSize) rt.dispose();
     }
     const canvas = document.createElement("canvas");
@@ -1049,6 +1064,16 @@ export function createViewer(container, part) {
       try { cb(dt); } catch (e) { console.warn("partforge: frame listener failed", e); }
     }
     if (cutaway.isEnabled) cutaway.updateForCamera();
+    // Re-size the pick markers against the pose this frame will actually draw:
+    // a dot is only alive for about a second, but orbiting or zooming inside
+    // that second must not resize it.
+    for (const dot of flashDots) scaleFlashDot(dot);
+    // …and re-project the held one, so a host anchored to it follows the
+    // camera. Change-gated: a still camera publishes nothing.
+    if (anchorDot) {
+      const next = projectPoint([anchorDot.position.x, anchorDot.position.y, anchorDot.position.z]);
+      if (anchorMoved(lastAnchor, next)) publishAnchor(next);
+    }
     renderer.render(scene, activeCamera);
     cutaway.renderOverlay(renderer, activeCamera);
   }
@@ -1139,22 +1164,119 @@ export function createViewer(container, part) {
   function onCameraEnd(cb) { controls.addEventListener("end", cb); }
 
   // Transient marker at a world-space point — visual confirmation of a pick.
+  //
+  // Two things keep it visible where it used to disappear. It is ordered above
+  // every band the cutaway raises its surfaces, edges and outlines into (a
+  // section view moves them past 1,000,000, so the old fixed 999 was painted
+  // over by the very geometry the marker sat on — and `depthTest: false` means
+  // no depth is written either, so nothing behind it survives the overdraw).
+  // And it is `transparent`, which puts it in the pass three draws LAST: a
+  // translucent part puts the cutaway's caps in the transparent list, where an
+  // opaque marker is already behind whatever its render order.
+  //
+  // The sphere is a UNIT sphere scaled per frame (see below) so it reads as a
+  // constant handful of CSS pixels instead of a fixed millimetre size.
+  const _flashWorld = new THREE.Vector3();
+  const FLASH_RENDER_ORDER = CUTAWAY_OVERLAY_RENDER_ORDER + 1;
   const flashTimers = new Set();
+  const flashDots = new Set();
+  // The subset that will not fade. A HELD marker outlives the pick that made
+  // it, because the host has hung something off it — see holdFlashPoint.
+  const heldDots = new Set();
+  let lastFlashed = null;   // the newest marker, which is what hold() holds
+  let anchorDot = null;     // the held marker the anchor stream follows
+  let lastAnchor = null;
+  const anchorListeners = new Set();
+  const flashGeometry = new THREE.SphereGeometry(1, 16, 12);
+  const flashViewport = new THREE.Vector2();
+
+  function scaleFlashDot(dot) {
+    renderer.getSize(flashViewport); // CSS px, which is what a pixel radius means
+    dot.scale.setScalar(flashWorldRadius(activeCamera, dot.position, flashViewport.y));
+  }
+
+  function projectPoint(world) {
+    renderer.getSize(flashViewport);
+    _flashWorld.set(world[0], world[1], world[2]);
+    return projectToScreen(activeCamera, _flashWorld, flashViewport.x, flashViewport.y);
+  }
+
+  function publishAnchor(anchor) {
+    lastAnchor = anchor;
+    // A throwing subscriber must not stop the render loop or the other
+    // subscribers — same containment the frame listeners get.
+    for (const cb of [...anchorListeners]) {
+      try { cb(anchor); } catch (e) { console.warn("partforge: anchor listener failed", e); }
+    }
+  }
+
+  function dropFlashDot(dot) {
+    scene.remove(dot);
+    dot.material.dispose(); // the geometry is shared and freed in dispose()
+    flashDots.delete(dot);
+    heldDots.delete(dot);
+    if (lastFlashed === dot) lastFlashed = null;
+  }
+
   function flashPoint(world) {
     const dot = new THREE.Mesh(
-      new THREE.SphereGeometry(1.2, 16, 12),
-      new THREE.MeshBasicMaterial({ color: 0xffcc33, depthTest: false })
+      flashGeometry,
+      new THREE.MeshBasicMaterial({
+        color: 0xffcc33, depthTest: false, depthWrite: false, transparent: true,
+      })
     );
-    dot.renderOrder = 999;
+    dot.renderOrder = FLASH_RENDER_ORDER;
     dot.position.set(world[0], world[1], world[2]);
+    scaleFlashDot(dot); // sized before its first frame, not one frame late
     scene.add(dot);
+    flashDots.add(dot);
+    lastFlashed = dot;
     const t = setTimeout(() => {
       flashTimers.delete(t);
-      scene.remove(dot); dot.geometry.dispose(); dot.material.dispose();
+      dot.userData.fadeTimer = null;
+      dropFlashDot(dot);
     }, 1200);
+    dot.userData.fadeTimer = t;
     flashTimers.add(t);
   }
 
+  // Keep the newest marker on screen until released. Earlier held markers stay
+  // held: picking a second spot should light both, and one release() clears
+  // them together. The anchor stream follows the newest, which is the one a
+  // host's own UI is anchored to.
+  function holdFlashPoint() {
+    if (!lastFlashed) return false;
+    const dot = lastFlashed;
+    if (dot.userData.fadeTimer) {
+      clearTimeout(dot.userData.fadeTimer);
+      flashTimers.delete(dot.userData.fadeTimer);
+      dot.userData.fadeTimer = null;
+    }
+    heldDots.add(dot);
+    anchorDot = dot;
+    publishAnchor(projectPoint([dot.position.x, dot.position.y, dot.position.z]));
+    return true;
+  }
+
+  function releaseFlashPoints() {
+    if (heldDots.size === 0 && !anchorDot) return;
+    for (const dot of [...heldDots]) dropFlashDot(dot);
+    anchorDot = null;
+    publishAnchor(null);
+  }
+
+  function onFlashAnchorChange(cb) {
+    // The `disposed` half is the same guard cutaway's onHandleHoverChange takes,
+    // and for the same two reasons: a subscribe racing teardown (effect-cleanup
+    // ordering, a StrictMode remount) would otherwise be handed an anchor for a
+    // dot no longer in the scene, and would re-populate a listener set that
+    // dispose() will never clear again — retaining the embedder's closure.
+    if (disposed || typeof cb !== "function") return () => {};
+    anchorListeners.add(cb);
+    cb(lastAnchor); // current state on subscribe, like onCutawayHandleHover
+    return () => anchorListeners.delete(cb);
+  }
+
   // Full teardown: render loop, observers, controls, timers, GPU resources, DOM.
   // Idempotent. Cached sub-part geometries and their edge lines are freed; the
   // shared and per-part cloned materials tolerate double-dispose.
@@ -1179,6 +1301,16 @@ export function createViewer(container, part) {
     controls.dispose();
     for (const t of flashTimers) clearTimeout(t);
     flashTimers.clear();
+    // A dot whose timer was just cancelled — or one held indefinitely — still
+    // holds its own material; the sphere geometry is shared and freed once.
+    for (const dot of flashDots) { scene.remove(dot); dot.material.dispose(); }
+    flashDots.clear();
+    heldDots.clear();
+    lastFlashed = null;
+    anchorDot = null;
+    lastAnchor = null;
+    anchorListeners.clear();
+    flashGeometry.dispose();
     cutaway.dispose();
     for (const n of names) {
       const g = subCache[n];
@@ -1247,12 +1379,17 @@ export function createViewer(container, part) {
     __subMesh: (n) => subMesh[n],   // test hooks (cf. attachAnimationControls' __viewer)
     __subLines: (n) => subLines[n],
     flashPoint,
+    projectPoint,
+    holdFlashPoint,
+    releaseFlashPoints,
+    onFlashAnchorChange,
     cutawaySupported: () => cutaway.isSupported,
     cutawayEnabled: () => cutaway.isEnabled,
     setCutawayEnabled,
     flipCutaway: cutaway.flip,
     resetCutaway: cutaway.reset,
     isWorldPointVisible: cutaway.isPointVisible,
+    getCutawayPlane: cutaway.getPlane,
     registerCutawayMaterial: cutaway.registerClippableMaterial,
     registerCanonicalCaptureHidden,
     onCutawayHandleHover: cutaway.onHandleHoverChange,

package/types/index.d.ts

@@ -28,6 +28,12 @@ export interface Selection {
   params: Record<string, ParamValue>;
   /** Present when the hit surface carries a `Solid.label()` name. */
   feature?: { label: string };
+  /**
+   * Present when the click landed on a cutaway's cut face. The point is inside
+   * the material rather than on a surface the part was built with, and the
+   * normal faces the half the section removed.
+   */
+  onCutPlane?: true;
 }
 
 export interface PickEvent {
@@ -38,6 +44,8 @@ export interface PickEvent {
   prompt: string;
   /** The selection formatted as a compact token. */
   token: string;
+  /** Where the pick's marker sits on the canvas, in CSS px from its top-left. */
+  anchor: { x: number; y: number };
 }
 
 /** Fired once per completed build. NOT fired for a pose-only edit. */
@@ -238,6 +246,24 @@ export interface AnnotateRuntime {
   onModeChange(cb: () => void): () => void;
 }
 
+/**
+ * The yellow marker a pick flashes, as a thing with a lifetime — for a host
+ * that hangs its own UI (a chat bubble, a callout) off the dot. A marker fades
+ * on its own about a second after the pick, so `hold()` belongs in the `onPick`
+ * handler, not behind a later user action.
+ */
+export interface PickMarkerRuntime {
+  /** Keep the newest marker on screen; false when there is none. Earlier held markers stay held. */
+  hold(): boolean;
+  /** Clear every held marker. */
+  release(): void;
+  /**
+   * Where the newest held marker is, as the camera moves; null when nothing is
+   * held. Fires immediately with the current state. Returns an unsubscribe.
+   */
+  onAnchorChange(cb: (anchor: { x: number; y: number; visible: boolean } | null) => void): () => void;
+}
+
 /** Where playback is: idle, swinging the camera to an intro cue, playing, or paused. */
 export type AnimationStatus = "idle" | "intro" | "playing" | "paused";
 
@@ -353,6 +379,8 @@ export interface PartRuntime {
   measure: MeasureRuntime;
   /** Annotation mode's runtime-controls API — mode on/off, ink state, and send. Always present; a no-op stand-in when `onAnnotationSend` was not supplied. */
   annotate: AnnotateRuntime;
+  /** The pick marker's lifetime — hold it on screen and follow it across the canvas. Always present (a no-op stand-in outside `makeHandle` tests). */
+  pickMarker: PickMarkerRuntime;
 }
 
 /** Mount a full parametric-part app from a `PartDefinition`. */