StreamTree Roadmap

This document tracks product direction and phased delivery. It aligns with DEPENDENCY_STRATEGY.md (optional extras, wrapper-first APIs) and PLAN.md (async + rerun model). CHANGELOG records what actually shipped per version.

How to use this roadmap

Release index (table below) — snapshot of phases and what has shipped in tagged releases (PyPI publishes when the release workflow succeeds on v*.*.* tags).
Near-term themes — backlog and cross-cutting work (docs, CLI, helpers) that span releases.
Pattern catalog — design vocabulary mapped to phases (not a separate product spec).
Phase 0–5 — historical goals and long-range bets; detailed shipped vs open for Phase 2 lives in the table + backlog, not duplicated in the Phase 2 feature list.

Contents: Release index · Phase 2 backlog & themes · Patterns · Phase 0 · Phase 1 · Phase 2 · Phase 3 · Phase 4 · Documentation (RTD) · Phase 5 · Vision

Release index

Last updated: 2026-05-13 (0.11.0 Phase 4 tooling slice).

Track	Status	Notes
Phase 0 — Foundation	Complete	Package layout, Streamlit renderer, design docs in `docs/`.
Phase 1 — MVP	In progress	0.1.0 core tree + state; 0.2.0 Pydantic + stub extras; deeper memoization / `streamlit-extras` curation still open.
Phase 2 — Application	Complete (0.9.0)	Shipped through 0.9.0: navigation sections (`page_links_sidebar_sections`, `multipage_sidebar_nav`), routing clears/batch (`clear_route`, `update_query_params`, …), bool + layout forms (`docs/PHASE2_FORMS.md`), `[ui]` (Stoggle, TaggerRow, MentionChip), `dismiss_tasks`, composite example `phase2_composite_demo.py`, Phase 2 doc reconciliation. 0.10.0+ adds `streamtree init --template` scaffolds (Phase 3). Stretch: heavier opinionated `App` + `Routes` product templates; alternate auth protocols → backlog.
Phase 3 — Data toolkit	Complete (0.10.0)	Shipped through 0.10.0: CRUD helpers, subtree memo, deferred fragments, perf/debug counters, ordered `submit_many` helper, exploration + enterprise protocol modules, `streamtree init --template`, docs and demos. Stretch (deeper admin frameworks, heavier analytics) → Phase 4 / app-specific layers.
Phase 4 — Tooling	Complete (0.11.0)	`streamtree tree` / `preview` / `serve`, `doctor --verbose`, `testing.viz`, `testing.introspection`, `testing.apptest`, `asyncio.summarize_async_tasks`, `debug_render_path`; MkDocs + mkdocstrings API pages; `.readthedocs.yml`. Docs — RTD: site config in-repo; PyPI `Documentation` URL points at RTD (`latest`; `stable` once versioned builds are active). Stretch (Storybook-style visual regression) remains backlog. Backlog: imperative Streamlit codegen (virtual `Element` tree → readable *`st.`** / context-manager Python) for docs, migration, and debugging — see Phase 4.
Docs — Read the Docs	In progress	`.readthedocs.yml` + PyPI `Documentation` URL (RTD `latest`); manual, guides, and API reference expand over releases (Documentation platform).

0.11.0 (shipped)

CLI: streamtree tree (module:attr, --format, --summarize, --expand-components); preview / serve aliases of run; doctor --verbose.
Testing / dev: streamtree.testing.viz, streamtree.testing.introspection, streamtree.testing.apptest, streamtree.asyncio.summarize_async_tasks, debug_render_path; examples.counter:streamtree_tree_root for tree demos.
Docs: docs/TESTING_AND_DEBUG.md; MkDocs mkdocstrings API reference; .readthedocs.yml.

0.10.0 (shipped)

