@beyondwork/docx-react-component 1.0.42 → 1.0.43

package/src/runtime/editor-state-channel.ts

@@ -0,0 +1,544 @@
+import type {
+  EditorStateBlob,
+  EditorStateLocation,
+  EditorStateNamespace,
+  EditorStatePartLoadFailure,
+  EditorStatePartPersistFailure,
+  EditorStatePersister,
+  EditorStatePolicy,
+  EditorStatePolicyEntry,
+  EditorStatePolicyMigration,
+  EditorStateResolver,
+  EditorStateResolveErrorMode,
+} from "../api/editor-state-types.ts";
+
+/**
+ * Default policy entry for a namespace not explicitly configured.
+ * Locks current behavior: in-document, block-on-resolve-failure,
+ * 250ms debounce.
+ */
+export const DEFAULT_POLICY_ENTRY: Readonly<Required<EditorStatePolicyEntry>> = {
+  location: "in-document",
+  key: "",
+  onResolveError: "block",
+  debounceMs: 250,
+} as const;
+
+export const DEFAULT_DEBOUNCE_MS = 250;
+
+/**
+ * Internal channel event surface.  Task D maps these to
+ * WordReviewEditorEvent variants.  Pure runtime emission; no
+ * dependency on the editor event union.
+ */
+export type EditorStateChannelEvent =
+  | { kind: "load_failed"; failure: EditorStatePartLoadFailure }
+  | { kind: "persist_failed"; failure: EditorStatePartPersistFailure }
+  | { kind: "policy_migrated"; migration: EditorStatePolicyMigration }
+  | { kind: "unknown_namespace"; namespace: string };
+
+export type EditorStateChannelListener = (event: EditorStateChannelEvent) => void;
+
+/**
+ * Parser-captured payload for an unknown namespace.  Stored verbatim
+ * so the serializer can re-emit the original XML fragment on save,
+ * preserving forward-compat with schemas the current build doesn't know.
+ */
+export interface UnknownNamespaceEntry {
+  rawXml?: string;
+  inline?: EditorStateBlob;
+  storageRef?: import("../api/editor-state-types.ts").EditorStateStorageRef;
+  schemaVersion?: string;
+}
+
+export interface EditorStateChannelOptions {
+  /** Injectable timer for tests.  Defaults to setTimeout/clearTimeout. */
+  scheduler?: {
+    setTimeout: (fn: () => void, ms: number) => unknown;
+    clearTimeout: (handle: unknown) => void;
+  };
+  /** UUID factory for editor-generated keys.  Defaults to crypto.randomUUID() when available. */
+  randomUuid?: () => string;
+}
+
+export interface EditorStateChannel {
+  // Policy ---------------------------------------------------------
+  setPolicy(partial: EditorStatePolicy): void;
+  getPolicyEntry(ns: EditorStateNamespace): Required<EditorStatePolicyEntry>;
+  getKey(ns: EditorStateNamespace): string | undefined;
+  /** Set the effective key for a namespace (e.g. from a loaded docx). */
+  setKey(ns: EditorStateNamespace, key: string): void;
+
+  // Callbacks ------------------------------------------------------
+  setResolver(resolver: EditorStateResolver | null): void;
+  setPersister(persister: EditorStatePersister | null): void;
+  getResolver(): EditorStateResolver | null;
+  getPersister(): EditorStatePersister | null;
+
+  // Mutation flow --------------------------------------------------
+  /**
+   * Record a subsystem mutation.  Schedules a debounced persist when
+   * the namespace is under keyed policy.  Pure state update + timer
+   * registration; the actual persister call happens on debounce-fire.
+   */
+  recordMutation(ns: EditorStateNamespace, blob: EditorStateBlob): void;
+
+  /**
+   * Flush any pending debounced persist for a namespace (or all).
+   * Returns a promise that resolves when all flushes complete or
+   * fail via the retry queue.
+   */
+  flush(ns?: EditorStateNamespace): Promise<void>;
+
+  /**
+   * Re-attempt persists sitting in the retry queue.
+   */
+  retry(ns?: EditorStateNamespace): Promise<void>;
+
+  // Load-path hooks ------------------------------------------------
+  /**
+   * Resolve a keyed namespace's blob via the registered resolver,
+   * applying onResolveError policy.  Returns the blob on success,
+   * undefined when the resolver missed or the failure mode is
+   * "empty" / "retain-last-known".
+   *
+   * Caller applies the returned blob to the subsystem store.  If the
+   * failure mode is "block", throws — caller should fail the load.
+   */
+  resolve(
+    ns: EditorStateNamespace,
+    entryKey: string,
+  ): Promise<{ blob: EditorStateBlob | null; appliedFallback: boolean }>;
+
+  /**
+   * Record a policy migration detected during load.  Caller diff'd
+   * the payload-written location vs. current policy location.  Emits
+   * policy_migrated event.
+   */
+  recordPolicyMigration(migration: EditorStatePolicyMigration): void;
+
+  /**
+   * Record an unknown-namespace finding from the parser.  Emits the
+   * warning event AND stores the raw entry so it round-trips verbatim
+   * on the next save.  `entry` carries the parser-captured rawXml.
+   */
+  recordUnknownNamespace(namespace: string, entry?: UnknownNamespaceEntry): void;
+
+  /**
+   * Return the preserved unknown-namespace entries captured during load,
+   * for the serializer to re-emit verbatim on save.
+   */
+  getUnknownEntries(): ReadonlyArray<UnknownNamespaceEntry & { name: string }>;
+
+  /**
+   * Record a load failure detected outside the resolver path (e.g.
+   * malformed inline JSON discovered by the parser).  Emits
+   * `load_failed` so hosts are notified through the same channel.
+   */
+  recordLoadFailure(failure: EditorStatePartLoadFailure): void;
+
+  /**
+   * Record a blob that was successfully loaded/applied (inline apply
+   * during hydration or post-resolve apply).  Updates `lastKnown` so
+   * the `retain-last-known` fallback has something to return on a
+   * subsequent resolver failure.  No event, no debounce.
+   */
+  recordLoaded(namespace: EditorStateNamespace, blob: EditorStateBlob): void;
+
+  // Subscription ---------------------------------------------------
+  addListener(listener: EditorStateChannelListener): () => void;
+
+  // Snapshot -------------------------------------------------------
+  /** Read-side snapshot used by the serializer. */
+  snapshot(): EditorStateChannelSnapshot;
+}
+
+export interface EditorStateChannelSnapshot {
+  policy: EditorStatePolicy;
+  keys: ReadonlyMap<EditorStateNamespace, string>;
+  /** Namespaces with a pending debounced persist. */
+  dirtyNamespaces: ReadonlySet<EditorStateNamespace>;
+  /** Retry queue size per namespace (0 when clean). */
+  retryCounts: ReadonlyMap<EditorStateNamespace, number>;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+export function createEditorStateChannel(
+  options: EditorStateChannelOptions = {},
+): EditorStateChannel {
+  const scheduler = options.scheduler ?? {
+    setTimeout: (fn, ms) => setTimeout(fn, ms),
+    clearTimeout: (h) => clearTimeout(h as ReturnType<typeof setTimeout>),
+  };
+  const randomUuid =
+    options.randomUuid ??
+    (() => {
+      if (typeof crypto !== "undefined" && crypto.randomUUID) {
+        return crypto.randomUUID();
+      }
+      // Fallback: simple UUIDv4 via Math.random — not cryptographic but ok for correlation keys.
+      return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === "x" ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+      });
+    });
+
+  const policy: EditorStatePolicy = {};
+  const keys = new Map<EditorStateNamespace, string>();
+  let resolver: EditorStateResolver | null = null;
+  let persister: EditorStatePersister | null = null;
+
+  // Debounce queue: namespace → { blob, timer }
+  interface DebounceEntry {
+    blob: EditorStateBlob;
+    timer: unknown;
+  }
+  const debounced = new Map<EditorStateNamespace, DebounceEntry>();
+
+  // Retry queue: namespace → latest blob that failed to persist + attempt count
+  interface RetryEntry {
+    blob: EditorStateBlob;
+    attemptCount: number;
+  }
+  const retries = new Map<EditorStateNamespace, RetryEntry>();
+
+  /**
+   * Last-known-good blob per namespace.  Populated on successful
+   * resolve, recordMutation, and inline apply during load.  Used to
+   * honor `retain-last-known` onResolveError: when the resolver fails
+   * we return this blob instead of falling through to empty.
+   */
+  const lastKnown = new Map<EditorStateNamespace, EditorStateBlob>();
+
+  /**
+   * Unknown-namespace entries captured at load; re-emitted verbatim on
+   * the next save so forward-compat namespaces survive round-trip.
+   */
+  const unknownEntries = new Map<string, UnknownNamespaceEntry>();
+
+  const listeners = new Set<EditorStateChannelListener>();
+
+  function emit(event: EditorStateChannelEvent): void {
+    for (const listener of listeners) {
+      try {
+        listener(event);
+      } catch {
+        // Listeners are host-supplied; they must not break the channel.
+      }
+    }
+  }
+
+  function effectiveEntry(ns: EditorStateNamespace): Required<EditorStatePolicyEntry> {
+    const configured = policy[ns];
+    if (!configured) return { ...DEFAULT_POLICY_ENTRY };
+    return {
+      location: configured.location,
+      key: configured.key ?? "",
+      onResolveError: configured.onResolveError ?? DEFAULT_POLICY_ENTRY.onResolveError,
+      debounceMs: configured.debounceMs ?? DEFAULT_DEBOUNCE_MS,
+    };
+  }
+
+  async function runPersist(
+    ns: EditorStateNamespace,
+    blob: EditorStateBlob,
+    priorAttempts: number,
+  ): Promise<void> {
+    const entry = effectiveEntry(ns);
+    if (entry.location === "in-document") {
+      // Nothing to persist externally — next serialize inlines.
+      return;
+    }
+    if (!persister) {
+      retries.set(ns, { blob, attemptCount: priorAttempts + 1 });
+      emit({
+        kind: "persist_failed",
+        failure: {
+          namespace: ns,
+          entryKey: keys.get(ns) ?? entry.key,
+          error: new Error("No persister registered"),
+          attemptCount: priorAttempts + 1,
+        },
+      });
+      return;
+    }
+    const key = keys.get(ns) ?? entry.key;
+    if (!key) {
+      retries.set(ns, { blob, attemptCount: priorAttempts + 1 });
+      emit({
+        kind: "persist_failed",
+        failure: {
+          namespace: ns,
+          entryKey: "",
+          error: new Error("No entry key assigned"),
+          attemptCount: priorAttempts + 1,
+        },
+      });
+      return;
+    }
+    try {
+      await persister(ns, key, blob);
+      retries.delete(ns);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      retries.set(ns, { blob, attemptCount: priorAttempts + 1 });
+      emit({
+        kind: "persist_failed",
+        failure: {
+          namespace: ns,
+          entryKey: key,
+          error,
+          attemptCount: priorAttempts + 1,
+        },
+      });
+    }
+  }
+
+  function cancelDebounce(ns: EditorStateNamespace): DebounceEntry | undefined {
+    const existing = debounced.get(ns);
+    if (existing) {
+      scheduler.clearTimeout(existing.timer);
+      debounced.delete(ns);
+    }
+    return existing;
+  }
+
+  function scheduleDebounce(
+    ns: EditorStateNamespace,
+    blob: EditorStateBlob,
+    debounceMs: number,
+  ): void {
+    cancelDebounce(ns);
+    const handle = scheduler.setTimeout(() => {
+      debounced.delete(ns);
+      void runPersist(ns, blob, 0);
+    }, debounceMs);
+    debounced.set(ns, { blob, timer: handle });
+  }
+
+  function validatePolicyChange(partial: EditorStatePolicy): void {
+    for (const [ns, entry] of Object.entries(partial) as Array<[
+      EditorStateNamespace,
+      EditorStatePolicyEntry,
+    ]>) {
+      if (entry.location === "rowstore" || entry.location === "key-only") {
+        if (!resolver || !persister) {
+          throw new Error(
+            `Keyed policy for "${ns}" requires both a resolver and persister to be registered first`,
+          );
+        }
+      }
+      if (entry.location === "key-only" && !entry.key) {
+        throw new Error(
+          `key-only policy for "${ns}" requires an explicit key`,
+        );
+      }
+    }
+  }
+
+  return {
+    setPolicy(partial) {
+      validatePolicyChange(partial);
+      for (const [ns, entry] of Object.entries(partial) as Array<[
+        EditorStateNamespace,
+        EditorStatePolicyEntry,
+      ]>) {
+        const previous = policy[ns];
+        // Effective prior location (defaults to in-document when the
+        // namespace has no explicit policy yet, per DEFAULT_POLICY_ENTRY).
+        const prevLocation: EditorStateLocation = previous?.location ?? "in-document";
+        policy[ns] = entry;
+        if (entry.key) {
+          keys.set(ns, entry.key);
+        } else if (!keys.has(ns) && entry.location !== "in-document") {
+          keys.set(ns, randomUuid());
+        }
+        if (prevLocation !== entry.location) {
+          // Only emit the migrated event when we actually had a prior
+          // explicit policy — first-time configuration is not a migration.
+          if (previous) {
+            emit({
+              kind: "policy_migrated",
+              migration: {
+                namespace: ns,
+                from: previous.location,
+                to: entry.location,
+                key: keys.get(ns),
+              },
+            });
+          }
+
+          // Migrate data across the location change so the next save/flush
+          // writes the in-memory state to the new destination.  The source
+          // blob is `lastKnown` (populated by recordMutation + inline apply
+          // + successful resolve) — authoritative across locations.
+          const retained = lastKnown.get(ns);
+          if (retained) {
+            if (prevLocation === "in-document" && entry.location !== "in-document") {
+              // in-document → keyed: queue for persist.
+              cancelDebounce(ns);
+              scheduleDebounce(ns, retained, entry.debounceMs ?? DEFAULT_DEBOUNCE_MS);
+            } else if (prevLocation !== "in-document" && entry.location === "in-document") {
+              // keyed → in-document: seed the inline dirty slot so the next
+              // serialize inlines the retained blob.
+              cancelDebounce(ns);
+              debounced.set(ns, { blob: retained, timer: null });
+            }
+          }
+        }
+      }
+    },
+
+    getPolicyEntry(ns) {
+      return effectiveEntry(ns);
+    },
+
+    getKey(ns) {
+      return keys.get(ns);
+    },
+
+    setKey(ns, key) {
+      keys.set(ns, key);
+    },
+
+    setResolver(next) {
+      resolver = next;
+    },
+
+    setPersister(next) {
+      persister = next;
+    },
+
+    getResolver() {
+      return resolver;
+    },
+
+    getPersister() {
+      return persister;
+    },
+
+    recordMutation(ns, blob) {
+      lastKnown.set(ns, blob);
+      const entry = effectiveEntry(ns);
+      if (entry.location === "in-document") {
+        // Mark dirty for the serializer — no external debounce needed.
+        // Use null timer to distinguish from a scheduled debounce.
+        debounced.set(ns, { blob, timer: null });
+        return;
+      }
+      scheduleDebounce(ns, blob, entry.debounceMs);
+    },
+
+    async flush(ns) {
+      const targets = ns ? [ns] : Array.from(debounced.keys());
+      for (const target of targets) {
+        const pending = cancelDebounce(target);
+        if (!pending) continue;
+        await runPersist(target, pending.blob, 0);
+      }
+    },
+
+    async retry(ns) {
+      const targets = ns ? [ns] : Array.from(retries.keys());
+      for (const target of targets) {
+        const entry = retries.get(target);
+        if (!entry) continue;
+        retries.delete(target);
+        await runPersist(target, entry.blob, entry.attemptCount);
+      }
+    },
+
+    async resolve(ns, entryKey) {
+      const entry = effectiveEntry(ns);
+      const retainBlob = (): EditorStateBlob | null => {
+        if (entry.onResolveError !== "retain-last-known") return null;
+        return lastKnown.get(ns) ?? null;
+      };
+      if (!resolver) {
+        const failure: EditorStatePartLoadFailure = {
+          namespace: ns,
+          entryKey,
+          error: new Error("No resolver registered"),
+          fallback: entry.onResolveError === "block" ? "empty" : entry.onResolveError,
+        };
+        emit({ kind: "load_failed", failure });
+        if (entry.onResolveError === "block") {
+          throw failure.error;
+        }
+        return { blob: retainBlob(), appliedFallback: true };
+      }
+      try {
+        const blob = await resolver(ns, entryKey);
+        if (blob === null) {
+          const failure: EditorStatePartLoadFailure = {
+            namespace: ns,
+            entryKey,
+            error: new Error(`Resolver returned null for ${ns}:${entryKey}`),
+            fallback: entry.onResolveError === "block" ? "empty" : entry.onResolveError,
+          };
+          emit({ kind: "load_failed", failure });
+          if (entry.onResolveError === "block") throw failure.error;
+          return { blob: retainBlob(), appliedFallback: true };
+        }
+        lastKnown.set(ns, blob);
+        return { blob, appliedFallback: false };
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        const failure: EditorStatePartLoadFailure = {
+          namespace: ns,
+          entryKey,
+          error,
+          fallback: entry.onResolveError === "block" ? "empty" : entry.onResolveError,
+        };
+        emit({ kind: "load_failed", failure });
+        if (entry.onResolveError === "block") throw error;
+        return { blob: retainBlob(), appliedFallback: true };
+      }
+    },
+
+    recordPolicyMigration(migration) {
+      emit({ kind: "policy_migrated", migration });
+    },
+
+    recordUnknownNamespace(namespace, entry) {
+      if (entry) {
+        unknownEntries.set(namespace, entry);
+      }
+      emit({ kind: "unknown_namespace", namespace });
+    },
+
+    getUnknownEntries() {
+      return Array.from(unknownEntries.entries()).map(([name, entry]) => ({ name, ...entry }));
+    },
+
+    recordLoadFailure(failure) {
+      emit({ kind: "load_failed", failure });
+    },
+
+    recordLoaded(ns, blob) {
+      lastKnown.set(ns, blob);
+    },
+
+    addListener(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+
+    snapshot() {
+      return {
+        policy: { ...policy },
+        keys: new Map(keys),
+        dirtyNamespaces: new Set(debounced.keys()),
+        retryCounts: new Map(
+          Array.from(retries.entries()).map(([ns, entry]) => [ns, entry.attemptCount]),
+        ),
+      };
+    },
+  };
+}