@beyondwork/docx-react-component 1.0.41 → 1.0.43

package/src/ui/editor-command-bag.ts

@@ -2,6 +2,7 @@ import { useMemo, useRef } from "react";
 
 import type {
   CommentSidebarThreadSnapshot,
+  EditorStoryTarget,
   FormattingAlignment,
   HeaderFooterLinkPatch,
   InsertImageOptions,
@@ -87,12 +88,25 @@ export interface EditorCommandBag {
   onAcceptAllChanges(): void;
   onRejectAllChanges(): void;
   onCloseStory?(): void;
+  /**
+   * @deprecated P8.11 — see the matching prop on `TwReviewWorkspaceProps`.
+   * Kept optional for back-compat; per-page bands use `onOpenStory`.
+   */
   onOpenHeaderStory?(): void;
+  /**
+   * @deprecated P8.11 — see `onOpenHeaderStory`.
+   */
   onOpenFooterStory?(): void;
   /** Open the header story for a specific page (double-click on its band). */
   onOpenHeaderStoryForPage?(pageIndex: number): void;
   /** Open the footer story for a specific page (double-click on its band). */
   onOpenFooterStoryForPage?(pageIndex: number): void;
+  /**
+   * P8.11 — per-page header/footer band click handler.  Receives the
+   * exact `EditorStoryTarget` the band represents; the command bag wires
+   * this to `runtime.openStory(target)`.
+   */
+  onOpenStory?(target: EditorStoryTarget): void;
   onSetParagraphIndentation?(indentation: {
     left?: number;
     right?: number;

package/src/ui/editor-runtime-boundary.ts

@@ -34,12 +34,20 @@ import {
   type DocumentRuntimeEvent,
   type DocumentRuntime,
 } from "../runtime/document-runtime.ts";
+import { createEditorStateChannel } from "../runtime/editor-state-channel.ts";
 import {
   createRuntimeCommandAppliedBridge,
   type RuntimeCommandAppliedBridge,
 } from "../runtime/collab/runtime-collab-sync.ts";
 import { createInertLayoutFacet } from "../runtime/layout/index.ts";
-import { loadDocxEditorSession } from "../io/docx-session.ts";
+import {
+  loadDocxEditorSession,
+  loadDocxEditorSessionAsync,
+} from "../io/docx-session.ts";
+import {
+  createLoadScheduler,
+  type LoadScheduler,
+} from "../io/load-scheduler.ts";
 import {
   decodePersistedSourcePackageBytes,
   hasValidPersistedSourcePackageDigest,
@@ -48,6 +56,7 @@ import {
   createEditorViewStateSnapshot,
   createViewState,
 } from "../runtime/view-state.ts";
+import { hydrateEditorStateFromEnvelope } from "../runtime/editor-state-integration.ts";
 import {
   recordPerfSample,
 } from "../ui-tailwind/editor-surface/perf-probe.ts";
@@ -62,6 +71,14 @@ export interface ResolvedSource {
   initialDocx?: Uint8Array | ArrayBuffer;
   initialSessionState?: EditorSessionState;
   initialSnapshot?: PersistedEditorSnapshot;
+  /**
+   * Fastload P6: when the boundary hook pre-loads the docx via the
+   * async loader (DOM environments only), it stashes the session here
+   * so `createRuntime` reuses it instead of running another synchronous
+   * load. Undefined in SSR / Node test fallback — `createRuntime` then
+   * does the classic synchronous load.
+   */
+  preloadedDocxSession?: ReturnType<typeof loadDocxEditorSession>;
 }
 
 export interface CreateRuntimeArgs {
@@ -280,6 +297,9 @@ export function useEditorRuntimeBoundary(
   const pendingReadySourceRef = useRef<"docx" | "session" | "snapshot" | null>(null);
   const autosaveTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
   const lastSavedRevisionTokenRef = useRef<string | null>(null);
+  // Fastload P6: scheduler used by the DOM-side async docx loader. Held
+  // here so it can be disposed on unmount / source change.
+  const loadSchedulerRef = useRef<LoadScheduler | null>(null);
   const hostAdapterRef = useRef(hostAdapter);
   const datastoreRef = useRef(datastore);
   const onEventRef = useRef(onEvent);
@@ -355,6 +375,10 @@ export function useEditorRuntimeBoundary(
       lastSavedRevisionTokenRef.current = null;
       runtimeRef.current?.dispose?.();
       runtimeRef.current = null;
+      // Fastload P6: dispose any scheduler held from a previous mount /
+      // source cycle before allocating a fresh one for this load.
+      loadSchedulerRef.current?.dispose();
+      loadSchedulerRef.current = null;
       setRuntime(null);
 
       try {
@@ -375,6 +399,33 @@ export function useEditorRuntimeBoundary(
           return;
         }
 
+        // Fastload P6: in a DOM environment, preload the docx via the
+        // async loader so normalize-body yields mid-walk and the browser
+        // can paint the skeleton while the rest of the parse finishes.
+        // SSR / Node tests fall through to the synchronous load inside
+        // `createRuntime`.
+        if (
+          source.initialDocx !== undefined &&
+          source.preloadedDocxSession === undefined &&
+          typeof document !== "undefined"
+        ) {
+          const scheduler = createLoadScheduler();
+          loadSchedulerRef.current = scheduler;
+          const preloaded = await loadDocxEditorSessionAsync({
+            documentId,
+            sourceLabel: source.sourceLabel,
+            bytes: source.initialDocx,
+            editorBuild: "dev",
+            scheduler,
+          });
+          if (cancelled) {
+            scheduler.dispose();
+            loadSchedulerRef.current = null;
+            return;
+          }
+          source.preloadedDocxSession = preloaded;
+        }
+
         const nextRuntime = createRuntime(
           {
             documentId,
@@ -480,6 +531,11 @@ export function useEditorRuntimeBoundary(
       }
       runtimeRef.current?.dispose?.();
       runtimeRef.current = null;
+      // Fastload P6: release any pending idle callbacks the load scheduler
+      // registered so React unmount doesn't leak setTimeout/IdleCallback
+      // handles.
+      loadSchedulerRef.current?.dispose();
+      loadSchedulerRef.current = null;
     };
   }, []);
 
@@ -568,14 +624,16 @@ function createRuntime(
   handlers: RuntimeLifecycleHandlers = {},
 ): WordReviewEditorRuntime {
   const bootstrapEvents: DocumentRuntimeEvent[] = [];
-  const docxSession = args.source.initialDocx
-    ? loadDocxEditorSession({
-        documentId: args.documentId,
-        sourceLabel: args.source.sourceLabel,
-        bytes: args.source.initialDocx,
-        editorBuild: "dev",
-      })
-    : undefined;
+  const docxSession =
+    args.source.preloadedDocxSession ??
+    (args.source.initialDocx
+      ? loadDocxEditorSession({
+          documentId: args.documentId,
+          sourceLabel: args.source.sourceLabel,
+          bytes: args.source.initialDocx,
+          editorBuild: "dev",
+        })
+      : undefined);
   const snapshotExportResolution = !args.source.initialDocx
     ? resolvePackageBackedExportSession(args)
     : undefined;
@@ -594,7 +652,7 @@ function createRuntime(
     ? applySessionExportBarrier(initialSessionState, snapshotExportResolution.barrier)
     : initialSessionState;
 
-  const runtime: WordReviewEditorRuntime = Object.assign(createDocumentRuntime({
+  const baseRuntime = createDocumentRuntime({
     documentId: args.documentId,
     initialSessionState: runtimeSessionState,
     sourceKind: args.source.source,
@@ -629,7 +687,39 @@ function createRuntime(
     },
     defaultAuthorId: args.currentUserId,
     onCommandApplied: args.commandAppliedBridge?.onCommandApplied,
-  }), {
+  });
+
+  // Schema 1.2: drive load-path hydration from the parsed envelope.
+  if (docxSession?.initialEditorStatePayload) {
+    void hydrateEditorStateFromEnvelope({
+      editorState: docxSession.initialEditorStatePayload,
+      channel: baseRuntime.editorStateChannel,
+      applyBlob: (ns, data) => {
+        switch (ns) {
+          case "hostAnnotations":
+            baseRuntime.setHostAnnotationOverlay(data as import("../api/public-types.ts").HostAnnotationOverlay);
+            break;
+          case "workflowOverlay":
+            baseRuntime.setWorkflowOverlay(data as import("../api/public-types.ts").WorkflowOverlay);
+            break;
+          case "workflowMetadata":
+            // Metadata is split across definitions + entries in the runtime;
+            // inline payload carries the full snapshot so we apply entries.
+            if (data && typeof data === "object" && "entries" in (data as object)) {
+              baseRuntime.setWorkflowMetadataEntries(
+                (data as { entries: import("../api/public-types.ts").WorkflowMetadataEntry[] }).entries,
+              );
+            }
+            break;
+          case "workItems":
+            // workItems namespace is reserved; no runtime setter yet.
+            break;
+        }
+      },
+    });
+  }
+
+  const runtime: WordReviewEditorRuntime = Object.assign(baseRuntime, {
     drainBootstrapEvents: () => bootstrapEvents.splice(0, bootstrapEvents.length),
     emitBlockedCommand: (
       command: string,
@@ -868,6 +958,7 @@ function createLoadingRuntimeBridge(input: {
       Promise.reject(createLoadingBoundaryError(input.snapshot.documentId, "export")),
     setWorkflowOverlay: () => undefined,
     clearWorkflowOverlay: () => undefined,
+    getWorkflowOverlay: () => null,
     getWorkflowScopeSnapshot: () => null,
     getInteractionGuardSnapshot: () => ({ effectiveMode: "edit", blockedReasons: [] }),
     getWorkflowMarkupSnapshot: () => ({
@@ -907,6 +998,15 @@ function createLoadingRuntimeBridge(input: {
       items: [],
     }),
     getRuntimeContextAnalytics: () => null,
+    // Schema 1.2 — no-op stubs for loading boundary (SSR / headless path).
+    configureEditorStatePolicy: () => undefined,
+    registerEditorStateResolver: () => undefined,
+    registerEditorStatePersister: () => undefined,
+    getEditorStateKey: () => undefined,
+    retryPendingPersist: async () => undefined,
+    editorStateChannel: createEditorStateChannel(),
+    getPerfCountersSnapshot: () => ({}),
+    resetPerfCounters: () => undefined,
   };
 }
 

package/src/ui/editor-shell-view.tsx

@@ -64,6 +64,16 @@ export interface EditorShellViewProps {
   interactionGuardSnapshot?: InteractionGuardSnapshot;
   chromePreset?: WordReviewEditorChromePreset;
   chromeOptions?: Partial<WordReviewEditorChromeOptions>;
+  /** P9g — live collab session for the `"collab"` chrome preset's top nav. */
+  collabSession?: import("../runtime/collab-session.ts").CollabSession;
+  collabTransportStatus?: import("../api/awareness-identity-types.ts").TransportStatus;
+  collabActorId?: string;
+  collabSendBaseline?: {
+    originDocumentId: string;
+    originPayloadId: string;
+    originContentHash: string;
+    payloadXml: string;
+  };
   reviewQueue?: ReviewQueueSnapshot;
   documentContextAnalytics?: RuntimeContextAnalyticsSnapshot | null;
   selectionContextAnalytics?: RuntimeContextAnalyticsSnapshot | null;
@@ -105,6 +115,17 @@ export interface EditorShellViewProps {
     issueId: string;
     action: import("../api/public-types.ts").ScopeIssueAction;
   }) => void;
+  /** R3 — forwarded from workspace to WordReviewEditor. */
+  onScopeAcceptSuggestionGroup?: (payload: {
+    scopeId: string;
+    groupId: string;
+  }) => void;
+  onScopeRejectSuggestionGroup?: (payload: {
+    scopeId: string;
+    groupId: string;
+  }) => void;
+  /** K2 — forwarded from workspace to WordReviewEditor. */
+  onScopeAskAgent?: (payload: { scopeId: string }) => void;
 }
 
 export function EditorShellView(props: EditorShellViewProps) {

package/src/ui/editor-surface-controller.tsx

@@ -52,6 +52,11 @@ export interface EditorSurfaceControllerProps {
   onUndo?: () => void;
   onRedo?: () => void;
   onBlockedInput?: (command: "paste" | "drop", message: string) => void;
+  onPasteApplied?: (meta: {
+    segmentCount: number;
+    charCount: number;
+    source: "paste" | "drop";
+  }) => void;
   onCommentActivated?: (commentId: string) => void;
   onRevisionActivated?: (revisionId: string) => void;
   workflowScopes?: readonly WorkflowScope[];

package/src/ui/headless/selection-helpers.ts

@@ -1,5 +1,15 @@
 import type { SelectionSnapshot } from "../../api/public-types";
 
+/**
+ * Headless-UI-side `createSelectionSnapshot` that produces the **public**
+ * `EditorAnchorProjection` shape (top-level `from`/`to`). The runtime-facing
+ * twin at `src/core/state/editor-state.ts` produces the internal
+ * `RangeAnchor` shape (`range: { from, to }`). The two are *not*
+ * interchangeable — they serve different type contracts. See the
+ * `EditorAnchorProjection` definitions in `src/api/public-types.ts` vs
+ * `src/core/selection/mapping.ts`. Do not merge without first unifying
+ * those two definitions.
+ */
 export function createSelectionSnapshot(anchor: number, head = anchor): SelectionSnapshot {
   const from = Math.min(anchor, head);
   const to = Math.max(anchor, head);

package/src/ui-tailwind/chrome/chrome-preset-model.ts

@@ -51,6 +51,24 @@ export function resolveChromePresetOptions(
       showSectionTagAction: false,
       showReviewRail: true,
     },
+    collab: {
+      // Collab preset composes on top of "review" — same review rail,
+      // plus the collab top nav (presence, role + audience chips,
+      // tamper banner, negotiation action bar, send-to-supplier).
+      // Each sub-surface has its own flag so hosts can selectively
+      // disable parts (e.g. single-user demo, or a presenter-only view)
+      // without forking the preset.
+      showReviewQueueBar: false,
+      showSectionTagAction: false,
+      showReviewRail: true,
+      showCollabTopNav: true,
+      showCollabPresenceStrip: true,
+      showCollabRoleChip: true,
+      showCollabAudienceChip: true,
+      showCollabTamperBanner: true,
+      showCollabNegotiationActionBar: true,
+      showCollabSendToSupplier: true,
+    },
   };
 
   return {
@@ -116,6 +134,16 @@ export function resolveChromeVisibilityForPreset(input: {
       statusBar: true,
       reviewRail: options.showReviewRail,
     },
+    collab: {
+      toolbar: true,
+      alerts: true,
+      selectionOverlay: true,
+      contextToolbars: true,
+      contextAnalytics: true,
+      pageChrome: true,
+      statusBar: true,
+      reviewRail: options.showReviewRail,
+    },
   };
 
   return {

package/src/ui-tailwind/chrome/chrome-preset-toolbar.tsx

@@ -1,15 +1,75 @@
 import React from "react";
 
-import type { WordReviewEditorChromePreset } from "../../api/public-types";
+import type {
+  WordReviewEditorChromeOptions,
+  WordReviewEditorChromePreset,
+} from "../../api/public-types";
+import type { CollabSession } from "../../runtime/collab-session.ts";
+import type { TransportStatus } from "../../api/awareness-identity-types.ts";
 import {
   TwToolbar,
   type TwToolbarProps,
 } from "../toolbar/tw-toolbar";
+import { CollabTopNavContainer } from "./collab-top-nav-container";
 
 export interface ChromePresetToolbarProps extends TwToolbarProps {
   chromePreset: WordReviewEditorChromePreset;
+  /** P9g — optional collab session. Rendered above the toolbar when the `"collab"` preset is active. */
+  collabSession?: CollabSession;
+  collabTransportStatus?: TransportStatus;
+  activeCommentId?: string;
+  collabActorId?: string;
+  collabSendBaseline?: {
+    originDocumentId: string;
+    originPayloadId: string;
+    originContentHash: string;
+    payloadXml: string;
+  };
+  /**
+   * Sub-surface visibility toggles from `resolveChromePresetOptions`.
+   * When omitted the container defaults match the `"collab"` preset.
+   */
+  chromeOptionsResolved?: Pick<
+    WordReviewEditorChromeOptions,
+    | "showCollabTopNav"
+    | "showCollabPresenceStrip"
+    | "showCollabRoleChip"
+    | "showCollabAudienceChip"
+    | "showCollabTamperBanner"
+    | "showCollabNegotiationActionBar"
+    | "showCollabSendToSupplier"
+  >;
 }
 
 export function ChromePresetToolbar(props: ChromePresetToolbarProps) {
-  return <TwToolbar {...props} preset={props.chromePreset} />;
+  const {
+    collabSession,
+    collabTransportStatus,
+    activeCommentId,
+    collabActorId,
+    collabSendBaseline,
+    chromeOptionsResolved,
+    ...toolbarProps
+  } = props;
+
+  const collabActive =
+    props.chromePreset === "collab" && collabSession !== undefined;
+
+  return (
+    <>
+      {collabActive ? (
+        <CollabTopNavContainer
+          session={collabSession}
+          {...(activeCommentId !== undefined ? { activeCommentId } : {})}
+          actorId={collabActorId ?? "local"}
+          {...(collabTransportStatus
+            ? { transportStatus: collabTransportStatus }
+            : {})}
+          {...(chromeOptionsResolved ? { visibility: chromeOptionsResolved } : {})}
+          {...(collabSendBaseline ? { sendBaseline: collabSendBaseline } : {})}
+        />
+      ) : null}
+      <TwToolbar {...toolbarProps} preset={props.chromePreset} />
+    </>
+  );
 }

package/src/ui-tailwind/chrome/collab-audience-chip.tsx

@@ -0,0 +1,73 @@
+import * as React from "react";
+
+import type { CommentAudience } from "../../api/comment-presentation-types.ts";
+
+export interface CollabAudienceChipProps {
+  /** `undefined` when there is no active comment. */
+  audience: CommentAudience | undefined;
+  /** `true` when the local user is allowed to change audience. */
+  canEdit: boolean;
+  /** Invoked when the user cycles the chip. Caller dispatches set-audience. */
+  onCycle?: (next: CommentAudience) => void;
+  className?: string;
+}
+
+const CYCLE: readonly CommentAudience[] = ["internal", "external", "shared"];
+
+/**
+ * Audience chip for the active comment in the collab top nav (P9c).
+ *
+ * Renders the current `audience` of the active comment. Clicking
+ * cycles `internal → external → shared → internal` and invokes
+ * `onCycle(next)` — the caller is responsible for dispatching
+ * `set-audience` through `session.dispatchCommentPresentation`.
+ *
+ * Fail-safe rendering:
+ * - Renders a disabled "no comment" placeholder when `audience` is
+ *   undefined (no active comment selected).
+ * - Respects `canEdit`: when false, renders a disabled chip with the
+ *   current audience but no click handler — useful for observer /
+ *   reviewer who cannot change the audience.
+ */
+export function CollabAudienceChip({
+  audience,
+  canEdit,
+  onCycle,
+  className,
+}: CollabAudienceChipProps): React.ReactElement {
+  const empty = audience === undefined;
+  const disabled = empty || !canEdit;
+  const rootClass = [
+    "tw-collab-audience-chip",
+    audience ? `tw-collab-audience-chip--${audience}` : "tw-collab-audience-chip--empty",
+    disabled ? "tw-collab-audience-chip--disabled" : null,
+    className ?? null,
+  ]
+    .filter((v): v is string => v !== null)
+    .join(" ");
+
+  const label = empty ? "no comment" : audience;
+
+  const handleClick = (): void => {
+    if (disabled || !audience) return;
+    const idx = CYCLE.indexOf(audience);
+    const next = CYCLE[(idx + 1) % CYCLE.length]!;
+    onCycle?.(next);
+  };
+
+  return (
+    <button
+      type="button"
+      className={rootClass}
+      data-testid="collab-audience-chip"
+      data-audience={audience ?? "none"}
+      data-can-edit={canEdit ? "true" : "false"}
+      aria-label={empty ? "No active comment" : `Audience: ${audience}`}
+      aria-disabled={disabled ? "true" : undefined}
+      disabled={disabled}
+      onClick={handleClick}
+    >
+      {label}
+    </button>
+  );
+}