@fieldnotes/core 0.55.0 → 0.56.0

package/dist/index.d.cts

@@ -986,6 +986,120 @@ declare class RemotePingOverlay {
     private renderPings;
 }
 
+/**
+ * The one camera capability `PingInput` needs; `Camera` satisfies it. Screen
+ * coordinates are element-local (the same space `Camera.screenToWorld`
+ * expects).
+ */
+interface PingInputHost {
+    screenToWorld(screen: Point): Point;
+}
+interface PingInputOptions {
+    /**
+     * Opt-in for the long-press gesture. Off by default: a hidden hold-to-ping
+     * gesture surprises users outside shared-canvas products, so hosts enable
+     * it deliberately. The keyboard/programmatic paths (`pingAtPointer`,
+     * `pingAt`) are always available. Default `false`.
+     */
+    longPressEnabled?: boolean;
+    /** Hold duration before a still press pings. Default `600`. */
+    longPressMs?: number;
+    /** Maximum pointer travel while holding; moving further cancels. Default `8`. */
+    slopPx?: number;
+    /** Emission style forwarded to hosts; matches `PingTool` defaults. */
+    color?: string;
+    durationMs?: number;
+    radius?: number;
+    /**
+     * Minimum interval between emitted pings, shared across the long-press and
+     * keyboard/programmatic paths. Faster pings are dropped entirely. Default
+     * `300`.
+     */
+    minIntervalMs?: number;
+    /**
+     * Host veto consulted at fire time on every path (e.g. return `false` while
+     * a ping tool is active to avoid double pings). A veto does not consume the
+     * rate-limit interval.
+     */
+    shouldPing?: () => boolean;
+}
+/**
+ * Always-available ping input alongside the active tool: long-press-to-ping
+ * plus keyboard/programmatic pings, independent of `PingTool`.
+ *
+ * `PingInput` is a passive observer by contract. Its DOM pointer listeners are
+ * registered `passive: true` and it never calls `preventDefault`,
+ * `stopPropagation`, or captures pointers, so the active tool, panning, and
+ * pinch navigation behave exactly as if it were absent (with a pencil active,
+ * a still hold pings AND the pencil still draws its dot). It also never
+ * renders: hosts feed emissions into their own `RemotePingOverlay` under a
+ * `'self'` sender key. Pings are ephemeral — no elements, no undo history, no
+ * persisted state, no camera movement.
+ *
+ * The long-press gesture is opt-in via `longPressEnabled` (hosts whose users
+ * would not expect hold-to-ping simply leave it off and keep the keyboard
+ * paths). When enabled, a long-press arms on the first pointer down (mouse
+ * primary button, touch, or pen), fires after `longPressMs` at the original
+ * press position, and
+ * cancels on movement past `slopPx`, a second pointer (two-finger
+ * navigation), or pointer up/cancel/leave. Keyboard support is a capability,
+ * not a binding: hosts call `pingAtPointer()` (last tracked hover position,
+ * world-converted at call time) or `pingAt(world)` from their own shortcut
+ * handling.
+ */
+declare class PingInput {
+    private readonly element;
+    private readonly host;
+    private longPressEnabled;
+    private longPressMs;
+    private slopPx;
+    private color;
+    private durationMs;
+    private radius;
+    private minIntervalMs;
+    private shouldPing;
+    private press;
+    private readonly downPointers;
+    private lastPointerScreen;
+    private lastEmitAt;
+    private disposed;
+    private optionListeners;
+    private pingListeners;
+    private readonly handlePointerDown;
+    private readonly handlePointerMove;
+    private readonly handlePointerUp;
+    private readonly handlePointerCancel;
+    private readonly handlePointerLeave;
+    constructor(element: HTMLElement, host: PingInputHost, options?: PingInputOptions);
+    private now;
+    getOptions(): PingInputOptions;
+    setOptions(options: PingInputOptions): void;
+    onOptionsChange(listener: () => void): () => void;
+    /**
+     * Subscribes to emitted pings. Listeners must not throw; a throwing
+     * listener is isolated so it cannot break input handling or other
+     * listeners.
+     */
+    onPing(listener: (emission: PingEmission) => void): () => void;
+    /**
+     * Pings at the last tracked pointer position (hover moves and presses),
+     * world-converted at call time. Returns `false` when no pointer has been
+     * seen yet, the host vetoes, or the rate limit drops the ping.
+     */
+    pingAtPointer(): boolean;
+    /** Pings a world position directly. Same veto and rate limit as every path. */
+    pingAt(world: Point): boolean;
+    /** Removes all DOM listeners and cancels any pending press. Idempotent. */
+    dispose(): void;
+    private toLocal;
+    private onPointerDown;
+    private onPointerMove;
+    private onPointerEnd;
+    private cancelPress;
+    private firePress;
+    private emit;
+}
+
 interface ActiveFormats {
     bold: boolean;
     italic: boolean;
@@ -1424,6 +1538,6 @@ declare class TemplateTool implements Tool {
     private notifyOptionsChange;
 }
 
-declare const VERSION = "0.55.0";
+declare const VERSION = "0.56.0";
 
-export { type ActiveFormats, type AlignEdge, type ArrowElement, type ArrowStrokeStyle, ArrowTool, type ArrowToolOptions, AutoSave, type AutoSaveOptions, type BackgroundOptions, type BackgroundPattern, type Binding, type Bounds, Camera, type CameraChangeInfo, type CameraOptions, type CanvasElement, type CanvasState, type Command, DEFAULT_NOTE_FONT_SIZE, type DistributeAxis, type ElementChangeMeta, ElementStore, type ElementStyle, type ElementType, type ElementUpdateEvent, EraserTool, type EraserToolOptions, type ExportAssetError, type ExportAssetErrorReason, type ExportImageOptions, type ExportResourceOptions, type ExportSvgOptions, type FontSizePreset, type GridElement, type GridInfo, HandTool, type HexOrientation, HistoryStack, type HistoryStackOptions, type HtmlElement, type HtmlExportError, type HtmlExportErrorReason, type HtmlExportOptions, type HtmlExportRenderer, type ImageElement, ImageTool, type ImageToolOptions, IndexedDBAdapter, type IndexedDBAdapterOptions, LASER_TRAIL_PRESENCE_KIND, LaserTool, type LaserToolOptions, type LaserTrailEmission, type LaserTrailPresence, type Layer, LayerManager, LocalStorageAdapter, MeasureTool, type MeasureToolOptions, type Measurement, MemoryAdapter, type NoteElement, NoteTool, type NoteToolOptions, type OverlayRenderer, PING_PRESENCE_KIND, PencilTool, type PencilToolOptions, type PingEmission, type PingPresence, PingTool, type PingToolOptions, type Point, type PointerState, RemoteLaserOverlay, type RemoteLaserOverlayHost, type RemoteLaserOverlayOptions, RemotePingOverlay, type RemotePingOverlayHost, type RemotePingOverlayOptions, type RenderStatsSnapshot, type RotateDirection, SelectTool, type ShapeElement, type ShapeKind, ShapeTool, type ShapeToolOptions, type ShortcutBindings, type ShortcutOptions, type ShortcutsApi, type Size, type StorageAdapter, type StrokeElement, type StrokePoint, type TemplateElement, type TemplateRenderStyle, type TemplateShape, TemplateTool, type TemplateToolOptions, type TextElement, TextTool, type TextToolOptions, type Tool, type ToolContext, ToolManager, type ToolName, VERSION, Viewport, type ViewportOptions, boundsIntersect, createArrow, createGrid, createHtmlElement, createImage, createNote, createShape, createStroke, createTemplate, createText, drawHexPath, exportImage, exportSvg, getActiveFormats, getArrowBounds, getArrowControlPoint, getArrowMidpoint, getArrowTangentAngle, getBendFromPoint, getElementBounds, getElementStyle, getElementsBoundingBox, getHexCellsInCone, getHexCellsInLine, getHexCellsInRadius, getHexCellsInRectangle, getHexCellsInSquare, getHexDistance, isLaserTrailPresence, isNearBezier, isPingPresence, setFontSize, smartSnap, snapPoint, snapToHexCenter, styleToPatch, toLaserTrailPresence, toPingPresence, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline };
+export { type ActiveFormats, type AlignEdge, type ArrowElement, type ArrowStrokeStyle, ArrowTool, type ArrowToolOptions, AutoSave, type AutoSaveOptions, type BackgroundOptions, type BackgroundPattern, type Binding, type Bounds, Camera, type CameraChangeInfo, type CameraOptions, type CanvasElement, type CanvasState, type Command, DEFAULT_NOTE_FONT_SIZE, type DistributeAxis, type ElementChangeMeta, ElementStore, type ElementStyle, type ElementType, type ElementUpdateEvent, EraserTool, type EraserToolOptions, type ExportAssetError, type ExportAssetErrorReason, type ExportImageOptions, type ExportResourceOptions, type ExportSvgOptions, type FontSizePreset, type GridElement, type GridInfo, HandTool, type HexOrientation, HistoryStack, type HistoryStackOptions, type HtmlElement, type HtmlExportError, type HtmlExportErrorReason, type HtmlExportOptions, type HtmlExportRenderer, type ImageElement, ImageTool, type ImageToolOptions, IndexedDBAdapter, type IndexedDBAdapterOptions, LASER_TRAIL_PRESENCE_KIND, LaserTool, type LaserToolOptions, type LaserTrailEmission, type LaserTrailPresence, type Layer, LayerManager, LocalStorageAdapter, MeasureTool, type MeasureToolOptions, type Measurement, MemoryAdapter, type NoteElement, NoteTool, type NoteToolOptions, type OverlayRenderer, PING_PRESENCE_KIND, PencilTool, type PencilToolOptions, type PingEmission, PingInput, type PingInputHost, type PingInputOptions, type PingPresence, PingTool, type PingToolOptions, type Point, type PointerState, RemoteLaserOverlay, type RemoteLaserOverlayHost, type RemoteLaserOverlayOptions, RemotePingOverlay, type RemotePingOverlayHost, type RemotePingOverlayOptions, type RenderStatsSnapshot, type RotateDirection, SelectTool, type ShapeElement, type ShapeKind, ShapeTool, type ShapeToolOptions, type ShortcutBindings, type ShortcutOptions, type ShortcutsApi, type Size, type StorageAdapter, type StrokeElement, type StrokePoint, type TemplateElement, type TemplateRenderStyle, type TemplateShape, TemplateTool, type TemplateToolOptions, type TextElement, TextTool, type TextToolOptions, type Tool, type ToolContext, ToolManager, type ToolName, VERSION, Viewport, type ViewportOptions, boundsIntersect, createArrow, createGrid, createHtmlElement, createImage, createNote, createShape, createStroke, createTemplate, createText, drawHexPath, exportImage, exportSvg, getActiveFormats, getArrowBounds, getArrowControlPoint, getArrowMidpoint, getArrowTangentAngle, getBendFromPoint, getElementBounds, getElementStyle, getElementsBoundingBox, getHexCellsInCone, getHexCellsInLine, getHexCellsInRadius, getHexCellsInRectangle, getHexCellsInSquare, getHexDistance, isLaserTrailPresence, isNearBezier, isPingPresence, setFontSize, smartSnap, snapPoint, snapToHexCenter, styleToPatch, toLaserTrailPresence, toPingPresence, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline };

package/dist/index.d.ts

@@ -986,6 +986,120 @@ declare class RemotePingOverlay {
     private renderPings;
 }
 
+/**
+ * The one camera capability `PingInput` needs; `Camera` satisfies it. Screen
+ * coordinates are element-local (the same space `Camera.screenToWorld`
+ * expects).
+ */
+interface PingInputHost {
+    screenToWorld(screen: Point): Point;
+}
+interface PingInputOptions {
+    /**
+     * Opt-in for the long-press gesture. Off by default: a hidden hold-to-ping
+     * gesture surprises users outside shared-canvas products, so hosts enable
+     * it deliberately. The keyboard/programmatic paths (`pingAtPointer`,
+     * `pingAt`) are always available. Default `false`.
+     */
+    longPressEnabled?: boolean;
+    /** Hold duration before a still press pings. Default `600`. */
+    longPressMs?: number;
+    /** Maximum pointer travel while holding; moving further cancels. Default `8`. */
+    slopPx?: number;
+    /** Emission style forwarded to hosts; matches `PingTool` defaults. */
+    color?: string;
+    durationMs?: number;
+    radius?: number;
+    /**
+     * Minimum interval between emitted pings, shared across the long-press and
+     * keyboard/programmatic paths. Faster pings are dropped entirely. Default
+     * `300`.
+     */
+    minIntervalMs?: number;
+    /**
+     * Host veto consulted at fire time on every path (e.g. return `false` while
+     * a ping tool is active to avoid double pings). A veto does not consume the
+     * rate-limit interval.
+     */
+    shouldPing?: () => boolean;
+}
+/**
+ * Always-available ping input alongside the active tool: long-press-to-ping
+ * plus keyboard/programmatic pings, independent of `PingTool`.
+ *
+ * `PingInput` is a passive observer by contract. Its DOM pointer listeners are
+ * registered `passive: true` and it never calls `preventDefault`,
+ * `stopPropagation`, or captures pointers, so the active tool, panning, and
+ * pinch navigation behave exactly as if it were absent (with a pencil active,
+ * a still hold pings AND the pencil still draws its dot). It also never
+ * renders: hosts feed emissions into their own `RemotePingOverlay` under a
+ * `'self'` sender key. Pings are ephemeral — no elements, no undo history, no
+ * persisted state, no camera movement.
+ *
+ * The long-press gesture is opt-in via `longPressEnabled` (hosts whose users
+ * would not expect hold-to-ping simply leave it off and keep the keyboard
+ * paths). When enabled, a long-press arms on the first pointer down (mouse
+ * primary button, touch, or pen), fires after `longPressMs` at the original
+ * press position, and
+ * cancels on movement past `slopPx`, a second pointer (two-finger
+ * navigation), or pointer up/cancel/leave. Keyboard support is a capability,
+ * not a binding: hosts call `pingAtPointer()` (last tracked hover position,
+ * world-converted at call time) or `pingAt(world)` from their own shortcut
+ * handling.
+ */
+declare class PingInput {
+    private readonly element;
+    private readonly host;
+    private longPressEnabled;
+    private longPressMs;
+    private slopPx;
+    private color;
+    private durationMs;
+    private radius;
+    private minIntervalMs;
+    private shouldPing;
+    private press;
+    private readonly downPointers;
+    private lastPointerScreen;
+    private lastEmitAt;
+    private disposed;
+    private optionListeners;
+    private pingListeners;
+    private readonly handlePointerDown;
+    private readonly handlePointerMove;
+    private readonly handlePointerUp;
+    private readonly handlePointerCancel;
+    private readonly handlePointerLeave;
+    constructor(element: HTMLElement, host: PingInputHost, options?: PingInputOptions);
+    private now;
+    getOptions(): PingInputOptions;
+    setOptions(options: PingInputOptions): void;
+    onOptionsChange(listener: () => void): () => void;
+    /**
+     * Subscribes to emitted pings. Listeners must not throw; a throwing
+     * listener is isolated so it cannot break input handling or other
+     * listeners.
+     */
+    onPing(listener: (emission: PingEmission) => void): () => void;
+    /**
+     * Pings at the last tracked pointer position (hover moves and presses),
+     * world-converted at call time. Returns `false` when no pointer has been
+     * seen yet, the host vetoes, or the rate limit drops the ping.
+     */
+    pingAtPointer(): boolean;
+    /** Pings a world position directly. Same veto and rate limit as every path. */
+    pingAt(world: Point): boolean;
+    /** Removes all DOM listeners and cancels any pending press. Idempotent. */
+    dispose(): void;
+    private toLocal;
+    private onPointerDown;
+    private onPointerMove;
+    private onPointerEnd;
+    private cancelPress;
+    private firePress;
+    private emit;
+}
+
 interface ActiveFormats {
     bold: boolean;
     italic: boolean;
@@ -1424,6 +1538,6 @@ declare class TemplateTool implements Tool {
     private notifyOptionsChange;
 }
 
-declare const VERSION = "0.55.0";
+declare const VERSION = "0.56.0";
 
-export { type ActiveFormats, type AlignEdge, type ArrowElement, type ArrowStrokeStyle, ArrowTool, type ArrowToolOptions, AutoSave, type AutoSaveOptions, type BackgroundOptions, type BackgroundPattern, type Binding, type Bounds, Camera, type CameraChangeInfo, type CameraOptions, type CanvasElement, type CanvasState, type Command, DEFAULT_NOTE_FONT_SIZE, type DistributeAxis, type ElementChangeMeta, ElementStore, type ElementStyle, type ElementType, type ElementUpdateEvent, EraserTool, type EraserToolOptions, type ExportAssetError, type ExportAssetErrorReason, type ExportImageOptions, type ExportResourceOptions, type ExportSvgOptions, type FontSizePreset, type GridElement, type GridInfo, HandTool, type HexOrientation, HistoryStack, type HistoryStackOptions, type HtmlElement, type HtmlExportError, type HtmlExportErrorReason, type HtmlExportOptions, type HtmlExportRenderer, type ImageElement, ImageTool, type ImageToolOptions, IndexedDBAdapter, type IndexedDBAdapterOptions, LASER_TRAIL_PRESENCE_KIND, LaserTool, type LaserToolOptions, type LaserTrailEmission, type LaserTrailPresence, type Layer, LayerManager, LocalStorageAdapter, MeasureTool, type MeasureToolOptions, type Measurement, MemoryAdapter, type NoteElement, NoteTool, type NoteToolOptions, type OverlayRenderer, PING_PRESENCE_KIND, PencilTool, type PencilToolOptions, type PingEmission, type PingPresence, PingTool, type PingToolOptions, type Point, type PointerState, RemoteLaserOverlay, type RemoteLaserOverlayHost, type RemoteLaserOverlayOptions, RemotePingOverlay, type RemotePingOverlayHost, type RemotePingOverlayOptions, type RenderStatsSnapshot, type RotateDirection, SelectTool, type ShapeElement, type ShapeKind, ShapeTool, type ShapeToolOptions, type ShortcutBindings, type ShortcutOptions, type ShortcutsApi, type Size, type StorageAdapter, type StrokeElement, type StrokePoint, type TemplateElement, type TemplateRenderStyle, type TemplateShape, TemplateTool, type TemplateToolOptions, type TextElement, TextTool, type TextToolOptions, type Tool, type ToolContext, ToolManager, type ToolName, VERSION, Viewport, type ViewportOptions, boundsIntersect, createArrow, createGrid, createHtmlElement, createImage, createNote, createShape, createStroke, createTemplate, createText, drawHexPath, exportImage, exportSvg, getActiveFormats, getArrowBounds, getArrowControlPoint, getArrowMidpoint, getArrowTangentAngle, getBendFromPoint, getElementBounds, getElementStyle, getElementsBoundingBox, getHexCellsInCone, getHexCellsInLine, getHexCellsInRadius, getHexCellsInRectangle, getHexCellsInSquare, getHexDistance, isLaserTrailPresence, isNearBezier, isPingPresence, setFontSize, smartSnap, snapPoint, snapToHexCenter, styleToPatch, toLaserTrailPresence, toPingPresence, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline };
+export { type ActiveFormats, type AlignEdge, type ArrowElement, type ArrowStrokeStyle, ArrowTool, type ArrowToolOptions, AutoSave, type AutoSaveOptions, type BackgroundOptions, type BackgroundPattern, type Binding, type Bounds, Camera, type CameraChangeInfo, type CameraOptions, type CanvasElement, type CanvasState, type Command, DEFAULT_NOTE_FONT_SIZE, type DistributeAxis, type ElementChangeMeta, ElementStore, type ElementStyle, type ElementType, type ElementUpdateEvent, EraserTool, type EraserToolOptions, type ExportAssetError, type ExportAssetErrorReason, type ExportImageOptions, type ExportResourceOptions, type ExportSvgOptions, type FontSizePreset, type GridElement, type GridInfo, HandTool, type HexOrientation, HistoryStack, type HistoryStackOptions, type HtmlElement, type HtmlExportError, type HtmlExportErrorReason, type HtmlExportOptions, type HtmlExportRenderer, type ImageElement, ImageTool, type ImageToolOptions, IndexedDBAdapter, type IndexedDBAdapterOptions, LASER_TRAIL_PRESENCE_KIND, LaserTool, type LaserToolOptions, type LaserTrailEmission, type LaserTrailPresence, type Layer, LayerManager, LocalStorageAdapter, MeasureTool, type MeasureToolOptions, type Measurement, MemoryAdapter, type NoteElement, NoteTool, type NoteToolOptions, type OverlayRenderer, PING_PRESENCE_KIND, PencilTool, type PencilToolOptions, type PingEmission, PingInput, type PingInputHost, type PingInputOptions, type PingPresence, PingTool, type PingToolOptions, type Point, type PointerState, RemoteLaserOverlay, type RemoteLaserOverlayHost, type RemoteLaserOverlayOptions, RemotePingOverlay, type RemotePingOverlayHost, type RemotePingOverlayOptions, type RenderStatsSnapshot, type RotateDirection, SelectTool, type ShapeElement, type ShapeKind, ShapeTool, type ShapeToolOptions, type ShortcutBindings, type ShortcutOptions, type ShortcutsApi, type Size, type StorageAdapter, type StrokeElement, type StrokePoint, type TemplateElement, type TemplateRenderStyle, type TemplateShape, TemplateTool, type TemplateToolOptions, type TextElement, TextTool, type TextToolOptions, type Tool, type ToolContext, ToolManager, type ToolName, VERSION, Viewport, type ViewportOptions, boundsIntersect, createArrow, createGrid, createHtmlElement, createImage, createNote, createShape, createStroke, createTemplate, createText, drawHexPath, exportImage, exportSvg, getActiveFormats, getArrowBounds, getArrowControlPoint, getArrowMidpoint, getArrowTangentAngle, getBendFromPoint, getElementBounds, getElementStyle, getElementsBoundingBox, getHexCellsInCone, getHexCellsInLine, getHexCellsInRadius, getHexCellsInRectangle, getHexCellsInSquare, getHexDistance, isLaserTrailPresence, isNearBezier, isPingPresence, setFontSize, smartSnap, snapPoint, snapToHexCenter, styleToPatch, toLaserTrailPresence, toPingPresence, toggleBold, toggleItalic, toggleStrikethrough, toggleUnderline };

package/dist/index.js

@@ -8845,6 +8845,191 @@ var RemotePingOverlay = class {
   }
 };
 
+// src/canvas/ping-input.ts
+var DEFAULT_LONG_PRESS_MS = 600;
+var DEFAULT_SLOP_PX = 8;
+var DEFAULT_COLOR3 = "#ff3b30";
+var DEFAULT_DURATION_MS2 = 1800;
+var DEFAULT_RADIUS2 = 48;
+var DEFAULT_MIN_INTERVAL_MS = 300;
+var PingInput = class {
+  element;
+  host;
+  longPressEnabled;
+  longPressMs;
+  slopPx;
+  color;
+  durationMs;
+  radius;
+  minIntervalMs;
+  shouldPing;
+  press = null;
+  downPointers = /* @__PURE__ */ new Set();
+  lastPointerScreen = null;
+  lastEmitAt = -Infinity;
+  disposed = false;
+  optionListeners = /* @__PURE__ */ new Set();
+  pingListeners = /* @__PURE__ */ new Set();
+  handlePointerDown = (e) => this.onPointerDown(e);
+  handlePointerMove = (e) => this.onPointerMove(e);
+  handlePointerUp = (e) => this.onPointerEnd(e);
+  handlePointerCancel = (e) => this.onPointerEnd(e);
+  handlePointerLeave = (e) => this.onPointerEnd(e);
+  constructor(element, host, options = {}) {
+    this.element = element;
+    this.host = host;
+    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_COLOR3;
+    this.durationMs = options.durationMs ?? DEFAULT_DURATION_MS2;
+    this.radius = options.radius ?? DEFAULT_RADIUS2;
+    this.minIntervalMs = options.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS;
+    this.shouldPing = options.shouldPing;
+    const opts = { passive: true };
+    element.addEventListener("pointerdown", this.handlePointerDown, opts);
+    element.addEventListener("pointermove", this.handlePointerMove, opts);
+    element.addEventListener("pointerup", this.handlePointerUp, opts);
+    element.addEventListener("pointercancel", this.handlePointerCancel, opts);
+    element.addEventListener("pointerleave", this.handlePointerLeave, opts);
+  }
+  now() {
+    return performance.now();
+  }
+  getOptions() {
+    return {
+      longPressEnabled: this.longPressEnabled,
+      longPressMs: this.longPressMs,
+      slopPx: this.slopPx,
+      color: this.color,
+      durationMs: this.durationMs,
+      radius: this.radius,
+      minIntervalMs: this.minIntervalMs,
+      ...this.shouldPing ? { shouldPing: this.shouldPing } : {}
+    };
+  }
+  setOptions(options) {
+    if (options.longPressEnabled !== void 0) {
+      this.longPressEnabled = options.longPressEnabled;
+      if (!this.longPressEnabled) this.cancelPress();
+    }
+    if (options.longPressMs !== void 0) this.longPressMs = options.longPressMs;
+    if (options.slopPx !== void 0) this.slopPx = options.slopPx;
+    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;
+    if (options.shouldPing !== void 0) this.shouldPing = options.shouldPing;
+    for (const listener of this.optionListeners) listener();
+  }
+  onOptionsChange(listener) {
+    this.optionListeners.add(listener);
+    return () => this.optionListeners.delete(listener);
+  }
+  /**
+   * Subscribes to emitted pings. Listeners must not throw; a throwing
+   * listener is isolated so it cannot break input handling or other
+   * listeners.
+   */
+  onPing(listener) {
+    this.pingListeners.add(listener);
+    return () => this.pingListeners.delete(listener);
+  }
+  /**
+   * Pings at the last tracked pointer position (hover moves and presses),
+   * world-converted at call time. Returns `false` when no pointer has been
+   * seen yet, the host vetoes, or the rate limit drops the ping.
+   */
+  pingAtPointer() {
+    if (this.disposed || this.lastPointerScreen === null) return false;
+    return this.emit(this.host.screenToWorld(this.lastPointerScreen));
+  }
+  /** Pings a world position directly. Same veto and rate limit as every path. */
+  pingAt(world) {
+    if (this.disposed) return false;
+    return this.emit(world);
+  }
+  /** Removes all DOM listeners and cancels any pending press. Idempotent. */
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.cancelPress();
+    this.downPointers.clear();
+    this.element.removeEventListener("pointerdown", this.handlePointerDown);
+    this.element.removeEventListener("pointermove", this.handlePointerMove);
+    this.element.removeEventListener("pointerup", this.handlePointerUp);
+    this.element.removeEventListener("pointercancel", this.handlePointerCancel);
+    this.element.removeEventListener("pointerleave", this.handlePointerLeave);
+    this.optionListeners.clear();
+    this.pingListeners.clear();
+  }
+  toLocal(e) {
+    const rect = this.element.getBoundingClientRect();
+    return { x: e.clientX - rect.left, y: e.clientY - rect.top };
+  }
+  onPointerDown(e) {
+    const local = this.toLocal(e);
+    this.lastPointerScreen = local;
+    const hadPointers = this.downPointers.size > 0;
+    this.downPointers.add(e.pointerId);
+    if (hadPointers) {
+      this.cancelPress();
+      return;
+    }
+    if (!this.longPressEnabled) return;
+    if (e.pointerType === "mouse" && e.button !== 0) return;
+    this.press = {
+      pointerId: e.pointerId,
+      x: local.x,
+      y: local.y,
+      timer: setTimeout(() => this.firePress(), this.longPressMs)
+    };
+  }
+  onPointerMove(e) {
+    const local = this.toLocal(e);
+    this.lastPointerScreen = local;
+    if (this.press === null || e.pointerId !== this.press.pointerId) return;
+    const dx = local.x - this.press.x;
+    const dy = local.y - this.press.y;
+    if (Math.hypot(dx, dy) > this.slopPx) this.cancelPress();
+  }
+  onPointerEnd(e) {
+    this.downPointers.delete(e.pointerId);
+    if (this.press !== null && e.pointerId === this.press.pointerId) this.cancelPress();
+  }
+  cancelPress() {
+    if (this.press === null) return;
+    clearTimeout(this.press.timer);
+    this.press = null;
+  }
+  firePress() {
+    if (this.press === null) return;
+    const screen = { x: this.press.x, y: this.press.y };
+    this.press = null;
+    this.emit(this.host.screenToWorld(screen));
+  }
+  emit(world) {
+    if (this.shouldPing && !this.shouldPing()) return false;
+    const t = this.now();
+    if (t - this.lastEmitAt < this.minIntervalMs) return false;
+    this.lastEmitAt = 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 {
+      }
+    }
+    return true;
+  }
+};
+
 // src/tools/hand-tool.ts
 var HandTool = class {
   name = "hand";
@@ -9106,7 +9291,7 @@ function erasePoints(points, eraser, radius) {
 }
 
 // src/tools/eraser-tool.ts
-var DEFAULT_RADIUS2 = 20;
+var DEFAULT_RADIUS3 = 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>`;
@@ -9119,7 +9304,7 @@ var EraserTool = class {
   cursor;
   mode;
   constructor(options = {}) {
-    this.radius = options.radius ?? DEFAULT_RADIUS2;
+    this.radius = options.radius ?? DEFAULT_RADIUS3;
     this.cursor = makeEraserCursor(this.radius);
     this.mode = options.mode ?? "partial";
   }
@@ -11401,7 +11586,7 @@ var TemplateTool = class {
 };
 
 // src/tools/laser-tool.ts
-var DEFAULT_COLOR3 = "#ff3b30";
+var DEFAULT_COLOR4 = "#ff3b30";
 var DEFAULT_WIDTH2 = 4;
 var DEFAULT_FADE_MS2 = 1200;
 var LaserTool = class {
@@ -11417,7 +11602,7 @@ var LaserTool = class {
   pendingEmission = [];
   constructor(options = {}) {
     this.name = options.name ?? "laser";
-    this.color = options.color ?? DEFAULT_COLOR3;
+    this.color = options.color ?? DEFAULT_COLOR4;
     this.width = options.width ?? DEFAULT_WIDTH2;
     this.fadeMs = options.fadeMs ?? DEFAULT_FADE_MS2;
   }
@@ -11545,10 +11730,10 @@ 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 DEFAULT_COLOR5 = "#ff3b30";
+var DEFAULT_DURATION_MS3 = 1800;
+var DEFAULT_RADIUS4 = 48;
+var DEFAULT_MIN_INTERVAL_MS2 = 300;
 var PingTool = class {
   name;
   color;
@@ -11562,10 +11747,10 @@ var PingTool = class {
   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;
+    this.color = options.color ?? DEFAULT_COLOR5;
+    this.durationMs = options.durationMs ?? DEFAULT_DURATION_MS3;
+    this.radius = options.radius ?? DEFAULT_RADIUS4;
+    this.minIntervalMs = options.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS2;
   }
   now() {
     return performance.now();
@@ -11665,7 +11850,7 @@ var PingTool = class {
 };
 
 // src/index.ts
-var VERSION = "0.55.0";
+var VERSION = "0.56.0";
 export {
   ArrowTool,
   AutoSave,
@@ -11686,6 +11871,7 @@ export {
   NoteTool,
   PING_PRESENCE_KIND,
   PencilTool,
+  PingInput,
   PingTool,
   RemoteLaserOverlay,
   RemotePingOverlay,