@beyondwork/docx-react-component 1.0.42 → 1.0.45

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

@@ -0,0 +1,217 @@
+/**
+ * editor-state-integration.ts — Schema 1.2 Task D + E helpers.
+ *
+ * Factored out of document-runtime.ts / docx-session.ts to keep
+ * those files focused.  Two entry points:
+ *
+ * - `hydrateEditorStateFromEnvelope`: called right after the runtime
+ *   is created and the envelope parsed; drives the load-path.
+ * - `collectEditorStateForSerialize`: called inside exportDocx before
+ *   `buildWorkflowPayloadParts`; drives the save-path.
+ */
+
+import type { EditorStateNamespace } from "../api/editor-state-types.ts";
+import type { EditorStateChannel } from "./editor-state-channel.ts";
+import type {
+  EditorStatePayload,
+  EditorStatePayloadNamespaceEntry,
+} from "../io/ooxml/workflow-payload.ts";
+
+// All namespaces the runtime currently knows about.
+export const ALL_EDITOR_STATE_NAMESPACES: readonly EditorStateNamespace[] = [
+  "hostAnnotations",
+  "workflowOverlay",
+  "workflowMetadata",
+  "workItems",
+] as const;
+
+// ---------------------------------------------------------------------------
+// Load-path: hydrateEditorStateFromEnvelope
+// ---------------------------------------------------------------------------
+
+export interface HydrateEditorStateArgs {
+  /** The editorState block parsed from the workflow-payload envelope. */
+  editorState: EditorStatePayload;
+  channel: EditorStateChannel;
+  /**
+   * Called for each namespace whose blob has been resolved/loaded.
+   * Responsible for applying the blob to the appropriate subsystem store
+   * (e.g. calling runtime.setHostAnnotationOverlay).
+   */
+  applyBlob: (namespace: EditorStateNamespace, data: unknown) => void;
+}
+
+/**
+ * Drives the load-path for schema 1.2 editor-state entries.
+ *
+ * - Unknown namespaces → preserved opaquely, `unknown_namespace` event.
+ * - Inline entries under in-document policy → applied directly.
+ * - Keyed entries → resolver called; result applied (or failure handled).
+ * - Policy mismatch → `policy_migrated` event.
+ *
+ * Returns a promise that resolves when all namespaces have been
+ * processed.  Rejects only when `onResolveError` is `"block"` for a
+ * namespace and the resolver fails — the caller should fail the load.
+ */
+export async function hydrateEditorStateFromEnvelope(
+  args: HydrateEditorStateArgs,
+): Promise<void> {
+  const { editorState, channel, applyBlob } = args;
+
+  // Record unknown namespaces first — they are preserved opaquely by
+  // the payload layer; we emit the warning event AND hand the raw XML
+  // to the channel so the next save round-trips it verbatim.
+  for (const unknown of editorState.unknownNamespaces ?? []) {
+    channel.recordUnknownNamespace(unknown.name, { rawXml: unknown.rawXml });
+  }
+
+  for (const entry of editorState.entries) {
+    await hydrateEntry({ entry, channel, applyBlob });
+  }
+}
+
+async function hydrateEntry(args: {
+  entry: EditorStatePayloadNamespaceEntry;
+  channel: EditorStateChannel;
+  applyBlob: (namespace: EditorStateNamespace, data: unknown) => void;
+}): Promise<void> {
+  const { entry, channel, applyBlob } = args;
+  const ns = entry.namespace;
+  const policyEntry = channel.getPolicyEntry(ns);
+
+  // Malformed inline JSON: surface as a load failure; don't apply.
+  if (entry.malformedInline) {
+    channel.recordLoadFailure({
+      namespace: ns,
+      error: new Error(`Malformed inline JSON for namespace "${ns}"`),
+      fallback: policyEntry.onResolveError === "block" ? "empty" : policyEntry.onResolveError,
+    });
+    return;
+  }
+
+  // Policy-migration detection: compare payload-written location vs
+  // current policy location.
+  const payloadLocation: string = entry.storageRef
+    ? entry.storageRef.location
+    : "in-document";
+  if (payloadLocation !== policyEntry.location) {
+    channel.recordPolicyMigration({
+      namespace: ns,
+      from: payloadLocation as import("../api/editor-state-types.ts").EditorStateLocation,
+      to: policyEntry.location,
+      key: entry.storageRef?.entryKey,
+    });
+  }
+
+  // Inline path: apply directly when both payload and policy agree on
+  // in-document.
+  if (entry.inline !== undefined && policyEntry.location === "in-document") {
+    applyBlob(ns, entry.inline);
+    channel.recordLoaded(ns, {
+      namespace: ns,
+      schemaVersion: entry.schemaVersion,
+      data: entry.inline,
+    });
+    return;
+  }
+
+  // Keyed path: set the key from the payload, then call the resolver.
+  if (entry.storageRef) {
+    channel.setKey(ns, entry.storageRef.entryKey);
+    // Under keyed policy the resolver wins over any inline blob.
+    const result = await channel.resolve(ns, entry.storageRef.entryKey);
+    if (result.blob !== null) {
+      applyBlob(ns, result.blob.data);
+      if (!result.appliedFallback) {
+        channel.recordLoaded(ns, result.blob);
+      }
+    }
+    // result.blob === null → failure already handled by channel (event
+    // emitted, fallback mode applied).  Nothing more to apply.
+    return;
+  }
+
+  // Mismatch: payload is inline but policy is keyed.  Apply inline as
+  // fallback (no key to resolve against).
+  if (entry.inline !== undefined) {
+    applyBlob(ns, entry.inline);
+    channel.recordLoaded(ns, {
+      namespace: ns,
+      schemaVersion: entry.schemaVersion,
+      data: entry.inline,
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Save-path: collectEditorStateForSerialize
+// ---------------------------------------------------------------------------
+
+export interface CollectEditorStateArgs {
+  channel: EditorStateChannel;
+  /**
+   * Returns the current in-memory blob for a namespace, or null if
+   * the namespace has no data to persist.
+   */
+  getNamespaceData: (ns: EditorStateNamespace) => { schemaVersion: string; data: unknown } | null;
+}
+
+/**
+ * Builds the `EditorStatePayload` for the serializer.
+ *
+ * 1. Flushes any pending debounced persists so the docx captures
+ *    the last-known-good state for rowstore namespaces.
+ * 2. For each namespace with data: emits inline or storageRef per policy.
+ * 3. Returns undefined when no namespaces have data — the serializer
+ *    then omits `<bw:editorState>` entirely (downgrade to 1.1/1.0).
+ */
+export async function collectEditorStateForSerialize(
+  args: CollectEditorStateArgs,
+): Promise<EditorStatePayload | undefined> {
+  const { channel, getNamespaceData } = args;
+
+  // Flush pending debounced persists before serialize resolves.
+  await channel.flush();
+
+  const entries: EditorStatePayloadNamespaceEntry[] = [];
+
+  for (const ns of ALL_EDITOR_STATE_NAMESPACES) {
+    const current = getNamespaceData(ns);
+    if (!current) continue;
+
+    const policyEntry = channel.getPolicyEntry(ns);
+
+    if (policyEntry.location === "in-document") {
+      entries.push({
+        namespace: ns,
+        schemaVersion: current.schemaVersion,
+        inline: current.data,
+      });
+    } else {
+      const key = channel.getKey(ns);
+      if (!key) continue; // Keyed policy without a key — can't serialize ref.
+      entries.push({
+        namespace: ns,
+        schemaVersion: current.schemaVersion,
+        storageRef: {
+          location: policyEntry.location as Exclude<
+            import("../api/editor-state-types.ts").EditorStateLocation,
+            "in-document"
+          >,
+          entryKey: key,
+        },
+      });
+    }
+  }
+
+  const unknownEntries = channel.getUnknownEntries();
+  const unknownNamespaces = unknownEntries
+    .filter((u): u is typeof u & { rawXml: string } => typeof u.rawXml === "string")
+    .map((u) => ({ name: u.name, rawXml: u.rawXml }));
+
+  if (entries.length === 0 && unknownNamespaces.length === 0) return undefined;
+  return {
+    entries,
+    ...(unknownNamespaces.length > 0 ? { unknownNamespaces } : {}),
+  };
+}

package/src/runtime/editor-surface/capabilities.ts

@@ -0,0 +1,411 @@
+/**
+ * Editor capability table — the single source of truth for every
+ * keyboard shortcut, context-menu action, and surface dispatch the
+ * mounted editor knows about.
+ *
+ * An `EditorCapability` classifies a binding into one of four kinds:
+ *   - `supported`      — the editor owns the mutation (runtime command
+ *                        or shell op).
+ *   - `host-delegated` — the editor recognizes the input but hands it
+ *                        off to the host via a typed callback prop.
+ *                        Host event name lives in `hostEvent`.
+ *   - `blocked`        — the editor explicitly rejects the input. The
+ *                        host sees a `command_blocked` event with the
+ *                        `blockReason.code` and `blockReason.message`.
+ *   - `passthrough`    — the editor does not intercept; the browser
+ *                        default behavior wins.
+ *
+ * This table is consumed by:
+ *   - `src/ui/runtime-shortcut-dispatch.ts` (I3 C.2) — each resolution
+ *     branch looks up by id rather than hard-coding block reasons.
+ *   - `docs/reference/editor-capabilities.md` (I3 C.4) — generated
+ *     from this table so the wiki + reference doc stay in sync.
+ *   - `src/ui/WordReviewEditor.tsx` (I3 C.3) — `host-delegated`
+ *     entries wire their `hostEvent` to the matching prop on
+ *     `WordReviewEditorProps`.
+ *
+ * C.1 (this file): enumerate every shortcut already present in
+ * `resolveShellShortcut` / `resolveSurfaceShortcut` / the PM
+ * Alt+Shift+arrow bindings. No behavior change — C.2 is the
+ * dispatcher refactor.
+ *
+ * Scope: keyboard shortcuts only in C.1. Context-menu capabilities
+ * land alongside the right-click hook (Phase F) in a later commit.
+ */
+
+export type CapabilityKind = "supported" | "host-delegated" | "blocked" | "passthrough";
+
+export type CapabilityCategory =
+  | "text-formatting"
+  | "paragraph-formatting"
+  | "navigation"
+  | "selection"
+  | "clipboard"
+  | "history"
+  | "tracked-changes"
+  | "comments"
+  | "structure"
+  | "system";
+
+export interface CapabilityShortcut {
+  /** Canonical Windows / Linux binding string (e.g. "Ctrl+B", "Shift+Tab"). */
+  winLinux: string;
+  /** Canonical Mac binding string (e.g. "Cmd+B", "Shift+Tab"). */
+  mac: string;
+}
+
+export interface CapabilityBlockReason {
+  code: string;
+  message: string;
+}
+
+export interface EditorCapability {
+  /** Stable symbolic identifier. Used for lookup + wire-format. */
+  id: string;
+  kind: CapabilityKind;
+  category: CapabilityCategory;
+  /** Human-readable description for docs + a11y help. */
+  label: string;
+  /** Present when the capability is keyboard-triggered. */
+  shortcut?: CapabilityShortcut;
+  /** For `host-delegated`: the `WordReviewEditorProps` callback name. */
+  hostEvent?: string;
+  /** For `blocked`: the reason returned in the `command_blocked` event. */
+  blockReason?: CapabilityBlockReason;
+}
+
+const UNSUPPORTED_SURFACE = "unsupported_surface";
+
+export const EDITOR_CAPABILITIES: readonly EditorCapability[] = [
+  // ---------------------------------------------------------------
+  // System — shell-level UX affordances
+  // ---------------------------------------------------------------
+  {
+    id: "shell.focus-region",
+    kind: "supported",
+    category: "system",
+    label: "Cycle focus between editor regions",
+    shortcut: { winLinux: "F6", mac: "F6" },
+  },
+  {
+    id: "shell.dismiss-selection-toolbar",
+    kind: "supported",
+    category: "system",
+    label: "Dismiss the selection toolbar",
+    shortcut: { winLinux: "Escape", mac: "Escape" },
+  },
+
+  // ---------------------------------------------------------------
+  // History
+  // ---------------------------------------------------------------
+  {
+    id: "history.undo",
+    kind: "supported",
+    category: "history",
+    label: "Undo",
+    shortcut: { winLinux: "Ctrl+Z", mac: "Cmd+Z" },
+  },
+  {
+    id: "history.redo",
+    kind: "supported",
+    category: "history",
+    label: "Redo",
+    shortcut: { winLinux: "Ctrl+Y", mac: "Cmd+Shift+Z" },
+  },
+
+  // ---------------------------------------------------------------
+  // Text formatting — shell-dispatched marks
+  // ---------------------------------------------------------------
+  {
+    id: "mark.toggle-bold",
+    kind: "supported",
+    category: "text-formatting",
+    label: "Toggle bold",
+    shortcut: { winLinux: "Ctrl+B", mac: "Cmd+B" },
+  },
+  {
+    id: "mark.toggle-italic",
+    kind: "supported",
+    category: "text-formatting",
+    label: "Toggle italic",
+    shortcut: { winLinux: "Ctrl+I", mac: "Cmd+I" },
+  },
+  {
+    id: "mark.toggle-underline",
+    kind: "supported",
+    category: "text-formatting",
+    label: "Toggle underline",
+    shortcut: { winLinux: "Ctrl+U", mac: "Cmd+U" },
+  },
+
+  // ---------------------------------------------------------------
+  // Comments
+  // ---------------------------------------------------------------
+  {
+    id: "comment.add",
+    kind: "supported",
+    category: "comments",
+    label: "Insert comment at selection",
+    shortcut: { winLinux: "Ctrl+Alt+M", mac: "Cmd+Option+A" },
+  },
+
+  // ---------------------------------------------------------------
+  // Paragraph-formatting — heading levels
+  // ---------------------------------------------------------------
+  {
+    id: "heading.set-level-1",
+    kind: "supported",
+    category: "paragraph-formatting",
+    label: "Apply Heading 1 style",
+    shortcut: { winLinux: "Ctrl+Alt+1", mac: "Cmd+Option+1" },
+  },
+  {
+    id: "heading.set-level-2",
+    kind: "supported",
+    category: "paragraph-formatting",
+    label: "Apply Heading 2 style",
+    shortcut: { winLinux: "Ctrl+Alt+2", mac: "Cmd+Option+2" },
+  },
+  {
+    id: "heading.set-level-3",
+    kind: "supported",
+    category: "paragraph-formatting",
+    label: "Apply Heading 3 style",
+    shortcut: { winLinux: "Ctrl+Alt+3", mac: "Cmd+Option+3" },
+  },
+
+  // ---------------------------------------------------------------
+  // Surface-dispatched text commands (PM-focus path)
+  // ---------------------------------------------------------------
+  {
+    id: "text.delete-backward",
+    kind: "supported",
+    category: "text-formatting",
+    label: "Delete character before the cursor",
+    shortcut: { winLinux: "Backspace", mac: "Backspace" },
+  },
+  {
+    id: "text.delete-forward",
+    kind: "supported",
+    category: "text-formatting",
+    label: "Delete character after the cursor",
+    shortcut: { winLinux: "Delete", mac: "Delete" },
+  },
+  {
+    id: "paragraph.split",
+    kind: "supported",
+    category: "structure",
+    label: "Split paragraph at cursor",
+    shortcut: { winLinux: "Enter", mac: "Enter" },
+  },
+  {
+    id: "text.insert-hard-break",
+    kind: "supported",
+    category: "structure",
+    label: "Insert hard line break",
+    shortcut: { winLinux: "Shift+Enter", mac: "Shift+Enter" },
+  },
+  {
+    id: "text.insert-tab",
+    kind: "supported",
+    category: "paragraph-formatting",
+    label: "Indent list item; in table, move to next cell; otherwise insert tab",
+    shortcut: { winLinux: "Tab", mac: "Tab" },
+  },
+  {
+    id: "text.outdent-tab",
+    kind: "supported",
+    category: "paragraph-formatting",
+    label: "Outdent list item or paragraph; in table, move to previous cell",
+    shortcut: { winLinux: "Shift+Tab", mac: "Shift+Tab" },
+  },
+  {
+    id: "list.indent",
+    kind: "supported",
+    category: "paragraph-formatting",
+    label: "Indent current list item (Word Alt+Shift binding)",
+    shortcut: { winLinux: "Alt+Shift+Right", mac: "Option+Shift+Right" },
+  },
+  {
+    id: "list.outdent",
+    kind: "supported",
+    category: "paragraph-formatting",
+    label: "Outdent current list item (Word Alt+Shift binding)",
+    shortcut: { winLinux: "Alt+Shift+Left", mac: "Option+Shift+Left" },
+  },
+  {
+    id: "table.navigate-cell",
+    kind: "supported",
+    category: "navigation",
+    label: "Move to next / previous table cell (Tab / Shift+Tab while inside a table)",
+    shortcut: { winLinux: "Tab", mac: "Tab" },
+  },
+
+  // ---------------------------------------------------------------
+  // Clipboard — force-plain-text shortcut
+  //
+  // Ctrl/Cmd+Shift+V resolves to `{kind: "none"}` at the shell layer
+  // and falls through to the browser's native paste flow, which PM's
+  // handlePaste routes through the same plain-text path as Ctrl/Cmd+V.
+  // Classified as `passthrough` here: we recognize the shortcut but
+  // don't intercept — the browser + PM surface handle it.
+  // ---------------------------------------------------------------
+  {
+    id: "clipboard.paste-plain-text",
+    kind: "passthrough",
+    category: "clipboard",
+    label: "Paste as plain text (today identical to Ctrl/Cmd+V — force-plain-text semantics land with Tier B rich paste)",
+    shortcut: { winLinux: "Ctrl+Shift+V", mac: "Cmd+Shift+V" },
+  },
+
+  // ---------------------------------------------------------------
+  // Host-delegated — browser-owned gestures
+  // ---------------------------------------------------------------
+  {
+    id: "shortcut.find",
+    kind: "host-delegated",
+    category: "navigation",
+    label: "Find in document",
+    shortcut: { winLinux: "Ctrl+F", mac: "Cmd+F" },
+    hostEvent: "onFindRequested",
+  },
+  {
+    id: "shortcut.print",
+    kind: "host-delegated",
+    category: "system",
+    label: "Print document",
+    shortcut: { winLinux: "Ctrl+P", mac: "Cmd+P" },
+    hostEvent: "onPrintRequested",
+  },
+  {
+    id: "shortcut.zoom-in",
+    kind: "host-delegated",
+    category: "system",
+    label: "Zoom in",
+    shortcut: { winLinux: "Ctrl+Plus", mac: "Cmd+Plus" },
+    hostEvent: "onZoomRequested",
+  },
+  {
+    id: "shortcut.zoom-out",
+    kind: "host-delegated",
+    category: "system",
+    label: "Zoom out",
+    shortcut: { winLinux: "Ctrl+Minus", mac: "Cmd+Minus" },
+    hostEvent: "onZoomRequested",
+  },
+  {
+    id: "shortcut.zoom-reset",
+    kind: "host-delegated",
+    category: "system",
+    label: "Reset zoom",
+    shortcut: { winLinux: "Ctrl+0", mac: "Cmd+0" },
+    hostEvent: "onZoomRequested",
+  },
+
+  // ---------------------------------------------------------------
+  // Blocked — Word shortcuts the mounted editor does not implement
+  // ---------------------------------------------------------------
+  {
+    id: "replaceText",
+    kind: "blocked",
+    category: "navigation",
+    label: "Find and replace",
+    shortcut: { winLinux: "Ctrl+H", mac: "Ctrl+H" },
+    blockReason: {
+      code: UNSUPPORTED_SURFACE,
+      message: "Replace shortcuts are not supported in the mounted editor yet.",
+    },
+  },
+  {
+    id: "goTo",
+    kind: "blocked",
+    category: "navigation",
+    label: "Go to",
+    shortcut: { winLinux: "Ctrl+G", mac: "Cmd+Option+G" },
+    blockReason: {
+      code: UNSUPPORTED_SURFACE,
+      message: "Go To shortcuts are not supported in the mounted editor yet.",
+    },
+  },
+  {
+    id: "toggleTrackChanges",
+    kind: "blocked",
+    category: "tracked-changes",
+    label: "Toggle track-changes authoring mode",
+    shortcut: { winLinux: "Ctrl+Shift+E", mac: "Cmd+Shift+E" },
+    blockReason: {
+      code: UNSUPPORTED_SURFACE,
+      message: "Track changes authoring shortcuts are not supported in the mounted editor.",
+    },
+  },
+  {
+    id: "checkSpelling",
+    kind: "blocked",
+    category: "system",
+    label: "Check spelling",
+    shortcut: { winLinux: "F7", mac: "F7" },
+    blockReason: {
+      code: UNSUPPORTED_SURFACE,
+      message: "Spelling shortcuts are not supported in the mounted editor.",
+    },
+  },
+  {
+    id: "openThesaurus",
+    kind: "blocked",
+    category: "system",
+    label: "Open thesaurus",
+    shortcut: { winLinux: "Shift+F7", mac: "Shift+F7" },
+    blockReason: {
+      code: UNSUPPORTED_SURFACE,
+      message: "Thesaurus shortcuts are not supported in the mounted editor.",
+    },
+  },
+  {
+    id: "extendSelection",
+    kind: "blocked",
+    category: "selection",
+    label: "Extend-selection mode",
+    shortcut: { winLinux: "F8", mac: "F8" },
+    blockReason: {
+      code: UNSUPPORTED_SURFACE,
+      message: "Extend-selection shortcuts are not supported in the mounted editor.",
+    },
+  },
+  {
+    id: "lastEdit",
+    kind: "blocked",
+    category: "navigation",
+    label: "Return to last edit",
+    shortcut: { winLinux: "Shift+F5", mac: "Shift+F5" },
+    blockReason: {
+      code: UNSUPPORTED_SURFACE,
+      message: "Last-edit shortcuts are not supported in the mounted editor.",
+    },
+  },
+];
+
+/**
+ * O(1) lookup by capability id. Derived from `EDITOR_CAPABILITIES`
+ * at module-load; freezes the map so accidental mutation throws.
+ */
+export const CAPABILITY_BY_ID: ReadonlyMap<string, EditorCapability> = (() => {
+  const map = new Map<string, EditorCapability>();
+  for (const cap of EDITOR_CAPABILITIES) {
+    map.set(cap.id, cap);
+  }
+  return map;
+})();
+
+/** Return every capability in the given category (preserves table order). */
+export function capabilitiesByCategory(
+  category: CapabilityCategory,
+): readonly EditorCapability[] {
+  return EDITOR_CAPABILITIES.filter((cap) => cap.category === category);
+}
+
+/** Return every capability with the given kind (preserves table order). */
+export function capabilitiesByKind(
+  kind: CapabilityKind,
+): readonly EditorCapability[] {
+  return EDITOR_CAPABILITIES.filter((cap) => cap.kind === kind);
+}

package/src/runtime/layout/index.ts

@@ -172,6 +172,8 @@ export {
   type PublicPageNode,
   type PublicPageRegions,
   type PublicPageRegion,
+  type PublicRegionBlock,
+  type PublicRegionKind,
   type PublicBlockFragment,
   type PublicLineBox,
   type PublicNoteAllocation,

package/src/runtime/layout/inert-layout-facet.ts

@@ -36,6 +36,8 @@ export function createInertLayoutFacet(): WordReviewEditorLayoutFacet {
     getLineBoxes: () => [],
     getLineBoxesForRegion: () => [],
     getStoryRegionsOnPage: () => [],
+    getStoryBlocksForRegion: () => [],
+    getDocumentEndnoteBlocks: () => [],
     getFragmentsForPage: () => [],
     getPageFormatCatalog: () => PAGE_FORMAT_CATALOG,
     getActivePageFormat: () => null,
@@ -59,6 +61,8 @@ export function createInertLayoutFacet(): WordReviewEditorLayoutFacet {
     getTableRenderPlan: () => null,
     getDirtyFieldFamilies: () => [],
     getFieldDirtinessReport: () => emptyReport,
+    setVisibleBlockRange: () => undefined,
+    requestViewportRefresh: () => undefined,
     subscribe: (_listener: (event: LayoutFacetEvent) => void) => () => undefined,
   };
 }