Write

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:docsEvery document: its sheets, versions, notes, pinned thought, stash and the poem form it's written towards
writing:settingsFont, size, paper, margins, focus, typewriter mode, poetry switches, the AI's address, model and API key
writing:cardHow you last set a picture to share: shape, look, colours, type, safe zone, position, signature, watermark
writing:poem-marks, writing:poem-width, writing:poem-learnThe poem panel: letters beside the lines, its width, the Learn fold
writing:places, writing:settings-openWhere the caret was in each document; which settings groups are open
writing:instructionsYour recent instructions to the AI
writing:ai-knownAn AI has answered here before (so the Synonyms card may ask it)
writing:lookup-onlineOnline look-ups switched on
writing:dict-offlineThe whole dictionary was kept on the device
writing:tour-offered, writing:privacy-seenThe tour and the privacy note have been shown once
Cache writing-shell-…The app itself, one per version
Cache writing-dict-v2Dictionary shards already used
Cache writing-runtimeFonts 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

  1. Try it locally with npm run dev (the app is at localhost:5173/write/).
  2. npm run build checks the types and builds into dist/, with a fresh service worker version.
  3. Raise the version in package.json (it shows in the ? panel), add the release to CHANGELOG.md, and tag it (git tag v0.2.0).
  4. Push to main with its tags. Vercel builds and deploys it to production in about a minute.
  5. 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

  1. Reproduce it on the live site, in the browser it was seen in. Safari behaves differently for the AI.
  2. Fix, then try it with the mouse and with the keyboard alone.
  3. Ship, check the deployment is live, then reply with what changed and that a reload brings it in.

Rebuilding the dictionary

  1. Download OpenThesaurus and WordNet 3.1 into data/raw/.
  2. Run python3 -I scripts/build_thesaurus.py data/raw/openthesaurus/openthesaurus.txt data/raw/wordnet/dict public/dict.
  3. If the shard format changed, raise the folder (v2 → v3) and the cache name in sw/sw.js and src/offline.ts together, so no browser mixes old and new shards.