partforge 0.91.0 → 0.93.0

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/src/framework/worker.js

@@ -10,6 +10,7 @@
 // in docs/KERNEL-CONTRACT.md.
 import { handle } from "./jobs.js";
 import { lintPart } from "../lint.js";
+import { cachedVectorDocs } from "./vectors.js";
 
 async function manifoldKernels() {
   const [{ default: Module }, { createManifoldKernel }] = await Promise.all([
@@ -140,7 +141,51 @@ export function runWorker(part, opts = {}) {
     // the pump awaits that boot, so routing lint through the queue would drag in
     // OCCT's ~11 MB WASM to run a check that never calls the kernel at all.
     if (e.data?.type === "lint") {
-      postMessage({ type: "lint-report", report: lintPart(current, { params: e.data.params }) });
+      // `vectorDocs` is what the two document-dependent vector rules need —
+      // vector-size-missing (does this file's `units` require a size?) and
+      // vector-unknown-shape (does it declare that shape name?). Without it both
+      // stay silent, which is how they are designed to degrade.
+      //
+      // CACHED ONLY, and deliberately so. This handler must stay synchronous:
+      // lint is instant and offline by construction, which is the property that
+      // lets a sandbox run it on every keystroke. Awaiting the async resolver
+      // here made lint hangable (asset-resolve.js's fetch has no timeout) and
+      // made the reply order depend on how fast each part's vectors fetched.
+      // cachedVectorDocs reads only bytes that are already resolved and never
+      // initiates a fetch, so a hosted sandbox gets both rules as soon as one
+      // build has run — the common case — and never waits for them.
+      //
+      // Guarded even so: lintPart's never-throws contract is worth nothing to a
+      // host if the handler around it can throw first and post NOTHING at all —
+      // in a real worker that surfaces as `unhandledrejection`, not an `error`
+      // event, so a host waiting on a lint-report just waits.
+      //
+      // Two levels, because they mean different things. The inner one covers a
+      // hostile `vectors` (a throwing getter, a Proxy whose ownKeys trap throws):
+      // that means "no documents", exactly as if the caller passed none, so the
+      // report is the same one lintPart alone would produce. The outer one is the
+      // last resort for anything neither of us has thought of.
+      let report;
+      try {
+        let vectorDocs;
+        try { vectorDocs = Object.fromEntries(cachedVectorDocs(current?.vectors)); }
+        catch { vectorDocs = undefined; }
+        report = lintPart(current, { params: e.data.params, vectorDocs });
+      } catch (cause) {
+        report = {
+          ok: false,
+          errors: [{
+            rule: "lint-context-error",
+            severity: "error",
+            message: `partforge/lint could not run: ${cause?.message || String(cause)}`,
+            hint: "The part or the lint request is too malformed to analyze — make sure `vectors`, `defaults` and `params` are plain, side-effect-free data rather than throwing getters or hostile Proxies.",
+            path: "",
+          }],
+          warnings: [],
+          notes: [],
+        };
+      }
+      postMessage({ type: "lint-report", report });
       return;
     }
     // Only generates supersede each other; exports/inspect always run (cancelling

package/src/ingest.js

@@ -0,0 +1,8 @@
+// The published `partforge/ingest` entry: SVG -> the partforge-vector JSON
+// format. DOM-required and main-thread only — a host runs it once per artwork
+// and stores the result, the same division of labour as `fontCatalog`.
+// partforge does not write files.
+//
+// Deliberately NOT re-exported from `partforge` (the main entry) or from
+// `partforge/geometry`: this must stay unreachable from the geometry worker.
+export { ingestSvg } from "./framework/ingest/svg-ingest.js";

package/src/parts/assets/emblem.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48">
+  <!-- A filled shape and a stroked OPEN shape, so this one file exercises both
+       of ingest's geometry paths. The union's tight bbox is 40 x 30 artwork
+       units: the circle spans 14..34 in both axes, and the stroked bar spans
+       4..44 in x (round caps add half the 4-unit width at each end) and 40..44
+       in y. Deliberately NOT centred in the viewBox, so anything that sizes from
+       the viewBox instead of the geometry gets a visibly wrong answer. -->
+  <circle cx="24" cy="24" r="10" fill="#111"/>
+  <polyline points="6 42 42 42" fill="none" stroke="#111" stroke-width="4" stroke-linecap="round"/>
+</svg>

package/src/parts/assets/emblem.vector.json

@@ -0,0 +1,110 @@
+{
+  "format": "partforge-vector",
+  "version": 1,
+  "units": "artwork",
+  "note": "Filled 2-D outlines for k.vector2d. `units` is \"mm\" (coordinates are millimetres, placed as authored) or \"artwork\" (no physical meaning; a size is required at every call site). `shapes` maps a name to a list of filled regions; each region's `outer` is its boundary and `holes` are subtracted from it. A contour is a `kind`: \"path\", \"circle\", \"rect\", or \"polygon\". Path segments run head-to-tail from `start`, and the contour closes implicitly from the last `to` back to `start`. y points UP. See docs/VECTOR-FORMAT.md.",
+  "source": "emblem.svg",
+  "bbox": {
+    "minX": 4,
+    "minY": -44,
+    "maxX": 44,
+    "maxY": -14
+  },
+  "shapes": {
+    "artwork": [
+      {
+        "outer": {
+          "kind": "path",
+          "start": [
+            14,
+            -24
+          ],
+          "segments": [
+            {
+              "kind": "arc",
+              "to": [
+                31.071068,
+                -31.071068
+              ],
+              "through": [
+                20.173166,
+                -33.238795
+              ]
+            },
+            {
+              "kind": "arc",
+              "to": [
+                24,
+                -14
+              ],
+              "through": [
+                33.238795,
+                -20.173166
+              ]
+            },
+            {
+              "kind": "arc",
+              "to": [
+                14,
+                -24
+              ],
+              "through": [
+                16.928932,
+                -16.928932
+              ]
+            }
+          ]
+        },
+        "holes": []
+      },
+      {
+        "outer": {
+          "kind": "path",
+          "start": [
+            6,
+            -40
+          ],
+          "segments": [
+            {
+              "kind": "arc",
+              "to": [
+                6,
+                -44
+              ],
+              "through": [
+                4,
+                -42
+              ]
+            },
+            {
+              "kind": "line",
+              "to": [
+                42,
+                -44
+              ]
+            },
+            {
+              "kind": "arc",
+              "to": [
+                42,
+                -40
+              ],
+              "through": [
+                44,
+                -42
+              ]
+            },
+            {
+              "kind": "line",
+              "to": [
+                6,
+                -40
+              ]
+            }
+          ]
+        },
+        "holes": []
+      }
+    ]
+  }
+}

package/src/parts/assets/plate.vector.json

@@ -0,0 +1,27 @@
+{
+  "format": "partforge-vector",
+  "version": 1,
+  "units": "mm",
+  "note": "Emblem backing plate. Drawn at 40 x 24 mm with M3 clearance holes on 28 mm centres and a keyway placed low, in the gap between the emblem artwork's disc and its bar, so it stays a real through-slot rather than getting capped by the emboss at the default emblem_w. Coordinates are millimetres and place as authored, so `body`, `holes`, and `keyway` share one frame — the cut in build lands where it is drawn.",
+  "shapes": {
+    "body": {
+      "role": "add",
+      "regions": [
+        { "outer": { "kind": "rect", "center": [0, 0], "width": 40, "height": 24, "radius": 4 } }
+      ]
+    },
+    "holes": {
+      "role": "subtract",
+      "regions": [
+        { "outer": { "kind": "circle", "center": [-14, 0], "r": 1.7 } },
+        { "outer": { "kind": "circle", "center": [14, 0], "r": 1.7 } }
+      ]
+    },
+    "keyway": {
+      "role": "subtract",
+      "regions": [
+        { "outer": { "kind": "polygon", "points": [[-3, -8], [3, -8], [0, -4]] } }
+      ]
+    }
+  }
+}

package/src/parts/emblem.js

@@ -0,0 +1,102 @@
+// The k.vector2d reference part — for BOTH paths the format supports: ingested
+// artwork (`emblem`, `units: "artwork"`, sized per call site) and an authored
+// 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 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.
+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),
+  },
+  parameters: [
+    {
+      id: "plate",
+      title: "Plate",
+      description: "The backing plate the artwork is embossed on. Its outline — including the bolt "
+        + "holes and keyway — is drawn in plate.vector.json, not parameterized.",
+      advanced: [
+        { key: "plate_t", label: "Thickness", unit: "mm", min: 1, max: 10, step: 0.5, description: "Plate thickness." },
+      ],
+    },
+    {
+      id: "art",
+      title: "Artwork",
+      description: "The embossed vector art. `emblem.svg` carries a filled circle and a stroked bar, so both of ingest's geometry paths are exercised.",
+      advanced: [
+        { key: "emblem_w", label: "Emblem width", unit: "mm", min: 8, max: 70, step: 1,
+          description: "Width of the artwork's **tight bounding box** in mm — not its `viewBox`. Stroke thickness scales with it." },
+        { key: "emboss", label: "Emboss height", unit: "mm", min: 0.4, max: 4, step: 0.2,
+          description: "How far the artwork stands proud of the plate." },
+      ],
+    },
+  ],
+  defaults: { plate_t: 3, emblem_w: 30, emboss: 1 },
+  parts: {
+    plate: {
+      label: "Plate",
+      views: ["plate"],
+      export: { name: "emblem-plate" },
+      // No shape named and no size: the file's own roles compose it (body minus
+      // holes minus keyway), and units "mm" places it exactly as drawn. A size
+      // HERE would be safe — the composed call measures the whole document at
+      // once — but it would also be pointless. What is not safe is fetching
+      // body/holes/keyway separately and sizing each call: each would scale
+      // against ITS OWN bounds, and the drawing's shared frame would be gone
+      // (ERROR-PATTERNS.md#vector-mm-shapes-misscaled). Millimetres place as
+      // authored; that is the whole point of the units mode.
+      // The keyway sits clear of the artwork at the default `emblem_w` (30) —
+      // confirmed by measurement, not eyeballed: their 2-D footprints have zero
+      // intersection. That clearance is deliberate, not incidental: a much
+      // larger `emblem_w` would grow the emboss until it overlaps the keyway's
+      // footprint again, and the union below would then cap it from above —
+      // a through-slot the drawing marks `role: "subtract"` quietly becoming a
+      // blind pocket. This is exactly the failure mode the `holes` gate below
+      // exists to catch, which is why that gate is only asserted at defaults.
+      build: (k, p) => k
+        .vector2d("plate")
+        .extrude({ h: p.plate_t })
+        .union(k.vector2d("emblem", { width: p.emblem_w }).extrude({ h: p.emboss }).translate([0, 0, p.plate_t])),
+    },
+  },
+  views: { plate: { label: "Plate" } },
+  verify: {
+    expect: {
+      plate: {
+        // Tight in all three axes, by the same +1 mm convention as
+        // import-demo.js's gates: verify evaluates the `defaults` case only
+        // (this part declares no presets), so bbox is checked against one
+        // deterministic value (40 x 24 x 4) forever, not a swept range —
+        // z = plate_t + emboss = 3 + 1 = 4 at these defaults specifically,
+        // not the schema's wider plate_t/emboss envelope. Revisit this bound
+        // if a preset is ever added that sweeps plate_t or emboss.
+        bbox: "<=[41,25,5]",
+        // Measured at defaults: 3013 mm^3 (`npx partforge measure`). The bare
+        // plate (no emboss union) is 2748 mm^3 — comfortably under this bound —
+        // so a silently-vanished emboss union fails here. Complemented by the
+        // `holes` gate below for the opposite failure (a cut that stops working
+        // raises volume, not lowers it, so this bound alone can't catch that).
+        volume: ">=2900",
+        watertight: true,
+        // Three through-holes: the two bolt circles, plus the keyway triangle —
+        // all cut clean through the extruded plate and, at this part's default
+        // `emblem_w`, none of them sit under the artwork's emboss (see the
+        // build comment above for why that placement matters). Confirmed with
+        // `npx partforge measure`, and falsified by temporarily flipping
+        // "holes"/"keyway" to role "add" in plate.vector.json (which drops
+        // this to 0, proving the gate can fail).
+        holes: 3,
+      },
+      _view: { overlaps: 0 },
+    },
+  },
+};

package/src/testing/manifold.js

@@ -6,10 +6,11 @@ import { createManifoldKernel } from "../framework/geometry/manifold-backend.js"
 import { resolveFonts } from "../framework/fonts.js";
 import { normalizeOpentype, parseFont } from "../framework/geometry/opentype-interop.js";
 import { ensureImports } from "../framework/imports.js";
+import { ensureVectors } from "../framework/vectors.js";
 import { nodeAssetSources } from "./assets.js";
 import { tessellateStepAssets } from "./step-mesh.js";
 
-export async function bootManifoldKernel({ quality = "preview", fonts, imports, importMeshes } = {}) {
+export async function bootManifoldKernel({ quality = "preview", fonts, imports, importMeshes, vectors } = {}) {
   const wasm = await Module();
   wasm.setup();
   const kernel = createManifoldKernel(wasm, { quality });
@@ -24,5 +25,6 @@ export async function bootManifoldKernel({ quality = "preview", fonts, imports,
     const meshes = importMeshes ?? (stepEntries.length ? await tessellateStepAssets(stepEntries) : null);
     await ensureImports(kernel, decl, meshes);
   }
+  if (vectors) await ensureVectors(kernel, nodeAssetSources(vectors));
   return kernel;
 }

package/src/testing/occt.js

@@ -8,9 +8,10 @@ import { createOcctKernel } from "../framework/geometry/occt-backend.js";
 import { resolveFonts } from "../framework/fonts.js";
 import { normalizeOpentype, parseFont } from "../framework/geometry/opentype-interop.js";
 import { ensureImports } from "../framework/imports.js";
+import { ensureVectors } from "../framework/vectors.js";
 import { nodeAssetSources } from "./assets.js";
 
-export async function bootOcctKernel({ fonts, imports, importMeshes } = {}) {
+export async function bootOcctKernel({ fonts, imports, importMeshes, vectors } = {}) {
   const require = createRequire(import.meta.url);
   globalThis.require = globalThis.require ?? require;
   globalThis.__dirname = globalThis.__dirname ?? path.dirname(fileURLToPath(import.meta.url));
@@ -22,5 +23,6 @@ export async function bootOcctKernel({ fonts, imports, importMeshes } = {}) {
   if (fonts) { const opentype = normalizeOpentype(await import("opentype.js"));
     for (const [name, buf] of await resolveFonts(nodeAssetSources(fonts))) kernel._fonts.set(name, parseFont(opentype, buf, name)); }
   if (imports) await ensureImports(kernel, nodeAssetSources(imports), importMeshes ?? null);
+  if (vectors) await ensureVectors(kernel, nodeAssetSources(vectors));
   return kernel;
 }

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`. */