Charts: AltairChart (Altair / st.altair_chart); EChartsChart (Apache ECharts via streamlit-echarts); [charts] pins altair, plotly, and streamlit-echarts; examples/altair_chart_demo.py, examples/echarts_demo.py.
Tables: DataGrid.on_result hook after AgGrid for selection-driven logic without forking the renderer; examples/datagrid_selection_demo.py.
Loading: streamtree.loading.match_task_many for all-done / any-error / any-cancelled semantics across several TaskHandle-like polls; submit_many_ordered for stable key ordering with match_task_many.
State / layout: memo_subtree (render-path scoped memo); DeferredFragment (st.fragment when available).
Thin modules (stdlib): streamtree.crud, streamtree.enterprise, streamtree.perf, streamtree.helpers.explore.
CLI / scaffold: streamtree init --template {default,crud,explore,enterprise} (Typer --template / -t).
Testing: streamtree.testing.summarize_tree_kinds for render_to_tree summaries.
Docs / examples: docs/PHASE3_CRUD.md, docs/PERFORMANCE.md (large-tree + hooks); examples/crud_pattern_demo.py, crud_automation_demo.py, deferred_region_demo.py, async_ordered_loader_demo.py.

0.9.0 (shipped)

Portals: Portal / PortalMount, gather_portals, portal_render_context (renderer integration); design in PHASE2_PORTALS_AND_PREFETCH.md.
Layout: SplitView (pseudo-sidebar via columns).
Multipage: iter_page_entries, prefetch_page_sources (stdlib file read + optional compile check); group_page_entries_by_order_prefix, page_links_sidebar_sections, multipage_sidebar_nav; documented in PERFORMANCE.md.
Forms: streamtree.forms_layout — build_model_from_bindings, model_field_grid (row/column layout, including bool fields); bool_field_names, bind_bool_fields; doc docs/PHASE2_FORMS.md.
Routing: clear_query_param, clear_route, update_query_params.
[ui]: BottomDock, FloatingActionButton, Stoggle, TaggerRow, MentionChip (streamlit-extras).
Async: dismiss_tasks batch terminal cleanup.
Docs / examples: docs/PHASE2_TAIL.md reconciliation; examples/phase2_composite_demo.py; README multipage vs Routes guidance; roadmap Phase 2 closure.

0.8.0 (shipped)

streamtree.helpers.page_links + init --with-pages template (discover_pages in sidebar).
streamtree.asyncio.dismiss_task for terminal task cleanup before key reuse.
[ui]: SocialBadge, StyleMetricCards.
[tables] / [charts]: DataGrid (streamlit-aggrid) and Chart (Plotly); streamtree.loading.match_task; routing.sync_query_value / set_query_value; docs/PERFORMANCE.md; examples datagrid_demo, chart_demo, async_loader_demo.
[all] and [dev]: include aggrid + plotly pins for combined installs and CI coverage.

0.7.1 (shipped)

Packaging / docs: patch 0.7.1; README CI badge and Actions links adjusted for the active GitHub remote used in development (see CHANGELOG).

0.7.0 (shipped)

streamtree.asyncio: submit_many for parallel independent tasks; cooperative cancellation (TaskHandle.cancel() on running work sets cancel_requested; is_task_cancel_requested / complete_cancelled for workers); mark_done respects worker-initiated cancelled; module docstring covers stale keys (same key = same logical task across reruns).

0.6.0 (shipped)

streamtree init: scaffold app.py (+ optional pages/) via [cli]; streamtree.helpers.scaffold.
AuthGate + streamtree.auth.build_authenticator behind [auth] (streamlit-authenticator).
Dialog / Popover overlay elements; Streamlit ≥ 1.33 dependency floor.
[ui]: ColoredHeader, VerticalSpaceLines (streamlit-extras wrappers).
Docs / tests: PHASE2_TAIL.md; expanded renderer and CLI coverage.

0.5.0 (shipped)

streamtree.helpers.pages: PageEntry, pages_dir_next_to, list_page_entries, discover_pages for Streamlit pages/ scripts (labels + sort keys + PageLink paths); exported from streamtree.helpers.
streamtree.asyncio: set_task_progress and TaskHandle.progress(); task session dict stores progress (lock-serialized with status/result/error).
Examples: examples/pages_helpers_demo.py, stub examples/pages/1_About_demo.py.
Docs: README install pin + capabilities, PLAN.md packaging line, DEPENDENCY_STRATEGY.md (helpers.pages + progress), this roadmap’s release index / Phase 2 “Next”.
Tests: expanded coverage for helpers.pages (paths, unicode, ordering, in-directory symlinks) and asyncio progress (poll while running, error path, main-thread updates).

