feat(platform): batch annotations without changing undo history

[henrique221]

Fixes #514.

Adds setAnnotations(annotations) and removeAnnotations(refs) to the editor API, with exported Annotation and AnnotationReference types. Each batch runs in one editor update. Existing type/id pairs are replaced, unrelated marks stay in place, and the last entry wins when a batch repeats a type/id. Callbacks remain optional. The single-annotation methods use the same path.

Annotation updates leave the history entry, undo stack, and redo stack unchanged. Pending user edits are flushed before the annotation update, which commits discretely, so the history exclusion tag cannot discard a real edit from the same tick. The editor's change notifier and Standard view also distinguish these updates from a real undo/redo restore.

Tests cover overlapping ranges, replacement, callbacks, invalid ranges, reserved types, empty batches, 128 diagnostics in one update/commit, undo/redo, and refreshing diagnostics from onUsjChange. A Standard view regression test checks that annotation updates do not suspend a pending marker edit.

Validation:

• shared-react: 1,667 passed, one existing skipped test.
• platform-editor: 1,696 passed.
• Typecheck and lint passed. Lint reports five warnings in unchanged files.
• Build and API extraction passed; the public API report is included.
• Removing the history exclusion tag makes all four new history tests fail.
• GitHub Actions passed on Linux, macOS, and Windows; CodeQL passed.

Integration with #531 was verified locally at its head 7a2b8fbf: 36 focused tests and the shared-react/platform typechecks passed. Tests cover both individual and batch annotations at mount, in the same tick as setUsj, and in ordered set/remove pairs. The resolution keeps runWhenLoaded around the shared setAnnotations and removeAnnotations forwarding in Editor.tsx; the individual methods delegate to them. The set-then-remove assertion in #531 should now expect no remaining mark, because the discrete annotation update commits the index before removal.

The load gate remains in #531. Until it lands, the existing requirement to apply annotations after loading still applies. Undo/redo restores document snapshots, so hosts should refresh diagnostics for the restored content.

When combining with #552, preserve the new Annotation and AnnotationReference exports in editorial-entry.ts, which that PR introduces and re-exports from the root entry point.

---

This change is 

Screenshots

Playwright captures of a local consumer harness loading the real Editor source at 2d91195a. The Genesis USJ fixture is local test data. Counters and result rows come from live editor events, getUsj(), and rendered marks.

1. Batch annotations applied in one editor commit

Three diagnostics are applied by one setAnnotations call. The real editor reports one annotation commit, zero content changes, and no undo entry.

2. Undo and redo after diagnostic refresh

After inserting ! with browser input, the host refreshes diagnostics from onUsjChange. Undo removes the edit and enables Redo; Redo restores it. The table records the actual text and history state after each action.

[codesandbox]

Review or Edit in CodeSandbox

Open the branch in Web Editor • VS Code • Insiders

Open Preview