Architecture #

tokenling is a static site plus a model, with an optional Rust pet host. In local mode the browser owns state, simulation and inference. Remote mode explicitly transfers ownership to the chosen host; the browser becomes a renderer/controller with a recovery checkpoint. See the Rust host. Both run the same rules: the shared Rust crate in core/, linked natively by the host and compiled to WebAssembly for the page.

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/owner data never enter analytics. Local state and generation remain in the browser; remote data go only to the chosen host. 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>/          main.js + brain.js + tokenling_core_bg.wasm, 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; the
 │                         shared engine (WebAssembly) runs the pet's rules
 ├─ worker       brain.js  loads the model, streams tokens; the shared stop and
 │                         context-fit rules from the same module
 ├─ 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 core/wasm/build.sh, the TypeScript checker and site/bundle.mjs, then hashes the emitted app/worker/rules 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 call the engine, which changes the save, then 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.

Execution ownership #

Setup asks local or remote, defaulting to local. Existing v1 saves migrate to local v2 saves without changing pet data. Settings permits both directions. hosting pins mode, selected brain and time zone; a separate browser record holds remote access keys and transfer intent. Exports omit keys and restore as local recovery saves.

Local-to-remote prepares an inactive record before activation and records remote intent before it gives up local execution. Remote-to-local parks the host atomically, fetches the latest full state and resets the browser body clock. Epoch/context checks fence late replies; operation IDs deduplicate retries. An explicit outage recovery uses the last checkpoint and asks the old host to stop when reachable, without overwriting the new local branch.

Remote mode stops browser body/brain scheduling. The host's copy of the same engine owns simulation, lookups, tags, memories and diary; returned effects only animate the LCD, exactly as local effects do. The browser's engine then only holds the latest checkpoint. The host thinks while the page is closed. Its native CPU worker is resident; a separately configured CUDA worker can handle reactive turns. Full serving and GPU performance qualification are separate from prior engine probes.

The pet's turn #

The same engine schedules turns in both modes; the browser's pump() and the host's dispatcher only run what it chooses while a brain is free.

1. Something asks for a turn. 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 (minutes while asleep or with "lively" off), so the pet lives on its own. Today's diary page is written at night once the pet sleeps; missed days follow after 30 quiet seconds. React beats idle; a hidden local page answers reactions only.
2. The engine's chat turn renders the state header and asks the brain to continue Name: after the chat lines that fit (1024 tokens for react turns, 512 for idle ones; fit drops the oldest lines).
3. The brain streams tokens. The shared stop rule ends a line at a newline, or right after a complete lookup tag ([clock], [look], [recall:…], [yesterday]).
4. On a lookup stop the turn appends {result} and asks again with the longer prefix: up to three lookups per line. A line that fails NOT_CUTE is generated again, three tries in all.
5. If the context changed while it was generating (the owner spoke, an offer, a pat, the pet fell asleep), the line is discarded; whatever changed asked for the next turn. Otherwise the engine commits it: the line joins the chat (keeping at most two consecutive silent lines) and its tags take effect: 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"). Effects play on the LCD.

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 a new header or a blank gap, and the engine keeps up to three known [doodle:…] stickers and the paragraphs. A page with unsafe text is dropped and its day stays pending.

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 core/src/world.rs, counted by each brain's tokenizer). 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 in local mode. 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.

Shared rules #

One Rust crate, core/, holds the prompt rendering, closed lists and lookups, stop and fit rules, body math, care and tag effects, turn scheduling, the diary and save reading. The host links it natively; the page and its worker load the same code as WebAssembly through wasm-bindgen and serde-wasm-bindgen. Preact/canvas, browser storage/lifecycle and browser inference stay in TypeScript; HTTP, SQLite, queue routing and native inference stay in the host. Python keeps independent training-format parity.

Time, calendar and random draws are inputs, so both builds replay the same scenario identically (server/tests/parity.mjs). The browser keeps the engine inside the module and reads a snapshot after changes; a plain one-second tick reads only the body fields, so the transcript and diary do not cross the boundary every second, and canvas frames never do. The module is part of the content-hashed app directory and the offline cache, and loads before the save is read.