@beyondwork/docx-react-component 1.0.47 → 1.0.49

package/src/runtime/collab/runtime-collab-sync.ts

@@ -17,8 +17,44 @@ import {
   createCommandEvent,
   isBroadcastCommand,
   isLocalOnlyCommand,
+  COMMAND_EVENT_SCHEMA_VERSION,
   type CommandEvent,
 } from "./event-types.ts";
+import { computeBaseDocFingerprint } from "./base-doc-fingerprint.ts";
+import type { Checkpoint } from "./checkpoint-store.ts";
+import { createWorkflowShared, type WorkflowSharedHandle } from "./workflow-shared.ts";
+
+/** Shared Y.Map key — {@link SHARED_META_MAP_KEY}. */
+const SHARED_META_MAP_KEY = "meta";
+const META_BASE_DOC_HASH_KEY = "baseDocHash";
+const META_SCHEMA_VERSION_KEY = "schemaVersion";
+const META_CREATED_AT_KEY = "createdAt";
+const CHECKPOINTS_KEY = "checkpoints";
+
+/**
+ * Lifecycle + correctness events surfaced by a
+ * {@link RuntimeCollabSyncHandle} subscription. Emitted in response to
+ * attach-path checks (base-doc fingerprint) and inbound replay filtering
+ * (command-event schema version). Hosts subscribe once and react to the
+ * whole stream.
+ *
+ * - `collab_sync_attached` — fires once after a successful attach with
+ *   the computed `baseDocFingerprint`. Safe to ignore; surfaced so hosts
+ *   can log a "session started" event or cache the fingerprint for a
+ *   subsequent peer-to-peer connect.
+ * - `collab_base_doc_mismatch` — fires when the shared `meta.baseDocHash`
+ *   disagrees with the local runtime's fingerprint. The sync transitions
+ *   to read-only (inbound replay dropped, outbound broadcast suppressed)
+ *   until the host detaches and re-attaches with a matching base doc.
+ * - `collab_event_schema_mismatch` — fires when an inbound
+ *   `CommandEvent` carries a `schemaVersion` other than
+ *   {@link COMMAND_EVENT_SCHEMA_VERSION}. The event is skipped; other
+ *   events in the log continue to replay.
+ */
+export type RuntimeCollabSyncEvent =
+  | { type: "collab_sync_attached"; baseDocFingerprint: string | null }
+  | { type: "collab_base_doc_mismatch"; expected: string; actual: string }
+  | { type: "collab_event_schema_mismatch"; eventId: string; receivedSchemaVersion: unknown };
 
 const PATCHABLE_TOP_LEVEL_KEYS = [
   "updatedAt",
@@ -153,10 +189,54 @@ export interface RuntimeCollabSyncOptions {
   runtime: DocumentRuntime;
   authorId: string;
   commandAppliedBridge: RuntimeCommandAppliedBridge;
+  /**
+   * Role of the local peer for workflow-shared gating. Defaults to `"author"`
+   * for backward compatibility with pre-P13 callers — ⚠ OMITTING THIS FIELD
+   * GRANTS AUTHOR-LEVEL WRITE ACCESS to the shared `workflow` Y.Map. Hosts
+   * that derive role from Awareness or an external auth layer should pass
+   * it explicitly to avoid silently promoting reviewers/observers to authors.
+   * - `"author"`: all workflow writes allowed.
+   * - `"reviewer"`: only `setAssignedReviewers` allowed; other writes refused.
+   * - `"observer"`: all writes refused with `collab_observer_readonly`.
+   */
+  role?: "author" | "reviewer" | "observer";
 }
 
 export interface RuntimeCollabSyncHandle {
   destroy(): void;
+  /**
+   * Subscribe to lifecycle + correctness events. Returns an
+   * unsubscribe function.
+   */
+  subscribe(listener: (event: RuntimeCollabSyncEvent) => void): () => void;
+  /**
+   * Returns the base-doc fingerprint this sync either seeded (first peer
+   * to attach) or verified against (subsequent peers). `null` before the
+   * attach-path fingerprint check wires up in commit 2 of the P11
+   * ship, or when the fingerprint check has not yet run.
+   */
+  getBaseDocFingerprint(): string | null;
+  /**
+   * `true` when the sync has transitioned to read-only (either a
+   * base-doc mismatch or a future shutdown condition). Read-only syncs
+   * neither broadcast outbound commands nor replay inbound events.
+   */
+  isReadOnly(): boolean;
+  /**
+   * Current size of the internal `appliedEventIds` dedup set. Exposed
+   * for observability + tests — hosts can watch it to spot runaway
+   * growth (the checkpoint pruning path shrinks it when a new
+   * checkpoint covers previously-seen events).
+   */
+  getAppliedEventCount(): number;
+  /**
+   * Returns the shared workflow handle backing the `workflow` Y.Map.
+   * Hosts can call `.setLockedMode()`, `.setRoundDeadline()`,
+   * `.setAssignedReviewers()`, and `.setWorkItemId()` to propagate
+   * state changes to other peers. Role gating (passed in `options.role`)
+   * enforces write permissions per §7 of the lane plan.
+   */
+  getWorkflowShared(): WorkflowSharedHandle;
 }
 
 export function createRuntimeCommandAppliedBridge(): RuntimeCommandAppliedBridge {
@@ -184,7 +264,123 @@ export function createRuntimeCollabSync(
   const yEvents = ydoc.getArray<CommandEvent>("commandEvents");
   const appliedEventIds = new Set<string>();
 
+  const listeners = new Set<(event: RuntimeCollabSyncEvent) => void>();
+  let readOnly = false;
+  let baseDocFingerprint: string | null = null;
+
+  // Events emitted before any subscriber exists are buffered and flushed
+  // to the first subscriber. This lets hosts react to the attach-path
+  // base-doc mismatch and schema-version mismatch for pre-existing
+  // events — both fire synchronously during `createRuntimeCollabSync`,
+  // before the caller has had a chance to call `sync.subscribe(...)`.
+  // Buffering is one-shot: subsequent subscribers see only live events.
+  const bufferedEvents: RuntimeCollabSyncEvent[] = [];
+  let bufferFlushed = false;
+
+  function emit(event: RuntimeCollabSyncEvent): void {
+    if (!bufferFlushed && listeners.size === 0) {
+      bufferedEvents.push(event);
+      return;
+    }
+    // Snapshot to avoid re-entrant mutation during dispatch.
+    for (const listener of [...listeners]) {
+      try {
+        listener(event);
+      } catch {
+        // Listener exceptions are isolated; the sync continues.
+      }
+    }
+  }
+
+  // Compute the local base-doc fingerprint once at attach time and
+  // seed-or-verify the shared `meta` Y.Map. First peer to attach to a
+  // fresh Y.Doc seeds `{ baseDocHash, schemaVersion, createdAt }`;
+  // subsequent peers verify their own fingerprint matches and transition
+  // to read-only on divergence.
+  const yMeta = ydoc.getMap<unknown>(SHARED_META_MAP_KEY);
+  const yCheckpoints = ydoc.getArray<Checkpoint>(CHECKPOINTS_KEY);
+  baseDocFingerprint = computeBaseDocFingerprint(runtime.getSessionState().canonicalDocument);
+
+  function latestCheckpointFingerprint(): string | null {
+    if (yCheckpoints.length === 0) return null;
+    const latest = yCheckpoints.get(yCheckpoints.length - 1) as Checkpoint | undefined;
+    if (!latest || !latest.documentAtCheckpoint) return null;
+    return computeBaseDocFingerprint(latest.documentAtCheckpoint);
+  }
+
+  function checkFingerprintAgainstMeta(): void {
+    if (readOnly) return;
+    const stored = yMeta.get(META_BASE_DOC_HASH_KEY);
+    if (typeof stored !== "string") return;
+    if (baseDocFingerprint === null) return;
+    if (stored === baseDocFingerprint) return;
+    // Joiner-with-checkpoint path: if the local runtime's fingerprint
+    // matches the latest checkpoint's fingerprint, accept the attach —
+    // the joiner legitimately booted from a mid-session snapshot.
+    // `meta.baseDocHash` still reflects the original base doc, which
+    // the joiner does not (and should not) reconstruct.
+    const latestCpFingerprint = latestCheckpointFingerprint();
+    if (latestCpFingerprint !== null && latestCpFingerprint === baseDocFingerprint) {
+      return;
+    }
+    readOnly = true;
+    emit({
+      type: "collab_base_doc_mismatch",
+      expected: stored,
+      actual: baseDocFingerprint,
+    });
+  }
+
+  ydoc.transact(() => {
+    if (yMeta.size === 0) {
+      yMeta.set(META_BASE_DOC_HASH_KEY, baseDocFingerprint);
+      yMeta.set(META_SCHEMA_VERSION_KEY, COMMAND_EVENT_SCHEMA_VERSION);
+      yMeta.set(META_CREATED_AT_KEY, new Date().toISOString());
+    } else {
+      checkFingerprintAgainstMeta();
+    }
+  });
+
+  // Watch for late-arriving divergent writes — covers the race case
+  // where two peers both saw an empty `meta` and both seeded their own
+  // fingerprint, plus the case where an out-of-band peer rewrites the
+  // hash after attach. Own-writes that match our fingerprint are no-ops
+  // (stored === baseDocFingerprint short-circuits).
+  yMeta.observe(checkFingerprintAgainstMeta);
+
+  if (!readOnly) {
+    emit({ type: "collab_sync_attached", baseDocFingerprint });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Workflow shared state — P13 Slice C
+  // ---------------------------------------------------------------------------
+  // Construct a WorkflowSharedHandle over `ydoc.getMap("workflow")`. The
+  // handle subscribes to Y.Map changes and propagates them to the runtime
+  // via `setSharedWorkflowState`. Role gating is enforced by the handle
+  // itself; the `role` option defaults to `"author"` for historical compat.
+  const effectiveRole = options.role ?? "author";
+  const workflowShared = createWorkflowShared({
+    ydoc,
+    role: effectiveRole,
+    localAuthorId: authorId,
+  });
+
+  // Seed initial state synchronously. For a fresh Y.Doc this is `{}`.
+  // For a late joiner it may already be populated — the seed ensures the
+  // runtime reflects pre-existing shared state at attach time (i.e. if a
+  // peer already set `lockedMode`, the new peer starts out locked).
+  runtime.setSharedWorkflowState(workflowShared.get());
+
+  const workflowUnsub = workflowShared.subscribe((state) => {
+    if (readOnly) return; // don't propagate while in read-only (post-mismatch)
+    runtime.setSharedWorkflowState(state);
+  });
+
   const unsubscribeCommandApplied = commandAppliedBridge.subscribe((command, _transaction, context, meta) => {
+    if (readOnly) {
+      return;
+    }
     if (isLocalOnlyCommand(command)) {
       return;
     }
@@ -216,14 +412,125 @@ export function createRuntimeCollabSync(
 
   yEvents.observe(onYEventsChange);
 
+  // Checkpoint-aware startup replay: if there's a checkpoint in the
+  // shared log, seed `appliedEventIds` with every event up to and
+  // including `latestCheckpoint.afterEventId` so the startup loop
+  // skips them. The caller is expected to have created `runtime` with
+  // `initialCanonicalDocument = latestCheckpoint.documentAtCheckpoint`
+  // so the snapshot + tail replay reproduces the author's state.
+  //
+  // If the `afterEventId` is not found in the current log (e.g. an
+  // out-of-order merge or a corrupt checkpoint), no events are
+  // seeded — the startup loop falls back to full replay, which is
+  // wasteful but safe thanks to the existing dedup.
+  if (yCheckpoints.length > 0) {
+    const latestCheckpoint = yCheckpoints.get(yCheckpoints.length - 1);
+    const targetAfterEventId = latestCheckpoint?.afterEventId;
+    if (typeof targetAfterEventId === "string") {
+      const events = yEvents.toArray();
+      let found = false;
+      for (const value of events) {
+        const eventId = (value as { eventId?: unknown })?.eventId;
+        if (typeof eventId !== "string") continue;
+        appliedEventIds.add(eventId);
+        if (eventId === targetAfterEventId) {
+          found = true;
+          break;
+        }
+      }
+      if (!found) {
+        // Fallback: clear the seeded ids so startup replay can proceed
+        // across the full log. Safe because the runtime was created
+        // from some canonical base (either a matching snapshot or the
+        // original doc) and the commit path is idempotent via
+        // `appliedEventIds` dedup for the live channel anyway.
+        appliedEventIds.clear();
+      }
+    }
+  }
+
   for (const value of yEvents.toArray()) {
     applyStartupEvent(value);
   }
 
+  // When a new checkpoint lands, prune `appliedEventIds` of every
+  // event up to and including the checkpoint's `afterEventId`. Those
+  // ids are now permanently captured in the snapshot, so the dedup
+  // set no longer needs them — Yjs doesn't re-deliver events to
+  // existing observers, so pruning is safe. Stale checkpoints whose
+  // `afterEventId` is not found in the current log leave the set
+  // intact.
+  function pruneAppliedEventIdsForCheckpoint(cursorEventId: string): void {
+    const events = yEvents.toArray();
+    const idsCovered = new Set<string>();
+    let foundCursor = false;
+    for (const value of events) {
+      const evt = value as { eventId?: unknown } | undefined;
+      const eventId = evt?.eventId;
+      if (typeof eventId !== "string") continue;
+      idsCovered.add(eventId);
+      if (eventId === cursorEventId) {
+        foundCursor = true;
+        break;
+      }
+    }
+    if (!foundCursor) return;
+    for (const id of idsCovered) {
+      appliedEventIds.delete(id);
+    }
+  }
+
+  function onCheckpointsChange(event: Y.YArrayEvent<Checkpoint>): void {
+    for (const delta of event.changes.delta) {
+      if (!Array.isArray(delta.insert)) continue;
+      for (const value of delta.insert) {
+        const cursor = (value as { afterEventId?: unknown } | undefined)?.afterEventId;
+        if (typeof cursor !== "string") continue;
+        pruneAppliedEventIdsForCheckpoint(cursor);
+      }
+    }
+  }
+  yCheckpoints.observe(onCheckpointsChange);
+
   return {
     destroy() {
       unsubscribeCommandApplied();
       yEvents.unobserve(onYEventsChange);
+      yMeta.unobserve(checkFingerprintAgainstMeta);
+      yCheckpoints.unobserve(onCheckpointsChange);
+      workflowUnsub();
+      workflowShared.destroy();
+      runtime.setSharedWorkflowState(null);
+      listeners.clear();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      if (!bufferFlushed) {
+        bufferFlushed = true;
+        const pending = bufferedEvents.splice(0);
+        for (const event of pending) {
+          try {
+            listener(event);
+          } catch {
+            // Listener exceptions are isolated.
+          }
+        }
+      }
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getBaseDocFingerprint() {
+      return baseDocFingerprint;
+    },
+    isReadOnly() {
+      return readOnly;
+    },
+    getAppliedEventCount() {
+      return appliedEventIds.size;
+    },
+    getWorkflowShared() {
+      return workflowShared;
     },
   };
 
@@ -240,6 +547,9 @@ export function createRuntimeCollabSync(
   }
 
   function applyStartupEvent(value: unknown): void {
+    if (readOnly) {
+      return;
+    }
     const event = asCommandEvent(value);
     if (!event) {
       return;
@@ -257,6 +567,9 @@ export function createRuntimeCollabSync(
   }
 
   function applyObservedEvent(value: unknown): void {
+    if (readOnly) {
+      return;
+    }
     const event = asCommandEvent(value);
     if (!event) {
       return;
@@ -277,6 +590,14 @@ export function createRuntimeCollabSync(
   }
 
   function isReplayableEvent(event: CommandEvent): boolean {
+    if ((event.schemaVersion as number) !== COMMAND_EVENT_SCHEMA_VERSION) {
+      emit({
+        type: "collab_event_schema_mismatch",
+        eventId: event.eventId,
+        receivedSchemaVersion: event.schemaVersion,
+      });
+      return false;
+    }
     if (isLocalOnlyCommand(event.command)) {
       return false;
     }
@@ -326,8 +647,17 @@ function asCommandEvent(value: unknown): CommandEvent | null {
     return null;
   }
 
+  // Preserve the received `schemaVersion` verbatim when present so
+  // `isReplayableEvent` can report the offending value on mismatch.
+  // Missing fields decode to `COMMAND_EVENT_SCHEMA_VERSION` — legacy
+  // peers that pre-date the field continue to replay cleanly.
+  const schemaVersion = typeof value.schemaVersion === "number"
+    ? value.schemaVersion
+    : COMMAND_EVENT_SCHEMA_VERSION;
+
   return {
     eventId: value.eventId,
+    schemaVersion: schemaVersion as CommandEvent["schemaVersion"],
     originClientId: value.originClientId,
     authorId: value.authorId,
     timestamp,

package/src/runtime/collab/workflow-shared.ts

@@ -0,0 +1,247 @@
+import * as Y from "yjs";
+
+import type { CollabBlockReason } from "../../api/comment-negotiation-types.ts";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface SharedWorkflowState {
+  lockedMode?: "editing" | "suggesting" | "commenting" | "viewing";
+  roundDeadline?: string; // ISO-8601
+  assignedReviewers?: string[]; // userIds
+  workItemId?: string;
+}
+
+export interface CreateWorkflowSharedOptions {
+  ydoc: Y.Doc;
+  role: "author" | "reviewer" | "observer";
+  /**
+   * Reserved for future audit use — emit `{ actor: localAuthorId }` on
+   * writes once the audit path lands. Currently unused at runtime;
+   * optional so callers without an author-id scheme don't have to
+   * fabricate one.
+   */
+  localAuthorId?: string;
+}
+
+export type WorkflowSharedResult =
+  | { ok: true }
+  | { ok: false; reason: CollabBlockReason };
+
+export interface WorkflowSharedHandle {
+  get(): SharedWorkflowState;
+  setLockedMode(mode: SharedWorkflowState["lockedMode"]): WorkflowSharedResult;
+  setRoundDeadline(deadline: string | undefined): WorkflowSharedResult;
+  setAssignedReviewers(reviewers: string[]): WorkflowSharedResult;
+  setWorkItemId(id: string | undefined): WorkflowSharedResult;
+  subscribe(listener: (state: SharedWorkflowState) => void): () => void;
+  destroy(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Y.Map key constants
+// ---------------------------------------------------------------------------
+
+const WORKFLOW_MAP_NAME = "workflow";
+const KEY_LOCKED_MODE = "lockedMode";
+const KEY_ROUND_DEADLINE = "roundDeadline";
+const KEY_ASSIGNED_REVIEWERS = "assignedReviewers";
+const KEY_WORK_ITEM_ID = "workItemId";
+
+// ---------------------------------------------------------------------------
+// Shallow-equality helpers
+// ---------------------------------------------------------------------------
+
+function arrayShallowEqual(
+  a: string[] | undefined,
+  b: string[] | undefined,
+): boolean {
+  if (a === b) return true;
+  if (a == null || b == null) return false;
+  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 stateShallowEqual(
+  a: SharedWorkflowState,
+  b: SharedWorkflowState,
+): boolean {
+  return (
+    a.lockedMode === b.lockedMode &&
+    a.roundDeadline === b.roundDeadline &&
+    a.workItemId === b.workItemId &&
+    arrayShallowEqual(a.assignedReviewers, b.assignedReviewers)
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a handle over `ydoc.getMap<unknown>("workflow")` that propagates
+ * shared workflow state — `lockedMode`, `roundDeadline`, `assignedReviewers`,
+ * and `workItemId` — across collab peers via per-key Yjs LWW conflict
+ * resolution.
+ *
+ * Role-gating (§7 lane plan):
+ * - observer: all writes refused with `collab_observer_readonly`.
+ * - reviewer: only `setAssignedReviewers` allowed; other writes refused with
+ *   `collab_role_restricted`.
+ * - author: all writes allowed.
+ */
+export function createWorkflowShared(
+  options: CreateWorkflowSharedOptions,
+): WorkflowSharedHandle {
+  const { ydoc, role } = options;
+  // Reserved for future audit path — see CreateWorkflowSharedOptions.localAuthorId.
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const _localAuthorId = options.localAuthorId;
+
+  const yMap = ydoc.getMap<unknown>(WORKFLOW_MAP_NAME);
+
+  const listeners = new Set<(state: SharedWorkflowState) => void>();
+  let destroyed = false;
+  let lastEmitted: SharedWorkflowState | null = null;
+
+  // -------------------------------------------------------------------------
+  // Read helper
+  // -------------------------------------------------------------------------
+
+  function readState(): SharedWorkflowState {
+    const state: SharedWorkflowState = {};
+    const lockedMode = yMap.get(KEY_LOCKED_MODE);
+    if (lockedMode !== undefined) {
+      state.lockedMode = lockedMode as SharedWorkflowState["lockedMode"];
+    }
+    const roundDeadline = yMap.get(KEY_ROUND_DEADLINE);
+    if (roundDeadline !== undefined) {
+      state.roundDeadline = roundDeadline as string;
+    }
+    const assignedReviewers = yMap.get(KEY_ASSIGNED_REVIEWERS);
+    if (assignedReviewers !== undefined) {
+      state.assignedReviewers = [...(assignedReviewers as string[])];
+    }
+    const workItemId = yMap.get(KEY_WORK_ITEM_ID);
+    if (workItemId !== undefined) {
+      state.workItemId = workItemId as string;
+    }
+    return state;
+  }
+
+  // -------------------------------------------------------------------------
+  // Observer — dedup-fires listeners on any Y.Map change
+  // -------------------------------------------------------------------------
+
+  function onMapChange(): void {
+    if (destroyed) return;
+    if (listeners.size === 0) {
+      lastEmitted = null;
+      return;
+    }
+    const next = readState();
+    if (lastEmitted !== null && stateShallowEqual(lastEmitted, next)) {
+      return; // deduplicated — same state, skip fire
+    }
+    lastEmitted = next;
+    for (const listener of [...listeners]) {
+      try {
+        listener(next);
+      } catch {
+        // Listener exceptions are isolated; the handle continues.
+      }
+    }
+  }
+
+  yMap.observe(onMapChange);
+
+  // -------------------------------------------------------------------------
+  // Role-gating helpers
+  // -------------------------------------------------------------------------
+
+  function checkObserver(): WorkflowSharedResult | null {
+    if (role === "observer") {
+      return { ok: false, reason: "collab_observer_readonly" };
+    }
+    return null;
+  }
+
+  function checkReviewerRestricted(): WorkflowSharedResult | null {
+    if (role === "reviewer") {
+      return { ok: false, reason: "collab_role_restricted" };
+    }
+    return null;
+  }
+
+  // -------------------------------------------------------------------------
+  // Handle
+  // -------------------------------------------------------------------------
+
+  return {
+    get(): SharedWorkflowState {
+      return readState();
+    },
+
+    setLockedMode(mode): WorkflowSharedResult {
+      const denied = checkObserver() ?? checkReviewerRestricted();
+      if (denied) return denied;
+      if (mode === undefined) {
+        yMap.delete(KEY_LOCKED_MODE);
+      } else {
+        yMap.set(KEY_LOCKED_MODE, mode);
+      }
+      return { ok: true };
+    },
+
+    setRoundDeadline(deadline): WorkflowSharedResult {
+      const denied = checkObserver() ?? checkReviewerRestricted();
+      if (denied) return denied;
+      if (deadline === undefined) {
+        yMap.delete(KEY_ROUND_DEADLINE);
+      } else {
+        yMap.set(KEY_ROUND_DEADLINE, deadline);
+      }
+      return { ok: true };
+    },
+
+    setAssignedReviewers(reviewers): WorkflowSharedResult {
+      const denied = checkObserver();
+      if (denied) return denied;
+      // reviewer is allowed here — do NOT call checkReviewerRestricted().
+      yMap.set(KEY_ASSIGNED_REVIEWERS, [...reviewers]);
+      return { ok: true };
+    },
+
+    setWorkItemId(id): WorkflowSharedResult {
+      const denied = checkObserver() ?? checkReviewerRestricted();
+      if (denied) return denied;
+      if (id === undefined) {
+        yMap.delete(KEY_WORK_ITEM_ID);
+      } else {
+        yMap.set(KEY_WORK_ITEM_ID, id);
+      }
+      return { ok: true };
+    },
+
+    subscribe(listener): () => void {
+      listeners.add(listener);
+      // Reset dedup baseline so the next change always fires fresh.
+      lastEmitted = null;
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+
+    destroy(): void {
+      if (destroyed) return;
+      destroyed = true;
+      yMap.unobserve(onMapChange);
+      listeners.clear();
+      lastEmitted = null;
+    },
+  };
+}

package/src/runtime/document-locations.ts

@@ -18,6 +18,7 @@ import type {
 } from "../api/public-types";
 import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
 import { MAIN_STORY_TARGET } from "../core/selection/mapping.ts";
+import { createPublicRangeAnchor } from "../core/selection/anchor-conversion.ts";
 import {
   createDocumentSectionSnapshots,
   findBookmarkNameForOffset,
@@ -47,15 +48,6 @@ function createLocationId(anchor: EditorAnchorProjection, storyTarget?: EditorSt
   }
 }
 
-function createPublicRangeAnchor(from: number, to: number): EditorAnchorProjection {
-  return {
-    kind: "range",
-    from,
-    to,
-    assoc: { start: -1, end: 1 },
-  };
-}
-
 function resolveOffsetMetadata(
   navigation: DocumentNavigationSnapshot,
   offset: number,

package/src/runtime/document-outline.ts

@@ -18,6 +18,7 @@ import type {
 import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
 import { createSelectionSnapshot } from "../core/state/editor-state.ts";
 import { MAIN_STORY_TARGET } from "../core/selection/mapping.ts";
+import { createPublicRangeAnchor } from "../core/selection/anchor-conversion.ts";
 import { parseTocLevelRange } from "../io/ooxml/parse-fields.ts";
 import { buildPageLayoutSnapshot, buildResolvedSections } from "./document-layout.ts";
 import { createDocumentNavigationSnapshot } from "./document-navigation.ts";
@@ -34,15 +35,6 @@ function getAnchorOffset(anchor: EditorAnchorProjection): number | undefined {
   }
 }
 
-function createPublicRangeAnchor(from: number, to: number): EditorAnchorProjection {
-  return {
-    kind: "range",
-    from,
-    to,
-    assoc: { start: -1, end: 1 },
-  };
-}
-
 export function resolveHeadingPath(
   headings: readonly DocumentHeadingSnapshot[],
   offset: number | undefined,