castle-web-cli 0.4.115 → 0.4.116

package/kits/physics-2d/editors/brushFit.js

@@ -0,0 +1,535 @@
+// Freehand brush → detented path vocabulary.
+// Pure functions (Node-testable). Constants are fixed / opinionated — no knobs.
+// Sibling spirit of scripts/import-svg.mjs bow fitting, but for sampled ink.
+
+import { bowToSegments, handlesForBow, magneticSnapPoint, snapBow, straightSegment, subpathVertexCount, LATTICE } from '../engine/pxartPath.js';
+
+// --- Tuned constants (each comment: what it does) ---
+
+/** Capture: skip a raw pointer sample closer than this (cells) to the previous. */
+export const DECIMATE_MIN_DIST = 0.05;
+
+/** Resample ink to this even arc-length spacing (cells) before corner/RDP/bow work. */
+export const RESAMPLE_SPACING = 0.1;
+
+/** Corner detection: look at turn over this arc-length window (cells). */
+export const CORNER_WINDOW = 1.0;
+
+/** Corner detection: mark a sample a corner when the local turn exceeds this (degrees). */
+export const CORNER_ANGLE_DEG = 60;
+
+/** Auto-close: endpoint must land within this distance (cells) of the start. */
+export const AUTO_CLOSE_DIST = 1.5;
+
+/** Auto-close: require at least this total ink length (cells) before closing. */
+export const AUTO_CLOSE_MIN_LENGTH = 4;
+
+/** Ramer–Douglas–Peucker: max deviation (cells) allowed from a chord when dropping samples. */
+export const RDP_TOLERANCE = 0.75;
+
+/** After lattice snap: drop anchors that leave a segment shorter than this (cells). */
+export const MIN_SEGMENT = 0.75;
+
+/** Reject the whole gesture when total ink length is under this (cells). */
+export const MIN_INK_LENGTH = 1.5;
+
+/** Bow fit: treat a span as straight when |raw sagitta| is below this (cells) before snap. */
+export const STRAIGHT_SAGITTA = 0.2;
+
+const CORNER_ANGLE_RAD = (CORNER_ANGLE_DEG * Math.PI) / 180;
+
+function dist(a, b) {
+  return Math.hypot(b[0] - a[0], b[1] - a[1]);
+}
+
+/** Append a raw pointer sample, skipping near-duplicates. Mutates and returns ink. */
+export function appendInkPoint(ink, x, y) {
+  if (!ink.length) {
+    ink.push([x, y]);
+    return ink;
+  }
+  const prev = ink[ink.length - 1];
+  if (Math.hypot(x - prev[0], y - prev[1]) < DECIMATE_MIN_DIST) return ink;
+  ink.push([x, y]);
+  return ink;
+}
+
+/** Polyline arc length. */
+export function inkLength(points) {
+  let len = 0;
+  for (let i = 1; i < points.length; i++) len += dist(points[i - 1], points[i]);
+  return len;
+}
+
+/** Resample to roughly even arc-length spacing. */
+export function resampleInk(points, spacing = RESAMPLE_SPACING) {
+  if (!points?.length) return [];
+  if (points.length === 1) return [[points[0][0], points[0][1]]];
+  const total = inkLength(points);
+  if (total < 1e-12) return [[points[0][0], points[0][1]]];
+  const out = [[points[0][0], points[0][1]]];
+  let acc = 0;
+  let nextAt = spacing;
+  for (let i = 1; i < points.length; i++) {
+    const a = points[i - 1];
+    const b = points[i];
+    const seg = dist(a, b);
+    if (seg < 1e-12) continue;
+    let t0 = 0;
+    while (acc + seg * (1 - t0) >= nextAt - 1e-12) {
+      const need = nextAt - acc;
+      const t = t0 + need / seg;
+      out.push([a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t]);
+      nextAt += spacing;
+      t0 = t;
+    }
+    acc += seg * (1 - t0);
+  }
+  const last = points[points.length - 1];
+  const tip = out[out.length - 1];
+  if (dist(tip, last) > spacing * 0.25) out.push([last[0], last[1]]);
+  else {
+    tip[0] = last[0];
+    tip[1] = last[1];
+  }
+  return out;
+}
+
+/**
+ * Indices into `samples` that are intentional corners.
+ * Endpoints of an open gesture are always corners. Closed: wrap-aware turns only
+ * (the join is not double-counted as an endpoint pair).
+ */
+export function detectCorners(samples, closed) {
+  const n = samples.length;
+  if (n === 0) return [];
+  if (n === 1) return [0];
+  if (n === 2) return closed ? [0] : [0, 1];
+
+  const half = CORNER_WINDOW / 2;
+  const flags = new Array(n).fill(false);
+  if (!closed) {
+    flags[0] = true;
+    flags[n - 1] = true;
+  }
+
+  // Prefix arc lengths for window lookups.
+  const arc = new Array(n).fill(0);
+  for (let i = 1; i < n; i++) arc[i] = arc[i - 1] + dist(samples[i - 1], samples[i]);
+  const total = closed ? arc[n - 1] + dist(samples[n - 1], samples[0]) : arc[n - 1];
+
+  function lerpAlong(a, b, u) {
+    return [a[0] + (b[0] - a[0]) * u, a[1] + (b[1] - a[1]) * u];
+  }
+
+  function sampleOnOpenArc(t) {
+    for (let i = 1; i < n; i++) {
+      if (arc[i] >= t) {
+        const a0 = arc[i - 1];
+        return lerpAlong(samples[i - 1], samples[i], (t - a0) / (arc[i] - a0 || 1e-12));
+      }
+    }
+    return [samples[n - 1][0], samples[n - 1][1]];
+  }
+
+  function sampleAtArc(target) {
+    if (!closed) return sampleOnOpenArc(Math.max(0, Math.min(total, target)));
+    let t = ((target % total) + total) % total;
+    if (t <= arc[n - 1]) return sampleOnOpenArc(t);
+    const a0 = arc[n - 1];
+    return lerpAlong(samples[n - 1], samples[0], (t - a0) / (total - a0 || 1e-12));
+  }
+
+  const start = closed ? 0 : 1;
+  const end = closed ? n : n - 1;
+  for (let i = start; i < end; i++) {
+    const s = arc[i];
+    const prev = sampleAtArc(s - half);
+    const next = sampleAtArc(s + half);
+    const vx0 = samples[i][0] - prev[0];
+    const vy0 = samples[i][1] - prev[1];
+    const vx1 = next[0] - samples[i][0];
+    const vy1 = next[1] - samples[i][1];
+    const L0 = Math.hypot(vx0, vy0);
+    const L1 = Math.hypot(vx1, vy1);
+    if (L0 < 1e-9 || L1 < 1e-9) continue;
+    const dot = (vx0 * vx1 + vy0 * vy1) / (L0 * L1);
+    const ang = Math.acos(Math.max(-1, Math.min(1, dot)));
+    if (ang >= CORNER_ANGLE_RAD) flags[i] = true;
+  }
+
+  const idxs = [];
+  for (let i = 0; i < n; i++) if (flags[i]) idxs.push(i);
+  if (!idxs.length) idxs.push(0);
+  return idxs;
+}
+
+function pointLineDist(p, a, b) {
+  const dx = b[0] - a[0];
+  const dy = b[1] - a[1];
+  const L2 = dx * dx + dy * dy;
+  if (L2 < 1e-18) return dist(p, a);
+  const t = ((p[0] - a[0]) * dx + (p[1] - a[1]) * dy) / L2;
+  const qx = a[0] + t * dx;
+  const qy = a[1] + t * dy;
+  return Math.hypot(p[0] - qx, p[1] - qy);
+}
+
+/** Open-polyline RDP; returns kept indices into `pts` (inclusive ends). */
+export function rdpIndices(pts, tol = RDP_TOLERANCE) {
+  const n = pts.length;
+  if (n <= 2) return n === 0 ? [] : n === 1 ? [0] : [0, 1];
+  const keep = new Array(n).fill(false);
+  keep[0] = true;
+  keep[n - 1] = true;
+  const stack = [[0, n - 1]];
+  while (stack.length) {
+    const [i0, i1] = stack.pop();
+    let maxD = 0;
+    let maxI = -1;
+    const a = pts[i0];
+    const b = pts[i1];
+    for (let i = i0 + 1; i < i1; i++) {
+      const d = pointLineDist(pts[i], a, b);
+      if (d > maxD) {
+        maxD = d;
+        maxI = i;
+      }
+    }
+    if (maxI >= 0 && maxD > tol) {
+      keep[maxI] = true;
+      stack.push([i0, maxI], [maxI, i1]);
+    }
+  }
+  const out = [];
+  for (let i = 0; i < n; i++) if (keep[i]) out.push(i);
+  return out;
+}
+
+/** Closed-loop RDP via a diameter split into two open halves. */
+function rdpClosedIndices(pts, tol = RDP_TOLERANCE) {
+  const n = pts.length;
+  if (n <= 2) return [...Array(n).keys()];
+  let maxD = 0;
+  let maxI = 1;
+  for (let i = 1; i < n; i++) {
+    const d = dist(pts[i], pts[0]);
+    if (d > maxD) {
+      maxD = d;
+      maxI = i;
+    }
+  }
+  const halfA = pts.slice(0, maxI + 1);
+  const halfB = pts.slice(maxI).concat([pts[0]]);
+  const idxA = rdpIndices(halfA, tol);
+  const idxB = rdpIndices(halfB, tol);
+  const set = new Set();
+  for (const i of idxA) set.add(i);
+  for (const i of idxB) {
+    const global = i < halfB.length - 1 ? maxI + i : 0;
+    set.add(global);
+  }
+  return [...set].sort((a, b) => a - b);
+}
+
+/**
+ * Signed sagitta of ink between two anchors: mean perpendicular deviation of
+ * mid-span samples from the chord (sign-correct, mirror-symmetric).
+ */
+export function fitBowForSpan(spanPts, a, b) {
+  const dx = b[0] - a[0];
+  const dy = b[1] - a[1];
+  const L = Math.hypot(dx, dy);
+  if (L < 1e-12) return 0;
+  const nx = -dy / L;
+  const ny = dx / L;
+  const mx = (a[0] + b[0]) / 2;
+  const my = (a[1] + b[1]) / 2;
+  if (!spanPts?.length) return 0;
+
+  // Prefer samples in the middle third of the span (by index).
+  const n = spanPts.length;
+  const i0 = Math.floor(n * 0.33);
+  const i1 = Math.max(i0 + 1, Math.ceil(n * 0.67));
+  let sum = 0;
+  let count = 0;
+  for (let i = i0; i < i1; i++) {
+    const p = spanPts[i];
+    sum += (p[0] - mx) * nx + (p[1] - my) * ny;
+    count++;
+  }
+  if (!count) {
+    const mid = spanPts[Math.floor(n / 2)];
+    sum = (mid[0] - mx) * nx + (mid[1] - my) * ny;
+    count = 1;
+  }
+  const raw = sum / count;
+  if (Math.abs(raw) < STRAIGHT_SAGITTA) return 0;
+  const bow = snapBow(raw, L);
+  if (bow !== 0 && !handlesForBow(a, b, bow)) return 0;
+  return bow;
+}
+
+function spanBetween(samples, i0, i1, closed) {
+  const n = samples.length;
+  if (!closed) return samples.slice(i0, i1 + 1);
+  if (i0 <= i1) return samples.slice(i0, i1 + 1);
+  return samples.slice(i0).concat(samples.slice(0, i1 + 1));
+}
+
+/**
+ * Snap anchors (pixel centers by default; half-cell lattice when halfPixel),
+ * merge coincidences, drop short edges.
+ * `cornerFlags[i]` marks anchors that must not lose to a non-corner neighbor.
+ */
+export function snapMergeCull(anchors, cornerFlags, halfPixel = false, cellPull = LATTICE / 2) {
+  if (!anchors.length) return { points: [], corners: [] };
+  let pts = anchors.map((p) => magneticSnapPoint(p[0], p[1], cellPull, halfPixel));
+  let corners = cornerFlags.map(Boolean);
+
+  // Merge consecutive duplicates (and wrap for later closed handling at caller).
+  const merged = [];
+  const mergedCorners = [];
+  for (let i = 0; i < pts.length; i++) {
+    const p = pts[i];
+    if (merged.length && dist(merged[merged.length - 1], p) < 1e-9) {
+      mergedCorners[mergedCorners.length - 1] =
+        mergedCorners[mergedCorners.length - 1] || corners[i];
+      continue;
+    }
+    merged.push(p);
+    mergedCorners.push(corners[i]);
+  }
+  pts = merged;
+  corners = mergedCorners;
+
+  // Drop short segments: never drop a corner in favor of a non-corner.
+  let changed = true;
+  while (changed && pts.length > 2) {
+    changed = false;
+    for (let i = 0; i < pts.length - 1; i++) {
+      if (dist(pts[i], pts[i + 1]) + 1e-12 >= MIN_SEGMENT) continue;
+      const drop = corners[i] && !corners[i + 1] ? i + 1 : !corners[i] && corners[i + 1] ? i : i + 1;
+      // Prefer dropping non-corners; if both corners, drop the later one.
+      const choice =
+        corners[i] === corners[i + 1] ? (corners[i] ? i + 1 : drop) : drop;
+      if (corners[choice] && !corners[choice === i ? i + 1 : i]) {
+        // Would drop corner for non-corner — skip this pair.
+        continue;
+      }
+      pts.splice(choice, 1);
+      corners.splice(choice, 1);
+      changed = true;
+      break;
+    }
+  }
+  return { points: pts, corners };
+}
+
+function autoClose(samples) {
+  if (samples.length < 2) return false;
+  const len = inkLength(samples);
+  if (len < AUTO_CLOSE_MIN_LENGTH) return false;
+  return dist(samples[0], samples[samples.length - 1]) <= AUTO_CLOSE_DIST;
+}
+
+function isValidResult(closed, start, segs) {
+  const n = subpathVertexCount({ closed, start, segs });
+  if (closed) {
+    if (n >= 3) return true;
+    if (n === 2) return (segs ?? []).some((s) => s.c1 || s.c2);
+    return false;
+  }
+  return n >= 2;
+}
+
+/**
+ * Fit raw freehand ink to a single subpath in the detented vocabulary.
+ * Returns null when the gesture is rejected (too short / invalid after fit).
+ * Does NOT assign fill/stroke — caller applies active palette key.
+ */
+export function fitBrushInk(rawInk, { halfPixel = false, cellPull = LATTICE / 2 } = {}) {
+  if (!rawInk?.length) return null;
+  const length = inkLength(rawInk);
+  if (length < MIN_INK_LENGTH) return null;
+
+  const samples = resampleInk(rawInk, RESAMPLE_SPACING);
+  if (samples.length < 2) return null;
+
+  let closed = autoClose(samples);
+  // When auto-closing, drop a trailing tip that sits on the start so the loop
+  // doesn't double-count the join; keep samples as an open ring for indexing.
+  let ring = samples;
+  if (closed && dist(samples[0], samples[samples.length - 1]) < RESAMPLE_SPACING * 0.5) {
+    ring = samples.slice(0, -1);
+    if (ring.length < 2) return null;
+  }
+
+  const cornerIdxs = detectCorners(ring, closed);
+  const cornerSet = new Set(cornerIdxs);
+
+  // Build ordered corner list around the ring.
+  let corners = [...cornerIdxs].sort((a, b) => a - b);
+  if (closed && corners.length === 0) corners = [0];
+  if (!closed) {
+    if (corners[0] !== 0) corners = [0, ...corners];
+    if (corners[corners.length - 1] !== ring.length - 1) corners = [...corners, ring.length - 1];
+    // dedupe
+    corners = [...new Set(corners)].sort((a, b) => a - b);
+  }
+
+  // Runs between consecutive corners (wrap if closed).
+  const runEnds = [];
+  if (closed) {
+    if (corners.length === 1) {
+      // Smooth closed blob: one circular run.
+      runEnds.push({ from: corners[0], to: corners[0], fullLoop: true });
+    } else {
+      for (let i = 0; i < corners.length; i++) {
+        const from = corners[i];
+        const to = corners[(i + 1) % corners.length];
+        runEnds.push({ from, to, fullLoop: false });
+      }
+    }
+  } else {
+    for (let i = 0; i < corners.length - 1; i++) {
+      runEnds.push({ from: corners[i], to: corners[i + 1], fullLoop: false });
+    }
+  }
+
+  // Simplify each run; collect global sample indices for anchors.
+  const anchorSampleIdx = new Set(corners);
+  for (const run of runEnds) {
+    let runPts;
+    let mapBack;
+    if (run.fullLoop) {
+      // Rotate so the sole corner is index 0, then closed RDP.
+      const rot = ring.slice(run.from).concat(ring.slice(0, run.from));
+      const kept = rdpClosedIndices(rot, RDP_TOLERANCE);
+      for (const k of kept) {
+        anchorSampleIdx.add((run.from + k) % ring.length);
+      }
+      continue;
+    }
+    if (run.from <= run.to) {
+      runPts = ring.slice(run.from, run.to + 1);
+      mapBack = (j) => run.from + j;
+    } else {
+      runPts = ring.slice(run.from).concat(ring.slice(0, run.to + 1));
+      mapBack = (j) => {
+        const after = ring.length - run.from;
+        return j < after ? run.from + j : j - after;
+      };
+    }
+    if (runPts.length < 2) continue;
+    const kept = rdpIndices(runPts, RDP_TOLERANCE);
+    for (const j of kept) anchorSampleIdx.add(mapBack(j));
+  }
+
+  let orderedIdx = [...anchorSampleIdx].sort((a, b) => a - b);
+  if (closed && orderedIdx.length >= 2) {
+    // Closed: do not keep a duplicate of start at the end.
+    // (ring is not closed with a repeated first point.)
+  }
+
+  let anchors = orderedIdx.map((i) => [ring[i][0], ring[i][1]]);
+  let isCorner = orderedIdx.map((i) => cornerSet.has(i));
+  // Endpoints of open paths are corners.
+  if (!closed && isCorner.length) {
+    isCorner[0] = true;
+    isCorner[isCorner.length - 1] = true;
+  }
+
+  const culled = snapMergeCull(anchors, isCorner, halfPixel, cellPull);
+  anchors = culled.points;
+  isCorner = culled.corners;
+
+  // Closed: merge first/last if they snapped together.
+  if (closed && anchors.length >= 2 && dist(anchors[0], anchors[anchors.length - 1]) < 1e-9) {
+    anchors.pop();
+    isCorner[0] = isCorner[0] || isCorner.pop();
+  }
+
+  // Short wrap edge on closed paths.
+  if (closed && anchors.length >= 2) {
+    while (anchors.length > 2 && dist(anchors[0], anchors[anchors.length - 1]) < MIN_SEGMENT) {
+      const last = anchors.length - 1;
+      if (isCorner[last] && !isCorner[0]) {
+        // drop first non-corner — rare; drop last if both corners
+        anchors.splice(last, 1);
+        isCorner.splice(last, 1);
+      } else if (!isCorner[last] && isCorner[0]) {
+        anchors.splice(last, 1);
+        isCorner.splice(last, 1);
+      } else if (!isCorner[last]) {
+        anchors.splice(last, 1);
+        isCorner.splice(last, 1);
+      } else {
+        break;
+      }
+    }
+  }
+
+  if (!anchors.length) return null;
+
+  // Map snapped anchors back onto ring indices for bow spans (nearest sample).
+  function nearestSampleIndex(p) {
+    let best = 0;
+    let bestD = Infinity;
+    for (let i = 0; i < ring.length; i++) {
+      const d = dist(ring[i], p);
+      if (d < bestD) {
+        bestD = d;
+        best = i;
+      }
+    }
+    return best;
+  }
+  const sampleForAnchor = anchors.map(nearestSampleIndex);
+
+  const edgeCount = closed ? anchors.length : Math.max(0, anchors.length - 1);
+  const segs = [];
+  for (let e = 0; e < edgeCount; e++) {
+    const a = anchors[e];
+    const b = anchors[(e + 1) % anchors.length];
+    const i0 = sampleForAnchor[e];
+    const i1 = sampleForAnchor[(e + 1) % sampleForAnchor.length];
+    const span = spanBetween(ring, i0, i1, closed);
+    const bow = fitBowForSpan(span, a, b);
+    segs.push(...bowToSegments(a, b, bow));
+  }
+
+  const start = [anchors[0][0], anchors[0][1]];
+  if (!isValidResult(closed, start, segs)) {
+    if (closed && anchors.length >= 2) {
+      closed = false;
+      const openSegs = segs.slice(0, Math.max(0, anchors.length - 1));
+      if (!isValidResult(false, start, openSegs)) return null;
+      return { closed: false, start, segs: openSegs };
+    }
+    return null;
+  }
+
+  return { closed, start, segs };
+}
+
+/** Build a stacked-shape object from a fit result + active palette key. */
+export function shapeFromBrushFit(fit, activeKey) {
+  if (!fit) return null;
+  // Always stroke + transparent fill (closed or open); fill is a separate toggle.
+  return {
+    fill: null,
+    stroke: activeKey,
+    subpaths: [
+      {
+        closed: !!fit.closed,
+        start: [fit.start[0], fit.start[1]],
+        segs: (fit.segs ?? []).map((s) => ({
+          to: [s.to[0], s.to[1]],
+          c1: s.c1 ? [s.c1[0], s.c1[1]] : undefined,
+          c2: s.c2 ? [s.c2[0], s.c2[1]] : undefined,
+        })),
+      },
+    ],
+  };
+}

