@fieldnotes/core 0.56.0 → 0.57.0

package/dist/index.cjs

@@ -34,6 +34,7 @@ __export(index_exports, {
   LaserTool: () => LaserTool,
   LayerManager: () => LayerManager,
   LocalStorageAdapter: () => LocalStorageAdapter,
+  MEASURE_PRESENCE_KIND: () => MEASURE_PRESENCE_KIND,
   MeasureTool: () => MeasureTool,
   MemoryAdapter: () => MemoryAdapter,
   NoteTool: () => NoteTool,
@@ -42,6 +43,7 @@ __export(index_exports, {
   PingInput: () => PingInput,
   PingTool: () => PingTool,
   RemoteLaserOverlay: () => RemoteLaserOverlay,
+  RemoteMeasureOverlay: () => RemoteMeasureOverlay,
   RemotePingOverlay: () => RemotePingOverlay,
   SelectTool: () => SelectTool,
   ShapeTool: () => ShapeTool,
@@ -79,6 +81,7 @@ __export(index_exports, {
   getHexCellsInSquare: () => getHexCellsInSquare,
   getHexDistance: () => getHexDistance,
   isLaserTrailPresence: () => isLaserTrailPresence,
+  isMeasurePresence: () => isMeasurePresence,
   isNearBezier: () => isNearBezier,
   isPingPresence: () => isPingPresence,
   setFontSize: () => setFontSize,
@@ -87,6 +90,7 @@ __export(index_exports, {
   snapToHexCenter: () => snapToHexCenter,
   styleToPatch: () => styleToPatch,
   toLaserTrailPresence: () => toLaserTrailPresence,
+  toMeasurePresence: () => toMeasurePresence,
   toPingPresence: () => toPingPresence,
   toggleBold: () => toggleBold,
   toggleItalic: () => toggleItalic,
@@ -8942,10 +8946,218 @@ var RemotePingOverlay = class {
   }
 };
 
+// src/canvas/measure-render.ts
+function formatMeasureLabel(feet) {
+  return `${Math.round(feet)} ft`;
+}
+function drawMeasurement(ctx, m, opts = {}) {
+  ctx.save();
+  if (opts.alpha !== void 0) ctx.globalAlpha = opts.alpha;
+  ctx.strokeStyle = m.color;
+  ctx.setLineDash([8, 4]);
+  ctx.lineWidth = 2;
+  ctx.beginPath();
+  ctx.moveTo(m.start.x, m.start.y);
+  ctx.lineTo(m.end.x, m.end.y);
+  ctx.stroke();
+  ctx.setLineDash([]);
+  ctx.fillStyle = m.color;
+  const dotRadius = 4;
+  ctx.beginPath();
+  ctx.arc(m.start.x, m.start.y, dotRadius, 0, Math.PI * 2);
+  ctx.fill();
+  ctx.beginPath();
+  ctx.arc(m.end.x, m.end.y, dotRadius, 0, Math.PI * 2);
+  ctx.fill();
+  const label = formatMeasureLabel(m.feet);
+  const midX = (m.start.x + m.end.x) / 2;
+  const midY = (m.start.y + m.end.y) / 2;
+  ctx.font = "14px sans-serif";
+  const metrics = ctx.measureText(label);
+  const padX = 6;
+  const padY = 4;
+  const textH = 14;
+  ctx.fillStyle = "rgba(0, 0, 0, 0.75)";
+  ctx.beginPath();
+  ctx.roundRect(
+    midX - metrics.width / 2 - padX,
+    midY - 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, midX, midY);
+  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";
+var DEFAULT_HOLD_MS = 1500;
+var DEFAULT_FADE_MS2 = 400;
+var DEFAULT_MAX_AGE_MS = 3e4;
+var RemoteMeasureOverlay = class {
+  host;
+  color;
+  holdMs;
+  fadeMs;
+  maxAgeMs;
+  measurements = /* @__PURE__ */ new Map();
+  unregister;
+  rafId = null;
+  disposed = false;
+  constructor(host, options = {}) {
+    this.host = host;
+    this.color = options.color ?? DEFAULT_COLOR3;
+    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));
+  }
+  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.disposed || !isMeasurePresence(data)) return false;
+    if ("cleared" in data) {
+      this.beginLinger(sender);
+      return true;
+    }
+    const existing = this.measurements.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,
+      clearedAt: null,
+      expiryTimer: setTimeout(() => this.beginLinger(sender), this.maxAgeMs)
+    });
+    this.host.requestRender();
+    return true;
+  }
+  /** Removes a sender's ruler immediately (presence-leave/disconnect). */
+  remove(sender) {
+    const entry = this.measurements.get(sender);
+    if (!entry) return;
+    if (entry.expiryTimer != null) clearTimeout(entry.expiryTimer);
+    this.measurements.delete(sender);
+    this.host.requestRender();
+  }
+  /** Removes every ruler immediately. */
+  clear() {
+    if (this.measurements.size === 0) return;
+    for (const entry of this.measurements.values()) {
+      if (entry.expiryTimer != null) clearTimeout(entry.expiryTimer);
+    }
+    this.measurements.clear();
+    this.host.requestRender();
+  }
+  /** Number of senders with a visible (active or lingering) ruler. */
+  get activeSenderCount() {
+    return this.measurements.size;
+  }
+  /** Unregisters the overlay, cancels timers, stops animating. Idempotent. */
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    if (this.rafId !== null) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = null;
+    }
+    for (const entry of this.measurements.values()) {
+      if (entry.expiryTimer != null) clearTimeout(entry.expiryTimer);
+    }
+    this.measurements.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;
+    const now = this.now();
+    let lingering = 0;
+    for (const [sender, entry] of this.measurements) {
+      if (entry.clearedAt === null) continue;
+      if (now - entry.clearedAt >= this.holdMs + this.fadeMs) {
+        this.measurements.delete(sender);
+      } else {
+        lingering += 1;
+      }
+    }
+    this.host.requestRender();
+    this.rafId = lingering > 0 ? requestAnimationFrame(() => this.tick()) : null;
+  }
+  renderMeasurements(ctx) {
+    if (this.measurements.size === 0) return;
+    const now = this.now();
+    for (const entry of this.measurements.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 });
+    }
+  }
+};
+
 // src/canvas/ping-input.ts
 var DEFAULT_LONG_PRESS_MS = 600;
 var DEFAULT_SLOP_PX = 8;
