@beyondwork/docx-react-component 1.0.42 → 1.0.43

package/src/ui-tailwind/editor-surface/tw-page-block-view.helpers.ts

@@ -0,0 +1,265 @@
+import type React from "react";
+
+import type {
+  SurfaceBlockSnapshot,
+  SurfaceTextMark,
+} from "../../api/public-types.ts";
+import type { CanonicalRunFormatting } from "../../model/canonical-document.ts";
+
+// ---------------------------------------------------------------------------
+// Pure helpers shared by `tw-page-block-view` (body) and `tw-region-block-
+// renderer` (header / footer / footnote / endnote bands).  Extracted in P8.4
+// so per-page regions reuse body typography verbatim — indent/margin/line-
+// height/marker geometry stay identical across all regions.
+// ---------------------------------------------------------------------------
+
+export const HEX_COLOR_RE = /^[0-9A-Fa-f]{3,8}$/;
+export const SAFE_FONT_RE = /^[A-Za-z0-9 ,\-'"]+$/;
+export const SAFE_ALIGNMENT = new Set([
+  "left",
+  "center",
+  "right",
+  "justify",
+  "start",
+  "end",
+]);
+
+export function safeHexColor(raw: string | null | undefined): string | null {
+  if (!raw || raw === "auto") return null;
+  return HEX_COLOR_RE.test(raw) ? `#${raw}` : null;
+}
+
+/** Resolve heading level from styleId or outlineLevel (outlineLevel 0 = Heading 1). */
+export function resolveHeadingLevel(
+  styleId?: string,
+  outlineLevel?: number,
+): number | null {
+  if (styleId) {
+    const normalized = styleId.toLowerCase();
+    const compact = normalized.replace(/[\s_-]+/g, "");
+    const headingMatch = /^heading([1-6])$/.exec(compact);
+    if (headingMatch) {
+      return Number.parseInt(headingMatch[1], 10);
+    }
+    if (compact === "title") return 1;
+    if (compact === "subtitle") return 2;
+    if (compact === "tocheading") return 1;
+    if (/^(appendix|schedule|annex|exhibit|attachment)(heading|title)$/.test(compact)) return 2;
+  }
+  if (
+    typeof outlineLevel === "number" &&
+    Number.isInteger(outlineLevel) &&
+    outlineLevel >= 0 &&
+    outlineLevel <= 5
+  ) {
+    return outlineLevel + 1;
+  }
+  return null;
+}
+
+export function resolveMarkerJustificationCss(raw: string | undefined): string {
+  switch (raw) {
+    case "left":
+      return "flex-start";
+    case "center":
+      return "center";
+    case "right":
+    case "both":
+    case "distribute":
+    default:
+      return "flex-end";
+  }
+}
+
+/** Build CSSProperties for a paragraph block from spacing/indent/alignment. */
+export function buildParagraphStyle(
+  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+): React.CSSProperties {
+  const style: React.CSSProperties = {};
+
+  // Alignment — direct takes precedence over resolvedParagraphFormatting
+  const rawAlignment = block.alignment ?? block.resolvedParagraphFormatting?.alignment;
+  const safeAlign = rawAlignment === "both" ? "justify" : rawAlignment;
+  if (safeAlign && SAFE_ALIGNMENT.has(safeAlign)) {
+    style.textAlign = safeAlign as React.CSSProperties["textAlign"];
+  }
+
+  // Spacing
+  const spacingBefore =
+    block.spacing?.before ?? block.resolvedParagraphFormatting?.spacing?.before;
+  const spacingAfter =
+    block.spacing?.after ?? block.resolvedParagraphFormatting?.spacing?.after;
+  const lineSpacing =
+    block.spacing?.line ?? block.resolvedParagraphFormatting?.spacing?.line;
+  const lineRule =
+    block.spacing?.lineRule ?? block.resolvedParagraphFormatting?.spacing?.lineRule;
+
+  if (spacingBefore != null) {
+    style.marginTop = `${spacingBefore / 20}pt`;
+  }
+  if (spacingAfter != null) {
+    style.marginBottom = `${spacingAfter / 20}pt`;
+  }
+  if (lineSpacing && lineRule === "auto") {
+    style.lineHeight = String(lineSpacing / 240);
+  } else if (lineSpacing && lineRule === "exact") {
+    style.lineHeight = `${lineSpacing / 20}pt`;
+  } else if (lineSpacing && lineRule === "atLeast") {
+    style.minHeight = `${lineSpacing / 20}pt`;
+  }
+
+  // Indentation
+  const indentLeft =
+    block.indentation?.left ?? block.resolvedParagraphFormatting?.indentation?.left;
+  const indentRight =
+    block.indentation?.right ?? block.resolvedParagraphFormatting?.indentation?.right;
+  const indentFirstLine =
+    block.indentation?.firstLine ?? block.resolvedParagraphFormatting?.indentation?.firstLine;
+  const indentHanging =
+    block.indentation?.hanging ?? block.resolvedParagraphFormatting?.indentation?.hanging;
+
+  if (indentLeft) style.paddingLeft = `${indentLeft / 20}pt`;
+  if (indentRight) style.paddingRight = `${indentRight / 20}pt`;
+  if (indentHanging) style.textIndent = `-${indentHanging / 20}pt`;
+  else if (indentFirstLine) style.textIndent = `${indentFirstLine / 20}pt`;
+
+  // Shading
+  const shadingFill = block.shading?.fill;
+  const shadingColor = safeHexColor(shadingFill);
+  if (shadingColor) style.backgroundColor = shadingColor;
+
+  // Page break visual indicator
+  if (block.pageBreakBefore) {
+    style.borderTop = "2px dashed rgba(0,0,0,0.1)";
+    style.paddingTop = "8px";
+    style.marginTop = "16px";
+  }
+
+  return style;
+}
+
+/** Build CSSProperties for the numbering marker span. */
+export function buildMarkerStyle(
+  prefix: string,
+  suffix: "tab" | "space" | "nothing" | undefined,
+  markerRunProperties: CanonicalRunFormatting | undefined,
+  markerWidth: number | undefined,
+  markerJustification: string | undefined,
+): React.CSSProperties {
+  const style: React.CSSProperties = {
+    fontVariantNumeric: "tabular-nums",
+    justifyContent: resolveMarkerJustificationCss(markerJustification),
+  };
+
+  if (markerRunProperties) {
+    if (markerRunProperties.bold) style.fontWeight = "bold";
+    if (markerRunProperties.italic) style.fontStyle = "italic";
+    if (markerRunProperties.underline && markerRunProperties.underline !== "none") {
+      style.textDecoration = "underline";
+    }
+    if (typeof markerRunProperties.fontSizeHalfPoints === "number") {
+      style.fontSize = `${markerRunProperties.fontSizeHalfPoints / 2}pt`;
+    }
+    const colorHex = markerRunProperties.colorHex;
+    if (colorHex && colorHex !== "auto") {
+      style.color = `#${colorHex.toLowerCase()}`;
+    }
+    const family = markerRunProperties.fontFamilyAscii ?? markerRunProperties.fontFamily;
+    if (family && SAFE_FONT_RE.test(family)) {
+      style.fontFamily = family;
+    }
+  } else {
+    style.color = "var(--color-text-tertiary)";
+    style.fontFamily = "var(--font-legal-sans)";
+  }
+
+  const hasResolvedMarkerWidth = typeof markerWidth === "number" && markerWidth > 0;
+  if (hasResolvedMarkerWidth) {
+    // P13.a: emit marker geometry in pt so it self-scales under CSS `zoom`.
+    const markerWidthPt = Math.max(1, markerWidth! / 20);
+    style.width = `${markerWidthPt}pt`;
+    style.minWidth = `${markerWidthPt}pt`;
+    style.flexBasis = `${markerWidthPt}pt`;
+    style.marginRight = 0;
+    style.overflow = "visible";
+  } else {
+    const fallbackMinWidth = Math.min(Math.max(prefix.length + 1, 4), 14);
+    const fallbackMarginRight =
+      suffix === "nothing" ? "0.25rem" : suffix === "space" ? "0.5rem" : "0.75rem";
+    style.minWidth = `${fallbackMinWidth}ch`;
+    style.marginRight = fallbackMarginRight;
+  }
+
+  return style;
+}
+
+/** Build CSSProperties for a text segment from marks and markAttrs. */
+export function buildSegmentStyle(
+  marks: SurfaceTextMark[] | undefined,
+  markAttrs?: {
+    fontSize?: number;
+    textColor?: string;
+    fontFamily?: string;
+    backgroundColor?: string;
+    charSpacing?: number;
+  },
+): React.CSSProperties {
+  const style: React.CSSProperties = {};
+
+  if (marks) {
+    if (marks.includes("bold")) style.fontWeight = "bold";
+    if (marks.includes("italic")) style.fontStyle = "italic";
+    if (marks.includes("underline")) style.textDecoration = "underline";
+    if (marks.includes("strikethrough") || marks.includes("doubleStrikethrough")) {
+      style.textDecoration = marks.includes("underline")
+        ? "underline line-through"
+        : "line-through";
+    }
+    if (marks.includes("superscript")) {
+      style.verticalAlign = "super";
+      style.fontSize = "smaller";
+    }
+    if (marks.includes("subscript")) {
+      style.verticalAlign = "sub";
+      style.fontSize = "smaller";
+    }
+    if (marks.includes("allCaps")) style.textTransform = "uppercase";
+    if (marks.includes("smallCaps")) style.fontVariant = "small-caps";
+    if (marks.includes("vanish")) style.display = "none";
+  }
+
+  if (markAttrs) {
+    if (markAttrs.fontSize) style.fontSize = `${markAttrs.fontSize}pt`;
+    if (markAttrs.textColor) style.color = markAttrs.textColor;
+    if (markAttrs.fontFamily && SAFE_FONT_RE.test(markAttrs.fontFamily)) {
+      style.fontFamily = markAttrs.fontFamily;
+    }
+    if (markAttrs.backgroundColor) style.backgroundColor = markAttrs.backgroundColor;
+    if (markAttrs.charSpacing) style.letterSpacing = `${markAttrs.charSpacing}px`;
+  }
+
+  return style;
+}
+
+export function hasStyleEntries(style: React.CSSProperties): boolean {
+  return Object.keys(style).length > 0;
+}
+
+export function headingClassList(level: number): string[] {
+  switch (level) {
+    case 1:
+      return ["text-3xl", "font-semibold", "tracking-tight", "leading-tight"];
+    case 2:
+      return ["text-2xl", "font-semibold", "tracking-tight"];
+    case 3:
+      return ["text-xl", "font-medium"];
+    case 4:
+      return ["text-lg", "font-medium"];
+    case 5:
+      return ["text-base", "font-semibold", "uppercase", "tracking-[0.12em]"];
+    case 6:
+      return ["text-sm", "font-semibold", "uppercase", "tracking-[0.16em]"];
+    default:
+      return [];
+  }
+}

package/src/ui-tailwind/editor-surface/tw-page-block-view.tsx

@@ -3,243 +3,15 @@ import React from "react";
 import type {
   SurfaceBlockSnapshot,
   SurfaceInlineSegment,
-  SurfaceTextMark,
 } from "../../api/public-types.ts";
-import type { CanonicalRunFormatting } from "../../model/canonical-document.ts";
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-const HEX_COLOR_RE = /^[0-9A-Fa-f]{3,8}$/;
-const SAFE_FONT_RE = /^[A-Za-z0-9 ,\-'"]+$/;
-const SAFE_ALIGNMENT = new Set(["left", "center", "right", "justify", "start", "end"]);
-
-// ---------------------------------------------------------------------------
-// Helper utilities (mirror pm-schema.ts helpers)
-// ---------------------------------------------------------------------------
-
-function safeHexColor(raw: string | null | undefined): string | null {
-  if (!raw || raw === "auto") return null;
-  return HEX_COLOR_RE.test(raw) ? `#${raw}` : null;
-}
-
-/** Resolve heading level from styleId or outlineLevel (outlineLevel 0 = Heading 1). */
-function resolveHeadingLevel(styleId?: string, outlineLevel?: number): number | null {
-  if (styleId) {
-    const normalized = styleId.toLowerCase();
-    const compact = normalized.replace(/[\s_-]+/g, "");
-    const headingMatch = /^heading([1-6])$/.exec(compact);
-    if (headingMatch) {
-      return Number.parseInt(headingMatch[1], 10);
-    }
-    if (compact === "title") return 1;
-    if (compact === "subtitle") return 2;
-    if (compact === "tocheading") return 1;
-    if (/^(appendix|schedule|annex|exhibit|attachment)(heading|title)$/.test(compact)) return 2;
-  }
-  if (
-    typeof outlineLevel === "number" &&
-    Number.isInteger(outlineLevel) &&
-    outlineLevel >= 0 &&
-    outlineLevel <= 5
-  ) {
-    return outlineLevel + 1;
-  }
-  return null;
-}
-
-function resolveMarkerJustificationCss(raw: string | undefined): string {
-  switch (raw) {
-    case "left":
-      return "flex-start";
-    case "center":
-      return "center";
-    case "right":
-    case "both":
-    case "distribute":
-    default:
-      return "flex-end";
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Style builders
-// ---------------------------------------------------------------------------
-
-/** Build CSSProperties for a paragraph block from spacing/indent/alignment. */
-function buildParagraphStyle(
-  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
-): React.CSSProperties {
-  const style: React.CSSProperties = {};
-
-  // Alignment — direct takes precedence over resolvedParagraphFormatting
-  const rawAlignment = block.alignment ?? block.resolvedParagraphFormatting?.alignment;
-  const safeAlign = rawAlignment === "both" ? "justify" : rawAlignment;
-  if (safeAlign && SAFE_ALIGNMENT.has(safeAlign)) {
-    style.textAlign = safeAlign as React.CSSProperties["textAlign"];
-  }
-
-  // Spacing
-  const spacingBefore =
-    block.spacing?.before ?? block.resolvedParagraphFormatting?.spacing?.before;
-  const spacingAfter =
-    block.spacing?.after ?? block.resolvedParagraphFormatting?.spacing?.after;
-  const lineSpacing =
-    block.spacing?.line ?? block.resolvedParagraphFormatting?.spacing?.line;
-  const lineRule =
-    block.spacing?.lineRule ?? block.resolvedParagraphFormatting?.spacing?.lineRule;
-
-  if (spacingBefore != null) {
-    style.marginTop = `${spacingBefore / 20}pt`;
-  }
-  if (spacingAfter != null) {
-    style.marginBottom = `${spacingAfter / 20}pt`;
-  }
-  if (lineSpacing && lineRule === "auto") {
-    style.lineHeight = String(lineSpacing / 240);
-  } else if (lineSpacing && lineRule === "exact") {
-    style.lineHeight = `${lineSpacing / 20}pt`;
-  } else if (lineSpacing && lineRule === "atLeast") {
-    style.minHeight = `${lineSpacing / 20}pt`;
-  }
-
-  // Indentation
-  const indentLeft =
-    block.indentation?.left ?? block.resolvedParagraphFormatting?.indentation?.left;
-  const indentRight =
-    block.indentation?.right ?? block.resolvedParagraphFormatting?.indentation?.right;
-  const indentFirstLine =
-    block.indentation?.firstLine ?? block.resolvedParagraphFormatting?.indentation?.firstLine;
-  const indentHanging =
-    block.indentation?.hanging ?? block.resolvedParagraphFormatting?.indentation?.hanging;
-
-  if (indentLeft) style.paddingLeft = `${indentLeft / 20}pt`;
-  if (indentRight) style.paddingRight = `${indentRight / 20}pt`;
-  if (indentHanging) style.textIndent = `-${indentHanging / 20}pt`;
-  else if (indentFirstLine) style.textIndent = `${indentFirstLine / 20}pt`;
-
-  // Shading
-  const shadingFill = block.shading?.fill;
-  const shadingColor = safeHexColor(shadingFill);
-  if (shadingColor) style.backgroundColor = shadingColor;
-
-  // Page break visual indicator
-  if (block.pageBreakBefore) {
-    style.borderTop = "2px dashed rgba(0,0,0,0.1)";
-    style.paddingTop = "8px";
-    style.marginTop = "16px";
-  }
-
-  return style;
-}
-
-/** Build CSSProperties for the numbering marker span. */
-function buildMarkerStyle(
-  prefix: string,
-  suffix: "tab" | "space" | "nothing" | undefined,
-  markerRunProperties: CanonicalRunFormatting | undefined,
-  markerWidth: number | undefined,
-  markerJustification: string | undefined,
-): React.CSSProperties {
-  const style: React.CSSProperties = {
-    fontVariantNumeric: "tabular-nums",
-    justifyContent: resolveMarkerJustificationCss(markerJustification),
-  };
-
-  if (markerRunProperties) {
-    if (markerRunProperties.bold) style.fontWeight = "bold";
-    if (markerRunProperties.italic) style.fontStyle = "italic";
-    if (markerRunProperties.underline && markerRunProperties.underline !== "none") {
-      style.textDecoration = "underline";
-    }
-    if (typeof markerRunProperties.fontSizeHalfPoints === "number") {
-      style.fontSize = `${markerRunProperties.fontSizeHalfPoints / 2}pt`;
-    }
-    const colorHex = markerRunProperties.colorHex;
-    if (colorHex && colorHex !== "auto") {
-      style.color = `#${colorHex.toLowerCase()}`;
-    }
-    const family = markerRunProperties.fontFamilyAscii ?? markerRunProperties.fontFamily;
-    if (family && SAFE_FONT_RE.test(family)) {
-      style.fontFamily = family;
-    }
-  } else {
-    style.color = "var(--color-text-tertiary)";
-    style.fontFamily = "var(--font-legal-sans)";
-  }
-
-  const hasResolvedMarkerWidth = typeof markerWidth === "number" && markerWidth > 0;
-  if (hasResolvedMarkerWidth) {
-    // P13.a: emit marker geometry in pt so it self-scales under CSS `zoom`.
-    const markerWidthPt = Math.max(1, markerWidth! / 20);
-    style.width = `${markerWidthPt}pt`;
-    style.minWidth = `${markerWidthPt}pt`;
-    style.flexBasis = `${markerWidthPt}pt`;
-    style.marginRight = 0;
-    style.overflow = "visible";
-  } else {
-    const fallbackMinWidth = Math.min(Math.max(prefix.length + 1, 4), 14);
-    const fallbackMarginRight =
-      suffix === "nothing" ? "0.25rem" : suffix === "space" ? "0.5rem" : "0.75rem";
-    style.minWidth = `${fallbackMinWidth}ch`;
-    style.marginRight = fallbackMarginRight;
-  }
-
-  return style;
-}
-
-/** Build CSSProperties for a text segment from marks and markAttrs. */
-function buildSegmentStyle(
-  marks: SurfaceTextMark[] | undefined,
-  markAttrs?: {
-    fontSize?: number;
-    textColor?: string;
-    fontFamily?: string;
-    backgroundColor?: string;
-    charSpacing?: number;
-  },
-): React.CSSProperties {
-  const style: React.CSSProperties = {};
-
-  if (marks) {
-    if (marks.includes("bold")) style.fontWeight = "bold";
-    if (marks.includes("italic")) style.fontStyle = "italic";
-    if (marks.includes("underline")) style.textDecoration = "underline";
-    if (marks.includes("strikethrough") || marks.includes("doubleStrikethrough")) {
-      style.textDecoration = marks.includes("underline")
-        ? "underline line-through"
-        : "line-through";
-    }
-    if (marks.includes("superscript")) {
-      style.verticalAlign = "super";
-      style.fontSize = "smaller";
-    }
-    if (marks.includes("subscript")) {
-      style.verticalAlign = "sub";
-      style.fontSize = "smaller";
-    }
-    if (marks.includes("allCaps")) style.textTransform = "uppercase";
-    if (marks.includes("smallCaps")) style.fontVariant = "small-caps";
-    if (marks.includes("vanish")) style.display = "none";
-  }
-
-  if (markAttrs) {
-    if (markAttrs.fontSize) style.fontSize = `${markAttrs.fontSize}pt`;
-    if (markAttrs.textColor) style.color = markAttrs.textColor;
-    if (markAttrs.fontFamily && SAFE_FONT_RE.test(markAttrs.fontFamily)) {
-      style.fontFamily = markAttrs.fontFamily;
-    }
-    if (markAttrs.backgroundColor) style.backgroundColor = markAttrs.backgroundColor;
-    if (markAttrs.charSpacing) style.letterSpacing = `${markAttrs.charSpacing}px`;
-  }
-
-  return style;
-}
-
-function hasStyleEntries(style: React.CSSProperties): boolean {
-  return Object.keys(style).length > 0;
-}
+import {
+  buildMarkerStyle,
+  buildParagraphStyle,
+  buildSegmentStyle,
+  hasStyleEntries,
+  headingClassList,
+  resolveHeadingLevel,
+} from "./tw-page-block-view.helpers.ts";
 
 // ---------------------------------------------------------------------------
 // Segment renderer
@@ -409,25 +181,6 @@ function ParagraphBlock({
   );
 }
 
-function headingClassList(level: number): string[] {
-  switch (level) {
-    case 1:
-      return ["text-3xl", "font-semibold", "tracking-tight", "leading-tight"];
-    case 2:
-      return ["text-2xl", "font-semibold", "tracking-tight"];
-    case 3:
-      return ["text-xl", "font-medium"];
-    case 4:
-      return ["text-lg", "font-medium"];
-    case 5:
-      return ["text-base", "font-semibold", "uppercase", "tracking-[0.12em]"];
-    case 6:
-      return ["text-sm", "font-semibold", "uppercase", "tracking-[0.16em]"];
-    default:
-      return [];
-  }
-}
-
 /** Render a table block as <table>. */
 function TableBlock({
   block,

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

@@ -188,6 +188,11 @@ export interface TwProseMirrorSurfaceProps {
   onUndo?: () => void;
   onRedo?: () => void;
   onBlockedInput?: (command: "paste" | "drop", message: string) => void;
+  onPasteApplied?: (meta: {
+    segmentCount: number;
+    charCount: number;
+    source: "paste" | "drop";
+  }) => void;
   onCommentActivated?: (commentId: string) => void;
   onRevisionActivated?: (revisionId: string) => void;
   onSelectionToolbarAnchorChange?: (anchor: SelectionToolbarAnchor | null) => void;
@@ -321,6 +326,9 @@ export const TwProseMirrorSurface = forwardRef<
     onBlockedInput: (command, message) => {
       props.onBlockedInput?.(command, message);
     },
+    onPasteApplied: (meta) => {
+      props.onPasteApplied?.(meta);
+    },
     onSelectionChange: (sel) => {
       pendingSelectionProbeRef.current = startPerfProbe("selection");
       props.onSelectionChange?.(
@@ -448,6 +456,7 @@ export const TwProseMirrorSurface = forwardRef<
       onUndo: () => callbacksRef.current?.onUndo(),
       onRedo: () => callbacksRef.current?.onRedo(),
       onBlockedInput: (command, message) => callbacksRef.current?.onBlockedInput?.(command, message),
+      onPasteApplied: (meta) => callbacksRef.current?.onPasteApplied?.(meta),
       onCompositionChange: (composing) => {
         sessionRef.current?.setComposing(composing);
       },

package/src/ui-tailwind/index.ts

@@ -11,7 +11,11 @@ export { renderTwCaret } from "./editor-surface/tw-caret";
 
 // Review rail
 export { TwReviewRail, type TwReviewRailProps, type ReviewRailTab } from "./review/tw-review-rail";
-export { TwCommentSidebar } from "./review/tw-comment-sidebar";
+export { TwCommentSidebar, type TwCommentSidebarProps } from "./review/tw-comment-sidebar";
+export {
+  CommentMarkdownRenderer,
+  type CommentMarkdownRendererProps,
+} from "./review/comment-markdown-renderer";
 export { TwRevisionSidebar } from "./review/tw-revision-sidebar";
 export { TwHealthPanel } from "./review/tw-health-panel";
 export { TwWorkflowTab, type TwWorkflowTabProps } from "./review/tw-workflow-tab";

package/src/ui-tailwind/page-stack/tw-endnote-area.tsx

@@ -0,0 +1,57 @@
+import React from "react";
+
+import type { SurfaceBlockSnapshot } from "../../api/public-types.ts";
+import { TwRegionBlockRenderer } from "./tw-region-block-renderer.tsx";
+
+// ---------------------------------------------------------------------------
+// TwEndnoteArea (P8.7)
+//
+// Read-only area for document-end endnote placement.  Unlike footnotes, which
+// the chrome layer positions per-page via an absolute rectangle, endnotes in
+// the default mode sit at the end of the document (Word's `w:pos="docEnd"`
+// behavior).  This component is mounted as a sibling of the chrome layer
+// after the last page rect — not as an absolutely positioned chrome overlay.
+//
+// It renders:
+//   1. A default 1px separator (1/3 of the parent width) along the top edge,
+//      and
+//   2. The ordered endnote bodies via `TwRegionBlockRenderer` (P8.4).
+//
+// When `blocks` is empty the component returns `null` so the document-end
+// slot stays visually absent.
+//
+// Per-section endnote placement (`w:endnotePr/w:pos` other than `docEnd`)
+// is a follow-up — tracked with the P8.b polish pass.
+// ---------------------------------------------------------------------------
+
+export interface TwEndnoteAreaProps {
+  blocks: readonly SurfaceBlockSnapshot[];
+  "data-testid"?: string;
+}
+
+export const TwEndnoteArea: React.FC<TwEndnoteAreaProps> = ({
+  blocks,
+  "data-testid": testId,
+}) => {
+  if (blocks.length === 0) return null;
+  return (
+    <div
+      data-endnote-area
+      data-testid={testId}
+      style={{ marginTop: "24pt" }}
+    >
+      <div
+        data-endnote-separator
+        style={{
+          width: "33%",
+          height: "1px",
+          backgroundColor: "currentColor",
+          marginBottom: "8pt",
+        }}
+      />
+      <TwRegionBlockRenderer blocks={blocks} />
+    </div>
+  );
+};
+
+export default TwEndnoteArea;