Editor and synchronization
What is this about?
In short: your text is stored as a structured tree and not as loose characters. We derive scenes on the server from this text, and every change carries a version so that conflicts stand out. This keeps text and scene data together, even when several people and devices are involved.
Protection goal
Text and the data attached to it should not drift apart. No change should silently overwrite another, and comments should stay at their place in the text.
How it works
- Structured text: The editor (TipTap) works with a tree of building blocks and not with raw HTML. This makes it checkable and allows references in the text.
- Scenes from the text: The scene divider in the text is the only source. When saving, the server derives the scene data from it, in the same transaction as the version check. The interface does not keep a second scene list of its own.
- Scenes are kept: If a divider disappears from the text, the scene is only marked as deleted. Linked data such as hints or character assignments is not lost, and if you restore the divider, the scene returns.
- Versions: Every save names the state it builds on. If it differs from the state on the server, the server reports a conflict, and you decide in the conflict dialog.
- Mentions: Characters, locations and other entries appear in the text as a reference to the entry and not as a bare name. If an entry is renamed, the text follows, unless you deliberately chose an alias.
- Comments: They are attached to a mark in the text and not to a character position. If the mark is lost, a stored text excerpt helps to find the place again.
- Claiming chapters: Whoever is editing a chapter can mark it as “being edited”. Others see the note.
Measures
- We derive scenes on the server so that the interface, the offline state and the database do not drift apart.
- We reject a save based on an outdated state instead of silently displacing the newer version.
- We do not merge automatically. In case of a conflict you choose, so no offline work is lost unnoticed.
- We use fixed identifiers for mentions so that renaming does not break anything.
- The text is checked when saving and limited to an allowlist.
What we do not promise
- There is no simultaneous writing in the same paragraph as in real-time editors. In case of a conflict, you decide.
- Claiming a chapter is a note that helps avoid conflicts, not an assurance that nobody else is writing.
- A comment can lose its place in the text if the text is heavily rebuilt there. The excerpt then helps, but it does not find the right place in every case.
How we check this
Deriving scenes, saving at the same time and claiming chapters have automated tests, which the table below names. The “Race Conditions” scenario is in the monthly report.
Evidence tests
| Test | What the test proves |
|---|---|
ChapterContentSyncServiceTest |
Scenes are derived on the server from the submitted text. |
ChapterContentSaveRaceConditionTest |
Saving the same chapter at the same time does not overwrite anything silently. |
ChapterContentAstSecurityTest |
Crafted or oversized texts are rejected without leaving traces. |
ChapterClaimTest |
A chapter can be claimed as “being edited”. |
ChapterClaimRaceConditionTest |
If two users claim the same free chapter at the same time, only one wins. |
MentionAstIntegrityTest |
Mentions in the text remain valid references to their entries. |
Change history
- : First version.