-var DEFAULT_COLOR3 = "#ff3b30";
+var DEFAULT_COLOR4 = "#ff3b30";
 var DEFAULT_DURATION_MS2 = 1800;
 var DEFAULT_RADIUS2 = 48;
 var DEFAULT_MIN_INTERVAL_MS = 300;
@@ -8978,7 +9190,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_COLOR3;
+    this.color = options.color ?? DEFAULT_COLOR4;
     this.durationMs = options.durationMs ?? DEFAULT_DURATION_MS2;
     this.radius = options.radius ?? DEFAULT_RADIUS2;
     this.minIntervalMs = options.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS;
@@ -11268,21 +11480,37 @@ var MeasureTool = class {
   gridType;
   hexOrientation;
   feetPerCell;
+  color;
   optionListeners = /* @__PURE__ */ new Set();
+  measurementListeners = /* @__PURE__ */ new Set();
+  emissionRafId = null;
   constructor(options = {}) {
     this.feetPerCell = options.feetPerCell ?? 5;
+    this.color = options.color ?? "#FF5722";
   }
   getOptions() {
-    return { feetPerCell: this.feetPerCell };
+    return { feetPerCell: this.feetPerCell, color: this.color };
   }
   setOptions(options) {
     if (options.feetPerCell !== void 0) this.feetPerCell = options.feetPerCell;
+    if (options.color !== void 0) this.color = options.color;
     this.notifyOptionsChange();
   }
   onOptionsChange(listener) {
     this.optionListeners.add(listener);
     return () => this.optionListeners.delete(listener);
   }
+  /**
+   * Subscribes to raf-coalesced measurement snapshots. While a measurement is
+   * in progress, listeners receive at most one snapshot per animation frame
+   * carrying the latest state; `null` is delivered synchronously when the
+   * measurement clears (pointer-up or deactivate). Emissions are ephemeral by
+   * contract: presence only — never elements, history, or persisted state.
+   */
+  onMeasurement(listener) {
+    this.measurementListeners.add(listener);
+    return () => this.measurementListeners.delete(listener);
+  }
   onPointerDown(state, ctx) {
     this.gridSize = ctx.gridSize ?? 1;
     this.gridType = ctx.gridType;
@@ -11290,22 +11518,27 @@ var MeasureTool = class {
     const world = ctx.camera.screenToWorld({ x: state.x, y: state.y });
     this.start = this.snapToGrid(world, ctx);
     this.end = { ...this.start };
+    this.scheduleEmission();
   }
   onPointerMove(state, ctx) {
     if (!this.start) return;
     const world = ctx.camera.screenToWorld({ x: state.x, y: state.y });
     this.end = this.snapToGrid(world, ctx);
     ctx.requestRender();
+    this.scheduleEmission();
   }
   onPointerUp(_state, ctx) {
     if (!this.start) return;
     this.start = null;
     this.end = null;
     ctx.requestRender();
+    this.emitClear();
   }
   onDeactivate(_ctx) {
+    const wasActive = this.start !== null;
     this.start = null;
     this.end = null;
+    if (wasActive) this.emitClear();
   }
   getMeasurement() {
     if (!this.start || !this.end) return null;
@@ -11331,46 +11564,7 @@ var MeasureTool = class {
   renderOverlay(ctx) {
     const m = this.getMeasurement();
     if (!m) return;
-    ctx.save();
-    ctx.strokeStyle = "#FF5722";
-    ctx.setLineDash([8, 4]);
-    ctx.lineWidth = 2;
-    ctx.beginPath();
-    ctx.moveTo(m.start.x, m.start.y);
-    ctx.lineTo(m.end.x, m.end.y);
-    ctx.stroke();
-    ctx.setLineDash([]);
-    ctx.fillStyle = "#FF5722";
-    const dotRadius = 4;
-    ctx.beginPath();
-    ctx.arc(m.start.x, m.start.y, dotRadius, 0, Math.PI * 2);
-    ctx.fill();
-    ctx.beginPath();
-    ctx.arc(m.end.x, m.end.y, dotRadius, 0, Math.PI * 2);
-    ctx.fill();
-    const label = `${Math.round(m.feet)} ft`;
-    const midX = (m.start.x + m.end.x) / 2;
-    const midY = (m.start.y + m.end.y) / 2;
-    ctx.font = "14px sans-serif";
-    const metrics = ctx.measureText(label);
-    const padX = 6;
-    const padY = 4;
-    const textH = 14;
-    ctx.fillStyle = "rgba(0, 0, 0, 0.75)";
-    ctx.beginPath();
-    ctx.roundRect(
-      midX - metrics.width / 2 - padX,
-      midY - 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, midX, midY);
-    ctx.restore();
+    drawMeasurement(ctx, { start: m.start, end: m.end, feet: m.feet, color: this.color });
   }
   snapToGrid(point, ctx) {
     if (!ctx.gridSize) return point;
@@ -11388,6 +11582,32 @@ var MeasureTool = class {
   notifyOptionsChange() {
     for (const listener of this.optionListeners) listener();
   }
+  scheduleEmission() {
+    if (this.measurementListeners.size === 0) return;
+    if (this.emissionRafId !== null) return;
+    this.emissionRafId = requestAnimationFrame(() => {
+      this.emissionRafId = null;
+      const m = this.getMeasurement();
+      if (!m) return;
+      this.emit({ ...m, color: this.color });
+    });
+  }
+  emitClear() {
+    if (this.emissionRafId !== null) {
+      cancelAnimationFrame(this.emissionRafId);
+      this.emissionRafId = null;
+    }
+    if (this.measurementListeners.size === 0) return;
+    this.emit(null);
+  }
+  emit(emission) {
+    for (const listener of this.measurementListeners) {
+      try {
+        listener(emission);
+      } catch {
+      }
+    }
+  }
 };
 
 // src/tools/template-tool.ts
@@ -11683,9 +11903,9 @@ var TemplateTool = class {
 };
 
 // src/tools/laser-tool.ts
-var DEFAULT_COLOR4 = "#ff3b30";
+var DEFAULT_COLOR5 = "#ff3b30";
 var DEFAULT_WIDTH2 = 4;
-var DEFAULT_FADE_MS2 = 1200;
+var DEFAULT_FADE_MS3 = 1200;
 var LaserTool = class {
   name;
   color;
@@ -11699,9 +11919,9 @@ var LaserTool = class {
   pendingEmission = [];
   constructor(options = {}) {
     this.name = options.name ?? "laser";
-    this.color = options.color ?? DEFAULT_COLOR4;
+    this.color = options.color ?? DEFAULT_COLOR5;
     this.width = options.width ?? DEFAULT_WIDTH2;
-    this.fadeMs = options.fadeMs ?? DEFAULT_FADE_MS2;
+    this.fadeMs = options.fadeMs ?? DEFAULT_FADE_MS3;
   }
   now() {
     return performance.now();
@@ -11827,7 +12047,7 @@ var LaserTool = class {
 };
 
 // src/tools/ping-tool.ts
-var DEFAULT_COLOR5 = "#ff3b30";
+var DEFAULT_COLOR6 = "#ff3b30";
 var DEFAULT_DURATION_MS3 = 1800;
 var DEFAULT_RADIUS4 = 48;
 var DEFAULT_MIN_INTERVAL_MS2 = 300;
@@ -11844,7 +12064,7 @@ var PingTool = class {
   pingListeners = /* @__PURE__ */ new Set();
   constructor(options = {}) {
     this.name = options.name ?? "ping";
-    this.color = options.color ?? DEFAULT_COLOR5;
+    this.color = options.color ?? DEFAULT_COLOR6;
     this.durationMs = options.durationMs ?? DEFAULT_DURATION_MS3;
     this.radius = options.radius ?? DEFAULT_RADIUS4;
     this.minIntervalMs = options.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS2;
@@ -11947,7 +12167,7 @@ var PingTool = class {
 };
 
 // src/index.ts
-var VERSION = "0.56.0";
+var VERSION = "0.57.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ArrowTool,
@@ -11964,6 +12184,7 @@ var VERSION = "0.56.0";
   LaserTool,
   LayerManager,
   LocalStorageAdapter,
+  MEASURE_PRESENCE_KIND,
   MeasureTool,
   MemoryAdapter,
   NoteTool,
@@ -11972,6 +12193,7 @@ var VERSION = "0.56.0";
   PingInput,
   PingTool,
   RemoteLaserOverlay,
+  RemoteMeasureOverlay,
   RemotePingOverlay,
   SelectTool,
   ShapeTool,
@@ -12009,6 +12231,7 @@ var VERSION = "0.56.0";
   getHexCellsInSquare,
   getHexDistance,
   isLaserTrailPresence,
+  isMeasurePresence,
   isNearBezier,
   isPingPresence,
   setFontSize,
@@ -12017,6 +12240,7 @@ var VERSION = "0.56.0";
   snapToHexCenter,
   styleToPatch,
   toLaserTrailPresence,
+  toMeasurePresence,
   toPingPresence,
   toggleBold,
   toggleItalic,