Architecture #

tokenling is a static site plus a model. Everything runs in the visitor's browser; the server only hands out files.

A deployment may enable a separate Cloudflare Web Analytics beacon for page traffic and performance. The builder adds it and its disclosure only when a site token is configured; pet state and generation remain in the browser. See deployment.md for configuration and privacy checks.

<base>/                                     (static files from any web server)
 ├─ index.html           site/index.html with its placeholders filled (site/build.sh)
 ├─ bench.html           test/bench.html with the release's model/runtime, unlinked
 ├─ sw.js                site/sw.js: offline copies and alerts
 ├─ assets/              site/assets/* (font, manifest, icons)
 ├─ app/<hash>/*.js      bundled main.js + brain.js, content-hashed together
 ├─ models/<id>/         tokenizer + config + onnx/model_q4.onnx
 └─ runtime/<name>/      transformers.min.js + ONNX Runtime Web .wasm/.mjs

browser
 ├─ main thread  main.js   Preact components + typed app controllers
 │                         scene.ts, sprites.ts and world.ts bundled inside
 ├─ worker       brain.js  loads the model, streams tokens, stops on line/lookup
 ├─ service worker sw.js   serves the offline copies, shows alerts
 ├─ localStorage "tokenling.v1"  the whole pet (JSON, see pet-simulation.md)
 ├─ Web Lock "tokenling.v1"      held by the one tab that runs the pet
 └─ Cache Storage "transformers-cache"  the downloaded model files
                  "tokenling-app"       page, app and runtime for offline use
                  "tokenling-alerts"    the alert plan

Modules #

site/build.sh runs the TypeScript checker and site/bundle.mjs, then hashes the emitted app/worker bytes together. The host page loads main.js and supplies only #pet-root, #pet-config, styles and static explanatory content. Preact owns all interactive markup. There is no hydration or server rendering.

The body remains independent of Preact: controllers change typed state and notify subscribers at ticks, actions and token updates. Components own form inputs, tab selection and refs. The canvas effect cancels its animation frame and removes input listeners when it unmounts (including tab takeover). The host contract is in host-page.md.

The pet's turn #

1. Something asks for a turn (wantTurn). React turns follow an owner message, an offer, a pat, cleaning, the lights, poop, waking, growing up, coming back or the end of a game. Idle turns come every 8–20 s while the tab is visible (minutes while asleep or with "lively" off), so the pet lives on its own. pump() runs one turn at a time; react beats idle.
2. petTurn() renders the state header (Wd.header("chat", worldState())) and asks the worker to continue Name: after the chat lines that fit (1024 tokens for react turns, 512 for idle ones).
3. The worker streams tokens. It stops at a newline, or right after a complete lookup tag ([clock], [look], [recall:…], [yesterday]).
4. On a lookup stop, petLine() appends {result} computed by Wd.toolResult and calls the worker again with the longer prefix. Up to three lookups per line.
5. If new lines arrived while it was generating, the line is discarded and the turn re-run with the new context. Otherwise the line is filtered (NOT_CUTE), appended to S.chat (keeping at most two consecutive silent lines), and applyTags() performs its effects: answer an open offer ([yes] eats, bathes, takes medicine or starts the game), walk, animate, show a want bubble, save a memory, put a gift on the shelf, note something for the diary, fall asleep or show a dream. Sleeping offers wake on acceptance; other sleeping lines only show dreams. An offer the pet saw but did not answer counts as no.
6. The chat view renders the line as plain text plus small "tool" chips, or a silent line as a short action ("Mochi toddles left, bounces").

The diary uses the same machinery with a ## tokenling diary header, the day's log as context and the prefix dear diary,; it runs to <|endoftext|> and the app strips and stores [doodle:…] stickers.

Where the model comes from #

teacher data ───────► train/gen_data.py ──► new.jsonl ─┐
older dataset ─────────────────────────────────────────┴► train/mix_data.py ► data.jsonl
                                               │ train/train.py (full fine-tune)
GPT-2 (124M) ─────────────────────────────────►ckpt (safetensors)
                                               │ train/export.sh
                                  optimum ONNX ► quantize.py ► model_q4.onnx + SHA256SUMS
                                               │ train/publish.sh
                                  <base>/models/<id>/

See training.md and export-and-runtime.md.

Constraints that shaped the design #

• The brain decides. Every choice the pet makes comes from a tag the model emits; the app runs the body and carries out decisions. That means many short generations (an idle turn every few seconds), so speed and prompt length matter more than eloquence.
• Context is 1024 tokens. The header is about 150 tokens, so the chat view sent to the model keeps only the newest lines that fit (fit() in brain.ts). Long-term knowledge lives in the header's remembers: and today: lines and in lookups, not in raw history.
• GPT-2 small is small, on purpose. Behavior is taught by example; it cannot follow instructions, and its occasional silliness is part of the pet. Everything it should "know" is in the prompt format.
• Phones. A 97 MB download, WebAssembly only, about 0.8 GB of page memory once loaded (measured on desktop Chromium; phones not measured).
• Storage. localStorage is about 5 MB, enough for state; the model goes in Cache Storage, and the page asks for persistent storage so it is not evicted.
• Speed. About 35 tokens/s on a 4-thread desktop WebAssembly session (see export-and-runtime.md); most turns are a few tokens.