0.4.1 (shipped)

Patch: version 0.4.1; README / changelog release metadata; CI badge target alignment (fork).

0.4.0 (shipped)

CLI: optional [cli] (Typer) + streamtree run / streamtree doctor; delegates to streamlit run.
streamtree.helpers.runner: argv builder + run_streamlit_sync (stdlib). [runner] extra remains a metadata stub; [pages] reserved for multipage helpers.
PageLink + st.page_link renderer path; Streamlit ≥ 1.30 required.
App: initial_sidebar_state, menu_items for st.set_page_config.
Forms: bind_numeric_fields, number_inputs, numeric_field_names.
Examples: examples/numeric_nav_demo.py, examples/streamtree_run_demo.md.

0.3.0 (shipped)

streamtree.app: App, apply_page_config, app_root_element, render_app() (guarded st.set_page_config).
streamtree.theme: Theme, theme() / theme_css(), ThemeRoot + provider(theme=...).
streamtree.asyncio: submit / TaskHandle (stdlib threads; [asyncio] slot for future backends).
streamtree.forms: bind_str_fields, str_text_inputs.
Examples: examples/app_shell.py, examples/async_bg.py, examples/model_form.py.

0.2.0 (shipped)

Deps: Pydantic v2, typing-extensions; stub extras (tables, charts, ui, auth, asyncio, async, cli, all); [async] aliases [asyncio] in pyproject.toml.
Routing: sync_route, set_route, Routes (examples/routed_app.py).
ErrorBoundary, app_context, forms slice (str_field_names, model_validate_json, format_validation_errors).

Phase 2 backlog & near-term themes

Backlog (post-0.6.0; Phase 2 application track closed at 0.9.0)

Stretch: opinionated App + Routes product templates (beyond streamtree init --template shells and helpers); alternate auth providers / OIDC stacks remain bring-your-own.
Auth: alternative providers / OIDC stacks remain bring-your-own; [auth] stays streamlit-authenticator + AuthGate unless a future pinned abstraction ships.
Async: new worker backends or pools (Phase 3 [async] story), beyond dismiss_tasks batching.
More streamlit-extras curation behind stable StreamTree names (ongoing).
Richer theme / memoization — largely Phase 1 / 3 (see release index).

Optional dedicated helpers

Reserved empty extras (same pattern as [pages]) until deps/APIs are pinned:

[pages] — optional extra stays empty until pinned third-party deps land; streamtree.helpers.pages (stdlib discovery) ships in the default install as of 0.5.0 — multipage / pages/ + navigation APIs ↔ Routes, App; Streamlit version matrix; no second web server.
[runner] — metadata-only companion to streamtree.helpers.runner (stdlib streamlit run helpers ship in the default install; [cli] adds Typer for the streamtree console script).

End-to-end app experience (optional Streamlit CLI)

Goal — One StreamTree-shaped workflow (scaffold → configure → run) without requiring the Streamlit CLI for teams that opt in.

Always supported: streamlit run app.py (CI, debugging, power users).
Shipped (0.4.0): streamtree run / streamtree doctor behind pip install "streamtree[cli]", delegating to python -m streamlit run (see streamtree.helpers.runner).
Shipped (0.6.0): streamtree init for app.py (+ optional pages/).
Boundary: DX/packaging layer in Phases 2–4, not a new server. “No Streamlit CLI” = no obligation to use Streamlit’s CLI, not removing Streamlit from the stack.
Docs: Full manual/guides on RTD (Documentation platform); README stays short.

Patterns from React ergonomics (non-VDOM, rerun-native)

StreamTree is not React and will not ship a browser VDOM. The list below maps product patterns to Streamlit’s rerun model (see phase column).

