# situ

> situ is a Python→JS compiler plus a framework-neutral component mount for reactive web UIs (a Litestar reference adapter and a Flask one; the Litestar imports are lazy, so the Flask path pulls in no 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`). Authors write real HTML plus a bounded dialect of Python and no client JavaScript.

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 measure 5–12 KB over a 509-line shared shim. 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; `python -m situ.check`
- [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
- [declui fields & models](declui/fields.md): Field options, the type→widget table, the five model adapters
- [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): 17 demos + 13 declui examples, 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): experimental — one interpolation + the wire projection
- [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-001 technical report