@fieldnotes/core 0.64.0 → 0.65.0

package/dist/index.cjs

@@ -20,6 +20,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AWARENESS_MAX_SELECTION: () => AWARENESS_MAX_SELECTION,
+  AWARENESS_PRESENCE_KIND: () => AWARENESS_PRESENCE_KIND,
   ArrowTool: () => ArrowTool,
   AutoSave: () => AutoSave,
   Camera: () => Camera,
@@ -38,6 +40,7 @@ __export(index_exports, {
   LASER_TRAIL_PRESENCE_KIND: () => LASER_TRAIL_PRESENCE_KIND,
   LaserTool: () => LaserTool,
   LayerManager: () => LayerManager,
+  LocalAwareness: () => LocalAwareness,
   LocalStorageAdapter: () => LocalStorageAdapter,
   MEASURE_PRESENCE_KIND: () => MEASURE_PRESENCE_KIND,
   MeasureTool: () => MeasureTool,
@@ -46,16 +49,20 @@ __export(index_exports, {
   NoteTool: () => NoteTool,
   PATH_PRESENCE_KIND: () => PATH_PRESENCE_KIND,
   PATH_PRESENCE_MAX_POINTS: () => PATH_PRESENCE_MAX_POINTS,
+  PEER_COLORS: () => PEER_COLORS,
   PING_PRESENCE_KIND: () => PING_PRESENCE_KIND,
   PathTool: () => PathTool,
+  PeerRoster: () => PeerRoster,
   PencilTool: () => PencilTool,
   PingInput: () => PingInput,
   PingTool: () => PingTool,
+  RemoteCursorOverlay: () => RemoteCursorOverlay,
   RemoteFocusReceiver: () => RemoteFocusReceiver,
   RemoteLaserOverlay: () => RemoteLaserOverlay,
   RemoteMeasureOverlay: () => RemoteMeasureOverlay,
   RemotePathOverlay: () => RemotePathOverlay,
   RemotePingOverlay: () => RemotePingOverlay,
+  RemoteSelectionOverlay: () => RemoteSelectionOverlay,
   SelectTool: () => SelectTool,
   ShapeTool: () => ShapeTool,
   TemplateTool: () => TemplateTool,
@@ -64,6 +71,7 @@ __export(index_exports, {
   VERSION: () => VERSION,
   Viewport: () => Viewport,
   applyCameraView: () => applyCameraView,
+  attachAwareness: () => attachAwareness,
   boundsIntersect: () => boundsIntersect,
   cameraOriginForView: () => cameraOriginForView,
   captureCameraView: () => captureCameraView,
@@ -77,6 +85,7 @@ __export(index_exports, {
   createStroke: () => createStroke,
   createTemplate: () => createTemplate,
   createText: () => createText,
+  defaultPeerColor: () => defaultPeerColor,
   drawHexPath: () => drawHexPath,
   elementRectsEqual: () => elementRectsEqual,
   exportImage: () => exportImage,
@@ -99,6 +108,7 @@ __export(index_exports, {
   getHexCellsInSquare: () => getHexCellsInSquare,
   getHexDistance: () => getHexDistance,
   gridDistanceCells: () => gridDistanceCells,
+  isAwarenessPresence: () => isAwarenessPresence,
   isFocusPresence: () => isFocusPresence,
   isLaserTrailPresence: () => isLaserTrailPresence,
   isMeasurePresence: () => isMeasurePresence,
@@ -12228,6 +12238,800 @@ var RemoteFocusReceiver = class {
   }
 };
 
+// src/canvas/awareness-presence.ts
+var AWARENESS_PRESENCE_KIND = "awareness";
+var AWARENESS_MAX_SELECTION = 256;
+var MAX_ID_LENGTH = 128;
+var MAX_NAME_LENGTH = 64;
+var MAX_COLOR_LENGTH2 = 64;
+var MAX_ROLE_LENGTH = 32;
+var MAX_TOOL_LENGTH = 64;
+function isBoundedString(value, max) {
+  return typeof value === "string" && value.length <= max;
+}
+function isOptionalBoundedString(value, max) {
+  return value === void 0 || isBoundedString(value, max);
+}
+function isFinitePoint4(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 isAwarenessPresence(data) {
+  if (typeof data !== "object" || data === null) return false;
+  const payload = data;
+  if (payload.kind !== AWARENESS_PRESENCE_KIND) return false;
+  if (!isBoundedString(payload.id, MAX_ID_LENGTH) || payload.id.length === 0) return false;
+  if ("cleared" in payload) return payload.cleared === true;
+  if (!isOptionalBoundedString(payload.name, MAX_NAME_LENGTH)) return false;
+  if (!isOptionalBoundedString(payload.color, MAX_COLOR_LENGTH2)) return false;
+  if (!isOptionalBoundedString(payload.role, MAX_ROLE_LENGTH)) return false;
+  if (!isOptionalBoundedString(payload.tool, MAX_TOOL_LENGTH)) return false;
+  if (payload.cursor !== void 0 && !isFinitePoint4(payload.cursor)) return false;
+  if (payload.selection !== void 0) {
+    if (!Array.isArray(payload.selection)) return false;
+    if (payload.selection.length > AWARENESS_MAX_SELECTION) return false;
+    for (const id of payload.selection) {
+      if (!isBoundedString(id, MAX_ID_LENGTH) || id.length === 0) return false;
+    }
+  }
+  return true;
+}
+
+// src/canvas/awareness-roster.ts
+var DEFAULT_STALE_MS = 45e3;
+var EMPTY_PEERS = Object.freeze([]);
+var EMPTY_SELECTION = Object.freeze([]);
+function sameSelection(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+function samePoint2(a, b) {
+  if (a === null || b === null) return a === b;
+  return a.x === b.x && a.y === b.y;
+}
+function toPeer(from, data, prev) {
+  const cursor = data.cursor ? { x: data.cursor.x, y: data.cursor.y } : null;
+  const incoming = data.selection ?? EMPTY_SELECTION;
+  const selection = prev && sameSelection(prev.selection, incoming) ? prev.selection : incoming.length === 0 ? EMPTY_SELECTION : Object.freeze([...incoming]);
+  const tool = data.tool ?? null;
+  if (prev && prev.id === data.id && prev.name === data.name && prev.color === data.color && prev.role === data.role && prev.tool === tool && prev.selection === selection && samePoint2(prev.cursor, cursor)) {
+    return prev;
+  }
+  const peer = {
+    from,
+    id: data.id,
+    ...data.name === void 0 ? {} : { name: data.name },
+    ...data.color === void 0 ? {} : { color: data.color },
+    ...data.role === void 0 ? {} : { role: data.role },
+    cursor,
+    selection,
+    tool
+  };
+  return peer;
+}
+var PeerRoster = class {
+  staleMs;
+  now;
+  rows = /* @__PURE__ */ new Map();
+  discovered = /* @__PURE__ */ new Map();
+  changeListeners = /* @__PURE__ */ new Set();
+  discoverListeners = /* @__PURE__ */ new Set();
+  leaveListeners = /* @__PURE__ */ new Set();
+  snapshot = EMPTY_PEERS;
+  snapshotDirty = false;
+  staleTimer = null;
+  isDisposed = false;
+  constructor(options = {}) {
+    this.staleMs = options.staleMs ?? DEFAULT_STALE_MS;
+    this.now = options.now ?? (() => Date.now());
+  }
+  get disposed() {
+    return this.isDisposed;
+  }
+  /**
+   * Applies a presence payload from `from`. Non-awareness or malformed payloads
+   * return `false` untouched, so hosts can feed every presence frame through.
+   */
+  apply(from, data) {
+    if (this.isDisposed || !isAwarenessPresence(data)) return false;
+    const isNew = !this.discovered.has(from);
+    this.discovered.set(from, this.now());
+    if ("cleared" in data) {
+      this.dropRow(from, "cleared");
+    } else {
+      const prev = this.rows.get(from);
+      const next = toPeer(from, data, prev);
+      if (next !== prev) {
+        this.rows.set(from, next);
+        this.changed();
+      }
+    }
+    this.armStaleTimer();
+    if (isNew) this.emit(this.discoverListeners, (l) => l(from));
+    return true;
+  }
+  /** Server-authored presence-leave: drops the row AND the discovery entry. */
+  remove(from) {
+    if (this.isDisposed) return;
+    const hadEntry = this.discovered.delete(from);
+    this.dropRow(from, "left");
+    if (hadEntry) this.armStaleTimer();
+  }
+  getPeers() {
+    if (this.snapshotDirty) {
+      this.snapshot = this.rows.size === 0 ? EMPTY_PEERS : Object.freeze([...this.rows.values()]);
+      this.snapshotDirty = false;
+    }
+    return this.snapshot;
+  }
+  getPeer(from) {
+    return this.rows.get(from);
+  }
+  /** Fires only when `getPeers()` would return a new reference. */
+  onChange(listener) {
+    this.changeListeners.add(listener);
+    return () => this.changeListeners.delete(listener);
+  }
+  /** First valid frame from a sender since its discovery entry was last dropped. */
+  onDiscover(listener) {
+    this.discoverListeners.add(listener);
+    return () => this.discoverListeners.delete(listener);
+  }
+  onLeave(listener) {
+    this.leaveListeners.add(listener);
+    return () => this.leaveListeners.delete(listener);
+  }
+  dispose() {
+    if (this.isDisposed) return;
+    this.isDisposed = true;
+    if (this.staleTimer !== null) clearTimeout(this.staleTimer);
+    this.staleTimer = null;
+    this.rows.clear();
+    this.discovered.clear();
+    this.snapshot = EMPTY_PEERS;
+    this.snapshotDirty = false;
+    this.changeListeners.clear();
+    this.discoverListeners.clear();
+    this.leaveListeners.clear();
+  }
+  dropRow(from, reason) {
+    const row = this.rows.get(from);
+    if (!row) return;
+    this.rows.delete(from);
+    this.changed();
+    this.emit(this.leaveListeners, (l) => l(row, reason));
+  }
+  changed() {
+    this.snapshotDirty = true;
+    this.emit(this.changeListeners, (l) => l());
+  }
+  emit(listeners, call) {
+    for (const listener of [...listeners]) {
+      try {
+        call(listener);
+      } catch {
+      }
+    }
+  }
+  armStaleTimer() {
+    if (this.staleTimer !== null) clearTimeout(this.staleTimer);
+    this.staleTimer = null;
+    if (!Number.isFinite(this.staleMs) || this.staleMs <= 0 || this.isDisposed || this.discovered.size === 0) {
+      return;
+    }
+    let earliest = Infinity;
+    for (const seen of this.discovered.values()) if (seen < earliest) earliest = seen;
+    const delay = Math.min(Math.max(0, earliest + this.staleMs - this.now()), 2 ** 31 - 1);
+    this.staleTimer = setTimeout(() => {
+      this.staleTimer = null;
+      this.expireStale();
+    }, delay);
+  }
+  expireStale() {
+    const t = this.now();
+    for (const from of [...this.discovered.keys()]) {
+      const seen = this.discovered.get(from);
+      if (seen === void 0 || t - seen < this.staleMs) continue;
+      this.discovered.delete(from);
+      this.dropRow(from, "stale");
+    }
+    this.armStaleTimer();
+  }
+};
+
+// src/canvas/awareness-publisher.ts
+var DEFAULT_FIELDS = Object.freeze({
+  cursor: true,
+  selection: false,
+  tool: true
+});
+var DEFAULT_INTERVAL_MS = 50;
+var DEFAULT_HEARTBEAT_MS = 15e3;
+var MAX_TIMER_DELAY_MS = 2 ** 31 - 1;
+var MAX_IDENTITY_ID_LENGTH = 128;
+var MAX_IDENTITY_NAME_LENGTH = 64;
+var MAX_IDENTITY_COLOR_LENGTH = 64;
+var MAX_IDENTITY_ROLE_LENGTH = 32;
+var MAX_TOOL_LENGTH2 = 64;
+var MAX_SELECTION_ID_LENGTH = 128;
+function normalizeIntervalMs(value) {
+  return Number.isFinite(value) && value >= 0 ? value : 0;
+}
+function normalizeHeartbeatMs(value) {
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}
+var LocalAwareness = class {
+  host;
+  element;
+  send;
+  selectionFilter;
+  onError;
+  intervalMs;
+  heartbeatMs;
+  identity;
+  fields;
+  lastPointer = null;
+  selection = [];
+  selectionFailed = false;
+  tool;
+  dirty = false;
+  lastSentAt = null;
+  throttleTimer = null;
+  heartbeatTimer = null;
+  unsubscribers = [];
+  isDisposed = false;
+  handlePointerMove = (e) => this.onPointerMove(e);
+  handlePointerEnd = (e) => this.onPointerEnd(e);
+  constructor(host, options) {
+    const element = options.element ?? host.domLayer.parentElement;
+    if (!element) throw new Error("LocalAwareness: the viewport wrapper is not mounted");
+    this.host = host;
+    this.element = element;
+    this.send = options.send;
+    this.selectionFilter = options.selectionFilter;
+    this.onError = options.onError;
+    this.intervalMs = normalizeIntervalMs(options.intervalMs ?? DEFAULT_INTERVAL_MS);
+    this.heartbeatMs = normalizeHeartbeatMs(options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS);
+    this.identity = this.normalizeIdentity(options.identity);
+    this.fields = mergeFields(DEFAULT_FIELDS, options.fields ?? {});
+    this.tool = host.toolManager.activeTool?.name ?? null;
+    if (this.fields.selection) this.refreshSelection();
+    const opts = { passive: true };
+    element.addEventListener("pointermove", this.handlePointerMove, opts);
+    element.addEventListener("pointerleave", this.handlePointerEnd, opts);
+    element.addEventListener("pointercancel", this.handlePointerEnd, opts);
+    this.unsubscribers.push(
+      host.onSelectionChange(() => {
+        if (this.fields.selection) this.schedule();
+      }),
+      host.toolManager.onChange((name) => {
+        this.tool = name;
+        if (this.fields.tool) this.schedule();
+      })
+    );
+    this.armHeartbeat();
+  }
+  get disposed() {
+    return this.isDisposed;
+  }
+  getFields() {
+    return this.fields;
+  }
+  setIdentity(identity) {
+    this.identity = this.normalizeIdentity(identity);
+    this.schedule();
+  }
+  /** Merges the given flags into the current policy; `undefined` keys are ignored. */
+  setFields(fields) {
+    this.fields = mergeFields(this.fields, fields);
+    this.schedule();
+  }
+  /**
+   * Requests a full frame: immediate when idle, otherwise folded into the
+   * pending trailing frame (so N simultaneous requests cost one frame). Hosts
+   * call it when the connection becomes live or reconnects.
+   */
+  announce() {
+    this.schedule();
+  }
+  /**
+   * The complete state a frame carries right now. Side-effecting when
+   * selection publishing is on: re-reads `getSelectedIds()`, re-runs
+   * `selectionFilter`, updates the fail-closed selection state, and may call
+   * `onError`. A no-op with respect to selection while publishing is off.
+   */
+  getState() {
+    const frame = { kind: AWARENESS_PRESENCE_KIND, id: this.identity.id };
+    if (this.identity.name !== void 0) frame.name = this.identity.name;
+    if (this.identity.color !== void 0) frame.color = this.identity.color;
+    if (this.identity.role !== void 0) frame.role = this.identity.role;
+    if (this.fields.cursor && this.lastPointer !== null) {
+      frame.cursor = { x: this.lastPointer.x, y: this.lastPointer.y };
+    }
+    if (this.fields.selection) {
+      this.refreshSelection();
+      if (!this.selectionFailed && this.selection.length > 0) {
+        frame.selection = [...this.selection];
+      }
+    }
+    if (this.fields.tool && this.tool !== null && this.tool.length <= MAX_TOOL_LENGTH2) {
+      frame.tool = this.tool;
+    }
+    return frame;
+  }
+  dispose() {
+    if (this.isDisposed) return;
+    this.isDisposed = true;
+    if (this.throttleTimer !== null) clearTimeout(this.throttleTimer);
+    this.throttleTimer = null;
+    if (this.heartbeatTimer !== null) clearTimeout(this.heartbeatTimer);
+    this.heartbeatTimer = null;
+    this.element.removeEventListener("pointermove", this.handlePointerMove);
+    this.element.removeEventListener("pointerleave", this.handlePointerEnd);
+    this.element.removeEventListener("pointercancel", this.handlePointerEnd);
+    for (const unsub of this.unsubscribers) unsub();
+    this.unsubscribers.length = 0;
+    this.safeSend({ kind: AWARENESS_PRESENCE_KIND, id: this.identity.id, cleared: true });
+  }
+  now() {
+    return Date.now();
+  }
+  onPointerMove(e) {
+    if (!e.isPrimary) return;
+    const rect = this.element.getBoundingClientRect();
+    const world = this.host.camera.screenToWorld({
+      x: e.clientX - rect.left,
+      y: e.clientY - rect.top
+    });
+    this.lastPointer = Number.isFinite(world.x) && Number.isFinite(world.y) ? { x: world.x, y: world.y } : null;
+    if (this.fields.cursor) this.schedule();
+  }
+  onPointerEnd(e) {
+    if (!e.isPrimary || this.lastPointer === null) return;
+    this.lastPointer = null;
+    if (this.fields.cursor) this.schedule();
+  }
+  refreshSelection() {
+    try {
+      const raw = this.host.getSelectedIds();
+      const ids = this.selectionFilter ? this.selectionFilter(raw) : raw;
+      if (!Array.isArray(ids)) throw new TypeError("selectionFilter must return an array");
+      for (const id of ids) {
+        if (typeof id !== "string") throw new TypeError("selectionFilter must return strings");
+        if (id.length === 0 || id.length > MAX_SELECTION_ID_LENGTH) {
+          throw new TypeError("selectionFilter must return ids of 1..128 characters");
+        }
+      }
+      this.selection = ids.slice(0, AWARENESS_MAX_SELECTION);
+      this.selectionFailed = false;
+    } catch (error) {
+      this.selection = [];
+      this.selectionFailed = true;
+      this.report(error);
+    }
+  }
+  schedule() {
+    if (this.isDisposed) return;
+    this.dirty = true;
+    if (this.throttleTimer !== null) return;
+    const elapsed = this.lastSentAt === null ? Infinity : this.now() - this.lastSentAt;
+    if (elapsed >= this.intervalMs) {
+      this.flush();
+      return;
+    }
+    this.throttleTimer = setTimeout(
+      () => {
+        this.throttleTimer = null;
+        if (this.dirty) this.flush();
+      },
+      Math.min(this.intervalMs - elapsed, MAX_TIMER_DELAY_MS)
+    );
+  }
+  flush() {
+    this.dirty = false;
+    this.lastSentAt = this.now();
+    this.safeSend(this.getState());
+    this.armHeartbeat();
+  }
+  armHeartbeat() {
+    if (this.heartbeatTimer !== null) clearTimeout(this.heartbeatTimer);
+    this.heartbeatTimer = null;
+    if (this.heartbeatMs <= 0 || this.isDisposed) return;
+    this.heartbeatTimer = setTimeout(
+      () => {
+        this.heartbeatTimer = null;
+        this.flush();
+      },
+      Math.min(this.heartbeatMs, MAX_TIMER_DELAY_MS)
+    );
+  }
+  safeSend(frame) {
+    try {
+      this.send(frame);
+    } catch (error) {
+      this.report(error);
+    }
+  }
+  report(error) {
+    try {
+      this.onError?.(error);
+    } catch {
+    }
+  }
+  /**
+   * Truncates identity strings to the wire caps and rejects an invalid id, so a
+   * sender can never publish a frame that the wire guard would drop outright.
+   * A truncated field is reported through `onError` (a `RangeError`) rather
+   * than silently shortened, so a caller passing an over-long name finds out.
+   */
+  normalizeIdentity(identity) {
+    if (identity.id.length === 0 || identity.id.length > MAX_IDENTITY_ID_LENGTH) {
+      throw new RangeError("LocalAwareness: identity.id must be 1..128 characters");
+    }
+    const normalized = {
+      id: identity.id
+    };
+    if (identity.name !== void 0) {
+      normalized.name = identity.name.slice(0, MAX_IDENTITY_NAME_LENGTH);
+      if (identity.name.length > MAX_IDENTITY_NAME_LENGTH) {
+        this.report(
+          new RangeError(
+            `LocalAwareness: identity.name truncated to ${MAX_IDENTITY_NAME_LENGTH} characters`
+          )
+        );
+      }
+    }
+    if (identity.color !== void 0) {
+      normalized.color = identity.color.slice(0, MAX_IDENTITY_COLOR_LENGTH);
+      if (identity.color.length > MAX_IDENTITY_COLOR_LENGTH) {
+        this.report(
+          new RangeError(
+            `LocalAwareness: identity.color truncated to ${MAX_IDENTITY_COLOR_LENGTH} characters`
+          )
+        );
+      }
+    }
+    if (identity.role !== void 0) {
+      normalized.role = identity.role.slice(0, MAX_IDENTITY_ROLE_LENGTH);
+      if (identity.role.length > MAX_IDENTITY_ROLE_LENGTH) {
+        this.report(
+          new RangeError(
+            `LocalAwareness: identity.role truncated to ${MAX_IDENTITY_ROLE_LENGTH} characters`
+          )
+        );
+      }
+    }
+    return normalized;
+  }
+};
+function mergeFields(current, patch) {
+  return Object.freeze({
+    cursor: patch.cursor ?? current.cursor,
+    selection: patch.selection ?? current.selection,
+    tool: patch.tool ?? current.tool
+  });
+}
+
+// src/canvas/remote-cursor-overlay.ts
+var PEER_COLORS = Object.freeze([
+  "#e11d48",
+  "#ea580c",
+  "#ca8a04",
+  "#16a34a",
+  "#0d9488",
+  "#0284c7",
+  "#2563eb",
+  "#7c3aed",
+  "#c026d3",
+  "#db2777",
+  "#4d7c0f",
+  "#b45309"
+]);
+function defaultPeerColor(seed) {
+  if (seed.length === 0) return PEER_COLORS[0] ?? "#2563eb";
+  let hash = 2166136261;
+  for (let i = 0; i < seed.length; i++) {
+    hash ^= seed.charCodeAt(i);
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return PEER_COLORS[hash % PEER_COLORS.length] ?? "#2563eb";
+}
+var DEFAULT_LABEL_FONT = "12px sans-serif";
+var LABEL_PAD_X = 6;
+var LABEL_PAD_Y = 3;
+var LABEL_HEIGHT = 16;
+var LABEL_OFFSET = 14;
+var MAX_LABEL_WIDTH_CACHE = 64;
+var RemoteCursorOverlay = class {
+  host;
+  roster;
+  colorFor;
+  showLabels;
+  labelFont;
+  labelWidths = /* @__PURE__ */ new Map();
+  unregister;
+  unsubscribe;
+  isDisposed = false;
+  constructor(host, roster, options = {}) {
+    this.host = host;
+    this.roster = roster;
+    this.colorFor = options.colorFor;
+    this.showLabels = options.showLabels ?? true;
+    this.labelFont = options.labelFont ?? DEFAULT_LABEL_FONT;
+    this.unregister = host.registerOverlay((ctx) => this.render(ctx));
+    this.unsubscribe = roster.onChange(() => {
+      if (this.labelWidths.size > MAX_LABEL_WIDTH_CACHE) this.labelWidths.clear();
+      host.requestRender();
+    });
+  }
+  get disposed() {
+    return this.isDisposed;
+  }
+  resolveColor(peer) {
+    return this.colorFor?.(peer) ?? peer.color ?? defaultPeerColor(peer.id);
+  }
+  dispose() {
+    if (this.isDisposed) return;
+    this.isDisposed = true;
+    this.unsubscribe?.();
+    this.unsubscribe = null;
+    this.unregister?.();
+    this.unregister = null;
+    this.labelWidths.clear();
+    this.host.requestRender();
+  }
+  render(ctx) {
+    if (this.isDisposed) return;
+    const zoom = this.host.camera.zoom;
+    const inv = zoom > 0 && Number.isFinite(zoom) ? 1 / zoom : 1;
+    for (const peer of this.roster.getPeers()) {
+      if (peer.cursor === null) continue;
+      const color = this.resolveColor(peer);
+      ctx.save();
+      ctx.translate(peer.cursor.x, peer.cursor.y);
+      ctx.scale(inv, inv);
+      ctx.beginPath();
+      ctx.moveTo(0, 0);
+      ctx.lineTo(0, 16);
+      ctx.lineTo(4.5, 12.5);
+      ctx.lineTo(11, 12.5);
+      ctx.closePath();
+      ctx.fillStyle = color;
+      ctx.fill();
+      ctx.strokeStyle = "#ffffff";
+      ctx.lineWidth = 1;
+      ctx.stroke();
+      if (this.showLabels && peer.name !== void 0 && peer.name.length > 0) {
+        this.drawLabel(ctx, peer.name, color);
+      }
+      ctx.restore();
+    }
+  }
+  drawLabel(ctx, name, color) {
+    ctx.font = this.labelFont;
+    const key = `${this.labelFont} ${name}`;
+    let width = this.labelWidths.get(key);
+    if (width === void 0) {
+      width = ctx.measureText(name).width;
+      this.labelWidths.set(key, width);
+    }
+    const w = width + LABEL_PAD_X * 2;
+    ctx.fillStyle = color;
+    ctx.beginPath();
+    ctx.roundRect(LABEL_OFFSET, LABEL_OFFSET, w, LABEL_HEIGHT + LABEL_PAD_Y, 4);
+    ctx.fill();
+    ctx.fillStyle = "#ffffff";
+    ctx.textAlign = "left";
+    ctx.textBaseline = "middle";
+    ctx.fillText(name, LABEL_OFFSET + LABEL_PAD_X, LABEL_OFFSET + (LABEL_HEIGHT + LABEL_PAD_Y) / 2);
+  }
+};
+
+// src/canvas/remote-selection-overlay.ts
+var DEFAULT_ALPHA = 0.6;
+var DEFAULT_LINE_WIDTH_PX = 2;
+var RemoteSelectionOverlay = class {
+  host;
+  roster;
+  colorFor;
+  alpha;
+  lineWidthPx;
+  signatures = [];
+  outlines = [];
+  storeDirty = true;
+  unregister;
+  unsubscribers = [];
+  isDisposed = false;
+  constructor(host, roster, options = {}) {
+    this.host = host;
+    this.roster = roster;
+    this.colorFor = options.colorFor;
+    this.alpha = options.alpha ?? DEFAULT_ALPHA;
+    this.lineWidthPx = options.lineWidthPx ?? DEFAULT_LINE_WIDTH_PX;
+    this.unregister = host.registerOverlay((ctx) => this.render(ctx));
+    const invalidate = () => {
+      this.storeDirty = true;
+      host.requestRender();
+    };
+    this.unsubscribers.push(
+      roster.onChange(() => host.requestRender()),
+      host.store.onChange(invalidate),
+      host.layerManager.on("change", invalidate)
+    );
+  }
+  get disposed() {
+    return this.isDisposed;
+  }
+  dispose() {
+    if (this.isDisposed) return;
+    this.isDisposed = true;
+    for (const unsub of this.unsubscribers) unsub();
+    this.unsubscribers.length = 0;
+    this.unregister?.();
+    this.unregister = null;
+    this.signatures = [];
+    this.outlines = [];
+    this.host.requestRender();
+  }
+  resolveColor(peer) {
+    return this.colorFor?.(peer) ?? peer.color ?? defaultPeerColor(peer.id);
+  }
+  /** Recomputes outlines only when the selection signature or the store/layers changed. */
+  rebuild() {
+    const peers = this.roster.getPeers();
+    const next = [];
+    for (const peer of peers) {
+      if (peer.selection.length === 0) continue;
+      next.push({ from: peer.from, selection: peer.selection, color: this.resolveColor(peer) });
+    }
+    let changed = this.storeDirty || next.length !== this.signatures.length;
+    if (!changed) {
+      for (let i = 0; i < next.length; i++) {
+        const a = next[i];
+        const b = this.signatures[i];
+        if (!a || !b || a.from !== b.from || a.selection !== b.selection || a.color !== b.color) {
+          changed = true;
+          break;
+        }
+      }
+    }
+    if (!changed) return;
+    this.storeDirty = false;
+    this.signatures = next;
+    if (next.length === 0) {
+      this.outlines = [];
+      return;
+    }
+    const colorById = /* @__PURE__ */ new Map();
+    for (const sig of next) {
+      for (const id of sig.selection) if (!colorById.has(id)) colorById.set(id, sig.color);
+    }
+    const layers = this.host.layerManager;
+    const rects = computeElementRects(
+      this.host.store,
+      (element) => colorById.has(element.id) && layers.isLayerVisible(element.layerId) ? element.id : null
+    );
+    this.outlines = rects.map((rect) => ({ rect, color: colorById.get(rect.id) ?? "#2563eb" }));
+  }
+  render(ctx) {
+    if (this.isDisposed) return;
+    this.rebuild();
+    if (this.outlines.length === 0) return;
+    const zoom = this.host.camera.zoom;
+    const inv = zoom > 0 && Number.isFinite(zoom) ? 1 / zoom : 1;
+    ctx.save();
+    ctx.globalAlpha = this.alpha;
+    ctx.lineWidth = this.lineWidthPx * inv;
+    for (const { rect, color } of this.outlines) {
+      ctx.save();
+      ctx.strokeStyle = color;
+      ctx.translate(rect.x + rect.w / 2, rect.y + rect.h / 2);
+      if (rect.rotation !== 0) ctx.rotate(rect.rotation);
+      ctx.strokeRect(-rect.w / 2, -rect.h / 2, rect.w, rect.h);
+      ctx.restore();
+    }
+    ctx.restore();
+  }
+};
+
+// src/canvas/attach-awareness.ts
+function attachAwareness(viewport, channel, options) {
+  const {
+    roster: rosterOptions,
+    cursors: cursorOptions,
+    selections: selectionOptions,
+    publish,
+    ...localOptions
+  } = options;
+  const roster = new PeerRoster(rosterOptions);
+  let local = null;
+  let cursors = null;
+  let selections = null;
+  const unsubscribers = [];
+  try {
+    local = publish === false ? null : new LocalAwareness(viewport, {
+      ...localOptions,
+      send: (data) => channel.sendPresence(data)
+    });
+    cursors = cursorOptions === false ? null : new RemoteCursorOverlay(viewport, roster, cursorOptions ?? {});
+    selections = selectionOptions === void 0 || selectionOptions === false ? null : new RemoteSelectionOverlay(
+      viewport,
+      roster,
+      selectionOptions === true ? {} : selectionOptions
+    );
+    if (publish !== false) unsubscribers.push(roster.onDiscover(() => local?.announce()));
+    unsubscribers.push(
+      channel.onPresence((from, data) => {
+        roster.apply(from, data);
+      })
+    );
+    unsubscribers.push(channel.onPresenceLeave((from) => roster.remove(from)));
+  } catch (error) {
+    for (let i = unsubscribers.length - 1; i >= 0; i--) {
+      try {
+        unsubscribers[i]?.();
+      } catch {
+      }
+    }
+    unsubscribers.length = 0;
+    try {
+      selections?.dispose();
+    } catch {
+    }
+    try {
+      cursors?.dispose();
+    } catch {
+    }
+    try {
+      local?.dispose();
+    } catch {
+    }
+    try {
+      roster.dispose();
+    } catch {
+    }
+    throw error;
+  }
+  let disposed = false;
+  return {
+    roster,
+    local,
+    cursors,
+    selections,
+    announce: () => local?.announce(),
+    setFields: (fields) => local?.setFields(fields),
+    dispose: () => {
+      if (disposed) return;
+      disposed = true;
+      try {
+        local?.dispose();
+      } catch {
+      }
+      try {
+        cursors?.dispose();
+      } catch {
+      }
+      try {
+        selections?.dispose();
+      } catch {
+      }
+      try {
+        roster.dispose();
+      } catch {
+      }
+      for (const unsub of unsubscribers) {
+        try {
+          unsub();
+        } catch {
+        }
+      }
+      unsubscribers.length = 0;
+    }
+  };
+}
+
 // src/tools/hand-tool.ts
 var HandTool = class {
   name = "hand";
@@ -13893,7 +14697,7 @@ var MeasureTool = class {
 // src/tools/path-tool.ts
 var EPS2 = 1e-6;
 var DEFAULT_COMMIT_TAP_RADIUS_PX = 12;
-function samePoint2(a, b) {
+function samePoint3(a, b) {
   return Math.abs(a.x - b.x) < EPS2 && Math.abs(a.y - b.y) < EPS2;
 }
 var PathTool = class {
@@ -14037,7 +14841,7 @@ var PathTool = class {
       return;
     }
     const last = this.lastWaypoint();
-    if (this.cursor && last && !samePoint2(this.cursor, last)) {
+    if (this.cursor && last && !samePoint3(this.cursor, last)) {
       this.waypoints.push({ ...this.cursor });
     }
     this.scheduleEmission();
@@ -14098,7 +14902,7 @@ var PathTool = class {
    * world point.
    */
   withinCommitRadius(point, last, ctx) {
-    if (samePoint2(point, last)) return true;
+    if (samePoint3(point, last)) return true;
     if (this.hasSnappingGrid()) return false;
     const zoom = ctx.camera.zoom;
     if (!(zoom > 0)) return false;
@@ -14146,7 +14950,7 @@ var PathTool = class {
   measure(cursor) {
     const points = this.waypoints.map((p) => ({ ...p }));
     const last = points[points.length - 1];
-    if (cursor && (!last || !samePoint2(cursor, last))) points.push({ ...cursor });
+    if (cursor && (!last || !samePoint3(cursor, last))) points.push({ ...cursor });
     const { total, cumulative } = pathDistanceCells(points, {
       gridSize: this.gridSize,
       gridType: this.gridType,
@@ -14794,9 +15598,11 @@ var PingTool = class {
 };
 
 // src/index.ts
-var VERSION = "0.64.0";
+var VERSION = "0.65.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AWARENESS_MAX_SELECTION,
+  AWARENESS_PRESENCE_KIND,
   ArrowTool,
   AutoSave,
   Camera,
@@ -14815,6 +15621,7 @@ var VERSION = "0.64.0";
   LASER_TRAIL_PRESENCE_KIND,
   LaserTool,
   LayerManager,
+  LocalAwareness,
   LocalStorageAdapter,
   MEASURE_PRESENCE_KIND,
   MeasureTool,
@@ -14823,16 +15630,20 @@ var VERSION = "0.64.0";
   NoteTool,
   PATH_PRESENCE_KIND,
   PATH_PRESENCE_MAX_POINTS,
+  PEER_COLORS,
   PING_PRESENCE_KIND,
   PathTool,
+  PeerRoster,
   PencilTool,
   PingInput,
   PingTool,
+  RemoteCursorOverlay,
   RemoteFocusReceiver,
   RemoteLaserOverlay,
   RemoteMeasureOverlay,
   RemotePathOverlay,
   RemotePingOverlay,
+  RemoteSelectionOverlay,
   SelectTool,
   ShapeTool,
   TemplateTool,
@@ -14841,6 +15652,7 @@ var VERSION = "0.64.0";
   VERSION,
   Viewport,
   applyCameraView,
+  attachAwareness,
   boundsIntersect,
   cameraOriginForView,
   captureCameraView,
@@ -14854,6 +15666,7 @@ var VERSION = "0.64.0";
   createStroke,
   createTemplate,
   createText,
+  defaultPeerColor,
   drawHexPath,
   elementRectsEqual,
   exportImage,
@@ -14876,6 +15689,7 @@ var VERSION = "0.64.0";
   getHexCellsInSquare,
   getHexDistance,
   gridDistanceCells,
+  isAwarenessPresence,
   isFocusPresence,
   isLaserTrailPresence,
   isMeasurePresence,