@beyondwork/docx-react-component 1.0.42 → 1.0.43

package/src/runtime/render/render-kernel.ts

@@ -17,7 +17,10 @@ import { MAIN_STORY_TARGET } from "../../core/selection/mapping.ts";
 import { recordPerfSample } from "../../ui-tailwind/editor-surface/perf-probe.ts";
 import type { EditorStoryTarget } from "../../api/public-types";
 import type {
+  PublicBlockFragment,
   PublicPageNode,
+  PublicPageRegion,
+  PublicRegionBlock,
   WordReviewEditorLayoutFacet,
 } from "../layout/public-facet.ts";
 import type {
@@ -305,6 +308,7 @@ function buildPage(
       zoom,
       "header",
       page.stories.header,
+      facet,
     );
   }
   if (page.stories.footer) {
@@ -314,9 +318,18 @@ function buildPage(
       zoom,
       "footer",
       page.stories.footer,
+      facet,
     );
   }
 
+  const footnoteRegions = buildFootnoteRegions(page, topPx, zoom, facet);
+  if (footnoteRegions.length > 0) {
+    regions.footnotes = footnoteRegions;
+  }
+  // Endnotes intentionally skipped — per-page endnote projection is not
+  // populated; endnotes use document-end placement via
+  // `facet.getDocumentEndnoteBlocks()`.
+
   const chromeReservations: PageChromeReservations = {
     ...defaultChromeReservations(layout, zoom),
   };
@@ -440,51 +453,181 @@ function buildHeaderFooterRegion(
   zoom: RenderZoom,
   kind: "header" | "footer",
   storyTarget: EditorStoryTarget,
+  facet: WordReviewEditorLayoutFacet,
 ): RenderStoryRegion {
   const layout = page.layout;
-  const widthTwips =
+  const fallbackWidthTwips =
     layout.pageWidth - layout.marginLeft - layout.marginRight;
-  let topTwips = 0;
-  let heightTwips = 0;
-  if (kind === "header") {
-    topTwips = layout.headerMargin ?? 720;
-    heightTwips = Math.max(0, layout.marginTop - topTwips);
-  } else {
-    topTwips = layout.pageHeight - layout.marginBottom;
-    heightTwips = Math.max(0, layout.marginBottom - (layout.footerMargin ?? 720));
-  }
+  const fallbackTopTwips =
+    kind === "header"
+      ? (layout.headerMargin ?? 720)
+      : layout.pageHeight - layout.marginBottom;
+  const fallbackHeightTwips =
+    kind === "header"
+      ? Math.max(0, layout.marginTop - (layout.headerMargin ?? 720))
+      : Math.max(0, layout.marginBottom - (layout.footerMargin ?? 720));
+
+  const region: PublicPageRegion =
+    (kind === "header" ? page.regions.header : page.regions.footer) ?? {
+      kind,
+      originTwips: fallbackTopTwips,
+      widthTwips: fallbackWidthTwips,
+      heightTwips: fallbackHeightTwips,
+      fragmentCount: 0,
+    };
 
   const frame: RenderFrameRect = {
     leftPx: layout.marginLeft * zoom.pxPerTwip,
-    topPx: pageTopPx + topTwips * zoom.pxPerTwip,
-    widthPx: widthTwips * zoom.pxPerTwip,
-    heightPx: heightTwips * zoom.pxPerTwip,
+    topPx: pageTopPx + region.originTwips * zoom.pxPerTwip,
+    widthPx: region.widthTwips * zoom.pxPerTwip,
+    heightPx: region.heightTwips * zoom.pxPerTwip,
   };
 
-  const region = kind === "header" ? page.regions.header : page.regions.footer;
-  if (!region) {
-    return {
-      storyTarget,
-      region: {
-        kind,
-        originTwips: topTwips,
-        widthTwips,
-        heightTwips,
-        fragmentCount: 0,
-      },
-      frame,
-      blocks: [],
-    };
-  }
+  const regionBlocks = facet.getStoryBlocksForRegion(page.pageIndex, kind);
+  const blocks = projectRegionBlocks(
+    regionBlocks,
+    frame,
+    zoom.pxPerTwip,
+    page.pageId,
+    page.pageIndex,
+    kind,
+  );
 
   return {
     storyTarget,
     region,
     frame,
-    blocks: [],
+    blocks,
   };
 }
 
