streamtree 0.2.0__tar.gz → 0.4.0__tar.gz

streamtree-0.4.0/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.0] — 2026-05-12
+
+### Added
+
+- **CLI (optional `[cli]`):** **`streamtree run`** delegates to **`python -m streamlit run`** with forwarded argv; **`streamtree doctor`** prints versions and Typer availability. **`[project.scripts]`** entry **`streamtree`**.
+- **`streamtree.helpers.runner`:** **`build_streamlit_run_argv`**, **`run_streamlit_sync`** (stdlib subprocess; **`FileNotFoundError`** → exit code **127**; empty args → **2**).
+- **`PageLink`** element mapping to **`st.page_link`** (Streamlit **≥ 1.30** in core dependencies).
+- **`App`:** **`initial_sidebar_state`** and **`menu_items`** passed through to **`st.set_page_config`** when set.
+- **`streamtree.forms`:** **`numeric_field_names`**, **`bind_numeric_fields`**, **`number_inputs`** for **`int`** / **`float`** and optional numeric fields.
+- Example **`examples/numeric_nav_demo.py`** and **`examples/streamtree_run_demo.md`** (CLI usage).
+
+### Changed
+
+- **Minimum Streamlit** raised to **`>=1.30.0`** (for **`st.page_link`**).
+- **`[cli]`** extra now lists **Typer**; stub extras **`[pages]`** and **`[runner]`** documented (runner helper ships in the default install; **`[runner]`** remains metadata-only).
+
+### Documentation
+
+- README: **`streamtree[cli]`**, **`streamtree run`**, Streamlit **1.30+** requirement, **`v0.4.0`** release tag example.
+- [DEPENDENCY_STRATEGY.md](docs/DEPENDENCY_STRATEGY.md): CLI / **`[pages]`** / **`[runner]`** notes.
+- [ROADMAP.md](docs/ROADMAP.md): **0.4.0** release index; Phase 2 “Next” adjusted.
+
+### Fixed
+
+- **CI:** **`cli-smoke`** sets job-level **`UV_PYTHON`** so **`uv run streamtree doctor`** reuses the **`[cli]`** sync environment (otherwise **`uv run`** could follow **`.python-version`** and miss Typer).
+
+## [0.3.0] — 2026-05-12
+
+### Added
+
+- **Packaging:** optional extra **`[async]`** as a TOML-quoted alias of the empty **`[asyncio]`** stub extra (matches install examples in the plan and dependency strategy).
+- **`streamtree.app.App`** shell with optional sidebar composition, **`apply_page_config`**, **`app_root_element`**, and **`render_app()`** (one-time `st.set_page_config` guard).
+- **`streamtree.theme`**: **`Theme`** (Pydantic), **`theme()`** / **`theme_css()`**, and **`ThemeRoot`** element for CSS injection via `app_context.provider(theme=...)`.
+- **`streamtree.asyncio`**: **`submit()`** / **`TaskHandle`** for daemon-thread background work with session-scoped poll keys (stdlib-only; optional `[asyncio]` / `[async]` stub extras unchanged as meta).
+- **`streamtree.forms`**: **`bind_str_fields`** and **`str_text_inputs`** for declarative `TextInput` grids from Pydantic string fields.
+- Examples **`examples/app_shell.py`**, **`examples/async_bg.py`**, **`examples/model_form.py`**.
+
+### Changed
+
+- **Routing:** `sync_route` / `set_route` now store the active route in `st.session_state` under `streamtree.routing.active.<param>` (one slot per query-param name) instead of a single global `streamtree.routing.active` key. Apps that read that private key must migrate.
+- **`ErrorBoundary.on_error`** is typed as ``Callable[[Exception], None]``, matching the renderer (only `Exception` subclasses are passed through).
+- **`Routes`:** duplicate route names are rejected at construction.
+- **`@component`:** returning ``None`` or a non-``Element`` value raises a clear ``TypeError`` (including in ``render_to_tree(..., expand_components=True)``).
+- **`streamtree.asyncio`:** task status dict updates are serialized with a lock; module and ``submit`` docstrings document rerun-polling semantics.
+- **`Theme`:** ``primary_color`` is restricted to ``#RGB`` / ``#RRGGBB`` hex; ``font_stack`` rejects ``<``, ``>``, and backticks; ``custom_css`` rejects ``<script`` and ``expression(`` substrings (full ``custom_css`` remains trusted CSS).
+- **`HStack`:** non-empty ``gap`` inserts gutter columns between children (CSS ``min-width`` on a spacer).
+
+### Documentation
+
+- README refresh (badges, absolute GitHub links for design docs and workflows); install examples pin **0.3.0**.
+- Design docs live at `docs/PLAN.md`, `docs/ROADMAP.md`, and `docs/DEPENDENCY_STRATEGY.md` with updated cross-links.
+- **StreamTree** is used as the product name in metadata and user-facing defaults (the PyPI / import name remains **`streamtree`**).
+
+## [0.2.0] — 2026-05-12
+
+### Added
+
+- **Pydantic** and **typing-extensions** as core dependencies; stub optional extras (`tables`, `charts`, `ui`, `auth`, `asyncio`, `cli`, `all`) per dependency strategy.
+- **`streamtree.app_context`**: `provider()` / `lookup()` / `current_bag()` for rerun-scoped DI-style values.
+- **`streamtree.routing`**: `sync_route` / `set_route` for query-param + session alignment.
+- **`Routes`** layout element (with Streamlit renderer) for one-of-many pages keyed by the active route.
+- **`ErrorBoundary`** element with Streamlit renderer fallback and optional `on_error` callback.
+- **`streamtree.forms`**: `str_field_names`, `model_validate_json`, `format_validation_errors` for Pydantic-first forms.
+- Example **`examples/routed_app.py`**: multi-page navigation + JSON profile validation.
+
+### Changed
+
+- Stricter validation for routing params and route names, app-context keys, `Routes` defaults/query keys, and `Annotated[...]` handling in `str_field_names`; `current_bag()` returns a shallow copy.
+- Pytest coverage targets `src/streamtree` by path to avoid import-order coverage warnings.
+
+## [0.1.0] — 2026-05-11
+
+### Added
+
+- Initial public API: `@component`, `render`, virtual elements (`Page`, layouts, widgets).
+- Session helpers: `state`, `toggle_state`, `form_state`, `session_state`, `memo`, `cache`.
+- Streamlit renderer mapping the virtual tree to `st.*` calls (including `Form` and submit flows).
+- `streamtree.testing.render_to_tree` for structure-focused tests without a live Streamlit session.
+- Runnable example: `examples/counter.py`.
+- Design docs under `docs/` (plan, roadmap, dependency strategy).
+
+[0.4.0]: https://github.com/streamtree-dev/streamtree/releases/tag/v0.4.0
+[0.3.0]: https://github.com/streamtree-dev/streamtree/releases/tag/v0.3.0
+[0.2.0]: https://github.com/streamtree-dev/streamtree/releases/tag/v0.2.0
+[0.1.0]: https://github.com/streamtree-dev/streamtree/releases/tag/v0.1.0

