Render a paired tracked move as a move, not as an unrelated delete plus insert

[nandoofz]

Environment: superdoc@2.12.0 + @superdoc/react@2.7.0 (@superdoc/docx-engine@0.11.0), browser adapter.

Follow-up to #3709, which fixed the serious half: moved text no longer disappears on import. Thank you for that. This is about the other half.

What happens now

A tracked move imported from a .docx renders as an unrelated deletion at the source and an unrelated insertion at the destination. Nothing links them and nothing marks them as a move, so a reader cannot tell "this passage moved" from "this passage was deleted and a similar one was added somewhere else".

Why this looks like a small step rather than a new feature

Most of it already exists:

• --sd-tracked-changes-move-from-* and --sd-tracked-changes-move-to-* theme variables, with #00853d as their default.
• modules.trackChanges.semanticColors accepts move, move-from and move-to as override keys, and move is documented as a group key for both sides.
• The types model the pairing in full: TrackChangeMoveSides { source, destination }, TrackChangeMoveSide, TrackChangeMoveTarget, role: 'move-source' | 'move-destination', moveDirection: 'up' | 'down'.
• The published docx-engine bundle carries the runtime plumbing for it, not only the declarations (movePair, move-source, move-destination, moveDirection all appear as runtime strings).

What appears to be missing is the pairing at render time. The layout path looks the move wrapper up in a map keyed by w:id plus 'delete' | 'insert', and when the lookup misses it renders the side with plain insert or delete visibility and no semantic metadata, then pushes a diagnostic:

render.tracked-move.annotation-unmatched
Tracked move wrapper w:moveFrom|w:moveTo has no matching annotation;
rendered with <insert|delete> visibility and no semantic metadata

With no semanticColorKey on the layer, the move colours above are never reached.

Ask

When the pair does resolve, stamp the move semantic keys on both sides so the existing colours and the existing semanticColors config apply. That would make a move visually distinguishable from a delete plus an insert without any new theming surface.

This looks adjacent to the unpaired-move follow-up mentioned when #3709 was closed, so it may already be in scope there.

A related question

