@fieldnotes/core 0.53.0 → 0.55.0

package/dist/index.cjs

@@ -30,13 +30,18 @@ __export(index_exports, {
   HistoryStack: () => HistoryStack,
   ImageTool: () => ImageTool,
   IndexedDBAdapter: () => IndexedDBAdapter,
+  LASER_TRAIL_PRESENCE_KIND: () => LASER_TRAIL_PRESENCE_KIND,
   LaserTool: () => LaserTool,
   LayerManager: () => LayerManager,
   LocalStorageAdapter: () => LocalStorageAdapter,
   MeasureTool: () => MeasureTool,
   MemoryAdapter: () => MemoryAdapter,
   NoteTool: () => NoteTool,
+  PING_PRESENCE_KIND: () => PING_PRESENCE_KIND,
   PencilTool: () => PencilTool,
+  PingTool: () => PingTool,
+  RemoteLaserOverlay: () => RemoteLaserOverlay,
+  RemotePingOverlay: () => RemotePingOverlay,
   SelectTool: () => SelectTool,
   ShapeTool: () => ShapeTool,
   TemplateTool: () => TemplateTool,
@@ -72,12 +77,16 @@ __export(index_exports, {
   getHexCellsInRectangle: () => getHexCellsInRectangle,
   getHexCellsInSquare: () => getHexCellsInSquare,
   getHexDistance: () => getHexDistance,
+  isLaserTrailPresence: () => isLaserTrailPresence,
   isNearBezier: () => isNearBezier,
+  isPingPresence: () => isPingPresence,
   setFontSize: () => setFontSize,
   smartSnap: () => smartSnap,
   snapPoint: () => snapPoint,
   snapToHexCenter: () => snapToHexCenter,
   styleToPatch: () => styleToPatch,
+  toLaserTrailPresence: () => toLaserTrailPresence,
+  toPingPresence: () => toPingPresence,
   toggleBold: () => toggleBold,
   toggleItalic: () => toggleItalic,
   toggleStrikethrough: () => toggleStrikethrough,
@@ -6922,6 +6931,7 @@ var RenderLoop = class {
   // set on recenter/viewport-change; consumed by the grid block
   stats = new RenderStats();
   layerGroups = /* @__PURE__ */ new Map();
+  overlays = /* @__PURE__ */ new Set();
   gridCacheCanvas = null;
   gridCacheCtx = null;
   lastGridRefs = [];
@@ -6980,6 +6990,29 @@ var RenderLoop = class {
   getStats() {
     return this.stats.getSnapshot();
   }
+  /**
+   * Registers a viewport overlay drawn beneath the active tool's own overlay.
+   * Returns an idempotent unsubscribe that also erases the overlay's last
+   * frame.
+   */
+  registerOverlay(draw) {
+    this.overlays.add(draw);
+    this.requestRender();
+    return () => {
+      if (this.overlays.delete(draw)) this.requestRender();
+    };
+  }
+  drawRegisteredOverlays(ctx) {
+    for (const draw of this.overlays) {
+      ctx.save();
+      try {
+        draw(ctx);
+      } catch {
+      } finally {
+        ctx.restore();
+      }
+    }
+  }
   compositeLayerCache(ctx, layerId, opacity) {
     const cached = this.layerCache.getCanvas(layerId);
     const offset = this.marginViewport.compositeOffset(
@@ -7113,7 +7146,8 @@ var RenderLoop = class {
     }
     const activeTool = this.toolManager.activeTool;
     const overlayOrder = visibleElements.length + 1;
-    if (hybridActive && activeTool?.renderOverlay) hybridOrders.add(overlayOrder);
+    const hasOverlay = activeTool?.renderOverlay !== void 0 || this.overlays.size > 0;
+    if (hybridActive && hasOverlay) hybridOrders.add(overlayOrder);
     this.hybridSurface.beginFrame(hybridOrders, this.canvasEl.width, this.canvasEl.height);
     for (const [layerId, elements] of this.layerGroups) {
       const isActiveDrawingLayer = layerId === this.activeDrawingLayerId;
@@ -7223,7 +7257,7 @@ var RenderLoop = class {
       hybridCtx.restore();
     }
     const overlayT0 = performance.now();
-    if (hybridActive && activeTool?.renderOverlay) {
+    if (hybridActive && hasOverlay) {
       const overlayCtx = this.hybridSurface.getContext(overlayOrder);
       if (overlayCtx) {
         overlayCtx.clearRect(0, 0, this.canvasEl.width, this.canvasEl.height);
@@ -7231,11 +7265,13 @@ var RenderLoop = class {
         overlayCtx.scale(dpr, dpr);
         overlayCtx.translate(this.camera.position.x, this.camera.position.y);
         overlayCtx.scale(this.camera.zoom, this.camera.zoom);
-        activeTool.renderOverlay(overlayCtx);
+        this.drawRegisteredOverlays(overlayCtx);
+        if (activeTool?.renderOverlay) activeTool.renderOverlay(overlayCtx);
         overlayCtx.restore();
       }
-    } else if (activeTool?.renderOverlay) {
-      activeTool.renderOverlay(ctx);
+    } else if (hasOverlay) {
+      this.drawRegisteredOverlays(ctx);
+      if (activeTool?.renderOverlay) activeTool.renderOverlay(ctx);
     }
     const overlayMs = performance.now() - overlayT0;
     ctx.restore();
@@ -8229,6 +8265,17 @@ var Viewport = class {
   requestRender() {
     this.renderLoop.requestRender();
   }
+  /**
+   * Registers a world-space overlay drawn above elements on every frame,
+   * regardless of the active tool — the surface for remote presence visuals
+   * such as laser trails, cursors, pings, and shared rulers. Overlays draw
+   * beneath the active tool's own `renderOverlay` and never touch elements,
+   * history, or persisted state. Returns an idempotent unsubscribe that also
+   * erases the overlay's last frame.
+   */
+  registerOverlay(draw) {
+    return this.renderLoop.registerOverlay(draw);
+  }
   exportState() {
     return exportState(
       this.store.snapshot(),
@@ -8576,6 +8623,324 @@ var Viewport = class {
   }
 };
 
+// src/canvas/remote-laser-overlay.ts
+var LASER_TRAIL_PRESENCE_KIND = "laser";
+function isFinitePoint(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 isLaserTrailPresence(data) {
+  if (typeof data !== "object" || data === null) return false;
+  const payload = data;
+  if (payload.kind !== LASER_TRAIL_PRESENCE_KIND) return false;
+  if (!Array.isArray(payload.points) || !payload.points.every(isFinitePoint)) return false;
+  if (payload.color !== void 0 && typeof payload.color !== "string") return false;
+  if (payload.width !== void 0 && !(typeof payload.width === "number" && payload.width > 0)) {
+    return false;
+  }
+  if (payload.fadeMs !== void 0 && !(typeof payload.fadeMs === "number" && payload.fadeMs > 0)) {
+    return false;
+  }
+  return true;
+}
+function toLaserTrailPresence(emission) {
+  return {
+    kind: LASER_TRAIL_PRESENCE_KIND,
+    points: emission.points.map((point) => ({ x: point.x, y: point.y })),
+    color: emission.color,
+    width: emission.width,
+    fadeMs: emission.fadeMs
+  };
+}
+var DEFAULT_COLOR = "#ff3b30";
+var DEFAULT_WIDTH = 4;
+var DEFAULT_FADE_MS = 1200;
+var DEFAULT_MAX_POINTS = 512;
+var RemoteLaserOverlay = class {
+  host;
+  color;
+  width;
+  fadeMs;
+  maxPointsPerSender;
+  trails = /* @__PURE__ */ new Map();
+  unregister;
+  rafId = null;
+  disposed = false;
+  constructor(host, options = {}) {
+    this.host = host;
+    this.color = options.color ?? DEFAULT_COLOR;
+    this.width = options.width ?? DEFAULT_WIDTH;
+    this.fadeMs = options.fadeMs ?? DEFAULT_FADE_MS;
+    this.maxPointsPerSender = options.maxPointsPerSender ?? DEFAULT_MAX_POINTS;
+    this.unregister = host.registerOverlay((ctx) => this.renderTrails(ctx));
+  }
+  now() {
+    return performance.now();
+  }
+  /**
+   * Applies a presence payload from `sender` (any opaque per-sender key, e.g.
+   * the envelope `from`). Non-laser or malformed payloads are ignored and
+   * reported as `false`, so hosts can feed every presence frame through.
+   */
+  apply(sender, data) {
+    if (this.disposed || !isLaserTrailPresence(data)) return false;
+    let trail = this.trails.get(sender);
+    if (!trail) {
+      trail = { points: [], color: this.color, width: this.width, fadeMs: this.fadeMs };
+      this.trails.set(sender, trail);
+    }
+    trail.color = data.color ?? this.color;
+    trail.width = data.width ?? this.width;
+    trail.fadeMs = data.fadeMs ?? this.fadeMs;
+    const t = this.now();
+    for (const point of data.points) {
+      trail.points.push({ x: point.x, y: point.y, t });
+    }
+    const excess = trail.points.length - this.maxPointsPerSender;
+    if (excess > 0) trail.points.splice(0, excess);
+    this.ensureAnimating();
+    this.host.requestRender();
+    return true;
+  }
+  /** Removes a sender's trail immediately (presence-leave/disconnect). */
+  remove(sender) {
+    if (this.trails.delete(sender)) this.host.requestRender();
+  }
+  /** Removes every trail immediately. */
+  clear() {
+    if (this.trails.size === 0) return;
+    this.trails.clear();
+    this.host.requestRender();
+  }
+  /** Number of senders with a live (unfaded) trail. */
+  get activeSenderCount() {
+    return this.trails.size;
+  }
+  /** Unregisters the overlay and stops the fade loop. Idempotent. */
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    if (this.rafId !== null) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = null;
+    }
+    this.trails.clear();
+    this.unregister?.();
+    this.unregister = null;
+  }
+  ensureAnimating() {
+    if (this.rafId === null) {
+      this.rafId = requestAnimationFrame(() => this.tick());
+    }
+  }
+  tick() {
+    if (this.disposed) return;
+    const now = this.now();
+    for (const [sender, trail] of this.trails) {
+      const cutoff = now - trail.fadeMs;
+      trail.points = trail.points.filter((point) => point.t >= cutoff);
+      if (trail.points.length === 0) this.trails.delete(sender);
+    }
+    this.host.requestRender();
+    this.rafId = this.trails.size > 0 ? requestAnimationFrame(() => this.tick()) : null;
+  }
+  renderTrails(ctx) {
+    if (this.trails.size === 0) return;
+    const now = this.now();
+    for (const trail of this.trails.values()) {
+      if (trail.points.length < 2) continue;
+      ctx.save();
+      ctx.strokeStyle = trail.color;
+      ctx.lineWidth = trail.width;
+      ctx.lineCap = "round";
+      ctx.lineJoin = "round";
+      for (let i = 0; i < trail.points.length - 1; i++) {
+        const a = trail.points[i];
+        const b = trail.points[i + 1];
+        if (!a || !b) continue;
+        const age = now - b.t;
+        ctx.globalAlpha = Math.max(0, 1 - age / trail.fadeMs);
+        ctx.beginPath();
+        ctx.moveTo(a.x, a.y);
+        ctx.lineTo(b.x, b.y);
+        ctx.stroke();
+      }
+      ctx.restore();
+    }
+  }
+};
+
+// src/canvas/ping-pulse.ts
+var RIPPLE_OFFSETS = [0, 0.25];
+function easeOutCubic(t) {
+  const inv = 1 - t;
+  return 1 - inv * inv * inv;
+}
+function renderPingPulse(ctx, x, y, ageMs, style) {
+  if (ageMs < 0 || ageMs >= style.durationMs) return;
+  ctx.save();
+  ctx.strokeStyle = style.color;
+  ctx.fillStyle = style.color;
+  for (const offset of RIPPLE_OFFSETS) {
+    const rippleSpan = style.durationMs * (1 - offset);
+    const rippleAge = ageMs - style.durationMs * offset;
+    if (rippleAge < 0) continue;
+    const progress = Math.min(1, rippleAge / rippleSpan);
+    const rippleRadius = style.radius * easeOutCubic(progress);
+    if (rippleRadius <= 0) continue;
+    ctx.globalAlpha = Math.max(0, 1 - progress);
+    ctx.lineWidth = Math.max(1.5, style.radius / 12);
+    ctx.beginPath();
+    ctx.arc(x, y, rippleRadius, 0, Math.PI * 2);
+    ctx.stroke();
+  }
+  const dotProgress = ageMs / style.durationMs;
+  ctx.globalAlpha = Math.max(0, 1 - Math.max(0, dotProgress - 0.5) * 2);
+  ctx.beginPath();
+  ctx.arc(x, y, Math.max(2, style.radius / 8), 0, Math.PI * 2);
+  ctx.fill();
+  ctx.restore();
+}
+
+// src/canvas/remote-ping-overlay.ts
+var PING_PRESENCE_KIND = "ping";
+function isPingPresence(data) {
+  if (typeof data !== "object" || data === null) return false;
+  const payload = data;
+  if (payload.kind !== PING_PRESENCE_KIND) return false;
+  if (typeof payload.x !== "number" || !Number.isFinite(payload.x)) return false;
+  if (typeof payload.y !== "number" || !Number.isFinite(payload.y)) return false;
+  if (payload.color !== void 0 && typeof payload.color !== "string") return false;
+  if (payload.durationMs !== void 0 && !(typeof payload.durationMs === "number" && Number.isFinite(payload.durationMs) && payload.durationMs > 0)) {
+    return false;
+  }
+  if (payload.radius !== void 0 && !(typeof payload.radius === "number" && Number.isFinite(payload.radius) && payload.radius > 0)) {
+    return false;
+  }
+  return true;
+}
+function toPingPresence(emission) {
+  return {
+    kind: PING_PRESENCE_KIND,
+    x: emission.x,
+    y: emission.y,
+    color: emission.color,
+    durationMs: emission.durationMs,
+    radius: emission.radius
+  };
+}
+var DEFAULT_COLOR2 = "#ff3b30";
+var DEFAULT_DURATION_MS = 1800;
+var DEFAULT_RADIUS = 48;
+var DEFAULT_MAX_PINGS = 8;
+var RemotePingOverlay = class {
+  host;
+  color;
+  durationMs;
+  radius;
+  maxPingsPerSender;
+  pings = /* @__PURE__ */ new Map();
+  unregister;
+  rafId = null;
+  disposed = false;
+  constructor(host, options = {}) {
+    this.host = host;
+    this.color = options.color ?? DEFAULT_COLOR2;
+    this.durationMs = options.durationMs ?? DEFAULT_DURATION_MS;
+    this.radius = options.radius ?? DEFAULT_RADIUS;
+    this.maxPingsPerSender = options.maxPingsPerSender ?? DEFAULT_MAX_PINGS;
+    this.unregister = host.registerOverlay((ctx) => this.renderPings(ctx));
+  }
+  now() {
+    return performance.now();
+  }
+  /**
+   * Applies a presence payload from `sender` (any opaque per-sender key, e.g.
+   * the envelope `from`). Non-ping or malformed payloads are ignored and
+   * reported as `false`, so hosts can feed every presence frame through.
+   */
+  apply(sender, data) {
+    if (this.disposed || !isPingPresence(data)) return false;
+    let senderPings = this.pings.get(sender);
+    if (!senderPings) {
+      senderPings = [];
+      this.pings.set(sender, senderPings);
+    }
+    senderPings.push({
+      x: data.x,
+      y: data.y,
+      t: this.now(),
+      color: data.color ?? this.color,
+      durationMs: data.durationMs ?? this.durationMs,
+      radius: data.radius ?? this.radius
+    });
+    const excess = senderPings.length - this.maxPingsPerSender;
+    if (excess > 0) senderPings.splice(0, excess);
+    this.ensureAnimating();
+    this.host.requestRender();
+    return true;
+  }
+  /** Removes a sender's pings immediately (presence-leave/disconnect). */
+  remove(sender) {
+    if (this.pings.delete(sender)) this.host.requestRender();
+  }
+  /** Removes every ping immediately. */
+  clear() {
+    if (this.pings.size === 0) return;
+    this.pings.clear();
+    this.host.requestRender();
+  }
+  /** Number of senders with a live (unexpired) ping. */
+  get activeSenderCount() {
+    return this.pings.size;
+  }
+  /** Unregisters the overlay and stops the animation loop. Idempotent. */
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    if (this.rafId !== null) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = null;
+    }
+    this.pings.clear();
+    this.unregister?.();
+    this.unregister = null;
+  }
+  ensureAnimating() {
+    if (this.rafId === null) {
+      this.rafId = requestAnimationFrame(() => this.tick());
+    }
+  }
+  tick() {
+    if (this.disposed) return;
+    const now = this.now();
+    for (const [sender, senderPings] of this.pings) {
+      const live = senderPings.filter((ping) => now - ping.t < ping.durationMs);
+      if (live.length === 0) {
+        this.pings.delete(sender);
+      } else {
+        this.pings.set(sender, live);
+      }
+    }
+    this.host.requestRender();
+    this.rafId = this.pings.size > 0 ? requestAnimationFrame(() => this.tick()) : null;
+  }
+  renderPings(ctx) {
+    if (this.pings.size === 0) return;
+    const now = this.now();
+    for (const senderPings of this.pings.values()) {
+      for (const ping of senderPings) {
+        renderPingPulse(ctx, ping.x, ping.y, now - ping.t, {
+          color: ping.color,
+          durationMs: ping.durationMs,
+          radius: ping.radius
+        });
+      }
+    }
+  }
+};
+
 // src/tools/hand-tool.ts
 var HandTool = class {
   name = "hand";
@@ -8837,7 +9202,7 @@ function erasePoints(points, eraser, radius) {
 }
 
 // src/tools/eraser-tool.ts
-var DEFAULT_RADIUS = 20;
+var DEFAULT_RADIUS2 = 20;
 function makeEraserCursor(radius) {
   const size = radius * 2;
   const svg = `<svg xmlns='http://www.w3.org/2000/svg' width='${size}' height='${size}'><circle cx='${radius}' cy='${radius}' r='${radius - 1}' fill='none' stroke='%23666' stroke-width='1.5'/></svg>`;
@@ -8850,7 +9215,7 @@ var EraserTool = class {
   cursor;
   mode;
   constructor(options = {}) {
-    this.radius = options.radius ?? DEFAULT_RADIUS;
+    this.radius = options.radius ?? DEFAULT_RADIUS2;
     this.cursor = makeEraserCursor(this.radius);
     this.mode = options.mode ?? "partial";
   }
@@ -11132,9 +11497,9 @@ var TemplateTool = class {
 };
 
 // src/tools/laser-tool.ts
-var DEFAULT_COLOR = "#ff3b30";
-var DEFAULT_WIDTH = 4;
-var DEFAULT_FADE_MS = 1200;
+var DEFAULT_COLOR3 = "#ff3b30";
+var DEFAULT_WIDTH2 = 4;
+var DEFAULT_FADE_MS2 = 1200;
 var LaserTool = class {
   name;
   color;
@@ -11144,11 +11509,13 @@ var LaserTool = class {
   rafId = null;
   drawing = false;
   optionListeners = /* @__PURE__ */ new Set();
+  trailListeners = /* @__PURE__ */ new Set();
+  pendingEmission = [];
   constructor(options = {}) {
     this.name = options.name ?? "laser";
-    this.color = options.color ?? DEFAULT_COLOR;
-    this.width = options.width ?? DEFAULT_WIDTH;
-    this.fadeMs = options.fadeMs ?? DEFAULT_FADE_MS;
+    this.color = options.color ?? DEFAULT_COLOR3;
+    this.width = options.width ?? DEFAULT_WIDTH2;
+    this.fadeMs = options.fadeMs ?? DEFAULT_FADE_MS2;
   }
   now() {
     return performance.now();
@@ -11163,6 +11530,7 @@ var LaserTool = class {
     }
     this.trail = [];
     this.drawing = false;
+    this.pendingEmission = [];
     ctx.setCursor?.("default");
     ctx.requestRender();
   }
@@ -11178,6 +11546,16 @@ var LaserTool = class {
     this.optionListeners.add(listener);
     return () => this.optionListeners.delete(listener);
   }
+  /**
+   * Subscribes to coalesced trail emissions. Points recorded by pointer input
+   * are batched and delivered at most once per animation frame, keeping
+   * outgoing presence packets small. Listeners must not throw; a throwing
+   * listener is isolated so it cannot stall the fade loop.
+   */
+  onTrail(listener) {
+    this.trailListeners.add(listener);
+    return () => this.trailListeners.delete(listener);
+  }
   setOptions(options) {
     if (options.color !== void 0) this.color = options.color;
     if (options.width !== void 0) this.width = options.width;
@@ -11186,14 +11564,18 @@ var LaserTool = class {
   }
   onPointerDown(state, ctx) {
     this.drawing = true;
-    const world = ctx.camera.screenToWorld({ x: state.x, y: state.y });
-    this.trail.push({ x: world.x, y: world.y, t: this.now() });
-    this.ensureAnimating(ctx);
+    this.recordPoint(state, ctx);
   }
   onPointerMove(state, ctx) {
     if (!this.drawing) return;
+    this.recordPoint(state, ctx);
+  }
+  recordPoint(state, ctx) {
     const world = ctx.camera.screenToWorld({ x: state.x, y: state.y });
     this.trail.push({ x: world.x, y: world.y, t: this.now() });
+    if (this.trailListeners.size > 0) {
+      this.pendingEmission.push({ x: world.x, y: world.y });
+    }
     this.ensureAnimating(ctx);
   }
   onPointerUp(_state, _ctx) {
@@ -11225,7 +11607,24 @@ var LaserTool = class {
       this.rafId = requestAnimationFrame(() => this.tick(ctx));
     }
   }
+  flushEmission() {
+    if (this.pendingEmission.length === 0) return;
+    const emission = {
+      points: this.pendingEmission,
+      color: this.color,
+      width: this.width,
+      fadeMs: this.fadeMs
+    };
+    this.pendingEmission = [];
+    for (const listener of this.trailListeners) {
+      try {
+        listener(emission);
+      } catch {
+      }
+    }
+  }
   tick(ctx) {
+    this.flushEmission();
     const cutoff = this.now() - this.fadeMs;
     this.trail = this.trail.filter((p) => p.t >= cutoff);
     if (this.trail.length > 0) {
@@ -11241,8 +11640,128 @@ var LaserTool = class {
   }
 };
 
+// src/tools/ping-tool.ts
+var DEFAULT_COLOR4 = "#ff3b30";
+var DEFAULT_DURATION_MS2 = 1800;
+var DEFAULT_RADIUS3 = 48;
+var DEFAULT_MIN_INTERVAL_MS = 300;
+var PingTool = class {
+  name;
+  color;
+  durationMs;
+  radius;
+  minIntervalMs;
+  pings = [];
+  lastEmitAt = -Infinity;
+  rafId = null;
+  optionListeners = /* @__PURE__ */ new Set();
+  pingListeners = /* @__PURE__ */ new Set();
+  constructor(options = {}) {
+    this.name = options.name ?? "ping";
+    this.color = options.color ?? DEFAULT_COLOR4;
+    this.durationMs = options.durationMs ?? DEFAULT_DURATION_MS2;
+    this.radius = options.radius ?? DEFAULT_RADIUS3;
+    this.minIntervalMs = options.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS;
+  }
+  now() {
+    return performance.now();
+  }
+  onActivate(ctx) {
+    ctx.setCursor?.("crosshair");
+  }
+  onDeactivate(ctx) {
+    if (this.rafId !== null) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = null;
+    }
+    this.pings = [];
+    ctx.setCursor?.("default");
+    ctx.requestRender();
+  }
+  getOptions() {
+    return {
+      name: this.name,
+      color: this.color,
+      durationMs: this.durationMs,
+      radius: this.radius,
+      minIntervalMs: this.minIntervalMs
+    };
+  }
+  setOptions(options) {
+    if (options.color !== void 0) this.color = options.color;
+    if (options.durationMs !== void 0) this.durationMs = options.durationMs;
+    if (options.radius !== void 0) this.radius = options.radius;
+    if (options.minIntervalMs !== void 0) this.minIntervalMs = options.minIntervalMs;
+    this.notifyOptionsChange();
+  }
+  onOptionsChange(listener) {
+    this.optionListeners.add(listener);
+    return () => this.optionListeners.delete(listener);
+  }
+  /**
+   * Subscribes to accepted pings. Listeners must not throw; a throwing
+   * listener is isolated so it cannot break the tap handling or other
+   * listeners.
+   */
+  onPing(listener) {
+    this.pingListeners.add(listener);
+    return () => this.pingListeners.delete(listener);
+  }
+  onPointerDown(state, ctx) {
+    const t = this.now();
+    if (t - this.lastEmitAt < this.minIntervalMs) return;
+    this.lastEmitAt = t;
+    const world = ctx.camera.screenToWorld({ x: state.x, y: state.y });
+    this.pings.push({ x: world.x, y: world.y, t });
+    const emission = {
+      x: world.x,
+      y: world.y,
+      color: this.color,
+      durationMs: this.durationMs,
+      radius: this.radius
+    };
+    for (const listener of this.pingListeners) {
+      try {
+        listener(emission);
+      } catch {
+      }
+    }
+    this.ensureAnimating(ctx);
+    ctx.requestRender();
+  }
+  onPointerMove(_state, _ctx) {
+  }
+  onPointerUp(_state, _ctx) {
+  }
+  renderOverlay(ctx) {
+    if (this.pings.length === 0) return;
+    const now = this.now();
+    for (const ping of this.pings) {
+      renderPingPulse(ctx, ping.x, ping.y, now - ping.t, {
+        color: this.color,
+        durationMs: this.durationMs,
+        radius: this.radius
+      });
+    }
+  }
+  ensureAnimating(ctx) {
+    if (this.rafId === null) {
+      this.rafId = requestAnimationFrame(() => this.tick(ctx));
+    }
+  }
+  tick(ctx) {
+    const cutoff = this.now() - this.durationMs;
+    this.pings = this.pings.filter((ping) => ping.t > cutoff);
+    ctx.requestRender();
+    this.rafId = this.pings.length > 0 ? requestAnimationFrame(() => this.tick(ctx)) : null;
+  }
+  notifyOptionsChange() {
+    for (const listener of this.optionListeners) listener();
+  }
+};
+
 // src/index.ts
-var VERSION = "0.53.0";
+var VERSION = "0.55.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ArrowTool,
@@ -11255,13 +11774,18 @@ var VERSION = "0.53.0";
   HistoryStack,
   ImageTool,
   IndexedDBAdapter,
+  LASER_TRAIL_PRESENCE_KIND,
   LaserTool,
   LayerManager,
   LocalStorageAdapter,
   MeasureTool,
   MemoryAdapter,
   NoteTool,
+  PING_PRESENCE_KIND,
   PencilTool,
+  PingTool,
+  RemoteLaserOverlay,
+  RemotePingOverlay,
   SelectTool,
   ShapeTool,
   TemplateTool,
@@ -11297,12 +11821,16 @@ var VERSION = "0.53.0";
   getHexCellsInRectangle,
   getHexCellsInSquare,
   getHexDistance,
+  isLaserTrailPresence,
   isNearBezier,
+  isPingPresence,
   setFontSize,
   smartSnap,
   snapPoint,
   snapToHexCenter,
   styleToPatch,
+  toLaserTrailPresence,
+  toPingPresence,
   toggleBold,
   toggleItalic,
   toggleStrikethrough,