partforge 0.91.0 → 0.92.0

package/package.json

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

@@ -42,3 +42,34 @@ export function flashWorldRadius(
   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/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();
@@ -25,7 +28,19 @@ export function attachPicker(viewer, { part, getContext, onPick, suppressed }) {
     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/viewer.js

@@ -6,7 +6,7 @@ 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 } from "./pick-flash.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";
@@ -871,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);
@@ -878,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");
@@ -1055,6 +1068,12 @@ export function createViewer(container, part) {
     // 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);
   }
@@ -1157,15 +1176,48 @@ export function createViewer(container, part) {
   //
   // 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(
       flashGeometry,
@@ -1178,15 +1230,53 @@ export function createViewer(container, part) {
     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);
-      flashDots.delete(dot);
-      // The geometry is shared by every dot and freed in dispose(), not here.
-      scene.remove(dot); 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.
@@ -1211,10 +1301,15 @@ export function createViewer(container, part) {
     controls.dispose();
     for (const t of flashTimers) clearTimeout(t);
     flashTimers.clear();
-    // A dot whose timer was just cancelled still holds its own material; the
-    // sphere geometry is shared across all of them and freed once.
+    // 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) {
@@ -1284,6 +1379,10 @@ 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,

package/types/index.d.ts

@@ -44,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. */
@@ -244,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";
 
@@ -359,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`. */