Error boundaries — subtree failures → fallback UI + logging.
Context / DI — theme, tenant, flags, route data without prop drilling.
Stable list identity / keys — dynamic children stay aligned across reruns.
Subtree memoization — skip rebuilding when inputs unchanged.
Transitions / deferred regions — lower-priority or chunked regions under load.
Suspense-shaped async — loading / ready / error UI for async-shaped work (rerun-native).
Imperative handles — focus, scroll, etc., where Streamlit allows; document limits.
Portals / layout targets — attach subtrees to sidebar, dialog, etc.
Dev introspection — tree, props, bound session_state keys.
Async task orchestration — submit off-thread, poll on rerun; optional progress (asynclit-class integrations behind streamtree.* when applicable).

#	Pattern	Primary phases
1	Error boundaries	2, 5
2	Context / DI	2, 5
3	Keyed lists / identity	1, 2
4	Subtree memoization	1, 3
5	Transitions / deferred regions	3
6	Async / Suspense-shaped boundaries	1, 2, 3
7	Imperative handles	2
8	Portals / layout targets	2
9	Dev introspection	4
10	Async task orchestration	2, 3, 4, 5

Phase 0 — Foundation

Goals

Package architecture, core rendering, developer ergonomics.
Dependency philosophy: small hard set; heavy stacks opt-in via extras.

Deliverables

Element model, @component, tree + Streamlit renderer.
Minimal docs; pattern philosophy tied to Patterns.
Async + rerun narrative + pointers to PLAN.md.
pyproject.toml install tiers documented (streamtree, [tables], …, [pages], [runner] when added, [dev], [all]).

Phase 1 — MVP

Goals

Usable framework on Streamlit; core layouts and state.

Features (checklist)

Elements: Text, Markdown, Button, TextInput, NumberInput, SelectBox, Checkbox, DataFrame, Image.

Layouts: VStack, HStack, Grid, Columns, Tabs, Sidebar, Form, Card.

State: state, toggle_state, form_state, session_state.

Rendering: render, component identity, key discipline.

Rerun-native: keyed dynamic lists; subtree memo hooks where MVP allows; documented loading branches (loading / ready / error) without blocking render.

Async (guidance): when to use st.cache_data / fragments vs future streamtree.asyncio.

Dependency alignment (MVP)

Hard deps per strategy; Pydantic for props/forms where scope allows.
Curated streamlit-extras only behind stable streamtree.* names.

Deliverables

pip-installable package, examples, demos.
Stub extras in pyproject.toml (tables, charts, ui, auth, async, cli, pages, runner, all) as names are reserved.
Optional [async] integration path documented even if not default-installed yet.

Phase 2 — Application features

Goals

Production-grade apps on Streamlit: routing, resilience, theming, async slice, forms.

Shipped on the Phase 2 track (0.2.0–0.9.0)

The bullets below are delivered today; per-version pins and changelog prose live in the Release index and CHANGELOG.md.

Routing & resilience: sync_route / set_route, Routes, ErrorBoundary, app_context.
Forms: Pydantic-first string + scalar numeric bindings and inputs.
App shell: App, apply_page_config, render_app, sidebar composition, PageLink + st.page_link, initial_sidebar_state / menu_items passthrough.
Theming: Theme / theme() / ThemeRoot.
Async worker slice: streamtree.asyncio submit / TaskHandle, session task dict, progress + set_task_progress / TaskHandle.progress(); submit_many and cooperative cancel (0.7.0); dismiss_task for terminal cleanup before key reuse (0.8.0).
Run / multipage DX (stdlib): streamtree.helpers.runner, optional [cli] streamtree run / doctor / init (with --with-pages shell + page_links, 0.8.0), streamtree.helpers.pages (discover_pages, page_links, …).
Package surface: helpers is exposed on the streamtree root package (streamtree.helpers).
Optional auth: AuthGate + [auth] (streamlit-authenticator).
Overlays: Dialog, Popover (Streamlit-native; version floor 1.33).
Optional UI extras: [ui] — ColoredHeader, VerticalSpaceLines (0.6.0); SocialBadge, StyleMetricCards (0.8.0); BottomDock, FloatingActionButton (0.9.0).
Portals & layout targets (0.9.0): Portal / PortalMount, SplitView, prefetch helpers — see PHASE2_PORTALS_AND_PREFETCH.md.
Layout-aware forms (0.9.0): streamtree.forms_layout — build_model_from_bindings, model_field_grid (str / numeric / bool); see PHASE2_FORMS.md.
Navigation / imperative edge (0.9.0): sectioned pages/ sidebar helpers; routing clear/batch query helpers (see README “Imperative handles”).
[ui] breadth (0.9.0): Stoggle, TaggerRow, MentionChip.
Async polish (0.9.0): dismiss_tasks batch terminal cleanup.

