@beyondwork/docx-react-component 1.0.77 → 1.0.79

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

@@ -569,6 +569,19 @@ export interface WordReviewEditorLayoutFacet {
    */
   getTableBodyYOffsetOnPage(blockId: string, pageIndex: number): number | null;
 
+  /**
+   * Viewport-cull height resolver — returns total rendered height (twips)
+   * for every block in the current page graph, computed as the sum of each
+   * fragment's `heightTwips` grouped by `blockId`. Consumers (the render
+   * surface builder in particular) use this to size `placeholder-culled`
+   * opaque stubs so the scrollable canvas does not change height when a
+   * block realizes during scroll.
+   *
+   * Returns an empty map on the inert facet or before the first successful
+   * pagination pass. Cached per `graph.revision`.
+   */
+  getBlockHeightsTwips(): ReadonlyMap<string, number>;
+
   // Fields ---------------------------------------------------------------
   getDirtyFieldFamilies(): readonly string[];
   getFieldDirtinessReport(): PublicFieldDirtinessReport;
@@ -707,6 +720,13 @@ export function createLayoutFacet(
     revision: number;
     blocks: readonly PublicRegionBlock[] | null;
   } = { revision: -1, blocks: null };
+  // Viewport-cull flicker fix — per-revision cache for getBlockHeightsTwips.
+  // One entry per blockId; value is the sum of that block's fragments'
+  // `heightTwips`. Busts on `graph.revision` change.
+  let blockHeightsCache: {
+    revision: number;
+    map: ReadonlyMap<string, number> | null;
+  } = { revision: -1, map: null };
 
   function resolveCanonicalDocument(): CanonicalDocumentEnvelope {
     if (input.canonicalDocument) {
@@ -1234,6 +1254,21 @@ export function createLayoutFacet(
       return null;
     },
 
+    getBlockHeightsTwips() {
+      const graph = currentGraph();
+      if (blockHeightsCache.revision === graph.revision && blockHeightsCache.map) {
+        return blockHeightsCache.map;
+      }
+      const map = new Map<string, number>();
+      for (const frag of graph.fragments) {
+        const prev = map.get(frag.blockId) ?? 0;
+        map.set(frag.blockId, prev + frag.heightTwips);
+      }
+      const frozen: ReadonlyMap<string, number> = map;
+      blockHeightsCache = { revision: graph.revision, map: frozen };
+      return frozen;
+    },
+
     getDirtyFieldFamilies() {
       return engine.getDirtyFieldFamilies();
     },

package/src/runtime/workflow/coordinator.ts

@@ -791,19 +791,72 @@ export function createWorkflowCoordinator(deps: CoordinatorDeps): WorkflowCoordi
       return { scopeId, anchor: params.anchor };
     }
 
-    const { document: nextDocument } = insertScopeMarkers(
-      deps.getDocument(),
-      { scopeId, from: anchor.from, to: anchor.to },
-    );
+    const plantResult = insertScopeMarkers(deps.getDocument(), {
+      scopeId,
+      from: anchor.from,
+      to: anchor.to,
+    });
 
-    if (nextDocument !== deps.getDocument()) {
-      deps.dispatch({
-        type: "document.replace",
-        document: nextDocument,
-        origin: { source: "api", at: clock() },
-      });
+    // Plant failed — pre-2026-04-24 this returned silently with a dead
+    // scopeId; callers later saw `scope-not-resolvable`. Now surface
+    // the typed failure on the AddScopeResult so consumers can detect
+    // the plant-failed path without a round-trip through
+    // resolveReference.
+    if (plantResult.status !== "planted") {
+      const callerAssoc: { readonly start: -1 | 1; readonly end: -1 | 1 } =
+        params.anchor.kind === "range"
+          ? params.anchor.assoc
+          : { start: -1, end: 1 };
+      // Return the caller's input range as an informational range
+      // anchor. The authoritative failure signal is `scopeId: ""` +
+      // `plantStatus.planted === false`. The detached-anchor shape has
+      // a fixed reason enum (`deleted|invalidatedByStructureChange|
+      // importAmbiguity`) that doesn't cover plant-refused, so we keep
+      // the range kind and let callers discriminate via plantStatus.
+      return {
+        scopeId: "",
+        anchor: {
+          kind: "range",
+          from: anchor.from,
+          to: anchor.to,
+          assoc: callerAssoc,
+        },
+        plantStatus: {
+          planted: false,
+          reason: plantResult.status,
+          ...(plantResult.status === "cross-paragraph-range"
+            ? {
+                fromBlockIndex: plantResult.fromBlockIndex,
+                toBlockIndex: plantResult.toBlockIndex,
+              }
+            : {}),
+          ...(plantResult.status === "non-paragraph-target"
+            ? {
+                blockIndex: plantResult.blockIndex,
+                blockKind: plantResult.blockKind,
+              }
+            : {}),
+          ...(plantResult.status === "range-out-of-bounds"
+            ? { storyLength: plantResult.storyLength }
+            : {}),
+          requestedFrom: plantResult.from,
+          requestedTo: plantResult.to,
+        },
+      };
+      // Intentionally NOT dispatching document.replace or workflow.set-overlay —
+      // a failed plant must not leave a half-registered scope. Prevents the
+      // pre-fix "overlay carries scopeId but canonical tree has no markers"
+      // state that produced `scope-not-resolvable` on every follow-up call.
     }
 
+    const nextDocument = plantResult.document;
+
+    deps.dispatch({
+      type: "document.replace",
+      document: nextDocument,
+      origin: { source: "api", at: clock() },
+    });
+
     // Coord-06 §13d — preserve the caller's assoc on the public anchor.
     // resolveScope re-derives the range from the inserted markers but emits
     // a hardcoded { start: -1, end: 1 }; without this override the caller's

package/src/runtime/workflow/scope-writer.ts

@@ -276,10 +276,19 @@ export type CreateScopeFromAnchorResult =
       readonly reason:
         | "from-negative"
         | "to-less-than-from"
-        | "range-exceeds-story-length";
+        | "range-exceeds-story-length"
+        | "cross-paragraph-range"
+        | "non-paragraph-target"
+        | "empty-document";
       readonly from: number;
       readonly to: number;
       readonly storyLength: number;
+      /** Cross-paragraph only — the two block indices the range straddled. */
+      readonly fromBlockIndex?: number;
+      readonly toBlockIndex?: number;
+      /** Non-paragraph target only — the offending block's index and kind. */
+      readonly blockIndex?: number;
+      readonly blockKind?: string;
       /**
        * Single-sentence, agent-actionable explanation. Tells the caller
        * what the failure was and the concrete next step — no guesswork
@@ -291,7 +300,9 @@ export type CreateScopeFromAnchorResult =
        * Short machine-routable next-step hint for thin consumers that
        * don't want to pattern-match on `reason`. Examples:
        *   "clamp-from-to-zero", "swap-from-and-to",
-       *   "clamp-to-to-storyLength-or-pick-a-different-range".
+       *   "clamp-to-to-storyLength-or-pick-a-different-range",
+       *   "narrow-to-single-paragraph",
+       *   "pick-a-paragraph-target".
        */
       readonly nextStep: string;
     };
@@ -420,5 +431,82 @@ export function createScopeFromAnchor(
     ...(scopeMetadataFields.length > 0 ? { scopeMetadataFields } : {}),
   });
 
+  // Pre-2026-04-24 the coordinator silently returned a minted scopeId
+  // even when insertScopeMarkers refused to plant (cross-paragraph
+  // range, non-paragraph target, out-of-bounds after the story-length
+  // check passed). Now the coordinator surfaces `plantStatus.planted:
+  // false`; translate each reason into the same `range-invalid` shape
+  // used by the bounds checks above so the caller gets one uniform
+  // discriminator to branch on.
+  if (result.plantStatus && result.plantStatus.planted === false) {
+    const ps = result.plantStatus;
+    if (ps.reason === "cross-paragraph-range") {
+      return {
+        status: "range-invalid",
+        reason: "cross-paragraph-range",
+        from,
+        to,
+        storyLength,
+        fromBlockIndex: ps.fromBlockIndex ?? -1,
+        toBlockIndex: ps.toBlockIndex ?? -1,
+        message:
+          `createScopeFromAnchor refused: range [${from}, ${to}] straddles ` +
+          `paragraphs ${ps.fromBlockIndex} and ${ps.toBlockIndex}. Marker-backed ` +
+          `scopes only plant inside a single paragraph today. Narrow the range to ` +
+          `land inside one paragraph, or create two separate scopes.`,
+        nextStep: "narrow-to-single-paragraph",
+      };
+    }
+    if (ps.reason === "non-paragraph-target") {
+      return {
+        status: "range-invalid",
+        reason: "non-paragraph-target",
+        from,
+        to,
+        storyLength,
+        blockIndex: ps.blockIndex ?? -1,
+        blockKind: ps.blockKind ?? "unknown",
+        message:
+          `createScopeFromAnchor refused: range [${from}, ${to}] targets a ` +
+          `${ps.blockKind ?? "non-paragraph"} block (index ${ps.blockIndex}). ` +
+          `Marker scopes only plant inside paragraphs today. Pick a paragraph ` +
+          `target, or use runtime.workflow.createScope({blockId}) for ` +
+          `whole-block scopes on the containing structure.`,
+        nextStep: "pick-a-paragraph-target",
+      };
+    }
+    if (ps.reason === "range-out-of-bounds") {
+      // Shouldn't happen — storyLength was checked above — but surface
+      // it as a first-class failure in case the underlying length math
+      // drifts from our bounds check.
+      return {
+        status: "range-invalid",
+        reason: "range-exceeds-story-length",
+        from,
+        to,
+        storyLength: ps.storyLength ?? storyLength,
+        message:
+          `createScopeFromAnchor refused: coordinator reports range [${from}, ${to}] ` +
+          `is out of bounds (storyLength=${ps.storyLength}). This is usually a ` +
+          `stale-offset bug (KI-P9) — re-derive positions from the current ` +
+          `document and retry.`,
+        nextStep: "clamp-to-to-storyLength-or-pick-a-different-range",
+      };
+    }
+    // empty-document — target has no canonical blocks.
+    return {
+      status: "range-invalid",
+      reason: "empty-document",
+      from,
+      to,
+      storyLength,
+      message:
+        `createScopeFromAnchor refused: the target document has no blocks; ` +
+        `cannot plant scope markers. Open or initialize a document before ` +
+        `creating sub-block scopes.`,
+      nextStep: "initialize-document-before-creating-scopes",
+    };
+  }
+
   return { status: "created", scopeId: result.scopeId, anchor: result.anchor };
 }

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

