# situ

> situ is a Python→JS compiler plus a framework-neutral component mount for reactive web UIs (a Litestar reference adapter, a generic ASGI one that imports no web framework, and a Flask one; the Litestar imports are lazy, so neither other path pulls in Litestar). Each piece of state declares its site — `Local` (browser), `Url` (query string), `Server` (database), `Synced` (reserved) — and the transport is derived from that declaration: the client island is generated, the routes are derived, and the client/server boundary is a compile-time invariant (a client read of `Server` state is a `CompileError`). The client dialect is typed — specified as a table of rules verified against CPython — so what compiles means in the browser what it means in Python. Authors write real HTML plus a bounded dialect of Python and no client JavaScript. `pip install situ` is the compiler + the ASGI adapter and imports no web framework; the Litestar mount (`mount_component`) and the Flask mount are extras (`situ[litestar]`, `situ[flask]`).

Key facts for tools: components are two sibling files sharing a stem (`name.py` sited signals + handlers, `name.html` HTML + `:`/`@` binders); a handler containing `await` becomes a POST command, otherwise it compiles to client JS; the compiler fails closed on anything outside its dialect; generated islands are a few KB over a small shared shim. A row the client reads (`t.<field>` in a binder) must declare its type — `data-row="<Record>"` on the row element plus a matching `TypedDict` — so each DOM string is decoded to its real type. Symmetrically, typing `context()`'s return as a `TypedDict` (opt-in) makes situ verify the server template against it at mount: a missing context key, a missing row/object field, or a non-iterable loop is a `CompileError`. The complete single-file reference for coding agents is [llms-full.txt](llms-full.txt).

## Docs

- [Quickstart](getting-started/quickstart.md): a working counter in three files — the two-file component model and the mount
- [Server components](getting-started/server-components.md): the three-site walkthrough — facade Protocol, context(), the DI wiring (Dishka on the Litestar mount; a `resolve` callable on the Flask mount), the command round trip
- [Tutorial](tutorial/index.md): build a complete issue tracker in six parts (every listing compiles and is browser-verified)
- [Sites & the seam](concepts/sites-and-the-seam.md): what each site derives; the three seam CompileErrors
- [Handlers & commands](concepts/handlers-and-commands.md): the await rule, event actions, reset()/signal(), optimistic updates
- [The compiled dialect](concepts/the-dialect.md): accepted expressions/statements, the whitelisted calls, everything rejected
- [Composition](concepts/composition.md): Context resolution, props/emits, slots, provide/inject, per-placement state, scoped CSS
- [The wire protocol](concepts/wire-protocol.md): bootstrap, command request/response, X-Siting-Signals, SSE live, windowing
- [Binders & events reference](reference/binders.md): the complete `:`/`@` vocabulary with constraints
- [API & CLI](reference/api.md): every public signature, verbatim; the `situ new` / `situ check` CLI
- [Compile errors](reference/errors.md): the fail-closed catalogue with fixes
- [Cheat sheet](reference/cheat-sheet.md): the whole surface on one page
- [declui](declui/index.md): a typed model + a Screen generate a form / list / master-detail / server tracker / create+edit write form
- [declui fields & models](declui/fields.md): Field options, the type→widget table, the five model adapters
- [declui screens & mounting](declui/screens.md): the screen modes, write forms (create/edit), fail-closed mounting
- [declui rule cascade](declui/rules.md): Screen(rules=...) — selector→property rules over {field,type,operation}, resolved at mount; `python -m situ.declui explain`
- [declui predicates](declui/predicates.md): the whitelisted expression grammar and where each predicate compiles
- [Component kit](ui/index.md): situ_ui — the class contract, wiring, theming

## Optional

- [Demos & examples](getting-started/demos.md): the demo gallery + the declui example tour (forms, lists, trackers, create/edit, the rule cascade), all browser-verified, plus a Flask example (`examples/flask/`) serving a declui tracker on plain Flask
- [situ vs. …](getting-started/comparisons.md): React, Vue, Svelte, htmx, Datastar, LiveView, Eliom and the research lineage
- [The unified idiom](concepts/unified-idiom.md): opt-in — one interpolation, the wire projection, a site-derived `:if` / `:else`, composition
- [Status & roadmap](project/status.md): alpha scope and the known limits (Synced is reserved, etc.)
- [Architecture & research](project/architecture.md): repo map, the design-note log, the TR-002 technical report