How it works
What happens inside Write, and when. The docs say what each tool does; this page shows what fires behind it: which event starts what, what waits for what, and what ever leaves your device.
Each diagram reads from top to bottom or left to right. The names in code are the source files in the repository, for anyone who wants to look closer.
The big picture
Write is a static website. There is no server of its own and no account: the pages, the code and the dictionary are plain files, and everything you write stays in your browser. Only two things can reach out, and only once you switch them on: an AI you connect, and online word look-ups.
flowchart TD
subgraph site["The website (static files)"]
pages["Pages
/ · /write/ · /docs/"]
code["App code"]
dict["Dictionary shards
/dict/v2/en · de"]
end
subgraph browser["Your browser"]
app["The app
(editor and tools)"]
sw["Service worker
offline copy"]
ls[("localStorage
documents · settings")]
worker["Writing check
(Harper · retext)"]
end
subgraph optional["Only when you switch them on"]
ai["Your AI
Ollama · llama.cpp · API key"]
dm["Datamuse
online words"]
end
site --> sw --> app
app <--> ls
app <--> worker
app -. "the passage you ask about" .-> ai
app -. "one word" .-> dm
Opening the app
When /write/ opens, the app reads its settings and documents from the browser, opens the document you had last, and sets up the page before it shows anything (no flicker of the wrong font or colour). The service worker registers after the page has loaded. A first visit gets the tour invitation a moment later.
sequenceDiagram autonumber participant B as Browser participant M as App (main.ts) participant S as localStorage participant W as Service worker B->>M: open /write/ M->>S: read writing:settings and writing:docs S-->>M: settings, documents M->>M: open the last document, or a new empty one M->>M: apply font, size, paper, margins, focus mode M->>M: count words, list documents, centre the caret B->>W: page loaded: register /sw.js W-->>M: ready (Settings shows "works offline") Note over M: first visit only:
after 1.2 s the ? offers the tour
Saving
There is no save button for your work in progress: every change is saved in the browser half a second after you stop typing. While a save is waiting, a small dot shows beside the word count. Closing the tab saves at once. Saving to a file (⌘S) is a separate thing, for a copy on your disk.
flowchart TD
type(["You type, paste, take a synonym …"]) --> upd["Editor 'update' event"]
upd --> count["Word count updates"]
upd --> dot["Dot appears: a save is waiting"]
dot --> wait{"500 ms
without a change?"}
wait -- "another change" --> dot
wait -- yes --> persist["persist(): document → JSON,
into its sheet, time stamped"]
persist --> write[("localStorage
writing:docs")]
write -- ok --> clear["Dot disappears"]
write -- "storage full" --> full["Note: storage is full
· Back up now"]
close(["Tab closes, or you open
another document"]) --> persist
A document holds its sheets, its pinned thought and its stash. Versions, notes and ghosted text live inside the text itself, so undo and redo cover them too.
Offline and updates
The service worker keeps a copy of the app on your device. Pages open from that copy right away, dictionary shards are kept as they're used (or all at once from Settings → Offline), and anything going to another site, like the AI or online look-ups, is never touched.
flowchart TD
req(["The browser asks for a file"]) --> other{"Another site?
(AI, Datamuse)"}
other -- yes --> net["Straight to the network,
never cached"]
other -- no --> kind{"What is it?"}
kind -- "a page (/ or /write/)" --> shell["From the app's copy
(network only if missing)"]
kind -- "/dict/…" --> dc["From the dictionary cache,
else fetched and kept"]
kind -- "anything else" --> rc["From any cache,
else fetched and kept"]
A new release never switches under your hands. Each build has its own version, made from its files. When the browser finds a new one, it waits until you say so.
sequenceDiagram
autonumber
participant D as Vercel
participant W as New service worker
participant M as App
participant Y as You
Note over D: a push to main builds and deploys
M->>D: on load, and every hour: anything new?
D-->>W: new sw.js, new version
W->>W: install: keep the new app files
W-->>M: installed, waiting
M->>Y: note: "A new version is ready · Reload"
Y->>M: Reload
M->>W: skip-waiting
W->>W: activate: drop the old files
W-->>M: controller changed
M->>M: reload the page (your text is already saved)
Controls that fade
The controls step back while you write and come back when you reach for the mouse. A trembling hand resting on the mouse doesn't count: it has to move a few pixels.
stateDiagram-v2 [*] --> Shown Shown --> Writing: a key in the text
(open panels close) Writing --> Shown: mouse moves ≥ 4 px Shown --> Resting: mouse still for 4 s,
no panel open Resting --> Shown: mouse moves Writing --> Shown: esc Shown --> Writing: esc
Synonyms
The Synonyms card opens at once and fills in as answers arrive. The dictionary answers first, from a small file of a few KB, kept after the first time. If an AI has been set up, it reads the sentence and moves the words that fit to the front. Online words and More with AI only run when you ask for them.
sequenceDiagram autonumber participant Y as You participant C as Synonyms card participant B as Dictionary (book.ts) participant A as Your AI participant O as Datamuse Y->>C: Synonyms (menu, or ⌘⇧E) C->>C: split into words, skip little ones (a, the, of …) C->>B: look up each word (and its base form) B-->>C: meanings and their words C->>C: put each word in the right form
(walked → strolled, Bigger → Larger) opt An AI has been set up C->>A: which of these fit this sentence? A-->>C: the fitting ones, best first end C-->>Y: the list, closest words first opt Online look-ups switched on C->>O: the one word O-->>C: related words (kept only if the dictionary knows them) end opt More with AI / Ask the AI Y->>C: click, or Enter C->>A: the sentence and the word A-->>C: new words, checked against the sentence end Y->>C: point at a word → shown in the text (nothing changes) Y->>C: click or Enter → it goes in, as a version of the word
The keys in the card: ← → ↑ ↓ and Tab move through the words and the buttons (Ask the AI, More words online, More with AI), Enter takes, esc closes, and typing on puts the card aside.
Versions
A passage with versions carries all of them inside the text, with a note of which one is shown. That's why they save with the document and undo just works. The original is always version 1.
stateDiagram-v2 [*] --> Plain: text you wrote Plain --> HasVersions: New version · Rewrite · Shorten ·
a synonym taken HasVersions --> HasVersions: flip ↑ ↓ / ⌘⌥↑ ⌘⌥↓,
add another, delete one HasVersions --> Comparing: Compare Comparing --> HasVersions: Use this, or click away HasVersions --> Plain: Keep this one,
or only one is left
flowchart LR nv(["New version"]) --> copy["A copy below,
old words selected"] copy --> typing["You type"] typing -- Enter --> keep["Kept: a new version,
shown in the text"] typing -- esc --> back["Taken back"] ai(["Rewrite · Shorten"]) --> ask["The AI gets the passage,
its paragraph, the ones around it
and your pinned thought"] ask --> three["Options in a card
(Rewrite: 3, Shorten: 2)"] three -- "point" --> preview["Shown in the text"] three -- "click / Enter" --> keep
The AI
Write has no AI of its own. It talks to one you choose: a model on your computer, or a hosted service with your API key. The first time the app needs it, it looks for one and remembers who answered until that server stops answering.
flowchart TD
need(["An AI action: Rewrite, Ask the AI, the lab …"]) --> known{"Found one already?"}
known -- yes --> send
known -- no --> mode{"Settings: which kind?"}
mode -- "API key" --> haskey{"Key and address set?"}
haskey -- no --> setup["'AI isn't ready yet'
· Open AI setup"]
haskey -- yes --> list["Ask the service for /models"]
mode -- "On this computer" --> addr{"Address given?"}
addr -- yes --> probe1["Ask that address"]
addr -- no --> probe2["Ask localhost:11434 (Ollama),
then localhost:8080 (llama.cpp)"]
probe1 & probe2 --> which{"Who answers?"}
which -- "/v1/models (llama.cpp, LM Studio)" --> ok
which -- "/api/tags (Ollama)" --> ok
which -- nobody --> setup
list -- "401 / 403" --> bad["'The service didn't accept
the API key'"]
list -- ok --> ok["Remembered for next time"]
ok --> send["Send the request,
answer constrained to JSON"]
send -- "network error" --> forget["Forget the server,
look again next time"]
What goes to the AI: the passage you asked about, its paragraph, the paragraphs just before and after, and the thought you pinned. Never the whole document. With a model on your own computer, none of it leaves your machine.
Nothing calls the AI unasked, with one exception you opt into by setting one up: once you have, the Synonyms card asks it which words fit the sentence, and the menu warms up synonyms for a single word.
Writing suggestions
When switched on in Settings, grammar and clarity hints are checked in your browser, in a background worker, so typing never waits for them. Nothing is sent anywhere. Ghosted text and code are skipped.
flowchart TD
edit(["You stop typing"]) --> t{"550 ms quiet?"}
t -- yes --> seg["Split the text into checkable pieces
(no ghosted text, no code)"]
seg --> w["Background worker"]
w --> h["Harper: grammar, spelling"]
w --> r["retext: repeated words,
simpler words, long sentences"]
h & r --> back["Results, by position"]
back --> dots["Dotted underlines in the text"]
dots -- "right-click" --> tip["The tip, with the fix one click away"]
What is stored where
Everything is in this browser, on this device. Clearing the site's data deletes it, so back up now and then (☰ → Back up all documents).
writing:docs | Every document: its sheets, versions, notes, pinned thought, stash and the poem form it's written towards |
writing:settings | Font, size, paper, margins, focus, typewriter mode, poetry switches, the AI's address, model and API key |
writing:card | How you last set a picture to share: shape, look, colours, type, safe zone, position, signature, watermark |
writing:poem-marks, writing:poem-width, writing:poem-learn | The poem panel: letters beside the lines, its width, the Learn fold |
writing:places, writing:settings-open | Where the caret was in each document; which settings groups are open |
writing:instructions | Your recent instructions to the AI |
writing:ai-known | An AI has answered here before (so the Synonyms card may ask it) |
writing:lookup-online | Online look-ups switched on |
writing:dict-offline | The whole dictionary was kept on the device |
writing:tour-offered, writing:privacy-seen | The tour and the privacy note have been shown once |
Cache writing-shell-… | The app itself, one per version |
Cache writing-dict-v2 | Dictionary shards already used |
Cache writing-runtime | Fonts and other files fetched once |
What can leave your device, and only after you switch it on: the passage you ask the AI about (to the server you chose), and the one word you look up online (to Datamuse).
Routines
For whoever runs the site.
Shipping a change
- Try it locally with
npm run dev(the app is atlocalhost:5173/write/). npm run buildchecks the types and builds intodist/, with a fresh service worker version.- Raise the version in
package.json(it shows in the ? panel), add the release toCHANGELOG.md, and tag it (git tag v0.2.0). - Push to
mainwith its tags. Vercel builds and deploys it to production in about a minute. - Open the site. Writers with it open see "A new version is ready" within the hour (or on their next visit) and choose when to reload. The ? panel shows the commit and build time of the version running.
Answering feedback
- Reproduce it on the live site, in the browser it was seen in. Safari behaves differently for the AI.
- Fix, then try it with the mouse and with the keyboard alone.
- Ship, check the deployment is live, then reply with what changed and that a reload brings it in.
Rebuilding the dictionary
- Download OpenThesaurus and WordNet 3.1 into
data/raw/. - Run
python3 -I scripts/build_thesaurus.py data/raw/openthesaurus/openthesaurus.txt data/raw/wordnet/dict public/dict. - If the shard format changed, raise the folder (
v2→v3) and the cache name insw/sw.jsandsrc/offline.tstogether, so no browser mixes old and new shards.