feat(track-changes): block-level structural tracked changes for tables

[shri-scale]

Summary

Adds a new StructuralTrackChanges extension that gives block-level (table) add/remove operations the same review pipeline as inline tracked changes — same data-track-change rendering, same accept/reject command surface, plus block-level entry registration in the comments-plugin so the review UI surface has the data it needs.

• Consumer computes structural hunks (computeStructuralDiff or their own logic) and dispatches via editor.commands.setStructuralDiff(hunks).
• Extension stamps a trackChange PM attribute on each affected tableRow; painter reads it and stamps data-track-change* on cells; CSS styles them.
• Existing Diffing, compareDocuments, replayDifferences, and inline TrackChanges are untouched. New extension is opt-in via editorExtensions: [StructuralTrackChanges] (not in starter extensions).

What's in this PR

Layer	Change
Schema	Shared blockTrackedChangeAttrSpec helper; spread into TableRow.addAttributes
Contracts	TrackedChangeMeta.operationId? + TableRow.trackedChange?
pm-adapter	parseTableRow populates TableRow.trackedChange from the PM attr
painter-dom	renderTableRow stamps data-track-change* on each cell of a tracked row
CSS	[data-track-change="insert" | "delete"] rules, themable via --sd-block-tracked-*
Helpers	getBlockTrackedChanges, applyRowTrackedChangeResolution (in track-changes)
Extension	StructuralTrackChanges with setStructuralDiff, accept/reject by id, bulk, and operation-grouped commands
acceptTrackedChangeById / rejectTrackedChangeById	Extended to also route row-attr ids and operationIds (falls back through 3 paths: inline mark → row id → operationId)
trackedTransaction interceptor	Passes through ReplaceSteps whose slice already carries block-level trackChange attrs (no double-tracking)
Comments-plugin	Walks block-level entries alongside inline marks; populates pluginState.trackedChanges and allCommentPositions
Public API	StructuralTrackChanges, computeStructuralDiff re-exported from the v1 barrel

Test plan

• Run full super-editor suite: pnpm test from packages/super-editor/ — should be green (~13,000 tests).
• Targeted suites: pnpm vitest run blockTrackedChangeAttr getBlockTrackedChanges acceptRejectRowTrackedChange blockTrackedChangePassthrough computeStructuralDiff applyHunks structural-track-changes blockTrackedChangeBubble
• End-to-end fixture: pnpm vitest run structural-track-changes-e2e — exercises computeStructuralDiff → setStructuralDiff → acceptAllStructuralChanges / rejectAllStructuralChanges against a real .docx pair.
• Manual smoke (consumer pattern): in a SuperDoc instance with editorExtensions: [StructuralTrackChanges], dispatch a remove hunk via setStructuralDiff → the matching table's rows turn red. acceptAllStructuralChanges removes the table.

Out of scope (separate follow-ups)

• DOCX round-trip of block-level tracked changes (the schema attr survives through PM renderDOM/parseDOM, but no OOXML writer/reader is wired)
• Block-level entries surfacing in the default SuperDoc bubble. Plugin state has the entries, but inline tracked changes' bubble appears via an editor.emit('commentsUpdate', ...) payload pipeline that block-level changes don't yet emit. Consumers with custom review UI (al-pmo today) can wire from getBlockTrackedChanges directly.
• Cell-level / column-level tracking
• A combined acceptAllChanges that batches inline + structural into one transaction (currently two sequential commands; two undo steps)
• Smarter structural-fingerprint matcher for computeStructuralDiff when sdBlockIds differ across imports (consumer can supply a custom identityKey)

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b9d84246ae

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[shri-scale]

Hi @caio-pizzol, I know its big change, just kind request

[cubic-dev-ai]

2 issues found across 38 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/super-editor/src/editors/v1/extensions/track-changes/blockTrackedChangeAttr.js">

<violation number="1" location="packages/super-editor/src/editors/v1/extensions/track-changes/blockTrackedChangeAttr.js:13">
P2: Return `null` from `parseDOM` when `data-track-change-id` is absent. A tracked change without an id cannot be resolved by `acceptRejectRowTrackedChange` (which matches by id), leaving an unactionable entry in the document. Guarding on `id` also keeps the runtime shape consistent with the documented type (`id: string` when non-null).</violation>
</file>

<file name="packages/super-editor/src/editors/v1/extensions/track-changes/trackChangesHelpers/trackedTransaction.js">

<violation number="1" location="packages/super-editor/src/editors/v1/extensions/track-changes/trackChangesHelpers/trackedTransaction.js:381">
P1: Missing `map.appendMap(step.getMap())` after applying the step. In multi-step transactions, subsequent steps will be mapped using stale positions that don't account for the document changes made by this block-level step, potentially causing position corruption or silently dropped steps.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[shri-scale]

Hi @caio-pizzol , any idea when this will be reviewed? Appreciate if it can be expedited. thanks

[shri-scale]

HI @caio-pizzol Its been month this PR been up, rebasing/merging is tricky, and may infact cause more issues. Can you please expedite or direct on this PR ?

[caio-pizzol]

Hi @shri-scale, first, thank you for this, and I'm sorry it sat so long. This is a big, careful change, especially the test coverage. The honest reason for the delay is that it touches always-on paths: schema, comments plugin, painter, layout cache, and accept/reject. That meant we needed to verify the OOXML model and look closely at how this fits with what already exists in the editor.