@@ -186,6 +186,16 @@ export interface TwChromeOverlayProps {
   /** Preview catalog threaded into the page-stack chrome so header /
    *  footer / footnote / endnote regions render real <img>s. */
   mediaPreviews?: Record<string, import("../editor-surface/pm-state-from-snapshot").MediaPreviewDescriptor>;
+  /**
+   * Slice B (§6.20 reshape) — section-properties ribbon bundle forwarded
+   * to whichever per-page header/footer band is the active story. Pass
+   * `null` (or omit) when no header/footer is active. The bundle's `kind`
+   * is set by the band itself; do not pre-pin it.
+   */
+  activeBandRibbonProps?: Omit<
+    import("../page-stack/tw-active-band-ribbon").TwActiveBandRibbonProps,
+    "kind" | "data-testid"
+  > | null;
 }
 
 /**
@@ -230,6 +240,7 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
   pmView,
   visiblePageIndexRange,
   mediaPreviews,
+  activeBandRibbonProps,
 }) => {
   return (
     <div
@@ -248,6 +259,7 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
           pmView={pmView}
           visiblePageIndexRange={visiblePageIndexRange ?? null}
           mediaPreviews={mediaPreviews}
+          activeBandRibbonProps={activeBandRibbonProps ?? null}
         />
       ) : null}
       <TwScopeRailLayer

package/src/ui-tailwind/editor-surface/pm-schema.ts

@@ -199,6 +199,17 @@ export const editorSchema = new Schema({
         pageBreakBefore: { default: null },
         hiddenTextOnly: { default: null },
         placeholderCulled: { default: null },
+        /**
+         * Rendered height (in twips) of the block that this placeholder
+         * stands in for, supplied by `DocumentRuntime` from L04's page
+         * graph. When present on a `placeholderCulled` paragraph, `toDOM`
+         * emits a fixed-height `<div>` (`${twips/20}pt`) instead of the
+         * `min-height: 20px` fallback, eliminating the scroll-path
+         * "paragraphs jump around pagination gaps" flicker that occurred
+         * when blocks realized at real heights larger than one line.
+         * Null / undefined preserves the pre-existing 20 px minimum.
+         */
+        placeholderHeightTwips: { default: null },
         blockId: { default: null },
         /**
          * `<w:framePr>` projection from `SurfaceBlockFragment.frameProperties`
@@ -214,6 +225,11 @@ export const editorSchema = new Schema({
       toDOM(node) {
         // Viewport-culled placeholder paragraph — cheap size-preserving leaf.
         if (node.attrs.placeholderCulled) {
+          const heightTwips = node.attrs.placeholderHeightTwips as number | null;
+          const heightStyle =
+            typeof heightTwips === "number" && heightTwips > 0
+              ? `height: ${heightTwips / 20}pt`
+              : "min-height: 20px";
           return [
             "div",
             {
@@ -221,7 +237,10 @@ export const editorSchema = new Schema({
               "data-placeholder-culled": "true",
               "data-placeholder-size": String(node.nodeSize),
               "data-placeholder-block-id": node.attrs.blockId ?? "",
-              style: "min-height: 20px; contain: strict;",
+              ...(typeof heightTwips === "number" && heightTwips > 0
+                ? { "data-placeholder-height-twips": String(heightTwips) }
+                : {}),
+              style: `${heightStyle}; contain: strict;`,
               "aria-hidden": "true",
             },
             0,

package/src/ui-tailwind/editor-surface/pm-state-from-snapshot.ts

@@ -867,10 +867,25 @@ function buildOpaqueBlock(
   const placeholderSize = block.placeholderSize ?? null;
   if (placeholderSize !== null) {
     const targetSize = placeholderSize as number;
+    // Flicker fix — when DocumentRuntime has enriched the placeholder with
+    // the block's known rendered height (from L04's page graph), thread it
+    // onto the paragraph node so `pm-schema.ts::toDOM` emits a fixed
+    // `height` style matching the real block. Without this, the placeholder
+    // renders at `min-height: 20px` and inflates to its real height when
+    // the block realizes on scroll, dragging content below the scroll
+    // pointer ("paragraphs jump around pagination gaps").
+    const placeholderHeightTwips = block.placeholderHeightTwips ?? null;
+    const placeholderAttrs: Record<string, unknown> = {
+      blockId: block.blockId,
+      placeholderCulled: true,
+    };
+    if (placeholderHeightTwips !== null) {
+      placeholderAttrs.placeholderHeightTwips = placeholderHeightTwips;
+    }
     if (targetSize <= 2) {
       // Edge case: bare empty paragraph claims exactly 2 positions.
       return editorSchema.nodes.paragraph.create(
-        { blockId: block.blockId, placeholderCulled: true },
+        placeholderAttrs,
         Fragment.empty,
       );
     }
@@ -878,7 +893,7 @@ function buildOpaqueBlock(
     // total PM positions = 1 (open) + (targetSize - 2) (text) + 1 (close) = targetSize.
     const filler = "\u200b".repeat(targetSize - 2);
     return editorSchema.nodes.paragraph.create(
-      { blockId: block.blockId, placeholderCulled: true },
+      placeholderAttrs,
       editorSchema.text(filler),
     );
   }

package/src/ui-tailwind/editor-surface/tw-prosemirror-surface.tsx

@@ -916,21 +916,21 @@ export const TwProseMirrorSurface = forwardRef<
       viewRef.current = view;
       recordPerfSample("pm.mount");
     } else {
-      // Wave 1 Slice C · the single funnel for snapshot replacement.
+      // Wave 1 Slice C · snapshot-replacement funnel.
       //
-      // `replaceStatePreservingPosition` encapsulates two invariants:
-      //   1. Scroll position preservation — capture the anchor block
-      //      before `view.updateState`, restore scroll after, so the
-      //      user's viewport doesn't jump when blocks above change
-      //      height (invariant 7: geometry-facet warm path, no DOM
-      //      measurement on the hot path).
-      //   2. Echo-suppression ordering — `suppressSelectionEchoRef` is
-      //      set to `true` BEFORE the state swap and released in a
-      //      microtask AFTER, so PM's internal selection-change events
-      //      during the swap are swallowed by the selection-sync
-      //      plugin.
+      // `replaceStatePreservingPosition` owns the echo-suppression
+      // ordering around the state swap — suppressSelectionEchoRef is
+      // set to `true` BEFORE updateState and released in a microtask
+      // AFTER, so PM's internal selection-change events during the
+      // swap are swallowed by the selection-sync plugin.
       //
-      // Ordering is regression-guarded by
+      // Scroll-anchor preservation (`preserveScrollAnchor: true`) is
+      // currently OFF by default after the 2026-04-24 jump-to-top
+      // regression report (see hotfix commit). Re-enable under a
+      // diagnosed-safe codepath only; the capture/restore helpers
+      // remain tested and ready.
+      //
+      // Ordering invariant is regression-guarded by
       // `test/ui-tailwind/editor-surface/preserve-position-ordering.test.ts`.
       replaceStatePreservingPosition(
         {

package/src/ui-tailwind/page-stack/tw-active-band-ribbon.tsx

@@ -0,0 +1,229 @@
+import React from "react";
+
+import { preserveEditorSelectionMouseDown } from "../../ui/headless/preserve-editor-selection";
+import { TwPageRuler } from "../chrome/tw-page-ruler";
+import type {
+  EditorViewStateSnapshot,
+  HeaderFooterLinkPatch,
+  PageLayoutSnapshot,
+  SectionBreakType,
+  SectionLayoutPatch,
+  SectionPageNumberingPatch,
+} from "../../api/public-types";
+import type { ActiveParagraphLayout } from "../review-workspace/paragraph-layout";
+
+// ---------------------------------------------------------------------------
+// TwActiveBandRibbon — Slice B of the §6.20 page-layout reshape.
+//
+// A quiet on-demand surface that floats above (header) or below (footer)
+// an active header/footer band. Hosts the section-properties controls
+// previously parked in `TwLayoutPanel` + `TwReviewWorkspacePageToolbar`,
+// scoped to the active story only — matching Word's "Header & Footer"
+// ribbon-tab mental model. Dismisses with the active band.
+//
+// Position context: the parent band uses `position: absolute`; this
+// ribbon uses `position: absolute` with `bottom: 100%` (header) or
+// `top: 100%` (footer) so it overflows the band frame without
+// repositioning the band itself.
+// ---------------------------------------------------------------------------
+
+export interface TwActiveBandRibbonProps {
+  kind: "header" | "footer";
+  pageLayout: PageLayoutSnapshot;
+  viewState: EditorViewStateSnapshot;
+  paragraphLayout: ActiveParagraphLayout | null;
+  readOnly: boolean;
+  onCloseStory?: () => void;
+  onInsertSectionBreak?: (type: SectionBreakType) => void;
+  onUpdateSectionLayout?: (sectionIndex: number, patch: SectionLayoutPatch) => void;
+  onSetSectionPageNumbering?: (
+    sectionIndex: number,
+    patch: SectionPageNumberingPatch | null,
+  ) => void;
+  onSetHeaderFooterLink?: (sectionIndex: number, patch: HeaderFooterLinkPatch) => void;
+  onSetParagraphIndentation?: React.ComponentProps<typeof TwPageRuler>["onSetIndentation"];
+  onSetParagraphTabStops?: React.ComponentProps<typeof TwPageRuler>["onSetTabStops"];
+  "data-testid"?: string;
+}
+
+export const TwActiveBandRibbon: React.FC<TwActiveBandRibbonProps> = React.memo(({
+  kind,
+  pageLayout,
+  viewState,
+  paragraphLayout,
+  readOnly,
+  onCloseStory,
+  onInsertSectionBreak,
+  onUpdateSectionLayout,
+  onSetSectionPageNumbering,
+  onSetHeaderFooterLink,
+  onSetParagraphIndentation,
+  onSetParagraphTabStops,
+  "data-testid": testId,
+}) => {
+  const sectionIndex = pageLayout.sectionIndex;
+  const nextOrientation =
+    pageLayout.orientation === "portrait" ? "landscape" : "portrait";
+  const titlePageEnabled = pageLayout.differentFirstPage;
+  const numberingFormat = pageLayout.pageNumbering?.format ?? "decimal";
+  const positionStyles: React.CSSProperties =
+    kind === "header"
+      ? { left: 0, right: 0, bottom: "100%" }
+      : { left: 0, right: 0, top: "100%" };
+  const linkVariant: HeaderFooterLinkPatch["variant"] =
+    pageLayout.headerVariants[0]?.variant ?? "default";
+
+  return (
+    <div
+      data-active-band-ribbon={kind}
+      data-testid={testId}
+      onMouseDown={preserveEditorSelectionMouseDown}
+      style={{
+        position: "absolute",
+        ...positionStyles,
+        pointerEvents: "auto",
+        zIndex: 2,
+      }}
+      className="flex flex-col gap-1 rounded-md border border-border/50 bg-canvas/95 px-2 py-1 shadow-sm backdrop-blur-sm"
+    >
+      <div className="flex flex-wrap items-center gap-1">
+        <span className="text-[10px] font-semibold uppercase tracking-[0.12em] text-tertiary">
+          {kind === "header" ? "Header" : "Footer"} · Section {sectionIndex + 1}
+        </span>
+        {onCloseStory ? (
+          <RibbonButton
+            ariaLabel="Return to document body"
+            onClick={onCloseStory}
+            data-testid="active-band-ribbon-close"
+          >
+            Done
+          </RibbonButton>
+        ) : null}
+        <span aria-hidden="true" className="mx-1 h-3 w-px bg-border/60" />
+        <RibbonButton
+          ariaLabel={`Switch section to ${nextOrientation}`}
+          disabled={readOnly || !onUpdateSectionLayout}
+          onClick={() =>
+            onUpdateSectionLayout?.(sectionIndex, {
+              pageSize: {
+                orientation: nextOrientation,
+                width: pageLayout.pageHeight,
+                height: pageLayout.pageWidth,
+              },
+            })
+          }
+          data-testid="active-band-ribbon-orientation"
+        >
+          {nextOrientation === "landscape" ? "Landscape" : "Portrait"}
+        </RibbonButton>
+        <RibbonButton
+          ariaLabel="Insert next-page section break"
+          disabled={readOnly || !onInsertSectionBreak}
+          onClick={() => onInsertSectionBreak?.("nextPage")}
+          data-testid="active-band-ribbon-section-break"
+        >
+          Section break
+        </RibbonButton>
+        <RibbonButton
+          ariaLabel="Restart page numbering at 1"
+          disabled={readOnly || !onSetSectionPageNumbering}
+          onClick={() =>
+            onSetSectionPageNumbering?.(sectionIndex, {
+              ...(pageLayout.pageNumbering ?? {}),
+              start: 1,
+            })
+          }
+          data-testid="active-band-ribbon-restart-numbering"
+        >
+          Restart numbering
+        </RibbonButton>
+        <RibbonButton
+          ariaLabel={
+            numberingFormat === "roman"
+              ? "Switch numbering to decimal"
+              : "Switch numbering to roman"
+          }
+          disabled={readOnly || !onSetSectionPageNumbering}
+          onClick={() =>
+            onSetSectionPageNumbering?.(sectionIndex, {
+              ...(pageLayout.pageNumbering ?? {}),
+              format: numberingFormat === "roman" ? "decimal" : "roman",
+            })
+          }
+          data-testid="active-band-ribbon-numbering-format"
+        >
+          {numberingFormat === "roman" ? "Decimal" : "Roman"}
+        </RibbonButton>
+        <RibbonButton
+          ariaLabel="Toggle different first page"
+          disabled={readOnly || !onUpdateSectionLayout}
+          onClick={() =>
+            onUpdateSectionLayout?.(sectionIndex, {
+              titlePage: !titlePageEnabled,
+            })
+          }
+          data-testid="active-band-ribbon-title-page"
+        >
+          {titlePageEnabled ? "Same first page" : "Different first page"}
+        </RibbonButton>
+        {sectionIndex > 0 && onSetHeaderFooterLink ? (
+          <RibbonButton
+            ariaLabel={`Link ${kind} to previous section`}
+            disabled={readOnly}
+            onClick={() =>
+              onSetHeaderFooterLink(sectionIndex, {
+                kind,
+                variant: linkVariant,
+                linkToPrevious: true,
+              })
+            }
+            data-testid="active-band-ribbon-link-previous"
+          >
+            Link to previous
+          </RibbonButton>
+        ) : null}
+      </div>
+      <TwPageRuler
+        pageLayout={pageLayout}
+        viewState={viewState}
+        paragraphLayout={paragraphLayout}
+        readOnly={readOnly}
+        onReturnToBody={onCloseStory ?? (() => undefined)}
+        onSetIndentation={onSetParagraphIndentation}
+        onSetTabStops={onSetParagraphTabStops}
+      />
+    </div>
+  );
+});
+
+interface RibbonButtonProps {
+  ariaLabel: string;
+  children: React.ReactNode;
+  disabled?: boolean;
+  onClick: () => void;
+  "data-testid"?: string;
+}
+
+function RibbonButton({
+  ariaLabel,
+  children,
+  disabled,
+  onClick,
+  "data-testid": testId,
+}: RibbonButtonProps): React.ReactElement {
+  return (
+    <button
+      type="button"
+      aria-label={ariaLabel}
+      disabled={disabled}
+      data-testid={testId}
+      onMouseDown={preserveEditorSelectionMouseDown}
+      onClick={onClick}
+      className="inline-flex h-6 items-center rounded px-2 text-[11px] font-medium text-primary transition-colors hover:bg-surface disabled:cursor-not-allowed disabled:opacity-40"
+    >
+      {children}
+    </button>
+  );
+}
+
+export default TwActiveBandRibbon;