Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
82a5f08
test(model): pin TextNode formatting contract before the run rewrite
gohabereg Oct 6, 2026
9846ed7
feat(model)!: store TextNode inline formatting as canonical runs
gohabereg Oct 6, 2026
bc8c17d
refactor(model): drop dead branches in run helpers, update docs for runs
gohabereg Oct 6, 2026
f130c7c
refactor(model): simplify run lookup for text insertion
gohabereg Oct 6, 2026
993b7b0
refactor(model): model runs as Mark, Run and RunList classes
gohabereg Oct 6, 2026
c72b2b6
refactor(model): rename Run and Mark to TextRun and TextMark
gohabereg Oct 6, 2026
f875e1c
refactor(model): rename inline-fragments folder to inline-text
gohabereg Oct 6, 2026
5b82d93
test(model): check run invariants on RunList, drop TextNode test acce…
gohabereg Oct 7, 2026
4784337
fix(model): keep inline formatting canonical for equal data and confl…
gohabereg Oct 7, 2026
1f345eb
docs(model): leave todos for InlineTreeNodeSerialized rename and undo…
gohabereg Oct 7, 2026
6c0a33c
docs(openspec): check off inline-fragments-flat-runs tasks
gohabereg Oct 7, 2026
45487f4
fix(model): copy inline data into TextFormattedEvent
gohabereg Oct 17, 2026
10af813
fix(dom-adapters): re-render formatting with every fragment overlappi…
gohabereg Oct 17, 2026
7162188
Merge branch 'spec/inline-fragments-flat-runs' into feat/inline-fragm…
gohabereg Oct 17, 2026
5959c25
fix(dom-adapters): rebuild re-rendered ranges from a text node, not p…
gohabereg Nov 5, 2026
50ee9d3
Merge branch 'spec/inline-fragments-flat-runs' into feat/inline-fragm…
gohabereg Nov 5, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 19 additions & 26 deletions docs/diagrams/model-tree-structure.mmd
Original file line number Diff line number Diff line change
Expand Up @@ -68,30 +68,24 @@ classDiagram
+update(value: T)
}

