Context
renderHtmlDiff() already uses data-diff-key / diffAttribute as the main identity primitive. This is useful and works well for app-rendered documents where callers can provide stable node IDs.
Flashtype relies on this heavily for Markdown diffs: Lix markdown block IDs become data-diff-keys, and nested list/table keys are derived from those block IDs.
Proposal
Document and harden the contract for keyed nodes.
High-signal semantics to specify:
- Same key on before/after = same logical node, regardless of position.
- Keyed matching should take precedence over fuzzy text/position matching.
- Missing key on after = removed; missing key on before = added.
- Duplicate keys should have explicit behavior: throw, warn, or document deterministic first-wins semantics.
- Nested keyed nodes should behave predictably when parent and child both have keys.
- Keyed nodes inside strict structures like
table, tbody, tr, ul, and li should preserve valid output structure.
Why
The current implementation appears to use a map keyed by the diff attribute, so the core primitive is already there. The gap is mostly API contract and edge-case guarantees.
For consumers like editor/review overlays, keyed identity is not a convenience; it is the main way to avoid noisy remove+add diffs for moved or edited blocks.
Context
renderHtmlDiff()already usesdata-diff-key/diffAttributeas the main identity primitive. This is useful and works well for app-rendered documents where callers can provide stable node IDs.Flashtype relies on this heavily for Markdown diffs: Lix markdown block IDs become
data-diff-keys, and nested list/table keys are derived from those block IDs.Proposal
Document and harden the contract for keyed nodes.
High-signal semantics to specify:
table,tbody,tr,ul, andlishould preserve valid output structure.Why
The current implementation appears to use a map keyed by the diff attribute, so the core primitive is already there. The gap is mostly API contract and edge-case guarantees.
For consumers like editor/review overlays, keyed identity is not a convenience; it is the main way to avoid noisy remove+add diffs for moved or edited blocks.