Does trackChanges.list() populate move, role and moveDirection today for an imported move, even while the render does not use them? If it does, a host can build its own affordance in the meantime, which would take the pressure off. We could not confirm it either way: the headless SDK did not finish opening our test document within five minutes (which may itself be #3900), and a hand-built minimal .docx was rejected with "source loading is not applicable for this document".

Steps to reproduce

The synthetic body from #3709 reproduces it. A pending move whose two sides share a w:name on the range markers:

<w:p>
  <w:r><w:t xml:space="preserve">Alpha one shall provide the services to beta two.</w:t></w:r>
</w:p>
<w:p>
  <w:moveFromRangeStart w:id="102" w:author="A. Author" w:date="2026-04-05T12:39:00Z" w:name="move1"/>
  <w:moveFrom w:id="103" w:author="A. Author" w:date="2026-04-05T12:39:00Z">
    <w:r><w:t xml:space="preserve">Gamma three means delta four and epsilon five acting on its behalf.</w:t></w:r>
  </w:moveFrom>
  <w:moveFromRangeEnd w:id="102"/>
</w:p>
<w:p>
  <w:moveToRangeStart w:id="105" w:author="A. Author" w:date="2026-04-05T12:39:00Z" w:name="move1"/>
  <w:moveTo w:id="106" w:author="A. Author" w:date="2026-04-05T12:39:00Z">
    <w:r><w:t xml:space="preserve">Gamma three means delta four and epsilon five acting on its behalf.</w:t></w:r>
  </w:moveTo>
  <w:moveToRangeEnd w:id="105"/>
</w:p>

Observed: the source side renders as a pending deletion, the destination as a pending insertion, neither in the move colours. Expected: both sides carry the move semantic keys, so move-from and move-to colour them and the two are recognisable as one move.

[nandoofz]

Answering the question at the end of this issue, since we can now measure it: yes, trackChanges.list() populates the pairing today, and it does so completely.

Measured on a document reporting 439 tracked changes:

• 2 rows with type: 'move'
• 2 rows whose navigationTarget.role is move-source or move-destination
• 2 rows where move.source and move.destination are both non-null
• 0 rows where only one of the two sides resolved

So the read model reconstructs the pair correctly. Only the render does not use it, which lines up with the diagnostic quoted above: render.tracked-move.annotation-unmatched is a lookup miss in the layout path, not missing data.

That narrows this issue usefully. It is not a new feature, it is stamping the semantic keys onto a pair the read model has already resolved. And in the meantime it means a host can build its own move affordance from the list plus ui.viewport.getRect, which is what we are going to do while this is open.

One thing the counts alone do not settle: whether those two rows are two separate moves, each carrying both of its sides, or one move represented as two rows that each carry both sides. If one logical row per move is the intended shape, the second reading would be a separate defect. Happy to dig further if that is useful to you.

[nandoofz]

We measured this from both ends, in the DOM of a real document and in its OOXML, and the two agree on a number that makes the ask much more specific than the one in the issue body. Sharing it because it narrows the fix a lot.

What is painted today

After scrolling to the move so its pages are mounted, the painted DOM carries exactly FOUR elements with move semantics: data-track-change-type="move" and data-track-change-semantic-color-key of move-from and move-to. They are found under the public ids of the two rows trackChanges.list() reports, and they render in the default move green.

The moved passage itself renders in the insertion colour, with no move key on it.

Why four

The source file marks the passage with w:moveFromRangeStart / w:moveFromRangeEnd and w:moveToRangeStart / w:moveToRangeEnd, and carries four self-closing w:moveFrom / w:moveTo elements inside w:pPr/w:rPr. Those four are paragraph marks. The moved text is not inside any move wrapper at all: it sits in ordinary runs BETWEEN the range markers.

So the four painted elements are the four paragraph marks, and the render is behaving exactly as its own annotation lookup implies: a wrapper it can pair gets the move key, and there is no wrapper around the text to pair.

Why this matters for the ask

The issue asks for the move semantic keys to be stamped when the pair resolves. That is necessary and, on this evidence, not sufficient: for a file in this shape there is no per-run wrapper to stamp, so stamping on wrapper resolution alone leaves the passage exactly as it is now.

What would colour the passage is interpreting the RANGE, not the wrapper: everything between w:moveFromRangeStart and w:moveFromRangeEnd belongs to the move-from side, and likewise for move-to. Word colours the passage this way, which is why the same file reads as a move there and as an insertion here.

Two smaller notes from the same measurement

Your own hover card already labels the passage Moved (insertion), so the pairing information does reach the UI layer. The gap is the colour on the text, not the knowledge.

trackChanges.list() populates the pair correctly: two rows sharing one move.pairId, both with moveDirection, both with move.source and move.destination resolved. What it does NOT populate is target, which TrackChangeMoveTarget declares as source: TextTarget | null and destination: TextTarget | null. Both are absent, so a host cannot get the text coordinates of either side from the list. And ui.viewport.getRect refuses a tracked-change entity address with invalid-target, which matches the note on entityAt's positional form that entity addresses are not resolvable by getRect. Between those two, a host has no supported way to locate the two halves in order to paint them itself, which is why this is being asked of the renderer.

[caio-pizzol]

Thanks for reporting this, @nandoofz. We confirmed a bug in SuperDoc 2.12 and 2.13 where a tracked move spanning multiple paragraphs only gets move styling on the first paragraph at each end; the remaining paragraphs appear as ordinary deletions and insertions. We’ve logged this for engineering. This may explain what you’re seeing, though we’d need your original document to confirm it’s the same issue.

[nandoofz]

Thanks for confirming the multi-paragraph bug. Two things: we cannot share the source document, and we have to correct a detail in our earlier comment that may have pointed you away from exactly the bug you just described.

Correction

Above we wrote that the moved text "is not inside any move wrapper at all: it sits in ordinary runs BETWEEN the range markers." That is wrong. We re-measured the file by walking the tags in order rather than pairing them with one regular expression, and a self-closing marker was being counted as an opening tag, which is what produced the earlier claim.

The actual shape, per side, and moveFrom and moveTo are symmetric:

Element	Count
<w:moveFromRangeStart> / <w:moveFromRangeEnd>	1 / 1, sharing w:name
self-closing <w:moveFrom/> inside w:pPr/w:rPr (paragraph marks)	2
<w:moveFrom> wrappers containing runs	2

The two wrappers hold one run each, of 3 and 97 characters. So the move spans three paragraphs per side, the moved runs are wrapped, and the total moved text is 100 characters per side.

Why that matches your finding

This is the multi-paragraph case you described. In the painted DOM we counted exactly four elements carrying data-track-change-type="move" and a move-from / move-to semantic colour key, across both ends. With two wrappers plus two paragraph marks per side, four is the count you get when only the first paragraph at each end is styled. The remaining wrapper, the 97-character one, renders in the insertion or deletion colour, which is the visible symptom from the issue body.

So the ask in the issue body narrows to what you already logged, and our earlier "there is no wrapper to pair" reasoning does not apply. Sorry for the detour.

On the document

We cannot attach the original: it is third-party material under confidentiality, and that is not something we can work around. What we can do is build a synthetic fixture with the shape above, three paragraphs per side, two wrappers and two paragraph marks each, produced by the same Word compare feature that produced ours. Say the word and we will put it together.

For anyone reproducing without a fixture: the distinguishing feature is a move whose range spans a paragraph boundary, so the source and destination each end up with more than one <w:moveFrom> / <w:moveTo> wrapper. A single-paragraph move has one wrapper per side and will not show the bug.

[nandoofz]

Here is the synthetic fixture we offered, inline, since the issue API takes no attachments.

It reproduces the shape we measured on the file we cannot share: per side, one range marker pair sharing w:name, two self-closing markers on paragraph marks, and two wrappers holding the moved runs, so the move spans three paragraphs at each end.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml" mc:Ignorable="w14" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006">
<w:body>
<w:p>
<w:r><w:t xml:space="preserve">Fixture A. A tracked move whose range spans three paragraphs on each side.</w:t>
</w:r>
</w:p>
<w:p>
<w:r><w:t xml:space="preserve">Destination follows.</w:t>
</w:r>
</w:p>
<w:p>
<w:pPr>
<w:rPr>
<w:moveTo w:id="102" w:author="Fixture Author" w:date="2026-01-01T00:00:00Z"/>
</w:rPr>
</w:pPr>
<w:r><w:t xml:space="preserve">Paragraph one of the to side keeps this text </w:t>
</w:r>
<w:moveToRangeStart w:id="101" w:author="Fixture Author" w:date="2026-01-01T00:00:00Z" w:name="moveFixtureA"/>
<w:moveTo w:id="104" w:author="Fixture Author" w:date="2026-01-01T00:00:00Z">
<w:r><w:t xml:space="preserve">and</w:t>
</w:r>
</w:moveTo>
</w:p>
<w:p>
<w:pPr>
<w:rPr>
<w:moveTo w:id="103" w:author="Fixture Author" w:date="2026-01-01T00:00:00Z"/>
</w:rPr>
</w:pPr>
</w:p>
<w:p>
<w:moveTo w:id="105" w:author="Fixture Author" w:date="2026-01-01T00:00:00Z">
<w:r><w:t xml:space="preserve">the receiving party shall keep the disclosed materials in a secure place for the agreed period.</w:t>
</w:r>
</w:moveTo>
<w:moveToRangeEnd w:id="101"/>
<w:r><w:t xml:space="preserve"> Paragraph three keeps this text.</w:t>
</w:r>
</w:p>
<w:p>
<w:r><w:t xml:space="preserve">Filler between the two sides.</w:t>
</w:r>
</w:p>
<w:p>
<w:r><w:t xml:space="preserve">Source follows.</w:t>
</w:r>
</w:p>
<w:p>
<w:pPr>
<w:rPr>
<w:moveFrom w:id="202" w:author="Fixture Author" w:date="2026-01-01T00:00:00Z"/>
</w:rPr>
</w:pPr>
<w:r><w:t xml:space="preserve">Paragraph one of the from side keeps this text </w:t>
</w:r>
<w:moveFromRangeStart w:id="201" w:author="Fixture Author" w:date="2026-01-01T00:00:00Z" w:name="moveFixtureA"/>
<w:moveFrom w:id="204" w:author="Fixture Author" w:date="2026-01-01T00:00:00Z">
<w:r><w:t xml:space="preserve">and</w:t>
</w:r>
</w:moveFrom>
</w:p>
<w:p>
<w:pPr>
<w:rPr>
<w:moveFrom w:id="203" w:author="Fixture Author" w:date="2026-01-01T00:00:00Z"/>
</w:rPr>
</w:pPr>
</w:p>
<w:p>
<w:moveFrom w:id="205" w:author="Fixture Author" w:date="2026-01-01T00:00:00Z">
<w:r><w:t xml:space="preserve">the receiving party shall keep the disclosed materials in a secure place for the agreed period.</w:t>
</w:r>
</w:moveFrom>
<w:moveFromRangeEnd w:id="201"/>
<w:r><w:t xml:space="preserve"> Paragraph three keeps this text.</w:t>
</w:r>
</w:p>
<w:sectPr>
<w:pgSz w:w="11906" w:h="16838"/>
<w:pgMar w:top="1417" w:right="1701" w:bottom="1417" w:left="1701" w:header="708" w:footer="708" w:gutter="0"/>
</w:sectPr>
</w:body>
</w:document>

Save the XML as word/document.xml and zip it with a minimal package:

[Content_Types].xml
_rels/.rels
word/document.xml
word/_rels/document.xml.rels

[Content_Types].xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/></Types>

_rels/.rels

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/></Relationships>

word/_rels/document.xml.rels is an empty <Relationships/> element. We can attach the built file instead if you would rather have the binary.

What we checked on it

Structure, counted by walking the tags in order:

Per side	Count
<w:moveFromRangeStart> / <w:moveFromRangeEnd>	1 / 1, sharing w:name
self-closing markers on paragraph marks	2
wrappers containing runs	2, of 3 and 95 characters

Opened with @superdoc/sdk@2.9.0, trackChanges.list() returns one row:

{ "type": "move", "role": "move-destination", "moveDirection": "up",
  "hasSource": true, "hasDestination": true }

So the read model pairs it correctly on this fixture, which is the same conclusion we reached on the real file. One difference worth flagging: on the real file the same call returned two rows of type: 'move', each with both sides resolved, while this fixture returns one. If one row per move is the intended shape, the two-row case may be worth a look on its own, but we could not narrow that down without the file.

The rendering question is the one this issue is about, and that needs a browser.

[caio-pizzol]

Thanks @nandoofz — we tested your synthetic fixture in the browser and confirmed the multi-paragraph styling bug on current V2. We’ve added the fixture and results to the existing engineering issue. We also confirmed that the API text targets cover only the first short run, and recorded that separately for triage. Your fixture is sufficient to reproduce these findings; we don’t need the confidential original. The separate two-row behavior remains unconfirmed.