partforge 0.86.0 → 0.88.0

package/docs/AUTHORING-PARTS.md

@@ -1770,7 +1770,7 @@ framing offscreen at a resolution independent of the window size and devicePixel
 for gallery/preview images, where grabbing the live canvas would be capped at the viewer
 pane's pixel size:
 
-- `runtime.captureCurrent({ size = 2048, hideGrid = true, quality = 0.9 } = {}) → string | null` —
+- `runtime.captureCurrent({ size = 2048, hideGrid = true, quality = 0.9, recenter = false } = {}) → string | null` —
   one offscreen render from the live camera's pose (position, up, and orbit target — not a
   canonical pose) with the live viewport's aspect ratio, `size` px on the long edge
   (clamped into `[256, maxTextureSize]`). Renders with 4× MSAA and the same
@@ -1783,6 +1783,16 @@ pane's pixel size:
   in the scene, so a dimensioned capture needs no special handling — enable measure
   mode (`runtime.measure.setEnabled(true)`) and call `captureCurrent()`; the dims are
   just part of the rendered frame.
+  `recenter: true` centres the part: the capture becomes the largest centred
+  sub-window of the current framing that still holds every visible vertex (equal
+  margins on both axes, rendered at the full `size` resolution through a view
+  offset, so it is a pixel-exact crop of what the user framed — same
+  perspective, no re-encode). The extent is the projection of the actual mesh
+  vertices, not a bounding box, so it is exact at any angle. The framing is
+  kept as-is when the geometry runs past any frame edge (a user who zoomed in
+  past the part's silhouette cropped it on purpose), when it is already centred,
+  or when measurement dimensions are pinned (their labels sit beside the part and
+  could otherwise be cut off).
 - `runtime.captureViews(viewNames) → [{ view, dataUrl }]` — the canonical-angle
   counterpart (fixed poses, framed to the visible assembly, 1024², grid hidden). Sized
   for feeding a vision model, not for display; use `captureCurrent` for showcase images.
@@ -1800,7 +1810,7 @@ button are hidden while Sketch (annotate) mode is active, but that only governs
 The ink is a transparent overlay and the WebGL canvas keeps rendering beneath
 it, so a host that calls `runtime.projection.set()` mid-sketch **visibly
 re-frames the 3D view underneath ink the user may still be drawing**: the
-strokes stay where they were laid down while the model shifts out from under
+elements stay where they were laid down while the model shifts out from under
 them, and the sketch that gets sent is misaligned, not merely mis-labelled.
 Deliberately unguarded, the same way it's always been free to call
 `setCameraState` during Sketch.
@@ -1811,10 +1821,46 @@ Deliberately unguarded, the same way it's always been free to call
 (replays exactly against the build that produced it) and `parts` (pinned to
 the CAD geometry, so it survives a later rebuild's bbox recentring; reread a
 sketch's camera intrinsics from `parts`, not `world`, once the model has been
-rebuilt). `ANNOTATION_VERSION` is **2**: both frames carry
+rebuilt). `ANNOTATION_VERSION` is **3**: both frames carry
 `projection: "perspective" | "orthographic"`, and under an orthographic camera
 `fov` is `null` while `orthoHeight` gives the frustum's world height instead.
