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

• 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
• Export button: stream full query result to disk as TSV (File System Access API, uncapped, bypasses the grid) #87 — streaming Export, uncapped, via File System Access API — merged (PR feat: streaming Export — stream full query result to disk, uncapped (#87) #103)
• Export script: run multi-statement SQL with log pane and multiple output files #99 — script export (multi-statement follow-up to Export button: stream full query result to disk as TSV (File System Access API, uncapped, bypasses the grid) #87): directory picker, sequential per-statement files, live log pane — PR feat: script export — multi-statement follow-up to streaming Export (#99) #104 open

Phase 3 — Windows

• Detached-tab pattern: extract shared primitive; add Data Pane Expand + convert Pipeline Expand #100 — detached-tab primitive (src/ui/detached-view.js) extracted from the schema graph's tab/overlay logic; now shared by the schema graph, the EXPLAIN pipeline graph (gains real-tab support), and a new Data Pane Expand (snapshot grid, sort/copy, in a tab or overlay). app.state.detachedView (a count) tracks open views. — PR open
• Cell-detail right-hand drawer: add horizontal resize #101 — cell-detail drawer horizontal resize (drag handle, splitters.js 'drawer' axis) — PR open
• UI consistency polish: disclosure chevrons, toast dismiss, popover autofocus, open-state tracking #102 — UI consistency polish: disclosure chevrons, toast dismiss, popover autofocus, open-state tracking — PR open

Phase 4 — editor

• 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
• 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

• Composable queries: reference other library queries via {{name}} (CTE-merge) #39 — composable queries {{name}} CTE-merge (pure core/; no editor dependency)
• 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

[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.