Release notes

Shipped scope for 0.2.0 through 0.9.0 is in the Release index and subsections above. Stretch work is in the backlog and PHASE2_TAIL.md.

Optional dependency alignment

[auth]: streamlit-authenticator behind AuthGate / build_authenticator; document limits; third-party identity stacks stay app-wrapped until a future pinned protocol ships.
[ui]: shadcn-style / extra-streamlit-components only behind StreamTree components.
[async] (when shipped): optional backend (e.g. asynclit) only via streamtree.asyncio public API.

Deliverables (remaining / stretch)

Phase 2 application deliverables from the original charter are closed as of 0.9.0 (see PHASE2_TAIL.md closure checklist). Ongoing product work continues under Phase 3 (data), 4 (tooling), and the stretch bullets in the backlog above.

Example apps for deeper data workflows and Phase 3 loaders (beyond the phase2_composite_demo slice).

Phase 3 — Data application toolkit

Goals

Best architecture layer for data-heavy Streamlit apps.

Features

Shipped (0.8.0): optional [tables] / DataGrid, [charts] / Chart (Plotly MVP); routing.sync_query_value / set_query_value; streamtree.loading.match_task for declarative loading / ready / error subtrees from TaskHandle.
Shipped (0.10.0): AltairChart (Altair); EChartsChart (streamlit-echarts); DataGrid.on_result; match_task_many; submit_many_ordered; memo_subtree; DeferredFragment; streamtree.crud, streamtree.enterprise, streamtree.perf, helpers.explore; streamtree init --template; testing.summarize_tree_kinds; docs/PHASE3_CRUD.md, PERFORMANCE.md, DEPENDENCY_STRATEGY.md updates; examples altair_chart_demo, echarts_demo, datagrid_selection_demo, crud_pattern_demo, crud_automation_demo, deferred_region_demo, async_ordered_loader_demo.
Stretch (Phase 4+): deeper packaged admin frameworks, richer analytics integrations, optional worker backends—treat as product-specific unless pinned here later.

Optional dependency alignment

[tables]: e.g. streamlit-aggrid → DataGrid.
[charts]: plotly + altair + streamlit-echarts → Chart, AltairChart, EChartsChart (see pyproject.toml / CHANGELOG 0.10.0).
[async]: worker-loop integration; docs stay on streamtree.asyncio.

Deliverables

Templates, exploration toolkit, enterprise-oriented components.
Shipped: docs/PERFORMANCE.md playbook; docs/PHASE3_CRUD.md; streamtree init --template shells; examples datagrid_demo, datagrid_selection_demo, chart_demo, async_loader_demo, altair_chart_demo, echarts_demo, crud_pattern_demo, crud_automation_demo, deferred_region_demo, async_ordered_loader_demo.
Ongoing (docs platform): streamtree.asyncio reference depth (cancellation, stale-run rules) in RTD / guides when the docs site lands.

Phase 4 — Testing and tooling

Goals

Enterprise workflows: testing, CLI, introspection, StreamTree-first run (optional), RTD as canonical learning surface.

Features

