@beyondwork/docx-react-component 1.0.41 → 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/resign-payload.ts

@@ -0,0 +1,120 @@
+import {
+  signWorkflowPayloadXml,
+  type PayloadSignature,
+  type PayloadSigner,
+} from "../io/ooxml/payload-signature.ts";
+
+/**
+ * Central re-sign hook. Every payload mutation — negotiation action,
+ * presentation edit, participant upsert, external-custody attach, and
+ * (in the P17 parallel lane) metadata-persistence toggle — MUST route
+ * through this helper before writing back to the docx. This keeps the
+ * tamper-evident invariant un-bypassable: no feature can silently
+ * mutate `bw:workflowPayload` without re-signing.
+ *
+ * The helper is intentionally thin — it does two jobs:
+ *   1. Replace (or append, if absent) the root `<bw:signature …/>`
+ *      element inside the provided payload XML with a new signature
+ *      over the canonicalized (bw-canon/1) form of the payload minus
+ *      the signature itself.
+ *   2. Return the rewritten XML so the caller can persist it.
+ *
+ * The canonicalizer already excludes `bw:signature` from its hashing
+ * surface; this helper reuses that guarantee instead of reimplementing
+ * it.
+ */
+export interface ResignPayloadArgs {
+  /** The full `<bw:workflowPayload …>…</bw:workflowPayload>` XML. */
+  payloadXml: string;
+  signer: PayloadSigner;
+  /** Optional clock override for deterministic tests. */
+  now?: string;
+}
+
+export interface ResignPayloadResult {
+  payloadXml: string;
+  signature: PayloadSignature;
+}
+
+export async function resignPayload(
+  args: ResignPayloadArgs,
+): Promise<ResignPayloadResult> {
+  const stripped = removeExistingSignature(args.payloadXml);
+  const signature = await signWorkflowPayloadXml(stripped, args.signer, args.now);
+  const signatureElement = renderSignatureElement(signature);
+  const payloadXml = insertSignatureBeforeClose(stripped, signatureElement);
+  return { payloadXml, signature };
+}
+
+const SIGNATURE_OPEN = /<(?:[A-Za-z_][\w-]*:)?signature\b/;
+const CLOSE_ROOT = /<\/(?:[A-Za-z_][\w-]*:)?workflowPayload\s*>\s*$/;
+
+function removeExistingSignature(xml: string): string {
+  // The canonicalizer drops bw:signature before hashing, but the stored
+  // XML keeps it. For a round-trippable rewrite we strip every
+  // self-closing or block-form signature element at the top level. We
+  // do this with a tolerant regex instead of a full parse because the
+  // host may have normalized the XML (whitespace / attr order) between
+  // writes; we just need to locate the element's extent.
+  let out = xml;
+  while (true) {
+    const match = SIGNATURE_OPEN.exec(out);
+    if (!match) break;
+    const start = match.index;
+    const rest = out.slice(start);
+    // Self-closing form: `<…signature …/>`
+    const selfClose = rest.match(/^<[^>]*?\/>/);
+    if (selfClose) {
+      out = out.slice(0, start) + out.slice(start + selfClose[0].length);
+      continue;
+    }
+    // Block form: `<…signature …>…</…signature>`
+    const openEnd = rest.indexOf(">");
+    if (openEnd < 0) break;
+    const tagName = match[0].slice(1); // drops leading <
+    const closeTag = new RegExp(`</${escapeRegex(tagName)}\\s*>`);
+    const closeMatch = closeTag.exec(rest);
+    if (!closeMatch) break;
+    const end = closeMatch.index + closeMatch[0].length;
+    out = out.slice(0, start) + out.slice(start + end);
+  }
+  return out;
+}
+
+function insertSignatureBeforeClose(xml: string, signatureElement: string): string {
+  const match = CLOSE_ROOT.exec(xml);
+  if (!match) {
+    throw new Error(
+      "resignPayload: could not locate </bw:workflowPayload> close tag",
+    );
+  }
+  const insertAt = match.index;
+  return (
+    xml.slice(0, insertAt) +
+    signatureElement +
+    xml.slice(insertAt)
+  );
+}
+
+function renderSignatureElement(sig: PayloadSignature): string {
+  return (
+    `<bw:signature` +
+    ` algorithm="${escapeAttr(sig.algorithm)}"` +
+    ` keyId="${escapeAttr(sig.keyId)}"` +
+    ` signedAt="${escapeAttr(sig.signedAt)}"` +
+    ` canonicalizationProfile="${escapeAttr(sig.canonicalizationProfile)}"` +
+    ` value="${escapeAttr(sig.value)}"/>`
+  );
+}
+
+function escapeAttr(v: string): string {
+  return v
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

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/tamper-gate.ts

@@ -0,0 +1,157 @@
+import {
+  verifyWorkflowPayloadXml,
+  type PayloadSignature,
+  type PayloadVerifier,
+} from "../io/ooxml/payload-signature.ts";
+
+/**
+ * Runtime metadata-integrity states.
+ *
+ * - `unsigned`   — payload has no `bw:signature`, treated as trust-on-
+ *                  first-use. Callers may mutate freely; the first
+ *                  mutation will re-sign and transition to `verified`.
+ * - `verified`   — signature present and valid against the registered
+ *                  verifier. Mutations are allowed through the gate.
+ * - `tampered`   — signature present but verification failed. All
+ *                  mutations are blocked with `metadata_tampered` until
+ *                  the user calls `acknowledge()`.
+ */
+export type MetadataIntegrity = "unsigned" | "verified" | "tampered";
+
+export type TamperGateEvent =
+  | { type: "integrity_changed"; state: MetadataIntegrity }
+  | { type: "metadata_integrity_violation" };
+
+export interface TamperGateArgs {
+  /**
+   * Verifier used on attach. Matches the signer the host writes the
+   * payload with. Omit to skip verification (payload is treated as
+   * unsigned).
+   */
+  verifier?: PayloadVerifier;
+}
+
+export interface AttachArgs {
+  payloadXml: string;
+  signature: PayloadSignature | undefined;
+}
+
+export type GuardResult =
+  | { ok: true }
+  | { ok: false; reason: "metadata_tampered" };
+
+export interface TamperGate {
+  readonly state: MetadataIntegrity;
+  /**
+   * Verifies the signature against the supplied payload XML and
+   * transitions the gate state. Idempotent — safe to call every
+   * time a new payload is attached.
+   */
+  attach(args: AttachArgs): Promise<MetadataIntegrity>;
+  /**
+   * Resets the gate to `unsigned`. Useful when the underlying
+   * payload is detached (host switched documents).
+   */
+  detach(): void;
+  /**
+   * Single chokepoint every mutation path consults before writing
+   * back to the payload. Returns `{ ok: false, reason: "metadata_tampered" }`
+   * when the gate is in `tampered` state and the user has not
+   * acknowledged. Returns `{ ok: true }` otherwise.
+   */
+  guard(): GuardResult;
+  /**
+   * Flips `tampered` → `verified`. Only effective when the current
+   * state is `tampered`; other states are left untouched.
+   */
+  acknowledge(): void;
+  /**
+   * Re-enters `tampered` — e.g. when a host writes a payload and the
+   * re-sign check disagrees with the stored signature. Primarily for
+   * test fixtures and future composition slices.
+   */
+  flagTampered(): void;
+  subscribe(listener: (event: TamperGateEvent) => void): () => void;
+  destroy(): void;
+}
+
+export function createTamperGate(args: TamperGateArgs = {}): TamperGate {
+  let state: MetadataIntegrity = "unsigned";
+  let hasEmittedViolation = false;
+  const listeners = new Set<(event: TamperGateEvent) => void>();
+
+  const emit = (event: TamperGateEvent): void => {
+    for (const fn of [...listeners]) fn(event);
+  };
+
+  const setState = (next: MetadataIntegrity): void => {
+    if (next === state) return;
+    state = next;
+    emit({ type: "integrity_changed", state: next });
+    if (next === "tampered" && !hasEmittedViolation) {
+      hasEmittedViolation = true;
+      emit({ type: "metadata_integrity_violation" });
+    }
+    if (next !== "tampered") {
+      // Re-arm the violation emitter so a subsequent tamper transition
+      // re-notifies the host. Matches the "once per open on tamper"
+      // requirement, where "open" is bracketed by acknowledge().
+      hasEmittedViolation = false;
+    }
+  };
+
+  return {
+    get state() {
+      return state;
+    },
+
+    async attach({ payloadXml, signature }) {
+      if (!signature) {
+        setState("unsigned");
+        return state;
+      }
+      if (!args.verifier) {
+        setState("unsigned");
+        return state;
+      }
+      const ok = await verifyWorkflowPayloadXml(
+        payloadXml,
+        signature,
+        args.verifier,
+      );
+      setState(ok ? "verified" : "tampered");
+      return state;
+    },
+
+    detach() {
+      setState("unsigned");
+    },
+
+    guard() {
+      if (state === "tampered") {
+        return { ok: false, reason: "metadata_tampered" };
+      }
+      return { ok: true };
+    },
+
+    acknowledge() {
+      if (state !== "tampered") return;
+      setState("verified");
+    },
+
+    flagTampered() {
+      setState("tampered");
+    },
+
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+
+    destroy() {
+      listeners.clear();
+    },
+  };
+}