refactor(direction): drop ParagraphAttrs.direction scalar field (SD-2778) (#3290)

* refactor(direction): centralize last paragraph isRtl reads on helper (SD-2778)

Migrate the two remaining direct reads of attrs.direction/.dir on the
paragraph inline-direction axis onto getParagraphInlineDirection:

- layout-bridge/src/position-hit.ts: isRtlBlock
- layout-resolved/src/resolveParagraph.ts: isRtl

Behavior is unchanged on the typed directionContext path and strictly
broader on fallback (the helper also covers paragraphProperties.rightToLeft).
After this, no consumer outside the helper reads the legacy scalar fields;
a follow-up can stop pm-adapter from writing them and drop them from
ParagraphAttrs.

* test(direction): pin SD-2778 migration via typed-path + broader-fallback cases

Two coverage gaps caught in review:

- layout-resolved/src/resolveLayout.test.ts ("preserves increasing
  first-line marker anchor for nested RTL list levels") used
  attrs.direction: 'rtl'. The pre-migration code read attrs.direction
  directly, so that fixture would have passed against the old
  implementation. Switch to directionContext.inlineDirection so the test
  only passes through the new helper-driven typed path.

- layout-bridge/test/position-hit.test.ts: switching isRtlBlock to
  getParagraphInlineDirection is strictly broader on fallback (the helper
  also picks up paragraphProperties.rightToLeft when no directionContext
  is present). Pin that case so the broadening is intentional and not a
  regression vector.

* refactor(direction): drop ParagraphAttrs.direction scalar field (SD-2778)

After #3289 centralized every paragraph isRtl read on
getParagraphInlineDirection, the scalar attrs.direction field has no
remaining consumers. Drop it from the producer and the type:

- pm-adapter no longer writes the conditional direction spread on
  ParagraphAttrs. directionContext.inlineDirection is the only source.
- contracts/index.ts: remove direction?: 'ltr' | 'rtl' from
  ParagraphAttrs and point the directionContext doc at the helper.
- contracts/direction-context.ts: tighten getParagraphInlineDirection's
  signature and body to drop the attrs.direction/.dir/.rtl fallbacks.
  paragraphProperties.rightToLeft fallback stays for PM-node / editor
  paths that read direction off the raw OOXML properties.

Tests that asserted on attrs.direction or constructed hand-rolled
FlowBlocks with { direction: 'rtl' } now use
directionContext.inlineDirection. Expect additive layout JSON snapshot
drift once the direction field disappears from paragraph attrs in
serialized layouts.

Tests: contracts 229, pm-adapter 1838, layout-bridge 1210,
layout-resolved 118, painter-dom 1070, super-editor 12836, style-engine
129 - all green.

* refactor(direction): finish dropping attrs.direction (diff.ts + stale fixtures)

Follow-up to 19b13fc. Two gaps caught on review:

- layout-bridge/src/diff.ts:372 still compared a.direction !== b.direction
  inside paragraphAttrsEqual. Vitest passed because esbuild/swc skips
  cross-package types; the tsup DTS build was the one that caught it.
  Migrate to getParagraphInlineDirection(a) !== getParagraphInlineDirection(b)
  so the diff respects directionContext + paragraphProperties fallback.

- Test fixtures across versionSignature.test.ts, rtl-date-parity.test.ts,
  cache.test.ts, and diff.test.ts still constructed hand-rolled FlowBlocks
  with { direction: 'rtl' }. They typecheck via Record<string, unknown>
  casts but no longer model the actual ParagraphAttrs shape. Migrate
  them all onto directionContext.

Build sweep (contracts → pm-adapter → layout-bridge → layout-resolved
→ painter-dom) now passes; tests still green across all five.

* docs(direction): retire ParagraphAttrs.direction mention in pm-adapter direction README

After SD-2778 drops the scalar `direction` field, the README sentence
that pointed consumers at it is stale. Point them at
`getParagraphInlineDirection` instead so the next reader lands on the
helper that knows about the typed context + paragraphProperties fallback.

* test(direction): pin producer contract that attrs.direction is not emitted

SD-2778 removes ParagraphAttrs.direction from the type, but TypeScript's
structural typing permits index-signature extra keys. Add a runtime
assertion inside the SD-2778 describe block that pm-adapter never emits
the legacy scalar field. Catches accidental re-introduction via a
future spread that TypeScript would let through.

Author: caio-pizzol

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

@@ -7,37 +7,24 @@ describe('getParagraphInlineDirection', () => {
     expect(getParagraphInlineDirection(null)).toBeUndefined();
   });
 
-  it('prefers directionContext.inlineDirection over legacy fields', () => {
+  it('prefers directionContext.inlineDirection over paragraphProperties.rightToLeft', () => {
     const attrs = {
       directionContext: { inlineDirection: 'rtl' as const },
-      direction: 'ltr',
-      rtl: false,
+      paragraphProperties: { rightToLeft: 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' };
+    // w:bidi"; paragraphProperties.rightToLeft is the PM-node/editor fallback.
+    const attrs = {
+      directionContext: { inlineDirection: null },
+      paragraphProperties: { rightToLeft: true },
+    };
     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');

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

@@ -161,9 +161,9 @@ export type RunScriptContext = {
  * 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.
+ * present. Falls back to `paragraphProperties.rightToLeft` for PM-node /
+ * editor paths that store direction on the raw OOXML properties rather
+ * than the typed direction context.
  *
  * Consumers should call this instead of inspecting attrs ad hoc so the
  * direction source check stays in one place.
@@ -172,25 +172,16 @@ 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';
-  }
+  if (ppRtl === true) return 'rtl';
+  if (ppRtl === false) return 'ltr';
   return undefined;
 }
 

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

@@ -1533,19 +1533,14 @@ export type ParagraphAttrs = {
   trackedChangesEnabled?: boolean;
   /** Marks an empty paragraph that only exists to carry section properties. */
   sectPrMarker?: boolean;
-  /**
-   * Resolved paragraph inline base direction. Populated from `directionContext.inlineDirection`
-   * during pm-adapter conversion; left undefined when no explicit bidi is set so the browser
-   * can apply UBA via missing `dir` attribute.
-   *
-   * Prefer reading `directionContext` (typed, complete) over this scalar field. The scalar
-   * remains for backwards compatibility with consumers that only need inline direction.
-   */
-  direction?: 'ltr' | 'rtl';
   /**
    * Resolved direction context for the paragraph (inline direction + writing mode).
    * Single source of truth for paragraph direction-aware rendering decisions.
    *
+   * Read via `getParagraphInlineDirection(attrs)` rather than inspecting this
+   * field directly so the helper can normalize `null` vs `undefined` and fall
+   * back to `paragraphProperties.rightToLeft` for PM-node / editor paths.
+   *
    * See `@superdoc/contracts/direction-context` for axis semantics.
    */
   directionContext?: ParagraphDirectionContext;

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

@@ -20,6 +20,7 @@ import type {
   DropCapDescriptor,
   ParagraphFrame,
 } from '@superdoc/contracts';
+import { getParagraphInlineDirection } from '@superdoc/contracts';
 import { fieldAnnotationKey } from './field-annotation-key.js';
 import { hashRunVisualMarks } from './run-visual-marks.js';
 import { hasTrackedChange, resolveTrackedChangesEnabled } from './tracked-changes-utils.js';
@@ -369,7 +370,7 @@ const paragraphAttrsEqual = (a?: ParagraphAttrs, b?: ParagraphAttrs): boolean =>
     a.tabIntervalTwips !== b.tabIntervalTwips ||
     a.keepNext !== b.keepNext ||
     a.keepLines !== b.keepLines ||
-    a.direction !== b.direction ||
+    getParagraphInlineDirection(a) !== getParagraphInlineDirection(b) ||
     a.floatAlignment !== b.floatAlignment
   ) {
     return false;

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

@@ -2024,8 +2024,12 @@ describe('MeasureCache', () => {
 
     describe('other paragraph attribute changes', () => {
       it('invalidates cache when direction changes', () => {
-        const block1 = paragraphWithAttrs('p1', 'Hello', { direction: 'ltr' });
-        const block2 = paragraphWithAttrs('p1', 'Hello', { direction: 'rtl' });
+        const block1 = paragraphWithAttrs('p1', 'Hello', {
+          directionContext: { inlineDirection: 'ltr', writingMode: 'horizontal-tb' },
+        });
+        const block2 = paragraphWithAttrs('p1', 'Hello', {
+          directionContext: { inlineDirection: 'rtl', writingMode: 'horizontal-tb' },
+        });
 
         cache.set(block1, 400, 600, { totalHeight: 20 });
         expect(cache.get(block2, 400, 600)).toBeUndefined();
@@ -2061,7 +2065,7 @@ describe('MeasureCache', () => {
             { val: 'end', pos: 8640, leader: 'dot' },
           ],
           keepNext: true,
-          direction: 'ltr',
+          directionContext: { inlineDirection: 'ltr', writingMode: 'horizontal-tb' },
         };
 
         const block1 = paragraphWithAttrs('p1', 'Hello', complexAttrs);

packages/layout-engine/layout-bridge/test/diff.test.ts

@@ -434,8 +434,16 @@ describe('computeDirtyRegions', () => {
 
     describe('other paragraph attribute changes', () => {
       it('detects direction change', () => {
-        const prev = [paragraphWithAttrs('p1', 'Hello', { direction: 'ltr' })];
-        const next = [paragraphWithAttrs('p1', 'Hello', { direction: 'rtl' })];
+        const prev = [
+          paragraphWithAttrs('p1', 'Hello', {
+            directionContext: { inlineDirection: 'ltr', writingMode: 'horizontal-tb' },
+          }),
+        ];
+        const next = [
+          paragraphWithAttrs('p1', 'Hello', {
+            directionContext: { inlineDirection: 'rtl', writingMode: 'horizontal-tb' },
+          }),
+        ];
         const result = computeDirtyRegions(prev, next);
         expect(result.firstDirtyIndex).toBe(0);
       });
@@ -492,7 +500,7 @@ describe('computeDirtyRegions', () => {
             { val: 'end' as const, pos: 8640, leader: 'dot' as const },
           ],
           keepNext: true,
-          direction: 'ltr' as const,
+          directionContext: { inlineDirection: 'ltr' as const, writingMode: 'horizontal-tb' as const },
         };
         const prev = [paragraphWithAttrs('p1', 'Hello', complexAttrs)];
         const next = [paragraphWithAttrs('p1', 'Hello', complexAttrs)];

packages/layout-engine/layout-bridge/test/position-hit.test.ts

@@ -23,19 +23,15 @@ describe('isRtlBlock', () => {
     ).toBe(true);
   });
 
-  it('keeps legacy paragraph direction as a fallback', () => {
-    expect(isRtlBlock(paragraph({ direction: 'rtl' }))).toBe(true);
-  });
-
   it('does not treat writing mode as inline RTL direction', () => {
     expect(isRtlBlock(paragraph({ textDirection: 'tbRl' }))).toBe(false);
   });
 
-  it('lets resolved direction context override legacy scalar direction', () => {
+  it('lets resolved direction context override paragraphProperties.rightToLeft', () => {
     expect(
       isRtlBlock(
         paragraph({
-          direction: 'rtl',
+          paragraphProperties: { rightToLeft: true },
           directionContext: {
             inlineDirection: 'ltr',
             writingMode: 'horizontal-tb',
@@ -45,14 +41,14 @@ describe('isRtlBlock', () => {
     ).toBe(false);
   });
 
-  it('falls through to legacy direction when directionContext.inlineDirection is undefined', () => {
+  it('falls through to paragraphProperties.rightToLeft when directionContext.inlineDirection is undefined', () => {
     // The resolver may produce inlineDirection: undefined when no paragraph w:bidi is set
     // anywhere in the cascade. In that case the typed context carries no inline-direction
-    // signal, and the legacy `direction` / `dir` field (if any) should still be honored.
+    // signal, and the PM-node paragraphProperties.rightToLeft fallback still applies.
     expect(
       isRtlBlock(
         paragraph({
-          direction: 'rtl',
+          paragraphProperties: { rightToLeft: true },
           directionContext: {
             inlineDirection: undefined,
             writingMode: 'horizontal-tb',

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

@@ -33,7 +33,7 @@ describe('deriveBlockVersion - bidi', () => {
   const makeParagraph = (bidi?: TextRun['bidi']): FlowBlock => ({
     kind: 'paragraph',
     id: 'p1',
-    attrs: { direction: 'rtl' },
+    attrs: { directionContext: { inlineDirection: 'rtl', writingMode: 'horizontal-tb' } },
     runs: [
       {
         text: '23.03.2026',

packages/layout-engine/painters/dom/src/formatting-marks.test.ts

@@ -159,7 +159,11 @@ describe('DomPainter formatting marks', () => {
 
     container.innerHTML = '';
     const rtlPainter = createDomPainter({
-      blocks: [createParagraphBlock(text, { direction: 'rtl' })],
+      blocks: [
+        createParagraphBlock(text, {
+          directionContext: { inlineDirection: 'rtl', writingMode: 'horizontal-tb' },
+        }),
+      ],
       measures: [measure],
       showFormattingMarks: true,
     });

packages/layout-engine/painters/dom/src/index.test.ts

@@ -5006,7 +5006,7 @@ describe('DomPainter', () => {
         ],
         attrs: {
           alignment: 'center',
-          direction: 'rtl',
+          directionContext: { inlineDirection: 'rtl', writingMode: 'horizontal-tb' },
         },
       };
       const footerMeasure: Measure = {
@@ -6072,7 +6072,7 @@ describe('DomPainter', () => {
         kind: 'paragraph',
         id: 'resolved-rtl-marker',
         runs: [{ text: 'RTL nested item', fontFamily: 'Arial', fontSize: 12, pmStart: 1, pmEnd: 16 }],
-        attrs: { direction: 'rtl' as const },
+        attrs: { directionContext: { inlineDirection: 'rtl', writingMode: 'horizontal-tb' } },
       };
 
       const paragraphMeasure: Measure = {
@@ -8536,7 +8536,7 @@ describe('DomPainter', () => {
       kind: 'paragraph',
       id: 'rtl-block',
       runs: [{ text: 'مرحبا', fontFamily: 'Arial', fontSize: 16 }],
-      attrs: { direction: 'rtl' as const, ...attrs },
+      attrs: { directionContext: { inlineDirection: 'rtl', writingMode: 'horizontal-tb' }, ...attrs },
     });
 
     const rtlMeasure: Measure = {
@@ -8591,7 +8591,7 @@ describe('DomPainter', () => {
           { kind: 'tab', width: 40, fontFamily: 'Arial', fontSize: 16 } as any,
           { text: 'عالم', fontFamily: 'Arial', fontSize: 16 },
         ],
-        attrs: { direction: 'rtl' as const },
+        attrs: { directionContext: { inlineDirection: 'rtl', writingMode: 'horizontal-tb' } },
       };
 
       const tabMeasure: Measure = {