@fieldnotes/core 0.60.0 → 0.61.0

package/dist/index.js

@@ -8484,6 +8484,17 @@ var Viewport = class _Viewport {
   getVisibleRect() {
     return this.camera.getVisibleRect(this.canvasEl.clientWidth, this.canvasEl.clientHeight);
   }
+  /**
+   * Size in CSS pixels of the canvas that `getVisibleRect()` measures.
+   * Exposed because `canvasEl` is private: consumers can only reach the
+   * wrapper (via `domLayer.parentElement`), so without this accessor the
+   * canonical size behind `getVisibleRect()` is unreachable and callers
+   * resort to `getVisibleRect().w * camera.zoom`. Capture and restore must
+   * measure the same element or saved views do not round-trip.
+   */
+  getCanvasSize() {
+    return { w: this.canvasEl.clientWidth, h: this.canvasEl.clientHeight };
+  }
   /** Centers the camera on a world point without changing zoom. */
   centerCameraAt(world) {
     const z = this.camera.zoom;
@@ -9632,6 +9643,361 @@ var PingInput = class {
   }
 };
 
+// src/canvas/camera-view.ts
+function assertValidView(view) {
+  const { x, y, w, h } = view;
+  if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(w) || !Number.isFinite(h)) {
+    throw new Error("[fieldnotes] CameraView requires finite x, y, w, and h");
+  }
+  if (w <= 0 || h <= 0) {
+    throw new Error("[fieldnotes] CameraView requires positive w and h");
+  }
+}
+function assertCanvasDims(canvasW, canvasH) {
+  if (!Number.isFinite(canvasW) || !Number.isFinite(canvasH)) {
+    throw new Error("[fieldnotes] canvas dimensions must be finite");
+  }
+  if (canvasW < 0 || canvasH < 0) {
+    throw new Error("[fieldnotes] canvas dimensions must not be negative");
+  }
+}
+function canvasDimsUsable(canvasW, canvasH) {
+  return Number.isFinite(canvasW) && Number.isFinite(canvasH) && canvasW >= 0 && canvasH >= 0;
+}
+function captureCameraView(viewport) {
+  const rect = viewport.getVisibleRect();
+  return { x: rect.x, y: rect.y, w: rect.w, h: rect.h };
+}
+function fitZoomForView(view, canvasW, canvasH) {
+  assertValidView(view);
+  assertCanvasDims(canvasW, canvasH);
+  if (canvasW === 0 || canvasH === 0) {
+    throw new Error("[fieldnotes] fitZoomForView requires a non-zero canvas size");
+  }
+  return Math.min(canvasW / view.w, canvasH / view.h);
+}
+function cameraOriginForView(view, zoom, canvasW, canvasH) {
+  return {
+    x: canvasW / 2 - (view.x + view.w / 2) * zoom,
+    y: canvasH / 2 - (view.y + view.h / 2) * zoom
+  };
+}
+function applyCameraView(camera, view, canvasW, canvasH) {
+  assertValidView(view);
+  assertCanvasDims(canvasW, canvasH);
+  if (canvasW === 0 || canvasH === 0) return;
+  camera.setZoom(fitZoomForView(view, canvasW, canvasH));
+  const origin = cameraOriginForView(view, camera.zoom, canvasW, canvasH);
+  camera.moveTo(origin.x, origin.y);
+}
+
+// src/canvas/camera-animator.ts
+var DEFAULT_DURATION_MS3 = 400;
+var FRAMED_EPSILON = 1e-6;
+var easeOutCubic2 = (t) => 1 - Math.pow(1 - t, 3);
+function lerp(a, b, k) {
+  return a + (b - a) * k;
+}
+function lerpView(from, to, k) {
+  return {
+    x: lerp(from.x, to.x, k),
+    y: lerp(from.y, to.y, k),
+    w: lerp(from.w, to.w, k),
+    h: lerp(from.h, to.h, k)
+  };
+}
+function viewsClose(a, b) {
+  return Math.abs(a.x - b.x) < FRAMED_EPSILON && Math.abs(a.y - b.y) < FRAMED_EPSILON && Math.abs(a.w - b.w) < FRAMED_EPSILON && Math.abs(a.h - b.h) < FRAMED_EPSILON;
+}
+var CameraAnimator = class {
+  camera;
+  getCanvasSize;
+  frames;
+  now;
+  durationMs;
+  easing;
+  rafId = null;
+  from = null;
+  to = null;
+  startedAt = 0;
+  endListeners = /* @__PURE__ */ new Set();
+  /**
+   * Monotonic operation counter. `animateTo`/`jumpTo` claim a generation
+   * before emitting 'superseded'; if an onEnd listener starts a newer
+   * operation during that emit, the outer call sees a bumped counter and
+   * bails instead of overwriting the nested animation's state. Without this,
+   * the nested animation would run to completion having never reported an end
+   * reason, breaking the exactly-one guarantee the spec makes.
+   */
+  generation = 0;
+  lastWrite = null;
+  disposed = false;
+  detachListeners = null;
+  constructor(element, camera, options) {
+    if (options.frames !== void 0) {
+      const { requestFrame, cancelFrame } = options.frames;
+      if (typeof requestFrame !== "function" || typeof cancelFrame !== "function") {
+        throw new Error(
+          "[fieldnotes] CameraAnimator: `frames` must supply both requestFrame and cancelFrame"
+        );
+      }
+    }
+    this.camera = camera;
+    this.getCanvasSize = options.getCanvasSize;
+    this.frames = options.frames ?? {
+      requestFrame: (cb) => requestAnimationFrame(cb),
+      cancelFrame: (id) => cancelAnimationFrame(id)
+    };
+    this.now = options.now ?? (() => performance.now());
+    this.durationMs = options.durationMs ?? DEFAULT_DURATION_MS3;
+    this.easing = options.easing ?? easeOutCubic2;
+    if (options.interactive ?? true) {
+      const onUserInput = () => {
+        this.end("cancelled");
+      };
+      const types = ["pointerdown", "wheel", "keydown"];
+      for (const type of types) {
+        element.addEventListener(type, onUserInput, { passive: true });
+      }
+      this.detachListeners = () => {
+        for (const type of types) {
+          element.removeEventListener(type, onUserInput);
+        }
+      };
+    }
+  }
+  get animating() {
+    return this.to !== null;
+  }
+  onEnd(listener) {
+    this.endListeners.add(listener);
+    return () => this.endListeners.delete(listener);
+  }
+  animateTo(view) {
+    const size = this.validateAndMeasure(view);
+    if (size === null) return;
+    const current = this.camera.getVisibleRect(size.w, size.h);
+    const generation = ++this.generation;
+    this.end("superseded");
+    if (this.generation !== generation) return;
+    if (viewsClose(current, view)) {
+      applyCameraView(this.camera, view, size.w, size.h);
+      this.emit("complete");
+      return;
+    }
+    this.from = current;
+    this.to = view;
+    this.startedAt = this.now();
+    this.lastWrite = null;
+    this.rafId = this.frames.requestFrame(this.step);
+  }
+  jumpTo(view) {
+    const size = this.validateAndMeasure(view);
+    if (size === null) return;
+    const generation = ++this.generation;
+    this.end("superseded");
+    if (this.generation !== generation) return;
+    applyCameraView(this.camera, view, size.w, size.h);
+    this.lastWrite = null;
+  }
+  cancel() {
+    if (this.disposed) return;
+    this.end("cancelled");
+  }
+  /**
+   * Terminal. Order is load-bearing: the flag is set BEFORE any listener runs,
+   * because an onEnd listener can call animateTo during the disposal callback.
+   * With the flag set last, that call would start a real animation which the
+   * listener clear then silently discards — a second animation with no end
+   * reason, breaking the exactly-one guarantee.
+   */
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.generation++;
+    const wasAnimating = this.to !== null;
+    this.clearFrame();
+    this.from = null;
+    this.to = null;
+    this.lastWrite = null;
+    if (wasAnimating) this.emit("cancelled");
+    this.endListeners.clear();
+    this.detachListeners?.();
+    this.detachListeners = null;
+  }
+  /**
+   * Steps 1-3 of the public-call contract. Returns null when the caller must
+   * stop, having already handled termination.
+   *
+   * The disposed check precedes validation deliberately: ordering it after
+   * would make `disposed.animateTo(invalidView)` both required to throw and
+   * required to stay silent. Disposal wins — a terminal animator is inert for
+   * every input, and post-disposal calls are exactly the racy teardown paths
+   * where a throw is least useful.
+   */
+  validateAndMeasure(view) {
+    if (this.disposed) return null;
+    assertValidView(view);
+    const size = this.getCanvasSize();
+    assertCanvasDims(size.w, size.h);
+    if (size.w === 0 || size.h === 0) {
+      this.end("cancelled");
+      return null;
+    }
+    return size;
+  }
+  step = () => {
+    if (this.disposed || this.to === null || this.from === null) return;
+    if (this.foreignWrite()) {
+      this.end("cancelled");
+      return;
+    }
+    const size = this.getCanvasSize();
+    if (!canvasDimsUsable(size.w, size.h)) {
+      this.end("cancelled");
+      return;
+    }
+    if (size.w === 0 || size.h === 0) {
+      this.end("cancelled");
+      return;
+    }
+    const elapsed = this.now() - this.startedAt;
+    const t = this.durationMs <= 0 ? 1 : Math.min(1, elapsed / this.durationMs);
+    const view = lerpView(this.from, this.to, this.easing(t));
+    applyCameraView(this.camera, view, size.w, size.h);
+    this.recordWrite();
+    if (t >= 1) {
+      this.end("complete");
+      return;
+    }
+    this.rafId = this.frames.requestFrame(this.step);
+  };
+  recordWrite() {
+    this.lastWrite = {
+      x: this.camera.position.x,
+      y: this.camera.position.y,
+      zoom: this.camera.zoom
+    };
+  }
+  foreignWrite() {
+    if (this.lastWrite === null) return false;
+    const eps = 1e-6;
+    return Math.abs(this.camera.position.x - this.lastWrite.x) > eps || Math.abs(this.camera.position.y - this.lastWrite.y) > eps || Math.abs(this.camera.zoom - this.lastWrite.zoom) > eps;
+  }
+  /** Terminates an in-flight animation with `reason`. No-op when idle. */
+  end(reason) {
+    if (this.disposed || this.to === null) return;
+    this.clearFrame();
+    this.from = null;
+    this.to = null;
+    this.lastWrite = null;
+    this.emit(reason);
+  }
+  clearFrame() {
+    if (this.rafId !== null) {
+      this.frames.cancelFrame(this.rafId);
+      this.rafId = null;
+    }
+  }
+  emit(reason) {
+    for (const listener of [...this.endListeners]) {
+      try {
+        listener(reason);
+      } catch {
+      }
+    }
+  }
+};
+
+// src/canvas/focus-presence.ts
+var FOCUS_PRESENCE_KIND = "focus";
+var AUDIENCES = ["all", "players", "display"];
+function isPositiveFinite(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function isFiniteNumber2(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function isFocusPresence(data) {
+  if (typeof data !== "object" || data === null) return false;
+  const payload = data;
+  if (payload.kind !== FOCUS_PRESENCE_KIND) return false;
+  if (!isFiniteNumber2(payload.x) || !isFiniteNumber2(payload.y)) return false;
+  if (!isPositiveFinite(payload.w) || !isPositiveFinite(payload.h)) return false;
+  if (typeof payload.audience !== "string" || !AUDIENCES.some((a) => a === payload.audience)) {
+    return false;
+  }
+  if (payload.color !== void 0 && typeof payload.color !== "string") return false;
+  return true;
+}
+function toFocusPresence(view, audience, color) {
+  return {
+    kind: FOCUS_PRESENCE_KIND,
+    x: view.x,
+    y: view.y,
+    w: view.w,
+    h: view.h,
+    audience,
+    ...color === void 0 ? {} : { color }
+  };
+}
+
+// src/canvas/remote-focus-receiver.ts
+function audienceIncludes(audience, role) {
+  if (role === "dm") return false;
+  if (audience === "all") return true;
+  if (audience === "players") return role === "player";
+  return role === "display";
+}
+var RemoteFocusReceiver = class {
+  role;
+  animator;
+  animate;
+  pulseColor;
+  overlay;
+  disposed = false;
+  constructor(host, options) {
+    this.role = options.role;
+    this.animator = options.animator;
+    this.animate = options.animate ?? true;
+    this.pulseColor = options.pulseColor;
+    this.overlay = options.pulse ?? true ? new RemotePingOverlay(host, {
+      ...options.pulseColor === void 0 ? {} : { color: options.pulseColor },
+      ...options.pulseDurationMs === void 0 ? {} : { durationMs: options.pulseDurationMs },
+      ...options.pulseRadius === void 0 ? {} : { radius: options.pulseRadius },
+      maxPingsPerSender: 1
+    }) : null;
+  }
+  /**
+   * Applies a presence payload from `sender`. Returns `false` for payloads
+   * that are not focus frames, or are addressed to a different role, so hosts
+   * can feed every presence frame through without disturbing other handlers.
+   */
+  apply(from, data) {
+    if (this.disposed || !isFocusPresence(data)) return false;
+    if (!audienceIncludes(data.audience, this.role)) return false;
+    const view = { x: data.x, y: data.y, w: data.w, h: data.h };
+    if (this.animate) {
+      this.animator.animateTo(view);
+    } else {
+      this.animator.jumpTo(view);
+    }
+    this.overlay?.apply(from, {
+      kind: "ping",
+      x: view.x + view.w / 2,
+      y: view.y + view.h / 2,
+      color: data.color ?? this.pulseColor
+    });
+    return true;
+  }
+  /** Idempotent. Does NOT dispose the animator — the host owns that. */
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.overlay?.dispose();
+  }
+};
+
 // src/tools/hand-tool.ts
 var HandTool = class {
   name = "hand";
@@ -9820,7 +10186,7 @@ function hitTestStroke(stroke, point, radius) {
 }
 
 // src/elements/stroke-erase.ts
-function lerp(a, b, t) {
+function lerp2(a, b, t) {
   return {
     x: a.x + (b.x - a.x) * t,
     y: a.y + (b.y - a.y) * t,
@@ -9879,13 +10245,13 @@ function erasePoints(points, eraser, radius) {
     erased = true;
     if (tLo > 0) {
       if (current.length === 0) current.push(a);
-      current.push(lerp(a, b, tLo));
+      current.push(lerp2(a, b, tLo));
       flush();
     } else {
       flush();
     }
     if (tHi < 1) {
-      current = [lerp(a, b, tHi), b];
+      current = [lerp2(a, b, tHi), b];
     }
   }
   flush();
@@ -12341,7 +12707,7 @@ var LaserTool = class {
 
 // src/tools/ping-tool.ts
 var DEFAULT_COLOR6 = "#ff3b30";
-var DEFAULT_DURATION_MS3 = 1800;
+var DEFAULT_DURATION_MS4 = 1800;
 var DEFAULT_RADIUS4 = 48;
 var DEFAULT_MIN_INTERVAL_MS2 = 300;
 var PingTool = class {
@@ -12358,7 +12724,7 @@ var PingTool = class {
   constructor(options = {}) {
     this.name = options.name ?? "ping";
     this.color = options.color ?? DEFAULT_COLOR6;
-    this.durationMs = options.durationMs ?? DEFAULT_DURATION_MS3;
+    this.durationMs = options.durationMs ?? DEFAULT_DURATION_MS4;
     this.radius = options.radius ?? DEFAULT_RADIUS4;
     this.minIntervalMs = options.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS2;
   }
@@ -12460,14 +12826,16 @@ var PingTool = class {
 };
 
 // src/index.ts
-var VERSION = "0.60.0";
+var VERSION = "0.61.0";
 export {
   ArrowTool,
   AutoSave,
   Camera,
+  CameraAnimator,
   DEFAULT_NOTE_FONT_SIZE,
   ElementStore,
   EraserTool,
+  FOCUS_PRESENCE_KIND,
   HandTool,
   HistoryStack,
   ImageTool,
@@ -12485,6 +12853,7 @@ export {
   PencilTool,
   PingInput,
   PingTool,
+  RemoteFocusReceiver,
   RemoteLaserOverlay,
   RemoteMeasureOverlay,
   RemotePingOverlay,
@@ -12495,7 +12864,10 @@ export {
   ToolManager,
   VERSION,
   Viewport,
+  applyCameraView,
   boundsIntersect,
+  cameraOriginForView,
+  captureCameraView,
   createArrow,
   createGrid,
   createHtmlElement,
@@ -12508,6 +12880,7 @@ export {
   drawHexPath,
   exportImage,
   exportSvg,
+  fitZoomForView,
   getActiveFormats,
   getArrowBounds,
   getArrowControlPoint,
@@ -12523,6 +12896,7 @@ export {
   getHexCellsInRectangle,
   getHexCellsInSquare,
   getHexDistance,
+  isFocusPresence,
   isLaserTrailPresence,
   isMeasurePresence,
   isNearBezier,
@@ -12532,6 +12906,7 @@ export {
   snapPoint,
   snapToHexCenter,
   styleToPatch,
+  toFocusPresence,
   toLaserTrailPresence,
   toMeasurePresence,
   toPingPresence,