-(v1 had `fov` only, and predates the projection toggle.)
+(v1 had `fov` only, and predates the projection toggle; v3 replaced the
+payload's `strokes` array with `elements` — typed pen/line/rect/ellipse
+shapes rather than raw ink paths — a change orthogonal to this camera block.)
+The payload is self-describing for LLM consumers: a top-level `summary` joins
+every element's plain-language `description`, and `frames` is a legend mapping
+each payload path to its coordinate convention (element `params` are
+stage-space, anchor `screen`s are per-axis normalized 0..1, descriptions are
+viewport percentages — `viewport.aspect` bridges them). Each element carries an
+`id` (`"e1"`, `"e2"`, …) for unambiguous reference in replies, `rotDeg`
+alongside the radian `rot`, and erased spans rendered into the description in
+each type's own vocabulary ("erased top edge", "erased arc 36°–126°"); each
+anchor of a gapped element carries the `run` index of the visible fragment it
+sits on.
+
+**Reconstructing rays from a sketch payload.** Every anchor also carries
+`ray: { origin, dir }` — a pick ray in the **parts frame** (mm origin, unit
+direction), computed from the live camera at send time and rounded to 4
+decimals; it is omitted when `camera.parts` is `null` (no meshes at send
+time — the same condition under which no `hit` can exist). Unlike `hit`,
+the ray is present even where the stroke crosses empty space, so any anchor
+can be projected onto a construction plane. For screen points that have no
+anchor (a circle's rim, a grid over a region), `partforge/oracle` exports
+`annotationRay(payload, screenOrAnchor, { frame? })` — the same ray,
+reconstructed from the payload's camera block (perspective and orthographic
+both) — and `rayPlane(ray, plane)` intersects either kind of ray with
+`{ point, normal }` or the shorthand origin planes `"xy" | "yz" | "zx"`,
+returning `{ point, t }` in mm or `null` on a parallel / behind-origin miss
+(the same miss semantics as `hit: null`). End to end:
+
+```js
+import { annotationRay, rayPlane } from "partforge/oracle";
+const anchor = payload.elements.find((e) => e.id === "e3")
+  .anchors.find((a) => a.at === "center");
+const hit = rayPlane(anchor.ray ?? annotationRay(payload, anchor), "xy");
+// → boss where the sketched circle's center points, on the z=0 plane:
+//   k.prism({ points: circleProfile(r_mm, [hit.point[0], hit.point[1]]), h })
+```
 
 **The markup convention (`demo.html` is the canonical copy-me page):** `<body>` carries
 `class="pf-shell"`, the flex row that lays the viewer column next to the rail. `#app`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.86.0",
+  "version": "0.88.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/annotate/annotate-controls.js

@@ -1,16 +1,16 @@
-// Viewbar chrome for annotation mode: the pencil toggle + contextual actions
-// (Undo / Clear / Send) shown while the mode is on. A direct sibling of
-// measure-controls.js — same no-op-without-button contract, same attribute
-// restore discipline on detach. The mode object (annotate-mode.js) owns all
-// behavior; this file only puts it on screen. One extra contract: a host whose
-// markup HAS the button but whose mount passed no onAnnotationSend gets the
-// button hidden entirely (spec: no dead Send) — mount passes mode = null.
+// Viewbar chrome for annotation mode: just the pencil toggle. A direct
+// sibling of measure-controls.js — same no-op-without-button contract, same
+// attribute restore discipline on detach. The mode object (annotate-mode.js)
+// owns all behavior; this file only puts the toggle on screen. One extra
+// contract: a host whose markup HAS the button but whose mount passed no
+// onAnnotationSend gets the button hidden entirely (spec: no dead toggle) —
+// mount passes mode = null.
 //
-// `send: "host"` drops the Send button from the row and leaves Undo/Clear.
-// It is for a host that draws its own send affordance (partforge-cloud pairs
-// the sketch with a typed prompt in its own composer, then calls
-// runtime.annotate.send()) — two Send buttons in two places, one of which
-// ignores the typed message, is the failure this avoids.
+// The Undo/Clear/Send actions that used to live in a row beside this button
+// moved to the sketch toolbar (sketch-toolbar.js, spec 2026-08-27) — the
+// toolbar OWNS the top of the stage while sketch mode is on, replacing the
+// whole viewbar rather than sharing it. This file no longer knows about
+// Undo/Clear/Send at all.
 import { attachButtonTooltips } from "../tooltip.js";
 import { runCleanupSteps, captureAttributes, restoreAttributes } from "../teardown.js";
 
