@fieldnotes/core 0.52.2 → 0.54.0

package/dist/index.cjs

@@ -30,6 +30,7 @@ __export(index_exports, {
   HistoryStack: () => HistoryStack,
   ImageTool: () => ImageTool,
   IndexedDBAdapter: () => IndexedDBAdapter,
+  LASER_TRAIL_PRESENCE_KIND: () => LASER_TRAIL_PRESENCE_KIND,
   LaserTool: () => LaserTool,
   LayerManager: () => LayerManager,
   LocalStorageAdapter: () => LocalStorageAdapter,
@@ -37,6 +38,7 @@ __export(index_exports, {
   MemoryAdapter: () => MemoryAdapter,
   NoteTool: () => NoteTool,
   PencilTool: () => PencilTool,
+  RemoteLaserOverlay: () => RemoteLaserOverlay,
   SelectTool: () => SelectTool,
   ShapeTool: () => ShapeTool,
   TemplateTool: () => TemplateTool,
@@ -72,12 +74,14 @@ __export(index_exports, {
   getHexCellsInRectangle: () => getHexCellsInRectangle,
   getHexCellsInSquare: () => getHexCellsInSquare,
   getHexDistance: () => getHexDistance,
+  isLaserTrailPresence: () => isLaserTrailPresence,
   isNearBezier: () => isNearBezier,
   setFontSize: () => setFontSize,
   smartSnap: () => smartSnap,
   snapPoint: () => snapPoint,
   snapToHexCenter: () => snapToHexCenter,
   styleToPatch: () => styleToPatch,
+  toLaserTrailPresence: () => toLaserTrailPresence,
   toggleBold: () => toggleBold,
   toggleItalic: () => toggleItalic,
   toggleStrikethrough: () => toggleStrikethrough,
@@ -6922,6 +6926,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 +6985,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 +7141,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 +7252,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 +7260,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();
@@ -8184,6 +8215,7 @@ var Viewport = class {
   noteEditor;
   arrowLabelEditor;
   historyRecorder;
+  transactionDepth = 0;
   selectionOps;
   toolContext;
   marginViewport;
@@ -8228,6 +8260,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(),
@@ -8297,6 +8340,35 @@ var Viewport = class {
   get shortcuts() {
     return this.inputHandler.shortcuts;
   }
+  /**
+   * Groups synchronous local store and layer mutations into one undo step.
+   * Nested calls join the outer transaction. If the callback throws, mutations
+   * already applied remain undoable and the original error is rethrown.
+   */
+  transaction(operation) {
+    const isOuterTransaction = this.transactionDepth === 0;
+    if (isOuterTransaction) {
+      this.inputHandler.flushPendingHistory();
+      this.historyRecorder.begin();
+    }
+    this.transactionDepth += 1;
+    try {
+      return operation();
+    } finally {
+      this.transactionDepth -= 1;
+      if (isOuterTransaction) this.historyRecorder.commit();
+    }
+  }
+  /** Removes existing elements as one undoable operation and returns the number removed. */
+  removeElements(ids) {
+    const existingIds = [...new Set(ids)].filter((id) => this.store.getById(id) !== void 0);
+    if (existingIds.length === 0) return 0;
+    this.transaction(() => {
+      for (const id of existingIds) this.store.remove(id);
+    });
+    this.requestRender();
+    return existingIds.length;
+  }
   undo() {
     this.inputHandler.flushPendingHistory();
     this.historyRecorder.pause();
@@ -8546,6 +8618,154 @@ 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/tools/hand-tool.ts
 var HandTool = class {
   name = "hand";
@@ -11102,9 +11322,9 @@ var TemplateTool = class {
 };
 
 // src/tools/laser-tool.ts
-var DEFAULT_COLOR = "#ff3b30";
-var DEFAULT_WIDTH = 4;
-var DEFAULT_FADE_MS = 1200;
+var DEFAULT_COLOR2 = "#ff3b30";
+var DEFAULT_WIDTH2 = 4;
+var DEFAULT_FADE_MS2 = 1200;
 var LaserTool = class {
   name;
   color;
@@ -11114,11 +11334,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_COLOR2;
+    this.width = options.width ?? DEFAULT_WIDTH2;
+    this.fadeMs = options.fadeMs ?? DEFAULT_FADE_MS2;
   }
   now() {
     return performance.now();
@@ -11133,6 +11355,7 @@ var LaserTool = class {
     }
     this.trail = [];
     this.drawing = false;
+    this.pendingEmission = [];
     ctx.setCursor?.("default");
     ctx.requestRender();
   }
@@ -11148,6 +11371,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;
@@ -11156,14 +11389,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) {
@@ -11195,7 +11432,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) {
@@ -11212,7 +11466,7 @@ var LaserTool = class {
 };
 
 // src/index.ts
-var VERSION = "0.52.2";
+var VERSION = "0.54.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ArrowTool,
@@ -11225,6 +11479,7 @@ var VERSION = "0.52.2";
   HistoryStack,
   ImageTool,
   IndexedDBAdapter,
+  LASER_TRAIL_PRESENCE_KIND,
   LaserTool,
   LayerManager,
   LocalStorageAdapter,
@@ -11232,6 +11487,7 @@ var VERSION = "0.52.2";
   MemoryAdapter,
   NoteTool,
   PencilTool,
+  RemoteLaserOverlay,
   SelectTool,
   ShapeTool,
   TemplateTool,
@@ -11267,12 +11523,14 @@ var VERSION = "0.52.2";
   getHexCellsInRectangle,
   getHexCellsInSquare,
   getHexDistance,
+  isLaserTrailPresence,
   isNearBezier,
   setFontSize,
   smartSnap,
   snapPoint,
   snapToHexCenter,
   styleToPatch,
+  toLaserTrailPresence,
   toggleBold,
   toggleItalic,
   toggleStrikethrough,