@beyondwork/docx-react-component 1.0.42 → 1.0.43

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,
@@ -908,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;

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-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-top-nav-container.tsx

@@ -0,0 +1,281 @@
+import * as React from "react";
+
+import type { CollabSession } from "../../runtime/collab-session.ts";
+import type {
+  CommentAudience,
+} from "../../api/comment-presentation-types.ts";
+import type { WordReviewEditorChromeOptions } from "../../api/public-types.ts";
+import type { TransportStatus } from "../../api/awareness-identity-types.ts";
+import { CollabPresenceStrip } from "./collab-presence-strip.tsx";
+import { CollabRoleChip } from "./collab-role-chip.tsx";
+import { CollabAudienceChip } from "./collab-audience-chip.tsx";
+import { CollabTamperBanner } from "./collab-tamper-banner.tsx";
+import { CollabNegotiationActionBar } from "./collab-negotiation-action-bar.tsx";
+import { CollabSendToSupplierButton } from "./collab-send-to-supplier-button.tsx";
+import {
+  CollabSendToSupplierModal,
+  type CollabSendToSupplierSubmitArgs,
+} from "./collab-send-to-supplier-modal.tsx";
+
+export type CollabSubSurfaceVisibility = Pick<
+  WordReviewEditorChromeOptions,
+  | "showCollabTopNav"
+  | "showCollabPresenceStrip"
+  | "showCollabRoleChip"
+  | "showCollabAudienceChip"
+  | "showCollabTamperBanner"
+  | "showCollabNegotiationActionBar"
+  | "showCollabSendToSupplier"
+>;
+
+export interface CollabTopNavContainerProps {
+  /** Wired collab session. When `undefined` / detached, the container renders nothing. */
+  session: CollabSession | undefined;
+  /** The currently-focused comment id (if any). Host supplies this from its own selection signal. */
+  activeCommentId?: string;
+  /**
+   * Fresh identity metadata about the local user. The session falls
+   * back to `author` if no awareness is wired, which matches the
+   * `CollabPosture` contract. This prop is passed through so tests /
+   * hosts can override the actor id used by the action bar without
+   * also mutating awareness.
+   */
+  actorId: string;
+  /** Current transport status signal (from the host's provider). */
+  transportStatus?: TransportStatus;
+  /** Visibility toggles from the chrome preset options. */
+  visibility?: CollabSubSurfaceVisibility;
+  /**
+   * Minimum send-to-supplier args a host wants to commit to before the
+   * confirmation modal even appears. The modal collects the rest.
+   */
+  sendBaseline?: {
+    originDocumentId: string;
+    originPayloadId: string;
+    originContentHash: string;
+    payloadXml: string;
+  };
+  /**
+   * Optional override for the activeStory filter passed into
+   * `getPresenceSnapshot({ activeStoryFilter })`.
+   */
+  activeStoryFilter?: string;
+  className?: string;
+}
+
+const DEFAULT_VISIBILITY: Required<CollabSubSurfaceVisibility> = {
+  showCollabTopNav: true,
+  showCollabPresenceStrip: true,
+  showCollabRoleChip: true,
+  showCollabAudienceChip: true,
+  showCollabTamperBanner: true,
+  showCollabNegotiationActionBar: true,
+  showCollabSendToSupplier: true,
+};
+
+/**
+ * P9g — chrome-toolbar container. Subscribes to the `CollabSession`
+ * event stream and renders the six P9a–f components from live
+ * snapshots. Pure React, no Yjs / awareness coupling — the session
+ * abstracts those away.
+ *
+ * The container intentionally renders `null` when no session is wired
+ * so the chrome toolbar can mount it unconditionally while the host
+ * decides whether to supply a session.
+ *
+ * Individual sub-surfaces can be opted out via `visibility`; the
+ * defaults mirror the `"collab"` chrome preset so hosts that
+ * instantiate directly get the full top nav.
+ */
+export function CollabTopNavContainer({
+  session,
+  activeCommentId,
+  actorId,
+  transportStatus,
+  visibility,
+  sendBaseline,
+  activeStoryFilter,
+  className,
+}: CollabTopNavContainerProps): React.ReactElement | null {
+  const effective: Required<CollabSubSurfaceVisibility> = {
+    ...DEFAULT_VISIBILITY,
+    ...normalizeVisibility(visibility),
+  };
+
+  const [tick, setTick] = React.useState(0);
+  const [sendModalOpen, setSendModalOpen] = React.useState(false);
+
+  React.useEffect(() => {
+    if (!session) return undefined;
+    const off = session.subscribe((event) => {
+      // Any event from the bridge OR the tamper gate triggers a
+      // re-read. The container is cheap to re-render; the underlying
+      // snapshots are already deep-cloned by the stores.
+      //
+      // We deliberately ignore the event type — the container is
+      // declarative about what it renders, so a single bump is enough.
+      void event;
+      setTick((n) => n + 1);
+    });
+    return off;
+  }, [session]);
+
+  if (!session || !effective.showCollabTopNav) return null;
+
+  const presence = session.getPresenceSnapshot({
+    ...(transportStatus ? { transportStatus } : {}),
+    ...(activeStoryFilter !== undefined ? { activeStoryFilter } : {}),
+  });
+  const posture = session.getCollabPosture({
+    ...(transportStatus ? { transportStatus } : {}),
+  });
+  const integrity = session.getMetadataIntegrity();
+  const presentation = session.getCommentPresentationSnapshot();
+  const negotiation = session.getCommentNegotiationSnapshot();
+
+  const activePresentation = activeCommentId
+    ? presentation.entries.find((e) => e.commentId === activeCommentId)
+    : undefined;
+  const activeNegotiation = activeCommentId
+    ? negotiation.entries.find((e) => e.commentId === activeCommentId)
+    : undefined;
+
+  const internalCount = presentation.entries.filter(
+    (e) => e.audience === "internal",
+  ).length;
+  const shareableCount = presentation.entries.filter(
+    (e) => e.audience !== "internal",
+  ).length;
+
+  const canEditAudience = posture.role !== "observer" && activePresentation !== undefined;
+  const tampered = integrity === "tampered";
+
+  const rootClass = [
+    "tw-collab-top-nav",
+    `tw-collab-top-nav--${posture.role}`,
+    tampered ? "tw-collab-top-nav--tampered" : null,
+    className ?? null,
+  ]
+    .filter((v): v is string => v !== null)
+    .join(" ");
+
+  const handleAudienceCycle = (next: CommentAudience): void => {
+    if (!activeCommentId) return;
+    void session.dispatchCommentPresentation({
+      type: "set-audience",
+      commentId: activeCommentId,
+      audience: next,
+    });
+  };
+
+  const handleNegotiationDispatch = (
+    action: Parameters<CollabSession["dispatchCommentNegotiation"]>[0],
+  ): void => {
+    session.dispatchCommentNegotiation(action, {
+      role: posture.role,
+      now: new Date().toISOString(),
+    });
+  };
+
+  const handleSendSubmit = async (
+    args: CollabSendToSupplierSubmitArgs,
+  ): Promise<void> => {
+    if (!sendBaseline) {
+      setSendModalOpen(false);
+      return;
+    }
+    await session.sendToExternal({
+      payloadXml: sendBaseline.payloadXml,
+      originDocumentId: sendBaseline.originDocumentId,
+      originPayloadId: sendBaseline.originPayloadId,
+      originContentHash: sendBaseline.originContentHash,
+      recipient: args.recipient,
+      sentBy: actorId,
+      archiveRef: args.archiveRef,
+    });
+    setSendModalOpen(false);
+  };
+
+  return (
+    <div
+      className={rootClass}
+      data-testid="collab-top-nav-container"
+      data-tick={tick.toString()}
+      data-role={posture.role}
+      data-integrity={integrity}
+    >
+      {effective.showCollabTamperBanner ? (
+        <CollabTamperBanner
+          integrity={integrity}
+          onAcknowledge={() => session.acknowledgeMetadataTampering()}
+        />
+      ) : null}
+
+      <div className="tw-collab-top-nav__row">
+        {effective.showCollabPresenceStrip ? (
+          <CollabPresenceStrip
+            presence={presence}
+            localRole={posture.role}
+          />
+        ) : null}
+
+        {effective.showCollabRoleChip ? (
+          <CollabRoleChip
+            posture={posture}
+            {...(transportStatus ? { transportStatus } : {})}
+          />
+        ) : null}
+
+        {effective.showCollabAudienceChip ? (
+          <CollabAudienceChip
+            audience={activePresentation?.audience}
+            canEdit={canEditAudience}
+            onCycle={handleAudienceCycle}
+          />
+        ) : null}
+
+        {effective.showCollabNegotiationActionBar ? (
+          <CollabNegotiationActionBar
+            entry={activeNegotiation}
+            actorId={actorId}
+            role={posture.role}
+            onDispatch={handleNegotiationDispatch}
+            disabled={tampered}
+          />
+        ) : null}
+
+        {effective.showCollabSendToSupplier ? (
+          <CollabSendToSupplierButton
+            role={posture.role}
+            integrity={integrity}
+            shareableCount={shareableCount}
+            internalCount={internalCount}
+            onOpenModal={() => setSendModalOpen(true)}
+          />
+        ) : null}
+      </div>
+
+      {effective.showCollabSendToSupplier ? (
+        <CollabSendToSupplierModal
+          open={sendModalOpen}
+          shareableCount={shareableCount}
+          internalCount={internalCount}
+          onClose={() => setSendModalOpen(false)}
+          onSubmit={handleSendSubmit}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+function normalizeVisibility(
+  visibility: CollabSubSurfaceVisibility | undefined,
+): Partial<Required<CollabSubSurfaceVisibility>> {
+  if (!visibility) return {};
+  const out: Partial<Required<CollabSubSurfaceVisibility>> = {};
+  for (const key of Object.keys(DEFAULT_VISIBILITY) as (keyof CollabSubSurfaceVisibility)[]) {
+    const v = visibility[key];
+    if (typeof v === "boolean") out[key] = v;
+  }
+  return out;
+}

package/src/ui-tailwind/chrome-overlay/tw-chrome-overlay.tsx

@@ -17,6 +17,7 @@ import type { OverlayCoordinateSpace } from "./chrome-overlay-projector";
 import type { ScopeRailSegment } from "../../runtime/layout";
 import type {
   EditorRole,
+  EditorStoryTarget,
   ScopeIssueAction,
   TableStructureContextSnapshot,
   WordReviewEditorLayoutFacet,
@@ -25,6 +26,7 @@ import type {
 import { TwScopeRailLayer } from "./tw-scope-rail-layer";
 import { TwScopeCardLayer } from "./tw-scope-card-layer";
 import { TwPageStackOverlayLayer } from "./tw-page-stack-overlay-layer";
+import { TwPageStackChromeLayer, type PmPortalView } from "../page-stack/tw-page-stack-chrome-layer";
 import { TwTableGripLayer } from "../chrome/tw-table-grip-layer";
 
 export interface TwChromeOverlayProps {
@@ -119,6 +121,37 @@ export interface TwChromeOverlayProps {
    * full workspace re-render.
    */
   renderFrameRevision?: number;
+
+  // Page-stack chrome layer (P8.8) --------------------------------------
+  /**
+   * Current active story target — the page-stack chrome layer uses this
+   * to decide which per-page band (if any) should render in active-slot
+   * mode.  When omitted the chrome layer treats `{ kind: "main" }` as
+   * the active story, so no band is promoted.
+   */
+  activeStory?: EditorStoryTarget;
+  /**
+   * Fired when the user clicks a per-page header / footer band to
+   * promote it into the active editing surface.  Task 10 will route PM
+   * into the matching band via React portals; today the handler is a
+   * pass-through to `runtime.openStory`.
+   */
+  onOpenStory?: (target: EditorStoryTarget) => void;
+  /**
+   * P8.11 — PM surface DOM element (`.ProseMirror` div).  The chrome
+   * layer's portal mechanism reparents this element across the per-page
+   * band portal slots as `activeStory` changes.  When omitted the
+   * reparent step is skipped; the chrome layer still renders read-only
+   * bands but the active-slot promotion is inert.
+   */
+  pmSurfaceElement?: HTMLElement | null;
+  /**
+   * P8.11 — optional PM view handle with `hasFocus()` + `focus()`.  When
+   * supplied, the chrome layer re-focuses PM after a portal swap so
+   * mid-edit band clicks don't silently drop the caret.  Omitting the
+   * handle leaves focus-restore as a no-op — DOM reparent still runs.
+   */
+  pmView?: PmPortalView | null;
 }
 
 /**
@@ -151,6 +184,10 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
   onSetRowHeight,
   pageStackScrollRoot,
   renderFrameRevision,
+  activeStory,
+  onOpenStory,
+  pmSurfaceElement,
+  pmView,
 }) => {
   return (
     <div
@@ -165,6 +202,17 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
           renderFrameRevision={renderFrameRevision ?? 0}
         />
       ) : null}
+      {pageStackScrollRoot !== undefined ? (
+        <TwPageStackChromeLayer
+          facet={facet}
+          scrollRoot={pageStackScrollRoot}
+          renderFrameRevision={renderFrameRevision ?? 0}
+          activeStory={activeStory ?? { kind: "main" }}
+          onOpenStory={onOpenStory}
+          pmSurfaceElement={pmSurfaceElement}
+          pmView={pmView}
+        />
+      ) : null}
       <TwScopeRailLayer
         facet={facet}
         space={space}