+/**
+ * P8.3 — Build one `RenderStoryRegion` per `page.regions.footnotes` entry.
+ * The page graph reserves footnote regions at the bottom of the page
+ * (above the footer band) when `noteAllocations` produced fragments.
+ * Blocks come from `facet.getStoryBlocksForRegion(pageIndex, "footnote-area")`
+ * — one entry per allocated note body, stacked vertically.
+ *
+ * Currently the page graph emits a single footnote region per page
+ * covering every allocation, so the returned array has length 0 or 1. The
+ * shape allows for future allocation-splitting without changing the
+ * render-kernel contract.
+ */
+function buildFootnoteRegions(
+  page: PublicPageNode,
+  pageTopPx: number,
+  zoom: RenderZoom,
+  facet: WordReviewEditorLayoutFacet,
+): RenderStoryRegion[] {
+  const footnoteRegions = page.regions.footnotes;
+  if (!footnoteRegions || footnoteRegions.length === 0) return [];
+
+  const regionBlocks = facet.getStoryBlocksForRegion(
+    page.pageIndex,
+    "footnote-area",
+  );
+  if (regionBlocks.length === 0) return [];
+
+  const results: RenderStoryRegion[] = [];
+  // Today the runtime emits a single footnote-area region per page; if that
+  // ever changes we will split `regionBlocks` across each region entry's
+  // `fragmentCount`.  Preserve the shape so consumers can iterate safely.
+  let cursor = 0;
+  for (const region of footnoteRegions) {
+    const frame: RenderFrameRect = {
+      leftPx: page.layout.marginLeft * zoom.pxPerTwip,
+      topPx: pageTopPx + region.originTwips * zoom.pxPerTwip,
+      widthPx: region.widthTwips * zoom.pxPerTwip,
+      heightPx: region.heightTwips * zoom.pxPerTwip,
+    };
+
+    const blocksForThisRegion =
+      footnoteRegions.length === 1
+        ? regionBlocks
+        : regionBlocks.slice(cursor, cursor + region.fragmentCount);
+    cursor += region.fragmentCount;
+
+    const blocks = projectRegionBlocks(
+      blocksForThisRegion,
+      frame,
+      zoom.pxPerTwip,
+      page.pageId,
+      page.pageIndex,
+      "footnote-area",
+    );
+
+    // Footnote regions don't have a single canonical storyTarget (each
+    // block belongs to a different footnote body).  Pick the first block's
+    // note as the region's primary story when available so chrome surfaces
+    // keyed on `storyTarget.kind === "footnote"` can dispatch on the band.
+    const firstNote = page.noteAllocations.find(
+      (alloc) => alloc.noteKind === "footnote",
+    );
+    const storyTarget: EditorStoryTarget = firstNote
+      ? { kind: "footnote", noteId: firstNote.noteId }
+      : MAIN_STORY_TARGET;
+
+    results.push({
+      storyTarget,
+      region,
+      frame,
+      blocks,
+    });
+  }
+
+  return results;
+}
+
+/**
+ * P8.3 — Stack a `PublicRegionBlock[]` into `RenderBlock[]` inside the
+ * given region frame.  The cursor starts at `regionFrame.topPx` and
+ * advances by each block's `heightTwips × pxPerTwip`.  Synthesizes a
+ * `PublicBlockFragment` shape for each block so chrome surfaces reading
+ * `RenderBlock.fragment` see a consistent shape across body / header /
+ * footer / footnote-area regions.
+ */
+function projectRegionBlocks(
+  regionBlocks: readonly PublicRegionBlock[],
+  regionFrame: RenderFrameRect,
+  pxPerTwip: number,
+  pageId: string,
+  pageIndex: number,
+  regionKind: PublicPageRegion["kind"],
+): RenderBlock[] {
+  const blocks: RenderBlock[] = [];
+  let y = regionFrame.topPx;
+  for (let i = 0; i < regionBlocks.length; i += 1) {
+    const regionBlock = regionBlocks[i]!;
+    const blockHeightPx = Math.max(0, regionBlock.heightTwips) * pxPerTwip;
+    const blockFrame: RenderFrameRect = {
+      leftPx: regionFrame.leftPx,
+      topPx: y,
+      widthPx: regionFrame.widthPx,
+      heightPx: blockHeightPx,
+    };
+    const fragment: PublicBlockFragment = {
+      fragmentId: regionBlock.fragmentId,
+      blockId: regionBlock.blockId,
+      pageId,
+      pageIndex,
+      regionKind,
+      from: regionBlock.runtimeFromOffset,
+      to: regionBlock.runtimeToOffset,
+      heightTwips: regionBlock.heightTwips,
+      orderInRegion: i,
+    };
+    blocks.push({
+      fragment,
+      frame: blockFrame,
+      kind: classifyBlockKindFromId(regionBlock.blockId),
+      lines: [],
+      blockDecorations: [],
+    });
+    y += blockHeightPx;
+  }
+  return blocks;
+}
+
 // classifyBlockKind moved to `./block-fragment-projection.ts` (P4).
 
 function buildAnchorIndex(

package/src/runtime/surface-projection.ts

@@ -107,7 +107,7 @@ export function createEditorSurfaceSnapshot(
     }
   }
 
