@fieldnotes/core 0.54.0 → 0.56.0

package/dist/index.cjs

@@ -37,8 +37,12 @@ __export(index_exports, {
   MeasureTool: () => MeasureTool,
   MemoryAdapter: () => MemoryAdapter,
   NoteTool: () => NoteTool,
+  PING_PRESENCE_KIND: () => PING_PRESENCE_KIND,
   PencilTool: () => PencilTool,
+  PingInput: () => PingInput,
+  PingTool: () => PingTool,
   RemoteLaserOverlay: () => RemoteLaserOverlay,
+  RemotePingOverlay: () => RemotePingOverlay,
   SelectTool: () => SelectTool,
   ShapeTool: () => ShapeTool,
   TemplateTool: () => TemplateTool,
@@ -76,12 +80,14 @@ __export(index_exports, {
   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,
@@ -8766,6 +8772,361 @@ var RemoteLaserOverlay = class {
   }
 };
 
+// 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/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";
@@ -9027,7 +9388,7 @@ function erasePoints(points, eraser, radius) {
 }
 
 // src/tools/eraser-tool.ts
-var DEFAULT_RADIUS = 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>`;
@@ -9040,7 +9401,7 @@ var EraserTool = class {
   cursor;
   mode;
   constructor(options = {}) {
-    this.radius = options.radius ?? DEFAULT_RADIUS;
+    this.radius = options.radius ?? DEFAULT_RADIUS3;
     this.cursor = makeEraserCursor(this.radius);
     this.mode = options.mode ?? "partial";
   }
@@ -11322,7 +11683,7 @@ var TemplateTool = class {
 };
 
 // src/tools/laser-tool.ts
-var DEFAULT_COLOR2 = "#ff3b30";
+var DEFAULT_COLOR4 = "#ff3b30";
 var DEFAULT_WIDTH2 = 4;
 var DEFAULT_FADE_MS2 = 1200;
 var LaserTool = class {
@@ -11338,7 +11699,7 @@ var LaserTool = class {
   pendingEmission = [];
   constructor(options = {}) {
     this.name = options.name ?? "laser";
-    this.color = options.color ?? DEFAULT_COLOR2;
+    this.color = options.color ?? DEFAULT_COLOR4;
     this.width = options.width ?? DEFAULT_WIDTH2;
     this.fadeMs = options.fadeMs ?? DEFAULT_FADE_MS2;
   }
@@ -11465,8 +11826,128 @@ var LaserTool = class {
   }
 };
 
+// src/tools/ping-tool.ts
+var DEFAULT_COLOR5 = "#ff3b30";
+var DEFAULT_DURATION_MS3 = 1800;
+var DEFAULT_RADIUS4 = 48;
+var DEFAULT_MIN_INTERVAL_MS2 = 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_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();
+  }
+  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.54.0";
+var VERSION = "0.56.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ArrowTool,
@@ -11486,8 +11967,12 @@ var VERSION = "0.54.0";
   MeasureTool,
   MemoryAdapter,
   NoteTool,
+  PING_PRESENCE_KIND,
   PencilTool,
+  PingInput,
+  PingTool,
   RemoteLaserOverlay,
+  RemotePingOverlay,
   SelectTool,
   ShapeTool,
   TemplateTool,
@@ -11525,12 +12010,14 @@ var VERSION = "0.54.0";
   getHexDistance,
   isLaserTrailPresence,
   isNearBezier,
+  isPingPresence,
   setFontSize,
   smartSnap,
   snapPoint,
   snapToHexCenter,
   styleToPatch,
   toLaserTrailPresence,
+  toPingPresence,
   toggleBold,
   toggleItalic,
   toggleStrikethrough,