toddstack-frontend-engine 0.1.0

App-agnostic Elm-style frontend core: update(model, msg) -> effects, an NDJSON bridge, dirty-key views, introspection, and a headless test harness. Runs as wasm in a worker or through UniFFI.
Documentation
# toddstack-frontend-engine

An app-agnostic frontend core: the Elm-style loop `update(model, msg) -> effects`. Part of
[toddstack](https://github.com/goddtriffin/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

- **`App`** is 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.** `update` calls `ctx.emit(...)`; the shell runs the effect and answers with
  `resolve`. Time is `ctx.at()`, the wall clock of the input being handled.
- **Views are keyed JSON.** `update` marks 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 of `x` and `y` are 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_assert`s 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

```rust
use serde::Deserialize;
use serde_json::{Value, json};
use toddstack_frontend_engine::{ActionSpec, App, Ctx, Effect, NoEffect};

#[derive(Deserialize)]
enum Action { Inc, Load }

#[derive(Default)]
struct Counter { count: i64, loading: bool }

impl App for Counter {
    type Action = Action;
    type Effect = NoEffect;

    fn boot(_boot: &Value, ctx: &mut Ctx<NoEffect>) -> Self {
        ctx.dirty("counter");
        Self::default()
    }

    fn update(&mut self, action: Action, ctx: &mut Ctx<NoEffect>) {
        match action {
            Action::Inc => self.count += 1,
            Action::Load => {
                self.loading = true;
                ctx.emit(Effect::http("GET", "/api/count"));
            }
        }
        ctx.dirty("counter");
    }

    fn resolve(&mut self, _id: u64, result: Result<Value, String>, ctx: &mut Ctx<NoEffect>) {
        self.loading = false;
        if let Ok(reply) = result {
            self.count = reply["body"]["count"].as_i64().unwrap_or(self.count);
        }
        ctx.dirty("counter");
    }

    fn view(&self, key: &str) -> Option<Value> {
        (key == "counter").then(|| json!({"count": self.count}))
    }
    fn screen(&self) -> String { "counter".to_owned() }
    fn actions(&self) -> Vec<ActionSpec> { vec![ActionSpec::new("Inc"), ActionSpec::new("Load")] }
}
```

`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):

```text
{"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.