@@ -19,7 +19,7 @@ const PENCIL_ICON = `<svg viewBox="0 0 24 24" width="16" height="16" fill="none"
 
 const noop = () => {};
 
-export function attachAnnotateControls(viewer, mode, { annotate: button } = {}, { tooltip, escapeScope, send = "viewbar" } = {}) {
+export function attachAnnotateControls(viewer, mode, { annotate: button } = {}, { tooltip, escapeScope } = {}) {
   if (!button) return { detach: noop };
 
   const hostAttributes = captureAttributes(button, BUTTON_ATTRIBUTES);
@@ -42,33 +42,8 @@ export function attachAnnotateControls(viewer, mode, { annotate: button } = {},
   button.setAttribute("aria-pressed", "false");
   if (!tooltip && !button.hasAttribute("title")) button.title = "Sketch";
 
-  const actions = document.createElement("span");
-  actions.className = "pf-annotate-actions";
-  const undoButton = document.createElement("button");
-  undoButton.type = "button";
-  undoButton.textContent = "Undo";
-  undoButton.title = "Remove the last stroke";
-  undoButton.setAttribute("aria-label", "Remove the last stroke");
-  const clearButton = document.createElement("button");
-  clearButton.type = "button";
-  clearButton.textContent = "Clear";
-  clearButton.title = "Remove all strokes";
-  clearButton.setAttribute("aria-label", "Remove all strokes");
-  let sendButton = null;
-  if (send !== "host") {
-    sendButton = document.createElement("button");
-    sendButton.type = "button";
-    sendButton.className = "pf-annotate-send";
-    sendButton.textContent = "Send";
-    sendButton.title = "Send the annotation";
-    sendButton.setAttribute("aria-label", "Send the annotation");
-  }
-  actions.append(...[undoButton, clearButton, sendButton].filter(Boolean));
-  button.after(actions);
-
-  const buttons = [button, undoButton, clearButton, sendButton].filter(Boolean);
   const tooltipBinding = tooltip
-    ? attachButtonTooltips(tooltip, buttons.map((element) => ({ element })))
+    ? attachButtonTooltips(tooltip, [{ element: button }])
     : null;
 
   function sync() {
@@ -76,18 +51,10 @@ export function attachAnnotateControls(viewer, mode, { annotate: button } = {},
     button.setAttribute("aria-pressed", String(on));
     button.setAttribute("aria-label", on ? "Stop sketching" : "Sketch");
     button.classList.toggle("on", on);
-    actions.hidden = !on;
-    const empty = mode.strokeCount() === 0;
-    undoButton.disabled = empty;
-    clearButton.disabled = empty;
-    if (sendButton) sendButton.disabled = empty;
     tooltipBinding?.sync();
   }
 
   const onToggle = () => { mode.setEnabled(!mode.isEnabled()); sync(); };
-  const onUndo = () => { mode.undo(); sync(); };
-  const onClear = () => { mode.clear(); sync(); };
-  const onSendClick = () => { mode.send(); sync(); };
   const onEscape = (event) => {
     if (event.key !== "Escape" || !mode.isEnabled()) return;
     event.preventDefault();
@@ -99,14 +66,10 @@ export function attachAnnotateControls(viewer, mode, { annotate: button } = {},
     sync();
     tooltipBinding?.hide();
   };
-  const offInk = mode.onInkChange(sync);
   const offMode = mode.onModeChange(sync);
 
   button.addEventListener("click", onToggle);
-  undoButton.addEventListener("click", onUndo);
-  clearButton.addEventListener("click", onClear);
-  sendButton?.addEventListener("click", onSendClick);
-  const escapeTargets = [escapeScope ?? viewer.domElement, ...buttons];
+  const escapeTargets = [escapeScope ?? viewer.domElement, button];
   for (const element of escapeTargets) element.addEventListener("keydown", onEscape);
   sync();
 
@@ -116,15 +79,10 @@ export function attachAnnotateControls(viewer, mode, { annotate: button } = {},
       if (detached) return;
       detached = true;
       runCleanupSteps([
-        offInk,
         offMode,
         () => button.removeEventListener("click", onToggle),
-        () => undoButton.removeEventListener("click", onUndo),
-        () => clearButton.removeEventListener("click", onClear),
-        () => sendButton?.removeEventListener("click", onSendClick),
         ...escapeTargets.map((element) => () => element.removeEventListener("keydown", onEscape)),
         () => tooltipBinding?.detach(),
-        () => actions.remove(),
         () => restoreAttributes(button, hostAttributes),
         () => { button.innerHTML = hostHtml; },
         () => button.classList.toggle("on", hostOn),