toddstack-frontend-engine
An app-agnostic frontend core: the Elm-style loop update(model, msg) -> effects. Part of
toddstack.
All client logic of an app lives in one Rust core. Web runs it as wasm in a module worker; iOS and Android run it through UniFFI. Shells (browser, Swift, Kotlin) only draw view models and run effects. The core never reads a clock, network, disk or randomness: everything it needs arrives as an input, so one headless harness can run it against a fake clock, network and random on every target and get byte-identical results.
The pattern
Appis the one trait:boot,update(action),resolve(effect id, result),view(key),screen(),actions(). State machines are plain enums in your model.- Effects are data.
updatecallsctx.emit(...); the shell runs the effect and answers withresolve. Time isctx.at(), the wall clock of the input being handled. - Views are keyed JSON.
updatemarks keys dirty (ctx.dirty("home")); the engine hashes each dirty view and reports it only when its bytes changed, so shells redraw only what changed. - Introspection lists the screen and the actions legal right now, with JSON schemas. The same protocol is the debug protocol: a person (or an agent) can drive an app over NDJSON.
- Pointer fast path:
Bridge::pointer(phase, x, y, at_ms)skips JSON for drags and drawing. The units ofxandyare yours.
Effects
Built in (Effect<X>): Http, Timer, CancelTimer, Store, Secure, Random, Navigate,
OpenAuthBrowser, Reload, LoadBlob, Span, Log, Report.
Your own go in the app's effect type X (type Effect = MyEffect on your App), emitted with
ctx.emit_app(...). They serialize flat next to the built-ins, so a shell matches on one key:
{"id":4,"Vibrate":{"ms":10}}. Haptics, sound, share sheets, push registration and review prompts
are app effects, not built in. An app with none uses NoEffect.
Name rule: an app effect must not be named like a built-in (Http, Timer, ...; see
BUILT_IN_EFFECT_NAMES). It serializes identically and reads back as the built-in. The runtime
debug_asserts this on every flush, so tests and debug builds catch it.
Pending<T> remembers, per effect id, what the app was doing when it asked, so resolve is a match
over an enum. RetryPolicy (exponential backoff, jitter drawn by the caller) and ClockOffset
(server time from the lowest-round-trip sample) are deterministic helpers.
A minimal app
use Deserialize;
use ;
use ;
Runtime::<Counter>::new(boot_bytes) implements Bridge: bytes in (dispatch), bytes out. The
example feature ships a fuller version (example::Counter) with a state-machine enum for a retried
fetch, a Store restore and an app-defined Vibrate effect; it is the app the tests run.
The wire (NDJSON)
One JSON object per line in, one per line out; every response carries "v" (BRIDGE_PROTOCOL).
Inputs: {"at":ms,"act":<Action>}, {"resolve":{"id":3,"ok":<v>}} or {"resolve":{"id":3,"err":"msg"}},
{"pointer":{"phase":0,"x":1.0,"y":2.0}}, {"view":"key"}, {"introspect":{}}, {"flush":{}}.
Responses to act, resolve, pointer and flush: {"dirty":[...],"effects":[{"id":1,...}]}.
Features
| feature | adds |
|---|---|
testing |
testing::{World, Session, Script, run_file, run_repl}: a fake clock, timers, store and seeded random; scripted HTTP with latency and delay; a JSON-lines scenario runner with snapshots; an NDJSON REPL. Uses std::fs: dev-dependency only |
wasm |
export_wasm_core!(MyApp): the wasm-bindgen Core class for a cdylib |
ffi |
export_uniffi_core!(MyApp): the UniFFI Core object for a staticlib / cdylib |
example |
the counter example app |
The consuming crate depends on wasm-bindgen (or uniffi) itself, at the exact version this crate
pins, and invokes the macro once. Build the wasm with
cargo build --target wasm32-unknown-unknown --features wasm and wasm-bindgen --target web.
Scenarios
A scenario is a .jsonl file, one step per line (# and blank lines skipped):
{"http":{"GET /api/count":[{"status":503},{"status":200,"body":{"count":42}}]}}
{"boot":{"v":1,"at":5000}}
{"send":{"act":"Fetch"}}
{"expect":{"effects":[{"Timer":{"after_ms":250}}],"view":{"counter":{"count":0}},"actions":["Inc"]}}
{"advance_ms":250}
{"snapshot":"counter"}
Steps: boot ($APP_VERSION is replaced from Options::app_version), http (scripted routes, a list
answers in order and repeats the last; latency_ms, delay_ms, body_file; a body of "$now+5"
follows the fake clock), send, pointer, blob, advance_ms, expect (partial match of
effects, dirty, view, screen, actions) and snapshot (exact match against
<snapshot_root>/<scenario>/<n>.json; set Options::golden to write them). App-defined effects the
fake world cannot answer are recorded; give Options::answerer (or Session::answerer) to answer
them. run_file returns the response log, so a test can run a scenario twice and compare.
The JavaScript side
js/ holds the typed browser half (a Deno-checked TypeScript package, copy or bundle it into the app):
protocol.ts (page and worker messages), worker.ts (serveCore: the module worker that owns the
wasm, transfers each dirty view's bytes, fetches LoadBlob blobs and drops replies from a replaced
core) and client.ts (connect and CoreClient: watch a view key, send actions, run timers and hand
every other effect to your run function).
What a native shell implements
Swift and Kotlin runners for the built-in effects are not part of this crate yet. A native shell
needs: an HTTP client for Http (answering {"status","body","sent","recv"}, auth from the
Keychain/Keystore token), timers, key-value and secure storage, a random source, navigation, an auth
browser session, and a fire-and-forget logger; plus a runner for each of the app's own effects. The
UniFFI object is dispatch / pointer / view / provide_blob, bytes in and out.