partforge 0.67.4 → 0.69.0

package/docs/AUTHORING-PARTS.md

@@ -1209,6 +1209,14 @@ Three rules worth internalizing before reaching for any of this:
   paper.js, which is cubic-only — an arc entering a boolean returns as a cubic
   approximation (relative error ~1e-6). `union`/`cut` first, `fillet` last keeps the
   rounded corners true circular arcs all the way to STEP export.
+- **A radius that doesn't fit is CLAMPED, not refused.** `fillet`/`chamfer` reduce any
+  corner whose magnitude its edges cannot hold down to the largest that they can, and
+  report each clamp on the build's warnings — so a slider that used to kill the part at
+  r=3.1 now rounds at whatever fits. Two ceilings apply: the corner's own edges, and
+  the edge it shares with a neighbouring selected corner (both back off together there).
+  It still throws when there is no feasible magnitude at all. **If an exact radius is
+  functionally required** — a bearing seat, a mating fit — do not trust the request:
+  clamp it yourself from the geometry that limits it, or assert it in `verify`.
 - **Run `validateProfile` after mutations.** `fillet`/`chamfer` check only their own
   corner's local fit — not whether the result self-intersects globally (a large radius
   on a narrow profile can produce arcs that cross the far side). `validateProfile`
@@ -2213,6 +2221,17 @@ radius self-intersects its cutters and yields a wrong shape rather than a skippe
 feature (OCCT skips instead). Clamp magnitudes against local geometry the way
 `filleted-box.js` does: `Math.min(p.fillet, halfWidth - 0.5, p.h - 0.5)`.
 
+**A defeated fillet/chamfer skips, and the build reports it.** On both backends a
+fillet or chamfer the geometry defeats does **not** fail the build: the op returns its
+input solid unchanged (edges left sharp) and the build result carries a feature-skip
+warning naming the op, its magnitude, and the reason. The same channel carries every
+other degrade — an `extrude` rim bevel reduced or left square, a `roundedBox` rim
+clamped to `round.side`, a `Shape2D` corner rounded smaller than asked — so the part on screen is real,
+minus that one feature, with everything downstream of it still applied. When a build
+answer includes such a warning, treat it as a failed feature, not a success: say so,
+and either adjust the geometry/radius and retry or leave the feature off deliberately.
+Do not conclude a fillet landed just because the build succeeded.
+
 **Preview routing is per sub-part.** Each sub-part is probed and routed independently, and
 a mixed part's regen fans out to both workers in parallel — a shelled body pays for OCCT
 while a plain lid rebuilds at Manifold speed beside it. Two scopes

package/docs/ERROR-PATTERNS.md

