@beyondwork/docx-react-component 1.0.81 → 1.0.82

package/src/ui-tailwind/chrome/editor-actions-to-palette.ts

@@ -12,9 +12,10 @@
  *
  * Progressive-disclosure discipline (designsystem.md §2.1 principle 4):
  *   - Actions without a wired callback are hidden, not rendered
- *     disabled.  The palette is the escape valve for low-frequency
- *     actions; an empty surface is better than a wall of disabled
- *     rows.
+ *     disabled unless the registry marks them as important signposts
+ *     by returning `"disabled"` from `when()`. Those rows stay visible
+ *     with an explanation so users can see that the product recognizes
+ *     the workflow even when the host has not wired it yet.
  *   - Mode-filtered actions (e.g. `scope-open-card` is
  *     workflow/review-only) only appear when the composition mode
  *     allows them.
@@ -33,7 +34,6 @@ import type {
   CommandPaletteGroup,
   CommandPaletteItem,
 } from "./tw-command-palette";
-import type { ContextMenuGroupId } from "./tw-context-menu";
 import type { ShortcutKey } from "./tw-shortcut-hint";
 
 /**
@@ -90,43 +90,63 @@ export function formatShortcutForPalette(
 }
 
 /**
- * Human-friendly group labels.  Kept here because the palette renders
- * section headings and the registry's group ids are terse internal
- * identifiers.
+ * Product-facing command palette buckets. These are intentionally not
+ * the context-menu `ContextMenuGroupId`s: right-click menus group by
+ * local action family, while the palette groups by user intent.
  */
