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 4/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
• Support variables in SELECT queries #134 — query variables: detect {name:Type} while editing, show an input strip, gate Run until filled, and substitute via ClickHouse's native param_<name> args (server-side, type-correct); reads only, so CREATE VIEW definitions stay verbatim. Values shared by name + persisted (asb:varValues). Pure detection/classification in src/core/query-params.js; no new dep. Distinct from Composable queries: reference other library queries via {{name}} (CTE-merge) #39 ({{name}} composable-query CTE-merge — different syntax and purpose). — merged (feat: query variables ({name:Type}) with native param_ substitution (#134) #138)

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: CodeMirror 6 + the features it unlocks

Strict sequence — each issue is the foundation of the next: #143 → #21 → #84 → #60.

• EditorPort: extract the editor behind an injected port; textarea as first adapter (no behavior change) #143 — EditorPort seam: every consumer moves onto an injected port; the current textarea editor becomes its first adapter. No behavior change — makes the CM6 swap reversible.
• Adopt CodeMirror 6 behind the EditorPort seam (replace the hand-rolled textarea editor) #21 — adopt CM6 behind the port (the deliberate 4th runtime dep; bundle delta measured: +406 KB raw / +134 KB gzip, approved at the plan gate): ClickHouse-dialect highlighting, per-tab undo, completion/hover parity v0 from core/completions.js; textarea adapter + superseded ui/editor-* / core/editor-* modules deleted. — PR feat: adopt CodeMirror 6 behind the EditorPort seam (#21) #145 open; manual real-Safari pass still owed post-merge (De-risk the html{zoom} layout dependency (Safari verification + fallback/guard) #70 lesson).
• Column-name autocompletion: FROM-driven column loading + alias/scope awareness #84 — schema-aware autocomplete on CM6: pure core/from-scope.js (FROM/alias resolution) + debounced idle-tick column loading feeding the completion source (never on the keystroke path). — PR feat: FROM-aware autocompletion — alias/scope resolution + debounced column loading (#84) #146 open (alias→table resolution, statement-scoped unqualified columns, 300ms idle-tick column prefetch; core/from-scope.js + core/completions.js at 100%).
• Version-exact reference docs in the editor from ClickHouse 26.6 embedded docs #60 — version-exact reference docs: CM6 hover extension + 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/)

Phase 6 — Dashboard (#149)

Epic: open favorited Library queries as an interactive dashboard in a new tab
(/sql/dashboard). Spec + pinned decisions + sub-phases D1–D8 live in #149. Same architecture
(signals + hyperscript, no framework — reaffirmed against the React mockup); one artifact,
client-side route; auth via one-time postMessage handoff + login fallback. Builds on #134
({name:Type} params / varValues) and the chart core.

• Feature: open favorited Library queries as an interactive Dashboard #149 D1 — route + auth handoff + read-only dashboard (favorites → chart tiles) — PR feat: open favorited Library queries as a read-only Dashboard (#149 D1) #150 merged
• Feature: open favorited Library queries as an interactive Dashboard #149 D2 — layout: Report mode + Arrange/Report switcher + 2/3 column count (persisted) — PR feat: dashboard Arrange/Report layout switcher (#149 D2) #151 merged
• Feature: open favorited Library queries as an interactive Dashboard #149 D3 — global filters (text): filter bar over {name:Type} params detected across every
  favorite's SQL, sharing state.varValues with the workbench; debounced re-run, per-tile
  unfilled-param gating, stable per-favorite tile slots (**Phase D3 — global filters (text)**: filter bar over detected {name:Type} params, re-run affected tiles #152) — PR pending
• Feature: open favorited Library queries as an interactive Dashboard #149 D4 — layout: drag-reorder, 1/2-col span, open panel in window (**Phase D4 — layout**: drag-reorder, 1/2-col span, open panel in window. #153)
• Feature: open favorited Library queries as an interactive Dashboard #149 D5 — KPI tiles (readKpi/formatKpiValue in core/, 100%) (Phase D5 — KPI tiles: readKpi + formatKpiValue in src/core/ (100%), single-row classification, KPI row, bare-scalar fallback, skipped-tiles note. #154)
• Feature: open favorited Library queries as an interactive Dashboard #149 D6 — curated filters (filter: / filter[]: queries, cascading)
• Feature: open favorited Library queries as an interactive Dashboard #149 D7 — expand modal, per-tile overrides, drill-down highlight
• Feature: open favorited Library queries as an interactive Dashboard #149 D8 — export (Markdown / PDF print / per-chart PNG)

Note: this checklist previously had D3/D4 swapped (layout vs. global filters) relative to #149's
own body — corrected here during #152 to match #149, the source of truth for phase order.

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 — the 1.2× scale is gone (--zoom: 1, PR fix: remove html{zoom:1.2} to kill phantom scrollbars; restore editor bars #147): it was landing box sizes on fractional device pixels and painting phantom scrollbars (editor most visibly; feat: adopt CodeMirror 6 behind the EditorPort seam (#21) #145 had hidden the editor's bars to dodge it). Setting --zoom:1 drops the app into the already-tested @supports not (zoom:1) state, so the bridging layer (--vp-zoom, Chart/menu/splitter correction) is now dormant at divisor 1. Remaining: tear out that dead scaffolding (Tear out the now-dormant html{zoom} bridging code (--zoom is 1 since #147) #148) — still wants a GraphSurface Schema graph: multi-select + group-move of nodes (marquee, Shift-click, ⌘A) with single-step undo #66 / real-Safari pass since Playwright WebKit ≠ real Safari for zoom×rect.

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.