@@ -81,11 +81,11 @@ Variant literals under this entry: `extrude: unknown bevel option`, `extrude: be
 
 - **Symptom:** `partforge: extrude bevel` warning saying the requested distance `exceeds what the profile can take — reduced to` a smaller one (or `has no valid offset for this profile — rim left square`; `hole` in place of `profile` when a hole's flare is the limit).
 - **Cause:** Offsetting the rim by the bevel distance would pinch a narrow feature (a tooth land, a thin bar, a thin web beside a hole) shut, so the bevel deterministically backs off to the largest offset the outline can take — the same geometric limit OCCT's chamfer hits, resolved in pure JS instead of kernel re-runs.
-- **Fix:** Usually nothing — the reduced bevel is the correct maximum for the geometry. To silence it, clamp the bevel parameter below the printed value or widen the narrow feature.
+- **Fix:** Usually nothing — the reduced bevel is the correct maximum for the geometry. To silence it, clamp the bevel parameter below the printed value or widen the narrow feature. Since partforge 0.69 this warning also rides the build result's `warnings` (see [feature-skipped-warning](#feature-skipped-warning)), so a host or agent is told the rim was left square rather than having to read the console.
 
 ## roundedbox-rim-clamped
 
-- **Symptom:** `roundedBox: round.top <n> clamped to round.side <m> (side must be 0 or ≥ rim radii; use side: 0 for a rim-only round-over)` in the console, and the built rim round-over is smaller than the `round.top`/`round.bottom` you passed.
+- **Symptom:** `roundedBox: round.top <n> clamped to round.side <m> (side must be 0 or ≥ rim radii; use side: 0 for a rim-only round-over)` in the console — and, since partforge 0.69, on the build result's `warnings` (see [feature-skipped-warning](#feature-skipped-warning)) — with the built rim round-over smaller than the `round.top`/`round.bottom` you passed.
 - **Cause:** the middle regime `0 < side < rim` has no closed-form corner shared by both backends, so the rim radii clamp down to `side` (the footprint-defining radius never grows silently).
 - **Fix:** either raise `round.side` to ≥ the rim radii (torus/sphere corners), or set `side: 0` exactly for a full-size rim-only round-over on sharp vertical edges.
 
@@ -394,37 +394,44 @@ growing a shape past the hole's own width.
 - **Symptom:** `contour-winding: could not chain offset boundary (incomplete intersection
   set)` thrown from `Shape2D.offset` (or `offsetPolygon`) after a raw offset self-overlaps
   at a narrow pinch.
-- **Cause:** *(Known corpus fixed in partforge 0.60; ID retained permanently.)* The resolver
+- **Cause:** *(Known corpus fixed in partforge 0.60, fold-apex case in 0.68.1; ID retained
+  permanently.)* The resolver
   used to classify every boundary piece from one fixed midpoint probe. At a narrow cell that
   probe could cross a nearby non-incident edge, read the wrong winding on both sides, and
   drop a real continuation. Fully eroded round text counters were a separate upstream cause:
-  their raw offset could retain a negative pocket even under a correct Positive fill.
-- **Fix:** Upgrade to partforge ≥ 0.60. The classifier now chooses among deterministic
-  interior samples by local boundary clearance and caps its probe distance accordingly.
+  their raw offset could retain a negative pocket even under a correct Positive fill. A third
+  cause survived to 0.68.1: at a hairpin fold the antiparallel return branch is the probe
+  anchor's immediate ring neighbour, which the clearance measurement blanket-excluded as
+  incident geometry — the probe stepped across the fold and kept an interior piece
+  (italic-sheared whole-word text was the reproduction).
+- **Fix:** Upgrade to partforge ≥ 0.68.1. The classifier chooses among deterministic
+  interior samples by local boundary clearance, caps its probe distance accordingly, and
+  counts a fold-back neighbour edge (direction reversed against the anchor's) as an
+  obstruction rather than incident geometry.
   Positive round offsets also decide counter collapse from the source hole's inradius before
   generating a raw outline. On the committed 36,090-offset corpus
   (`node scripts/offset-rates.mjs`), chain failures before the retry ladder are
-  1 round / 2 chamfer / 4 sharp and **zero remain after it**; the full glyph matrix,
+  0 round / 1 chamfer / 1 sharp and **zero remain after it**; the full glyph matrix,
   including `"Scott"` through +3, has no throw or topology divergence.
 
   The literal error remains intentionally loud if a new pathological arrangement defeats
-  every retry rung. If it appears on ≥0.60, report the profile, delta, and corner style so it
+  every retry rung. If it appears on ≥0.68.1, report the profile, delta, and corner style so it
   can become a deterministic fixture. Reducing `|delta|` or simplifying nearly coincident
   features is a temporary workaround; changing corner style is not a reliable general fix.
 
 ## fillet-chamfer-radius-does-not-fit
 
-- **Symptom:** `filletProfile: corner <i> at (<x>, <y>): r=<r> does not fit; max ≈ <m>` (or `chamferProfile: … dist=<d> does not fit; max ≈ <m>`) thrown from `Shape2D.fillet`/`.chamfer` or the free `filletProfile`/`chamferProfile` functions.
+- **Symptom:** *(partforge ≥ 0.69 — a WARNING, no longer a throw.)* `filletProfile: corner <i> at (<x>, <y>): r=<r> does not fit — clamped to <m>` (or `chamferProfile: … dist=<d> does not fit — clamped to <m>`) from `Shape2D.fillet`/`.chamfer` or the free `filletProfile`/`chamferProfile` functions, and the corner comes back rounded at `<m>` rather than at what was asked for.
 - **Cause:** The requested radius/distance exceeds what the corner's adjacent edges (or curved neighbor) can hold before the tangent point runs past the segment's own end.
-- **Fix:** Use the reported `max ≈` value, or narrow `opts.corners` to skip that corner. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Editing profiles".
+- **Fix:** Usually nothing — the clamp is the designed degrade, and `<m>` is the largest magnitude that corner can hold. It throws only when a corner admits **no** valid magnitude at all. If the exact radius is functionally required (a bearing seat, a mating fit), the part must give the corner longer edges or select fewer corners; assert it in a `verify` block rather than trusting the request. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Editing profiles".
 
-Variant literal for a curve-adjacent corner (note the semicolon form, not parenthesized): `filletProfile: corner <i> at (<x>, <y>): could not fit r=<r> against the curved segment; max ≈ <m>` (`chamferProfile: … could not fit dist=<d> against the curved segment; max ≈ <m>` for chamfer).
+Variant literal for a curve-adjacent corner: `filletProfile: corner <i> at (<x>, <y>): r=<r> does not fit against the curved segment — clamped to <m>` (`chamferProfile: … dist=<d> …` for chamfer). Its ceiling is bisected rather than closed-form, and the residual throw (`could not fit r=<r> against the curved segment; max ≈ <m>`) survives for a corner where the solver finds no valid radius at all.
 
 ## fillet-chamfer-corners-overlap
 
-- **Symptom:** `filletProfile: corners <i> and <j> overlap on segment <k> (reduce r)` (or the same from `chamferProfile`).
+- **Symptom:** *(partforge ≥ 0.69 — normally a WARNING now.)* `filletProfile: corner <i>: r=<r> overruns the edge it shares with a neighbouring corner — clamped to <m>`. The throw `filletProfile: corners <i> and <j> overlap on segment <k> (reduce r)` survives only as a backstop, when eight successive back-off passes still cannot fit the pair.
 - **Cause:** Two adjacent selected corners each claim more of the edge between them than it has — their combined setbacks exceed the segment's length (or curved arc-length span).
-- **Fix:** Reduce `r`/`dist`, or fillet/chamfer only one of the two corners (drop the other from `opts.corners`). See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Editing profiles".
+- **Fix:** Usually nothing — both corners are scaled down until they fit (exactly, in one step, on a straight shared edge; geometrically on a curved one). Fillet/chamfer only one of the two corners if you would rather keep the other's full radius. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Editing profiles".
 
 ## profile-query-needs-single-contour
 
@@ -585,6 +592,15 @@ between the Manifold preview and the OCCT STEP export.
 - **Symptom:** A Manifold-built fillet/chamfer produces a mangled or over-cut shape (no error), where the same part on OCCT would skip the feature with a `fillet(…) failed` warning.
 - **Cause:** The mesh fillet does not validate radius feasibility — a magnitude larger than the local geometry self-intersects its cutter solids and the booleans happily apply them.
 - **Fix:** Clamp the magnitude against local dimensions in the part (`Math.min(p.fillet, halfWidth - 0.5, …)` — see `src/parts/filleted-box.js`), which is required practice on the mesh class per [KERNEL-CONTRACT.md](KERNEL-CONTRACT.md) § "Mesh degrade policy".
+
+## feature-skipped-warning
+
+- **Symptom:** The build succeeds but its result carries a warning like `fillet 1.15 failed (<reason>) — feature skipped, edges left sharp` (mesh backend), or `fillet(2) failed (…) — feature skipped` / `chamfer 3 over-ran the geometry — reduced to …` (OCCT repair policy), and the rendered part is missing the blend.
+- **Cause:** *(partforge ≥ 0.69.)* A fillet/chamfer the geometry (or its own selector) defeats no longer fails the whole build on either backend: the op returns its input solid unchanged, everything downstream still applies, and the skip is recorded on the build result's `warnings` (`kernel.takeBuildWarnings()` / the `meshes` message's `warnings: [{part, message}]`).
+- **Fix:** Read the parenthesized reason. A bad selector (unknown plane, wrong `at` height) is a part bug — fix the selector. A geometry-defeated blend usually wants a smaller magnitude or simpler input (clamp per the entry above), or the feature deliberately left off. Treat the warning as "this feature did not land", never as a cosmetic note — the shape on screen genuinely lacks it.
+
+  The same channel carries every other degrade in a build: an `extrude` rim bevel reduced or skipped (`extrude bevel <b> …`), a `roundedBox` rim radius clamped to `round.side`, and the `Shape2D` corner-op clamps in the two entries above. A build result's `warnings` is the complete list of what the part asked for and did not get.
+
 # Hardware library
 
 Reserved for `hardware-*` patterns (issue #30). No entries yet.

package/docs/KERNEL-CONTRACT.md

@@ -396,14 +396,43 @@ garbage). A failing chamfer instead binary-searches the largest valid distance.
 conforming B-rep kernel must degrade this way — a fillet request must never brick the
 build, and authors should expect all-or-nothing filleting per call, not per edge.
 
-**Mesh degrade policy** (`mesh-fillet.js`): the mesh class degrades by *rerouting*, not
-skipping — an unsupported edge class or an empty selection throws
-`KernelCapabilityError` and the framework retries the build on the B-rep kernel, which
-then applies its own repair policy. One asymmetry is deliberate: the mesh class does
-**not** validate radius feasibility (an oversized radius yields self-intersecting tools
-and a wrong shape rather than a skipped feature), so parts should clamp magnitudes
-against local geometry the way `filleted-box.js` does — good practice on both classes,
-mandatory on this one.
+**Mesh degrade policy** (`mesh-fillet.js` + `manifold-backend.js`): an unsupported edge
+class or a function selector *reroutes* — it throws `KernelCapabilityError` and the
+framework retries the build on the B-rep kernel, which then applies its own repair
+policy. Every other fillet/chamfer failure on the mesh class (a geometry-defeated
+blend, a selector naming an unknown plane, an empty selection error from the machinery)
+now **skips like the B-rep policy**: the op returns its input solid unchanged and
+records a feature-skip warning instead of failing the build. One asymmetry is
+deliberate: the mesh class does **not** validate radius feasibility (an oversized
+radius yields self-intersecting tools and a wrong shape rather than a skipped feature),
+so parts should clamp magnitudes against local geometry the way `filleted-box.js`
+does — good practice on both classes, mandatory on this one.
+
+**2-D corner-op policy** (`contour-ops.js`, partforge 0.69): `Shape2D.fillet`/`.chamfer`
+— and the free `filletProfile`/`chamferProfile` — **CLAMP** a magnitude the geometry
+cannot take rather than throwing. Two ceilings apply, and both were already computed
+for the error messages this replaces: a per-corner one (closed-form for a line-line
+corner, bisected for a curve-adjacent one) and a shared-edge one where two selected
+corners claim the same segment, resolved by scaling both until they fit — exactly in
+one step on a straight edge, geometrically on a curved one, bounded at 8 passes. Each
+clamp is reported through the warnings channel. It still throws where there is no
+feasible magnitude at all: a corner the curve solver cannot fit at any radius, a
+selector matching no corner, and a shared edge still overlapping after the pass bound.
+A conforming implementation must not silently return the requested magnitude.
+
+**Feature-skip warnings channel** (both backends, partforge 0.69): every skipped,
+clamped, or rescued feature is recorded on the kernel and drained with
+`kernel.takeBuildWarnings()`. The full set: a mesh fillet/chamfer that returned its
+input, occt-repair's skip/bisection rescues, a `roundall-skipped`, an `extrude` rim
+bevel reduced or left square, a `roundedBox` rim radius clamped to `round.side`, and
+a `Shape2D.fillet`/`.chamfer` corner clamped to what its edges can hold. Backend-neutral
+helpers reach the recorder through the kernel's internal `_recordWarning`, so there is
+one list per build rather than one per subsystem. The worker job layer (`jobs.js`) drains per
+sub-part and attaches `warnings: [{part, message}]` to the `meshes` /
+`capture-meshes` result when any were recorded, so a host can tell its user (or its
+agent) that the part on screen is missing a feature it asked for. A skipped op still
+console.warns as before; the channel is additive. Hosts that ignore the field see
+exactly the old behavior.
 
 ## Shape2D (2-D booleans)
 
@@ -530,13 +559,14 @@ delta.
 
 **Measured failure surface.** The committed instrument is
 `node scripts/offset-rates.mjs`, over 600 deterministic seeded shapes plus six glyph cases,
-20 deltas, and three corner styles (36,090 attempts). In partforge 0.60 it reports:
+20 deltas, and three corner styles (36,090 attempts). In partforge 0.68.1 (after the
+fold-aware clearance fix in the winding classifier) it reports:
 
-- before the retry ladder: round 1/12,030 (0.008%), chamfer 2/12,030 (0.017%), sharp
-  4/12,030 (0.033%);
+- before the retry ladder: round 0/12,030, chamfer 1/12,030 (0.008%), sharp
+  1/12,030 (0.008%);
 - after the retry ladder: zero chain-incomplete failures for all three styles;
-- seven oracle-checked rescues, with median area error 0.0972%, worst 1.663%
-  (2.2373 mm²), zero region-count losses, and zero complete arc losses.
+- two oracle-checked rescues, with median area error 0.0727%, worst 0.073%
+  (0.0720 mm²), zero region-count losses, and zero complete arc losses.
 
 The ladder remains a numerical escape hatch: it perturbs delta by 1e-9, coarsens crossing
 clustering, then tries polyline outlines. A future case that reaches a coarse clustering or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.67.4",
+  "version": "0.69.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/app-demo.js

@@ -14,4 +14,8 @@ import { mount } from "./framework/index.js";
 window.__pfRuntime = mount(demoPart, {
   createWorker: (name) =>
     new Worker(new URL("./demo-worker.js", import.meta.url), { type: "module", name }),
+  onAnnotationSend: (payload) => {
+    window.__pfLastAnnotation = payload;
+    console.log("annotation payload", payload);
+  },
 });

package/src/framework/annotate/annotate-controls.js

@@ -0,0 +1,134 @@
+// 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.
+//
+// `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.
+import { attachButtonTooltips } from "../tooltip.js";
+import { runCleanupSteps, captureAttributes, restoreAttributes } from "../teardown.js";
+
+const BUTTON_ATTRIBUTES = ["type", "aria-pressed", "aria-label", "title", "disabled", "hidden"];
+const PENCIL_ICON = `<svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21.174 6.812a1 1 0 0 0-3.986-3.987L3.842 16.174a2 2 0 0 0-.5.83l-1.321 4.352a.5.5 0 0 0 .623.622l4.353-1.32a2 2 0 0 0 .83-.497z"/><path d="m15 5 4 4"/></svg>`;
+
+const noop = () => {};
+
+export function attachAnnotateControls(viewer, mode, { annotate: button } = {}, { tooltip, escapeScope, send = "viewbar" } = {}) {
+  if (!button) return { detach: noop };
+
+  const hostAttributes = captureAttributes(button, BUTTON_ATTRIBUTES);
+  if (!mode) {
+    button.hidden = true;
+    let restored = false;
+    return {
+      detach() {
+        if (restored) return;
+        restored = true;
+        restoreAttributes(button, hostAttributes);
+      },
+    };
+  }
+  const hostHtml = button.innerHTML;
+  const hostOn = button.classList.contains("on");
+
+  button.type = "button";
+  button.innerHTML = PENCIL_ICON;
+  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 })))
+    : null;
+
+  function sync() {
+    const on = mode.isEnabled();
+    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();
+    // Consume the keystroke — same order-independence contract as
+    // measure-controls.js vs cutaway (which covers itself with escapeGuard;
+    // mount extends that guard to include annotate).
+    event.stopImmediatePropagation();
+    mode.setEnabled(false);
+    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];
+  for (const element of escapeTargets) element.addEventListener("keydown", onEscape);
+  sync();
+
+  let detached = false;
+  return {
+    detach() {
+      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),
+      ], "annotate control cleanup failed");
+    },
+  };
+}

