feat: open favorited Library queries as a read-only Dashboard (#149 D1)

[BorisTyshkevich]

What & why

Part of #149 — Phase D1 of the Dashboard epic (roadmap #68, Phase 6).

Adds a standalone /sql/dashboard page that opens the favorited subset of
the Library as a read-only dashboard in a new tab — each favorited,
chartable saved query rendered as a live chart tile. It's the same served
artifact reached by a client-side route: no new runtime dependency, no build
change. KPI tiles, filters, layout, and export come in later phases (D2–D7).

What's in D1

• Route — the SPA http_handlers regex widens to ^/sql(/dashboard)?/?$
  (the anchored config.json rule is unaffected); bootstrap branches on
  location.pathname to renderDashboard vs renderApp. Config/OAuth resolve
  from the /sql base on the dashboard route (configBase), so config.json,
  token exchange, and refresh all work there.
• Auth handoff — a new tab starts signed-out (per-tab sessionStorage), so
  "Open as dashboard" hands the opener's credentials over once via a
  same-origin postMessage handshake: the child requests, the opener grants a
  snapshot. Both sides pin the exact target origin and the peer window;
  the child re-seeds its in-memory auth (token / authMode / idp / chCtx.origin)
  and its own sessionStorage. A cold/bookmarked visit has no opener and falls
  back to the normal login, which returns to the dashboard after sign-in.
• Tiles — each favorite runs read-only (readonly=2, so a favorite that
  contains a write is rejected server-side rather than executed) and renders via
  the existing renderChart / autoChart seam. Single-row (KPI) and
  non-chartable favorites are skipped with an "N not shown" header note.
  Header: back link, editable-later title, favorites chip, source chip, Refresh.
• Entry point — File ▾ → "Open as dashboard", enabled once ≥1 query is
  starred.

Layers

• Pure: src/core/dashboard.js (route/config helpers, JSON→rows transform, tile
  classification) + src/core/auth-handoff.js (snapshot/restore + message
  predicates) — both 100/100/100/100.
• Net: queryDashboardTile in src/net/ch-client.js (read-only tile fetch).
• Render: src/ui/dashboard.js over the app controller; the tile fetch goes
  through app.runTile (no src/net import in the UI layer).

Reviews

Ran self code-review, security-review (the auth-handoff surface), and a
conventions pass. Fixes folded in: reuse detectSqlFormat for trailing-FORMAT
detection (avoids double-FORMAT on FORMAT x SETTINGS y); wrap
ensureConfig/getToken inside runTile's try so a thrown token refresh
degrades to a tile error instead of freezing the grid; handle the {aborted}
tile outcome; give the opener a longer listen window than the child's request
timeout; guard the grant on hasAuth. Security review found no defects
(explicit-origin postMessage, origin+source pinning, tokens stay same-origin /
per-tab, CSP unchanged, readonly=2 unbypassable, anchored route regex).

Verification

npm test (1387 tests, per-file gate green) · npm run build · npm run test:e2e (chromium + webkit, 36) · plus a real-Chromium smoke of the built
dist/sql.html at /sql/dashboard (signed-in session + mocked ClickHouse):
the chart tile renders via real Chart.js, the KPI favorite is skipped ("1 not
shown"), and the footer shows real stats.

Notes / follow-ups

• Deploy: a cold/bookmarked /sql/dashboard OAuth sign-in needs
  /sql/dashboard registered as an IdP redirect URI (documented in README);
  opening from the app uses the in-session handoff and needs nothing extra.
• Known limitation (per Feature: open favorited Library queries as an interactive Dashboard #149): two tabs independently refreshing a
  rotating OAuth refresh token can race — BroadcastChannel sync deferred.
• Favorites auto-run on open; readonly=2 confines this to reads, equivalent to
  running the same query in the workbench.

Checklist

• npm test passes (the per-file coverage gate is non-negotiable)
• Tests added/updated in the same change as the code
• npm run build succeeds (single-file dist/sql.html)
• Layers kept honest: pure logic in src/core/, network in src/net/ (injected fetch), DOM in src/ui/
• No new runtime dependency (or it's a deliberate, justified addition — see CONTRIBUTING)
• README / CHANGELOG.md ([Unreleased]) updated if behavior or the deployed surface changed
• Reconciled affected tracked work (roadmap Roadmap to 1.0.0 #68, the issue body, ADR/CHANGELOG) if this change reshaped it

🤖 Generated with Claude Code