@beyondwork/docx-react-component 1.0.77 → 1.0.78

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.77",
+  "version": "1.0.78",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

package/src/io/ooxml/parse-shapes.ts

@@ -10,7 +10,7 @@
  * preserved in the canonical node's rawXml field for lossless round-trip export.
  */
 
-import type { ShapeContent } from "../../model/canonical-document.ts";
+import type { BlockNode, ShapeContent } from "../../model/canonical-document.ts";
 import { parseFill } from "./parse-fill.ts";
 import {
   type XmlElementNode,
@@ -40,7 +40,7 @@ export interface ParsedWpsShape {
    * shape-textbox paragraphs). Same shape + semantics as
    * `ShapeContent.txbxBlocks` on the drawing-frame path.
    */
-  txbxBlocks?: ReadonlyArray<{ type: string; [key: string]: unknown }>;
+  txbxBlocks?: ReadonlyArray<BlockNode>;
   /** DrawML geometry preset, e.g. "rect", "roundRect". */
   geometry?: string;
   /** Original drawing XML for lossless round-trip export. */
@@ -122,10 +122,20 @@ export function parseShapeXml(
   // content (CCEP "Copyright CCEP STRICTLY CONFIDENTIAL" footer band)
   // is reachable only via the `.text` summary string — L03 cascade +
   // L11 render can't walk runs/marks.
-  let txbxBlocks: ReadonlyArray<{ type: string; [key: string]: unknown }> | undefined;
+  let txbxBlocks: ReadonlyArray<BlockNode> | undefined;
   if (txbxContentXml && blockParser) {
     try {
-      txbxBlocks = blockParser(txbxContentXml);
+      // The `blockParser` callback is supplied by parse-main-document.ts
+      // as a thin wrapper over `parseBlockStreamFromXml`. That function
+      // returns `ParsedBlockNode[]` — structurally identical to canonical
+      // `BlockNode[]` at runtime for shape-textbox content (verified on
+      // CCEP SOW footer fixture 2026-04-24: paragraph + text + TextMark
+      // shapes land end-to-end with zero `ParsedBlockNode`-only fields
+      // surfaced). The cast is safe here because the runtime output IS
+      // canonical; a structural `as unknown as BlockNode[]` preserves
+      // type safety at every consumer site (L03 cascade, L11 render,
+      // validator walk).
+      txbxBlocks = blockParser(txbxContentXml) as unknown as ReadonlyArray<BlockNode>;
     } catch {
       txbxBlocks = undefined;
     }
@@ -214,6 +224,17 @@ function extractAllText(node: XmlElementNode): string {
 // txbxContentXml, optional recursive txbxBlocks).
 // ───────────────────────────────────────────────────────────────────────────
 
+/**
+ * Callback signature for the txbx-content block parser supplied by
+ * parse-main-document.ts / parse-headers-footers.ts. The actual
+ * implementation wraps `parseBlockStreamFromXml` which returns
+ * `ParsedBlockNode[]`; its runtime output is canonical `BlockNode[]`
+ * for shape-textbox content (no `ParsedBlockNode`-only fields surface
+ * at the shape boundary — verified on CCEP SOW footer fixture
+ * 2026-04-24). The structural `unknown` return keeps the parse layer
+ * layer-pure; `parseShapeContent` + `parseShapeXml` cast to canonical
+ * `BlockNode[]` at the assembly seam.
+ */
 export type TxbxBlockParser = (xml: string) => ReadonlyArray<{ type: string; [key: string]: unknown }>;
 
 export function parseShapeContent(
@@ -240,10 +261,15 @@ export function parseShapeContent(
   const txbxContent = txbx ? findFirstDescendant(txbx, "txbxContent") : undefined;
   const txbxContentXml = txbxContent ? extractRawXml(txbxContent) : undefined;
 
-  let txbxBlocks: ReadonlyArray<{ type: string; [key: string]: unknown }> | undefined;
+  let txbxBlocks: ReadonlyArray<BlockNode> | undefined;
   if (txbxContentXml && blockParser) {
     try {
-      txbxBlocks = blockParser(txbxContentXml);
+      // See `TxbxBlockParser` doc above: runtime output is canonical
+      // `BlockNode[]` for shape-textbox content (verified on CCEP SOW
+      // footer fixture 2026-04-24). Cast at the assembly seam so
+      // downstream consumers (L03, L11, validator) get canonical types
+      // without local `as unknown` ceremony.
+      txbxBlocks = blockParser(txbxContentXml) as unknown as ReadonlyArray<BlockNode>;
     } catch {
       // Preserve-only fallback: keep txbxContentXml for serialization; leave
       // txbxBlocks undefined so consumers know recursion did not succeed.

package/src/model/canonical-document.ts

@@ -1786,12 +1786,29 @@ export interface SmartArtPreviewNode {
 /**
  * Read-only rendering of a wps:wsp WordprocessingShape. Text content is
  * extracted for display. The original drawing XML is preserved in rawXml.
+ *
+ * When the shape is a text-box (`isTextBox: true`), the raw textbox XML
+ * is preserved in `txbxContentXml` for lossless round-trip, and the
+ * parsed block structure lands in `txbxBlocks` — canonical `BlockNode[]`
+ * with styles already resolved (coord-02 §14 / coord-11 §22 closed L01
+ * side 2026-04-24 in `7d87f1189`; L02 type-promoted 2026-04-24 once the
+ * runtime contract was confirmed canonical).
  */
 export interface ShapeNode {
   type: "shape";
   text?: string;
   geometry?: string;
   isTextBox?: boolean;
+  /** Raw `<w:txbxContent>` XML, preserved for serialization + round-trip. */
+  txbxContentXml?: string;
+  /**
+   * Parsed canonical block-level structure from `<w:txbxContent>`,
+   * populated when the parse path supplies a `blockParser` callback
+   * (headers/footers via `src/io/ooxml/parse-headers-footers.ts`;
+   * body via `src/io/ooxml/parse-main-document.ts`). Shape + semantics
+   * identical to `ShapeContent.txbxBlocks` on the drawing-frame path.
+   */
+  txbxBlocks?: ReadonlyArray<BlockNode>;
   rawXml: string;
 }
 
@@ -1971,14 +1988,16 @@ export interface ShapeContent {
    * Parsed block-level structure from `w:txbxContent`, populated when a
    * `blockParser` callback is supplied during parse (CO4 F3.3).
    *
-   * Type is deliberately structural (`{ type: string; ... }`) rather than
-   * canonical `BlockNode[]` because the recursion stops at the parse layer
-   * before the style + numbering normalization pass that converts
-   * `ParsedBlockNode` → canonical `BlockNode`. Consumers that need the fully
-   * normalized form run normalization on this subtree explicitly. Testing
-   * that `txbxBlocks.length > 0` proves the recursion executed.
+   * Canonical `BlockNode[]` — the parse path produces fully-normalized
+   * blocks (styles resolved, marks attached, no `ParsedBlockNode`-only
+   * fields at runtime). Verified on the CCEP SOW footer fixture 2026-04-24:
+   * paragraph + text + `TextMark` shapes land end-to-end. Type promoted
+   * 2026-04-24 from the earlier weakly-typed escape hatch once the L01
+   * shape-textbox parse (commit `7d87f1189`) confirmed the runtime
+   * contract — unblocks L03 cascade + L11 render walking `txbxBlocks`
+   * without `as unknown as BlockNode[]` casts at the consumer site.
    */
-  txbxBlocks?: ReadonlyArray<{ type: string; [key: string]: unknown }>;
+  txbxBlocks?: ReadonlyArray<BlockNode>;
   rawXml: string;
 }
 
@@ -2860,11 +2879,29 @@ function validateDocumentNode(
       return;
     case "chart_preview":
     case "smartart_preview":
-    case "shape":
     case "wordart":
     case "vml_shape":
       expectString(record.rawXml, `${path}.rawXml`, issues);
       return;
+    case "shape":
+      expectString(record.rawXml, `${path}.rawXml`, issues);
+      if (record.txbxBlocks !== undefined) {
+        if (!Array.isArray(record.txbxBlocks)) {
+          issues.push({
+            path: `${path}.txbxBlocks`,
+            message: "shape.txbxBlocks must be an array when present.",
+          });
+        } else {
+          // coord-02 §14 follow-up (2026-04-24): `ShapeNode.txbxBlocks`
+          // is canonical `BlockNode[]`. Walk it with the same validator
+          // used for top-level document content so run marks / paragraph
+          // structure / nested shapes all enforce the normal rules.
+          record.txbxBlocks.forEach((child, index) => {
+            validateDocumentNode(child, `${path}.txbxBlocks[${index}]`, issues);
+          });
+        }
+      }
+      return;
     case "drawing_frame": {
       const anchor = asPlainObject(record.anchor, `${path}.anchor`, issues);
       const content = asPlainObject(record.content, `${path}.content`, issues);

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/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;

package/src/ui-tailwind/page-stack/tw-page-chrome-entry.tsx

@@ -27,6 +27,7 @@ import { TwPageHeaderBand } from "./tw-page-header-band.tsx";
 import { TwPageFooterBand } from "./tw-page-footer-band.tsx";
 import { TwFootnoteArea } from "./tw-footnote-area.tsx";
 import type { MediaPreviewDescriptor } from "../editor-surface/pm-state-from-snapshot.ts";
+import type { TwActiveBandRibbonProps } from "./tw-active-band-ribbon.tsx";
 
 export interface TwPageChromeEntryProps {
   rect: PageOverlayRect;
@@ -40,6 +41,15 @@ export interface TwPageChromeEntryProps {
   /** Preview catalog threaded into header/footer/footnote region renderers
    *  so images (CCEP logos on 7-of-8 CCEP docs) render as real <img>s. */
   mediaPreviews?: Record<string, MediaPreviewDescriptor>;
+  /**
+   * Slice B (§6.20 reshape) — section-properties ribbon bundle forwarded
+   * to whichever band is active for this page. The bundle's `pageLayout`
+   * + `viewState` + `paragraphLayout` already reflect the active story;
+   * `kind` is set by the band itself. Pass `null` (or omit) when no
+   * header/footer is active anywhere — keeps the inactive-page memo
+   * stable across activate/deactivate cycles on a different page.
+   */
+  activeBandRibbonProps?: Omit<TwActiveBandRibbonProps, "kind" | "data-testid"> | null;
 }
 
 function TwPageChromeEntryInner({
@@ -52,6 +62,7 @@ function TwPageChromeEntryInner({
   visiblePageIndexRange,
   renderFrameRevision,
   mediaPreviews,
+  activeBandRibbonProps,
 }: TwPageChromeEntryProps): React.ReactElement {
   const layout = page.layout;
   const headerStory = page.stories.header;
@@ -192,6 +203,7 @@ function TwPageChromeEntryInner({
           sectionLabel={headerActive ? headerSectionLabel : undefined}
           onClick={handleHeaderClick}
           mediaPreviews={mediaPreviews}
+          ribbonProps={headerActive ? activeBandRibbonProps ?? null : null}
         />
       ) : null}
       {footerRegion && footerStory ? (
@@ -206,6 +218,7 @@ function TwPageChromeEntryInner({
           sectionLabel={footerActive ? footerSectionLabel : undefined}
           onClick={handleFooterClick}
           mediaPreviews={mediaPreviews}
+          ribbonProps={footerActive ? activeBandRibbonProps ?? null : null}
         />
       ) : null}
       {footnoteRegion ? (
@@ -249,7 +262,8 @@ function propsAreEqual(
     prev.rect.topPx === next.rect.topPx &&
     prev.rect.bottomPx === next.rect.bottomPx &&
     prev.rect.pageId === next.rect.pageId &&
-    prev.mediaPreviews === next.mediaPreviews
+    prev.mediaPreviews === next.mediaPreviews &&
+    prev.activeBandRibbonProps === next.activeBandRibbonProps
   );
 }
 

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

@@ -3,6 +3,10 @@ import React from "react";
 import type { SurfaceBlockSnapshot } from "../../api/public-types.ts";
 import type { MediaPreviewDescriptor } from "../editor-surface/pm-state-from-snapshot.ts";
 import { TwRegionBlockRenderer } from "./tw-region-block-renderer.tsx";
+import {
+  TwActiveBandRibbon,
+  type TwActiveBandRibbonProps,
+} from "./tw-active-band-ribbon.tsx";
 
 // ---------------------------------------------------------------------------
 // TwPageFooterBand (P8.5)
@@ -36,6 +40,12 @@ export interface TwPageFooterBandProps {
   onClick: () => void;
   "data-testid"?: string;
   mediaPreviews?: Record<string, MediaPreviewDescriptor>;
+  /**
+   * Slice B (§6.20 reshape) — section-properties ribbon that floats
+   * below the footer band when it is the active story slot. See
+   * `TwPageHeaderBandProps.ribbonProps` for shape rationale.
+   */
+  ribbonProps?: Omit<TwActiveBandRibbonProps, "kind" | "data-testid"> | null;
 }
 
 export const TwPageFooterBand: React.FC<TwPageFooterBandProps> = React.memo(({
@@ -50,6 +60,7 @@ export const TwPageFooterBand: React.FC<TwPageFooterBandProps> = React.memo(({
   onClick,
   "data-testid": testId,
   mediaPreviews,
+  ribbonProps,
 }) => {
   return (
     <div
@@ -73,6 +84,13 @@ export const TwPageFooterBand: React.FC<TwPageFooterBandProps> = React.memo(({
           {sectionLabel}
         </span>
       ) : null}
+      {isActiveSlot && ribbonProps ? (
+        <TwActiveBandRibbon
+          kind="footer"
+          {...ribbonProps}
+          data-testid={testId ? `${testId}-ribbon` : undefined}
+        />
+      ) : null}
       {isActiveSlot ? (
         <div
           data-pm-portal-slot

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

@@ -3,6 +3,10 @@ import React from "react";
 import type { SurfaceBlockSnapshot } from "../../api/public-types.ts";
 import type { MediaPreviewDescriptor } from "../editor-surface/pm-state-from-snapshot.ts";
 import { TwRegionBlockRenderer } from "./tw-region-block-renderer.tsx";
+import {
+  TwActiveBandRibbon,
+  type TwActiveBandRibbonProps,
+} from "./tw-active-band-ribbon.tsx";
 
 // ---------------------------------------------------------------------------
 // TwPageHeaderBand (P8.5)
@@ -40,6 +44,14 @@ export interface TwPageHeaderBandProps {
    *  (CCEP logos on 7-of-8 CCEP docs) render as real <img>s instead of
    *  the 48×32 placeholder chip. */
   mediaPreviews?: Record<string, MediaPreviewDescriptor>;
+  /**
+   * Slice B (§6.20 reshape) — section-properties ribbon that floats
+   * above the band when it is the active story slot. Omit (or pass
+   * `null`) to suppress the ribbon — `isActiveSlot` alone is not
+   * sufficient because some hosts mount the band in active mode without
+   * surfacing layout controls (e.g. headless / read-only previews).
+   */
+  ribbonProps?: Omit<TwActiveBandRibbonProps, "kind" | "data-testid"> | null;
 }
 
 export const TwPageHeaderBand: React.FC<TwPageHeaderBandProps> = React.memo(({
@@ -54,6 +66,7 @@ export const TwPageHeaderBand: React.FC<TwPageHeaderBandProps> = React.memo(({
   onClick,
   "data-testid": testId,
   mediaPreviews,
+  ribbonProps,
 }) => {
   return (
     <div
@@ -77,6 +90,13 @@ export const TwPageHeaderBand: React.FC<TwPageHeaderBandProps> = React.memo(({
           {sectionLabel}
         </span>
       ) : null}
+      {isActiveSlot && ribbonProps ? (
+        <TwActiveBandRibbon
+          kind="header"
+          {...ribbonProps}
+          data-testid={testId ? `${testId}-ribbon` : undefined}
+        />
+      ) : null}
       {isActiveSlot ? (
         <div
           data-pm-portal-slot

package/src/ui-tailwind/page-stack/tw-page-stack-chrome-layer.tsx

@@ -80,6 +80,7 @@ import {
 } from "../chrome-overlay/tw-page-stack-overlay-layer.tsx";
 import { TwEndnoteArea } from "./tw-endnote-area.tsx";
 import { TwPageChromeEntry } from "./tw-page-chrome-entry.tsx";
+import type { TwActiveBandRibbonProps } from "./tw-active-band-ribbon.tsx";
 
 /**
  * Minimal structural type for the PM `EditorView` handle consumed by
@@ -149,6 +150,13 @@ export interface TwPageStackChromeLayerProps {
    *  in headers/footers/footnote bodies render as real <img>s. Without
    *  this, image segments fall back to the 48×32 gray placeholder chip. */
   mediaPreviews?: Record<string, import("../editor-surface/pm-state-from-snapshot.ts").MediaPreviewDescriptor>;
+  /**
+   * Slice B (§6.20 reshape) — section-properties ribbon bundle forwarded
+   * to whichever page's active band renders it. Pass `null` (or omit)
+   * when no header/footer is active to keep memo equality stable for
+   * inactive sessions.
+   */
+  activeBandRibbonProps?: Omit<TwActiveBandRibbonProps, "kind" | "data-testid"> | null;
 }
 
 const TwPageStackChromeLayerInner: React.FC<TwPageStackChromeLayerProps> = ({
@@ -162,6 +170,7 @@ const TwPageStackChromeLayerInner: React.FC<TwPageStackChromeLayerProps> = ({
   visiblePageIndexRange,
   "data-testid": testId,
   mediaPreviews,
+  activeBandRibbonProps,
 }) => {
   const [rects, setRects] = React.useState<readonly PageOverlayRect[]>([]);
   const overlayRootRef = React.useRef<HTMLDivElement | null>(null);
@@ -407,6 +416,7 @@ const TwPageStackChromeLayerInner: React.FC<TwPageStackChromeLayerProps> = ({
             visiblePageIndexRange={visiblePageIndexRange}
             renderFrameRevision={renderFrameRevision}
             mediaPreviews={mediaPreviews}
+            activeBandRibbonProps={activeBandRibbonProps}
           />
         );
       })}

package/src/ui-tailwind/tw-review-workspace.tsx

@@ -220,12 +220,14 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
     viewState.selection.activeRange.kind === "node"
       ? viewState.selection.activeRange.at
       : viewState.selection.head;
-  // Slice A (designsystem §6.20 reshape): the legacy "Layout tools"
-  // disclosure that gated this resolver is gone. Slice B (active-band
-  // ribbon) re-enables resolution when a header/footer band is the
-  // active story; until then, no consumer reads activeParagraphLayout
-  // so the resolver stays inert.
-  const shouldResolveActiveParagraphLayout = false;
+  // Slice B (designsystem §6.20 reshape): the active-band ribbon's
+  // `TwPageRuler` reads `activeParagraphLayout` when a header or footer
+  // story is the active slot, so the resolver runs only while that ribbon
+  // is mounted.  Body-mode editing skips the resolver — no consumer reads
+  // it on the body path.
+  const shouldResolveActiveParagraphLayout =
+    snapshot.activeStory.kind === "header" ||
+    snapshot.activeStory.kind === "footer";
   const effectiveSelectionMode = props.interactionGuardSnapshot?.effectiveMode ?? "edit";
   const allowLocalChromeMutations = Boolean(caps?.canEdit) && effectiveSelectionMode === "edit";
   const {
@@ -333,6 +335,53 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
       onDismissSelectionToolbar: props.onDismissSelectionToolbar,
     });
 
+  // Slice B (designsystem §6.20 reshape) — section-properties ribbon
+  // bundle.  Built only while a header or footer band is the active
+  // story; the chrome layer forwards it to whichever band rendered the
+  // ribbon.  Document-level read-only governs the controls (the
+  // pageChromeReadOnly flag also disables on header/footer-active, which
+  // is the wrong polarity here — the ribbon's whole point is editing
+  // section properties from inside the header/footer).
+  const ribbonReadOnly =
+    snapshot.readOnly || effectiveSelectionMode !== "edit";
+  const activeBandRibbonProps = useMemo(() => {
+    if (
+      snapshot.activeStory.kind !== "header" &&
+      snapshot.activeStory.kind !== "footer"
+    ) {
+      return null;
+    }
+    if (!snapshot.pageLayout) {
+      return null;
+    }
+    return {
+      pageLayout: snapshot.pageLayout,
+      viewState,
+      paragraphLayout: activeParagraphLayout,
+      readOnly: ribbonReadOnly,
+      onCloseStory: props.onCloseStory,
+      onInsertSectionBreak: props.onInsertSectionBreak,
+      onUpdateSectionLayout: props.onUpdateSectionLayout,
+      onSetSectionPageNumbering: props.onSetSectionPageNumbering,
+      onSetHeaderFooterLink: props.onSetHeaderFooterLink,
+      onSetParagraphIndentation: props.onSetParagraphIndentation,
+      onSetParagraphTabStops: props.onSetParagraphTabStops,
+    };
+  }, [
+    snapshot.activeStory.kind,
+    snapshot.pageLayout,
+    viewState,
+    activeParagraphLayout,
+    ribbonReadOnly,
+    props.onCloseStory,
+    props.onInsertSectionBreak,
+    props.onUpdateSectionLayout,
+    props.onSetSectionPageNumbering,
+    props.onSetHeaderFooterLink,
+    props.onSetParagraphIndentation,
+    props.onSetParagraphTabStops,
+  ]);
+
   // Audit §2.4 — the shell header is ALWAYS present in default composition.
   // When the host does not supply a pre-assembled shell node, fall back to
   // a default TwShellHeader wired to the workspace's editor-role state so
@@ -1010,6 +1059,7 @@ export function TwReviewWorkspace(inputProps: TwReviewWorkspaceProps) {
                             pmSurfaceElement={pmSurfaceElement}
                             visiblePageIndexRange={visiblePageIndexRange}
                             mediaPreviews={props.mediaPreviews}
+                            activeBandRibbonProps={activeBandRibbonProps}
                           />
                         ) : null}
                       </div>