package/src/framework/annotate/annotate-mode.js

@@ -0,0 +1,165 @@
+// Annotation-mode orchestrator — the one annotate module touching both the DOM
+// and the viewer (the measure-mode.js stance). Owns pointer→ink, the mode
+// lifecycle, and payload assembly. The overlay canvas is lazy-created on first
+// enable and kept across toggles; INK is not — exiting the mode discards it,
+// because screen-space ink is only meaningful against the camera pose it was
+// drawn over (deliberately unlike measure pins).
+import * as THREE from "three";
+import { createInkStore, anchorSpecs, DEFAULT_STROKE_WIDTH } from "./ink.js";
+import { createInkCanvas } from "./ink-canvas.js";
+import { raycastViewer } from "../selection/raycast.js";
+
+export const ANNOTATION_VERSION = 1;
+// Long-edge bound on BOTH pictures in the payload. The ink canvas is stage
+// sized × devicePixelRatio, so an unbounded send on a large hi-DPI display
+// hands the host a multi-megabyte pair of base64 strings — slow to encode,
+// and past the ceiling a host that ships them anywhere has to enforce. 2048
+// is captureCurrent's own default and comfortably above what any reviewer
+// (human or model) reads a sketch at; a smaller stage exports at its own size
+// and pays nothing.
+const SEND_MAX_EDGE = 2048;
+
+export function createAnnotateMode(viewer, { stage, getContext, onSend, createCanvas = createInkCanvas } = {}) {
+  const ink = createInkStore();
+  let canvas = null; // lazy; created on first enable
+  let enabled = false;
+  let drawing = false;
+  const modeListeners = new Set();
+  const notifyMode = () => { for (const cb of [...modeListeners]) cb(); };
+  const offInk = ink.onChange(() => canvas?.setStrokes(ink.strokes()));
+
+  const rectOf = () => canvas.element.getBoundingClientRect();
+  const normalized = (event, rect) => [
+    Math.min(1, Math.max(0, (event.clientX - rect.left) / rect.width)),
+    Math.min(1, Math.max(0, (event.clientY - rect.top) / rect.height)),
+  ];
+
+  // isPrimary === false (a second simultaneous touch) is ignored; undefined
+  // (plain MouseEvent, some test environments) draws normally.
+  const onPointerDown = (event) => {
+    if (event.isPrimary === false || drawing) return;
+    const rect = rectOf();
+    if (!rect.width || !rect.height) return;
+    drawing = true;
+    canvas.element.setPointerCapture?.(event.pointerId);
+    const [nx, ny] = normalized(event, rect);
+    ink.begin(nx, ny, { width: DEFAULT_STROKE_WIDTH, aspect: rect.width / rect.height });
+  };
+  const onPointerMove = (event) => {
+    if (!drawing || event.isPrimary === false) return;
+    const [nx, ny] = normalized(event, rectOf());
+    ink.extend(nx, ny);
+  };
+  const onPointerEnd = (event) => {
+    if (!drawing || event.isPrimary === false) return;
+    drawing = false;
+    ink.end();
+  };
+
+  function ensureCanvas() {
+    if (canvas) return;
+    canvas = createCanvas(stage);
+    canvas.element.addEventListener("pointerdown", onPointerDown);
+    canvas.element.addEventListener("pointermove", onPointerMove);
+    canvas.element.addEventListener("pointerup", onPointerEnd);
+    canvas.element.addEventListener("pointercancel", onPointerEnd);
+  }
+
+  function setEnabled(on) {
+    if (on === enabled) return;
+    enabled = on;
+    if (on) {
+      ensureCanvas();
+      canvas.show();
+    } else {
+      drawing = false;
+      ink.clear(); // spec: ink never survives an exit
+      canvas?.hide();
+    }
+    notifyMode();
+  }
+
+  // The camera pose in two frames. World replays exactly against THIS build;
+  // the parts frame (through the inverse of the shared parts parent's
+  // matrixWorld — the measure-mode idiom) stays pinned to the CAD geometry, so
+  // it survives the per-view bbox recentring when the model is rebuilt later.
+  function cameraBlock() {
+    const { pos, target } = viewer.getCameraState();
+    const world = { pos, target, up: viewer.camera.up.toArray(), fov: viewer.camera.fov };
+    const parent = Object.values(viewer._subMeshes ?? {})[0]?.parent ?? null;
+    if (!parent) return { world, parts: null };
+    parent.updateWorldMatrix(true, false);
+    const inv = parent.matrixWorld.clone().invert();
+    const map = (v) => new THREE.Vector3(v[0], v[1], v[2]).applyMatrix4(inv).toArray();
+    const up = new THREE.Vector3(world.up[0], world.up[1], world.up[2]).transformDirection(inv).toArray();
+    return { world, parts: { pos: map(world.pos), target: map(world.target), up, fov: world.fov } };
+  }
+
+  function send() {
+    if (!enabled || ink.isEmpty()) return false;
+    const rect = rectOf();
+    if (!rect.width || !rect.height) return false;
+    const { width, height, dpr } = canvas.size();
+    // Model render FIRST: on a lost WebGL context captureCurrent returns null
+    // and we abort with the ink intact — nothing is silently dropped.
+    const model = viewer.captureCurrent({ size: Math.min(Math.max(width, height), SEND_MAX_EDGE) });
+    if (!model) return false;
+    const strokes = ink.strokes();
+    const aspect = rect.width / rect.height;
+    const anchors = strokes.flatMap((stroke, index) =>
+      anchorSpecs(stroke.points, aspect).map((spec) => {
+        const hit = raycastViewer(
+          viewer,
+          rect.left + spec.screen[0] * rect.width,
+          rect.top + spec.screen[1] * rect.height,
+        );
+        return {
+          stroke: index,
+          ...(spec.kind ? { kind: spec.kind } : { t: spec.t }),
+          screen: spec.screen,
+          // a miss is kept as null — "circled empty space" is signal
+          hit: hit ? { subPart: hit.subPart, pointLocal: hit.pointLocal } : null,
+        };
+      }));
+    const { view, params } = getContext();
+    onSend?.({
+      version: ANNOTATION_VERSION,
+      strokes,
+      anchors,
+      images: { drawing: canvas.toDataUrl({ maxEdge: SEND_MAX_EDGE }), model },
+      camera: cameraBlock(),
+      viewport: { width: rect.width, height: rect.height, dpr },
+      context: { view, params: { ...params } },
+    });
+    setEnabled(false); // sent: exit and discard
+    return true;
+  }
+
+  let detached = false;
+  return {
+    setEnabled,
+    isEnabled: () => enabled,
+    undo: () => ink.undo(),
+    clear: () => ink.clear(),
+    strokeCount: () => ink.strokeCount(),
+    send,
+    onInkChange: (cb) => ink.onChange(cb),
+    onModeChange: (cb) => { modeListeners.add(cb); return () => modeListeners.delete(cb); },
+    detach() {
+      if (detached) return;
+      detached = true;
+      // Leave the state machine honest: a detach while enabled must not
+      // strand isEnabled() at true forever. Runs before listeners/canvas
+      // teardown below — setEnabled(false) notifies mode listeners and hides
+      // the canvas, both of which still need to be live for this call.
+      setEnabled(false);
+      offInk();
+      if (!canvas) return;
+      canvas.element.removeEventListener("pointerdown", onPointerDown);
+      canvas.element.removeEventListener("pointermove", onPointerMove);
+      canvas.element.removeEventListener("pointerup", onPointerEnd);
+      canvas.element.removeEventListener("pointercancel", onPointerEnd);
+      canvas.dispose();
+    },
+  };
+}