-const GROUP_LABELS: Record<ContextMenuGroupId, string> = {
-  clipboard: "Clipboard",
-  suggestion: "Review",
-  comment: "Comments",
-  table: "Table",
-  formatting: "Formatting",
-  misc: "More",
+type ProductPaletteGroupId =
+  | "commands"
+  | "search"
+  | "navigation"
+  | "mode"
+  | "diagnostics";
+
+const GROUP_LABELS: Record<ProductPaletteGroupId, string> = {
+  commands: "Commands",
+  search: "Search",
+  navigation: "Navigation",
+  mode: "Mode",
+  diagnostics: "Diagnostics",
 };
 
 /**
- * Stable group order — matches the progressive-disclosure priority in
- * designsystem.md §2.1 (clipboard first because it's always available,
- * review + comment next because they're the primary legal-review
- * actions, table + formatting after, misc last).
+ * Stable product group order per editor-product Slice 3.
  */
-const GROUP_ORDER: readonly ContextMenuGroupId[] = [
-  "clipboard",
-  "suggestion",
-  "comment",
-  "table",
-  "formatting",
-  "misc",
+const GROUP_ORDER: readonly ProductPaletteGroupId[] = [
+  "commands",
+  "search",
+  "navigation",
+  "mode",
+  "diagnostics",
 ];
 
-function isActionAvailable(
+function actionAvailability(
   action: EditorAction,
   ctx: EditorActionDispatchContext,
-): boolean {
+): false | "enabled" | "disabled" {
   const verdict = action.when ? action.when(ctx) : true;
-  // "disabled" actions are hidden from the palette.  The palette is a
-  // search-first surface; surfacing disabled rows dilutes the query
-  // space and clutters the empty state.
-  return verdict === true;
+  if (verdict === false) return false;
+  return verdict === "disabled" ? "disabled" : "enabled";
+}
+
+function paletteGroupForAction(action: EditorAction): ProductPaletteGroupId {
+  switch (action.id) {
+    case "find":
+    case "replace":
+      return "search";
+    case "go-to":
+    case "jump-to-comment-in-rail":
+    case "scope-jump-in-rail":
+    case "scope-open-card":
+      return "navigation";
+    case "scope-mark-resolved":
+      return "mode";
+    case "object-info":
+    case "print":
+      return "diagnostics";
+    default:
+      return "commands";
+  }
 }
 
 export interface BuildPaletteGroupsInput {
@@ -145,15 +165,18 @@ export function buildPaletteGroupsFromRegistry(
     dismiss: input.dismiss,
   };
 
-  const byGroup = new Map<ContextMenuGroupId, CommandPaletteItem[]>();
+  const byGroup = new Map<ProductPaletteGroupId, CommandPaletteItem[]>();
 
   for (const action of EDITOR_ACTION_REGISTRY) {
     if (action.modes && !action.modes.has(input.mode)) continue;
-    if (!isActionAvailable(action, ctx)) continue;
+    const availability = actionAvailability(action, ctx);
+    if (availability === false) continue;
 
     const item: CommandPaletteItem = {
       id: action.id,
       label: action.label,
+      ...(action.description ? { description: action.description } : {}),
+      ...(availability === "disabled" ? { disabled: true } : {}),
       // Chrome Closure Pass · Task 4 (designsystem.md §6.25) —
       // preserve the registry shortcut so the palette row shows
       // the same hint as the matching context-menu / tooltip.
@@ -163,9 +186,10 @@ export function buildPaletteGroupsFromRegistry(
       onInvoke: () => action.run(ctx),
     };
 
-    const bucket = byGroup.get(action.group) ?? [];
+    const groupId = paletteGroupForAction(action);
+    const bucket = byGroup.get(groupId) ?? [];
     bucket.push(item);
-    byGroup.set(action.group, bucket);
+    byGroup.set(groupId, bucket);
   }
 
   const groups: CommandPaletteGroup[] = [];

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

@@ -251,6 +251,7 @@ export const TwChromeOverlay: React.FC<TwChromeOverlayProps> = ({
       {pageStackScrollRoot !== undefined ? (
         <TwPageStackChromeLayer
           facet={facet}
+          geometryFacet={geometryFacet}
           scrollRoot={pageStackScrollRoot}
           renderFrameRevision={renderFrameRevision ?? 0}
           activeStory={activeStory ?? { kind: "main" }}

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

@@ -94,6 +94,99 @@ export interface VisiblePageIndexRange {
   end: number;
 }
 
+function pageOverlayRectsEqual(
+  a: readonly PageOverlayRect[],
+  b: readonly PageOverlayRect[],
+): boolean {
+  if (a === b) return true;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) {
+    const left = a[i]!;
+    const right = b[i]!;
+    if (
+      left.pageId !== right.pageId ||
+      left.pageIndex !== right.pageIndex ||
+      left.topPx !== right.topPx ||
+      left.bottomPx !== right.bottomPx ||
+      left.heightPx !== right.heightPx
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function pageOverlayLastBottom(rects: readonly PageOverlayRect[]): number {
+  let bottom = 0;
+  for (const rect of rects) {
+    if (rect.bottomPx > bottom) bottom = rect.bottomPx;
+  }
+  return bottom;
+}
+
+/**
+ * Page mode currently keeps the editable ProseMirror body as one natural DOM
+ * flow and paints page cards behind it. Layout geometry gives us the intended
+ * page frames, but browser-rendered PM content can exceed the final geometry
+ * frame (wide tables, fallback font metrics, or deliberately-degraded
+ * over-tall blocks). The decorative paper must follow that visible flow so
+ * text never appears directly on the workspace canvas.
+ */
+export function extendFinalPageOverlayRectToFlowHeight(
+  rects: readonly PageOverlayRect[],
+  flowHeightPx: number,
+): readonly PageOverlayRect[] {
+  if (rects.length === 0 || !Number.isFinite(flowHeightPx)) return rects;
+  const last = rects[rects.length - 1]!;
+  if (flowHeightPx <= last.bottomPx + 1) return rects;
+  return [
+    ...rects.slice(0, -1),
+    {
+      ...last,
+      bottomPx: flowHeightPx,
+      heightPx: Math.max(0, flowHeightPx - last.topPx),
+    },
+  ];
+}
+
+export function extendPageOverlayRectsAcrossTableBoundaryGaps(
+  rects: readonly PageOverlayRect[],
+  tableBoundaryIndices: readonly number[],
+): readonly PageOverlayRect[] {
+  if (rects.length === 0 || tableBoundaryIndices.length === 0) return rects;
+  const tableBoundaries = new Set(tableBoundaryIndices);
+  const byPageIndex = new Map<number, PageOverlayRect>();
+  for (const rect of rects) {
+    byPageIndex.set(rect.pageIndex, rect);
+  }
+
+  let changed = false;
+  const bridged = rects.map((rect) => {
+    if (!tableBoundaries.has(rect.pageIndex)) return rect;
+    const next = byPageIndex.get(rect.pageIndex + 1);
+    if (!next || next.topPx <= rect.bottomPx + 1) return rect;
+    changed = true;
+    return {
+      ...rect,
+      bottomPx: next.topPx,
+      heightPx: Math.max(0, next.topPx - rect.topPx),
+    };
+  });
+  return changed ? bridged : rects;
+}
+
+function mergePageOverlayRectsByPageIndex(
+  baseRects: readonly PageOverlayRect[],
+  flowRects: readonly PageOverlayRect[],
+): readonly PageOverlayRect[] {
+  if (baseRects.length === 0 || flowRects.length === 0) return baseRects;
+  const flowByIndex = new Map<number, PageOverlayRect>();
+  for (const rect of flowRects) {
+    flowByIndex.set(rect.pageIndex, rect);
+  }
+  return baseRects.map((rect) => flowByIndex.get(rect.pageIndex) ?? rect);
+}
+
 function normalizeVisiblePageIndexRange(
   range: VisiblePageIndexRange | null | undefined,
   pageCount: number,
@@ -126,6 +219,26 @@ function parsePageBoundaryIndex(prevPageId: string): number | undefined {
   return Number.parseInt(match[1] ?? "", 10);
 }
 
+function collectTableEmbeddedBoundaryIndices(
+  queryRoot: Pick<HTMLElement, "querySelectorAll"> | null,
+): number[] {
+  if (!queryRoot) return [];
+  const indices: number[] = [];
+  const widgets = Array.from(
+    queryRoot.querySelectorAll<HTMLElement>("[data-page-frame-end]"),
+  );
+  for (const widget of widgets) {
+    const prevPageId = widget.getAttribute("data-page-frame-end");
+    if (!prevPageId) continue;
+    const boundaryIndex = parsePageBoundaryIndex(prevPageId);
+    if (boundaryIndex === undefined) continue;
+    if (widget.closest("[data-pm-table-root='true'], table")) {
+      indices.push(boundaryIndex);
+    }
+  }
+  return indices;
+}
+
 /**
  * Pure helper: turn pre-measured page-boundary widget positions into
  * one `PageOverlayRect` per page.  No DOM access — the caller supplies
@@ -407,6 +520,39 @@ function resolveOffsetHeight(widget: HTMLElement): number {
   return widget.offsetHeight ?? 0;
 }
 
+function readElementFlowHeight(
+  element: HTMLElement | null,
+  options: { includeScrollHeight?: boolean } = {},
+): number {
+  if (!element) return 0;
+  let height = 0;
+  // geometry:allow-dom-fallback
+  height = Math.max(height, element.clientHeight || 0);
+  if (options.includeScrollHeight !== false) {
+    // geometry:allow-dom-fallback
+    height = Math.max(height, element.scrollHeight || 0);
+  }
+  if (height <= 0) {
+    // geometry:allow-dom-fallback
+    const rect = element.getBoundingClientRect();
+    height = Math.max(height, rect.height || 0);
+  }
+  return height;
+}
+
+function readOverlayFlowHeight(origin: HTMLElement | null): number {
+  if (!origin) return 0;
+  const parent = origin.parentElement instanceof HTMLElement
+    ? origin.parentElement
+    : null;
+  const parentHeight = readElementFlowHeight(parent);
+  if (parentHeight > 0) return parentHeight;
+  // Fallback only: do not read origin.scrollHeight here. The overlay's own
+  // absolutely-positioned paper cards can otherwise preserve a stale extended
+  // height after editable content shrinks.
+  return readElementFlowHeight(origin, { includeScrollHeight: false });
+}
+
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
@@ -438,6 +584,10 @@ export interface TwPageStackOverlayLayerProps {
    * time this changes so the overlays stay aligned with content.
    */
   renderFrameRevision: number;
+  /**
+   * Kept for call-site compatibility. Paper-card backgrounds intentionally
+   * render every page; viewport culling belongs to heavier chrome layers.
+   */
   visiblePageIndexRange?: VisiblePageIndexRange | null;
   /** Optional test id applied to the overlay root. */
   "data-testid"?: string;
@@ -524,7 +674,6 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
   geometryFacet,
   scrollRoot,
   renderFrameRevision,
-  visiblePageIndexRange,
   "data-testid": testId,
 }) => {
   // DS-C2 — prefer `ui.overlays.getAnchor({ kind: "page", ... })` as
@@ -542,12 +691,21 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
     if (!geometryFacet) return [];
     const pageCount = facet.getPageCount();
     if (pageCount <= 0) return [];
+    // Paper-card backgrounds are cheap and must stay ahead of scroll. Heavy
+    // header/footer/footnote chrome still consumes `visiblePageIndexRange`;
+    // this decorative white-paper layer renders every card so fast scrolls
+    // never expose the gray canvas while the page window catches up.
     const warm = resolvePageOverlayRectsFromGeometry(
       geometryFacet,
       pageCount,
-      visiblePageIndexRange,
+      null,
     );
-    return warm ?? [];
+    return warm
+      ? extendPageOverlayRectsAcrossTableBoundaryGaps(
+          warm,
+          collectTableEmbeddedBoundaryIndices(scrollRoot),
+        )
+      : [];
   });
   // P3.d fix: the overlay root acts as the **measurement origin** so
   // widget `topPx` / `bottomPx` are expressed in the exact coordinate
@@ -576,12 +734,60 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
   // tears down.
   const rafHandleRef = React.useRef<number | null>(null);
 
+  const setRectsIfChanged = React.useCallback(
+    (next: readonly PageOverlayRect[]) => {
+      setRects((prev) => (pageOverlayRectsEqual(prev, next) ? prev : next));
+    },
+    [],
+  );
+
+  const reconcilePaperRectsWithFlow = React.useCallback(
+    (
+      baseRects: readonly PageOverlayRect[],
+      pageCount: number,
+    ): readonly PageOverlayRect[] => {
+      if (baseRects.length === 0 || pageCount <= 0) return baseRects;
+      const origin = overlayRootRef.current;
+      const flowHeight = readOverlayFlowHeight(origin);
+      const bridgedBase = extendPageOverlayRectsAcrossTableBoundaryGaps(
+        baseRects,
+        collectTableEmbeddedBoundaryIndices(scrollRoot),
+      );
+      if (flowHeight <= 0) return bridgedBase;
+
+      const extendedBase = extendFinalPageOverlayRectToFlowHeight(
+        bridgedBase,
+        flowHeight,
+      );
+      if (!origin || !scrollRoot) return extendedBase;
+
+      // The common warm path has geometry and DOM flow in agreement. Avoid the
+      // full boundary-widget scan unless the PM flow is visibly taller than the
+      // geometry stack. When it is taller, the paper-card layer must follow the
+      // in-flow boundaries so content remains on paper instead of canvas.
+      if (flowHeight <= pageOverlayLastBottom(bridgedBase) + 1) {
+        return extendedBase;
+      }
+
+      const widgets = measureWidgetsViaBoundingRect(scrollRoot, origin, {
+        pageCount,
+        visiblePageIndexRange: null,
+      });
+      if (widgets.length === 0) return extendedBase;
+
+      const flowRects = resolvePageOverlayRects({
+        widgets,
+        pageCount,
+        scrollHeight: flowHeight,
+        visiblePageIndexRange: null,
+      });
+      const merged = mergePageOverlayRectsByPageIndex(extendedBase, flowRects);
+      return extendFinalPageOverlayRectToFlowHeight(merged, flowHeight);
+    },
+    [scrollRoot],
+  );
+
   const refreshRectsNow = React.useCallback(() => {
-    if (!scrollRoot) {
-      setRects([]);
-      return;
-    }
-    const origin = overlayRootRef.current;
     const pageCount = facet.getPageCount();
 
     // DS-C2 — first try the UI API seam so presentation code does not
@@ -608,12 +814,12 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
       const uiRects = resolvePageOverlayRectsFromUiApi(
         ui,
         pageCount,
-        visiblePageIndexRange,
+        null,
         pageIds,
       );
       if (uiRects !== null) {
         incrementInvalidationCounter("overlay.page.ui_api.hit");
-        setRects(uiRects);
+        setRectsIfChanged(reconcilePaperRectsWithFlow(uiRects, pageCount));
         return;
       }
       incrementInvalidationCounter("overlay.page.ui_api.fallthrough");
@@ -630,54 +836,65 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
       const geometryRects = resolvePageOverlayRectsFromGeometry(
         geometryFacet,
         pageCount,
-        visiblePageIndexRange,
+        null,
       );
       if (geometryRects !== null) {
-        setRects(geometryRects);
+        setRectsIfChanged(reconcilePaperRectsWithFlow(geometryRects, pageCount));
         return;
       }
     }
 
+    if (!scrollRoot) {
+      setRectsIfChanged([]);
+      return;
+    }
+    const origin = overlayRootRef.current;
+
     // Cold-open / pre-paint DOM fallback — warm path early-returned
     // above via `geometryFacet` or the UI-API resolver. Lines below
     // fire only before the first render frame.
     if (origin) {
       const widgets = measureWidgetsViaBoundingRect(scrollRoot, origin, {
         pageCount,
-        visiblePageIndexRange,
+        visiblePageIndexRange: null,
       });
       // geometry:allow-dom-fallback
       const originRect = origin.getBoundingClientRect();
-      setRects(
-        resolvePageOverlayRects({
-          widgets,
-          pageCount,
-          scrollHeight:
-            // geometry:allow-dom-fallback
-            origin.clientHeight > 0 ? origin.clientHeight : originRect.height,
-          visiblePageIndexRange,
-        }),
-      );
+      const domRects = resolvePageOverlayRects({
+        widgets,
+        pageCount,
+        scrollHeight:
+          // geometry:allow-dom-fallback
+          origin.clientHeight > 0 ? origin.clientHeight : originRect.height,
+        visiblePageIndexRange: null,
+      });
+      setRectsIfChanged(reconcilePaperRectsWithFlow(domRects, pageCount));
     } else {
       const widgets = measureWidgetsViaOffsetChain(scrollRoot, {
         pageCount,
-        visiblePageIndexRange,
+        visiblePageIndexRange: null,
       });
-      setRects(
-        resolvePageOverlayRects({
-          widgets,
-          pageCount,
-          // geometry:allow-dom-fallback
-          scrollHeight: scrollRoot.clientHeight,
-          visiblePageIndexRange,
-        }),
-      );
+      const domRects = resolvePageOverlayRects({
+        widgets,
+        pageCount,
+        // geometry:allow-dom-fallback
+        scrollHeight: scrollRoot.clientHeight,
+        visiblePageIndexRange: null,
+      });
+      setRectsIfChanged(reconcilePaperRectsWithFlow(domRects, pageCount));
     }
-  }, [facet, geometryFacet, scrollRoot, ui, visiblePageIndexRange]);
+  }, [
+    facet,
+    geometryFacet,
+    reconcilePaperRectsWithFlow,
+    scrollRoot,
+    setRectsIfChanged,
+    ui,
+  ]);
 
   const refreshRects = React.useCallback(() => {
     if (!scrollRoot) {
-      setRects([]);
+      refreshRectsNow();
       return;
     }
     const runtime = scrollRoot.ownerDocument?.defaultView as
@@ -724,6 +941,7 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
   // Observe scroll-root size changes so zoom, viewport resize, or font
   // loading re-trigger measurement without a full app re-render.
   React.useEffect(() => {
+    if (geometryFacet) return;
     if (!scrollRoot) return;
     const runtime = scrollRoot.ownerDocument?.defaultView as
       | (Window & { ResizeObserver?: typeof ResizeObserver })
@@ -732,7 +950,7 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
     const observer = new runtime.ResizeObserver(() => refreshRects());
     observer.observe(scrollRoot);
     return () => observer.disconnect();
-  }, [scrollRoot, refreshRects]);
+  }, [geometryFacet, scrollRoot, refreshRects]);
 
   // Observe DOM mutations so PM re-renders (page-break widgets added /
   // removed on relayout) re-trigger measurement.  We filter to
@@ -750,6 +968,7 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
   // times within one animation frame coalesces into one measurement
   // pass instead of a per-mutation re-render storm.
   React.useEffect(() => {
+    if (geometryFacet) return;
     if (!scrollRoot) return;
     const runtime = scrollRoot.ownerDocument?.defaultView as
       | (Window & { MutationObserver?: typeof MutationObserver })
@@ -775,7 +994,7 @@ export const TwPageStackOverlayLayer: React.FC<TwPageStackOverlayLayerProps> = (
     // actually matters for the overlay's rect math.
     observer.observe(scrollRoot, { childList: true, subtree: false });
     return () => observer.disconnect();
-  }, [scrollRoot, refreshRects]);
+  }, [geometryFacet, scrollRoot, refreshRects]);
 
   // Always render the overlay root so the ref resolves on first paint.
   // Without the root element we never get a `getBoundingClientRect()`

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

@@ -279,6 +279,28 @@ export const editorSchema = new Schema({
         const indentHanging = node.attrs.indentHanging as number | null;
         if (indentHanging) styles.push(`text-indent: -${indentHanging / 20}pt`);
         else if (indentFirstLine) styles.push(`text-indent: ${indentFirstLine / 20}pt`);
+        // Numbering marker-lane outdent (coord-04 §1.21 — "legal numbering
+        // touches the left margin / clips into page chrome"). Word/LO model:
+        // a numbered paragraph occupies `[markerLane.start, textColumn.right]`;
+        // the marker lane lives at `[textStart - hanging, textStart]`. When
+        // `hanging > indentLeft` the marker starts at negative x relative to
+        // the paragraph's content-frame origin — a legitimate Word scenario
+        // (w:ind w:left="360" w:hanging="720"). The marker span's
+        // `margin-left: -markerWidth` (emitted below) depends on the
+        // paragraph's content box actually reaching that far left; without
+        // this outdent the marker slides off the page frame and clips into
+        // surrounding chrome. `margin-left` expands the paragraph's content
+        // box leftward while keeping `padding-left` (body-text alignment)
+        // untouched.
+        const numberingMarkerStartTwips = node.attrs.numberingMarkerStart as
+          | number
+          | null;
+        if (
+          typeof numberingMarkerStartTwips === "number" &&
+          numberingMarkerStartTwips < 0
+        ) {
+          styles.push(`margin-left: ${numberingMarkerStartTwips / 20}pt`);
+        }
         const shadingColor = safeHexColor(node.attrs.shadingFill as string | null);
         if (shadingColor) styles.push(`background-color: ${shadingColor}`);
         // Paragraph borders. Reads the PublicBorderSpec shape
@@ -378,6 +400,27 @@ export const editorSchema = new Schema({
         if (contextualSpacingAfter) {
           attrs["data-contextual-spacing-after"] = "true";
         }
+        // Numbering geometry debug visibility (coord-04 §1.21 Deliverable D):
+        // expose the resolved marker lane on the paragraph element so parity
+        // investigators can inspect truth-vs-render without re-deriving the
+        // geometry. Values are twips; consumers convert at read time.
+        if (typeof numberingMarkerStartTwips === "number") {
+          attrs["data-numbering-marker-start-twips"] = String(numberingMarkerStartTwips);
+        }
+        const _numberingMarkerWidthTwips = node.attrs.numberingMarkerWidth as
+          | number
+          | null;
+        if (
+          typeof _numberingMarkerWidthTwips === "number" &&
+          _numberingMarkerWidthTwips > 0
+        ) {
+          attrs["data-numbering-marker-width-twips"] = String(
+            _numberingMarkerWidthTwips,
+          );
+        }
+        if (typeof indentLeft === "number") {
+          attrs["data-numbering-body-start-twips"] = String(indentLeft);
+        }
         if (styles.length > 0) attrs.style = styles.join("; ");
         const numberingPrefix = node.attrs.numberingPrefix as string | null;
         const numberingLevel = node.attrs.numberingLevel as number | null;
@@ -453,6 +496,17 @@ export const editorSchema = new Schema({
           if (hasResolvedMarkerWidth) {
             // P13.a: emit marker geometry in pt (twips/20 == pt) so it
             // self-scales under CSS `zoom` and matches Word's intent.
+            //
+            // Marker-lane contract (coord-04 §1.21 — Word/LO model):
+            // the marker occupies `[markerStart, markerStart + markerWidth]`
+            // where `markerStart = textStart - hanging`. The negative
+            // `margin-left` pulls the marker leftward by its own width into
+            // the paragraph's padding zone (`textStart - markerWidth`, since
+            // `padding-left = textStart`). When `markerStart < 0` the
+            // paragraph itself carries a compensating negative `margin-left`
+            // (emitted above at the paragraph-style branch) so its content
+            // box reaches far enough left to hold the marker without
+            // clipping into page chrome.
             const markerWidthPt = Math.max(1, numberingMarkerWidth / 20);
             prefixStyles.push(
               `width: ${markerWidthPt}pt`,
@@ -462,7 +516,6 @@ export const editorSchema = new Schema({
               `margin-right: 0`,
               `overflow: visible`,
             );
-            void numberingMarkerStart; // consumed via paragraph padding-left geometry
           } else {
             prefixStyles.push(
               `min-width: ${fallbackMinWidth}ch`,