{streamtree-0.2.0 → streamtree-0.4.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Streamtree contributors
+Copyright (c) 2026 StreamTree contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

streamtree-0.4.0/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: streamtree
+Version: 0.4.0
+Summary: StreamTree: declarative, typed composition for Streamlit.
+Author: StreamTree contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/streamtree-dev/streamtree
+Project-URL: Documentation, https://github.com/streamtree-dev/streamtree#readme
+Project-URL: Repository, https://github.com/streamtree-dev/streamtree
+Project-URL: Issues, https://github.com/streamtree-dev/streamtree/issues
+Project-URL: Changelog, https://github.com/streamtree-dev/streamtree/blob/main/CHANGELOG.md
+Keywords: streamlit,ui,components,declarative
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.4.0
+Requires-Dist: streamlit>=1.30.0
+Requires-Dist: typing-extensions>=4.8.0
+Provides-Extra: tables
+Provides-Extra: charts
+Provides-Extra: ui
+Provides-Extra: auth
+Provides-Extra: asyncio
+Provides-Extra: async
+Provides-Extra: cli
+Requires-Dist: typer>=0.12.3; extra == "cli"
+Provides-Extra: pages
+Provides-Extra: runner
+Provides-Extra: all
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.5.0; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+Requires-Dist: ruff>=0.2.0; extra == "dev"
+Requires-Dist: ty>=0.0.30; extra == "dev"
+Requires-Dist: typer>=0.12.3; extra == "dev"
+Dynamic: license-file
+
+# StreamTree
+
+[![PyPI version](https://img.shields.io/pypi/v/streamtree)](https://pypi.org/project/streamtree/)
+[![Python versions](https://img.shields.io/pypi/pyversions/streamtree)](https://pypi.org/project/streamtree/)
+[![License](https://img.shields.io/pypi/l/streamtree)](https://github.com/streamtree-dev/streamtree/blob/main/LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/streamtree-dev/streamtree/ci.yml?branch=main&label=CI)](https://github.com/streamtree-dev/streamtree/actions/workflows/ci.yml?query=branch%3Amain)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://docs.astral.sh/ruff/)
+
+Declarative, typed composition for [Streamlit](https://streamlit.io/). StreamTree adds components, layout primitives, scoped session state, and test-friendly tree rendering while keeping Streamlit’s execution model and widgets. No JavaScript or separate frontend build is required.
+
+## Overview
+
+| Traditional scripts | With StreamTree |
+|---------------------|-----------------|
+| Layout and widgets mixed in one long file | `@component` functions return an **element tree** |
+| Many ad hoc `st.session_state` keys | `state()` and helpers scoped to the render path |
+| Structure is hard to inspect or snapshot | `streamtree.testing.render_to_tree()` for tests and docs |
+
+StreamTree is an **architecture layer** for Streamlit, not a React-style web framework.
+
+## Capabilities
+
+- **Components and elements** — `@component`, `render` / `render_app`, layouts (`Page`, `Card`, `Grid`, `VStack`, `Form`, `Tabs`, `Sidebar`, `Routes`, `ErrorBoundary`, and more), and widget wrappers.
+- **App shell (0.3+)** — `App` with a guarded `st.set_page_config`, plus optional sidebar and main composition via `render_app`.
+- **Theming (0.3+)** — `Theme`, `ThemeRoot`, `theme()`, `theme_css()`, and `app_context.provider(theme=...)`.
+- **Background work (0.3+)** — `streamtree.asyncio.submit` and `TaskHandle` for stdlib-thread jobs you poll across reruns.
+- **Forms (0.3+)** — Pydantic-oriented helpers: `bind_str_fields` / `str_text_inputs`, plus **`bind_numeric_fields` / `number_inputs`** (0.4+) for `int` / `float` fields (optional `int | None` / `float | None` use model defaults or `None` for an empty number input).
+- **CLI (0.4+)** — Optional **`streamtree[cli]`**: `streamtree run` delegates to Streamlit; `streamtree doctor` prints versions (see [examples/streamtree_run_demo.md](examples/streamtree_run_demo.md)).
+- **State** — `state`, `toggle_state`, `form_state`, `memo`, `cache`.
+- **Routing and context** — Query-param routing (`streamtree.routing`), `ErrorBoundary`, `streamtree.forms` utilities, and `app_context.provider` / `lookup` for shared values.
+- **Interop** — Inside `@component`, your function body runs during render; you may call `st.*` (columns, metrics, charts, third-party components) and still return an element tree, or `fragment()` when the subtree is fully imperative.
+- **Quality** — Pydantic v2 in the default install, typing-first APIs, and `render_to_tree` for structural tests.
+
+Optional extras (`tables`, `charts`, `ui`, `auth`, `asyncio`, `async`, `pages`, `runner`) are mostly stubs for future wrappers; **`[cli]`** adds **Typer** and the **`streamtree`** console script (`run`, `doctor`). See [Dependency strategy](https://github.com/streamtree-dev/streamtree/blob/main/docs/DEPENDENCY_STRATEGY.md). The `streamtree.asyncio` module and **`streamtree.helpers.runner`** ship in the default package.
+
+## Requirements
+
+Python **3.10+**, with **Streamlit ≥ 1.30** (for `st.page_link` used by `PageLink`), **Pydantic v2**, and **typing-extensions** (see `pyproject.toml`).
+
+## Installation
+
+```bash
+pip install streamtree==0.4.0
+pip install "streamtree[cli]"   # Typer + ``streamtree run`` / ``streamtree doctor``
+```
+
+From a clone, with dev dependencies:
+
+```bash
+git clone https://github.com/streamtree-dev/streamtree.git
+cd streamtree
+uv sync --extra dev
+# or: pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+from streamtree import component, render
+from streamtree.elements import Button, Card, Page, Text
+from streamtree.state import state
+
+
+@component
+def Counter():
+    count = state(0)
+    return Card(
+        Text(f"Count: {count()}"),
+        Button("Increment", on_click=lambda: count.increment(1)),
+        Button("Reset", on_click=lambda: count.set(0)),
+    )
+
+
+if __name__ == "__main__":
+    render(Page(Counter()))
+```
+
+Run examples from the repository root:
+
+```bash
+streamlit run examples/counter.py
+streamlit run examples/routed_app.py
+streamlit run examples/app_shell.py
+streamlit run examples/async_bg.py
+streamlit run examples/model_form.py
+streamlit run examples/numeric_nav_demo.py
+# With Typer installed (``pip install "streamtree[cli]"``):
+streamtree run examples/counter.py
+```
+
+## Using Streamlit inside components
+
+The `@component` body runs on every rerun in the same process as `streamlit`. You can call `st.columns`, `st.metric`, plotting APIs, or `components.v1` before returning elements. Use **stable `key=`** arguments on imperative widgets when Streamlit requires them. When a subtree is drawn entirely with `st.*`, return `fragment()`.
+
+```python
+import streamlit as st
+
+from streamtree import component, fragment, render
+from streamtree.elements import Button, Markdown, Page, TextInput, VStack
+from streamtree.state import state
+
+
+@component
+def DashboardHeader():
+    band, meta = st.columns([3, 1])
+    with band:
+        st.title("Operations")
+    with meta:
+        st.metric("Queue depth", 12, delta=-2)
+
+    notes = state("", key="header_notes")
+    return VStack(
+        Markdown("**Notes** (StreamTree `TextInput`):"),
+        TextInput("Session notes", value=notes),
+        Button("Clear notes", on_click=lambda: notes.set("")),
+    )
+
+
+@component
+def MetricsStrip():
+    cols = st.columns(4)
+    for i, col in enumerate(cols):
+        with col:
+            st.metric(f"M{i + 1}", 100 + i * 7, delta=i - 1)
+    return fragment()
+
+
+if __name__ == "__main__":
+    render(Page(DashboardHeader(), MetricsStrip()))
+```
+
+## App shell, theme, and background tasks
+
+`App` plus `render_app()` centralize page configuration. Combine `ThemeRoot` with `provider(theme=Theme(...))` for CSS variables, and use `streamtree.asyncio.submit` for non-blocking work you observe via `TaskHandle.status` on reruns.
+
+```python
+from streamtree import asyncio, component, render_app
+from streamtree.app import App
+from streamtree.app_context import provider
+from streamtree.elements import Page, Text, ThemeRoot, VStack
+from streamtree.theme import Theme
+
+
+@component
+def Body():
+    handle = asyncio.submit(lambda: 7, key="demo_job")
+    return VStack(
+        ThemeRoot(),
+        Text(f"status={handle.status()} result={handle.result()}"),
+    )
+
+
+if __name__ == "__main__":
+    with provider(theme=Theme(primary_color="#0068c9")):
+        render_app(App(page_title="Demo", body=Body()))
+```
+
+## Patterns
+
+**Grid of components**
+
+```python
+from streamtree.elements import Grid
+
+Grid(UserCard(user1), UserCard(user2), columns=2)
+```
+
+**Bound text input**
+
+```python
+from streamtree.elements import TextInput
+from streamtree.state import state
+
+search = state("")
+TextInput(label="Search", value=search)
+```
+
+## Documentation
+
+| Resource | Description |
+|----------|-------------|
+| [Plan](https://github.com/streamtree-dev/streamtree/blob/main/docs/PLAN.md) | Vision, architecture, risks |
+| [Roadmap](https://github.com/streamtree-dev/streamtree/blob/main/docs/ROADMAP.md) | Phased delivery |
+| [Dependency strategy](https://github.com/streamtree-dev/streamtree/blob/main/docs/DEPENDENCY_STRATEGY.md) | Dependencies and optional extras |
+| [CHANGELOG](https://github.com/streamtree-dev/streamtree/blob/main/CHANGELOG.md) | Release history |
+
+## Contributing
+
+Install dev tools, then run lint, type check, and tests (mirrors CI on Python 3.10–3.12):
+
+```bash
+uv sync --extra dev
+uv run ruff format .
+uv run ruff check src tests
+uv run ty check src
+uv run pytest
+```
+
+Equivalent with **pip**: `pip install -e ".[dev]"`, then `ruff`, `ty check src`, and `pytest` as above.
+
+## Releases
+
+**Automated:** Add a **`PYPI_API_TOKEN`** secret to the repository. When `main` is green, push a tag of the form **`v0.4.0`**. The [release workflow](https://github.com/streamtree-dev/streamtree/blob/main/.github/workflows/release.yml) runs lint, type check, pytest (including coverage), builds with `uv build`, and publishes to PyPI.
+
+**Manual:** `uv build` (or `python -m build`), then upload `dist/` with **twine** or **`uv publish`**. Keep `pyproject.toml`, `streamtree.__version__`, `tests/test_package_meta.py`, and `CHANGELOG.md` in sync when cutting a release.
+
+## License
+
+MIT. See [LICENSE](https://github.com/streamtree-dev/streamtree/blob/main/LICENSE).

streamtree-0.4.0/README.md

@@ -0,0 +1,209 @@
+# StreamTree
+
+[![PyPI version](https://img.shields.io/pypi/v/streamtree)](https://pypi.org/project/streamtree/)
+[![Python versions](https://img.shields.io/pypi/pyversions/streamtree)](https://pypi.org/project/streamtree/)
+[![License](https://img.shields.io/pypi/l/streamtree)](https://github.com/streamtree-dev/streamtree/blob/main/LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/streamtree-dev/streamtree/ci.yml?branch=main&label=CI)](https://github.com/streamtree-dev/streamtree/actions/workflows/ci.yml?query=branch%3Amain)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://docs.astral.sh/ruff/)
+
+Declarative, typed composition for [Streamlit](https://streamlit.io/). StreamTree adds components, layout primitives, scoped session state, and test-friendly tree rendering while keeping Streamlit’s execution model and widgets. No JavaScript or separate frontend build is required.
+
+## Overview
+
+| Traditional scripts | With StreamTree |
+|---------------------|-----------------|
+| Layout and widgets mixed in one long file | `@component` functions return an **element tree** |
+| Many ad hoc `st.session_state` keys | `state()` and helpers scoped to the render path |
+| Structure is hard to inspect or snapshot | `streamtree.testing.render_to_tree()` for tests and docs |
+
+StreamTree is an **architecture layer** for Streamlit, not a React-style web framework.
+
+## Capabilities
+
+- **Components and elements** — `@component`, `render` / `render_app`, layouts (`Page`, `Card`, `Grid`, `VStack`, `Form`, `Tabs`, `Sidebar`, `Routes`, `ErrorBoundary`, and more), and widget wrappers.
+- **App shell (0.3+)** — `App` with a guarded `st.set_page_config`, plus optional sidebar and main composition via `render_app`.
+- **Theming (0.3+)** — `Theme`, `ThemeRoot`, `theme()`, `theme_css()`, and `app_context.provider(theme=...)`.
+- **Background work (0.3+)** — `streamtree.asyncio.submit` and `TaskHandle` for stdlib-thread jobs you poll across reruns.
+- **Forms (0.3+)** — Pydantic-oriented helpers: `bind_str_fields` / `str_text_inputs`, plus **`bind_numeric_fields` / `number_inputs`** (0.4+) for `int` / `float` fields (optional `int | None` / `float | None` use model defaults or `None` for an empty number input).
+- **CLI (0.4+)** — Optional **`streamtree[cli]`**: `streamtree run` delegates to Streamlit; `streamtree doctor` prints versions (see [examples/streamtree_run_demo.md](examples/streamtree_run_demo.md)).
+- **State** — `state`, `toggle_state`, `form_state`, `memo`, `cache`.
+- **Routing and context** — Query-param routing (`streamtree.routing`), `ErrorBoundary`, `streamtree.forms` utilities, and `app_context.provider` / `lookup` for shared values.
+- **Interop** — Inside `@component`, your function body runs during render; you may call `st.*` (columns, metrics, charts, third-party components) and still return an element tree, or `fragment()` when the subtree is fully imperative.
+- **Quality** — Pydantic v2 in the default install, typing-first APIs, and `render_to_tree` for structural tests.
+
+Optional extras (`tables`, `charts`, `ui`, `auth`, `asyncio`, `async`, `pages`, `runner`) are mostly stubs for future wrappers; **`[cli]`** adds **Typer** and the **`streamtree`** console script (`run`, `doctor`). See [Dependency strategy](https://github.com/streamtree-dev/streamtree/blob/main/docs/DEPENDENCY_STRATEGY.md). The `streamtree.asyncio` module and **`streamtree.helpers.runner`** ship in the default package.
+
+## Requirements
+
+Python **3.10+**, with **Streamlit ≥ 1.30** (for `st.page_link` used by `PageLink`), **Pydantic v2**, and **typing-extensions** (see `pyproject.toml`).
+
+## Installation
+
+```bash
+pip install streamtree==0.4.0
+pip install "streamtree[cli]"   # Typer + ``streamtree run`` / ``streamtree doctor``
+```
+
+From a clone, with dev dependencies:
+
+```bash
+git clone https://github.com/streamtree-dev/streamtree.git
+cd streamtree
+uv sync --extra dev
+# or: pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+from streamtree import component, render
+from streamtree.elements import Button, Card, Page, Text
+from streamtree.state import state
+
+
+@component
+def Counter():
+    count = state(0)
+    return Card(
+        Text(f"Count: {count()}"),
+        Button("Increment", on_click=lambda: count.increment(1)),
+        Button("Reset", on_click=lambda: count.set(0)),
+    )
+
+
+if __name__ == "__main__":
+    render(Page(Counter()))
+```
+
+Run examples from the repository root:
+
+```bash
+streamlit run examples/counter.py
+streamlit run examples/routed_app.py
+streamlit run examples/app_shell.py
+streamlit run examples/async_bg.py
+streamlit run examples/model_form.py
+streamlit run examples/numeric_nav_demo.py
+# With Typer installed (``pip install "streamtree[cli]"``):
+streamtree run examples/counter.py
+```
+
+## Using Streamlit inside components
+
+The `@component` body runs on every rerun in the same process as `streamlit`. You can call `st.columns`, `st.metric`, plotting APIs, or `components.v1` before returning elements. Use **stable `key=`** arguments on imperative widgets when Streamlit requires them. When a subtree is drawn entirely with `st.*`, return `fragment()`.
+
+```python
+import streamlit as st
+
+from streamtree import component, fragment, render
+from streamtree.elements import Button, Markdown, Page, TextInput, VStack
+from streamtree.state import state
+
+
+@component
+def DashboardHeader():
+    band, meta = st.columns([3, 1])
+    with band:
+        st.title("Operations")
+    with meta:
+        st.metric("Queue depth", 12, delta=-2)
+
+    notes = state("", key="header_notes")
+    return VStack(
+        Markdown("**Notes** (StreamTree `TextInput`):"),
+        TextInput("Session notes", value=notes),
+        Button("Clear notes", on_click=lambda: notes.set("")),
+    )
+
+
+@component
+def MetricsStrip():
+    cols = st.columns(4)
+    for i, col in enumerate(cols):
+        with col:
+            st.metric(f"M{i + 1}", 100 + i * 7, delta=i - 1)
+    return fragment()
+
+
+if __name__ == "__main__":
+    render(Page(DashboardHeader(), MetricsStrip()))
+```
+
+## App shell, theme, and background tasks
+
+`App` plus `render_app()` centralize page configuration. Combine `ThemeRoot` with `provider(theme=Theme(...))` for CSS variables, and use `streamtree.asyncio.submit` for non-blocking work you observe via `TaskHandle.status` on reruns.
+
+```python
+from streamtree import asyncio, component, render_app
+from streamtree.app import App
+from streamtree.app_context import provider
+from streamtree.elements import Page, Text, ThemeRoot, VStack
+from streamtree.theme import Theme
+
+
+@component
+def Body():
+    handle = asyncio.submit(lambda: 7, key="demo_job")
+    return VStack(
+        ThemeRoot(),
+        Text(f"status={handle.status()} result={handle.result()}"),
+    )
+
+
+if __name__ == "__main__":
+    with provider(theme=Theme(primary_color="#0068c9")):
+        render_app(App(page_title="Demo", body=Body()))
+```
+
+## Patterns
+
+**Grid of components**
+
+```python
+from streamtree.elements import Grid
+
+Grid(UserCard(user1), UserCard(user2), columns=2)
+```
+
+**Bound text input**
+
+```python
+from streamtree.elements import TextInput
+from streamtree.state import state
+
+search = state("")
+TextInput(label="Search", value=search)
+```
+
+## Documentation
+
+| Resource | Description |
+|----------|-------------|
+| [Plan](https://github.com/streamtree-dev/streamtree/blob/main/docs/PLAN.md) | Vision, architecture, risks |
+| [Roadmap](https://github.com/streamtree-dev/streamtree/blob/main/docs/ROADMAP.md) | Phased delivery |
+| [Dependency strategy](https://github.com/streamtree-dev/streamtree/blob/main/docs/DEPENDENCY_STRATEGY.md) | Dependencies and optional extras |
+| [CHANGELOG](https://github.com/streamtree-dev/streamtree/blob/main/CHANGELOG.md) | Release history |
+
+## Contributing
+
+Install dev tools, then run lint, type check, and tests (mirrors CI on Python 3.10–3.12):
+
+```bash
+uv sync --extra dev
+uv run ruff format .
+uv run ruff check src tests
+uv run ty check src
+uv run pytest
+```
+
+Equivalent with **pip**: `pip install -e ".[dev]"`, then `ruff`, `ty check src`, and `pytest` as above.
+
+## Releases
+
+**Automated:** Add a **`PYPI_API_TOKEN`** secret to the repository. When `main` is green, push a tag of the form **`v0.4.0`**. The [release workflow](https://github.com/streamtree-dev/streamtree/blob/main/.github/workflows/release.yml) runs lint, type check, pytest (including coverage), builds with `uv build`, and publishes to PyPI.
+
+**Manual:** `uv build` (or `python -m build`), then upload `dist/` with **twine** or **`uv publish`**. Keep `pyproject.toml`, `streamtree.__version__`, `tests/test_package_meta.py`, and `CHANGELOG.md` in sync when cutting a release.
+
+## License
+
+MIT. See [LICENSE](https://github.com/streamtree-dev/streamtree/blob/main/LICENSE).