package/src/framework/annotate/ink-canvas.js

@@ -0,0 +1,129 @@
+// The annotation ink layer: a transparent 2D canvas stacked over the viewer
+// canvas (the first screen-space overlay canvas in the framework — everything
+// else that follows the model is in-scene, see dim3-scene.js). Appended to the
+// STAGE, not document.body, so it lives in .pf-stage's positioning context and
+// behaves under the narrow-pane layout. While visible it owns all pointer
+// events, which is what freezes orbit controls during annotation — no viewer
+// changes needed. Strokes render dark-core-over-light-halo so ink reads on
+// both themes and any model color.
+import { runCleanupSteps } from "../teardown.js";
+
+const CORE_COLOR = "#d92d20";
+const HALO_COLOR = "rgba(255, 255, 255, 0.85)";
+const HALO_RATIO = 2.2; // halo pass width relative to the core width
+
+export function createInkCanvas(stage, {
+  getContext2d = (canvas) => canvas.getContext("2d"),
+  createCanvas = () => document.createElement("canvas"),
+} = {}) {
+  const canvas = createCanvas();
+  canvas.className = "pf-ink-canvas";
+  canvas.hidden = true;
+  stage.appendChild(canvas);
+  const ctx = getContext2d(canvas);
+  let strokes = [];
+
+  // Strokes are normalized, so a pass is written against whatever bitmap it is
+  // handed — the live canvas, or the scratch one toDataUrl uses to bound an
+  // export. Width scales with the target's short edge for the same reason.
+  function drawPass(target, targetCtx, color, widthScale) {
+    targetCtx.strokeStyle = color;
+    targetCtx.fillStyle = color;
+    targetCtx.lineCap = "round";
+    targetCtx.lineJoin = "round";
+    const short = Math.min(target.width, target.height);
+    for (const stroke of strokes) {
+      const w = stroke.width * short * widthScale;
+      if (stroke.points.length === 1) {
+        const [nx, ny] = stroke.points[0];
+        targetCtx.beginPath();
+        targetCtx.arc(nx * target.width, ny * target.height, w / 2, 0, Math.PI * 2);
+        targetCtx.fill();
+        continue;
+      }
+      targetCtx.lineWidth = w;
+      targetCtx.beginPath();
+      stroke.points.forEach(([nx, ny], i) => {
+        const x = nx * target.width;
+        const y = ny * target.height;
+        if (i === 0) targetCtx.moveTo(x, y);
+        else targetCtx.lineTo(x, y);
+      });
+      targetCtx.stroke();
+    }
+  }
+
+  function drawInto(targetCtx, target) {
+    targetCtx.clearRect(0, 0, target.width, target.height);
+    drawPass(target, targetCtx, HALO_COLOR, HALO_RATIO);
+    drawPass(target, targetCtx, CORE_COLOR, 1);
+  }
+
+  function draw() {
+    if (!ctx) return;
+    drawInto(ctx, canvas);
+  }
+
+  function resize() {
+    const rect = stage.getBoundingClientRect();
+    const dpr = globalThis.devicePixelRatio || 1;
+    const width = Math.max(1, Math.round(rect.width * dpr));
+    const height = Math.max(1, Math.round(rect.height * dpr));
+    if (canvas.width !== width || canvas.height !== height) {
+      canvas.width = width;
+      canvas.height = height;
+    }
+    draw();
+  }
+
+  // The viewer's own ResizeObserver is internal (viewer.js exposes no resize
+  // hook), so the overlay runs its own — ink is normalized, so a resize is
+  // just a re-rasterize at the new bitmap size. Skip it while hidden: the
+  // stage keeps resizing (rail drags, window resizes) whether or not
+  // annotate mode is on, and re-rasterizing an invisible canvas is wasted
+  // work; show() already calls resize() so nothing is missed on re-entry.
+  const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => {
+    if (canvas.hidden) return;
+    resize();
+  });
+  observer?.observe(stage);
+
+  let disposed = false;
+  return {
+    element: canvas,
+    show() { canvas.hidden = false; resize(); },
+    hide() { canvas.hidden = true; },
+    setStrokes(next) { strokes = next; draw(); },
+    // The ink layer as a transparent PNG. `maxEdge` bounds the exported
+    // bitmap: the live canvas is stage-sized × devicePixelRatio, so on a large
+    // hi-DPI display it runs to several thousand pixels a side, and a PNG that
+    // big is both slow to encode and large enough that a host with a payload
+    // ceiling would have to drop it — losing the drawing while keeping the
+    // picture of the model, which is the one outcome worse than failing. Above
+    // the bound the strokes are re-rasterized into a scratch canvas rather than
+    // resampled, so thin ink stays crisp instead of turning to mush. Under it
+    // (the ordinary case) nothing is copied and the live canvas exports
+    // directly.
+    toDataUrl({ maxEdge } = {}) {
+      const long = Math.max(canvas.width, canvas.height);
+      if (!maxEdge || long <= maxEdge) return canvas.toDataURL("image/png");
+      const scale = maxEdge / long;
+      const scratch = createCanvas();
+      scratch.width = Math.max(1, Math.round(canvas.width * scale));
+      scratch.height = Math.max(1, Math.round(canvas.height * scale));
+      const scratchCtx = getContext2d(scratch);
+      if (!scratchCtx) return canvas.toDataURL("image/png");
+      drawInto(scratchCtx, scratch);
+      return scratch.toDataURL("image/png");
+    },
+    size: () => ({ width: canvas.width, height: canvas.height, dpr: globalThis.devicePixelRatio || 1 }),
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      runCleanupSteps([
+        () => observer?.disconnect(),
+        () => canvas.remove(),
+      ], "ink canvas cleanup failed");
+    },
+  };
+}