Roadmap to 1.0.0

[BorisTyshkevich]

Meta/tracking issue + living build plan. Architecture is settled (#88 / ADR-0001); the phases below are ordered so each refactor lands on a stable base and the most-wanted features ship early. Check items off as they land.

Architecture (settled — #88, ADR-0001)

• State: @preact/signals-core, migrated slice-by-slice. No UI framework (React/Preact/Solid). A Preact spike on the schema panel (spike/preact-schema, ADR-0001 addendum) confirmed a component model removes the in-place-mutation pain but buys a second render paradigm the roadmap doesn't justify.
• Shape: signals (state) · pure logic in src/core/ · imperative adapters behind injected seams for the hard / third-party / high-frequency-pointer surfaces (editor, EXPLAIN + schema graphs, Chart.js, result grid). Extract a shared primitive (EditorPort, GraphSurface, a result-view registry, Drawer) on the second consumer — not speculatively (CLAUDE.md rule 5).

Build order

Phase 0 — baseline before refactors (cheap, do first)

• Add WebKit/Safari to e2e + decide the supported-browser stance #69 — add WebKit/Safari to Playwright e2e — done (test(e2e): add WebKit/Safari to the Playwright matrix + decide the support stance (#69) #90, merged)
• De-risk the html{zoom} layout dependency (Safari verification + fallback/guard) #70 — de-risk the html{zoom} dependency — fix landed (PR fix(zoom): correctly size fullscreen graph panels on Safari under html{zoom} (#70) #92). Manual Safari testing showed the only real divergence is viewport units under zoom (Chromium's vh/vw ignore it, Safari's track it), which mis-sized the fullscreen graph panels on Safari; the divisor is now measured at runtime and published as --vp-zoom, plus the @supports not (zoom:1) 1× fallback. (The pointer/caret/drag math self-calibrates, so it was already correct on Safari — the originally-planned "mis-scaling banner" was dropped as a false-positive.) Finding: Playwright WebKit ≠ real Safari for zoom×rect/viewport, so Add WebKit/Safari to e2e + decide the supported-browser stance #69's CI "Safari verified" didn't exercise this — folded into Document the supported-browser matrix (browsers, ClickHouse versions, IdP requirements) #71. Full zoom removal still folds into Phase 3/5.

Phase 1 — finish reactivity (#88)

• tabs / activeTabId · sidePanel
• resultView / running · libraryName / libraryDirty — merged (Incremental reactivity via @preact/signals-core + architecture decisions (part of #88) #89)
• Convert the schema slice to signals (schema/schemaError/schemaFilter) — Phase 1 of #88 #91 — schema / schemaFilter → signals (replaced Set/Map, not in-place mutation); the schema panel stays imperative

Phase 2 — near-term wins (no CM6; ride on the textarea + the signals results pane)

• Cap SELECT result rows (default 500) with a 100/500/1000/5000/10000 selector #86 — cap result rows (default 500) + a 100/500/1k/5k/10k selector (server-side LIMIT, not a virtualized grid)
• Multiquery + run-selection: execute a ;-separated script (DDL / INSERT / single-row SELECT) with per-statement output #83 — multiquery / run-selection (;-split + run a selection; statement-splitter pure in core/) — PR feat: multiquery + run-selection — run a ;-separated script (#83) #95 open (awaiting merge)
• Composable queries: reference other library queries via {{name}} (CTE-merge) #39 — composable queries {{name}} CTE-merge (pure core/; no editor dependency)

Phase 3 — editor → CodeMirror 6 (#21, reopened)

• introduce an EditorPort interface + a textarea-adapter (current editor behind it)
• codemirror-adapter (@codemirror/lang-sql) behind the seam; SQL logic stays pure in core/; gated like app.js/Chart/dagre
• migrate behind the port; delete the textarea adapter once Chromium/Firefox/WebKit e2e is green

Phase 4 — editor intelligence (on CM6)

• Column-name autocompletion: FROM-driven column loading + alias/scope awareness #84 — schema-aware autocomplete (schemaCompletionSource on the live schema)
• Version-exact reference docs in the editor from ClickHouse 26.6 embedded docs #60 — version-exact reference docs: a CM6 hover extension + a right-side docs pane; extract a shared Drawer here (cell detail + schema detail + docs pane = its third consumer)

Phase 5 — schema / data-flow graph

• extract GraphSurface (src/ui/graph-surface.js) + src/core/graph-selection.js (pure) — shared by the schema graph and, where possible, the EXPLAIN pipeline graph
• Schema graph: multi-select + group-move of nodes (marquee, Shift-click, ⌘A) with single-step undo #66 — multi-select + group-move (marquee / Shift-click / ⌘A, align/distribute, single-step undo) on GraphSurface
• Schema lineage: cap the EXPLAIN AST fan-out on large schemas #42 — cap EXPLAIN AST fan-out on large schemas (pure core/)

Cross-cutting

• Local runner: desktop/native OAuth via loopback redirect (RFC 8252) instead of a registered web redirect URI #67 — local runner: native/desktop OAuth via loopback (RFC 8252)
• full html{zoom} removal — folded into the Phase 3/5 coordinate-path rewrites

Release-blockers (1.0 must not ship without)

• De-risk the html{zoom} layout dependency (Safari verification + fallback/guard) #70 (html{zoom} de-risk) ✅ fix via fix(zoom): correctly size fullscreen graph panels on Safari under html{zoom} (#70) #92 (Safari panel sizing, manually verified) · Document the supported-browser matrix (browsers, ClickHouse versions, IdP requirements) #71 (supported browsers / ClickHouse versions / IdP matrix) — Add WebKit/Safari to e2e + decide the supported-browser stance #69 (WebKit e2e) ✅ done via test(e2e): add WebKit/Safari to the Playwright matrix + decide the support stance (#69) #90

Nice-to-haves

• Small UI polish: prettier EXPLAIN (pretty/compact, version-gated), underscore-tables-last, table-detail loading spinner #85 — EXPLAIN polish (pretty/compact, underscore-tables-last, table-detail spinner)
• Export button: stream full query result to disk as TSV (File System Access API, bypasses result grid) #87 — export full result to disk (File System Access API), bypassing the grid

Done

• test(e2e): add WebKit/Safari to the Playwright matrix + decide the support stance (#69) #90 — WebKit/Safari added to the Playwright e2e matrix + support stance (Add WebKit/Safari to e2e + decide the supported-browser stance #69). Merged to main.
• Incremental reactivity via @preact/signals-core + architecture decisions (part of #88) #89 (part of Adopt reactivity via @preact/signals-core, incrementally (ADR-0001) #88) — the signals-core foundation (tabs/activeTabId/sidePanel · resultView/running · libraryName/libraryDirty), the architecture decisions (CLAUDE.md rule 5, ADR-0001 Accepted, contributor working-discipline), and the e2e import-map fix. Merged to main.

Parallelization (which issues can /ship concurrently)

Run parallel issues in separate git worktrees (claude --worktree <name> per session) — never two /ships in one working dir. Only parallelize dependency-independent issues; never run an issue against an unmerged dependency.

• Independent — parallel-safe off main now: De-risk the html{zoom} layout dependency (Safari verification + fallback/guard) #70, Composable queries: reference other library queries via {{name}} (CTE-merge) #39, Schema lineage: cap the EXPLAIN AST fan-out on large schemas #42 (pure core/ / infra; don't touch the signal-converted files).
• Now unblocked — the signals foundation (Incremental reactivity via @preact/signals-core + architecture decisions (part of #88) #89) is on main: the Phase-1 schema slice (Convert the schema slice to signals (schema/schemaError/schemaFilter) — Phase 1 of #88 #91), Cap SELECT result rows (default 500) with a 100/500/1000/5000/10000 selector #86, Multiquery + run-selection: execute a ;-separated script (DDL / INSERT / single-row SELECT) with per-statement output #83 (they build on the signal-driven results pane / run flow).
• Serial chain (each needs the previous): Consider CodeMirror 6 for the SQL editor (schema-aware autocomplete) #21 (CM6 / EditorPort) → Column-name autocompletion: FROM-driven column loading + alias/scope awareness #84, Version-exact reference docs in the editor from ClickHouse 26.6 embedded docs #60 → Schema graph: multi-select + group-move of nodes (marquee, Shift-click, ⌘A) with single-step undo #66 (after GraphSurface is extracted).

main now carries #89 + #90, so it's the clean base for everything downstream.

[BorisTyshkevich]

Roadmap state audit (2026-06-29)

Reconciled the checklist against main and the linked issues/PRs; ticked the items now actually complete.

Newly checked off (all landed in code):

• NOTICE + third-party attribution, CHANGELOG.md, CONTRIBUTING.md, issue/PR templates + CODEOWNERS, <noscript> fallback, remove design/ prototype — all shipped in PR chore: release-readiness hygiene (attribution, CHANGELOG, CONTRIBUTING, dependabot) #75 (merged). Verified present on main; design/ is gone; the bundled Chart.js/dagre notices are embedded in dist/sql.html.
• Dependency alerting — dependabot.yml shipped in PR chore: release-readiness hygiene (attribution, CHANGELOG, CONTRIBUTING, dependabot) #75. ⚠️ Caveat: no CodeQL workflow was added (.github/workflows/ is just ci.yml + release.yml). If CodeQL is wanted for 1.0, it's still outstanding — say the word and I'll open a follow-up.
• Surface an in-app version/build stamp (version + commit) for support #74 In-app version/build stamp — done via PR feat: in-app version/build stamp (version + commit) (#74) #81 (closed Surface an in-app version/build stamp (version + commit) for support #74); live on the otel demo cluster (v0.1.4 (<commit>) in the user menu).

Still open / unchecked (accurate):

• Release-blockers Add WebKit/Safari to e2e + decide the supported-browser stance #69 (WebKit/Safari), De-risk the html{zoom} layout dependency (Safari verification + fallback/guard) #70 (de-risk html{zoom}), Document the supported-browser matrix (browsers, ClickHouse versions, IdP requirements) #71 (browser matrix), Add SECURITY.md: disclosure policy + client_secret-in-config.json threat model #72 (SECURITY.md) — all open. Confirmed SECURITY.md is not yet in the repo.
• Accessibility pass: ARIA on menus/autocomplete/tabs, aria-live on errors, visible focus rings #73 accessibility (carries prefers-reduced-motion); "desktop-only" statement (tracked in Document the supported-browser matrix (browsers, ClickHouse versions, IdP requirements) #71).
• Feature tracks Schema graph: multi-select + group-move of nodes (marquee, Shift-click, ⌘A) with single-step undo #66, Schema lineage: cap the EXPLAIN AST fan-out on large schemas #42, Version-exact reference docs in the editor from ClickHouse 26.6 embedded docs #60, Composable queries: reference other library queries via {{name}} (CTE-merge) #39, Support safe live-tail results for SELECT … STREAM #59, Live visualizations for streaming queries: sliding-window aggregates and animated updates #61, Local runner: desktop/native OAuth via loopback redirect (RFC 8252) instead of a registered web redirect URI #67 — all open.

Net: the should-have/nice-to-have hygiene is essentially done; what remains for 1.0 is the four release-blockers (#69–#72) plus the per-track feature decisions.