Shipped: streamtree.testing.render_to_tree for JSON snapshot workflows in tests (see README testing row); 0.10.0+ streamtree.testing.summarize_tree_kinds for kind counts on tree dicts.
Shipped (CI): lint-test (reusable workflow) runs ruff (format + lint), ty, and pytest with coverage on ubuntu-latest, windows-2025-vs2026, and macos-latest, each with Python 3.10–3.13; cli-smoke runs streamtree doctor with [cli] on the same three OSes; docs-and-dist runs MkDocs (build --strict) and uv build on Ubuntu + 3.12. Release reuses the same jobs, uploads dist/ from docs-and-dist for publish-pypi / publish-github, and uses concurrency + Dependabot for Actions (see .github/workflows/).
Shipped (0.11.0): streamtree tree (JSON / text / Mermaid, --summarize, --expand-components); streamtree preview / serve (run aliases); doctor --verbose; streamtree.testing.viz, streamtree.testing.introspection, streamtree.testing.apptest, streamtree.asyncio.summarize_async_tasks, debug_render_path; MkDocs + mkdocstrings API pages; .readthedocs.yml for RTD builds.
Backlog — Streamlit codegen: emit imperative Streamlit Python from a frozen Element tree (parallel to render_to_tree, not a second renderer). Intended for RTD side-by-side “Streamlit equivalent” panels, migration off StreamTree, and debug diffs. Scope is best-effort: map built-in streamtree.* widgets/layouts to st.* / with st.*; @component call sites may expand to inlined subtrees when expand_components=True-style data is available, otherwise stubs or comments. Extras (DataGrid, EChartsChart, …) need explicit tables or “opaque custom block” escapes. Likely homes: streamtree.testing or streamtree tree --format streamlit (CLI + library API).
Stretch / backlog: Storybook-style visual regression; heavier “preview server” beyond Streamlit forwarding.

Optional dependency alignment

[dev]: pytest, ruff, ty (CI typecheck), mypy (optional local contributor toolchain); mkdocstrings + mkdocs-autorefs for API reference builds.
[cli]: typer + minimal deps; streamlit run remains documented fallback.

Deliverables

Shipped / in repo today: cross-platform CI coverage (see Features above); render_to_tree and summarize_tree_kinds workflows; 0.11.0 CLI + testing helpers + RTD config + API reference skeleton.
Ongoing: RTD project wiring + deeper manual / guides; async testing recipes beyond run_app_function; optional visual regression tooling; Streamlit codegen from element trees (Phase 4 Features backlog above).
streamtree entry point — RTD ↔ CLI copy alignment (Documentation platform).

Documentation platform (Read the Docs)

Goals

Versioned, searchable docs on Read the Docs as the primary learning path (README + docs/*.md stay summaries / design depth).

Scope (rolled out over several releases)

User manual: concepts (rerun model, trees vs st.*, @component, keys, render / render_app, App); core libs; optional extras matrix + Streamlit version notes; interop + deployment.

How-to guides: first full app; routing; forms; async; lifecycle tutorials once streamtree run / init exist (End-to-end).

API reference: autodoc (Sphinx or MkDocs/mkdocstrings—decision in-repo); intersphinx to Streamlit / Pydantic / stdlib; stable per-symbol URLs.

Streamlit equivalent (future): optional generated st.* blocks next to StreamTree snippets once imperative Streamlit codegen lands (Phase 4 backlog — Testing and tooling).

Operations: stable vs latest policy tied to tags/PyPI; PR doc builds with fail-on-broken-links where feasible; contributor preview + prose styleguide.

Deliverables

RTD project + webhooks; site skeleton (Manual · Guides · API · release notes link).
MVP: minimal manual + one end-to-end guide + API index before “1.0”; then flesh out scope above.
PyPI Documentation URL → RTD stable when the site goes public.

Phase 5 — Ecosystem expansion

Goals

Optional non-Streamlit renderers and plugin ecosystem.

Features

FastAPI / static HTML renderers; plugin registry; cross-runtime error/context/memo semantics where feasible; async-native data hooks for alternate hosts; FastAPI + Streamlit coexistence patterns.

Deliverables

Multi-renderer abstraction, plugin SDK, extension registry, async-capable plugin contract.

Long-term vision

StreamTree becomes:

The architecture layer for Streamlit-first apps.
A Python-native UI ecosystem with optional heavier runtimes.
A production application platform: optional StreamTree CLI + templates + runner for create/run, Streamlit as default engine, streamlit run always available.
A project whose manual, guides, and API reference live on Read the Docs (above).

Potential spin-out packages: streamtree-auth, streamtree-testing, streamtree-fastapi, streamtree-admin, streamtree-charts, streamtree-enterprise, optional streamtree-async if streamtree.asyncio grows large enough.

Reuse Patterns for testing, admin, and async-heavy surfaces.