refactor: migrate paragraph consumers to directionContext (SD-2777) (#3263)

* refactor: read paragraph direction from directionContext (SD-2777)

Migrates Phase A paragraph consumers onto Wave 1a's resolver context
(SD-2776). Adds getParagraphInlineDirection helper in @superdoc/contracts
that reads directionContext.inlineDirection first, with a compat fallback
to legacy attrs.direction / attrs.dir / attrs.rtl /
paragraphProperties.rightToLeft until SD-2778 collapses the duplicates.

Behavior is unchanged because pm-adapter still mirrors
directionContext.inlineDirection onto the legacy fields, so hash output
stays identical.

Phase A scope (consumers, paragraph-axis only):
- layout-bridge: paragraph-hash-utils, cache (paragraph + cell sites)
- layout-resolved: versionSignature (block + cell sites)
- painter-dom: renderer (block + cell hash sites)
- super-editor: listBoundaryNavigationPlugin

Out of scope (deferred):
- Table-axis consumers (renderTableFragment / renderTableCell /
  renderTableRow). Wait for PR #3227 to settle since it overlaps these.
- SD-2779 rename of the rtl-paragraph DomPainter feature module.
  Kept separate to avoid diff noise.
- ParagraphNodeView.inferParagraphRtlFromRuns - heuristic violates the
  resolver's no-infer-from-runs rule; removing it is a behavior change.

* chore(comments): apply comment-policy fixes to Phase A

- Drop paraphrase from three `// Direction` section labels in layout-bridge.
  The label now matches the surrounding `// Shading` / `// Tabs` neighbors;
  the helper's name + JSDoc already document the read order.
- Reshape the compat-fallback comment on getParagraphInlineDirection into
  the policy's canonical `AIDEV-NOTE: compat-fallback - <trigger>. Retire
  once <condition>.` form per comment-policy.md.

No behavior change.

* test(pm-adapter): pin direction <-> directionContext.inlineDirection invariant (SD-2777)

Verifies the load-bearing property of the Phase A migration: pm-adapter
must write `paragraphAttrs.direction` and
`paragraphAttrs.directionContext.inlineDirection` as either the same value
or both undefined.

This is what makes `getParagraphInlineDirection(attrs)` produce a hash
byte-identical to the legacy `attrs.direction` read on FlowBlock attrs.
Layout-compare against 462 R2 docs returned 0 changed snapshots; this test
codifies the invariant so a future change to the writer can't silently
break hash stability.

Also rename `getParagraphInlineDirection` test 'returns undefined when
directionContext is present with no inlineDirection' to
'falls back past directionContext when inlineDirection is null' so the
title matches the assertion.

* refactor: migrate remaining FlowBlock attrs direction reads to helper (SD-2777)

Catches four `attrs?.direction === 'rtl'` reads the original audit's regex
missed (the optional-chain form `attrs?.direction` didn't match
`attrs\.direction`):

- painters/dom/src/renderer.ts:3182, 3289 - render-path isRtl lookups
- painters/dom/src/features/rtl-paragraph/rtl-styles.ts - isRtlParagraph helper
- super-editor/.../CaretGeometry.ts - caret RTL adjustment

Behavior is unchanged: the pm-adapter invariant test added in the previous
commit proves `direction` and `directionContext.inlineDirection` are always
paired (or both undefined). These call sites resolve to the same value via
the helper as they did via the legacy scalar.

Caught via codex-bot review comment on PR #3263 plus a broader grep for
`paragraphProperties.rightToLeft` reads.

Two upstream consumers remain out of scope: `headless-toolbar/helpers/
paragraph.ts` and `extensions/text-align/text-align.js` read
`paragraphProperties.rightToLeft` at the style-resolved layer, upstream of
pm-adapter where directionContext doesn't exist yet.

Author: caio-pizzol

packages/layout-engine/contracts/src/direction-context.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import { getParagraphInlineDirection } from './direction-context.js';
+
+describe('getParagraphInlineDirection', () => {
+  it('returns undefined for null/undefined attrs', () => {
+    expect(getParagraphInlineDirection(undefined)).toBeUndefined();
+    expect(getParagraphInlineDirection(null)).toBeUndefined();
+  });
+
+  it('prefers directionContext.inlineDirection over legacy fields', () => {
+    const attrs = {
+      directionContext: { inlineDirection: 'rtl' as const },
+      direction: 'ltr',
+      rtl: false,
+    };
+    expect(getParagraphInlineDirection(attrs)).toBe('rtl');
+  });
+
+  it('falls back past directionContext when inlineDirection is null', () => {
+    // Per resolver semantics, inlineDirection=null/undefined means "no explicit
+    // w:bidi"; the legacy `direction` field is the next fallback in the chain.
+    const attrs = { directionContext: { inlineDirection: null }, direction: 'rtl' };
+    expect(getParagraphInlineDirection(attrs)).toBe('rtl');
+  });
+
+  it('falls back to attrs.direction', () => {
+    expect(getParagraphInlineDirection({ direction: 'rtl' })).toBe('rtl');
+    expect(getParagraphInlineDirection({ direction: 'ltr' })).toBe('ltr');
+  });
+
+  it('falls back to attrs.dir', () => {
+    expect(getParagraphInlineDirection({ dir: 'rtl' })).toBe('rtl');
+    expect(getParagraphInlineDirection({ dir: 'ltr' })).toBe('ltr');
+  });
+
+  it('falls back to attrs.rtl boolean', () => {
+    expect(getParagraphInlineDirection({ rtl: true })).toBe('rtl');
+    expect(getParagraphInlineDirection({ rtl: false })).toBe('ltr');
+  });
+
+  it('falls back to paragraphProperties.rightToLeft', () => {
+    expect(getParagraphInlineDirection({ paragraphProperties: { rightToLeft: true } })).toBe('rtl');
+    expect(getParagraphInlineDirection({ paragraphProperties: { rightToLeft: false } })).toBe('ltr');
+  });
+
+  it('returns undefined when no signal is present', () => {
+    expect(getParagraphInlineDirection({})).toBeUndefined();
+    expect(getParagraphInlineDirection({ directionContext: {} })).toBeUndefined();
+    expect(getParagraphInlineDirection({ paragraphProperties: {} })).toBeUndefined();
+  });
+});

packages/layout-engine/contracts/src/direction-context.ts

@@ -156,3 +156,40 @@ export type RunScriptContext = {
     eastAsian?: string;
   };
 };
+
+/**
+ * Read a paragraph's inline base direction from its attributes.
+ *
+ * Prefers the resolved {@link ParagraphDirectionContext} (SD-2776) when
+ * present, then falls back to the legacy scalar fields (`direction`,
+ * `dir`, `rtl`, `paragraphProperties.rightToLeft`) for compatibility
+ * until SD-2778 collapses the duplicates.
+ *
+ * Consumers should call this instead of inspecting attrs ad hoc so the
+ * direction source check stays in one place.
+ */
+export function getParagraphInlineDirection(
+  attrs:
+    | {
+        directionContext?: { inlineDirection?: BaseDirection | null } | null;
+        direction?: string | null;
+        dir?: string | null;
+        rtl?: boolean | null;
+        paragraphProperties?: { rightToLeft?: boolean | null } | null;
+      }
+    | null
+    | undefined,
+): BaseDirection | undefined {
+  const fromContext = attrs?.directionContext?.inlineDirection;
+  if (fromContext != null) return fromContext;
+  // AIDEV-NOTE: compat-fallback - used when ParagraphAttrs.directionContext.inlineDirection is absent.
+  // Retire once SD-2778 collapses the duplicate scalar fields onto directionContext.
+  const ppRtl = attrs?.paragraphProperties?.rightToLeft;
+  if (attrs?.direction === 'rtl' || attrs?.dir === 'rtl' || attrs?.rtl === true || ppRtl === true) {
+    return 'rtl';
+  }
+  if (attrs?.direction === 'ltr' || attrs?.dir === 'ltr' || attrs?.rtl === false || ppRtl === false) {
+    return 'ltr';
+  }
+  return undefined;
+}

packages/layout-engine/contracts/src/index.ts

@@ -16,6 +16,7 @@ export type {
   RunBidiContext,
   RunScriptContext,
 } from './direction-context.js';
+export { getParagraphInlineDirection } from './direction-context.js';
 import type { ParagraphDirectionContext, RunBidiContext, RunScriptContext } from './direction-context.js';
 
 // Export table contracts

packages/layout-engine/layout-bridge/src/cache.ts

@@ -1,16 +1,17 @@
-import type {
-  DrawingBlock,
-  FlowBlock,
-  ImageBlock,
-  ImageRun,
-  ListBlock,
-  TableBlock,
-  ParagraphBlock,
-  ParagraphAttrs,
-  ParagraphFrame,
-  TableAttrs,
-  TableCellAttrs,
-  Run,
+import {
+  getParagraphInlineDirection,
+  type DrawingBlock,
+  type FlowBlock,
+  type ImageBlock,
+  type ImageRun,
+  type ListBlock,
+  type TableBlock,
+  type ParagraphBlock,
+  type ParagraphAttrs,
+  type ParagraphFrame,
+  type TableAttrs,
+  type TableCellAttrs,
+  type Run,
 } from '@superdoc/contracts';
 import { fieldAnnotationKey } from './field-annotation-key.js';
 import { hasTrackedChange, resolveTrackedChangesEnabled } from './tracked-changes-utils.js';
@@ -392,7 +393,8 @@ const hashRuns = (block: FlowBlock): string => {
             }
 
             // Direction
-            if (attrs.direction) parts.push(`dir:${attrs.direction}`);
+            const cellDir = getParagraphInlineDirection(attrs);
+            if (cellDir) parts.push(`dir:${cellDir}`);
 
             if (parts.length > 0) {
               cellHashes.push(`pa:${parts.join(':')}`);
@@ -547,7 +549,8 @@ const hashRuns = (block: FlowBlock): string => {
     }
 
     // Direction
-    if (attrs.direction) parts.push(`dir:${attrs.direction}`);
+    const dir = getParagraphInlineDirection(attrs);
+    if (dir) parts.push(`dir:${dir}`);
 
     // Pagination properties
     if (attrs.keepNext) parts.push('kn');

packages/layout-engine/layout-bridge/src/paragraph-hash-utils.ts

@@ -1,12 +1,13 @@
-import type {
-  ParagraphAttrs,
-  ParagraphBorders,
-  ParagraphBorder,
-  Run,
-  TableBorders,
-  TableBorderValue,
-  CellBorders,
-  BorderSpec,
+import {
+  getParagraphInlineDirection,
+  type ParagraphAttrs,
+  type ParagraphBorders,
+  type ParagraphBorder,
+  type Run,
+  type TableBorders,
+  type TableBorderValue,
+  type CellBorders,
+  type BorderSpec,
 } from '@superdoc/contracts';
 
 /**
@@ -202,7 +203,8 @@ export const hashParagraphAttrs = (attrs: ParagraphAttrs | undefined): string =>
   }
 
   // Direction
-  if (attrs.direction) parts.push(`dir:${attrs.direction}`);
+  const dir = getParagraphInlineDirection(attrs);
+  if (dir) parts.push(`dir:${dir}`);
 
   return parts.join(':');
 };

packages/layout-engine/layout-resolved/src/versionSignature.ts

@@ -1,21 +1,22 @@
-import type {
-  DrawingBlock,
-  FieldAnnotationRun,
-  FlowBlock,
-  Fragment,
-  ImageBlock,
-  ImageDrawing,
-  ImageRun,
-  ParagraphAttrs,
-  ParagraphBlock,
-  SdtMetadata,
-  ShapeGroupDrawing,
-  SourceAnchor,
-  TableAttrs,
-  TableBlock,
-  TableCellAttrs,
-  TextRun,
-  VectorShapeDrawing,
+import {
+  getParagraphInlineDirection,
+  type DrawingBlock,
+  type FieldAnnotationRun,
+  type FlowBlock,
+  type Fragment,
+  type ImageBlock,
+  type ImageDrawing,
+  type ImageRun,
+  type ParagraphAttrs,
+  type ParagraphBlock,
+  type SdtMetadata,
+  type ShapeGroupDrawing,
+  type SourceAnchor,
+  type TableAttrs,
+  type TableBlock,
+  type TableCellAttrs,
+  type TextRun,
+  type VectorShapeDrawing,
 } from '@superdoc/contracts';
 import { hashParagraphBorders } from './paragraphBorderHash.js';
 import {
@@ -293,7 +294,7 @@ export const deriveBlockVersion = (block: FlowBlock): string => {
           attrs.borders ? hashParagraphBorders(attrs.borders) : '',
           attrs.shading?.fill ?? '',
           attrs.shading?.color ?? '',
-          attrs.direction ?? '',
+          getParagraphInlineDirection(attrs) ?? '',
           attrs.tabs?.length ? JSON.stringify(attrs.tabs) : '',
         ].join(':')
       : '';
@@ -437,7 +438,7 @@ export const deriveBlockVersion = (block: FlowBlock): string => {
               hash = hashNumber(hash, attrs.indent?.hanging ?? 0);
               hash = hashString(hash, attrs.shading?.fill ?? '');
               hash = hashString(hash, attrs.shading?.color ?? '');
-              hash = hashString(hash, attrs.direction ?? '');
+              hash = hashString(hash, getParagraphInlineDirection(attrs) ?? '');
               if (attrs.borders) {
                 hash = hashString(hash, hashParagraphBorders(attrs.borders));
               }

packages/layout-engine/painters/dom/src/features/rtl-paragraph/rtl-styles.ts

@@ -7,12 +7,13 @@
  * @ooxml w:pPr/w:bidi — paragraph bidirectional flag
  * @spec  ECMA-376 §17.3.1.1 (bidi)
  */
-import type { ParagraphAttrs } from '@superdoc/contracts';
+import { getParagraphInlineDirection, type ParagraphAttrs } from '@superdoc/contracts';
 
 /**
  * Returns true when the paragraph attributes indicate right-to-left direction.
  */
-export const isRtlParagraph = (attrs: ParagraphAttrs | undefined): boolean => attrs?.direction === 'rtl';
+export const isRtlParagraph = (attrs: ParagraphAttrs | undefined): boolean =>
+  getParagraphInlineDirection(attrs) === 'rtl';
 
 /**
  * Compute the effective CSS text-align for a paragraph.

packages/layout-engine/painters/dom/src/renderer.ts

@@ -61,6 +61,7 @@ import {
   computeLinePmRange,
   expandRunsForInlineNewlines,
   getCellSpacingPx,
+  getParagraphInlineDirection,
   normalizeColumnLayout,
   normalizeBaselineShift,
   resolveBaseFontSizeForVerticalText,
@@ -3178,7 +3179,7 @@ export class DomPainter {
             fragment.markerTextWidth,
             resolvedLine.indentOffset,
           );
-          const isRtl = block.attrs?.direction === 'rtl';
+          const isRtl = getParagraphInlineDirection(block.attrs) === 'rtl';
           const lineEl = this.renderLine(
             block,
             resolvedLine.line,
@@ -3285,7 +3286,7 @@ export class DomPainter {
         const paraIndent = block.attrs?.indent;
         const paraIndentLeft = paraIndent?.left ?? 0;
         const paraIndentRight = paraIndent?.right ?? 0;
-        const isRtl = block.attrs?.direction === 'rtl';
+        const isRtl = getParagraphInlineDirection(block.attrs) === 'rtl';
         const {
           anchorIndentPx: paraMarkerAnchorIndent,
           firstLinePx: markerFirstLine,
@@ -7774,7 +7775,7 @@ const deriveBlockVersion = (block: FlowBlock): string => {
           attrs.borders ? hashParagraphBorders(attrs.borders) : '',
           attrs.shading?.fill ?? '',
           attrs.shading?.color ?? '',
-          attrs.direction ?? '',
+          getParagraphInlineDirection(attrs) ?? '',
           attrs.tabs?.length ? JSON.stringify(attrs.tabs) : '',
         ].join(':')
       : '';
@@ -7960,7 +7961,7 @@ const deriveBlockVersion = (block: FlowBlock): string => {
               hash = hashNumber(hash, attrs.indent?.hanging ?? 0);
               hash = hashString(hash, attrs.shading?.fill ?? '');
               hash = hashString(hash, attrs.shading?.color ?? '');
-              hash = hashString(hash, attrs.direction ?? '');
+              hash = hashString(hash, getParagraphInlineDirection(attrs) ?? '');
               if (attrs.borders) {
                 hash = hashString(hash, hashParagraphBorders(attrs.borders));
               }

packages/layout-engine/pm-adapter/src/attributes/paragraph.test.ts

@@ -348,6 +348,37 @@ describe('computeParagraphAttrs', () => {
     expect(paragraphAttrs.direction).toBeUndefined();
   });
 
+  // SD-2777 invariant: pm-adapter must keep `direction` and
+  // `directionContext.inlineDirection` aligned (or both absent). This is the
+  // load-bearing property that lets `getParagraphInlineDirection` produce a
+  // hash byte-identical to the legacy `attrs.direction` read across the
+  // entire R2 corpus. If this breaks, the helper-based hash sites in
+  // layout-bridge / layout-resolved / painter-dom will drift from the
+  // pre-migration output.
+  describe('SD-2777: direction and directionContext.inlineDirection are paired', () => {
+    const cases: Array<{ name: string; rightToLeft: boolean | undefined; expected: 'rtl' | 'ltr' | undefined }> = [
+      { name: 'rightToLeft=true', rightToLeft: true, expected: 'rtl' },
+      { name: 'rightToLeft=false', rightToLeft: false, expected: 'ltr' },
+      { name: 'rightToLeft=undefined', rightToLeft: undefined, expected: undefined },
+    ];
+
+    for (const { name, rightToLeft, expected } of cases) {
+      it(`${name}: attrs.direction === directionContext.inlineDirection (${String(expected)})`, () => {
+        const paragraph: PMNode = {
+          type: { name: 'paragraph' },
+          attrs: {
+            paragraphProperties: rightToLeft === undefined ? {} : { rightToLeft },
+          },
+        };
+
+        const { paragraphAttrs } = computeParagraphAttrs(paragraph as never);
+
+        expect(paragraphAttrs.direction).toBe(expected);
+        expect(paragraphAttrs.directionContext?.inlineDirection).toBe(expected);
+      });
+    }
+  });
+
   it('inherits writing mode from body section context (§17.3.1.41)', () => {
     // When the paragraph omits w:textDirection, it should pick up writing-mode
     // from the section. This test feeds a pre-resolved sectionDirectionContext

packages/super-editor/src/editors/v1/core/presentation-editor/selection/CaretGeometry.ts

@@ -8,15 +8,16 @@ import {
   pmPosToCharOffset,
   extractParagraphIndent,
 } from '@superdoc/layout-bridge';
-import type {
-  FlowBlock,
-  Layout,
-  Line,
-  Measure,
-  ParaFragment,
-  TableBlock,
-  TableFragment,
-  TableMeasure,
+import {
+  getParagraphInlineDirection,
+  type FlowBlock,
+  type Layout,
+  type Line,
+  type Measure,
+  type ParaFragment,
+  type TableBlock,
+  type TableFragment,
+  type TableMeasure,
 } from '@superdoc/contracts';
 import { computeTableCaretLayoutRectFromDom } from '../tables/TableCaretDomGeometry.js';
 import { getPageElementByIndex } from '../../../dom-observer/PageDom.js';
@@ -196,7 +197,7 @@ export function computeCaretLayoutRectGeometry(
 
   const availableWidth = Math.max(0, fragment.width - (indentAdjust + indent.right));
   const charX = measureCharacterX(block, line, pmOffset, availableWidth);
-  const isRtlParagraph = block.attrs?.direction === 'rtl';
+  const isRtlParagraph = getParagraphInlineDirection(block.attrs) === 'rtl';
   const resolvedCharX = isRtlParagraph ? Math.max(0, availableWidth - charX) : charX;
   const localX = fragment.x + indentAdjust + resolvedCharX;
   const lineOffset = lineHeightBeforeIndex(measure.lines, fragment.fromLine, index);