The direction is right: OOXML represents inserted/deleted table rows with w:ins / w:del under w:trPr, with no table-level insert/delete marker. That matches the row-level model here.

The main issue is architectural: we already have a structural-row pipeline: enumerateStructuralRowChanges, the review graph, stampTableRows, and importer/exporter support in row-track-change.js. This PR adds a second model beside it: getBlockTrackedChanges, operationId, and applyHunks. Two parallel models can disagree. For example, an imported multi-row deleted table has per-row Word ids and no operationId, so the existing pipeline groups it as one structural table change while the new block walk can see separate row entries. Before merge, we'd want this built on the existing structural-row pipeline rather than beside it.

Concrete items:

1. In table-row.js, ...blockTrackedChangeAttrSpec is spread, then trackChange is redefined later with rendered: false. That means the helper's parse/render behavior is dead for table rows, so the DOM round-trip described in the PR does not actually happen for rows.

2. Please stamp/generated structural changes through the existing path, or otherwise align with it, so generated revisions carry the same metadata shape as native tracked table revisions: author/date/revision grouping and valid export behavior.

3. acceptAllTrackedChanges / rejectAllTrackedChanges currently return reviewDecision.applied, so a block-only change can mutate the document but report false.

4. The PR description is stale in two places: the extension is registered in getStarterExtensions(), and row-level OOXML reader/writer support already exists through the converter.

5. Paragraph support looks like a separate design question. OOXML paragraph-mark revisions are not the same primitive as table-row insert/delete revisions, so I'd prefer splitting that into its own PR with its own justification.

Happy to pair on the pipeline reconciliation. I don't think we should set a merge ETA until the structural-row integration direction is settled, but once that revision is up and CI is green, we should be able to do a focused re-review quickly.

For faster comms, let's try to connect on the side (discord, caio@superdoc.dev) - so make sure to give this the priority it needs

[shri-scale]

Hi @shri-scale, first, thank you for this, and I'm sorry it sat so long. This is a big, careful change, especially the test coverage. The honest reason for the delay is that it touches always-on paths: schema, comments plugin, painter, layout cache, and accept/reject. That meant we needed to verify the OOXML model and look closely at how this fits with what already exists in the editor.

The direction is right: OOXML represents inserted/deleted table rows with w:ins / w:del under w:trPr, with no table-level insert/delete marker. That matches the row-level model here.

The main issue is architectural: we already have a structural-row pipeline: enumerateStructuralRowChanges, the review graph, stampTableRows, and importer/exporter support in row-track-change.js. This PR adds a second model beside it: getBlockTrackedChanges, operationId, and applyHunks. Two parallel models can disagree. For example, an imported multi-row deleted table has per-row Word ids and no operationId, so the existing pipeline groups it as one structural table change while the new block walk can see separate row entries. Before merge, we'd want this built on the existing structural-row pipeline rather than beside it.

Concrete items:

1. In table-row.js, ...blockTrackedChangeAttrSpec is spread, then trackChange is redefined later with rendered: false. That means the helper's parse/render behavior is dead for table rows, so the DOM round-trip described in the PR does not actually happen for rows.
2. Please stamp/generated structural changes through the existing path, or otherwise align with it, so generated revisions carry the same metadata shape as native tracked table revisions: author/date/revision grouping and valid export behavior.
3. acceptAllTrackedChanges / rejectAllTrackedChanges currently return reviewDecision.applied, so a block-only change can mutate the document but report false.
4. The PR description is stale in two places: the extension is registered in getStarterExtensions(), and row-level OOXML reader/writer support already exists through the converter.
5. Paragraph support looks like a separate design question. OOXML paragraph-mark revisions are not the same primitive as table-row insert/delete revisions, so I'd prefer splitting that into its own PR with its own justification.

Happy to pair on the pipeline reconciliation. I don't think we should set a merge ETA until the structural-row integration direction is settled, but once that revision is up and CI is green, we should be able to do a focused re-review quickly.

For faster comms, let's try to connect on the side (discord, caio@superdoc.dev) - so make sure to give this the priority it needs

Hi @caio-pizzol — thanks for the careful review, you were right about the parallel model. Pushed a refactor that routes block-level changes through the existing structural-row pipeline instead of beside it.

Quick rundown of your points:

Parallel models — gone. getBlockTrackedChanges, the {kind} shape, the operationId field, and the blockTrackedChangeAttrSpec helper (plus the dead spreads in table-row.js and paragraph.js) are all deleted. applyHunks now just calls into stampTableRows, so generated and imported revisions go through the same path and carry the same OOXML shape.

Metadata + grouping — handled by stampTableRows. Author/date come from editor.options.user, and revisionGroupId groups multi-row table changes just like native ones.

acceptAll / rejectAll return-value bug — fixed. Block-level fallback dropped; everything routes through dispatchReviewDecision, so block-only changes both mutate the doc and return true. Same applies to the per-id variants.

PR description staleness — fair, will update it next.

Paragraph support — agreed, dropping it from this PR. Separate design as you suggested.

One small new export: enumerateStructuralRowChanges, so downstream consumers can read structural changes through the same pipeline (replaced our parallel block walk on our side).

Net diff: ~600 lines deleted, ~30 added. Smoke-tested end-to-end against our AI-review flow (single/multi-row insert + delete, per-pill accept/reject, mixed accept-all/reject-all). All clean.

Will reach out on discord — thanks again for taking the time on this.