package/kits/physics-2d/editors/brushShapes.js

@@ -0,0 +1,140 @@
+import { LATTICE, MIN_ELLIPSE_RADIUS, deriveShape, straightSegment } from '../engine/pxartPath.js';
+import { snapPenAnchor } from './pathTools.js';
+import { shapeBounds } from './pixelGeometry.js';
+
+const MIN_DRAG = 0.25;
+
+function snapPt(x, y, halfPixel, cellPull) {
+  return snapPenAnchor(x, y, halfPixel, cellPull);
+}
+
+/** Shift: square drag box from start, sized to the larger axis (sign preserved). */
+function constrainDragEnd(start, end) {
+  const dx = end.x - start.x;
+  const dy = end.y - start.y;
+  const side = Math.max(Math.abs(dx), Math.abs(dy));
+  if (side < MIN_DRAG) return end;
+  return {
+    x: start.x + Math.sign(dx || 1) * side,
+    y: start.y + Math.sign(dy || 1) * side,
+  };
+}
+
+/**
+ * Build a stroke-only path shape from a brush primitive drag.
+ * Returns null when the gesture is too small or degenerate after snap.
+ */
+export function shapeFromBrushDrag(
+  mode,
+  start,
+  end,
+  { halfPixel = false, constrain = false, activeKey, cellPull = LATTICE / 2 } = {}
+) {
+  if (!start || !end || !activeKey) return null;
+  const [sx, sy] = snapPt(start.x, start.y, halfPixel, cellPull);
+  let dragEnd = end;
+  // Square the drag box for rect only — squaring circles makes min/max radius identical.
+  if (constrain && mode === 'rect') {
+    dragEnd = constrainDragEnd({ x: sx, y: sy }, end);
+  }
+  const [ex, ey] = snapPt(dragEnd.x, dragEnd.y, halfPixel, cellPull);
+  const from = { x: sx, y: sy };
+  const to = { x: ex, y: ey };
+
+  // One segment per edge *between* the given corners: the edge from the last
+  // corner back to the first is implied by `closed`, not stored.
+  const strokedPolygon = (pts, key) => ({
+    fill: null,
+    stroke: key,
+    subpaths: [{ closed: true, start: pts[0], segs: pts.slice(1).map(straightSegment) }],
+  });
+
+  if (mode === 'line') {
+    if (Math.hypot(ex - sx, ey - sy) < MIN_DRAG) return null;
+    return {
+      fill: null,
+      stroke: activeKey,
+      subpaths: [{ closed: false, start: [sx, sy], segs: [straightSegment([ex, ey])] }],
+    };
+  }
+
+  const { x0, x1, y0, y1 } = shapeBounds(from, to);
+  if (Math.abs(x1 - x0) < MIN_DRAG && Math.abs(y1 - y0) < MIN_DRAG) return null;
+
+  if (mode === 'rect') {
+    if (constrain) {
+      const side = Math.max(Math.abs(ex - sx), Math.abs(ey - sy));
+      if (side < MIN_DRAG) return null;
+      const x1 = sx + Math.sign(ex - sx || 1) * side;
+      const y1 = sy + Math.sign(ey - sy || 1) * side;
+      const pts = [
+        [sx, sy],
+        [x1, sy],
+        [x1, y1],
+        [sx, y1],
+      ];
+      return strokedPolygon(pts, activeKey);
+    }
+    if (Math.abs(x1 - x0) < MIN_DRAG || Math.abs(y1 - y0) < MIN_DRAG) return null;
+    const pts = [
+      [x0, y0],
+      [x1, y0],
+      [x1, y1],
+      [x0, y1],
+    ].map(([x, y]) => snapPt(x, y, halfPixel, cellPull));
+    return strokedPolygon(pts, activeKey);
+  }
+
+  if (mode === 'triangle') {
+    if (Math.hypot(ex - sx, ey - sy) < MIN_DRAG) return null;
+    // Drag defines the hypotenuse (start → end); right angle at (start.x, end.y).
+    const right = snapPt(sx, ey, halfPixel, cellPull);
+    const pts = [
+      [sx, sy],
+      right,
+      [ex, ey],
+    ];
+    if (
+      Math.hypot(pts[0][0] - pts[1][0], pts[0][1] - pts[1][1]) < MIN_DRAG ||
+      Math.hypot(pts[1][0] - pts[2][0], pts[1][1] - pts[2][1]) < MIN_DRAG ||
+      Math.hypot(pts[2][0] - pts[0][0], pts[2][1] - pts[0][1]) < MIN_DRAG
+    ) {
+      return null;
+    }
+    return strokedPolygon(pts, activeKey);
+  }
+
+  if (mode === 'circle') {
+    const spanX = Math.abs(ex - sx);
+    const spanY = Math.abs(ey - sy);
+    // Independent radii, so the drag box is the shape. Shift squares it back
+    // into a circle. Previously the smaller span won and an oval was
+    // unreachable from this gesture at all.
+    const rawRx = (constrain ? Math.max(spanX, spanY) : spanX) / 2;
+    const rawRy = (constrain ? Math.max(spanX, spanY) : spanY) / 2;
+    if (Math.min(rawRx, rawRy) < MIN_DRAG) return null;
+    const [cx, cy] = snapPt((sx + ex) / 2, (sy + ey) / 2, halfPixel, cellPull);
+    return deriveShape({
+      prim: 'ellipse',
+      cx,
+      cy,
+      rx: Math.max(MIN_ELLIPSE_RADIUS, rawRx),
+      ry: Math.max(MIN_ELLIPSE_RADIUS, rawRy),
+      fill: null,
+      stroke: activeKey,
+    });
+  }
+
+  return null;
+}
+
+/** Ghost wrapper for overlay preview (stroke key applied at commit). */
+export function ghostFromBrushDrag(
+  mode,
+  start,
+  end,
+  { halfPixel = false, constrain = false, activeKey, cellPull = LATTICE / 2 } = {}
+) {
+  const shape = shapeFromBrushDrag(mode, start, end, { halfPixel, constrain, activeKey, cellPull });
+  return shape;
+}

package/kits/physics-2d/editors/mediaFile.js

@@ -1,5 +1,16 @@
 import { useEffect, useState } from 'react';
-import { fileUrl, onFilesChanged } from 'castle-web-sdk';
+import * as sdk from 'castle-web-sdk';
+
+// `fileUrl` arrived in castle-web-sdk 0.4.12, and a deck takes a kit update
+// (`castle-web update-import`) without reinstalling its packages -- so a deck
+// still holding an older SDK would meet a kit that imports a name its SDK does
+// not export, which is a hard build failure, not an undefined. Hence the
+// namespace import and the fallback: taking a kit update can't break a deck over
+// a version skew it never asked about. Delete both once no deck can be older
+// than 0.4.12.
+const fileUrl =
+  sdk.fileUrl ?? ((path) => `/__castle/files/raw?path=${encodeURIComponent(path)}`);
+const { onFilesChanged } = sdk;
 
 // The URL a media viewer points at, re-minted whenever the file itself changes
 // on disk (a re-upload over the same name, an agent regenerating an asset). The