-  const secondaryStories = createSecondaryStorySurfaces(document);
+  const secondaryStories = createSecondaryStorySurfaces(document, numberingPrefixResolver);
 
   return {
     storySize: cursor,
@@ -886,9 +886,13 @@ function appendInlineSegments(
       return { nextCursor: start + 1, lockedFragmentIds: [node.fragmentId] };
     }
     case "chart_preview":
-      return appendComplexPreviewSegment(paragraph, node, start, "Embedded chart", createChartDetail(node));
+      return appendComplexPreviewSegment(paragraph, node, start, "Embedded chart", createChartDetail(node), {
+        previewMediaId: node.previewMediaId,
+      });
     case "smartart_preview":
-      return appendComplexPreviewSegment(paragraph, node, start, "SmartArt diagram", createSmartArtDetail(node));
+      return appendComplexPreviewSegment(paragraph, node, start, "SmartArt diagram", createSmartArtDetail(node), {
+        previewMediaId: node.previewMediaId,
+      });
     case "shape":
       if (promoteSecondaryStoryTextBoxes && node.isTextBox && node.text) {
         return appendTextBoxSegment(
@@ -1023,6 +1027,7 @@ function appendComplexPreviewSegment(
   start: number,
   label: string,
   detail: string,
+  extras: { previewMediaId?: string } = {},
 ): { nextCursor: number; lockedFragmentIds: string[] } {
   paragraph.segments.push({
     segmentId: `${paragraph.blockId}-segment-${paragraph.segments.length}`,
@@ -1033,6 +1038,7 @@ function appendComplexPreviewSegment(
     warningId: `warning:complex-preview:${start}`,
     label,
     detail,
+    ...(extras.previewMediaId ? { previewMediaId: extras.previewMediaId } : {}),
     state: "locked-preserve-only",
   });
   return { nextCursor: start + 1, lockedFragmentIds: [] };
@@ -1174,6 +1180,7 @@ function createPlainText(
 
 function createSecondaryStorySurfaces(
   document: CanonicalDocumentEnvelope,
+  numberingPrefixResolver: NumberingPrefixResolver,
 ): SecondaryStorySurface[] {
   const surfaces: SecondaryStorySurface[] = [];
   const subParts = document.subParts;
@@ -1181,8 +1188,6 @@ function createSecondaryStorySurfaces(
     return surfaces;
   }
 
-  const numberingPrefixResolver = createNumberingPrefixResolver(document.numbering);
-
   for (const section of collectSectionContexts(document)) {
     const headerVariants = resolveSectionVariants(
       "header",

package/src/runtime/workflow-markup.ts

@@ -22,28 +22,32 @@ import type {
   WorkflowCommentMarkup,
 } from "../api/public-types";
 import { MAIN_STORY_TARGET } from "../core/selection/mapping.ts";
-import { searchSurfaceBlocks } from "../core/search/search-text.ts";
+import {
+  projectSurfaceText,
+  searchProjectedSurfaceText,
+} from "../core/search/search-text.ts";
 import { describeOpaqueFragment, isBlockedImportFeatureKey } from "../preservation/store.ts";
 import type { CanonicalDocumentEnvelope } from "../core/state/editor-state.ts";
 
-export function collectWorkflowMarkupSnapshot(input: {
-  renderSnapshot: RuntimeRenderSnapshot;
-  fieldSnapshot: FieldSnapshot;
-  protectionSnapshot: ProtectionSnapshot;
-  preservation: CanonicalDocumentEnvelope["preservation"];
-  workflowMetadataSnapshot?: WorkflowMetadataSnapshot;
-}): WorkflowMarkupSnapshot {
+/**
+ * Surface-derived markup (highlights + block-level opaque fragments).
+ *
+ * Pure function of `(surface, preservation)` — extracted from
+ * `collectWorkflowMarkupSnapshot` so callers can cache the expensive walk
+ * separately from the cheap reference-equal inputs (metadata, comments,
+ * revisions, protected ranges).
+ */
+export function collectWorkflowSurfaceMarkup(
+  surface: RuntimeRenderSnapshot["surface"],
+  preservation: CanonicalDocumentEnvelope["preservation"],
+): { highlights: WorkflowHighlightMarkup[]; opaqueFragments: WorkflowOpaqueFragmentMarkup[] } {
   const highlights: WorkflowHighlightMarkup[] = [];
-  const metadata = collectWorkflowMetadataMarkup(input.workflowMetadataSnapshot);
-  const fields: WorkflowFieldMarkup[] = [];
   const opaqueFragments: WorkflowOpaqueFragmentMarkup[] = [];
-  const surface = input.renderSnapshot.surface;
-
   if (surface) {
     collectSurfaceMarkup(
       surface.blocks,
       MAIN_STORY_TARGET,
-      input.preservation,
+      preservation,
       highlights,
       opaqueFragments,
     );
@@ -51,16 +55,55 @@ export function collectWorkflowMarkupSnapshot(input: {
       collectSurfaceMarkup(
         story.blocks,
         story.target,
-        input.preservation,
+        preservation,
         highlights,
         opaqueFragments,
       );
     }
+  }
+  return { highlights, opaqueFragments };
+}
 
+export function collectWorkflowMarkupSnapshot(input: {
+  renderSnapshot: RuntimeRenderSnapshot;
+  fieldSnapshot: FieldSnapshot;
+  protectionSnapshot: ProtectionSnapshot;
+  preservation: CanonicalDocumentEnvelope["preservation"];
+  workflowMetadataSnapshot?: WorkflowMetadataSnapshot;
+  surfaceMarkupCache?: {
+    highlights: WorkflowHighlightMarkup[];
+    opaqueFragments: WorkflowOpaqueFragmentMarkup[];
+  };
+  perfStage?: (name: string, durationMs: number) => void;
+}): WorkflowMarkupSnapshot {
+  const perf = input.perfStage;
+  const stageStart = perf ? () => performance.now() : () => 0;
+  const stageEnd = perf ? (name: string, t0: number) => perf(name, performance.now() - t0) : () => {};
+
+  const tMeta = stageStart();
+  const metadata = collectWorkflowMetadataMarkup(input.workflowMetadataSnapshot);
+  stageEnd("metadata", tMeta);
+
+  const fields: WorkflowFieldMarkup[] = [];
+  const surface = input.renderSnapshot.surface;
+
+  const tSurface = stageStart();
+  const surfaceMarkup = input.surfaceMarkupCache ??
+    collectWorkflowSurfaceMarkup(surface, input.preservation);
+  const highlights = surfaceMarkup.highlights.slice();
+  const opaqueFragments = surfaceMarkup.opaqueFragments.slice();
+  stageEnd("surface", tSurface);
+
+  if (surface) {
+    const tFields = stageStart();
     fields.push(...collectFieldMarkup(surface, input.fieldSnapshot));
+    stageEnd("fields", tFields);
   }
+  const tOpaqueRest = stageStart();
   opaqueFragments.push(...collectOpaqueFragmentMarkup(input.preservation, opaqueFragments));
+  stageEnd("opaqueRest", tOpaqueRest);
 
+  const tCommentsEtc = stageStart();
   const comments = input.renderSnapshot.comments.threads.map((thread): WorkflowCommentMarkup => ({
     markupId: `comment:${thread.commentId}`,
     kind: "comment",
@@ -113,6 +156,8 @@ export function collectWorkflowMarkupSnapshot(input: {
       }),
     );
 
+  stageEnd("commentsEtc", tCommentsEtc);
+
   const items: WorkflowMarkupItem[] = [
     ...highlights,
     ...metadata,
@@ -303,11 +348,21 @@ function collectFieldMarkup(
     return [];
   }
 
+  // L7 Phase 1.5: project each story's text once up-front. The prior code
+  // called searchSurfaceBlocks per field, which re-projected the entire
+  // surface on every invocation. For the CCEP large-tables fixture this
+  // was ~220 ms per commit. Hoisting the projection out of the per-field
+  // loop collapses that to a single projection per story.
   const stories = [
-    { blocks: surface.blocks, storyTarget: MAIN_STORY_TARGET },
+    {
+      blocks: surface.blocks,
+      storyTarget: MAIN_STORY_TARGET,
+      projection: projectSurfaceText(surface.blocks),
+    },
     ...surface.secondaryStories.map((story) => ({
       blocks: story.blocks,
       storyTarget: story.target,
+      projection: projectSurfaceText(story.blocks),
     })),
   ];
 
@@ -318,7 +373,7 @@ function collectFieldMarkup(
     }
 
     for (const story of stories) {
-      const matches = searchSurfaceBlocks(story.blocks, displayText, { limit: 2 });
+      const matches = searchProjectedSurfaceText(story.projection, displayText, { limit: 2 });
       if (matches.length === 1) {
         const match = matches[0]!;
         return [

package/src/ui/WordReviewEditor.tsx

@@ -938,6 +938,22 @@ export function __createWordReviewEditorRefBridge(
         pendingConflicts,
       });
     },
+    // Schema 1.2 — EditorStateChannel delegation.
+    configureEditorStatePolicy: (policy) => {
+      runtime.configureEditorStatePolicy(policy);
+    },
+    registerEditorStateResolver: (resolver) => {
+      runtime.registerEditorStateResolver(resolver);
+    },
+    registerEditorStatePersister: (persister) => {
+      runtime.registerEditorStatePersister(persister);
+    },
+    getEditorStateKey: (namespace) => {
+      return runtime.getEditorStateKey(namespace);
+    },
+    retryPendingPersist: async (namespace) => {
+      await runtime.retryPendingPersist(namespace);
+    },
     setHostAnnotationOverlay: (overlay) => {
       runtime.setHostAnnotationOverlay(clonePublicValue(overlay));
     },
@@ -1961,6 +1977,22 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
             pendingConflicts: metadataConflictPendingRef.current,
           });
         },
+        // Schema 1.2 — EditorStateChannel delegation.
+        configureEditorStatePolicy: (policy) => {
+          activeRuntime.configureEditorStatePolicy(policy);
+        },
+        registerEditorStateResolver: (resolver) => {
+          activeRuntime.registerEditorStateResolver(resolver);
+        },
+        registerEditorStatePersister: (persister) => {
+          activeRuntime.registerEditorStatePersister(persister);
+        },
+        getEditorStateKey: (namespace) => {
+          return activeRuntime.getEditorStateKey(namespace);
+        },
+        retryPendingPersist: async (namespace) => {
+          await activeRuntime.retryPendingPersist(namespace);
+        },
         setHostAnnotationOverlay: (overlay) => {
           setHostAnnotationOverlayState(clonePublicValue(overlay));
         },
@@ -2618,6 +2650,19 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
           code: "unsupported_surface",
           message,
         }]),
+      onPasteApplied: (meta: {
+        segmentCount: number;
+        charCount: number;
+        source: "paste" | "drop";
+      }) => {
+        onEventRef.current?.({
+          type: "paste_applied",
+          documentId: props.documentId,
+          segmentCount: meta.segmentCount,
+          charCount: meta.charCount,
+          source: meta.source,
+        });
+      },
     };
 
     const reviewCallbacks = {
@@ -2763,14 +2808,21 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         applyRuntimeImageResize(activeRuntime, mediaId, dimensions),
       onSetImageFrame: (mediaId, offsets) =>
         applyRuntimeImageReposition(activeRuntime, mediaId, offsets),
-      onOpenHeaderStory: () =>
-        openDefaultStoryVariant(activeRuntime, snapshot.pageLayout, documentNavigation, "header"),
-      onOpenFooterStory: () =>
-        openDefaultStoryVariant(activeRuntime, snapshot.pageLayout, documentNavigation, "footer"),
+      // P8.11 — `onOpenHeaderStory` / `onOpenFooterStory` retired from the
+      // WordReviewEditor wiring.  Per-page header / footer bands rendered
+      // by `TwPageStackChromeLayer` call `onOpenStory(target)` with the
+      // exact `EditorStoryTarget` they represent, so the variant /
+      // relationship resolution happens inside the layout facet instead
+      // of the UI.  The deprecated props remain in the workspace type
+      // with a mount-time `console.warn`; hosts that still pass them can
+      // migrate to `onOpenStory` at their leisure.
       onOpenHeaderStoryForPage: (pageIndex: number) =>
         openStoryForPage(activeRuntime, pageIndex, "header"),
       onOpenFooterStoryForPage: (pageIndex: number) =>
         openStoryForPage(activeRuntime, pageIndex, "footer"),
+      onOpenStory: (target) => {
+        activeRuntime.openStory(target);
+      },
       onDeleteSectionBreak: (sectionIndex) =>
         applyRuntimeDeleteSectionBreak(activeRuntime, sectionIndex),
       onUpdateSectionLayout: (sectionIndex, patch) =>
@@ -2901,6 +2953,17 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         interactionGuardSnapshot={interactionGuardSnapshot}
         chromePreset={effectiveChromePreset}
         chromeOptions={chromeOptions}
+        {...(props.collabSession ? { collabSession: props.collabSession } : {})}
+        {...(props.collabTransportStatus
+          ? { collabTransportStatus: props.collabTransportStatus }
+          : {})}
+        {...(props.activeCommentId !== undefined
+          ? { activeCommentId: props.activeCommentId }
+          : {})}
+        collabActorId={currentUser.userId}
+        {...(props.collabSendBaseline
+          ? { collabSendBaseline: props.collabSendBaseline }
+          : {})}
         reviewQueue={reviewQueueSnapshot}
         documentContextAnalytics={documentContextAnalytics}
         selectionContextAnalytics={selectionContextAnalytics}
@@ -4866,47 +4929,6 @@ function openStoryForPage(
   runtime.openStory(target);
 }
 
-function openDefaultStoryVariant(
-  runtime: WordReviewEditorRuntime,
-  pageLayout: PageLayoutSnapshot | undefined,
-  navigation: ReturnType<WordReviewEditorRuntime["getDocumentNavigationSnapshot"]> | undefined,
-  kind: "header" | "footer",
-): void {
-  const variants =
-    kind === "header"
-      ? pageLayout?.headerVariants
-      : pageLayout?.footerVariants;
-  const activePage = navigation?.pages[navigation.activePageIndex];
-  const isFirstPageInSection =
-    activePage !== undefined &&
-    activePage.sectionIndex === pageLayout?.sectionIndex &&
-    activePage.pageInSection === 0;
-  const isEvenDocumentPage = activePage !== undefined && (activePage.pageIndex + 1) % 2 === 0;
-
-  let variant =
-    pageLayout?.differentFirstPage && isFirstPageInSection
-      ? variants?.find((entry) => entry.variant === "first")
-      : undefined;
-
-  if (!variant && pageLayout?.differentOddEvenPages && isEvenDocumentPage) {
-    variant = variants?.find((entry) => entry.variant === "even");
-  }
-
-  if (!variant) {
-    variant = variants?.find((entry) => entry.variant === "default") ?? variants?.[0];
-  }
-
-  if (!variant) {
-    return;
-  }
-  runtime.openStory({
-    kind,
-    relationshipId: variant.relationshipId,
-    variant: variant.variant,
-    sectionIndex: pageLayout?.sectionIndex,
-  });
-}
-
 function searchRuntimeDocument(
   runtime: WordReviewEditorRuntime,
   mountedSurface: TwProseMirrorSurfaceRef | null,

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;