Combined release branch (@scale/superdoc): #3343 + #3714 + #3758 + #3750 + local fixes

FORK.md

@@ -0,0 +1,132 @@
+# SuperDoc fork — `@scale/superdoc`
+
+This is a **fork** of [`superdoc-dev/superdoc`](https://github.com/superdoc-dev/superdoc),
+maintained so the al-pmo (Dune PMO) correspondence editor can use unreleased
+upstream features plus a few local fixes **before** they land in an official
+SuperDoc release.
+
+The integration branch is **`release/combined-main`**. It is the branch al-pmo
+links against and the branch we publish from as the private package
+`@scale/superdoc`.
+
+> If you only want the one-line answer: al-pmo's tracked-change review needs
+> block-level (table/paragraph) tracked changes and a couple of fixes that are
+> spread across several open upstream PRs. This branch stacks them on one base
+> so we can build and consume a single package.
+
+---
+
+## What's on the branch
+
+Base = upstream `main` at merge-base `75297f6a0`. On top of that, in order:
+
+### Upstream PRs merged in
+
+| Upstream PR | Merge marker | What it provides | Why al-pmo needs it |
+|---|---|---|---|
+| **#3343** (block-level tracked changes) | `dd7c3d728`, tip `851b4b9e6` | Block-level structural tracked changes for **tables and paragraphs** (`StructuralTrackChanges`, `computeStructuralDiff`, `setStructuralDiff`) | Whole-paragraph / whole-table add+remove must be reviewable as a single change, not inline text edits that leave empty blocks behind |
+| **#3714** (direction) | `29918e8e9` | Auto-detect paragraph base direction (`dir="auto"`), resolve per paragraph | Correct RTL/LTR for Arabic correspondence |
+| **#3758** (linked styles) | `82681a861` | "Update to match" — redefine named paragraph styles; resolve effective formatting | Style fidelity on AI-proposed drafts |
+| **#3750** (context menu) | `e16a01dd7` | Open editor context menu on right-click over resize overlays | Editor UX |
+
+> #3343 is pinned at commit **`851b4b9`** specifically — the
+> *paragraph-capable* revision of the block-tracked-changes work. Earlier
+> revisions only handled tables; rebasing onto `851b4b9` is what restored
+> bullet/paragraph block tracking.
+
+### Local fixes on top (NOT in any upstream PR)
+
+| Commit | Change |
+|---|---|
+| `576e0cd95` | `fix(track-changes)`: use the first **non-empty** run's marks for a tracked replace (avoids a blank-run mark wiping replacement styling) |
+| _(this commit)_ | `fix(track-changes)`: resolve inline **and** block tracked changes in **one atomic** accept-all / reject-all transaction — fixes the "accept-all needs two clicks" bug (see below) |
+| _(this commit)_ | `chore`: scope the published package as **`@scale/superdoc`** |
+
+#### Atomic accept-all / reject-all
+
+`acceptAllTrackedChanges` / `rejectAllTrackedChanges` previously resolved inline
+marks in one transaction and block-level (row/paragraph) changes in a second
+one. The second transaction raced the first and was dropped as a mismatched
+transaction, so a mixed inline+block review needed multiple clicks to fully
+resolve. `dispatchReviewDecision` now accepts an `appendToTr` callback so the
+block resolution (`applyRowTrackedChangeResolution`) is appended onto the **same**
+transaction, with a fallback path for the block-only case.
+
+Files:
+- `packages/super-editor/src/editors/v1/extensions/track-changes/track-changes.js`
+
+---
+
+## How al-pmo consumes this fork
+
+al-pmo (`ips-applications/applications/dune/al-pmo/frontend`) depends on
+`@scale/superdoc`. For local development it uses a **`link:` override** in
+`frontend/package.json` pointing at this working tree, so fork changes are
+picked up after a rebuild — no publish needed to iterate.
+
+The al-pmo side also carries its own **diff layer** that drives these fork
+primitives (`paragraph-diff.ts`, `superdoc-adapter.ts`,
+`shared-doc-canvas.tsx`): paragraph/alignment/list detection, numbering-marker
+merge, and table-in-place pinning. That logic lives in al-pmo, not here — see
+al-pmo's `docs/SUPERDOC_TRACKED_REPLACE_STYLE_FIX.md`.
+
+> Longer term, much of that al-pmo diff layer overlaps with this fork's native
+> `compareDocuments` + `replayDifferences` engine
+> (`packages/super-editor/src/editors/v1/extensions/diffing/`), which already
+> does recursive, attribute-aware diffing (alignment, lists, table rows) and
+> replays it as native tracked changes. Migrating al-pmo onto that engine is a
+> tracked follow-up.
+
+---
+
+## Working with the branch
+
+```bash
+# remotes
+#   origin   = github.com/dawidbudaszewski/superdoc  (this fork)
+#   upstream = github.com/superdoc-dev/superdoc       (real SuperDoc)
+
+git checkout release/combined-main
+
+# build the package al-pmo links against
+pnpm install
+pnpm --filter @scale/superdoc run build   # see packages/superdoc/package.json scripts
+```
+
+### Adding another upstream PR
+
+```bash
+git fetch upstream pull/<PR>/head:pr-<PR>
+git merge --no-ff pr-<PR> -m "chore: merge pr-<PR> into combined branch"
+# rebuild, relink, smoke-test in al-pmo
+```
+
+### Publishing as `@scale/superdoc`
+
+Publish **from this branch (`release/combined-main`)** — no rebuild. The
+mechanics live in al-pmo's `scripts/superdoc` (so the rename rules stay in one
+place); see that folder's `README.md` → *"Manual publish from
+`release/combined-main` (no rebuild)"* for the exact commands. In short:
+
+1. `apply-scale-namespace.mjs "$PWD" <N>` — transient `@scale` rename + `-scale.N`
+   version stamp (core and react get **different** base versions).
+2. `pnpm install --no-frozen-lockfile` then build both `@scale/superdoc` and
+   `@scale/superdoc-react`.
+3. Auth to CodeArtifact and `pnpm publish` both (core first; react pins the exact
+   core version).
+4. `git checkout -- .` to revert the rename — the `@scale` rename is **never
+   committed**.
+
+Then in al-pmo drop the `link:` override in `frontend/package.json`, pin **both**
+published `-scale.N` versions, and `pnpm install`.
+
+---
+
+## Status / caveats
+
+- This branch is **ahead of upstream** and is **not** itself an upstream PR.
+  The block-tracked-changes feature exists upstream as PR #3343; the combined
+  branch and the local fixes do not.
+- Keep the branch buildable: after any merge or fix, rebuild and smoke-test the
+  al-pmo tracked-change review (bullets, signature alignment, table row
+  remove, accept-all in one click).

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

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { cloneColumnLayout, extractHeaderFooterSpace, normalizeColumnLayout, widthsEqual } from './index.js';
-import type { FlowBlock, Layout } from './index.js';
+import type { FlowBlock, Layout, TableRow, TrackedChangeMeta } from './index.js';
 
 describe('contracts', () => {
   it('accepts a basic FlowBlock structure', () => {
@@ -85,4 +85,18 @@ describe('contracts', () => {
     });
     expect(normalizeColumnLayout({ count: 2, gap: 24 }, 624).widths).toEqual([300, 300]);
   });
+
+  it('TrackedChangeMeta accepts an optional operationId', () => {
+    const meta: TrackedChangeMeta = { kind: 'delete', id: 'r1', operationId: 'op-table-1' };
+    expect(meta.operationId).toBe('op-table-1');
+  });
+
+  it('TableRow accepts an optional trackedChange field carrying row-level metadata', () => {
+    const row: TableRow = {
+      id: 'row-1',
+      cells: [],
+      trackedChange: { kind: 'insert', id: 'r1', operationId: 'op-table-1' },
+    };
+    expect(row.trackedChange?.kind).toBe('insert');
+  });
 });

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

