From 2751f62c75ec71f54027118bad9beed77e34eb3f Mon Sep 17 00:00:00 2001 From: gohabereg Date: Tue, 6 Oct 2026 23:21:29 +0100 Subject: [PATCH 1/3] docs(openspec): propose inline-fragments-flat-runs Replace the order-dependent inline formatting tree in TextNode with a canonical flat run model: maximal fragments (#53), deterministic fragment order, order-independent loading. Co-Authored-By: Claude Opus 5.5 --- .../inline-fragments-flat-runs/.openspec.yaml | 2 + .../inline-fragments-flat-runs/design.md | 155 ++++++++++++++++++ .../inline-fragments-flat-runs/proposal.md | 37 +++++ .../specs/model/spec.md | 155 ++++++++++++++++++ .../inline-fragments-flat-runs/tasks.md | 40 +++++ 5 files changed, 389 insertions(+) create mode 100644 openspec/changes/inline-fragments-flat-runs/.openspec.yaml create mode 100644 openspec/changes/inline-fragments-flat-runs/design.md create mode 100644 openspec/changes/inline-fragments-flat-runs/proposal.md create mode 100644 openspec/changes/inline-fragments-flat-runs/specs/model/spec.md create mode 100644 openspec/changes/inline-fragments-flat-runs/tasks.md diff --git a/openspec/changes/inline-fragments-flat-runs/.openspec.yaml b/openspec/changes/inline-fragments-flat-runs/.openspec.yaml new file mode 100644 index 00000000..aa32566b --- /dev/null +++ b/openspec/changes/inline-fragments-flat-runs/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-06 diff --git a/openspec/changes/inline-fragments-flat-runs/design.md b/openspec/changes/inline-fragments-flat-runs/design.md new file mode 100644 index 00000000..e06ab02c --- /dev/null +++ b/openspec/changes/inline-fragments-flat-runs/design.md @@ -0,0 +1,155 @@ +## Context + +`TextNode` (in `packages/model/src/entities/inline-fragments/`, renamed to `inline-text/` by this change) holds a text value and its inline formatting. Today it is the root of a tree: `ParentInlineNode` → nested `FormattingInlineNode`s (one per applied tool, with `tool` and `data`) → `TextInlineNode` leaves, glued together by the `ParentNode`/`ChildNode` decorator mixins. + +The tree is private to the model in practice: + +- serialization is `{ value, fragments }`, where `fragments` comes from `getFragments()`; the tree itself is never stored; +- loading replays `format()` per fragment (`TextNode#initialize`); +- `FormattingAdapter` (dom-adapters) renders from fragments it reads through the API, wrapping each with `surround()` in array order; +- collaboration and undo/redo operate on `format`/`unformat` ranges; +- no package outside `inline-fragments/` imports the node classes. + +The tree's shape depends on operation order. `ParentNode#normalize` only merges equal neighbouring siblings, and `ParentInlineNode#getFragments` only merges a fragment into the one right before it in pre-order. With the current code: + +| Operations | `getFragments()` | +|---|---| +| `abcd`: bold 0–2, italic 0–4, bold 2–4 | `bold 0–2, italic 0–4, bold 2–4` | +| `abcd`: bold 0–4, italic 0–4 | `bold 0–4, italic 0–4` | +| `abcdef`: bold 0–3, italic 1–3, italic 3–6, bold 3–5 | `bold 0–3, italic 1–6, bold 3–5` | +| `abcd`: italic 1–3, bold 0–4 | `bold 0–1, italic 1–3, bold 1–4` | + +All four should return maximal fragments; the first two describe identical formatting. + +## Goals / Non-Goals + +**Goals:** + +- Canonical formatting state: identical formatting gives identical internal state, identical fragments and identical fragment order. +- Maximal fragments (#53) and a deterministic fragment order. +- Keep the `TextNode` public API, events, event payloads and serialized format. +- Keep current behaviour where it is not order-dependent: insertion inheritance, range-query semantics, data replacement on re-application, validation errors. +- Simpler code that is easy to test to the model's Stryker threshold. + +**Non-Goals:** + +- Per-tool inclusivity (e.g. text typed right after a link not extending it). +- Per-tool `rank` to control nesting between tools beyond the default sort. +- Several marks of the same tool on one character (nested ``, overlapping comments). +- Mark identity (an id table so a link's data is stored once). +- Inline embeds (atomic inline objects with their own content). +- A balanced run container (rope / B-tree) for very long texts. + +Each of these fits the run model later without changing its core rule (see Decision 1); none is needed now. + +## Decisions + +### 1. Flat runs instead of a (canonical) tree + +`TextNode` stores its content in a `RunList`, which holds `TextRun`s: + +```ts +class TextMark { readonly tool: InlineToolName; readonly data?: InlineToolData; equals(mark: TextMark): boolean } +class TextRun { readonly text: string; readonly marks: readonly TextMark[] } // marks sorted by tool name +``` + +Invariants, restored at the end of every mutating operation: + +1. No empty runs. Empty text is `[]`. +2. Adjacent runs never have equal mark sets (they are merged). +3. A run carries at most one mark per tool. + +Invariant 2 makes the representation canonical: the runs are a pure function of "which marks apply to which character". + +Alternatives considered: + +- **Keep the tree, rebuild it canonically after each operation** with a stack rule (start asc, end desc, tool name). Canonical, but keeps all the tree code, still needs a global fragment merge (a tree has to cut crossing fragments), and rebuilds the tree on every operation. +- **Keep the tree, build the fewest-splits tree.** Exact minimisation is a dynamic program over mark orders per run, O(runs · k! · k) for k overlapping marks; it needs the run decomposition as input anyway, plus a deterministic tie-break. +- **Fix only `getFragments` merging (#53).** Fixes the fragment output but leaves order-dependent fragment order, DOM nesting and loading. + +The tree's advantages (direct mapping from HTML, stored nesting, inline nodes with children) are not used by the model today, and the flat fragment format could not carry them anyway. + +### 2. Operations: split, change marks, merge + +All range edits use one helper, `#splitAt(offset)`, which guarantees a run boundary at `offset` (cutting a run in two with the same marks if needed). Then: + +- `format(tool, start, end, data)`: split at `start` and `end`; on every run in `[start, end)` set the mark for `tool` to `{ tool, data }` (adding it or replacing an existing one: Invariant 3 and "re-applying replaces data"); merge. +- `unformat(tool, start, end)`: split at `start` and `end`; remove the `tool` mark from runs in `[start, end)`; merge. +- `removeText(start, end)`: split at `start` and `end`; remove the runs in `[start, end)`, collecting their text; merge. +- `insertText(text, index)`: find the run that owns `index` (Decision 4) and insert into its string. Mark sets don't change, so no split or merge is needed. Into empty text, create `{ text, marks: [] }`. +- A zero-length `format`/`unformat`/`removeText` range changes nothing (same as today). + +`#merge()` is one pass joining adjacent runs with equal mark sets and dropping empty runs. Operations stay O(runs), and runs exist only where formatting changes. + +Events are dispatched by `TextNode` exactly as today (same event classes, `PartialIndex({ textRange })`, context user, `{ tool, data }` payloads), including when `format` re-applies identical data. + +### 3. Fragments: one sweep, then a fixed sort + +`getFragments()` walks the runs once with a map of open fragments by tool: + +- a fragment closes at the current offset when the run no longer has a mark of that tool, or has one with different data; +- a fragment opens for every mark of the run that isn't already open; +- everything still open closes at the end. + +The result is sorted by start ascending, end descending, tool name ascending. Because a fragment stays open across runs while its mark continues, fragments are maximal by construction (#53), and the sort makes the order, and therefore `FormattingAdapter`'s DOM nesting, deterministic. `surround()` wraps whatever is already in the range, so a containing fragment (listed first) wraps the contained one, and for equal ranges the tool later in name order ends up outside. Fragment objects, ranges and data are fresh copies per call, so callers can't change internal state through them. + +### 4. Insertion inherits from the left + +`insertText` at index `i > 0` inserts into the run containing character `i - 1`; at `i = 0` it inserts into the first run. This reproduces today's `findChildByIndex` behaviour (`index <= offset + length` picks the left node) and was confirmed against the current implementation. + +### 5. Range queries + +`getFragments(start, end, tool?)` validates the range, computes all fragments, and keeps those with `fragment.start < end && fragment.end > start`. That matches today's `#reduceChildrenInRange` (strict overlap, so touching fragments and empty ranges return nothing), but returns full merged ranges instead of the tree pieces that happened to overlap. `tool` filters the result as today. Computing all fragments per query is O(runs); it can be narrowed later if profiling shows a need. + +### 6. Single equality point for mark data + +Two marks are equal when their tools are equal and `isSameInlineData(a.data, b.data)` holds. Run merging (Invariant 2), the fragment sweep and the identical-data check all go through `TextMark#equals`. The `wire-inline-tool-data-comparator` change can replace the data comparison there with a per-tool comparator without touching the algorithms. + +`isSameInlineData` treats `undefined` and `{}` as equal, but they serialize differently. Without care, merging runs keeps whichever one was on the left and re-applying replaces one with the other, so equal formatting could serialize differently. `TextMark` therefore stores empty data as `undefined`, and fragments never carry `data: {}`. It also stores a deep copy of the data (`cloneInlineData`), and `RunList#toFragments` hands out copies, so neither the object passed to `format` nor a returned fragment can change the runs behind the model's back. + +Alternatives considered: normalizing to `{}` instead (adds `data: {}` to every fragment without data, changing serialized output for most documents); freezing the data (throws on consumers that mutate fragments in strict mode). + +### 6a. Deterministic loading of conflicting fragments + +Our own serialized fragments never overlap for one tool, but external input can (v2 import, hand-written or remote JSON). `TextNode#initialize` applies initial fragments sorted by start, end descending, tool name, then `JSON.stringify(data)`, so where fragments of one tool overlap with different data, the one that sorts later wins regardless of input order. The comparator is a total order, unlike the fragment output sort, which never compares two fragments of the same tool with equal ranges. + +### 7. Module layout and exports + +- `TextNode/index.ts` keeps the public class. It extends `EventBus` directly (it no longer has a `ParentInlineNode` base) and keeps its constructor options (`value`, `fragments`). +- `TextMark`, `TextRun` and `RunList` are classes in their own folders under `inline-text/` (the `inline-fragments/` folder is renamed, since it no longer holds fragments), not exported from the package: + - `TextMark` is an immutable value object with `equals()`. + - `TextRun` is an immutable data class with no behaviour, kept as a class for consistency with the other entities. + - `RunList` owns the runs and their invariants. Its public methods (`insert`, `remove`, `setMark`, `removeMark`, `toFragments`, `getText`, `length`, and a `runs` copy for tests) restore the invariants before returning. Splitting, merging and mark-set helpers are private. + - `TextNode` keeps validation, events and loading, and delegates storage to `RunList`. + - Fields are `public readonly`, not `#private`, because Jest's `toEqual` ignores `#` fields and run assertions would pass vacuously. +- `ParentInlineNode`, `FormattingInlineNode`, `TextInlineNode`, `InlineNode`, the `ParentNode`/`ChildNode` mixins and their mocks are deleted, along with their exports from `@editorjs/model`. +- `format`/`unformat` return `void`. +- Validation errors keep their current messages, since specs and callers may rely on them. + +### 8. Testing strategy + +- **Regression first.** The four cases from Context, plus behaviour-preservation tests (insertion inheritance, range queries, data replacement, removal, validation), are added to `TextNode/TextNode.integration.spec.ts` before the rewrite (the unit spec mocks the tree, so it can't host them). They run against the current implementation (the order-dependent ones fail) and stay unchanged afterwards as the contract. +- **Invariant checks on `RunList`.** The invariants belong to `RunList`, so they are checked there: a test-only helper (a `*.testing.ts` file, excluded from Stryker) reads `RunList#runs` and asserts them after every `RunList` spec and after every step of the `RunList` random sequences. `TextNode` has no test-only API; its tests go through its public API only. +- **Seeded random sequences.** A shared helper (no new dependency) generates operation sequences and applies them to a per-character reference model: + - the `RunList` sequences check the invariants, text and fragments after every operation; + - the `TextNode` sequences check text and fragments after every operation, then that rebuilding from `serialized` gives the same fragments, and that shuffling the serialized fragments before loading gives the same result. +- Integration specs (`InlineTree.integration.spec.ts`) are kept where they assert fragments and rewritten where they assert tree shape. + +## Risks / Trade-offs + +- [Fragments that used to carry `data: {}` (bold and italic applied from the UI) now come out without `data`] → Equal under `isSameInlineData`, and documents load the same either way. Consumers reading `fragment.data` of such tools must accept `undefined`; the SDK already types `createWrapper(data?)` as optional. `@editorjs/inline-link` dereferences `data` without a guard, so a link with empty data (which has no meaning) would throw; links always carry `href` in practice. + +- [Fragment order changes for existing documents with overlapping formatting, so DOM nesting can differ from before] → Content and formatting are identical; only wrapper nesting changes, and it becomes stable. Mention it in the PR description. +- [`FormattingAdapter`'s incremental re-render can leave empty wrappers (e.g. ``) next to a re-rendered range] → Pre-existing: the same sequence on `main` leaves them too. Out of scope; the model is correct either way. +- [`getFragments(start, end)` returns larger ranges where the tree used to return split pieces; `FormattingAdapter` re-renders the union of returned ranges] → That's the correct range to re-render. Covered by existing dom-adapters tests; the playground should be checked once by hand. +- [Removing exported classes is a breaking change for anyone importing them from `@editorjs/model`] → Nothing in the monorepo does. Listed as BREAKING in the proposal. +- [Rewriting a mutation-tested module can lower the Stryker score] → The run code is much smaller; the regression, invariant and randomized tests target it directly. Run `test:mutations` for the model before opening the PR. +- [Open conflicts with in-flight PRs] → #192 and #194 touch `EditorDocument`/`BlockNode`/`model-types`, not `inline-fragments/`. The folder rename only changes import paths in `BlockNode` and `entities/index.ts`, which may need a trivial rebase. #192 also edits `BlockNode` specs that build `TextNode`s, which only use the public API. + +## Migration Plan + +No data migration: the serialized format is unchanged and loading is order-independent. Ship as a single implementation PR stacked on this spec PR. Rollback is reverting that PR. + +## Open Questions + +None blocking. Follow-ups once needed: per-tool rank and inclusivity, multi-instance marks, a mark id table, inline embeds. diff --git a/openspec/changes/inline-fragments-flat-runs/proposal.md b/openspec/changes/inline-fragments-flat-runs/proposal.md new file mode 100644 index 00000000..5bcbc2bb --- /dev/null +++ b/openspec/changes/inline-fragments-flat-runs/proposal.md @@ -0,0 +1,37 @@ +## Why + +The inline formatting of a `TextNode` is stored as a tree (`FormattingInlineNode` / `TextInlineNode`) whose shape depends on the order the formatting was applied in, not only on the resulting formatting. The same markup can therefore produce different trees, which leaks out as: + +- split fragments: `getFragments()` only merges a fragment with the one right before it in pre-order, so applying bold 0–2, italic 0–4, bold 2–4 on `abcd` returns `bold 0–2, italic 0–4, bold 2–4` instead of `bold 0–4, italic 0–4` (#53); +- order-dependent fragment order, and so order-dependent DOM nesting (`FormattingAdapter` wraps fragments in the order the model returns them); +- loading a text from fragments gives a tree that depends on the order of the fragments array. + +Replacing the tree with a canonical flat representation (runs of text, each with the set of marks applied to it) removes the cause rather than patching each symptom, and simplifies every operation to "split, change marks, merge". + +## What Changes + +- `TextNode` stores its content as a list of runs `{ text, marks }` with three invariants: no empty runs, adjacent runs never carry equal mark sets, at most one mark per tool in a run. +- `getFragments()` returns maximal fragments: each stretch of characters formatted with the same tool and equal data is one fragment, regardless of how it was applied (fixes #53). +- Fragments are returned in a deterministic order: start ascending, end descending, tool name ascending. DOM nesting produced by `FormattingAdapter` becomes deterministic as a consequence: a fragment that contains another wraps it, and for equal ranges the tool later in name order ends up outside (`surround()` wraps whatever is already in the range). +- The formatting state, and so the fragments, no longer depend on the order of `format`/`unformat` operations or on the order of fragments passed to the `TextNode` constructor. +- `getFragments(start, end)` returns whole fragments that intersect the range; for text whose fragments used to be split by the tree, the returned ranges are now the full, merged ranges. +- Public `TextNode` API (`insertText`, `removeText`, `getText`, `format`, `unformat`, `getFragments`, `serialized`, `length`), its events and the serialized format stay the same. +- **BREAKING** (package API): `FormattingInlineNode`, `ParentInlineNode`, `TextInlineNode`, the `ParentNode`/`ChildNode` mixins and the `InlineNode` type are removed from `@editorjs/model` exports. No package in the monorepo imports them. `TextNode#format`/`#unformat` return `void` instead of the created tree nodes (the return value is not used anywhere). + +## Capabilities + +### New Capabilities + +None. + +### Modified Capabilities + +- `model`: the "Inline text tree" requirement is replaced by requirements for run-based inline text: canonical formatting state, maximal fragments, deterministic fragment order, range queries and insertion inheritance. + +## Impact + +- **Code**: `packages/model/src/entities/inline-fragments/` is rewritten and renamed to `inline-text/`. `TextNode` stays as the public class; `ParentInlineNode`, `FormattingInlineNode`, `TextInlineNode`, `InlineNode` and the `ParentNode`/`ChildNode` mixins (with their mocks and specs) are removed. Specs asserting exact tree shapes are replaced by specs asserting fragments and run invariants. +- **Consumers**: `BlockNode`, `EditorDocument`, `EditorJSModel`, `core`, `dom-adapters` and `collaboration-manager` only use the `TextNode` API, events and fragments, so they need no changes. The visible differences are merged fragment ranges and a deterministic fragment order, which may change DOM nesting for text that was formatted with overlapping tools. +- **Data**: serialized text (`value` + `fragments`) is unchanged; existing documents load as before, and their fragments come out merged and sorted. +- **Docs**: `docs/model.md` and `docs/diagrams/model-tree-structure.mmd` describe the inline tree (`FormattingInlineNode` + `TextInlineNode`); they are superseded by this change and must be updated to describe runs. +- **Related work**: fixes #53. The `wire-inline-tool-data-comparator` change keeps working: mark equality goes through a single comparison point (`isSameInlineData`) that a per-tool comparator can replace. Out of scope, but designed to fit later: per-tool `rank` in the sort, multiple instances of one tool (nested quotes, overlapping comments), mark identity via an id table, inline embeds, and a balanced run container. diff --git a/openspec/changes/inline-fragments-flat-runs/specs/model/spec.md b/openspec/changes/inline-fragments-flat-runs/specs/model/spec.md new file mode 100644 index 00000000..827fc8a5 --- /dev/null +++ b/openspec/changes/inline-fragments-flat-runs/specs/model/spec.md @@ -0,0 +1,155 @@ +## REMOVED Requirements + +### Requirement: Inline text tree +**Reason**: The inline formatting tree (`ParentInlineNode` / `FormattingInlineNode` / `TextInlineNode`) is not canonical: its shape, and the fragments derived from it, depend on the order formatting was applied in (#53). It is replaced by a flat run representation inside `TextNode`. +**Migration**: Use `TextNode` only. Its public API (`insertText`, `removeText`, `getText`, `format`, `unformat`, `getFragments`, `serialized`, `length`), events and serialized format are unchanged. `format`/`unformat` now return `void`; the tree node classes and the `ParentNode`/`ChildNode` mixins are no longer exported. + +## ADDED Requirements + +### Requirement: Inline formatted text +The system SHALL provide `TextNode` as the container of a text data node's value and inline formatting. It SHALL support inserting and removing text, reading text, applying (`format`) and removing (`unformat`) an inline tool over a character range, and listing inline fragments. Indices and ranges SHALL be validated against the current text length, and a range's end SHALL NOT be lower than its start. `insertText`, `removeText`, `format` and `unformat` SHALL dispatch `TextAddedEvent`, `TextRemovedEvent`, `TextFormattedEvent` and `TextUnformattedEvent` respectively, with the affected text range and the current context user. `serialized` SHALL return the text value and the fragments as returned by `getFragments()`. `TextNode` SHALL keep its own copy of the data passed to `format` and SHALL return copies of it in fragments, so changes to those objects don't change its state. + +Implemented in `src/entities/inline-text/TextNode/index.ts`, validated by its co-located `.spec.ts`. + +#### Scenario: Inserting text into an empty text node +- **GIVEN** a `TextNode` with no text +- **WHEN** `insertText('abc')` is called +- **THEN** `getText()` returns `abc`, `getFragments()` returns no fragments and a `TextAddedEvent` with text range `[0, 0]` is dispatched + +#### Scenario: Removing text with an out-of-range index +- **GIVEN** a `TextNode` with text `abc` +- **WHEN** `removeText(0, 5)` is called +- **THEN** it throws a range validation error and the text is unchanged + +#### Scenario: Formatting with an inverted range +- **GIVEN** a `TextNode` with text `abcd` +- **WHEN** `format('bold', 3, 1)` is called +- **THEN** it throws a range validation error + +#### Scenario: Removing text inside formatting +- **GIVEN** a `TextNode` with text `abcdef` formatted with bold over `[1, 5]` +- **WHEN** `removeText(2, 4)` is called +- **THEN** `removeText` returns `cd`, `getText()` returns `abef` and `getFragments()` returns bold over `[1, 3]` + +#### Scenario: Mutating data after formatting +- **GIVEN** a `TextNode` with text `abcd` formatted with link over `[0, 4]` using a data object `{ href: 'a' }` +- **WHEN** that object's `href` is changed to `b`, or the `data` of a fragment returned by `getFragments()` is changed +- **THEN** `getFragments()` still returns link `[0, 4]` with `{ href: 'a' }` + +#### Scenario: Removing all formatted text drops the fragment +- **GIVEN** a `TextNode` with text `abcd` formatted with bold over `[1, 3]` +- **WHEN** `removeText(1, 3)` is called +- **THEN** `getFragments()` returns no fragments + +### Requirement: Canonical inline formatting state +The formatting state of a `TextNode`, and so its fragments, SHALL depend only on which inline tool (with which data) applies to each character, never on the order or the way `format`, `unformat` and text operations were performed, nor on the order of fragments passed to the constructor. Each character SHALL carry at most one mark per inline tool. Empty data (`{}`) SHALL be treated as no data and returned without a `data` key, so equal data can't produce different output. Fragments passed to the constructor SHALL be applied sorted by range start ascending, range end descending, tool name, then data, so where fragments of the same tool overlap with different data, the one that sorts later wins whatever order they were passed in. + +#### Scenario: Same formatting applied in a different order +- **GIVEN** two `TextNode`s with text `abcd` +- **WHEN** the first gets bold `[0, 2]`, italic `[0, 4]`, bold `[2, 4]` and the second gets bold `[0, 4]`, italic `[0, 4]` +- **THEN** both return the same fragments: bold `[0, 4]`, italic `[0, 4]` + +#### Scenario: Loading the same fragments in a different order +- **GIVEN** fragments bold `[0, 3]` and italic `[1, 5]` for text `abcdef` +- **WHEN** one `TextNode` is constructed with them in that order and another with them reversed +- **THEN** both return the same fragments in the same order + +#### Scenario: Empty data is the same as no data +- **GIVEN** two `TextNode`s with text `abcd` +- **WHEN** the first gets bold `[0, 2]` with data `{}` and bold `[2, 4]` without data, and the second gets the same with the data swapped +- **THEN** both return a single bold fragment over `[0, 4]` without a `data` key + +#### Scenario: Loading conflicting fragments in a different order +- **GIVEN** fragments link `[0, 4]` with `{ href: 'a' }` and link `[2, 6]` with `{ href: 'b' }` for text `abcdef` +- **WHEN** one `TextNode` is constructed with them in that order and another with them reversed +- **THEN** both return link `[0, 2]` with `{ href: 'a' }` and link `[2, 6]` with `{ href: 'b' }` + +#### Scenario: Unformatting restores the previous state +- **GIVEN** a `TextNode` with text `abcd` formatted with bold `[0, 4]` +- **WHEN** italic is applied over `[1, 3]` and then removed over `[1, 3]` +- **THEN** `getFragments()` returns only bold `[0, 4]` + +### Requirement: Maximal inline fragments +`getFragments()` SHALL return one fragment per maximal stretch of characters formatted with the same tool and equal data. Adjacent or overlapping stretches of the same tool with equal data SHALL be returned as a single fragment; stretches of the same tool whose data differs SHALL be returned as separate fragments. Data equality SHALL default to a deep structural comparison, which an inline tool MAY override with its own comparator. + +#### Scenario: Fragments split by other formatting are merged +- **GIVEN** a `TextNode` with text `abcdef` +- **WHEN** bold `[0, 3]`, italic `[1, 3]`, italic `[3, 6]` and bold `[3, 5]` are applied in that order +- **THEN** `getFragments()` returns bold `[0, 5]` and italic `[1, 6]` + +#### Scenario: Adjacent formatting with equal data is merged +- **GIVEN** a `TextNode` with text `abcd` +- **WHEN** link `{ href: 'a' }` is applied over `[0, 2]` and then over `[2, 4]` +- **THEN** `getFragments()` returns a single link fragment over `[0, 4]` with data `{ href: 'a' }` + +#### Scenario: Adjacent formatting with different data is kept separate +- **GIVEN** a `TextNode` with text `abcd` +- **WHEN** link `{ href: 'a' }` is applied over `[0, 2]` and link `{ href: 'b' }` over `[2, 4]` +- **THEN** `getFragments()` returns link `[0, 2]` with `{ href: 'a' }` and link `[2, 4]` with `{ href: 'b' }` + +#### Scenario: Removing text joins equal fragments +- **GIVEN** a `TextNode` with text `abcdef`, bold `[0, 2]`, italic `[2, 4]` and bold `[4, 6]` +- **WHEN** `removeText(2, 4)` is called +- **THEN** `getFragments()` returns a single bold fragment over `[0, 4]` + +### Requirement: Re-applying an inline tool +When an inline tool is applied over a range where some characters already carry that tool, the system SHALL replace the existing data with the newly supplied data on the affected characters only. When the supplied data is equal to the existing data (under the effective comparator), the formatting state SHALL be left unchanged. + +#### Scenario: Re-applying the same tool with different data +- **GIVEN** a `TextNode` with text `abcd` formatted with link `{ href: 'a' }` over `[0, 4]` +- **WHEN** link `{ href: 'b' }` is applied over `[1, 3]` +- **THEN** `getFragments()` returns link `[0, 1]` with `{ href: 'a' }`, link `[1, 3]` with `{ href: 'b' }` and link `[3, 4]` with `{ href: 'a' }` + +#### Scenario: Re-applying the same tool with identical data +- **GIVEN** a `TextNode` with text `abcd` formatted with link `{ href: 'a' }` over `[0, 4]` +- **WHEN** link `{ href: 'a' }` is applied over `[1, 3]` +- **THEN** `getFragments()` still returns a single link fragment over `[0, 4]` + +### Requirement: Deterministic inline fragment order +`getFragments()` SHALL return fragments sorted by range start ascending, then range end descending, then tool name ascending, so that fragments which contain others come first. + +#### Scenario: Containing fragment comes first +- **GIVEN** a `TextNode` with text `abcd` +- **WHEN** italic `[1, 3]` is applied and then bold `[0, 4]` +- **THEN** `getFragments()` returns bold `[0, 4]` before italic `[1, 3]` + +#### Scenario: Equal ranges are ordered by tool name +- **GIVEN** a `TextNode` with text `abcd` +- **WHEN** italic `[0, 4]` is applied and then bold `[0, 4]` +- **THEN** `getFragments()` returns bold `[0, 4]` before italic `[0, 4]` + +### Requirement: Inline fragments in a range +`getFragments(start, end, tool?)` SHALL return the whole fragments (with their full ranges) that share at least one character with `[start, end)`, in the same order as `getFragments()`. Fragments that only touch the range boundary SHALL NOT be returned, and an empty range SHALL return no fragments. When `tool` is passed, only fragments of that tool SHALL be returned. + +#### Scenario: Partially covered fragment is returned whole +- **GIVEN** a `TextNode` with text `abcdef` formatted with bold `[1, 5]` +- **WHEN** `getFragments(0, 2)` is called +- **THEN** it returns bold `[1, 5]` + +#### Scenario: Touching fragment is not returned +- **GIVEN** a `TextNode` with text `abcdef` formatted with bold `[0, 2]` and italic `[4, 6]` +- **WHEN** `getFragments(2, 4)` is called +- **THEN** it returns no fragments + +#### Scenario: Filtering by tool +- **GIVEN** a `TextNode` with text `abcd` formatted with bold `[0, 4]` and italic `[1, 3]` +- **WHEN** `getFragments(0, 4, 'italic')` is called +- **THEN** it returns only italic `[1, 3]` + +### Requirement: Inserted text inherits formatting +Text inserted at index `i > 0` SHALL get the formatting of the character at `i - 1`. Text inserted at index `0` of a non-empty text SHALL get the formatting of the first character. Text inserted into an empty text SHALL have no formatting. + +#### Scenario: Inserting at the end of a formatted stretch +- **GIVEN** a `TextNode` with text `abcd` formatted with bold `[0, 2]` +- **WHEN** `insertText('X', 2)` is called +- **THEN** `getFragments()` returns bold `[0, 3]` + +#### Scenario: Inserting at the start of formatted text +- **GIVEN** a `TextNode` with text `abcd` formatted with bold `[0, 2]` +- **WHEN** `insertText('X', 0)` is called +- **THEN** `getFragments()` returns bold `[0, 3]` + +#### Scenario: Inserting after unformatted text +- **GIVEN** a `TextNode` with text `abcd` formatted with bold `[2, 4]` +- **WHEN** `insertText('X', 2)` is called +- **THEN** `getFragments()` returns bold `[3, 5]` diff --git a/openspec/changes/inline-fragments-flat-runs/tasks.md b/openspec/changes/inline-fragments-flat-runs/tasks.md new file mode 100644 index 00000000..fb6b6ed3 --- /dev/null +++ b/openspec/changes/inline-fragments-flat-runs/tasks.md @@ -0,0 +1,40 @@ +## 1. Regression and contract tests (against the current tree) + +- [ ] 1.1 Add order-independence tests to `packages/model/src/entities/inline-text/TextNode/TextNode.integration.spec.ts` (the unit spec mocks the tree): `should return the same fragments when equal formatting is applied in a different order` (bold 0–2, italic 0–4, bold 2–4 vs bold 0–4, italic 0–4), `should merge fragments split by other formatting` (bold 0–3, italic 1–3, italic 3–6, bold 3–5 → bold 0–5, italic 1–6), `should return a single fragment when a tool is applied over an existing shorter fragment of another tool` (italic 1–3, bold 0–4), and `should return the same fragments when constructed with fragments in a different order`. Confirm they fail on the current implementation +- [ ] 1.2 Add fragment order tests: `should return a containing fragment before the contained one` and `should order fragments with equal ranges by tool name` +- [ ] 1.3 Add behaviour-preservation tests that pass on the current implementation: insertion inheritance (at the end of a formatted stretch, at index 0, after unformatted text, into empty text), range queries (partial overlap returns the whole fragment, touching fragments and empty ranges return nothing, filtering by tool), data replacement and the identical-data no-op, adjacent equal/different data, `removeText` inside formatting, removing all formatted text, `removeText` joining equal fragments, unformat restoring the previous state, zero-length format, and the validation errors +- [ ] 1.4 Commit the tests on their own so the implementation commit shows only the failing order-dependent cases turning green + +## 2. Run model + +- [ ] 2.1 Write failing tests for the private run helpers (`RunList/RunList.spec.ts`, `TextMark/TextMark.spec.ts`): `splitAt` (inside a run, on a boundary, at 0 and at the end), `merge` (equal neighbours joined, empty runs dropped, different data kept apart), and the fragment sweep (open/close on data change, maximal fragments, sort order) +- [ ] 2.2 Implement `TextMark` (immutable, `equals()` using `isSameInlineData`), `TextRun` (immutable data) and `RunList` (owns the runs and their invariants) classes under `inline-text/`, with mark equality only through `TextMark#equals` +- [ ] 2.3 Add a test-only `expectRunInvariants(runList)` helper (`RunList/runInvariants.testing.ts`, excluded from Stryker) checking no empty runs, no equal neighbours, one mark per tool and marks sorted by tool. Call it after every `RunList` spec and after every operation in the `RunList` random sequences (`RunList/RunList.random.spec.ts`). Keep `TextNode` free of test-only API + +## 3. TextNode on runs + +- [ ] 3.1 Rewrite `TextNode` to extend `EventBus` directly and store `#runs`: implement `length`, `getText`, `insertText`, `removeText`, `format`, `unformat`, `getFragments` and `serialized` as in design Decisions 2–5, dispatching the same events with the same payloads and keeping the current validation error messages +- [ ] 3.2 Make `format`/`unformat` return `void` and update their callers' types if needed (`BlockNode`) +- [ ] 3.3 Make the section 1 and 2 tests pass +- [ ] 3.4 Add the seeded random-sequence test (no new dependency, shared generator and reference model in `specs/randomOperations.testing.ts`, `TextNode/TextNode.random.spec.ts`): random `insertText`/`removeText`/`format`/`unformat` sequences compare text and fragments with a per-character reference model after every operation, then check that a `TextNode` rebuilt from `serialized` returns the same fragments, and that shuffling the serialized fragments before rebuilding gives the same result + +## 4. Remove the tree + +- [ ] 4.1 Delete `ParentInlineNode`, `FormattingInlineNode`, `TextInlineNode`, `InlineNode` and the `ParentNode`/`ChildNode` mixins with their mocks and specs, and remove their exports from `inline-text/index.ts` +- [ ] 4.2 Port `specs/InlineTree.integration.spec.ts` to the `TextNode` API as `specs/InlineFormatting.integration.spec.ts`, rewrite `TextNode/TextNode.spec.ts` without tree mocks, and drop the specs of the removed classes +- [ ] 4.3 Run the whole model test suite plus the `core`, `dom-adapters` and `collaboration-manager` suites, and fix anything that relied on the removed classes or on the old fragment order + +## 5. Docs and wrap-up + +- [ ] 5.1 Update `docs/model.md` (the `TextNode` bullet) and `docs/diagrams/model-tree-structure.mmd` (replace the `ParentInlineNode`/`FormattingInlineNode`/`TextInlineNode` classes with the run model) to describe runs +- [ ] 5.2 Run `yarn lint` for the touched packages and `test:mutations` for `@editorjs/model`; make sure the score stays above the threshold +- [ ] 5.3 Check formatting in the playground once by hand (overlapping bold/italic, undo/redo of formatting) +- [ ] 5.4 Run `openspec validate inline-fragments-flat-runs --type change` and make sure it passes + +## 6. Review fixes + +- [ ] 6.1 Write failing tests, then store empty data as no data in `TextMark`, so equal data can't serialize differently depending on operation order +- [ ] 6.2 Write failing tests, then make `TextMark` keep a deep copy of its data and `RunList#toFragments` return copies (`cloneInlineData` in `utils/`) +- [ ] 6.3 Write failing tests, then apply initial fragments in a total order (start, end descending, tool, data) so conflicting fragments load the same in any order +- [ ] 6.4 Extend the shared random generator with empty data for non-link tools and random, possibly conflicting, initial fragments loaded in shuffled order against the reference model +- [ ] 6.5 Cache `RunList#length`, drop the `#merge` call for inserting into an empty list, and fold `getFragments` filters into one predicate From 4c10de5736d3030ab9f0468c057bffc503504df5 Mon Sep 17 00:00:00 2001 From: gohabereg Date: Sat, 17 Oct 2026 19:36:56 +0100 Subject: [PATCH 2/3] docs(openspec): cover event data copies and adapter re-render in inline-fragments-flat-runs Co-Authored-By: Claude Opus 5.5 --- .../inline-fragments-flat-runs/design.md | 2 +- .../inline-fragments-flat-runs/proposal.md | 1 + .../specs/dom-adapters/spec.md | 21 +++++++++++++++++++ .../specs/model/spec.md | 4 ++-- .../inline-fragments-flat-runs/tasks.md | 2 ++ 5 files changed, 27 insertions(+), 3 deletions(-) create mode 100644 openspec/changes/inline-fragments-flat-runs/specs/dom-adapters/spec.md diff --git a/openspec/changes/inline-fragments-flat-runs/design.md b/openspec/changes/inline-fragments-flat-runs/design.md index e06ab02c..98d334b3 100644 --- a/openspec/changes/inline-fragments-flat-runs/design.md +++ b/openspec/changes/inline-fragments-flat-runs/design.md @@ -141,7 +141,7 @@ Our own serialized fragments never overlap for one tool, but external input can - [Fragment order changes for existing documents with overlapping formatting, so DOM nesting can differ from before] → Content and formatting are identical; only wrapper nesting changes, and it becomes stable. Mention it in the PR description. - [`FormattingAdapter`'s incremental re-render can leave empty wrappers (e.g. ``) next to a re-rendered range] → Pre-existing: the same sequence on `main` leaves them too. Out of scope; the model is correct either way. -- [`getFragments(start, end)` returns larger ranges where the tree used to return split pieces; `FormattingAdapter` re-renders the union of returned ranges] → That's the correct range to re-render. Covered by existing dom-adapters tests; the playground should be checked once by hand. +- [`getFragments(start, end)` returns whole merged ranges where the tree used to return split pieces, so a fragment can reach outside the range `FormattingAdapter` queried and overlap fragments it never saw. Rendering the widened range with only the first query's fragments drops formatting from the DOM] → `FormattingAdapter` re-queries over the widened range until it stops growing (`collectFragmentsToRender`) and renders with every fragment overlapping it. The same loss already happened on `main` in some operation orders. - [Removing exported classes is a breaking change for anyone importing them from `@editorjs/model`] → Nothing in the monorepo does. Listed as BREAKING in the proposal. - [Rewriting a mutation-tested module can lower the Stryker score] → The run code is much smaller; the regression, invariant and randomized tests target it directly. Run `test:mutations` for the model before opening the PR. - [Open conflicts with in-flight PRs] → #192 and #194 touch `EditorDocument`/`BlockNode`/`model-types`, not `inline-fragments/`. The folder rename only changes import paths in `BlockNode` and `entities/index.ts`, which may need a trivial rebase. #192 also edits `BlockNode` specs that build `TextNode`s, which only use the public API. diff --git a/openspec/changes/inline-fragments-flat-runs/proposal.md b/openspec/changes/inline-fragments-flat-runs/proposal.md index 5bcbc2bb..a9538c10 100644 --- a/openspec/changes/inline-fragments-flat-runs/proposal.md +++ b/openspec/changes/inline-fragments-flat-runs/proposal.md @@ -27,6 +27,7 @@ None. ### Modified Capabilities - `model`: the "Inline text tree" requirement is replaced by requirements for run-based inline text: canonical formatting state, maximal fragments, deterministic fragment order, range queries and insertion inheritance. +- `dom-adapters`: "Inline formatting rendering" re-renders with every fragment overlapping the widened range, since fragments now come back whole and can reach outside the queried range. ## Impact diff --git a/openspec/changes/inline-fragments-flat-runs/specs/dom-adapters/spec.md b/openspec/changes/inline-fragments-flat-runs/specs/dom-adapters/spec.md new file mode 100644 index 00000000..0e34e2fd --- /dev/null +++ b/openspec/changes/inline-fragments-flat-runs/specs/dom-adapters/spec.md @@ -0,0 +1,21 @@ +## MODIFIED Requirements + +### Requirement: Inline formatting rendering +The system SHALL provide `FormattingAdapter`, which registers `InlineTool` instances (from `core:ToolLoaded` events) and renders `InlineFragment`s as DOM wrapper elements, re-rendering affected ranges on `TextFormattedEvent`/`TextUnformattedEvent`. Because fragments are returned whole and can reach outside the queried range, the adapter SHALL widen the range to the boundaries of the returned fragments and query again until the range stops growing, and SHALL render the range with every fragment overlapping it, so formatting that only overlaps the widened range is not lost. + +#### Scenario: Re-rendering overlapping formats +- **GIVEN** a `TextFormattedEvent` or `TextUnformattedEvent` affecting a range +- **WHEN** the adapter re-renders that range +- **THEN** it expands the range by one character on each side to catch adjacent boundary fragments, extracts the range into a template, wraps overlapping fragments using each tool's `createWrapper(data)` output, and replaces the DOM range contents so overlapping/adjacent inline formats nest correctly + +#### Scenario: Formatting that only overlaps the widened range +- **GIVEN** text `abcdefghij` with italic `[0, 2)` and bold `[0, 10)` +- **WHEN** italic is applied over `[8, 9)` +- **THEN** the adapter re-renders `[0, 10)` with bold `[0, 10)`, italic `[0, 2)` and italic `[8, 9)`, so italic `[0, 2)` stays in the DOM + +#### Scenario: Partially unformatting a fragment that contains others +- **GIVEN** text `abcdefghij` with bold `[0, 10)`, italic `[0, 2)` and italic `[8, 10)` +- **WHEN** bold is removed over `[4, 6)` +- **THEN** the adapter re-renders `[0, 10)` with bold `[0, 4)`, bold `[6, 10)` and both italic fragments + +Implemented in `src/FormattingAdapter/index.ts`, `src/utils/collectFragmentsToRender.ts`, `src/utils/surround.ts`, `src/utils/expandRangeNodeBoundary.ts`. diff --git a/openspec/changes/inline-fragments-flat-runs/specs/model/spec.md b/openspec/changes/inline-fragments-flat-runs/specs/model/spec.md index 827fc8a5..d5ad190e 100644 --- a/openspec/changes/inline-fragments-flat-runs/specs/model/spec.md +++ b/openspec/changes/inline-fragments-flat-runs/specs/model/spec.md @@ -7,7 +7,7 @@ ## ADDED Requirements ### Requirement: Inline formatted text -The system SHALL provide `TextNode` as the container of a text data node's value and inline formatting. It SHALL support inserting and removing text, reading text, applying (`format`) and removing (`unformat`) an inline tool over a character range, and listing inline fragments. Indices and ranges SHALL be validated against the current text length, and a range's end SHALL NOT be lower than its start. `insertText`, `removeText`, `format` and `unformat` SHALL dispatch `TextAddedEvent`, `TextRemovedEvent`, `TextFormattedEvent` and `TextUnformattedEvent` respectively, with the affected text range and the current context user. `serialized` SHALL return the text value and the fragments as returned by `getFragments()`. `TextNode` SHALL keep its own copy of the data passed to `format` and SHALL return copies of it in fragments, so changes to those objects don't change its state. +The system SHALL provide `TextNode` as the container of a text data node's value and inline formatting. It SHALL support inserting and removing text, reading text, applying (`format`) and removing (`unformat`) an inline tool over a character range, and listing inline fragments. Indices and ranges SHALL be validated against the current text length, and a range's end SHALL NOT be lower than its start. `insertText`, `removeText`, `format` and `unformat` SHALL dispatch `TextAddedEvent`, `TextRemovedEvent`, `TextFormattedEvent` and `TextUnformattedEvent` respectively, with the affected text range and the current context user. `serialized` SHALL return the text value and the fragments as returned by `getFragments()`. `TextNode` SHALL keep its own copy of the data passed to `format` and SHALL return copies of it in fragments and in the dispatched `TextFormattedEvent`, so changes to those objects don't change its state or the events (and the collaboration operations and undo history built from them). Implemented in `src/entities/inline-text/TextNode/index.ts`, validated by its co-located `.spec.ts`. @@ -34,7 +34,7 @@ Implemented in `src/entities/inline-text/TextNode/index.ts`, validated by its co #### Scenario: Mutating data after formatting - **GIVEN** a `TextNode` with text `abcd` formatted with link over `[0, 4]` using a data object `{ href: 'a' }` - **WHEN** that object's `href` is changed to `b`, or the `data` of a fragment returned by `getFragments()` is changed -- **THEN** `getFragments()` still returns link `[0, 4]` with `{ href: 'a' }` +- **THEN** `getFragments()` still returns link `[0, 4]` with `{ href: 'a' }`, and the dispatched `TextFormattedEvent` still carries `{ href: 'a' }` #### Scenario: Removing all formatted text drops the fragment - **GIVEN** a `TextNode` with text `abcd` formatted with bold over `[1, 3]` diff --git a/openspec/changes/inline-fragments-flat-runs/tasks.md b/openspec/changes/inline-fragments-flat-runs/tasks.md index fb6b6ed3..09b2e470 100644 --- a/openspec/changes/inline-fragments-flat-runs/tasks.md +++ b/openspec/changes/inline-fragments-flat-runs/tasks.md @@ -38,3 +38,5 @@ - [ ] 6.3 Write failing tests, then apply initial fragments in a total order (start, end descending, tool, data) so conflicting fragments load the same in any order - [ ] 6.4 Extend the shared random generator with empty data for non-link tools and random, possibly conflicting, initial fragments loaded in shuffled order against the reference model - [ ] 6.5 Cache `RunList#length`, drop the `#merge` call for inserting into an empty list, and fold `getFragments` filters into one predicate +- [ ] 6.6 Write a failing test, then put a separate copy of the inline data into `TextFormattedEvent`, so mutating the caller's object can't change collaboration operations or undo history built from the event +- [ ] 6.7 Write failing tests, then make `FormattingAdapter` re-query fragments over the widened re-render range until it stops growing (`collectFragmentsToRender` in `dom-adapters/src/utils/`), and start the range from the edit rather than from the first fragment From 87ba227e8abb773331e54a6b158ba01fc54f4045 Mon Sep 17 00:00:00 2001 From: gohabereg Date: Thu, 5 Nov 2026 00:40:41 +0000 Subject: [PATCH 3/3] docs(openspec): require text-node rebuild in FormattingAdapter re-render Co-Authored-By: Claude Opus 5.5 --- openspec/changes/inline-fragments-flat-runs/design.md | 1 + .../inline-fragments-flat-runs/specs/dom-adapters/spec.md | 7 ++++++- openspec/changes/inline-fragments-flat-runs/tasks.md | 1 + 3 files changed, 8 insertions(+), 1 deletion(-) diff --git a/openspec/changes/inline-fragments-flat-runs/design.md b/openspec/changes/inline-fragments-flat-runs/design.md index 98d334b3..4493fec3 100644 --- a/openspec/changes/inline-fragments-flat-runs/design.md +++ b/openspec/changes/inline-fragments-flat-runs/design.md @@ -142,6 +142,7 @@ Our own serialized fragments never overlap for one tool, but external input can - [Fragment order changes for existing documents with overlapping formatting, so DOM nesting can differ from before] → Content and formatting are identical; only wrapper nesting changes, and it becomes stable. Mention it in the PR description. - [`FormattingAdapter`'s incremental re-render can leave empty wrappers (e.g. ``) next to a re-rendered range] → Pre-existing: the same sequence on `main` leaves them too. Out of scope; the model is correct either way. - [`getFragments(start, end)` returns whole merged ranges where the tree used to return split pieces, so a fragment can reach outside the range `FormattingAdapter` queried and overlap fragments it never saw. Rendering the widened range with only the first query's fragments drops formatting from the DOM] → `FormattingAdapter` re-queries over the widened range until it stops growing (`collectFragmentsToRender`) and renders with every fragment overlapping it. The same loss already happened on `main` in some operation orders. +- [Wider re-render ranges push more text through the adapter's rebuild, which assigned the plain text to `template.innerHTML`: text that looks like markup was parsed, shifting offsets and inserting live elements] → The range is rebuilt from a `DocumentFragment` holding a single text node. Pre-existing on `main`; fixed here because this change makes it easier to hit. `dom-adapters` specs now run in jsdom (and as ESM, like `core`) so the rendering is covered by tests. - [Removing exported classes is a breaking change for anyone importing them from `@editorjs/model`] → Nothing in the monorepo does. Listed as BREAKING in the proposal. - [Rewriting a mutation-tested module can lower the Stryker score] → The run code is much smaller; the regression, invariant and randomized tests target it directly. Run `test:mutations` for the model before opening the PR. - [Open conflicts with in-flight PRs] → #192 and #194 touch `EditorDocument`/`BlockNode`/`model-types`, not `inline-fragments/`. The folder rename only changes import paths in `BlockNode` and `entities/index.ts`, which may need a trivial rebase. #192 also edits `BlockNode` specs that build `TextNode`s, which only use the public API. diff --git a/openspec/changes/inline-fragments-flat-runs/specs/dom-adapters/spec.md b/openspec/changes/inline-fragments-flat-runs/specs/dom-adapters/spec.md index 0e34e2fd..6d504a6f 100644 --- a/openspec/changes/inline-fragments-flat-runs/specs/dom-adapters/spec.md +++ b/openspec/changes/inline-fragments-flat-runs/specs/dom-adapters/spec.md @@ -1,7 +1,7 @@ ## MODIFIED Requirements ### Requirement: Inline formatting rendering -The system SHALL provide `FormattingAdapter`, which registers `InlineTool` instances (from `core:ToolLoaded` events) and renders `InlineFragment`s as DOM wrapper elements, re-rendering affected ranges on `TextFormattedEvent`/`TextUnformattedEvent`. Because fragments are returned whole and can reach outside the queried range, the adapter SHALL widen the range to the boundaries of the returned fragments and query again until the range stops growing, and SHALL render the range with every fragment overlapping it, so formatting that only overlaps the widened range is not lost. +The system SHALL provide `FormattingAdapter`, which registers `InlineTool` instances (from `core:ToolLoaded` events) and renders `InlineFragment`s as DOM wrapper elements, re-rendering affected ranges on `TextFormattedEvent`/`TextUnformattedEvent`. Because fragments are returned whole and can reach outside the queried range, the adapter SHALL widen the range to the boundaries of the returned fragments and query again until the range stops growing, and SHALL render the range with every fragment overlapping it, so formatting that only overlaps the widened range is not lost. The re-rendered range SHALL be rebuilt from its plain text as a text node, never parsed as markup, so text that looks like HTML stays text. #### Scenario: Re-rendering overlapping formats - **GIVEN** a `TextFormattedEvent` or `TextUnformattedEvent` affecting a range @@ -13,6 +13,11 @@ The system SHALL provide `FormattingAdapter`, which registers `InlineTool` insta - **WHEN** italic is applied over `[8, 9)` - **THEN** the adapter re-renders `[0, 10)` with bold `[0, 10)`, italic `[0, 2)` and italic `[8, 9)`, so italic `[0, 2)` stays in the DOM +#### Scenario: Text that looks like markup +- **GIVEN** an input whose text contains a literal `y`, an entity-like `<`, or `` +- **WHEN** formatting is applied to a range around that text +- **THEN** the input's text still equals the model text, no element is created from it, and the formatting wraps the expected characters + #### Scenario: Partially unformatting a fragment that contains others - **GIVEN** text `abcdefghij` with bold `[0, 10)`, italic `[0, 2)` and italic `[8, 10)` - **WHEN** bold is removed over `[4, 6)` diff --git a/openspec/changes/inline-fragments-flat-runs/tasks.md b/openspec/changes/inline-fragments-flat-runs/tasks.md index 09b2e470..56ab154e 100644 --- a/openspec/changes/inline-fragments-flat-runs/tasks.md +++ b/openspec/changes/inline-fragments-flat-runs/tasks.md @@ -40,3 +40,4 @@ - [ ] 6.5 Cache `RunList#length`, drop the `#merge` call for inserting into an empty list, and fold `getFragments` filters into one predicate - [ ] 6.6 Write a failing test, then put a separate copy of the inline data into `TextFormattedEvent`, so mutating the caller's object can't change collaboration operations or undo history built from the event - [ ] 6.7 Write failing tests, then make `FormattingAdapter` re-query fragments over the widened re-render range until it stops growing (`collectFragmentsToRender` in `dom-adapters/src/utils/`), and start the range from the edit rather than from the first fragment +- [ ] 6.8 Write failing jsdom-backed `FormattingAdapter` tests (literal tags, entity-like text, HTML in text), then rebuild re-rendered ranges from a text node instead of `template.innerHTML`. Run `dom-adapters` Jest in jsdom and ESM mode so the specs can import the ESM `sdk` build