class ParentInlineNode {
<<abstract>>
+children: InlineNode[]
+insertText(text, index?)
+removeText(start?, end?)
+format(tool, start, end, data?)
+unformat(tool, start, end)
+getFragments(start?, end?): InlineFragment[]
class RunList {
+length: number
+insert(text, offset)
+remove(start, end): string
+setMark(start, end, mark)
+removeMark(start, end, tool)
+toFragments(): InlineFragment[]
}

class FormattingInlineNode {
+tool: InlineToolName
+data?: InlineToolData
+format(tool, start, end, data?)
+unformat(tool, start, end)
+split(index): FormattingInlineNode
class TextRun {
+text: string
+marks: TextMark[]
}

class TextInlineNode {
+value: string
+length: number
+insertText(text, index?)
+removeText(start?, end?)
+format(tool, start, end, data?): InlineNode[]
class TextMark {
+tool: InlineToolName
+data?: InlineToolData
+equals(mark): boolean
}

%% ── Caret management ─────────────────────────────
Expand Down Expand Up @@ -125,7 +119,7 @@ classDiagram
BlockNode --|> EventBus
BlockTune --|> EventBus
ValueNode --|> EventBus
ParentInlineNode --|> EventBus
TextNode --|> EventBus

%% Document composition
EditorJSModel "1" *-- "1" EditorDocument : document
Expand All @@ -136,11 +130,10 @@ classDiagram
BlockNode "1" *-- "0..*" ValueNode : data[key]
BlockNode "1" *-- "0..*" BlockTune : tunes[name]

%% Inline tree
TextNode --|> ParentInlineNode
FormattingInlineNode --|> ParentInlineNode
ParentInlineNode "1" *-- "0..*" FormattingInlineNode : children
ParentInlineNode "1" *-- "0..*" TextInlineNode : children
%% Inline formatting runs
TextNode "1" *-- "1" RunList : runs
RunList "1" *-- "0..*" TextRun : runs
TextRun "1" o-- "0..*" TextMark : marks

%% Caret management (declared last → placed right)
EditorJSModel "1" *-- "1" CaretManager : caretManager
Expand Down
2 changes: 1 addition & 1 deletion docs/model.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ Internally it owns an `EditorDocument` (ordered `BlockNode[]`) and a `CaretManag

Each `BlockNode` contains keyed data nodes:

- `TextNode`: rich text with inline tree (`FormattingInlineNode` + `TextInlineNode`).
- `TextNode`: rich text. Inline formatting is stored as runs: pieces of text with the set of marks (inline tool + data) applied to every character. Runs are canonical (no empty runs, neighbours never have equal mark sets, at most one mark per tool), so the same formatting always gives the same state. `getFragments()` derives maximal fragments from the runs, sorted by start, then end descending, then tool name.
- `ValueNode<T>`: non-text typed value for tools.
- `BlockTune`: per-block tune configuration.

Expand Down
52 changes: 26 additions & 26 deletions openspec/changes/inline-fragments-flat-runs/tasks.md
Original file line number Diff line number Diff line change
@@ -1,43 +1,43 @@
## 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
- [x] 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
- [x] 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`
- [x] 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
- [x] 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
- [x] 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)
- [x] 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`
- [x] 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
- [x] 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
- [x] 3.2 Make `format`/`unformat` return `void` and update their callers' types if needed (`BlockNode`)
- [x] 3.3 Make the section 1 and 2 tests pass
- [x] 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
- [x] 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`
- [x] 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
- [x] 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
- [x] 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
- [x] 5.2 Run `yarn lint` for the touched packages and `test:mutations` for `@editorjs/model`; make sure the score stays above the threshold
- [x] 5.3 Check formatting in the playground once by hand (overlapping bold/italic, undo/redo of formatting)
- [x] 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
- [ ] 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
- [x] 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
- [x] 6.2 Write failing tests, then make `TextMark` keep a deep copy of its data and `RunList#toFragments` return copies (`cloneInlineData` in `utils/`)
- [x] 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
- [x] 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
- [x] 6.5 Cache `RunList#length`, drop the `#merge` call for inserting into an empty list, and fold `getFragments` filters into one predicate
- [x] 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
- [x] 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
- [x] 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
2 changes: 1 addition & 1 deletion openspec/config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ context: |
Tech stack: TypeScript, Yarn 4 (Berry) workspaces monorepo (packages/*, packages/tools/*).
Domain: Editor.js document model - a collaborative rich-text editor engine (block/inline
data tree, operational-transform based collaboration, pluggable block/inline tools).
Key packages: model (EditorJSModel/EditorDocument/BlockNode/inline-fragments/CaretManager),
Key packages: model (EditorJSModel/EditorDocument/BlockNode/inline-text/CaretManager),
model-types (shared event/type contracts), core, dom-adapters, ot-server (collaboration/OT
server), sdk (public API for building tools/plugins - tools should depend on this, not on
model directly), ui, collaboration-manager, and packages/tools/* (built-in block/inline
Expand Down
2 changes: 1 addition & 1 deletion packages/dom-adapters/jest.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import type { JestConfigWithTsJest } from 'ts-jest';

export default {
preset: 'ts-jest',
testEnvironment: 'node',
testEnvironment: 'jsdom',
testMatch: [ '<rootDir>/src/**/*.spec.ts' ],
modulePathIgnorePatterns: [ '<rootDir>/.*/__mocks__' ],
extensionsToTreatAsEsm: ['.ts'],
Expand Down
5 changes: 3 additions & 2 deletions packages/dom-adapters/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@
"lint": "eslint ./src",
"lint:ci": "yarn lint --max-warnings 0",
"lint:fix": "yarn lint --fix",
"test": "jest",
"test": "node --experimental-vm-modules $(yarn bin jest)",
"test:coverage": "yarn test --coverage=true",
"test:mutations": "stryker run",
"test:mutations": "NODE_OPTIONS=\"$NODE_OPTIONS --experimental-vm-modules\" stryker run",
"clear": "rm -rf ./dist && rm -rf ./tsconfig.build.tsbuildinfo"
},
"devDependencies": {
Expand All @@ -28,6 +28,7 @@
"eslint-config-codex": "^2.0.3",
"eslint-plugin-import": "^2.29.0",
"jest": "^29.7.0",
"jest-environment-jsdom": "^29.7.0",
"stryker-cli": "^1.0.2",
"ts-jest": "^29.2.5",
"ts-node": "^10.9.2",
Expand Down
Loading
Loading