Architecture & research¶

The repository map¶

src/situ/
  siting/        the Signal / Signals / Site contract + the X-Siting-Signals header
  compiler/      the Python→JS compiler (pure stdlib)
    frontend/      parse the .py/.html pair · :each row scopes · region split · splice_tree
    emitter/       the owned back end: expression / statement / binder visitors
    markers.py     Local · Url · Server · Synced · Prop · Emit · Provide · Inject
    resolve.py     Context + static tree resolution (situ check)
    unified.py     the unified idiom desugarer (experimental)
  mount/         core.py the framework-neutral runtime (dispatch/render + command/region/feed/window) · runtime.py+factories.py the Litestar adapter · flask.py the Flask adapter
  static/        _rt.js — the 509-line client shim (no expression interpreter)
  declui/        the declarative generator: spec · generate · predicates · mount
  infra/         Jinja string rendering; [sqlalchemy]: engine + Dishka session provider
  check.py       python -m situ.check
src/situ_ui/     the component kit: ui.css (the class contract) · widgets.js · components/
demos/           17 showcase apps under one umbrella (demos.app:app)
examples/declui/ 13 generator examples under a second umbrella
examples/flask/  a declui server tracker served on plain Flask (situ.mount.flask)
tests/           unit (a_unit) · golden-bytes · real-browser e2e (tests/e2e)
notes/           the design log — one numbered note per design round

Sizes, for orientation: the compiler is ~3,200 lines, declui ~2,500, the mount ~770 (a framework-neutral core plus the Litestar and Flask adapters), the shim 509 lines of JS; the test suite is roughly the size of src/ itself.

How it holds together¶

flowchart LR
    subgraph authoring["Authoring"]
        PY["name.py"]
        HTML["name.html"]
    end
    subgraph compile["Compile time"]
        FE["FrontEnd"]
        SPL["splice_tree"]
        EA["EmittedApp"]
    end
    subgraph runtime["Runtime"]
        MOUNT["mount: neutral core + adapter (Litestar / Flask)<br/>page · island · /cmd · /feed"]
        BROWSER["_rt.js + generated island"]
    end
    PY --> FE
    HTML --> FE
    FE --> SPL --> EA --> MOUNT
    MOUNT <--> BROWSER

declui sits in front of this pipeline: it generates ordinary component source (situ's own language is its intermediate representation) and hands it to the unmodified compiler.

The research record¶

situ is the productized core of a documented research programme:

• TR-001 — "situ: Site-Declared State and a Compile-Time Client/Server Seam for Python Web UIs" — the technical report: goals, mechanisms, measured comparisons, prior-art positioning, and threats to validity. In this repository at docs/papers/TR-001.md.
• The design log (notes/14–notes/28) — one note per design round: the unified template idiom and the wire projection (14–16), the component kit (17–20), the composition redesign with its golden-bytes invariant (21–23), the backlog compass (24), and the declui line (25–27) with per-slice build and adversarial-review records.
• The upstream webui repository — the original demo programme: fifteen TodoMVC implementations over one backend (five controls, ten inventions), the four-way issue-tracker comparison, and the adversarial prior-art audit that grades this project's novelty claims.

Two numbers from that record worth carrying in your head: the same issue tracker costs 130 hand-written client lines as a vanilla SPA, 36 as htmx+Alpine, ~30 inline expressions as Datastar, and 0 with situ (a 76-line island is generated); and every generated island across all thirty shipped apps measures 5–12 KB unminified.

Lineage, in one paragraph¶

The placement idea (annotate where a value lives, derive the wire) descends from two decades of multi-tier programming research — Links, Hop, Eliom, ML5, ScalaLoci, Electric Clojure — recombined here at per-signal granularity in unmodified Python. The compile-away stance is Svelte's, taken further (no per-instance runtime at all). The region-swap transport is hypermedia's (htmx, Datastar). declui recycles AribaWeb/MetaUI's rule model with resolution moved to build time. The new constructs, per that audit: the template wire projection, the byte-identity composition invariant, and the compile-time predicate cascade. TR-001 cites all of it properly.