TanStack web backlog

Decompose epics into actionable tasks. Check off as you complete; prefer issues/PRs for assignment, this file as SSOT mirror.

Phase 0 — Hygiene

• Narrative: non-product UI paths described in SSOT/ADR without legacy stack names
• Remove or rewrite vox-codegen-html references (Cargo exclude comment, forward-migration charter, Ludus quests, CodeRabbit planner allowlist)
• Link ADR 010 + this roadmap from AGENTS.md (optional one-liner)

Phase 1 — Examples

• Create examples/archive/ and move non-golden .vox files
• Update crates/vox-parser/tests/parity_test.rs MUST_PARSE (recursive walk)
• Document golden list in examples/README.md
• examples/STYLE.md + FEATURE_INDEX.md + PARSE_STATUS.md; optional VOX_EXAMPLES_STRICT_PARSE=1 in parity_test

Phase 2 — TanStack Router

• Emit createRootRoute / createRoute / createRouter / RouterProvider from routes { (vox-codegen-ts/src/emitter.rs)
• Add @tanstack/react-router to templates.rs package_json; drop unused router dep from islands package.json template
• Prefer App entry in fs_utils::find_component_name when App.tsx exists
• Integration tests: routes { codegen assertions (pipeline.rs)

Phase 3 — pnpm workspace

• Emit root pnpm-workspace.yaml when islands/ + main app paths are known (frontend.rs)
• Document root pnpm install / pnpm -r build in ref-cli.md
• Align islands workspace paths: resolve islands/ or packages/islands/ (island_package_root, pnpm-workspace.yaml, build_islands_if_present)

Phase 4 — TanStack Start + SSR

• Scaffold Start-compatible vite.config / entry (templates.rs vite_config(..., tanstack_start: true) + frontend.rs)
• routes { + Start: manifest-first — codegen routes.manifest.ts + components + vox-client.ts; user-owned TanStack adapter + file routes + routeTree.gen.ts (emitter.rs, route_manifest.rs, CLI tanstack.rs scaffold)
• Regenerate file-route routeTree.gen.ts via TanStack Router CLI (pnpm run routes:gen / tsr generate) for the no-routes { path — pnpm install / build scripts run it when not using programmatic voxRouteTree
• vox run: optional Vite upstream via VOX_ORCHESTRATE_VITE=1 + VOX_SSR_DEV_URL (see how-to)
• Generated Axum serve_dispatch: GET non-/api proxy to VOX_SSR_DEV_URL when set
• Production Docker sketch — see TanStack SSR with Axum (multi-stage Node build + Rust binary; adjust paths to your crate/binary name)
• CI: pnpm install + vite build on web-vite-build-smoke (ubuntu-latest exception) with examples/full_stack_minimal.vox (opt-in local: VOX_WEB_VITE_SMOKE=1)

Phase 5 — Query / Table (optional)

• @loading: lexer/parser → Decl::Loading → Spinner.tsx + TanStack Router pendingComponent via manifest / component wiring (route_manifest.rs, emitter.rs)
• TanStack Query helper emitted: vox-tanstack-query.tsx (via emitter.rs) defines useVoxServerQuery — import from generated output next to vox-client.ts.
• Optional enhancement: Auto-wrap useVoxServerQuery inside Path C reactive components that consume @query data (not inside routes.manifest.ts loaders, which must remain plain async functions — React hooks are invalid there). Until then, authors call useVoxServerQuery(['key'], () => myQuery({...})) in components. Legacy serverFns.ts / Wave F tasks in tanstack-start-implementation-backlog.md are superseded by vox-client.ts.
• Table-heavy UIs: TanStack Table — prefer for sort/filter/column-heavy grids when staying in React; hand-rolled <table> or lightweight lists remain fine for simple cases (see vox-web-stack.md)

Phase 6 — v0

• vox build validates each present {Name}.tsx for @v0 against the named export contract; cargo test -p vox-cli v0_tsx_normalize covers matchers; optional vox doctor check when VOX_WEB_TS_OUT points at the TS output dir
• Docs: @v0 links v0.dev, named exports, islands / vox island, and doctor env

Phase 7 — Virtual File Routes + Complete TanStack Start

Full checklist (with truth table): tanstack-start-implementation-backlog.md
Spec / historical fate table: tanstack-start-codegen-spec.md — treat virtual-file-route emit as historical; shipped model is manifest + adapter.

• Wave A — obviated / done in tree: Loader + pending + not_found / error + nested routes (field names: loader_name, pending_component_name). Deferred: under / layout_name on RouteEntry; redirect / wildcard parsing.
• Partial — Wave B: Open hir/nodes/decl.rs before executing backlog B-items; some deprecation noise intentionally remains for migration paths.
• Partial — Wave C: Classic @component fn and retired surfaces are Error (see typeck / parser); emitter loops may still exist for migration — verify tree, do not assume checklist is greenfield.
• Wave D — obviated (shape): Scaffold files: vox-cli templates + optional codegen_ts/scaffold.rs; not the spec’s exclusive Start-only client.tsx / router.tsx trio from compiler alone.
• Wave E — cancelled: Compiler __root.tsx / app/routes.ts virtual program — replaced by routes.manifest.ts + file routes + optional manifest adapter.
• Wave F: vox-client.ts + Axum (GET @query, POST mutation/server). Residual ergonomics: docs / env constants — non-blocking.
• Wave G: Docs drift vs manifest-first spec (roadmap, decorator pages, how-tos) — ongoing editorial.
• Wave H: web_routing_fullstack.vox, blog_fullstack.vox, v0_shadcn_island.vox + pipeline tests. layout_groups.vox blocked until layout/redirect grammar unless expressed as nested paths only.
• Partial — Wave I: No virtual route snapshots; instead web_ir_lower_emit, include_01 pipeline, axum_emit_contract. Add tests only if new grammar ships.
• Partial — Wave J: tanstack.rs, spa.rs, frontend.rs are live; revisit when vox init --web changes.
• Wave K: ADR 010 / architecture-index links — spot-check when touching web ADRs.