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>

[cubic-dev-ai]

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.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/super-editor/src/editors/v1/extensions/track-changes/trackChangesHelpers/trackedTransaction.js, line 381:

<comment>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.</comment>

<file context>
@@ -349,6 +373,15 @@ export const trackedTransaction = ({ tr, state, user, replacements = 'paired' })
+    // Wrapping the inner cell content with inline trackInsert marks would
+    // double-track. Apply such steps as-is.
+    if (step instanceof ReplaceStep && sliceContainsPreMarkedBlockTrackedChange(step.slice)) {
+      newTr.step(step);
+      return;
+    }
</file context>

Suggested change

	newTr.step(step);
	newTr.step(step);
	map.appendMap(step.getMap());

[cubic-dev-ai]

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).

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/super-editor/src/editors/v1/extensions/track-changes/blockTrackedChangeAttr.js, line 13:

<comment>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).</comment>

<file context>
@@ -0,0 +1,33 @@
+  trackChange: {
+    default: null,
+    parseDOM: (el) => {
+      const kind = el.getAttribute('data-track-change');
+      if (kind !== 'insert' && kind !== 'delete') return null;
+      return {
</file context>