Skip to content

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
    lang/          the typed dialect: rules (verified vs CPython) · types · check · IR · lower
    emitter/       the owned back end: expression / statement / binder visitors (over lang/)
    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 ~700-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/           showcase apps under one umbrella (demos.app:app)
examples/declui/ 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/c_browser)
notes/           the design log — one numbered note per design round

Sizes, for orientation: the compiler is ~6,200 lines (its typed-dialect core, compiler/lang/, is ~2,000), declui ~4,500, the mount ~890 (a framework-neutral core plus the Litestar and Flask adapters), the shim ~700 lines of JS; the test suite is larger than 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-002 — "situ: A Verified-Dialect Compiler for Site-Declared Python Web UIs" — the current technical report (the typed-dialect edition): the programming model, the compiler and its correctness against CPython, the wire projection, zero-runtime composition, declui, the evaluation, and the enforcement-class method. In this repository at docs/papers/TR-002.md. It supersedes TR-001 (docs/papers/TR-001.md), a valid pre-typed-dialect snapshot that carries the detailed measurement tables.
  • The design log (notes/14–notes/36) — 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), the declui line (25–27) with per-slice build and adversarial-review records, the fail-closed audit (34), and the typed dialect (35) with the TR followup (36).
  • 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 the 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, the compile-time predicate cascade, and — since — the verified typed dialect. TR-002 cites all of it properly.