@beyondwork/docx-react-component 1.0.109 → 1.0.111

package/src/runtime/scopes/semantic-scope-types.ts

@@ -289,6 +289,12 @@ export interface ScopeBundleEvidence {
    * `requires-rehydration` or `unavailable`; Layer 08 never fabricates rects.
    */
   readonly geometry?: ScopeGeometryEvidence;
+  /**
+   * Bounded Layer-05 adjacent geometry evidence. This is compositor/read
+   * evidence only; it does not make a scope replaceable. Rows are present only
+   * when L05 marked them `compositorReady` in `frame-px` space.
+   */
+  readonly adjacentGeometry?: ScopeAdjacentGeometryEvidence;
   /**
    * Presentation hint only. Consumers may use this to choose a cheap inline
    * treatment for field-like scopes versus a broader overlay treatment for
@@ -449,6 +455,67 @@ export interface ScopeGeometryEvidence {
   };
 }
 
+export type ScopeAdjacentGeometryAxis = "numbering-marker" | "field-region";
+
+export interface ScopeAdjacentGeometryFramePixelRect {
+  readonly leftPx: number;
+  readonly topPx: number;
+  readonly widthPx: number;
+  readonly heightPx: number;
+  readonly coordinateSpace: "frame-px";
+}
+
+export interface ScopeAdjacentGeometryFramePixelPoint {
+  readonly xPx: number;
+  readonly yPx: number;
+  readonly coordinateSpace: "frame-px";
+}
+
+export interface ScopeAdjacentGeometryRowEvidence {
+  readonly axis: ScopeAdjacentGeometryAxis;
+  readonly source: "l05-adjacent-geometry-intake";
+  readonly docId?: string;
+  readonly canonicalBlockId?: string;
+  readonly runtimeFragmentId?: string;
+  readonly pageId?: string;
+  readonly pageIndex?: number;
+  readonly frameId?: string;
+  readonly precision: "word-page-local-calibration";
+  readonly coordinateSpace: "frame-px";
+  readonly compositorReady: true;
+  readonly scaleSource?: "runtime-render-frame-page-rect";
+  readonly renderFrameRevision?: number;
+  readonly numbering?: {
+    readonly runtimeNumberingId?: string;
+    readonly canonicalNumberingInstanceId?: string;
+    readonly canonicalLevel?: number;
+    readonly markerKind?: string;
+    readonly markerSuffix?: string;
+    readonly markerLane?: ScopeAdjacentGeometryFramePixelRect;
+    readonly textColumn?: ScopeAdjacentGeometryFramePixelRect;
+  };
+  readonly fieldRegion?: {
+    readonly canonicalFieldId?: string;
+    readonly runtimeFieldRegionId?: string;
+    readonly instructionFamily?: string;
+    readonly fieldStartAnchorPx?: ScopeAdjacentGeometryFramePixelPoint;
+    readonly fieldEndAnchorPx?: ScopeAdjacentGeometryFramePixelPoint;
+    readonly fieldResultRangePx?: ScopeAdjacentGeometryFramePixelRect;
+  };
+}
+
+export interface ScopeAdjacentGeometryEvidence {
+  readonly status: "available" | "unavailable";
+  readonly source: "l05-adjacent-geometry-intake";
+  readonly schemaVersion?: "layer-05-adjacent-geometry-intake/v2";
+  readonly rowCount: number;
+  readonly rows?: readonly ScopeAdjacentGeometryRowEvidence[];
+  readonly reason?:
+    | "adjacent-geometry-provider-unavailable"
+    | "scope-adjacent-frame-pixel-row-unavailable"
+    | "l05-adjacent-intake-not-compositor-ready";
+}
+
 export type ScopeVisualizationClass = "field" | "broad";
 
 export interface ScopeVisualizationHint {

package/src/ui-tailwind/chrome-overlay/tw-table-split-row-carry-overlay.tsx

@@ -0,0 +1,62 @@
+import React from "react";
+
+export interface TableSplitRowCarryOverlayEntry {
+  blockId: string;
+  rowIndex: number;
+  topPx: number;
+  leftPx: number;
+  widthPx: number;
+  heightPx: number;
+  continuesFromPreviousPage?: boolean;
+  continuesToNextPage?: boolean;
+}
+
+export interface TwTableSplitRowCarryOverlayProps {
+  entries: readonly TableSplitRowCarryOverlayEntry[];
+}
+
+function TwTableSplitRowCarryOverlayInner({
+  entries,
+}: TwTableSplitRowCarryOverlayProps): React.ReactElement | null {
+  if (entries.length === 0) return null;
+
+  return (
+    <>
+      {entries.map((entry) => (
+        <div
+          key={`${entry.blockId}:${entry.rowIndex}:${entry.topPx}:${entry.heightPx}`}
+          aria-hidden
+          data-table-split-row-carry=""
+          data-block-id={entry.blockId}
+          data-row-index={entry.rowIndex}
+          data-continues-from-previous-page={
+            entry.continuesFromPreviousPage ? "true" : undefined
+          }
+          data-continues-to-next-page={
+            entry.continuesToNextPage ? "true" : undefined
+          }
+          style={{
+            position: "absolute",
+            top: `${entry.topPx}px`,
+            left: `${entry.leftPx}px`,
+            width: `${entry.widthPx}px`,
+            height: `${entry.heightPx}px`,
+            pointerEvents: "none",
+            boxSizing: "border-box",
+            borderTop: entry.continuesFromPreviousPage
+              ? "1px dashed var(--color-border-accent)"
+              : undefined,
+            borderBottom: entry.continuesToNextPage
+              ? "1px dashed var(--color-border-accent)"
+              : undefined,
+            backgroundColor: "color-mix(in srgb, var(--color-accent) 8%, transparent)",
+          }}
+        />
+      ))}
+    </>
+  );
+}
+
+export const TwTableSplitRowCarryOverlay = React.memo(
+  TwTableSplitRowCarryOverlayInner,
+);

package/src/ui-tailwind/debug/layer11-consumer-readiness.ts

@@ -215,6 +215,38 @@ export interface Layer11RenderCalibrationSummary {
   route: "presentation-check" | "lower-layer-fact-required" | "insufficient-evidence";
 }
 
+export type Layer11AdjacentGeometryAxis = "numbering-marker" | "field-region";
+
+export interface Layer11AdjacentGeometryIntakeLike {
+  readonly schemaVersion?: unknown;
+  readonly totals?: {
+    readonly numberingCompositorReadyRows?: unknown;
+    readonly fieldRegionCompositorReadyRows?: unknown;
+  };
+  readonly pageLocalNormalization?: {
+    readonly framePixelCoordinateSpace?: unknown;
+    readonly framePixelPrecision?: unknown;
+    readonly compositorReady?: unknown;
+  };
+}
+
+export interface Layer11AdjacentGeometryAxisReadiness {
+  axis: Layer11AdjacentGeometryAxis;
+  compositorReadyRows: number;
+  assertionReady: boolean;
+  route: "presentation-consumer-ready" | "lower-layer-fact-required";
+  reason: string;
+}
+
+export interface Layer11AdjacentGeometryConsumerSummary {
+  schemaVersion: string | null;
+  framePixelCoordinateSpace: string | null;
+  framePixelPrecision: string | null;
+  assertionReadyCount: number;
+  lowerLayerFactRequiredCount: number;
+  entries: readonly Layer11AdjacentGeometryAxisReadiness[];
+}
+
 const PRIMARY_RENDER_EVIDENCE = new Set<Layer11RenderEvidenceKind>([
   "word-oracle",
   "render-word",
@@ -270,3 +302,75 @@ export function summarizeWordFirstRenderCalibration(
     route: "presentation-check",
   };
 }
+
+export function summarizeLayer11AdjacentGeometryConsumer(
+  intake: Layer11AdjacentGeometryIntakeLike,
+): Layer11AdjacentGeometryConsumerSummary {
+  const schemaVersion =
+    typeof intake.schemaVersion === "string" ? intake.schemaVersion : null;
+  const normalization = intake.pageLocalNormalization;
+  const framePixelCoordinateSpace =
+    typeof normalization?.framePixelCoordinateSpace === "string"
+      ? normalization.framePixelCoordinateSpace
+      : null;
+  const framePixelPrecision =
+    typeof normalization?.framePixelPrecision === "string"
+      ? normalization.framePixelPrecision
+      : null;
+  const normalizationReady =
+    schemaVersion === "layer-05-adjacent-geometry-intake/v2" &&
+    framePixelCoordinateSpace === "frame-px" &&
+    normalization?.compositorReady === true;
+  const entries: Layer11AdjacentGeometryAxisReadiness[] = [
+    summarizeAdjacentGeometryAxis(
+      "numbering-marker",
+      numberValue(intake.totals?.numberingCompositorReadyRows),
+      normalizationReady,
+    ),
+    summarizeAdjacentGeometryAxis(
+      "field-region",
+      numberValue(intake.totals?.fieldRegionCompositorReadyRows),
+      normalizationReady,
+    ),
+  ];
+
+  return {
+    schemaVersion,
+    framePixelCoordinateSpace,
+    framePixelPrecision,
+    assertionReadyCount: entries.filter((entry) => entry.assertionReady).length,
+    lowerLayerFactRequiredCount: entries.filter((entry) => !entry.assertionReady)
+      .length,
+    entries,
+  };
+}
+
+function summarizeAdjacentGeometryAxis(
+  axis: Layer11AdjacentGeometryAxis,
+  compositorReadyRows: number,
+  normalizationReady: boolean,
+): Layer11AdjacentGeometryAxisReadiness {
+  const assertionReady = normalizationReady && compositorReadyRows > 0;
+  if (assertionReady) {
+    return {
+      axis,
+      compositorReadyRows,
+      assertionReady,
+      route: "presentation-consumer-ready",
+      reason:
+        "L05 published frame-pixel rows with compositorReady provenance; L11 may consume this bounded subset without reconstructing geometry.",
+    };
+  }
+  return {
+    axis,
+    compositorReadyRows,
+    assertionReady,
+    route: "lower-layer-fact-required",
+    reason:
+      "L11 must wait for L05 frame-pixel rows marked compositorReady before treating this axis as a presentation assertion.",
+  };
+}
+
+function numberValue(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}

package/src/ui-tailwind/editor-surface/pm-page-break-decorations.ts

@@ -89,6 +89,15 @@ export interface PageBreakDecorationInput {
    * heuristic.
    */
   blockIndexRangeByPageIndex?: ReadonlyMap<number, { first: number; last: number }>;
+  /**
+   * Page indexes whose boundary/content widgets would be inserted at a document
+   * position inside a table. PM widgets inherit that table-cell containing
+   * block, so visible chrome there paints page numbers inside the cell and
+   * block-level invisible anchors can perturb table layout. Keep the diagnostic
+   * markers but suppress the visible spacer/seam and shrink anchors to inline
+   * zero-size markers.
+   */
+  suppressChromeForPageIndex?: ReadonlySet<number>;
 }
 
 export function buildPageBreakDecorations(
@@ -111,7 +120,13 @@ export function buildPageBreakDecorations(
   // (coord-11 §19) are emitted in a second pass at the end of this
   // function.
   if (graph.pages.length < 2) {
-    return buildPageAnchorDecorationsInto(decorations, graph, posture, runtimeToPmOffset);
+    return buildPageAnchorDecorationsInto(
+      decorations,
+      graph,
+      posture,
+      runtimeToPmOffset,
+      input.suppressChromeForPageIndex,
+    );
   }
 
   for (let i = 1; i < graph.pages.length; i += 1) {
@@ -133,6 +148,8 @@ export function buildPageBreakDecorations(
       input.headerPreviewByPageId?.get(next.pageId) ?? "";
 
     const nextBlockRange = input.blockIndexRangeByPageIndex?.get(next.pageIndex);
+    const suppressVisibleChrome =
+      input.suppressChromeForPageIndex?.has(next.pageIndex) === true;
 
     decorations.push(
       Decoration.widget(
@@ -155,6 +172,7 @@ export function buildPageBreakDecorations(
             nextHeaderPreview,
             nextPageFirstBlockIndex: nextBlockRange?.first ?? -1,
             nextPageLastBlockIndex: nextBlockRange?.last ?? -1,
+            suppressVisibleChrome,
           }),
         {
           side: -1,
@@ -171,7 +189,13 @@ export function buildPageBreakDecorations(
       ),
     );
   }
-  return buildPageAnchorDecorationsInto(decorations, graph, posture, runtimeToPmOffset);
+  return buildPageAnchorDecorationsInto(
+    decorations,
+    graph,
+    posture,
+    runtimeToPmOffset,
+    input.suppressChromeForPageIndex,
+  );
 }
 
 /**
@@ -197,6 +221,7 @@ function buildPageAnchorDecorationsInto(
   graph: RuntimePageGraph,
   posture: "page" | "canvas",
   runtimeToPmOffset: ((runtimeOffset: number) => number | null) | undefined,
+  tableInteriorPageIndex?: ReadonlySet<number>,
 ): Decoration[] {
   let contentPageOrdinal = 0;
   for (const page of graph.pages) {
@@ -214,6 +239,7 @@ function buildPageAnchorDecorationsInto(
         () => buildPageAnchorWidgetDom({
           pageNumber: anchorPageNumber,
           pageId: anchorPageId,
+          tableInterior: tableInteriorPageIndex?.has(page.pageIndex) === true,
         }),
         {
           side: 1,
@@ -268,6 +294,7 @@ interface ChromeWidgetInput {
    * -1 when block-index info was not supplied to the decoration builder.
    */
   nextPageLastBlockIndex: number;
+  suppressVisibleChrome?: boolean;
 }
 
 // P14.c — cache the widget DOM by input identity.  PM rebuilds the
@@ -299,6 +326,7 @@ function widgetCacheKey(input: ChromeWidgetInput): string {
     input.nextHeaderPreview,
     input.nextPageFirstBlockIndex,
     input.nextPageLastBlockIndex,
+    input.suppressVisibleChrome ? "1" : "0",
   ].join("\x1f");
 }
 
@@ -337,22 +365,29 @@ export function __resetPageBreakWidgetCache(): void {
  *
  * Emitted as a PM widget via `buildPageBreakDecorations` so it lives
  * on the content layer (present under chrome=none) rather than on an
- * absolute-positioned chrome overlay.
+ * absolute-positioned chrome overlay. When the page starts inside a table,
+ * the marker stays inline and zero-width so it does not create a block box
+ * inside the table cell.
  */
 function buildPageAnchorWidgetDom(input: {
   pageNumber: number;
   pageId: string;
+  tableInterior?: boolean;
 }): HTMLElement {
   const root = document.createElement("span");
   root.setAttribute("data-kind", "page-content-anchor");
   root.setAttribute("data-page-content-wrapper", "");
   root.setAttribute("data-page-number", String(input.pageNumber));
   root.setAttribute("data-page-id", input.pageId);
+  if (input.tableInterior) {
+    root.setAttribute("data-page-anchor-suppressed", "table-interior");
+  }
   root.setAttribute("aria-hidden", "true");
   root.contentEditable = "false";
-  root.style.display = "block";
+  root.style.display = input.tableInterior ? "inline-block" : "block";
   root.style.height = "0";
-  root.style.width = "100%";
+  root.style.width = input.tableInterior ? "0" : "100%";
+  root.style.overflow = "hidden";
   root.style.userSelect = "none";
   return root;
 }
@@ -391,6 +426,16 @@ function buildChromeWidgetDomUncached(input: ChromeWidgetInput): HTMLElement {
   root.style.width = "100%";
   root.style.userSelect = "none";
 
+  if (input.suppressVisibleChrome) {
+    root.setAttribute("data-page-chrome-suppressed", "table-interior");
+    root.setAttribute("aria-hidden", "true");
+    root.style.height = "0";
+    root.style.width = "0";
+    root.style.overflow = "hidden";
+    root.style.pointerEvents = "none";
+    return root;
+  }
+
   if (input.posture === "canvas") {
     // Single dotted horizontal line with an unframed page-number label.
     root.style.height = `${input.interGapPx + 1}px`;

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

@@ -151,6 +151,7 @@ function buildPageBreakDecorationsFromProps(
       pageIndex: p.page.pageIndex,
       startOffset: p.page.startOffset,
       isBlankFiller: p.page.isBlankFiller,
+      frame: p.page.frame,
       stories: {
         displayPageNumber: p.page.stories.displayPageNumber,
         header: p.page.stories.header,
@@ -184,6 +185,7 @@ function buildPageBreakDecorationsFromProps(
   // carry `data-page-first-block-index` / `data-page-last-block-index`
   // attributes needed by `useVisibleBlockRange`.
   let blockIndexRangeByPageIndex: Map<number, { first: number; last: number }> | undefined;
+  let suppressChromeForPageIndex: Set<number> | undefined;
   if (surfaceBlocks && surfaceBlocks.length > 0 && frame.pages.length > 0) {
     blockIndexRangeByPageIndex = new Map();
     for (let pi = 0; pi < frame.pages.length; pi++) {
@@ -193,6 +195,13 @@ function buildPageBreakDecorationsFromProps(
       if (range) {
         blockIndexRangeByPageIndex.set(page.page.pageIndex, range);
       }
+      if (
+        pi > 0 &&
+        isRuntimeOffsetInsideTableBlock(surfaceBlocks, page.page.startOffset)
+      ) {
+        if (!suppressChromeForPageIndex) suppressChromeForPageIndex = new Set();
+        suppressChromeForPageIndex.add(page.page.pageIndex);
+      }
     }
   }
 
@@ -206,9 +215,27 @@ function buildPageBreakDecorationsFromProps(
     headerPreviewByPageId: previews?.headerPreviewByPageId,
     footerPreviewByPageId: previews?.footerPreviewByPageId,
     blockIndexRangeByPageIndex,
+    suppressChromeForPageIndex,
   });
 }
 
+function isRuntimeOffsetInsideTableBlock(
+  blocks: readonly import("../../api/public-types.ts").SurfaceBlockSnapshot[],
+  offset: number,
+): boolean {
+  for (const block of blocks) {
+    if (offset <= block.from || offset >= block.to) continue;
+    if (block.kind === "table") return true;
+    if (
+      block.kind === "sdt_block" &&
+      isRuntimeOffsetInsideTableBlock(block.children, offset)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
 function extractDecorations(
   set: DecorationSet,
   _doc: unknown,

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

@@ -16,6 +16,7 @@
 import React from "react";
 import type {
   EditorStoryTarget,
+  GeometryFacet,
   PublicPageNode,
   SurfaceTableRowSnapshot,
   WordReviewEditorLayoutFacet,
@@ -23,6 +24,10 @@ import type {
 import { buildPageAnchorAttributes } from "../../api/v3/_page-anchor-id.ts";
 import type { PageOverlayRect } from "../chrome-overlay/tw-page-stack-overlay-layer.tsx";
 import { TwTableContinuationHeader } from "../chrome-overlay/tw-table-continuation-header.tsx";
+import {
+  TwTableSplitRowCarryOverlay,
+  type TableSplitRowCarryOverlayEntry,
+} from "../chrome-overlay/tw-table-split-row-carry-overlay.tsx";
 import { FRAME_PX_PER_TWIP_AT_96DPI } from "../tw-review-workspace.tsx";
 import { TwPageHeaderBand } from "./tw-page-header-band.tsx";
 import { TwPageFooterBand } from "./tw-page-footer-band.tsx";
@@ -35,6 +40,7 @@ export interface TwPageChromeEntryProps {
   pageIndex: number;
   page: PublicPageNode;
   facet: WordReviewEditorLayoutFacet;
+  geometryFacet?: GeometryFacet;
   activeStory: EditorStoryTarget;
   activeStoryPageIndex?: number | null;
   onOpenStory?: (target: EditorStoryTarget, pageIndex: number) => void;
@@ -60,6 +66,7 @@ function TwPageChromeEntryInner({
   pageIndex,
   page,
   facet,
+  geometryFacet,
   activeStory,
   activeStoryPageIndex,
   onOpenStory,
@@ -134,6 +141,16 @@ function TwPageChromeEntryInner({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [facet, pageIndex, page, renderFrameRevision]);
 
+  const splitRowCarryEntries = React.useMemo(
+    () =>
+      collectSplitRowCarryOverlayEntries({
+        geometryFacet,
+        pageIndex,
+        pageTopPx: rect.topPx,
+      }),
+    [geometryFacet, pageIndex, rect.topPx, renderFrameRevision],
+  );
+
   const handleHeaderDoubleClick = React.useCallback(
     () => headerStory && onOpenStory?.(headerStory, pageIndex),
     [onOpenStory, headerStory, pageIndex],
@@ -257,6 +274,7 @@ function TwPageChromeEntryInner({
           bodyOriginTopPx={px(layout.marginTop)}
         />
       ))}
+      <TwTableSplitRowCarryOverlay entries={splitRowCarryEntries} />
     </div>
   );
 }
@@ -269,6 +287,7 @@ function propsAreEqual(
     prev.pageIndex === next.pageIndex &&
     prev.page === next.page &&
     prev.facet === next.facet &&
+    prev.geometryFacet === next.geometryFacet &&
     prev.activeStory === next.activeStory &&
     prev.activeStoryPageIndex === next.activeStoryPageIndex &&
     prev.onOpenStory === next.onOpenStory &&
@@ -285,6 +304,49 @@ function propsAreEqual(
 
 export const TwPageChromeEntry = React.memo(TwPageChromeEntryInner, propsAreEqual);
 
+function collectSplitRowCarryOverlayEntries(input: {
+  geometryFacet?: GeometryFacet;
+  pageIndex: number;
+  pageTopPx: number;
+}): readonly TableSplitRowCarryOverlayEntry[] {
+  const index = input.geometryFacet?.getGeometryIndex();
+  if (!index) return [];
+
+  const entries: TableSplitRowCarryOverlayEntry[] = [];
+  const seen = new Set<string>();
+  for (const entry of index.semanticEntries) {
+    if (entry.kind !== "table-row") continue;
+    if (entry.pageIndex !== input.pageIndex) continue;
+    if (entry.rect.space !== "frame") continue;
+    const carries = entry.tableContinuation?.splitRowCarry ?? [];
+    if (carries.length === 0) continue;
+    const blockId = entry.blockId;
+    if (!blockId) continue;
+    for (const carry of carries) {
+      const rowIndex = entry.rowIndex ?? carry.rowIndex;
+      if (rowIndex === undefined) continue;
+      const topPx = Math.max(0, entry.rect.topPx - input.pageTopPx);
+      const leftPx = Math.max(0, entry.rect.leftPx);
+      const widthPx = Math.max(1, entry.rect.widthPx);
+      const heightPx = Math.max(1, entry.rect.heightPx);
+      const key = `${blockId}:${rowIndex}:${topPx}:${leftPx}:${widthPx}:${heightPx}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      entries.push({
+        blockId,
+        rowIndex,
+        topPx,
+        leftPx,
+        widthPx,
+        heightPx,
+        continuesFromPreviousPage: carry.continuesFromPreviousPage,
+        continuesToNextPage: carry.continuesToNextPage,
+      });
+    }
+  }
+  return entries;
+}
+
 function isActiveStoryMatch(
   active: EditorStoryTarget,
   candidate: EditorStoryTarget,

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

@@ -503,6 +503,7 @@ const TwPageStackChromeLayerInner: React.FC<TwPageStackChromeLayerProps> = ({
             pageIndex={rect.pageIndex}
             page={page}
             facet={facet}
+            geometryFacet={geometryFacet}
             activeStory={activeStory}
             activeStoryPageIndex={activeStoryPageIndex}
             onOpenStory={handleOpenStoryForPage}

package/src/README.md

@@ -1,85 +0,0 @@
-# Source Layout
-
-The landed source tree is still organized around the active docx implementation, not around the future target office-wide layout.
-
-## Current Landed Layout
-
-```text
-src/
-  api/
-  model/
-  core/
-    schema/
-    state/
-    commands/
-    selection/
-  review/
-    store/
-  io/
-    opc/
-    ooxml/
-    normalize/
-    export/
-  preservation/
-  validation/
-  runtime/
-  ui/
-    headless/            # Shared pure logic (framework-free)
-    shared/              # Shared utilities (revision-filters)
-    WordReviewEditor.tsx  # Entry point
-  ui-tailwind/           # Default rendering (Tailwind + Radix + Lucide)
-    editor-surface/
-    toolbar/
-    review/
-    status/
-    chrome/
-    theme/
-```
-
-This is the truthful current layout for implementation work today.
-
-## Target Broader Layout
-
-The broader repo story now targets a future layout like this:
-
-```text
-src/
-  platform/
-  formats/
-    docx/
-    xlsx/
-    pdf/
-```
-
-That layout is not landed yet. Use it as a planning direction, not as evidence that the current code has already been reorganized.
-
-## UI Layer Strategy
-
-- `ui/headless/` — Pure logic: keyboard handling, decoration models, selection utilities. No React dependencies.
-- `ui-tailwind/` — Default rendering: Tailwind CSS, Radix UI primitives, Lucide icons. All styling via CSS custom properties.
-- `ui/WordReviewEditor.tsx` — Public entry point that bridges the runtime to the Tailwind layer.
-
-Legacy inline-CSSProperties components have been removed. See `docs/reference/word-review-editor-frontend-architecture.md` for the canonical frontend architecture.
-
-Keep business rules close to the subsystem that owns them. Do not centralize unrelated logic into generic utility layers.
-
-Ownership rules:
-
-- `api` exposes public contracts only.
-- `model`, `core`, `review`, `io`, `preservation`, and `validation` should remain React-free when possible.
-- `runtime` is the only mutation boundary the UI calls into.
-- `ui` consumes runtime contracts and design tokens; it does not own canonical document truth.
-
-## Broader Repo Direction
-
-As the repo broadens:
-
-- shared package and preservation concerns should move toward `src/platform/`
-- current docx runtime code remains the active implementation track until a deliberate source move lands
-- future xlsx work should gain its own source area rather than widening docx-specific modules by implication
-- future pdf work should remain separate from the first OOXML platform layer unless architecture decisions intentionally broaden it
-
-Wave 0 inventory references:
-
-- `component-inventory.md`
-  Wave-owned inventory for the major editor subsystems, their boundaries, and the promotion target for this scaffold phase.

package/src/api/README.md

@@ -1,26 +0,0 @@
-# API
-
-Public TypeScript contracts for `WordReviewEditor` belong here.
-
-This layer should expose:
-
-- component props and ref types
-- session-state and snapshot compatibility types
-- host adapter and datastore adapter interfaces
-- runtime-derived position and selection projection types used by the public API
-- discriminated event unions
-- warning and error payloads
-- persisted snapshot contracts
-- export and compatibility report types
-
-Do not place runtime logic here.
-
-Frozen naming and boundary rules:
-
-- the shipped component name is `WordReviewEditor`
-- `DocumentRuntime` is an internal runtime contract, not a public React component name
-- `EditorSessionState` is the canonical host-facing live-session contract
-- `PersistedEditorSnapshot` is the legacy/store compatibility envelope
-- `EditorHostAdapter` is the preferred persistence boundary; `EditorDatastoreAdapter` remains the snapshot-compatible bridge
-- public range references are canonical-position projections, not DOM-path handles
-- render snapshots stay in `src/runtime`; `src/api` only exposes persisted host-facing snapshot types