situ 0.1.0__tar.gz

situ-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stéphane Fermigier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

situ-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: situ
+Version: 0.1.0
+Summary: Site your state, derive the wire — a Python→JS component compiler with an explicit client/server seam, for Litestar.
+Keywords: litestar,hypermedia,compiler,reactive,signals,web-ui,frontend,python-to-javascript
+Author: Stéphane Fermigier
+Author-email: Stéphane Fermigier <sfermigier@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Litestar
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Typing :: Typed
+Requires-Dist: litestar>=2.22
+Requires-Dist: jinja2>=3.1
+Requires-Dist: flask>=3.0 ; extra == 'flask'
+Requires-Dist: attrs>=23.0 ; extra == 'model-adapters'
+Requires-Dist: msgspec>=0.18 ; extra == 'model-adapters'
+Requires-Dist: pydantic>=2.0 ; extra == 'model-adapters'
+Requires-Dist: sqlalchemy>=2.0.50 ; extra == 'sqlalchemy'
+Requires-Dist: aiosqlite>=0.20.0 ; extra == 'sqlalchemy'
+Requires-Dist: dishka>=1.6 ; extra == 'sqlalchemy'
+Requires-Dist: greenlet>=3.0 ; extra == 'sqlalchemy'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://situ.hop3.abilian.com/
+Provides-Extra: flask
+Provides-Extra: model-adapters
+Provides-Extra: sqlalchemy
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/situ-wordmark.svg" alt="situ" width="220">
+</p>
+
+<p align="center"><em>Site your state, derive the wire.</em></p>
+
+---
+
+**situ** lets a Python developer write a reactive web UI as one component — real HTML on
+top, Python signals and handlers below — and declare, per piece of state, *where it lives*.
+A real Python→JS compiler reads that and emits a small, app-specific client island; the
+client/server boundary stays explicit and is enforced at compile time. You author no
+client JavaScript, and you can read every line the compiler ships.
+
+The compiler and the mount core are framework-neutral; situ ships a
+[Litestar](https://litestar.dev) adapter (the reference) and a Flask one, and a component
+mounts on either unchanged. It is for Python full-stack and backend developers who reach for
+hypermedia (htmx, Datastar) and hit the wall where a piece of state wants to live in the
+browser — a live search, a selection, an open dialog.
+
+> situ is a young, alpha library extracted from a research repo
+> ([webui](https://github.com/sfermigier/webui)); the compiler accepts a **bounded**
+> dialect of Python and fails *closed* on anything outside it. See *Status* below.
+
+## The one idea: site each piece of state
+
+Every signal declares its **site**, and the transport follows from that — you never write
+a fetch, a target, or an SSE wire.
+
+| Site | Where it lives | What the compiler derives |
+|------|----------------|---------------------------|
+| `Local[T]` | the browser | compiled to JS, zero network |
+| `Url[T]` | the query string | a shareable link the server re-renders |
+| `Server[Facade]` | the database | a POST command that morphs one region |
+| `Synced[T]` | a local-first replica | a store reconciled by a sync engine |
+
+The boundary is a **compile-time invariant**: a client read of `Server`-sited state is a
+`CompileError`, so database-backed state cannot reach the browser by accident.
+
+## Install
+
+```bash
+pip install situ                 # the compiler + the Litestar mount
+pip install "situ[flask]"        # + the Flask (WSGI) mount adapter
+pip install "situ[sqlalchemy]"   # + the optional SQLAlchemy/Dishka session helpers
+```
+
+Requires Python 3.12+.
+
+## Quickstart
+
+A component is **two sibling files sharing a stem**, so each gets native editor tooling.
+
+`counter.py` — the signals and handlers:
+
+```python
+from situ import Local
+
+count: Local[int] = 0  # client state — compiled to JS, no network
+
+
+def bump() -> None:
+    global count          # names the local signal this handler writes
+    count = count + 1
+```
+
+`counter.html` — real HTML with shorthand reactive attributes:
+
+```html
+<div data-region>
+  <button @click="bump">+1</button>
+  <strong :text="count"></strong>
+</div>
+```
+
+`app.py` — the controller is one mount call plus the wiring:
+
+```python
+from pathlib import Path
+
+import situ
+from litestar import Litestar
+from litestar.plugins.jinja import JinjaTemplateEngine
+from litestar.static_files import create_static_files_router
+from litestar.template.config import TemplateConfig
+from situ import mount_static_component
+
+HERE = Path(__file__).parent
+
+app = Litestar(
+    route_handlers=[
+        mount_static_component(
+            path="/counter",
+            stem=HERE / "counter",       # counter.py + counter.html
+            template="page.html",        # situ ships a minimal default
+            meta={"name": "Counter"},
+        ),
+        # serve the runtime shim the generated island loads from /static/_rt.js
+        create_static_files_router(path="/static", directories=[situ.static_dir()]),
+    ],
+    template_config=TemplateConfig(
+        directory=situ.templates_dir(), engine=JinjaTemplateEngine
+    ),
+)
+```
+
+```bash
+litestar --app app:app run    # then open http://localhost:8000/counter
+```
+
+Two rules the runtime enforces: every reactive element lives inside `<header>` or the
+single `<div data-region>` (where binders are wired at boot), and `data-region` must be
+the first attribute on that `<div>`.
+
+When a piece of state needs the database, declare it `Server[Facade]`, give the component a
+`context` function and a facade, and switch to `mount_component` — the same component file,
+now with a server seam. `mount_tree` composes a root component with typed children. To serve
+the same compiled component on Flask instead, `situ.mount.flask.mount_flask` mounts it as a
+`Blueprint` — see `examples/flask/`.
+
+## What's in the box
+
+- `situ.compiler` — the Python→JS compiler (`parse_front_end`, `load_front_end`,
+  `compile_app`, `splice_tree`) and the site markers. Pure standard library.
+- `situ.mount` — a framework-neutral mount core (`situ.mount.core`: dispatch + render + the
+  command/region/feed/window protocol, no framework imported) with thin adapters over it: the
+  Litestar route factories (`mount_component`, `mount_static_component`, `mount_tree`) and a
+  Flask `Blueprint` adapter (`situ.mount.flask.mount_flask`). The Litestar bindings load
+  lazily, so the Flask path imports no Litestar.
+- `situ.siting` — the `Signal` / `Signals` / `Site` contract.
+- `situ.infra.templating` — a Jinja string-render helper (`render_string`); and, behind
+  `[sqlalchemy]`, `situ.infra.db` / `situ.infra.di` — a SQLAlchemy async engine + Dishka
+  session provider.
+- `situ.static_dir()` / `situ.templates_dir()` — paths to the bundled `_rt.js` shim and
+  the default `page.html`, to wire into your Litestar static + template config.
+
+## Status
+
+Alpha. The compiler accepts a bounded dialect of Python and rejects the rest with a clear
+error; it does not relocate database I/O to the client. Dishka is required only by the
+Litestar `mount_component`, which reads `request.state.dishka_container` (the `[sqlalchemy]`
+extra ships a ready provider, or wire your own); the Flask adapter takes a plain `resolve`
+callable and needs no Dishka. The story behind the design — fifteen TodoMVC
+implementations and a four-way master-detail comparison — lives in the
+[webui research repo](https://github.com/sfermigier/webui).
+
+## License
+
+[MIT](LICENSE) © Stéphane Fermigier

situ-0.1.0/README.md

@@ -0,0 +1,149 @@
+<p align="center">
+  <img src="assets/situ-wordmark.svg" alt="situ" width="220">
+</p>
+
+<p align="center"><em>Site your state, derive the wire.</em></p>
+
+---
+
+**situ** lets a Python developer write a reactive web UI as one component — real HTML on
+top, Python signals and handlers below — and declare, per piece of state, *where it lives*.
+A real Python→JS compiler reads that and emits a small, app-specific client island; the
+client/server boundary stays explicit and is enforced at compile time. You author no
+client JavaScript, and you can read every line the compiler ships.
+
+The compiler and the mount core are framework-neutral; situ ships a
+[Litestar](https://litestar.dev) adapter (the reference) and a Flask one, and a component
+mounts on either unchanged. It is for Python full-stack and backend developers who reach for
+hypermedia (htmx, Datastar) and hit the wall where a piece of state wants to live in the
+browser — a live search, a selection, an open dialog.
+
+> situ is a young, alpha library extracted from a research repo
+> ([webui](https://github.com/sfermigier/webui)); the compiler accepts a **bounded**
+> dialect of Python and fails *closed* on anything outside it. See *Status* below.
+
+## The one idea: site each piece of state
+
+Every signal declares its **site**, and the transport follows from that — you never write
+a fetch, a target, or an SSE wire.
+
+| Site | Where it lives | What the compiler derives |
+|------|----------------|---------------------------|
+| `Local[T]` | the browser | compiled to JS, zero network |
+| `Url[T]` | the query string | a shareable link the server re-renders |
+| `Server[Facade]` | the database | a POST command that morphs one region |
+| `Synced[T]` | a local-first replica | a store reconciled by a sync engine |
+
+The boundary is a **compile-time invariant**: a client read of `Server`-sited state is a
+`CompileError`, so database-backed state cannot reach the browser by accident.
+
+## Install
+
+```bash
+pip install situ                 # the compiler + the Litestar mount
+pip install "situ[flask]"        # + the Flask (WSGI) mount adapter
+pip install "situ[sqlalchemy]"   # + the optional SQLAlchemy/Dishka session helpers
+```
+
+Requires Python 3.12+.
+
+## Quickstart
+
+A component is **two sibling files sharing a stem**, so each gets native editor tooling.
+
+`counter.py` — the signals and handlers:
+
+```python
+from situ import Local
+
+count: Local[int] = 0  # client state — compiled to JS, no network
+
+
+def bump() -> None:
+    global count          # names the local signal this handler writes
+    count = count + 1
+```
+
+`counter.html` — real HTML with shorthand reactive attributes:
+
+```html
+<div data-region>
+  <button @click="bump">+1</button>
+  <strong :text="count"></strong>
+</div>
+```
+
+`app.py` — the controller is one mount call plus the wiring:
+
+```python
+from pathlib import Path
+
+import situ
+from litestar import Litestar
+from litestar.plugins.jinja import JinjaTemplateEngine
+from litestar.static_files import create_static_files_router
+from litestar.template.config import TemplateConfig
+from situ import mount_static_component
+
+HERE = Path(__file__).parent
+
+app = Litestar(
+    route_handlers=[
+        mount_static_component(
+            path="/counter",
+            stem=HERE / "counter",       # counter.py + counter.html
+            template="page.html",        # situ ships a minimal default
+            meta={"name": "Counter"},
+        ),
+        # serve the runtime shim the generated island loads from /static/_rt.js
+        create_static_files_router(path="/static", directories=[situ.static_dir()]),
+    ],
+    template_config=TemplateConfig(
+        directory=situ.templates_dir(), engine=JinjaTemplateEngine
+    ),
+)
+```
+
+```bash
+litestar --app app:app run    # then open http://localhost:8000/counter
+```
+
+Two rules the runtime enforces: every reactive element lives inside `<header>` or the
+single `<div data-region>` (where binders are wired at boot), and `data-region` must be
+the first attribute on that `<div>`.
+
+When a piece of state needs the database, declare it `Server[Facade]`, give the component a
+`context` function and a facade, and switch to `mount_component` — the same component file,
+now with a server seam. `mount_tree` composes a root component with typed children. To serve
+the same compiled component on Flask instead, `situ.mount.flask.mount_flask` mounts it as a
+`Blueprint` — see `examples/flask/`.
+
+## What's in the box
+
+- `situ.compiler` — the Python→JS compiler (`parse_front_end`, `load_front_end`,
+  `compile_app`, `splice_tree`) and the site markers. Pure standard library.
+- `situ.mount` — a framework-neutral mount core (`situ.mount.core`: dispatch + render + the
+  command/region/feed/window protocol, no framework imported) with thin adapters over it: the
+  Litestar route factories (`mount_component`, `mount_static_component`, `mount_tree`) and a
+  Flask `Blueprint` adapter (`situ.mount.flask.mount_flask`). The Litestar bindings load
+  lazily, so the Flask path imports no Litestar.
+- `situ.siting` — the `Signal` / `Signals` / `Site` contract.
+- `situ.infra.templating` — a Jinja string-render helper (`render_string`); and, behind
+  `[sqlalchemy]`, `situ.infra.db` / `situ.infra.di` — a SQLAlchemy async engine + Dishka
+  session provider.
+- `situ.static_dir()` / `situ.templates_dir()` — paths to the bundled `_rt.js` shim and
+  the default `page.html`, to wire into your Litestar static + template config.
+
+## Status
+
+Alpha. The compiler accepts a bounded dialect of Python and rejects the rest with a clear
+error; it does not relocate database I/O to the client. Dishka is required only by the
+Litestar `mount_component`, which reads `request.state.dishka_container` (the `[sqlalchemy]`
+extra ships a ready provider, or wire your own); the Flask adapter takes a plain `resolve`
+callable and needs no Dishka. The story behind the design — fifteen TodoMVC
+implementations and a four-way master-detail comparison — lives in the
+[webui research repo](https://github.com/sfermigier/webui).
+
+## License
+
+[MIT](LICENSE) © Stéphane Fermigier

situ-0.1.0/pyproject.toml

@@ -0,0 +1,118 @@
+[project]
+name = "situ"
+version = "0.1.0"
+description = "Site your state, derive the wire — a Python→JS component compiler with an explicit client/server seam, for Litestar."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Stéphane Fermigier", email = "sfermigier@gmail.com" }]
+keywords = [
+    "litestar",
+    "hypermedia",
+    "compiler",
+    "reactive",
+    "signals",
+    "web-ui",
+    "frontend",
+    "python-to-javascript",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Litestar",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Topic :: Software Development :: Code Generators",
+    "Typing :: Typed",
+]
+# The siting runtime + the compiler are pure stdlib; litestar + jinja2 are needed only
+# for the `mount` route factories + the string-render helper, which are the common path.
+dependencies = [
+    "litestar>=2.22",
+    "jinja2>=3.1",
+]
+
+[project.optional-dependencies]
+# The bundled SQLAlchemy async engine + Dishka session provider (situ.infra.db / .di).
+# Optional: mount_component reads `request.state.dishka_container` as a runtime contract,
+# but you can wire your own DI/DB instead of these helpers.
+sqlalchemy = [
+    "sqlalchemy>=2.0.50",
+    "aiosqlite>=0.20.0",
+    "dishka>=1.6",
+    "greenlet>=3.0",  # required by SQLAlchemy's async engine
+]
+# declui's model-source adapters (`situ.declui.read_model`): generate a form from an attrs / msgspec /
+# Pydantic model, not only a @dataclass. Each is imported lazily, only when such a model is used.
+model-adapters = [
+    "attrs>=23.0",
+    "msgspec>=0.18",
+    "pydantic>=2.0",
+]
+# Serve a compiled situ component from a Flask (WSGI) app via `situ.mount.flask.mount_flask` — the
+# proof that the mount is framework-neutral (no Litestar / Dishka on the path). See examples/flask/.
+flask = [
+    "flask>=3.0",
+]
+
+[project.urls]
+Homepage = "https://situ.hop3.abilian.com/"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "httpx>=0.27",        # litestar TestClient transport
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "pytest-cov>=7.1.0",
+    "ty>=0.0.51",
+    "pyrefly>=1.1.1",
+    "nox>=2026.4.10",
+    "pre-commit>=4.6.0",
+    # mirror the [sqlalchemy] extra so the server-backed demo + tests run on `uv sync`
+    "dishka>=1.6",
+    "sqlalchemy>=2.0.50",
+    "aiosqlite>=0.20.0",
+    "greenlet>=3.0",
+    "litestar[standard]>=2.24.0",
+    "playwright>=1.60.0",
+    # the declui model-adapter sources, so their byte-identical tests run on `uv sync`
+    "attrs>=23.0",
+    "msgspec>=0.18",
+    "pydantic>=2.0",
+    "zensical>=0.0.46",
+    # the Flask adapter's demo + acceptance test (situ.mount.flask) run on `uv sync`
+    "flask>=3.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.8.4,<0.9.0"]
+build-backend = "uv_build"
+
+# [tool.hatch.build.targets.wheel]
+# packages = ["src/situ", "src/situ_ui"]
+
+# [tool.hatch.build.targets.sdist]
+# include = ["src/situ", "src/situ_ui", "tests", "demos", "README.md", "LICENSE", "assets"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]  # so tests can import the example apps under demos/
+
+# ruff is configured in ruff.toml (a standalone file makes ruff ignore [tool.ruff] here).
+
+[tool.mypy]
+python_version = "3.12"
+mypy_path = "src"
+exclude = ["/static/"]
+warn_unused_ignores = true
+
+[[tool.mypy.overrides]]
+# The SQLAlchemy/Dishka helpers (situ.infra.db / .di) live behind the optional
+# `[sqlalchemy]` extra, so these imports may be absent in a base install.
+module = ["dishka.*", "sqlalchemy.*"]
+ignore_missing_imports = true

situ-0.1.0/src/situ/__init__.py

@@ -0,0 +1,99 @@
+"""situ — site your state, derive the wire.
+
+Declare where each piece of UI state lives (``Local`` / ``Url`` / ``Server`` / ``Synced``);
+a real Python→JS compiler emits a small, app-specific client island and enforces the
+client/server seam at compile time (a client read of ``Server``-sited state is a
+``CompileError``). Mount a compiled component as a Litestar router with ``mount_component``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from .compiler.emitter import EmittedApp, compile_app
+from .compiler.frontend import (
+    CompileError,
+    FrontEnd,
+    load_front_end,
+    parse_front_end,
+    splice_tree,
+)
+from .compiler.markers import (
+    Emit,
+    Inject,
+    Local,
+    Prop,
+    Provide,
+    Server,
+    Synced,
+    Url,
+)
+from .compiler.resolve import Context
+from .mount import parse_id_set
+from .siting.runtime import Signal, Signals, Site
+
+if TYPE_CHECKING:  # the checkers see real types; at runtime these load on first access
+    from .mount import mount_component, mount_static_component, mount_tree
+
+__version__ = "0.1.0"
+
+# the Litestar-backed mount factories load lazily, so `import situ` (or serving via the Flask
+# adapter) pulls in no Litestar until you reach for one of them — situ's compiler + siting core is
+# framework-neutral. See situ.mount.flask for the Flask adapter that proves it.
+_LAZY_MOUNT = frozenset({"mount_component", "mount_static_component", "mount_tree"})
+
+
+def __getattr__(name: str) -> Any:
+    if name in _LAZY_MOUNT:
+        from . import mount  # noqa: PLC0415
+
+        return getattr(mount, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def static_dir() -> Path:
+    """Filesystem path to situ's bundled browser assets (the ``_rt.js`` runtime shim).
+
+    Serve this directory at ``/static`` (e.g. a Litestar static-files router pointed
+    here) so a generated island can load the shim from ``/static/_rt.js``.
+    """
+    return Path(__file__).resolve().parent / "static"
+
+
+def templates_dir() -> Path:
+    """Filesystem path to situ's bundled Jinja templates (a default ``page.html``).
+
+    Add it to your Litestar ``TemplateConfig`` search path to render with the default page.
+    """
+    return Path(__file__).resolve().parent / "templates"
+
+
+__all__ = [
+    "CompileError",
+    "Context",
+    "Emit",
+    "EmittedApp",
+    "FrontEnd",
+    "Inject",
+    "Local",
+    "Prop",
+    "Provide",
+    "Server",
+    "Signal",
+    "Signals",
+    "Site",
+    "Synced",
+    "Url",
+    "__version__",
+    "compile_app",
+    "load_front_end",
+    "mount_component",
+    "mount_static_component",
+    "mount_tree",
+    "parse_front_end",
+    "parse_id_set",
+    "splice_tree",
+    "static_dir",
+    "templates_dir",
+]

situ-0.1.0/src/situ/check.py

@@ -0,0 +1,63 @@
+"""``situ check`` — a static pass: every PascalCase ``<Tag/>`` a component tree reaches must
+resolve, checked by reading templates without booting the server.
+
+Run it in ``make lint`` / pre-commit (and an editor/LSP later) so an unresolved component is caught
+in the fast feedback loop, before the app even boots. Resolve ``ROOT`` against the union of one or more
+``--from-dir`` contexts, optionally including the ``situ_ui`` kit with ``--kit``::
+
+    python -m situ.check demos/issues/components/issues --from-dir demos/issues/components
+    python -m situ.check demos/ui_gallery/components/gallery --kit
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from situ.compiler.resolve import Context, check_tree
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="situ.check", description=__doc__)
+    p.add_argument(
+        "root", type=Path, help="the root component (a .html file or its stem)"
+    )
+    p.add_argument(
+        "--from-dir",
+        action="append",
+        default=[],
+        type=Path,
+        dest="dirs",
+        metavar="DIR",
+        help="a component directory to resolve tags from (repeatable)",
+    )
+    p.add_argument(
+        "--kit", action="store_true", help="also resolve against the situ_ui kit"
+    )
+    args = p.parse_args(argv)
+
+    ctx = Context.of({})
+    for d in args.dirs:
+        ctx = ctx.merge(Context.from_dir(d))
+    if args.kit:
+        import situ_ui  # noqa: PLC0415 — lazy so situ.check has no hard dependency on the kit
+
+        ctx = ctx.merge(situ_ui.kit())
+
+    stem = args.root.with_suffix("") if args.root.suffix else args.root
+    errors = check_tree(stem, ctx)
+    for e in errors:
+        print(f"situ check: {e}", file=sys.stderr)
+    if errors:
+        print(
+            f"situ check: {len(errors)} unresolved component(s) under {stem.name}",
+            file=sys.stderr,
+        )
+        return 1
+    print(f"situ check: {stem.name} — all components resolve")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

situ-0.1.0/src/situ/compiler/__init__.py

@@ -0,0 +1,2 @@
+"""The single-file-component compiler toolchain: the ``frontend`` package (parse + ``scopes`` +
+``compose``), the owned ``emitter`` package (the Python→JS back-end), and the site ``markers``."""

situ-0.1.0/src/situ/compiler/emitter/__init__.py

@@ -0,0 +1,21 @@
+"""The owned Python→JS compiler back-end: the shared compile context (``ctx``), the
+expression compiler (``expr``), the statement/action compilers (``stmt``), the binder
+emitters + island assembly (``binders``), and the orchestrator (``core``) that drives
+them into an ``EmittedApp``. The front-end that feeds it is ``..frontend``.
+
+This package ``__init__`` is the back-end's public facade — import the names below from
+``situ.compiler.emitter`` (the submodules import from each other, never from here)."""
+
+from __future__ import annotations
+
+from .core import EmittedApp, compile_app
+from .ctx import EmitCtx
+from .stmt import EVENT_CALL_BUILTINS, _compile_call_stmt
+
+__all__ = [
+    "EVENT_CALL_BUILTINS",
+    "EmitCtx",
+    "EmittedApp",
+    "_compile_call_stmt",
+    "compile_app",
+]