Status & roadmap¶

Alpha, deliberately bounded¶

situ is a young library extracted from a research programme. The compiler accepts a bounded dialect and fails closed; the API may still move. It is proven at TodoMVC-to-issue-tracker scale, browser-verified throughout — and not yet hardened for auth, real concurrency, or production operations.

What "done" means here¶

A feature counts only when:

1. a Playwright e2e passes in a real browser — the fixture fails on any console error, because a server-side TestClient happily passes pages whose client is broken;
2. make lint is clean across ruff (check + format), ty, pyrefly, mypy, and situ check over the component trees;
3. risky compiler changes additionally pass an adversarial review whose confirmed findings are fixed and regression-tested first.

Four standing invariants guard refactors: the differential oracle (every dialect expression, generated over operand-type pairs, evaluated in CPython and in node — situ must agree or refuse to compile; the recorded-disagreement baseline may only shrink, and is currently empty), the decomposition property (a component tree emits the same program as the equivalent monolith, over 200 generated trees), the golden-bytes test (the real demo trees' compiled output — rendered output and wire contract — does not drift), and the seam's CompileErrors. Each is mutation-tested: break what it guards, and it must go red.

The typed dialect¶

The client dialect is specified as a table of typing rules (compiler/lang/rules.py), each verified against CPython, and compiled through a clean parse → check → TypedIR → lower pipeline whose lowerer has no guards — an ill-typed program cannot reach it. This is what makes ==, <, in, arithmetic, len, truthiness, and the rest mean in the browser what they mean in Python. Two consequences for authors: a row the client reads declares its type (data-row="<Record>" + a TypedDict; declui derives it), and the dialect accepts more than the old untyped emitter (k in d, xs[-1], 'ab' * 3, n % m all work now). See the dialect.

Known limits¶

Each is documented where it applies; collected here:

Roadmap themes¶

From the design log (notes/24, notes/27, notes/28 in the repository):

• Framework adapters — the mount core is now framework-neutral, and a Flask (WSGI) adapter (situ.mount.flask) ships alongside the Litestar reference. Next: a Starlette adapter (async-native, no asyncio.run bridge) and moving litestar from a hard dependency to a [litestar] extra (the imports are already lazy, so the Flask path pulls in no Litestar).
• Synced, for real — a replica + reconciliation engine behind the reserved site.
• Typed templates — derive per-component context types from the parsed template (the wire projection and data-row already supply row schemas) and check context() against them.
• Finish the type inference — an unannotated handler parameter compared to a numeric signal is the one path still on the old emitter's coercion helpers (S.eqv/S.setHas, emitted zero times across the corpus but not yet deletable). Infer such a parameter's type from its typed call sites, then delete the helpers. Generate the dialect reference from rules.py so the docs cannot drift from the compiler.
• declui next slices — the create dialog, richer zone vocabularies (tabs) with the eject line kept explicit, a build-time facade-signature check for generated commands.
• Seam Certificate — emit the trust surface as diffable data (every signal's site, every provide/inject edge, every client↔server boundary).
• DX — watch/recompile on edit; editor support for the binder surface.

Versioning¶

Semantic versioning; user-visible changes land in CHANGES.md. The license is MIT.