@@ -366,6 +366,12 @@ export type TrackedChangeMeta = {
   id: string;
   overlapParentId?: string;
   relationship?: 'parent' | 'child' | 'standalone';
+  /**
+   * Optional grouping key. Tracked changes sharing a non-empty `operationId`
+   * are resolved together — e.g. every row of a deleted table shares one
+   * `operationId` and the review surface collapses them into one entry.
+   */
+  operationId?: string;
   /**
    * Internal story key identifying which content story owns this tracked
    * change (`'body'`, `'hf:part:…'`, `'fn:…'`, `'en:…'`).
@@ -926,6 +932,12 @@ export type TableRow = {
   cells: TableCell[];
   attrs?: TableRowAttrs;
   sourceAnchor?: SourceAnchor;
+  /**
+   * Row-level tracked-change metadata. Populated by pm-adapter from the
+   * ProseMirror `trackChange` node attribute. The painter reads this and
+   * stamps `data-track-change*` on the cell DOM elements.
+   */
+  trackedChange?: TrackedChangeMeta;
 };
 
 export type TableBlock = {

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

@@ -306,6 +306,21 @@ const hashRuns = (block: FlowBlock): string => {
         continue;
       }
 
+      // Row-level tracked change (block-level diff replay sets `trackedChange`
+      // on a tableRow's attrs). Without folding it into the measure-cache
+      // fingerprint, applyHunks-style transactions that only mutate the row's
+      // `trackChange` attr don't invalidate the cache, so the page is never
+      // re-measured and the visible cells never receive their decoration
+      // classes. Read from `row.attrs.trackedChange` — the canonical location
+      // written by the v1 layout-adapter from the OOXML-aligned
+      // `attrs.trackChange.type` shape. Mirror of the painter page-fingerprint
+      // fix in renderer.ts and the canonical-version fix in
+      // layout-resolved/versionSignature.ts.
+      const rowTC = row.attrs?.trackedChange;
+      if (rowTC) {
+        cellHashes.push(`rtc:${rowTC.kind ?? ''}:${rowTC.id ?? ''}:${rowTC.operationId ?? ''}`);
+      }
+
       for (const cell of row.cells) {
         // Include cell-level attributes that affect rendering (borders, padding, etc.)
         // This ensures cache invalidation when cell formatting changes (e.g., remove borders).

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

@@ -533,6 +533,20 @@ export const deriveBlockVersion = (block: FlowBlock): string => {
     for (const row of rows) {
       if (!row || !Array.isArray(row.cells)) continue;
       hash = hashNumber(hash, row.cells.length);
+      // Row-level tracked change (block-level diff replay sets `trackedChange`
+      // on a tableRow's attrs). Without folding it into the canonical block
+      // version, applyHunks-style transactions that only mutate the row's
+      // `trackChange` attr don't bump the version, so the resolved-layout
+      // pipeline reuses cached entries and the painter never sees the update.
+      // Read from `row.attrs.trackedChange` — the canonical location written
+      // by the v1 layout-adapter from the OOXML-aligned `attrs.trackChange.type`
+      // shape. Mirror of the fixes in renderer.ts and layout-bridge/cache.ts.
+      const rowTC = row.attrs?.trackedChange;
+      if (rowTC) {
+        hash = hashString(hash, rowTC.kind ?? '');
+        hash = hashString(hash, rowTC.id ?? '');
+        hash = hashString(hash, rowTC.operationId ?? '');
+      }
       for (const cell of row.cells) {
         if (!cell) continue;
         const cellBlocks = cell.blocks ?? (cell.paragraph ? [cell.paragraph] : []);

packages/layout-engine/painters/dom/src/features/inline-direction/rtl-styles.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'vitest';
+import { applyRtlStyles, resolveTextAlign } from './rtl-styles.js';
+
+const el = () => document.createElement('p');
+const rtlAttrs = { paragraphProperties: { rightToLeft: true } };
+const ltrAttrs = { paragraphProperties: { rightToLeft: false } };
+const unsetAttrs = { paragraphProperties: {} };
+
+describe('applyRtlStyles direction mapping', () => {
+  it('sets dir="rtl" and direction:rtl for explicit RTL', () => {
+    const element = el();
+    expect(applyRtlStyles(element, rtlAttrs as any)).toBe(true);
+    expect(element.getAttribute('dir')).toBe('rtl');
+    expect(element.style.direction).toBe('rtl');
+  });
+
+  it('sets dir="ltr" for explicit LTR', () => {
+    const element = el();
+    expect(applyRtlStyles(element, ltrAttrs as any)).toBe(false);
+    expect(element.getAttribute('dir')).toBe('ltr');
+    expect(element.style.direction).toBe('ltr');
+  });
+
+  it('sets dir="auto" for unset paragraphs (wrapper)', () => {
+    const element = el();
+    expect(applyRtlStyles(element, unsetAttrs as any)).toBe(false);
+    expect(element.getAttribute('dir')).toBe('auto');
+    expect(element.style.direction).toBe('');
+  });
+
+  it('inheritAuto: leaves dir unset for unset paragraphs (line inherits wrapper)', () => {
+    const element = el();
+    expect(applyRtlStyles(element, unsetAttrs as any, true)).toBe(false);
+    expect(element.getAttribute('dir')).toBeNull();
+    expect(element.style.direction).toBe('');
+  });
+
+  it('inheritAuto: still stamps explicit rtl/ltr on lines', () => {
+    const r = el();
+    applyRtlStyles(r, rtlAttrs as any, true);
+    expect(r.getAttribute('dir')).toBe('rtl');
+    const l = el();
+    applyRtlStyles(l, ltrAttrs as any, true);
+    expect(l.getAttribute('dir')).toBe('ltr');
+  });
+});
+
+describe('resolveTextAlign with auto', () => {
+  it('returns start for default alignment when direction is auto', () => {
+    expect(resolveTextAlign(undefined, false, true)).toBe('start');
+  });
+  it('keeps explicit alignment under auto', () => {
+    expect(resolveTextAlign('center', false, true)).toBe('center');
+  });
+  it('unchanged for explicit directions', () => {
+    expect(resolveTextAlign('justify', true)).toBe('right');
+    expect(resolveTextAlign('justify', false)).toBe('left');
+  });
+});

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

@@ -22,14 +22,17 @@ export const isRtlParagraph = (attrs: ParagraphAttrs | undefined): boolean =>
  * becomes 'left' (LTR) or 'right' (RTL) to align the last line correctly.
  * When no explicit alignment is set the default follows the paragraph direction.
  */
-export const resolveTextAlign = (alignment: ParagraphAttrs['alignment'], isRtl: boolean): string => {
+export const resolveTextAlign = (alignment: ParagraphAttrs['alignment'], isRtl: boolean, isAuto = false): string => {
   switch (alignment) {
     case 'center':
     case 'right':
     case 'left':
       return alignment;
     case 'justify':
     default:
+      // For auto-direction paragraphs we don't know the resolved side at paint
+      // time — `start` follows the browser-resolved `dir="auto"`.
+      if (isAuto) return 'start';
       return isRtl ? 'right' : 'left';
   }
 };
@@ -38,17 +41,39 @@ export const resolveTextAlign = (alignment: ParagraphAttrs['alignment'], isRtl:
  * Apply `dir` and `text-align` to an element based on paragraph attributes.
  * Used by both `renderLine` (line elements) and `applyParagraphBlockStyles`
  * (fragment wrappers) so the logic stays in one place.
+ *
+ * `inheritAuto` is set for per-line elements: a paragraph with no explicit
+ * direction must resolve its base direction ONCE (on the paragraph wrapper via
+ * `dir="auto"`); the individual visual lines then inherit it. Stamping
+ * `dir="auto"` on each line would make every wrapped line re-detect from its
+ * own first strong character, so an RTL paragraph whose continuation line
+ * begins with Latin text would wrongly flip to LTR.
  */
-export const applyRtlStyles = (element: HTMLElement, attrs: ParagraphAttrs | undefined): boolean => {
-  const rtl = isRtlParagraph(attrs);
-  if (rtl) {
+export const applyRtlStyles = (
+  element: HTMLElement,
+  attrs: ParagraphAttrs | undefined,
+  inheritAuto = false,
+): boolean => {
+  const dir = getParagraphInlineDirection(attrs); // 'rtl' | 'ltr' | undefined
+  const rtl = dir === 'rtl';
+  if (dir === 'rtl') {
     element.setAttribute('dir', 'rtl');
     element.style.direction = 'rtl';
-  } else {
+  } else if (dir === 'ltr') {
+    element.setAttribute('dir', 'ltr');
+    element.style.direction = 'ltr';
+  } else if (inheritAuto) {
+    // Line-level: inherit the paragraph wrapper's resolved auto direction
+    // rather than independently auto-detecting per visual line.
     element.removeAttribute('dir');
     element.style.direction = '';
+  } else {
+    // Paragraph wrapper: let the browser detect base direction from content
+    // (dir="auto"). An absent dir would inherit the container direction instead.
+    element.setAttribute('dir', 'auto');
+    element.style.direction = '';
   }
-  element.style.textAlign = resolveTextAlign(attrs?.alignment, rtl);
+  element.style.textAlign = resolveTextAlign(attrs?.alignment, rtl, dir === undefined);
   return rtl;
 };
 

packages/layout-engine/painters/dom/src/paragraph/renderParagraphFragment.ts

@@ -5,6 +5,7 @@ import type {
   ParagraphMeasure,
   ResolvedFragmentItem,
   SdtMetadata,
+  TrackedChangeMeta,
 } from '@superdoc/contracts';
 import { isMinimalWordLayout as isMinimalWordLayoutShared } from '@superdoc/common/list-marker-utils';
 import type { MinimalWordLayout } from '@superdoc/common/list-marker-utils';
@@ -13,6 +14,7 @@ import { DOM_CLASS_NAMES } from '@superdoc/dom-contract';
 import { CLASS_NAMES, fragmentStyles } from '../styles.js';
 import { shouldRenderSdtContainerChrome, type SdtBoundaryOptions } from '../sdt/container.js';
 import { allowFontSynthesis } from '../runs/font-synthesis.js';
+import { applyBlockTrackedChangeToParagraph, resolveTrackedChangesConfig } from '../runs/tracked-changes.js';
 import type { BetweenBorderInfo } from './borders/index.js';
 import { renderParagraphContent, type ParagraphRenderLineInput } from './renderParagraphContent.js';
 
@@ -152,6 +154,16 @@ export const renderParagraphFragment = (params: RenderParagraphFragmentParams):
       contentControlsChrome,
     });
 
+    // Whole-paragraph structural tracked change (insert/delete). The adapter
+    // stamped paint-ready meta onto block.attrs.trackedChange; decorate the
+    // fragment so a deleted paragraph strikes through (and collapses in 'final'
+    // mode) instead of leaving an empty bullet — the paragraph analogue of the
+    // row-cell decoration.
+    const blockTrackedChange = (block.attrs as { trackedChange?: TrackedChangeMeta } | undefined)?.trackedChange;
+    if (blockTrackedChange) {
+      applyBlockTrackedChangeToParagraph(fragmentEl, blockTrackedChange, resolveTrackedChangesConfig(block));
+    }
+
     return fragmentEl;
   } catch (error) {
     console.error('[DomPainter] Fragment rendering failed:', { fragment, error });