@fieldnotes/core 0.63.0 → 0.64.0

package/dist/index.cjs

@@ -44,13 +44,17 @@ __export(index_exports, {
   MemoryAdapter: () => MemoryAdapter,
   MinimapController: () => MinimapController,
   NoteTool: () => NoteTool,
+  PATH_PRESENCE_KIND: () => PATH_PRESENCE_KIND,
+  PATH_PRESENCE_MAX_POINTS: () => PATH_PRESENCE_MAX_POINTS,
   PING_PRESENCE_KIND: () => PING_PRESENCE_KIND,
+  PathTool: () => PathTool,
   PencilTool: () => PencilTool,
   PingInput: () => PingInput,
   PingTool: () => PingTool,
   RemoteFocusReceiver: () => RemoteFocusReceiver,
   RemoteLaserOverlay: () => RemoteLaserOverlay,
   RemoteMeasureOverlay: () => RemoteMeasureOverlay,
+  RemotePathOverlay: () => RemotePathOverlay,
   RemotePingOverlay: () => RemotePingOverlay,
   SelectTool: () => SelectTool,
   ShapeTool: () => ShapeTool,
@@ -78,6 +82,7 @@ __export(index_exports, {
   exportImage: () => exportImage,
   exportSvg: () => exportSvg,
   fitZoomForView: () => fitZoomForView,
+  footprintFromSize: () => footprintFromSize,
   getActiveFormats: () => getActiveFormats,
   getArrowBounds: () => getArrowBounds,
   getArrowControlPoint: () => getArrowControlPoint,
@@ -93,20 +98,26 @@ __export(index_exports, {
   getHexCellsInRectangle: () => getHexCellsInRectangle,
   getHexCellsInSquare: () => getHexCellsInSquare,
   getHexDistance: () => getHexDistance,
+  gridDistanceCells: () => gridDistanceCells,
   isFocusPresence: () => isFocusPresence,
   isLaserTrailPresence: () => isLaserTrailPresence,
   isMeasurePresence: () => isMeasurePresence,
   isNearBezier: () => isNearBezier,
+  isPathPresence: () => isPathPresence,
   isPingPresence: () => isPingPresence,
+  pathDistanceCells: () => pathDistanceCells,
   resolveHtmlRouting: () => resolveHtmlRouting,
   setFontSize: () => setFontSize,
   smartSnap: () => smartSnap,
+  snapFootprintCenter: () => snapFootprintCenter,
   snapPoint: () => snapPoint,
+  snapToCellCenter: () => snapToCellCenter,
   snapToHexCenter: () => snapToHexCenter,
   styleToPatch: () => styleToPatch,
   toFocusPresence: () => toFocusPresence,
   toLaserTrailPresence: () => toLaserTrailPresence,
   toMeasurePresence: () => toMeasurePresence,
+  toPathPresence: () => toPathPresence,
   toPingPresence: () => toPingPresence,
   toggleBold: () => toggleBold,
   toggleItalic: () => toggleItalic,
@@ -146,6 +157,310 @@ function smartSnap(point, ctx) {
   }
   return snapPoint(point, ctx.gridSize);
 }
+function footprintOf(footprint) {
+  return typeof footprint === "number" ? { w: footprint, h: footprint } : footprint;
+}
+function footprintFromSize(size, gridSize) {
+  if (!(gridSize > 0)) return 1;
+  return {
+    w: Math.max(1, Math.round(size.w / gridSize)),
+    h: Math.max(1, Math.round(size.h / gridSize))
+  };
+}
+function snapAxisToCell(value, gridSize, cells) {
+  const n2 = Math.max(1, Math.round(cells));
+  if (n2 % 2 === 0) return Math.round(value / gridSize) * gridSize || 0;
+  return (Math.round((value - gridSize / 2) / gridSize) + 0.5) * gridSize || 0;
+}
+function snapToCellCenter(point, gridSize, footprint = 1) {
+  const { w, h } = footprintOf(footprint);
+  return { x: snapAxisToCell(point.x, gridSize, w), y: snapAxisToCell(point.y, gridSize, h) };
+}
+function snapFootprintCenter(point, footprint, ctx) {
+  if (!ctx.snapToGrid || !ctx.gridSize) return point;
+  if (ctx.gridType === "hex" && ctx.hexOrientation) {
+    return snapToHexCenter(point, ctx.gridSize, ctx.hexOrientation);
+  }
+  return snapToCellCenter(point, ctx.gridSize, footprint);
+}
+
+// src/elements/hex-fill.ts
+function offsetToCube(col, row, orientation) {
+  if (orientation === "pointy") {
+    return { q: col - (row - (row & 1)) / 2, r: row };
+  }
+  return { q: col, r: row - (col - (col & 1)) / 2 };
+}
+function cubeToOffset(q, r, orientation) {
+  if (orientation === "pointy") {
+    return { col: q + (r - (r & 1)) / 2, row: r };
+  }
+  return { col: q, row: r + (q - (q & 1)) / 2 };
+}
+function offsetToPixel(col, row, cellSize, orientation) {
+  if (orientation === "pointy") {
+    const hexW = Math.sqrt(3) * cellSize;
+    const rowH = 1.5 * cellSize;
+    const offsetX = row % 2 !== 0 ? hexW / 2 : 0;
+    return { x: col * hexW + offsetX, y: row * rowH };
+  }
+  const hexH = Math.sqrt(3) * cellSize;
+  const colW = 1.5 * cellSize;
+  const offsetY = col % 2 !== 0 ? hexH / 2 : 0;
+  return { x: col * colW, y: row * hexH + offsetY };
+}
+function pixelToOffset(x, y, cellSize, orientation) {
+  if (orientation === "pointy") {
+    const hexW = Math.sqrt(3) * cellSize;
+    const rowH = 1.5 * cellSize;
+    const row = Math.round(y / rowH);
+    const offsetX = row % 2 !== 0 ? hexW / 2 : 0;
+    return { col: Math.round((x - offsetX) / hexW), row };
+  }
+  const hexH = Math.sqrt(3) * cellSize;
+  const colW = 1.5 * cellSize;
+  const col = Math.round(x / colW);
+  const offsetY = col % 2 !== 0 ? hexH / 2 : 0;
+  return { col, row: Math.round((y - offsetY) / hexH) };
+}
+function enumerateHexRing(centerQ, centerR, n2, orientation, cellSize) {
+  const cells = [];
+  for (let dq = -n2; dq <= n2; dq++) {
+    const rMin = Math.max(-n2, -dq - n2);
+    const rMax = Math.min(n2, -dq + n2);
+    for (let dr = rMin; dr <= rMax; dr++) {
+      const absQ = centerQ + dq;
+      const absR = centerR + dr;
+      const off = cubeToOffset(absQ, absR, orientation);
+      cells.push(offsetToPixel(off.col, off.row, cellSize, orientation));
+    }
+  }
+  return cells;
+}
+function getHexDistance(a, b, cellSize, orientation) {
+  const offA = pixelToOffset(a.x, a.y, cellSize, orientation);
+  const offB = pixelToOffset(b.x, b.y, cellSize, orientation);
+  const cubeA = offsetToCube(offA.col, offA.row, orientation);
+  const cubeB = offsetToCube(offB.col, offB.row, orientation);
+  const dq = cubeA.q - cubeB.q;
+  const dr = cubeA.r - cubeB.r;
+  const ds = -dq - dr;
+  return Math.max(Math.abs(dq), Math.abs(dr), Math.abs(ds));
+}
+function getHexCellsInRadius(center2, radiusCells, cellSize, orientation) {
+  const n2 = Math.round(radiusCells);
+  const off = pixelToOffset(center2.x, center2.y, cellSize, orientation);
+  const cube = offsetToCube(off.col, off.row, orientation);
+  if (n2 <= 0) {
+    return [offsetToPixel(off.col, off.row, cellSize, orientation)];
+  }
+  return enumerateHexRing(cube.q, cube.r, n2, orientation, cellSize);
+}
+function getHexCellsInCone(center2, angle, radiusCells, cellSize, orientation) {
+  const n2 = Math.round(radiusCells);
+  const off = pixelToOffset(center2.x, center2.y, cellSize, orientation);
+  const cube = offsetToCube(off.col, off.row, orientation);
+  const centerPixel = offsetToPixel(off.col, off.row, cellSize, orientation);
+  if (n2 <= 0) return [centerPixel];
+  const vertexOffset = orientation === "pointy" ? Math.PI / 6 : 0;
+  const step = Math.PI / 3;
+  const snappedAngle = Math.round((angle - vertexOffset) / step) * step + vertexOffset;
+  const halfAngle = Math.PI / 6 + 1e-6;
+  const cells = [centerPixel];
+  for (let dq = -n2; dq <= n2; dq++) {
+    const rMin = Math.max(-n2, -dq - n2);
+    const rMax = Math.min(n2, -dq + n2);
+    for (let dr = rMin; dr <= rMax; dr++) {
+      if (dq === 0 && dr === 0) continue;
+      const absQ = cube.q + dq;
+      const absR = cube.r + dr;
+      const pixel = offsetToPixel(
+        cubeToOffset(absQ, absR, orientation).col,
+        cubeToOffset(absQ, absR, orientation).row,
+        cellSize,
+        orientation
+      );
+      const dx = pixel.x - centerPixel.x;
+      const dy = pixel.y - centerPixel.y;
+      let diff = Math.atan2(dy, dx) - snappedAngle;
+      if (diff > Math.PI) diff -= 2 * Math.PI;
+      if (diff < -Math.PI) diff += 2 * Math.PI;
+      if (Math.abs(diff) <= halfAngle) {
+        cells.push(pixel);
+      }
+    }
+  }
+  return cells;
+}
+function getHexCellsInLine(center2, angle, radiusCells, cellSize, orientation) {
+  const n2 = Math.round(radiusCells);
+  const off = pixelToOffset(center2.x, center2.y, cellSize, orientation);
+  const cube = offsetToCube(off.col, off.row, orientation);
+  const centerPixel = offsetToPixel(off.col, off.row, cellSize, orientation);
+  if (n2 <= 0) return [centerPixel];
+  const vertexOffset = orientation === "pointy" ? Math.PI / 6 : 0;
+  const step = Math.PI / 3;
+  const snappedAngle = Math.round((angle - vertexOffset) / step) * step + vertexOffset;
+  const cos = Math.cos(snappedAngle);
+  const sin = Math.sin(snappedAngle);
+  const snapUnit = Math.sqrt(3) * cellSize;
+  const lineLength = n2 * snapUnit;
+  const halfWidth = snapUnit * 0.5 + 1e-6;
+  const cells = [];
+  for (let dq = -n2; dq <= n2; dq++) {
+    const rMin = Math.max(-n2, -dq - n2);
+    const rMax = Math.min(n2, -dq + n2);
+    for (let dr = rMin; dr <= rMax; dr++) {
+      const absQ = cube.q + dq;
+      const absR = cube.r + dr;
+      const pixel = offsetToPixel(
+        cubeToOffset(absQ, absR, orientation).col,
+        cubeToOffset(absQ, absR, orientation).row,
+        cellSize,
+        orientation
+      );
+      const dx = pixel.x - centerPixel.x;
+      const dy = pixel.y - centerPixel.y;
+      const along = dx * cos + dy * sin;
+      const perp = Math.abs(-dx * sin + dy * cos);
+      if (along >= -snapUnit * 0.1 && along <= lineLength + snapUnit * 0.1 && perp <= halfWidth) {
+        cells.push(pixel);
+      }
+    }
+  }
+  return cells;
+}
+function getHexCellsInRectangle(center2, angle, lengthCells, widthCells, cellSize, orientation) {
+  const nLen = Math.round(lengthCells);
+  const wCells = Math.max(1, Math.round(widthCells));
+  const off = pixelToOffset(center2.x, center2.y, cellSize, orientation);
+  const cube = offsetToCube(off.col, off.row, orientation);
+  const centerPixel = offsetToPixel(off.col, off.row, cellSize, orientation);
+  if (nLen <= 0) return [centerPixel];
+  const vertexOffset = orientation === "pointy" ? Math.PI / 6 : 0;
+  const step = Math.PI / 3;
+  const snappedAngle = Math.round((angle - vertexOffset) / step) * step + vertexOffset;
+  const cos = Math.cos(snappedAngle);
+  const sin = Math.sin(snappedAngle);
+  const snapUnit = Math.sqrt(3) * cellSize;
+  const lineLength = nLen * snapUnit;
+  const halfWidth = wCells * snapUnit / 2 + 1e-6;
+  const iterM = nLen + Math.ceil(wCells / 2) + 1;
+  const cells = [];
+  for (let dq = -iterM; dq <= iterM; dq++) {
+    const rMin = Math.max(-iterM, -dq - iterM);
+    const rMax = Math.min(iterM, -dq + iterM);
+    for (let dr = rMin; dr <= rMax; dr++) {
+      const absQ = cube.q + dq;
+      const absR = cube.r + dr;
+      const pixel = offsetToPixel(
+        cubeToOffset(absQ, absR, orientation).col,
+        cubeToOffset(absQ, absR, orientation).row,
+        cellSize,
+        orientation
+      );
+      const dx = pixel.x - centerPixel.x;
+      const dy = pixel.y - centerPixel.y;
+      const along = dx * cos + dy * sin;
+      const perp = Math.abs(-dx * sin + dy * cos);
+      if (along >= -snapUnit * 0.1 && along <= lineLength + snapUnit * 0.1 && perp <= halfWidth) {
+        cells.push(pixel);
+      }
+    }
+  }
+  return cells;
+}
+function getHexCellsInSquare(center2, radiusCells, cellSize, orientation) {
+  const n2 = Math.round(radiusCells);
+  const off = pixelToOffset(center2.x, center2.y, cellSize, orientation);
+  const cube = offsetToCube(off.col, off.row, orientation);
+  const centerPixel = offsetToPixel(off.col, off.row, cellSize, orientation);
+  if (n2 <= 0) return [centerPixel];
+  const snapUnit = Math.sqrt(3) * cellSize;
+  const halfSide = n2 * snapUnit / 2;
+  const cells = [];
+  for (let dq = -n2; dq <= n2; dq++) {
+    const rMin = Math.max(-n2, -dq - n2);
+    const rMax = Math.min(n2, -dq + n2);
+    for (let dr = rMin; dr <= rMax; dr++) {
+      const absQ = cube.q + dq;
+      const absR = cube.r + dr;
+      const pixel = offsetToPixel(
+        cubeToOffset(absQ, absR, orientation).col,
+        cubeToOffset(absQ, absR, orientation).row,
+        cellSize,
+        orientation
+      );
+      if (Math.abs(pixel.x - centerPixel.x) <= halfSide && Math.abs(pixel.y - centerPixel.y) <= halfSide) {
+        cells.push(pixel);
+      }
+    }
+  }
+  return cells;
+}
+function drawHexPath(ctx, cx, cy, cellSize, orientation) {
+  const angleOffset = orientation === "pointy" ? Math.PI / 6 : 0;
+  ctx.moveTo(cx + cellSize * Math.cos(angleOffset), cy + cellSize * Math.sin(angleOffset));
+  for (let i = 1; i < 6; i++) {
+    const a = angleOffset + Math.PI / 3 * i;
+    ctx.lineTo(cx + cellSize * Math.cos(a), cy + cellSize * Math.sin(a));
+  }
+  ctx.closePath();
+}
+
+// src/core/grid-metric.ts
+function squareCost(rule, straight, diag) {
+  switch (rule) {
+    case "alternate":
+      return straight + diag + Math.floor(diag / 2);
+    case "manhattan":
+      return straight + 2 * diag;
+    case "chebyshev":
+    case "euclidean":
+    default:
+      return straight + diag;
+  }
+}
+function pathDistanceCells(points, grid) {
+  const cumulative = [];
+  const first = points[0];
+  if (first === void 0) return { total: 0, cumulative };
+  const gridSize = grid.gridSize > 0 ? grid.gridSize : 1;
+  const rule = grid.diagonalRule ?? "euclidean";
+  const orientation = grid.hexOrientation;
+  const hex = grid.gridType === "hex" && orientation !== void 0;
+  const squareRule = grid.gridType === "square" && rule !== "euclidean";
+  let straight = 0;
+  let diag = 0;
+  let euclid = 0;
+  let hexCells = 0;
+  cumulative.push(0);
+  let prev = first;
+  for (let i = 1; i < points.length; i++) {
+    const next = points[i];
+    if (next === void 0) break;
+    if (hex && orientation !== void 0) {
+      hexCells += getHexDistance(prev, next, gridSize, orientation);
+      cumulative.push(hexCells);
+    } else if (squareRule) {
+      const dx = Math.abs(Math.round((next.x - prev.x) / gridSize));
+      const dy = Math.abs(Math.round((next.y - prev.y) / gridSize));
+      const d = Math.min(dx, dy);
+      diag += d;
+      straight += Math.max(dx, dy) - d;
+      cumulative.push(squareCost(rule, straight, diag));
+    } else {
+      euclid += Math.hypot(next.x - prev.x, next.y - prev.y) / gridSize;
+      cumulative.push(euclid);
+    }
+    prev = next;
+  }
+  const total = cumulative[cumulative.length - 1] ?? 0;
+  return { total, cumulative };
+}
+function gridDistanceCells(a, b, grid) {
+  return pathDistanceCells([a, b], grid).total;
+}
 
 // src/elements/note-sanitizer.ts
 var BOLD_TAGS = /* @__PURE__ */ new Set(["b", "strong"]);
@@ -1672,6 +1987,12 @@ var KeyboardHandler = class {
     if (e.key === " ") {
       this.deps.setSpaceHeld(true);
     }
+    const tool = this.deps.getActiveTool();
+    const ctx = this.deps.getToolContext();
+    if (tool?.onKeyDown && ctx && tool.onKeyDown(e, ctx)) {
+      e.preventDefault();
+      return;
+    }
     const action = this.shortcutMap.match(e);
     if (action !== null) {
       this.runAction(action, e);
@@ -1967,6 +2288,7 @@ var InputHandler = class {
       abortSignal: this.abortController.signal,
       getToolContext: () => this.toolContext,
       getIsToolActive: () => this.isToolActive,
+      getActiveTool: () => this.toolManager?.activeTool ?? null,
       getLastPointerEvent: () => this.lastPointerEvent,
       setSpaceHeld: (v) => {
         this.spaceHeld = v;
@@ -2048,7 +2370,7 @@ var InputHandler = class {
     this.element.addEventListener("pointermove", this.onPointerMove, opts);
     this.element.addEventListener("pointerup", this.onPointerUp, opts);
     this.element.addEventListener("pointerleave", this.onPointerLeave, opts);
-    this.element.addEventListener("pointercancel", this.onPointerUp, opts);
+    this.element.addEventListener("pointercancel", this.onPointerCancel, opts);
     this.element.addEventListener("contextmenu", this.onContextMenu, opts);
     window.addEventListener("blur", this.onCoastInterrupt, opts);
     window.addEventListener("visibilitychange", this.onCoastInterrupt, opts);
@@ -2127,6 +2449,12 @@ var InputHandler = class {
     }
   };
   onPointerUp = (e) => {
+    this.finishPointer(e, false);
+  };
+  onPointerCancel = (e) => {
+    this.finishPointer(e, true);
+  };
+  finishPointer(e, cancelled) {
     this.cancelLongPress();
     try {
       this.element.releasePointerCapture(e.pointerId);
@@ -2149,16 +2477,18 @@ var InputHandler = class {
     if (this.activePointers.size === 0) this.coastStoppedByPointer = false;
     const upResult = this.inputFilter.filterUp(e);
     if (this.isToolActive) {
-      this.dispatchToolUp(e);
+      if (cancelled) this.dispatchToolCancel(e);
+      else this.dispatchToolUp(e);
       this.isToolActive = false;
     } else if (this.deferredDown && upResult.pendingTap) {
       this.dispatchToolDown(this.deferredDown);
-      this.dispatchToolUp(e);
+      if (cancelled) this.dispatchToolCancel(e);
+      else this.dispatchToolUp(e);
       this.deferredDown = null;
     } else {
       this.deferredDown = null;
     }
-  };
+  }
   runAction(action, e) {
     this.keyboard.runAction(action, e);
   }
@@ -2265,6 +2595,11 @@ var InputHandler = class {
     this.toolManager.handlePointerUp(this.toPointerState(e), this.toolContext);
     this.historyRecorder?.commit();
   }
+  dispatchToolCancel(e) {
+    if (!this.toolManager || !this.toolContext) return;
+    this.toolManager.handlePointerCancel(this.toPointerState(e), this.toolContext);
+    this.historyRecorder?.commit();
+  }
   isInScope() {
     if (this.scope === "window") return true;
     const active = document.activeElement;
@@ -2277,7 +2612,7 @@ var InputHandler = class {
   cancelToolIfActive(e) {
     this.cancelLongPress();
     if (this.isToolActive) {
-      this.dispatchToolUp(e);
+      this.dispatchToolCancel(e);
       this.isToolActive = false;
     }
     this.deferredDown = null;
@@ -3375,230 +3710,6 @@ function getImage(src, imageCache, onImageLoad, onImageError) {
   return null;
 }
 
-// src/elements/hex-fill.ts
-function offsetToCube(col, row, orientation) {
-  if (orientation === "pointy") {
-    return { q: col - (row - (row & 1)) / 2, r: row };
-  }
-  return { q: col, r: row - (col - (col & 1)) / 2 };
-}
-function cubeToOffset(q, r, orientation) {
-  if (orientation === "pointy") {
-    return { col: q + (r - (r & 1)) / 2, row: r };
-  }
-  return { col: q, row: r + (q - (q & 1)) / 2 };
-}
-function offsetToPixel(col, row, cellSize, orientation) {
-  if (orientation === "pointy") {
-    const hexW = Math.sqrt(3) * cellSize;
-    const rowH = 1.5 * cellSize;
-    const offsetX = row % 2 !== 0 ? hexW / 2 : 0;
-    return { x: col * hexW + offsetX, y: row * rowH };
-  }
-  const hexH = Math.sqrt(3) * cellSize;
-  const colW = 1.5 * cellSize;
-  const offsetY = col % 2 !== 0 ? hexH / 2 : 0;
-  return { x: col * colW, y: row * hexH + offsetY };
-}
-function pixelToOffset(x, y, cellSize, orientation) {
-  if (orientation === "pointy") {
-    const hexW = Math.sqrt(3) * cellSize;
-    const rowH = 1.5 * cellSize;
-    const row = Math.round(y / rowH);
-    const offsetX = row % 2 !== 0 ? hexW / 2 : 0;
-    return { col: Math.round((x - offsetX) / hexW), row };
-  }
-  const hexH = Math.sqrt(3) * cellSize;
-  const colW = 1.5 * cellSize;
-  const col = Math.round(x / colW);
-  const offsetY = col % 2 !== 0 ? hexH / 2 : 0;
-  return { col, row: Math.round((y - offsetY) / hexH) };
-}
-function enumerateHexRing(centerQ, centerR, n2, orientation, cellSize) {
-  const cells = [];
-  for (let dq = -n2; dq <= n2; dq++) {
-    const rMin = Math.max(-n2, -dq - n2);
-    const rMax = Math.min(n2, -dq + n2);
-    for (let dr = rMin; dr <= rMax; dr++) {
-      const absQ = centerQ + dq;
-      const absR = centerR + dr;
-      const off = cubeToOffset(absQ, absR, orientation);
-      cells.push(offsetToPixel(off.col, off.row, cellSize, orientation));
-    }
-  }
-  return cells;
-}
-function getHexDistance(a, b, cellSize, orientation) {
-  const offA = pixelToOffset(a.x, a.y, cellSize, orientation);
-  const offB = pixelToOffset(b.x, b.y, cellSize, orientation);
-  const cubeA = offsetToCube(offA.col, offA.row, orientation);
-  const cubeB = offsetToCube(offB.col, offB.row, orientation);
-  const dq = cubeA.q - cubeB.q;
-  const dr = cubeA.r - cubeB.r;
-  const ds = -dq - dr;
-  return Math.max(Math.abs(dq), Math.abs(dr), Math.abs(ds));
-}
-function getHexCellsInRadius(center2, radiusCells, cellSize, orientation) {
-  const n2 = Math.round(radiusCells);
-  const off = pixelToOffset(center2.x, center2.y, cellSize, orientation);
-  const cube = offsetToCube(off.col, off.row, orientation);
-  if (n2 <= 0) {
-    return [offsetToPixel(off.col, off.row, cellSize, orientation)];
-  }
-  return enumerateHexRing(cube.q, cube.r, n2, orientation, cellSize);
-}
-function getHexCellsInCone(center2, angle, radiusCells, cellSize, orientation) {
-  const n2 = Math.round(radiusCells);
-  const off = pixelToOffset(center2.x, center2.y, cellSize, orientation);
-  const cube = offsetToCube(off.col, off.row, orientation);
-  const centerPixel = offsetToPixel(off.col, off.row, cellSize, orientation);
-  if (n2 <= 0) return [centerPixel];
-  const vertexOffset = orientation === "pointy" ? Math.PI / 6 : 0;
-  const step = Math.PI / 3;
-  const snappedAngle = Math.round((angle - vertexOffset) / step) * step + vertexOffset;
-  const halfAngle = Math.PI / 6 + 1e-6;
-  const cells = [centerPixel];
-  for (let dq = -n2; dq <= n2; dq++) {
-    const rMin = Math.max(-n2, -dq - n2);
-    const rMax = Math.min(n2, -dq + n2);
-    for (let dr = rMin; dr <= rMax; dr++) {
-      if (dq === 0 && dr === 0) continue;
-      const absQ = cube.q + dq;
-      const absR = cube.r + dr;
-      const pixel = offsetToPixel(
-        cubeToOffset(absQ, absR, orientation).col,
-        cubeToOffset(absQ, absR, orientation).row,
-        cellSize,
-        orientation
-      );
-      const dx = pixel.x - centerPixel.x;
-      const dy = pixel.y - centerPixel.y;
-      let diff = Math.atan2(dy, dx) - snappedAngle;
-      if (diff > Math.PI) diff -= 2 * Math.PI;
-      if (diff < -Math.PI) diff += 2 * Math.PI;
-      if (Math.abs(diff) <= halfAngle) {
-        cells.push(pixel);
-      }
-    }
-  }
-  return cells;
-}
-function getHexCellsInLine(center2, angle, radiusCells, cellSize, orientation) {
-  const n2 = Math.round(radiusCells);
-  const off = pixelToOffset(center2.x, center2.y, cellSize, orientation);
-  const cube = offsetToCube(off.col, off.row, orientation);
-  const centerPixel = offsetToPixel(off.col, off.row, cellSize, orientation);
-  if (n2 <= 0) return [centerPixel];
-  const vertexOffset = orientation === "pointy" ? Math.PI / 6 : 0;
-  const step = Math.PI / 3;
-  const snappedAngle = Math.round((angle - vertexOffset) / step) * step + vertexOffset;
-  const cos = Math.cos(snappedAngle);
-  const sin = Math.sin(snappedAngle);
-  const snapUnit = Math.sqrt(3) * cellSize;
-  const lineLength = n2 * snapUnit;
-  const halfWidth = snapUnit * 0.5 + 1e-6;
-  const cells = [];
-  for (let dq = -n2; dq <= n2; dq++) {
-    const rMin = Math.max(-n2, -dq - n2);
-    const rMax = Math.min(n2, -dq + n2);
-    for (let dr = rMin; dr <= rMax; dr++) {
-      const absQ = cube.q + dq;
-      const absR = cube.r + dr;
-      const pixel = offsetToPixel(
-        cubeToOffset(absQ, absR, orientation).col,
-        cubeToOffset(absQ, absR, orientation).row,
-        cellSize,
-        orientation
-      );
-      const dx = pixel.x - centerPixel.x;
-      const dy = pixel.y - centerPixel.y;
-      const along = dx * cos + dy * sin;
-      const perp = Math.abs(-dx * sin + dy * cos);
-      if (along >= -snapUnit * 0.1 && along <= lineLength + snapUnit * 0.1 && perp <= halfWidth) {
-        cells.push(pixel);
-      }
-    }
-  }
-  return cells;
-}
-function getHexCellsInRectangle(center2, angle, lengthCells, widthCells, cellSize, orientation) {
-  const nLen = Math.round(lengthCells);
-  const wCells = Math.max(1, Math.round(widthCells));
-  const off = pixelToOffset(center2.x, center2.y, cellSize, orientation);
-  const cube = offsetToCube(off.col, off.row, orientation);
-  const centerPixel = offsetToPixel(off.col, off.row, cellSize, orientation);
-  if (nLen <= 0) return [centerPixel];
-  const vertexOffset = orientation === "pointy" ? Math.PI / 6 : 0;
-  const step = Math.PI / 3;
-  const snappedAngle = Math.round((angle - vertexOffset) / step) * step + vertexOffset;
-  const cos = Math.cos(snappedAngle);
-  const sin = Math.sin(snappedAngle);
-  const snapUnit = Math.sqrt(3) * cellSize;
-  const lineLength = nLen * snapUnit;
-  const halfWidth = wCells * snapUnit / 2 + 1e-6;
-  const iterM = nLen + Math.ceil(wCells / 2) + 1;
-  const cells = [];
-  for (let dq = -iterM; dq <= iterM; dq++) {
-    const rMin = Math.max(-iterM, -dq - iterM);
-    const rMax = Math.min(iterM, -dq + iterM);
-    for (let dr = rMin; dr <= rMax; dr++) {
-      const absQ = cube.q + dq;
-      const absR = cube.r + dr;
-      const pixel = offsetToPixel(
-        cubeToOffset(absQ, absR, orientation).col,
-        cubeToOffset(absQ, absR, orientation).row,
-        cellSize,
-        orientation
-      );
-      const dx = pixel.x - centerPixel.x;
-      const dy = pixel.y - centerPixel.y;
-      const along = dx * cos + dy * sin;
-      const perp = Math.abs(-dx * sin + dy * cos);
-      if (along >= -snapUnit * 0.1 && along <= lineLength + snapUnit * 0.1 && perp <= halfWidth) {
-        cells.push(pixel);
-      }
-    }
-  }
-  return cells;
-}
-function getHexCellsInSquare(center2, radiusCells, cellSize, orientation) {
-  const n2 = Math.round(radiusCells);
-  const off = pixelToOffset(center2.x, center2.y, cellSize, orientation);
-  const cube = offsetToCube(off.col, off.row, orientation);
-  const centerPixel = offsetToPixel(off.col, off.row, cellSize, orientation);
-  if (n2 <= 0) return [centerPixel];
-  const snapUnit = Math.sqrt(3) * cellSize;
-  const halfSide = n2 * snapUnit / 2;
-  const cells = [];
-  for (let dq = -n2; dq <= n2; dq++) {
-    const rMin = Math.max(-n2, -dq - n2);
-    const rMax = Math.min(n2, -dq + n2);
-    for (let dr = rMin; dr <= rMax; dr++) {
-      const absQ = cube.q + dq;
-      const absR = cube.r + dr;
-      const pixel = offsetToPixel(
-        cubeToOffset(absQ, absR, orientation).col,
-        cubeToOffset(absQ, absR, orientation).row,
-        cellSize,
-        orientation
-      );
-      if (Math.abs(pixel.x - centerPixel.x) <= halfSide && Math.abs(pixel.y - centerPixel.y) <= halfSide) {
-        cells.push(pixel);
-      }
-    }
-  }
-  return cells;
-}
-function drawHexPath(ctx, cx, cy, cellSize, orientation) {
-  const angleOffset = orientation === "pointy" ? Math.PI / 6 : 0;
-  ctx.moveTo(cx + cellSize * Math.cos(angleOffset), cy + cellSize * Math.sin(angleOffset));
-  for (let i = 1; i < 6; i++) {
-    const a = angleOffset + Math.PI / 3 * i;
-    ctx.lineTo(cx + cellSize * Math.cos(a), cy + cellSize * Math.sin(a));
-  }
-  ctx.closePath();
-}
-
 // src/elements/renderers/template-measure.ts
 function renderTemplateFeetLabel(ctx, p) {
   if (p.feet <= 0) return;
@@ -5573,6 +5684,13 @@ var ToolManager = class {
   handlePointerUp(state, ctx) {
     this.current?.onPointerUp(state, ctx);
   }
+  /** Cancels the active gesture; falls back to `onPointerUp` for tools without `onPointerCancel`. */
+  handlePointerCancel(state, ctx) {
+    const tool = this.current;
+    if (!tool) return;
+    if (tool.onPointerCancel) tool.onPointerCancel(state, ctx);
+    else tool.onPointerUp(state, ctx);
+  }
   onChange(listener) {
     this.changeListeners.add(listener);
     return () => this.changeListeners.delete(listener);
@@ -11182,145 +11300,119 @@ function drawMeasurement(ctx, m, opts = {}) {
   ctx.restore();
 }
 
-// src/canvas/remote-measure-overlay.ts
-var MEASURE_PRESENCE_KIND = "measure";
-function isFinitePoint2(value) {
-  if (typeof value !== "object" || value === null) return false;
-  const point = value;
-  return typeof point.x === "number" && Number.isFinite(point.x) && typeof point.y === "number" && Number.isFinite(point.y);
-}
-function isMeasurePresence(data) {
-  if (typeof data !== "object" || data === null) return false;
-  const payload = data;
-  if (payload.kind !== MEASURE_PRESENCE_KIND) return false;
-  if ("cleared" in payload) return payload.cleared === true;
-  if (!isFinitePoint2(payload.start) || !isFinitePoint2(payload.end)) return false;
-  if (typeof payload.cells !== "number" || !Number.isFinite(payload.cells)) return false;
-  if (typeof payload.feet !== "number" || !Number.isFinite(payload.feet)) return false;
-  if (payload.color !== void 0 && typeof payload.color !== "string") return false;
-  return true;
-}
-function toMeasurePresence(emission) {
-  if (emission === null) return { kind: MEASURE_PRESENCE_KIND, cleared: true };
-  return {
-    kind: MEASURE_PRESENCE_KIND,
-    start: emission.start,
-    end: emission.end,
-    cells: emission.cells,
-    feet: emission.feet,
-    color: emission.color
-  };
-}
-var DEFAULT_COLOR3 = "#FF5722";
+// src/canvas/linger-overlay.ts
 var DEFAULT_HOLD_MS = 1500;
 var DEFAULT_FADE_MS2 = 400;
 var DEFAULT_MAX_AGE_MS = 3e4;
-var RemoteMeasureOverlay = class {
+var LingerOverlay = class {
   host;
-  color;
+  draw;
+  clock;
   holdMs;
   fadeMs;
   maxAgeMs;
-  measurements = /* @__PURE__ */ new Map();
+  entries = /* @__PURE__ */ new Map();
   unregister;
   rafId = null;
-  disposed = false;
-  constructor(host, options = {}) {
+  isDisposed = false;
+  /**
+   * `clock` exists only as a test seam; production callers leave it at
+   * `performance.now`. Owners that expose their own `now()` seam pass it
+   * through so a spy on the owner still drives this overlay's timing.
+   */
+  constructor(host, options, draw, clock = () => performance.now()) {
     this.host = host;
-    this.color = options.color ?? DEFAULT_COLOR3;
+    this.draw = draw;
+    this.clock = clock;
     this.holdMs = options.holdMs ?? DEFAULT_HOLD_MS;
     this.fadeMs = options.fadeMs ?? DEFAULT_FADE_MS2;
     this.maxAgeMs = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
-    this.unregister = host.registerOverlay((ctx) => this.renderMeasurements(ctx));
+    this.unregister = host.registerOverlay((ctx) => this.render(ctx));
   }
   now() {
-    return performance.now();
+    return this.clock();
   }
   /**
-   * Applies a presence payload from `sender` (any opaque per-sender key, e.g.
-   * the envelope `from`). Non-measure or malformed payloads are ignored and
-   * reported as `false`, so hosts can feed every presence frame through.
+   * Stores `sender`'s current entry as active, replacing any previous one and
+   * cancelling an in-flight linger, and restarts the `maxAgeMs` expiry timer.
    */
-  apply(sender, data) {
-    if (this.disposed || !isMeasurePresence(data)) return false;
-    if ("cleared" in data) {
-      this.beginLinger(sender);
-      return true;
-    }
-    const existing = this.measurements.get(sender);
+  set(sender, entry) {
+    if (this.isDisposed) return;
+    const existing = this.entries.get(sender);
     if (existing?.expiryTimer != null) clearTimeout(existing.expiryTimer);
-    this.measurements.set(sender, {
-      start: data.start,
-      end: data.end,
-      feet: data.feet,
-      color: data.color ?? this.color,
+    this.entries.set(sender, {
+      entry,
       clearedAt: null,
-      expiryTimer: setTimeout(() => this.beginLinger(sender), this.maxAgeMs)
+      expiryTimer: setTimeout(() => this.linger(sender), this.maxAgeMs)
     });
     this.host.requestRender();
-    return true;
   }
-  /** Removes a sender's ruler immediately (presence-leave/disconnect). */
+  /** Starts the hold-then-fade lifetime for `sender`'s entry. */
+  linger(sender) {
+    const entry = this.entries.get(sender);
+    if (!entry || entry.clearedAt !== null) return;
+    if (entry.expiryTimer != null) {
+      clearTimeout(entry.expiryTimer);
+      entry.expiryTimer = null;
+    }
+    entry.clearedAt = this.now();
+    this.ensureAnimating();
+    this.host.requestRender();
+  }
+  /** Removes a sender's entry immediately (presence-leave/disconnect). */
   remove(sender) {
-    const entry = this.measurements.get(sender);
+    const entry = this.entries.get(sender);
     if (!entry) return;
     if (entry.expiryTimer != null) clearTimeout(entry.expiryTimer);
-    this.measurements.delete(sender);
+    this.entries.delete(sender);
     this.host.requestRender();
   }
-  /** Removes every ruler immediately. */
+  /** Removes every entry immediately. */
   clear() {
-    if (this.measurements.size === 0) return;
-    for (const entry of this.measurements.values()) {
+    if (this.entries.size === 0) return;
+    for (const entry of this.entries.values()) {
       if (entry.expiryTimer != null) clearTimeout(entry.expiryTimer);
     }
-    this.measurements.clear();
+    this.entries.clear();
     this.host.requestRender();
   }
-  /** Number of senders with a visible (active or lingering) ruler. */
+  /** Number of senders with a visible (active or lingering) entry. */
   get activeSenderCount() {
-    return this.measurements.size;
+    return this.entries.size;
+  }
+  /** True once `dispose` has run; the overlay accepts no further entries. */
+  get disposed() {
+    return this.isDisposed;
   }
   /** Unregisters the overlay, cancels timers, stops animating. Idempotent. */
   dispose() {
-    if (this.disposed) return;
-    this.disposed = true;
+    if (this.isDisposed) return;
+    this.isDisposed = true;
     if (this.rafId !== null) {
       cancelAnimationFrame(this.rafId);
       this.rafId = null;
     }
-    for (const entry of this.measurements.values()) {
+    for (const entry of this.entries.values()) {
       if (entry.expiryTimer != null) clearTimeout(entry.expiryTimer);
     }
-    this.measurements.clear();
+    this.entries.clear();
     this.unregister?.();
     this.unregister = null;
     this.host.requestRender();
   }
-  beginLinger(sender) {
-    const entry = this.measurements.get(sender);
-    if (!entry || entry.clearedAt !== null) return;
-    if (entry.expiryTimer != null) {
-      clearTimeout(entry.expiryTimer);
-      entry.expiryTimer = null;
-    }
-    entry.clearedAt = this.now();
-    this.ensureAnimating();
-    this.host.requestRender();
-  }
   ensureAnimating() {
     if (this.rafId === null) {
       this.rafId = requestAnimationFrame(() => this.tick());
     }
   }
   tick() {
-    if (this.disposed) return;
+    if (this.isDisposed) return;
     const now = this.now();
     let lingering = 0;
-    for (const [sender, entry] of this.measurements) {
+    for (const [sender, entry] of this.entries) {
       if (entry.clearedAt === null) continue;
       if (now - entry.clearedAt >= this.holdMs + this.fadeMs) {
-        this.measurements.delete(sender);
+        this.entries.delete(sender);
       } else {
         lingering += 1;
       }
@@ -11328,24 +11420,278 @@ var RemoteMeasureOverlay = class {
     this.host.requestRender();
     this.rafId = lingering > 0 ? requestAnimationFrame(() => this.tick()) : null;
   }
-  renderMeasurements(ctx) {
-    if (this.measurements.size === 0) return;
+  render(ctx) {
+    if (this.entries.size === 0) return;
     const now = this.now();
-    for (const entry of this.measurements.values()) {
+    for (const entry of this.entries.values()) {
       let alpha = 1;
       if (entry.clearedAt !== null) {
         const fadeAge = now - entry.clearedAt - this.holdMs;
         if (fadeAge > 0) alpha = Math.max(0, 1 - fadeAge / this.fadeMs);
       }
-      drawMeasurement(ctx, entry, { alpha });
+      this.draw(ctx, entry.entry, alpha);
+    }
+  }
+};
+
+// src/canvas/remote-measure-overlay.ts
+var MEASURE_PRESENCE_KIND = "measure";
+function isFinitePoint2(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const point = value;
+  return typeof point.x === "number" && Number.isFinite(point.x) && typeof point.y === "number" && Number.isFinite(point.y);
+}
+function isMeasurePresence(data) {
+  if (typeof data !== "object" || data === null) return false;
+  const payload = data;
+  if (payload.kind !== MEASURE_PRESENCE_KIND) return false;
+  if ("cleared" in payload) return payload.cleared === true;
+  if (!isFinitePoint2(payload.start) || !isFinitePoint2(payload.end)) return false;
+  if (typeof payload.cells !== "number" || !Number.isFinite(payload.cells)) return false;
+  if (typeof payload.feet !== "number" || !Number.isFinite(payload.feet)) return false;
+  if (payload.color !== void 0 && typeof payload.color !== "string") return false;
+  return true;
+}
+function toMeasurePresence(emission) {
+  if (emission === null) return { kind: MEASURE_PRESENCE_KIND, cleared: true };
+  return {
+    kind: MEASURE_PRESENCE_KIND,
+    start: emission.start,
+    end: emission.end,
+    cells: emission.cells,
+    feet: emission.feet,
+    color: emission.color
+  };
+}
+var DEFAULT_COLOR3 = "#FF5722";
+var RemoteMeasureOverlay = class {
+  color;
+  overlay;
+  constructor(host, options = {}) {
+    this.color = options.color ?? DEFAULT_COLOR3;
+    this.overlay = new LingerOverlay(
+      host,
+      options,
+      (ctx, entry, alpha) => drawMeasurement(ctx, entry, { alpha }),
+      () => this.now()
+    );
+  }
+  now() {
+    return performance.now();
+  }
+  /**
+   * Applies a presence payload from `sender` (any opaque per-sender key, e.g.
+   * the envelope `from`). Non-measure or malformed payloads are ignored and
+   * reported as `false`, so hosts can feed every presence frame through.
+   */
+  apply(sender, data) {
+    if (this.overlay.disposed || !isMeasurePresence(data)) return false;
+    if ("cleared" in data) {
+      this.overlay.linger(sender);
+      return true;
+    }
+    this.overlay.set(sender, {
+      start: data.start,
+      end: data.end,
+      feet: data.feet,
+      color: data.color ?? this.color
+    });
+    return true;
+  }
+  /** Removes a sender's ruler immediately (presence-leave/disconnect). */
+  remove(sender) {
+    this.overlay.remove(sender);
+  }
+  /** Removes every ruler immediately. */
+  clear() {
+    this.overlay.clear();
+  }
+  /** Number of senders with a visible (active or lingering) ruler. */
+  get activeSenderCount() {
+    return this.overlay.activeSenderCount;
+  }
+  /** Unregisters the overlay, cancels timers, stops animating. Idempotent. */
+  dispose() {
+    this.overlay.dispose();
+  }
+};
+
+// src/canvas/path-render.ts
+function resolveSegmentColors(cumulativeFeet, bands, color) {
+  const sorted = [...bands].sort((a, b) => a.feet - b.feet);
+  const out = [];
+  for (let i = 1; i < cumulativeFeet.length; i++) {
+    const end = cumulativeFeet[i] ?? 0;
+    const band = sorted.find((b) => b.feet >= end);
+    out.push(band ? band.color : color);
+  }
+  return out;
+}
+var LABEL_OFFSET_Y = 18;
+function drawPath(ctx, m, opts = {}) {
+  const first = m.points[0];
+  if (first === void 0) return;
+  ctx.save();
+  if (opts.alpha !== void 0) ctx.globalAlpha = opts.alpha;
+  ctx.lineWidth = 2;
+  let prev = first;
+  for (let i = 1; i < m.points.length; i++) {
+    const next = m.points[i];
+    if (next === void 0) break;
+    ctx.strokeStyle = m.segmentColors[i - 1] ?? m.color;
+    ctx.setLineDash([8, 4]);
+    ctx.beginPath();
+    ctx.moveTo(prev.x, prev.y);
+    ctx.lineTo(next.x, next.y);
+    ctx.stroke();
+    prev = next;
+  }
+  ctx.setLineDash([]);
+  ctx.fillStyle = m.color;
+  for (const p of m.points) {
+    ctx.beginPath();
+    ctx.arc(p.x, p.y, 4, 0, Math.PI * 2);
+    ctx.fill();
+  }
+  if (m.points.length >= 2) {
+    const last = prev;
+    const label = formatMeasureLabel(m.feet);
+    ctx.font = "14px sans-serif";
+    const metrics = ctx.measureText(label);
+    const padX = 6;
+    const padY = 4;
+    const textH = 14;
+    const cx = last.x;
+    const cy = last.y - LABEL_OFFSET_Y;
+    ctx.fillStyle = "rgba(0, 0, 0, 0.75)";
+    ctx.beginPath();
+    ctx.roundRect(
+      cx - metrics.width / 2 - padX,
+      cy - textH / 2 - padY,
+      metrics.width + padX * 2,
+      textH + padY * 2,
+      4
+    );
+    ctx.fill();
+    ctx.fillStyle = "#FFFFFF";
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    ctx.fillText(label, cx, cy);
+  }
+  ctx.restore();
+}
+
+// src/canvas/remote-path-overlay.ts
+var PATH_PRESENCE_KIND = "path";
+var PATH_PRESENCE_MAX_POINTS = 256;
+var MAX_COLOR_LENGTH = 64;
+var EPS = 1e-6;
+function isFinitePoint3(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const point = value;
+  return typeof point.x === "number" && Number.isFinite(point.x) && typeof point.y === "number" && Number.isFinite(point.y);
+}
+function isPathPresence(data) {
+  if (typeof data !== "object" || data === null) return false;
+  const payload = data;
+  if (payload.kind !== PATH_PRESENCE_KIND) return false;
+  if ("cleared" in payload) return payload.cleared === true;
+  if (!Array.isArray(payload.points)) return false;
+  if (payload.points.length === 0 || payload.points.length > PATH_PRESENCE_MAX_POINTS) return false;
+  for (const point of payload.points) {
+    if (!isFinitePoint3(point)) return false;
+  }
+  if (!Array.isArray(payload.segmentColors)) return false;
+  if (payload.segmentColors.length !== payload.points.length - 1) return false;
+  for (const color of payload.segmentColors) {
+    if (typeof color !== "string" || color.length > MAX_COLOR_LENGTH) return false;
+  }
+  if (typeof payload.feet !== "number" || !Number.isFinite(payload.feet)) return false;
+  if (payload.color !== void 0) {
+    if (typeof payload.color !== "string" || payload.color.length > MAX_COLOR_LENGTH) return false;
+  }
+  return true;
+}
+function samePoint(a, b) {
+  return Math.abs(a.x - b.x) < EPS && Math.abs(a.y - b.y) < EPS;
+}
+function toPathPresence(emission) {
+  if (emission === null) return { kind: PATH_PRESENCE_KIND, cleared: true };
+  const points = emission.waypoints.map((point) => ({ x: point.x, y: point.y }));
+  const last = points[points.length - 1];
+  const cursor = emission.cursor;
+  if (cursor && (!last || !samePoint(cursor, last))) points.push({ x: cursor.x, y: cursor.y });
+  const cumulativeFeet = [0];
+  let total = 0;
+  for (let i = 1; i < points.length; i++) {
+    total += emission.segments[i - 1]?.feet ?? 0;
+    cumulativeFeet.push(total);
+  }
+  return {
+    kind: PATH_PRESENCE_KIND,
+    points,
+    segmentColors: resolveSegmentColors(cumulativeFeet, emission.rangeBands, emission.color),
+    feet: emission.totalFeet,
+    color: emission.color
+  };
+}
+var DEFAULT_COLOR4 = "#FF5722";
+var RemotePathOverlay = class {
+  color;
+  overlay;
+  constructor(host, options = {}) {
+    this.color = options.color ?? DEFAULT_COLOR4;
+    this.overlay = new LingerOverlay(
+      host,
+      options,
+      (ctx, entry, alpha) => drawPath(ctx, entry, { alpha }),
+      () => this.now()
+    );
+  }
+  now() {
+    return performance.now();
+  }
+  /**
+   * Applies a presence payload from `sender` (any opaque per-sender key, e.g.
+   * the envelope `from`). Non-path or malformed payloads are ignored and
+   * reported as `false`, so hosts can feed every presence frame through.
+   */
+  apply(sender, data) {
+    if (this.overlay.disposed || !isPathPresence(data)) return false;
+    if ("cleared" in data) {
+      this.overlay.linger(sender);
+      return true;
     }
+    this.overlay.set(sender, {
+      points: data.points,
+      segmentColors: data.segmentColors,
+      feet: data.feet,
+      color: data.color ?? this.color
+    });
+    return true;
+  }
+  /** Removes a sender's path immediately (presence-leave/disconnect). */
+  remove(sender) {
+    this.overlay.remove(sender);
+  }
+  /** Removes every path immediately. */
+  clear() {
+    this.overlay.clear();
+  }
+  /** Number of senders with a visible (active or lingering) path. */
+  get activeSenderCount() {
+    return this.overlay.activeSenderCount;
+  }
+  /** Unregisters the overlay, cancels timers, stops animating. Idempotent. */
+  dispose() {
+    this.overlay.dispose();
   }
 };
 
 // src/canvas/ping-input.ts
 var DEFAULT_LONG_PRESS_MS = 600;
 var DEFAULT_SLOP_PX = 8;
-var DEFAULT_COLOR4 = "#ff3b30";
+var DEFAULT_COLOR5 = "#ff3b30";
 var DEFAULT_DURATION_MS2 = 1800;
 var DEFAULT_RADIUS2 = 48;
 var DEFAULT_MIN_INTERVAL_MS = 300;
@@ -11378,7 +11724,7 @@ var PingInput = class {
     this.longPressEnabled = options.longPressEnabled ?? false;
     this.longPressMs = options.longPressMs ?? DEFAULT_LONG_PRESS_MS;
     this.slopPx = options.slopPx ?? DEFAULT_SLOP_PX;
-    this.color = options.color ?? DEFAULT_COLOR4;
+    this.color = options.color ?? DEFAULT_COLOR5;
     this.durationMs = options.durationMs ?? DEFAULT_DURATION_MS2;
     this.radius = options.radius ?? DEFAULT_RADIUS2;
     this.minIntervalMs = options.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS;
@@ -12714,7 +13060,8 @@ var SelectTool = class {
         } else if (!ctx.smartGuides && ctx.gridType && "size" in el) {
           const centerX = el.position.x + el.size.w / 2 + adjDx;
           const centerY = el.position.y + el.size.h / 2 + adjDy;
-          const snappedCenter = this.snap({ x: centerX, y: centerY }, ctx);
+          const footprint = footprintFromSize(el.size, ctx.gridSize ?? 0);
+          const snappedCenter = snapFootprintCenter({ x: centerX, y: centerY }, footprint, ctx);
           ctx.store.update(id, {
             position: {
               x: snappedCenter.x - el.size.w / 2,
@@ -13292,15 +13639,15 @@ var ShapeTool = class {
   }
   onActivate(_ctx) {
     if (typeof window !== "undefined") {
-      window.addEventListener("keydown", this.onKeyDown);
-      window.addEventListener("keyup", this.onKeyUp);
+      window.addEventListener("keydown", this.trackShiftKeyDown);
+      window.addEventListener("keyup", this.trackShiftKeyUp);
     }
   }
   onDeactivate(_ctx) {
     this.shiftHeld = false;
     if (typeof window !== "undefined") {
-      window.removeEventListener("keydown", this.onKeyDown);
-      window.removeEventListener("keyup", this.onKeyUp);
+      window.removeEventListener("keydown", this.trackShiftKeyDown);
+      window.removeEventListener("keyup", this.trackShiftKeyUp);
     }
   }
   onPointerDown(state, ctx) {
@@ -13393,10 +13740,13 @@ var ShapeTool = class {
   snap(point, ctx) {
     return smartSnap(point, ctx);
   }
-  onKeyDown = (e) => {
+  // Deliberately NOT migrated to `Tool.onKeyDown`: that hook is gated by
+  // editable-target and keyboard-scope checks, and a Shift release must be
+  // observed wherever it happens or the constraint sticks after the key is up.
+  trackShiftKeyDown = (e) => {
     if (e.key === "Shift") this.shiftHeld = true;
   };
-  onKeyUp = (e) => {
+  trackShiftKeyUp = (e) => {
     if (e.key === "Shift") this.shiftHeld = false;
   };
 };
@@ -13540,6 +13890,353 @@ var MeasureTool = class {
   }
 };
 
+// src/tools/path-tool.ts
+var EPS2 = 1e-6;
+var DEFAULT_COMMIT_TAP_RADIUS_PX = 12;
+function samePoint2(a, b) {
+  return Math.abs(a.x - b.x) < EPS2 && Math.abs(a.y - b.y) < EPS2;
+}
+var PathTool = class {
+  name = "path";
+  feetPerCell;
+  color;
+  diagonalRule;
+  footprintOption;
+  rangeBands;
+  commitTapRadiusPx;
+  resolveStart;
+  waypoints = [];
+  cursor = null;
+  anchorKey;
+  footprint = 1;
+  pointerDown = false;
+  commitOnUp = false;
+  // Grid state is captured at the opening pointer-down so a path measured on
+  // one grid keeps that metric even if the host reconfigures mid-gesture.
+  gridSize = 0;
+  gridType;
+  hexOrientation;
+  snapEnabled = false;
+  optionListeners = /* @__PURE__ */ new Set();
+  pathListeners = /* @__PURE__ */ new Set();
+  commitListeners = /* @__PURE__ */ new Set();
+  emissionRafId = null;
+  constructor(options = {}) {
+    this.feetPerCell = options.feetPerCell ?? 5;
+    this.color = options.color ?? "#FF5722";
+    this.diagonalRule = options.diagonalRule ?? "euclidean";
+    this.footprintOption = options.footprint ?? 1;
+    this.rangeBands = options.rangeBands ?? [];
+    this.commitTapRadiusPx = options.commitTapRadiusPx ?? DEFAULT_COMMIT_TAP_RADIUS_PX;
+    this.resolveStart = options.resolveStart;
+  }
+  getOptions() {
+    return {
+      feetPerCell: this.feetPerCell,
+      color: this.color,
+      diagonalRule: this.diagonalRule,
+      footprint: this.footprintOption,
+      rangeBands: this.rangeBands,
+      commitTapRadiusPx: this.commitTapRadiusPx,
+      resolveStart: this.resolveStart
+    };
+  }
+  setOptions(options) {
+    if (options.feetPerCell !== void 0) this.feetPerCell = options.feetPerCell;
+    if (options.color !== void 0) this.color = options.color;
+    if (options.diagonalRule !== void 0) this.diagonalRule = options.diagonalRule;
+    if (options.footprint !== void 0) this.footprintOption = options.footprint;
+    if (options.rangeBands !== void 0) this.rangeBands = options.rangeBands;
+    if (options.commitTapRadiusPx !== void 0) {
+      this.commitTapRadiusPx = options.commitTapRadiusPx;
+    }
+    if (options.resolveStart !== void 0) this.resolveStart = options.resolveStart;
+    this.notifyOptionsChange();
+  }
+  onOptionsChange(listener) {
+    this.optionListeners.add(listener);
+    return () => this.optionListeners.delete(listener);
+  }
+  /**
+   * Subscribes to raf-coalesced path snapshots. While a path is open,
+   * listeners receive at most one snapshot per animation frame carrying the
+   * latest state; `null` is delivered synchronously when the path closes
+   * (commit, cancel, or deactivate).
+   */
+  onPath(listener) {
+    this.pathListeners.add(listener);
+    return () => this.pathListeners.delete(listener);
+  }
+  /**
+   * Subscribes to finished paths. The emission carries `cursor: null` and the
+   * final waypoints; applying the move (and recording history for it) is the
+   * host's job — the tool has already forgotten the path by then.
+   */
+  onCommit(listener) {
+    this.commitListeners.add(listener);
+    return () => this.commitListeners.delete(listener);
+  }
+  get isOpen() {
+    return this.waypoints.length > 0;
+  }
+  /** Synchronous snapshot of the open path; `null` when no path is open. */
+  getEmission() {
+    if (!this.isOpen) return null;
+    return this.buildEmission(this.cursor);
+  }
+  onPointerDown(state, ctx) {
+    const world = ctx.camera.screenToWorld({ x: state.x, y: state.y });
+    if (!this.isOpen) {
+      const anchor = this.resolveStart ? this.resolveStart(world, ctx) : { origin: world };
+      if (!anchor) return;
+      this.gridSize = ctx.gridSize ?? 0;
+      this.gridType = ctx.gridType;
+      this.hexOrientation = ctx.hexOrientation;
+      this.snapEnabled = ctx.snapToGrid === true;
+      this.footprint = anchor.footprint ?? this.footprintOption;
+      const origin = this.snap(anchor.origin);
+      this.waypoints = [origin];
+      this.cursor = { ...origin };
+      this.anchorKey = anchor.anchorKey;
+      this.pointerDown = true;
+      this.scheduleEmission();
+      ctx.requestRender();
+      return;
+    }
+    const point = this.snap(world);
+    const last = this.lastWaypoint();
+    if (last && this.withinCommitRadius(point, last, ctx)) {
+      this.commitOnUp = true;
+      this.cursor = { ...last };
+    } else {
+      this.cursor = point;
+    }
+    this.pointerDown = true;
+    this.scheduleEmission();
+    ctx.requestRender();
+  }
+  onPointerMove(state, ctx) {
+    if (!this.isOpen) return;
+    const world = ctx.camera.screenToWorld({ x: state.x, y: state.y });
+    const point = this.snap(world);
+    const last = this.lastWaypoint();
+    if (this.commitOnUp && last && this.withinCommitRadius(point, last, ctx)) {
+      this.cursor = { ...last };
+    } else {
+      this.commitOnUp = false;
+      this.cursor = point;
+    }
+    this.scheduleEmission();
+    ctx.requestRender();
+  }
+  onPointerUp(_state, ctx) {
+    if (!this.isOpen) return;
+    this.pointerDown = false;
+    if (this.commitOnUp) {
+      this.commit(ctx);
+      return;
+    }
+    const last = this.lastWaypoint();
+    if (this.cursor && last && !samePoint2(this.cursor, last)) {
+      this.waypoints.push({ ...this.cursor });
+    }
+    this.scheduleEmission();
+    ctx.requestRender();
+  }
+  onHover(state, ctx) {
+    if (!this.isOpen || this.pointerDown) return;
+    const world = ctx.camera.screenToWorld({ x: state.x, y: state.y });
+    this.cursor = this.snap(world);
+    this.scheduleEmission();
+    ctx.requestRender();
+  }
+  /** A takeover (second pointer, platform cancel) abandons the path outright. */
+  onPointerCancel(_state, ctx) {
+    this.cancel(ctx);
+  }
+  onDeactivate(ctx) {
+    this.cancel(ctx);
+  }
+  onKeyDown(event, ctx) {
+    if (!this.isOpen) return false;
+    if (event.key === "Enter") {
+      this.commit(ctx);
+      return true;
+    }
+    if (event.key === "Escape") {
+      this.cancel(ctx);
+      return true;
+    }
+    return false;
+  }
+  renderOverlay(ctx) {
+    if (!this.isOpen) return;
+    const { points, cumulative, total } = this.measure(this.cursor);
+    const cumulativeFeet = cumulative.map((cells) => cells * this.feetPerCell);
+    drawPath(ctx, {
+      points,
+      segmentColors: resolveSegmentColors(cumulativeFeet, this.rangeBands, this.color),
+      color: this.color,
+      feet: total * this.feetPerCell
+    });
+  }
+  lastWaypoint() {
+    return this.waypoints[this.waypoints.length - 1];
+  }
+  /**
+   * Is `point` close enough to `last` to mean "finish here"? EXACT match always
+   * qualifies. The screen-space tolerance is added ONLY when this path has no
+   * active snapping grid: on a snapping grid (`gridType === 'square'`, or
+   * `'hex'` with a captured orientation, and `gridSize > 0`) the adjacent
+   * cell/hex centre can be as little as one grid cell away, and a radius
+   * computed from CSS pixels has no relationship to that distance — at a
+   * sufficiently zoomed-out camera the radius would swallow a whole neighbour
+   * cell and turn a deliberate next-waypoint tap into an unwanted commit.
+   * Snapping already makes a fingertip tap land exactly on the last waypoint,
+   * so the tolerance is unnecessary there; it exists for the gridless and
+   * `snapPoint`/identity paths, where a fingertip can never land on an exact
+   * world point.
+   */
+  withinCommitRadius(point, last, ctx) {
+    if (samePoint2(point, last)) return true;
+    if (this.hasSnappingGrid()) return false;
+    const zoom = ctx.camera.zoom;
+    if (!(zoom > 0)) return false;
+    const radius = this.commitTapRadiusPx / zoom;
+    if (radius <= 0) return false;
+    const dx = point.x - last.x;
+    const dy = point.y - last.y;
+    return dx * dx + dy * dy <= radius * radius;
+  }
+  /**
+   * True when this path's captured grid state snaps every waypoint onto a
+   * cell/hex centre: a `square` grid, or a `hex` grid with a captured
+   * orientation, both with a usable `gridSize`. Mirrors the unconditional
+   * branches of `snap` below — NOT the `snapToGrid`-gated fallback, which
+   * leaves waypoints unsnapped when the user turns snapping off.
+   */
+  hasSnappingGrid() {
+    if (!(this.gridSize > 0)) return false;
+    if (this.gridType === "square") return true;
+    return this.gridType === "hex" && this.hexOrientation !== void 0;
+  }
+  /**
+   * Snapping to cell or hex centres is UNCONDITIONAL for a `square` grid, or a
+   * `hex` grid WITH a captured orientation: a movement path measures in cells,
+   * so an unsnapped waypoint would report a distance the grid does not agree
+   * with. A `hex` grid WITHOUT an orientation falls through to the
+   * `snapToGrid`-gated `snapPoint` (intersection) branch below, same as the
+   * gridType-less case — unlike `smartSnap`, which is off entirely when the
+   * user turns snapping off.
+   */
+  snap(point) {
+    if (this.gridSize <= 0) return point;
+    if (this.gridType === "hex" && this.hexOrientation) {
+      return snapToHexCenter(point, this.gridSize, this.hexOrientation);
+    }
+    if (this.gridType === "square") {
+      return snapToCellCenter(point, this.gridSize, this.footprint);
+    }
+    if (this.snapEnabled) {
+      return snapPoint(point, this.gridSize);
+    }
+    return point;
+  }
+  /** The measured polyline: waypoints, plus the cursor when it adds a leg. */
+  measure(cursor) {
+    const points = this.waypoints.map((p) => ({ ...p }));
+    const last = points[points.length - 1];
+    if (cursor && (!last || !samePoint2(cursor, last))) points.push({ ...cursor });
+    const { total, cumulative } = pathDistanceCells(points, {
+      gridSize: this.gridSize,
+      gridType: this.gridType,
+      hexOrientation: this.hexOrientation,
+      diagonalRule: this.diagonalRule
+    });
+    return { points, cumulative, total };
+  }
+  buildEmission(cursor) {
+    const { cumulative, total } = this.measure(cursor);
+    const segments = [];
+    for (let i = 1; i < cumulative.length; i++) {
+      const cells = (cumulative[i] ?? 0) - (cumulative[i - 1] ?? 0);
+      segments.push({ cells, feet: cells * this.feetPerCell });
+    }
+    return {
+      anchorKey: this.anchorKey,
+      waypoints: this.waypoints.map((p) => ({ ...p })),
+      cursor: cursor ? { ...cursor } : null,
+      segments,
+      totalCells: total,
+      totalFeet: total * this.feetPerCell,
+      color: this.color,
+      rangeBands: this.rangeBands
+    };
+  }
+  commit(ctx) {
+    if (this.waypoints.length < 2) {
+      this.cancel(ctx);
+      return;
+    }
+    const emission = this.buildEmission(null);
+    this.reset();
+    this.emitCommit(emission);
+    this.emitClear();
+    ctx.requestRender();
+  }
+  cancel(ctx) {
+    if (!this.isOpen) return;
+    this.reset();
+    this.emitClear();
+    ctx.requestRender();
+  }
+  reset() {
+    this.waypoints = [];
+    this.cursor = null;
+    this.anchorKey = void 0;
+    this.footprint = this.footprintOption;
+    this.pointerDown = false;
+    this.commitOnUp = false;
+  }
+  notifyOptionsChange() {
+    for (const listener of this.optionListeners) listener();
+  }
+  scheduleEmission() {
+    if (this.pathListeners.size === 0) return;
+    if (this.emissionRafId !== null) return;
+    this.emissionRafId = requestAnimationFrame(() => {
+      this.emissionRafId = null;
+      const emission = this.getEmission();
+      if (!emission) return;
+      this.emitPath(emission);
+    });
+  }
+  emitClear() {
+    if (this.emissionRafId !== null) {
+      cancelAnimationFrame(this.emissionRafId);
+      this.emissionRafId = null;
+    }
+    if (this.pathListeners.size === 0) return;
+    this.emitPath(null);
+  }
+  emitPath(emission) {
+    for (const listener of this.pathListeners) {
+      try {
+        listener(emission);
+      } catch {
+      }
+    }
+  }
+  emitCommit(emission) {
+    for (const listener of this.commitListeners) {
+      try {
+        listener(emission);
+      } catch {
+      }
+    }
+  }
+};
+
 // src/tools/template-tool.ts
 var MIN_RECT_WIDTH = 20;
 function defaultRectWidth(radius, scaleUnit) {
@@ -13833,7 +14530,7 @@ var TemplateTool = class {
 };
 
 // src/tools/laser-tool.ts
-var DEFAULT_COLOR5 = "#ff3b30";
+var DEFAULT_COLOR6 = "#ff3b30";
 var DEFAULT_WIDTH3 = 4;
 var DEFAULT_FADE_MS3 = 1200;
 var LaserTool = class {
@@ -13849,7 +14546,7 @@ var LaserTool = class {
   pendingEmission = [];
   constructor(options = {}) {
     this.name = options.name ?? "laser";
-    this.color = options.color ?? DEFAULT_COLOR5;
+    this.color = options.color ?? DEFAULT_COLOR6;
     this.width = options.width ?? DEFAULT_WIDTH3;
     this.fadeMs = options.fadeMs ?? DEFAULT_FADE_MS3;
   }
@@ -13977,7 +14674,7 @@ var LaserTool = class {
 };
 
 // src/tools/ping-tool.ts
-var DEFAULT_COLOR6 = "#ff3b30";
+var DEFAULT_COLOR7 = "#ff3b30";
 var DEFAULT_DURATION_MS4 = 1800;
 var DEFAULT_RADIUS4 = 48;
 var DEFAULT_MIN_INTERVAL_MS2 = 300;
@@ -13994,7 +14691,7 @@ var PingTool = class {
   pingListeners = /* @__PURE__ */ new Set();
   constructor(options = {}) {
     this.name = options.name ?? "ping";
-    this.color = options.color ?? DEFAULT_COLOR6;
+    this.color = options.color ?? DEFAULT_COLOR7;
     this.durationMs = options.durationMs ?? DEFAULT_DURATION_MS4;
     this.radius = options.radius ?? DEFAULT_RADIUS4;
     this.minIntervalMs = options.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS2;
@@ -14097,7 +14794,7 @@ var PingTool = class {
 };
 
 // src/index.ts
-var VERSION = "0.63.0";
+var VERSION = "0.64.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ArrowTool,
@@ -14124,13 +14821,17 @@ var VERSION = "0.63.0";
   MemoryAdapter,
   MinimapController,
   NoteTool,
+  PATH_PRESENCE_KIND,
+  PATH_PRESENCE_MAX_POINTS,
   PING_PRESENCE_KIND,
+  PathTool,
   PencilTool,
   PingInput,
   PingTool,
   RemoteFocusReceiver,
   RemoteLaserOverlay,
   RemoteMeasureOverlay,
+  RemotePathOverlay,
   RemotePingOverlay,
   SelectTool,
   ShapeTool,
@@ -14158,6 +14859,7 @@ var VERSION = "0.63.0";
   exportImage,
   exportSvg,
   fitZoomForView,
+  footprintFromSize,
   getActiveFormats,
   getArrowBounds,
   getArrowControlPoint,
@@ -14173,20 +14875,26 @@ var VERSION = "0.63.0";
   getHexCellsInRectangle,
   getHexCellsInSquare,
   getHexDistance,
+  gridDistanceCells,
   isFocusPresence,
   isLaserTrailPresence,
   isMeasurePresence,
   isNearBezier,
+  isPathPresence,
   isPingPresence,
+  pathDistanceCells,
   resolveHtmlRouting,
   setFontSize,
   smartSnap,
+  snapFootprintCenter,
   snapPoint,
+  snapToCellCenter,
   snapToHexCenter,
   styleToPatch,
   toFocusPresence,
   toLaserTrailPresence,
   toMeasurePresence,
+  toPathPresence,
   toPingPresence,
   toggleBold,
   toggleItalic,