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

Phase D1 of the Dashboard epic: a standalone `/sql/dashboard` route (the same
served artifact, reached by a client-side branch) that renders the favorited
subset of the Library as read-only chart tiles. No new runtime dependency, no
build change.

- Route: widen the SPA `http_handlers` regex to `^/sql(/dashboard)?/?$` and
  branch on `location.pathname` in `bootstrap` (renderDashboard vs renderApp).
  Config/OAuth resolve from the `/sql` base on the dashboard route (configBase).
- Auth: a one-time, same-origin `postMessage` credential handoff from the
  opener (both target origin and peer window pinned), re-seeding the child's
  in-memory auth (token/authMode/idp/chCtx.origin) and its own per-tab
  sessionStorage. A cold/bookmarked visit falls back to the normal login flow.
- Tiles: each favorite runs read-only (`readonly=2`, writes rejected
  server-side) and renders via the existing `renderChart`/`autoChart` seam;
  single-row (KPI) and non-chartable favorites are skipped with an "N not
  shown" header note.
- File menu gains "Open as dashboard" (enabled once ≥1 query is favorited).

Pure logic in `core/dashboard.js` + `core/auth-handoff.js` (100%); net helper
`queryDashboardTile`; render in `ui/dashboard.js`. Tests added to the per-file
coverage gate; README (routes + redirect-URI note) and CHANGELOG updated.

KPI tiles, global filters, drag-to-arrange layout, per-tile controls, and
export follow in #149 D2–D7.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GyLqZGyUkm7mP6WhZCkodj

Author: BorisTyshkevich

CHANGELOG.md

@@ -9,6 +9,24 @@ auto-generated per-PR notes; this file is the curated, human-readable history.
 
 ## [Unreleased]
 
+### Added
+- **Dashboard (phase 1): open your favorited Library queries as a read-only
+  dashboard in a new tab** (#149). A new **File ▾ → "Open as dashboard"** item
+  (enabled once at least one query is starred) opens `/sql/dashboard` — the same
+  single served artifact, reached by a client-side route — and renders each
+  favorited, chartable query as a live chart tile, reusing the existing Chart.js
+  result view. The new tab is authenticated by a **one-time, same-origin
+  `postMessage` credential handoff** from the opener (both the target origin and
+  the peer window are verified); a cold/bookmarked visit falls back to the normal
+  login flow, which returns to the dashboard after sign-in. Tile queries run
+  **read-only** (`readonly=2`), so a favorite that happens to contain a write is
+  rejected server-side rather than executed on open/refresh. Single-row (KPI) and
+  non-chartable favorites are skipped for now with an "N not shown" note. KPI
+  tiles, global filters, drag-to-arrange layout, per-tile controls, and export
+  arrive in later phases (#149 D2–D7). Known limitation: two tabs independently
+  refreshing a *rotating* OAuth refresh token can race (BroadcastChannel sync
+  deferred).
+
 ### Fixed
 - **Editor scrollbars are back, and the whole UI's scrollbars behave
   consistently again.** The console no longer renders at 1.2× via `html{zoom}`

README.md

@@ -374,7 +374,12 @@ see "Security headers" below), and uploads the SPA + config into ClickHouse
 
 1. Add the rendered `dist/http_handlers.xml` to the server's `config.d/` (or push
    it as an ACM cluster setting `config.d/sql-browser.xml`) and reload ClickHouse.
-2. Register the redirect URI `https://<ch-host>/sql` with your OAuth IdP.
+   The SPA handler serves both `/sql` (the workbench) and `/sql/dashboard` (the
+   favorites dashboard) from the same file.
+2. Register the redirect URI `https://<ch-host>/sql` with your OAuth IdP. If users
+   will open `/sql/dashboard` via a cold/bookmarked link (rather than from the app,
+   which hands credentials over in-session), also register
+   `https://<ch-host>/sql/dashboard` so that direct sign-in can complete.
 3. Make sure ClickHouse accepts the bearer JWT — either a CH
    `<token_processors>` entry validating your IdP's JWKS, or a delegated
    `<http_authentication_servers>` verifier. See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md).

deploy/http_handlers.xml

@@ -6,6 +6,7 @@
 
   Routes:
     GET /sql              -> the SPA (dist/sql.html in user_files)
+    GET /sql/dashboard    -> the SAME SPA (client-side route: the favorites dashboard)
     GET /sql/config.json  -> the OAuth config (issuer + client_id [+ audience])
 
   The SPA POSTs queries to "/" with `Authorization: Bearer <id_token>`; that is
@@ -23,7 +24,10 @@
 <clickhouse>
   <http_handlers>
     <rule name="sql_browser_spa">
-      <url>regex:^/sql/?$</url>
+      <!-- Serves the SPA for both the workbench (/sql) and the client-side
+           dashboard route (/sql/dashboard) from the same sql.html. The
+           config.json rule below is anchored separately, so it still matches. -->
+      <url>regex:^/sql(/dashboard)?/?$</url>
       <methods>GET</methods>
       <handler>
         <type>static</type>

src/core/auth-handoff.js

@@ -0,0 +1,54 @@
+// Pure helpers for the one-time cross-tab auth handoff (#149 D1). No DOM.
+//
+// "Open as dashboard" opens a new same-origin tab whose sessionStorage starts
+// empty. Rather than force a second sign-in, the opener grants its live
+// credentials once via postMessage: the child requests them, the opener replies
+// with a snapshot of its auth session keys, and the child restores them into its
+// own (per-tab) sessionStorage. Everything here is pure — the postMessage wiring
+// + origin/source checks live in the app controller (over injected window seams);
+// these are the message contract, the key set, and the origin/source predicates,
+// kept here so they are trivially 100% testable.
+
+/** The sessionStorage keys that carry a live auth session (OAuth or basic). */
+export const AUTH_SS_KEYS = [
+  'oauth_id_token', 'oauth_refresh_token', 'oauth_idp', 'oauth_origin',
+  'ch_basic_auth', 'ch_basic_user', 'ch_basic_origin',
+];
+
+/** postMessage `data.type` values for the handoff handshake. */
+export const AUTH_REQUEST = 'asb-auth-request';
+export const AUTH_GRANT = 'asb-auth-grant';
+
+/** Read the present auth keys out of a sessionStorage-like object. */
+export function snapshotAuth(ss) {
+  const snap = {};
+  for (const k of AUTH_SS_KEYS) {
+    const v = ss.getItem(k);
+    if (v != null) snap[k] = v;
+  }
+  return snap;
+}
+
+/** Write a snapshot's auth keys into a sessionStorage-like object. */
+export function restoreAuth(ss, snap) {
+  for (const k of AUTH_SS_KEYS) {
+    if (snap && snap[k] != null) ss.setItem(k, snap[k]);
+  }
+}
+
+/** Does a snapshot carry usable credentials (an OAuth token or basic creds)? */
+export function hasAuth(snap) {
+  return !!(snap && (snap.oauth_id_token || snap.ch_basic_auth));
+}
+
+/** A well-formed credential *request* from the expected origin + source window. */
+export function isAuthRequest(e, origin, source) {
+  return !!e && e.origin === origin && e.source === source
+    && !!e.data && e.data.type === AUTH_REQUEST;
+}
+
+/** A well-formed credential *grant* from the expected origin + source window. */
+export function isAuthGrant(e, origin, source) {
+  return !!e && e.origin === origin && e.source === source
+    && !!e.data && e.data.type === AUTH_GRANT;
+}

src/core/dashboard.js

@@ -0,0 +1,79 @@
+// Pure logic for the Dashboard view (#149). No DOM, no globals.
+//
+// A dashboard is "the favorited subset of the Library, rendered together" — no
+// new schema. This module holds the route helpers, the ClickHouse `FORMAT JSON`
+// → array-rows transform the chart layer expects, and the per-tile
+// classification (chart vs skip). KPI tiles (single-row) and non-chartable
+// favorites are skipped in D1 (KPIs arrive in D2); the render layer counts them
+// for the header's "N not shown" note.
+
+import { autoChart, chartCfgValid, cloneChartCfg, normalizeChartCfg } from './chart-data.js';
+import { detectSqlFormat } from './format.js';
+
+/** True on the standalone dashboard route (`/sql/dashboard`, trailing slash ok). */
+export function isDashboardRoute(pathname) {
+  return /\/sql\/dashboard\/?$/.test(pathname || '');
+}
+
+/**
+ * The SPA base path for config.json / OAuth resolution, independent of the
+ * dashboard sub-route: `/sql/dashboard` → `/sql` so `loadConfigDoc` fetches
+ * `/sql/config.json` (not the non-existent `/sql/dashboard/config.json`).
+ */
+export function configBase(pathname) {
+  return (pathname || '').replace(/\/dashboard\/?$/, '');
+}
+
+/**
+ * A favorite's SQL prepared for a one-shot tile fetch: strip a trailing `;` and
+ * append `FORMAT JSON` — unless the query already ends in its own trailing
+ * `FORMAT` clause (which we leave intact; a non-JSON format just errors the tile
+ * gracefully rather than being silently doubled). Trailing-FORMAT detection
+ * reuses `detectSqlFormat`, which correctly handles ClickHouse's
+ * `FORMAT x SETTINGS y` ordering.
+ */
+export function dashboardTileSql(sql) {
+  const trimmed = String(sql || '').replace(/;\s*$/, '').trimEnd();
+  return detectSqlFormat(trimmed) ? trimmed : trimmed + '\nFORMAT JSON';
+}
+
+/**
+ * Transform a ClickHouse `FORMAT JSON` response into the shape the chart layer
+ * wants: `columns` = `meta` ([{name,type}]), `rows` = array-of-arrays (row[i]
+ * by column position), plus a small footer meta ({rows, ms, bytes}).
+ */
+export function parseJsonResult(json) {
+  const columns = json.meta || [];
+  const data = json.data || [];
+  const rows = data.map((o) => columns.map((c) => o[c.name]));
+  const stats = json.statistics || {};
+  return {
+    columns,
+    rows,
+    meta: {
+      rows: json.rows != null ? json.rows : rows.length,
+      ms: stats.elapsed != null ? Math.round(stats.elapsed * 1000) : null,
+      bytes: stats.bytes_read != null ? stats.bytes_read : null,
+    },
+  };
+}
+
+/**
+ * Classify a favorite's result into a dashboard tile. In D1:
+ *   - 0 rows            → skip (empty)
+ *   - exactly 1 row     → skip (a KPI — rendered in D2)
+ *   - saved chart cfg valid for these columns → chart with that cfg
+ *   - else autoChart    → chart, or skip when nothing is plottable
+ * `savedChart` is the favorite's persisted `{cfg, key}` (or undefined). The
+ * returned cfg is a normalized clone — never an alias of the saved entry.
+ */
+export function classifyTile(columns, rows, savedChart) {
+  if (rows.length === 0) return { kind: 'skip', reason: 'empty' };
+  if (rows.length === 1) return { kind: 'skip', reason: 'kpi' };
+  const saved = savedChart && savedChart.cfg;
+  const cfg = chartCfgValid(saved, columns)
+    ? normalizeChartCfg(cloneChartCfg(saved))
+    : autoChart(columns);
+  if (!cfg) return { kind: 'skip', reason: 'nonChartable' };
+  return { kind: 'chart', cfg };
+}

src/main.js

@@ -11,11 +11,16 @@ import { handleKeydown } from './ui/shortcuts.js';
 import { exchangeCodeForTokens, bearerFromTokens } from './net/oauth.js';
 import { decodeShare } from './core/share.js';
 import { cloneChartCfg } from './core/chart-data.js';
+import { isDashboardRoute } from './core/dashboard.js';
 
 export async function bootstrap(app, env) {
   const loc = env.location;
   const ss = env.sessionStorage;
   const hist = env.history;
+  // The standalone dashboard route (#149) reuses this same bootstrap + app: it
+  // shares the OAuth-callback handling below, but renders the dashboard instead
+  // of the workbench and skips editor-only share-link seeding.
+  const dash = isDashboardRoute(loc.pathname);
   const u = new URL(loc.href);
   const code = u.searchParams.get('code');
   const stateParam = u.searchParams.get('state');
@@ -55,31 +60,40 @@ export async function bootstrap(app, env) {
   // A shared query (SQL + chart config) rides in the URL hash, which is lost
   // through the OAuth redirect (and we strip it below). Stash it in
   // sessionStorage so it survives the round-trip and restore it once we're back.
-  let shared = decodeShare(loc.hash);
-  if (shared.sql) ss.setItem('oauth_shared', JSON.stringify(shared));
-  else {
-    try { shared = JSON.parse(ss.getItem('oauth_shared') || 'null') || { sql: '', chart: null }; }
-    catch { shared = { sql: '', chart: null }; }
-  }
-  if (shared.sql) {
-    const t0 = app.state.tabs.value[0];
-    t0.sql = shared.sql;
-    t0.name = 'Shared query';
-    if (shared.chart && shared.chart.cfg) {
-      t0.chartCfg = cloneChartCfg(shared.chart.cfg);
-      t0.chartKey = shared.chart.key ?? null;
+  // The dashboard route has no editor tab to seed, so it skips this entirely.
+  if (!dash) {
+    let shared = decodeShare(loc.hash);
+    if (shared.sql) ss.setItem('oauth_shared', JSON.stringify(shared));
+    else {
+      try { shared = JSON.parse(ss.getItem('oauth_shared') || 'null') || { sql: '', chart: null }; }
+      catch { shared = { sql: '', chart: null }; }
+    }
+    if (shared.sql) {
+      const t0 = app.state.tabs.value[0];
+      t0.sql = shared.sql;
+      t0.name = 'Shared query';
+      if (shared.chart && shared.chart.cfg) {
+        t0.chartCfg = cloneChartCfg(shared.chart.cfg);
+        t0.chartKey = shared.chart.key ?? null;
+      }
+      hist.replaceState(null, '', loc.pathname + loc.search);
     }
-    hist.replaceState(null, '', loc.pathname + loc.search);
   }
 
+  // A freshly-opened dashboard tab is signed out (per-tab sessionStorage); try a
+  // one-time credential handoff from the opener before deciding what to render.
+  // A cold/bookmarked visit has no opener → falls through to the login screen,
+  // which after sign-in returns to /sql/dashboard and renders the dashboard.
+  if (dash && !app.isSignedIn()) await app.receiveAuthHandoff(env);
+
   if (app.isSignedIn()) {
     // Signed in either via a valid OAuth token or a restored basic session.
     ss.removeItem('oauth_shared'); // consumed
     // Resolve config first so the header shows the real CH identity (the
     // ch_auth=basic username, not the raw email claim) on first paint.
     // (ensureConfig is a no-op in basic mode.)
     await app.ensureConfig();
-    app.renderApp();
+    if (dash) app.renderDashboard(); else app.renderApp();
   } else {
     app.showLogin(callbackError);
   }
@@ -95,6 +109,7 @@ if (typeof document !== 'undefined' && !globalThis.__ASB_NO_AUTOSTART__) {
     sessionStorage: window.sessionStorage,
     history: window.history,
     fetch: window.fetch.bind(window),
+    opener: window.opener, // dashboard tab reads its opener for the auth handoff
   });
 }
 /* c8 ignore stop */

src/net/ch-client.js

@@ -84,6 +84,19 @@ export async function queryJson(ctx, sql, signal) {
   return resp.json();
 }
 
+/**
+ * Run a favorite's SQL for a read-only dashboard tile (#149): `FORMAT JSON` plus
+ * the `readonly=2` HTTP setting, so a favorite that happens to contain a write
+ * (INSERT / ALTER / DROP / …) is rejected server-side rather than executed when
+ * the dashboard opens or refreshes — level 2 still permits SELECT and
+ * query-level `SETTINGS`. Returns parsed JSON; throws CH's reason on error.
+ */
+export async function queryDashboardTile(ctx, sql, signal) {
+  const resp = await authedFetch(ctx, chUrl(ctx.origin, { format: 'JSON', extra: { readonly: 2 } }), sql, signal);
+  if (!resp.ok) throw new Error(parseExceptionText(await resp.text()));
+  return resp.json();
+}
+
 /**
  * Run a `system.tables`/`system.columns` query (`sqlBody`, without its FORMAT
  * clause) with data-lake-catalog visibility enabled, falling back to the plain

src/styles.css

@@ -1737,3 +1737,73 @@ table.res-table tbody tr:hover td.idx { background: var(--bg-hover); }
   /* Cell-detail drawer → full-width, non-resizable (its handle is hidden above). */
   .cd-panel { width: 100vw !important; min-width: 0; }
 }
+
+/* ── Dashboard (#149 D1) ───────────────────────────────────────────────────
+   The standalone /sql/dashboard page: sticky header + a responsive grid of
+   read-only chart tiles rendered from favorited Library queries. */
+.dash-header {
+  position: sticky; top: 0; z-index: 40; display: flex; align-items: center;
+  gap: 12px; padding: 11px 20px; background: var(--bg-header);
+  border-bottom: 1px solid var(--border); flex-wrap: wrap;
+}
+.dash-back {
+  display: inline-flex; align-items: center; gap: 6px; color: var(--fg-mute);
+  text-decoration: none; font-size: 12px; padding: 4px 9px; border-radius: 6px;
+  border: 1px solid var(--border);
+}
+.dash-back:hover { background: var(--bg-hover); color: var(--fg); }
+.dash-back svg { transform: scaleX(-1); }
+.dash-title { font-size: 16px; font-weight: 700; color: var(--fg); letter-spacing: -.01em; }
+.dash-chip {
+  display: inline-flex; align-items: center; gap: 5px; font-size: 11px;
+  color: var(--fg-mute); background: var(--bg-chip); padding: 3px 9px; border-radius: 20px;
+}
+.dash-fav { color: var(--accent); }
+.dash-src { font-family: var(--mono); }
+.dash-dot { width: 6px; height: 6px; border-radius: 6px; background: #22C55E; }
+.dash-skip { font-size: 11px; color: var(--fg-faint); }
+.dash-updated { font-size: 11px; color: var(--fg-faint); font-family: var(--mono); }
+.dash-btn {
+  display: inline-flex; align-items: center; gap: 6px; height: 30px; padding: 0 12px;
+  background: var(--bg-chip); color: var(--fg); border: 1px solid var(--border);
+  border-radius: 7px; font: 500 12px var(--ui); cursor: pointer;
+}
+.dash-btn:hover { background: var(--bg-hover); }
+.dash-btn:disabled { opacity: .55; cursor: default; }
+.dash-grid {
+  display: grid; gap: 14px; padding: 18px 20px 40px;
+  grid-template-columns: repeat(auto-fill, minmax(340px, 1fr));
+  max-width: 1560px; margin: 0 auto;
+}
+.dash-empty { padding: 60px 20px; text-align: center; color: var(--fg-mute); font-size: 13px; }
+.dash-tile {
+  display: flex; flex-direction: column; overflow: hidden; min-height: 300px;
+  background: var(--bg-side); border: 1px solid var(--border); border-radius: 10px;
+}
+.dash-tile-head {
+  padding: 11px 12px 9px; border-bottom: 1px solid var(--border-faint);
+}
+.dash-tile-name {
+  font-size: 13px; font-weight: 600; color: var(--fg);
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap; display: block;
+}
+.dash-tile-body { flex: 1; min-height: 0; padding: 6px 8px; display: flex; }
+.dash-tile-body > .chart-view { flex: 1; min-width: 0; }
+.dash-tile-load {
+  display: flex; align-items: center; gap: 8px; margin: auto;
+  color: var(--fg-faint); font-size: 12px;
+}
+.dash-tile-error {
+  margin: auto; padding: 12px; color: var(--error-fg); background: var(--error-bg);
+  border: 1px solid var(--error-bd); border-radius: 8px; font-size: 12px;
+  font-family: var(--mono); max-width: 90%;
+}
+.dash-tile-foot {
+  display: flex; align-items: center; gap: 12px; padding: 7px 12px;
+  border-top: 1px solid var(--border-faint); font-family: var(--mono);
+  font-size: 10.5px; color: var(--fg-faint);
+}
+@media (max-width: 640px) {
+  .dash-grid { grid-template-columns: 1fr; padding: 12px; }
+  .dash-header { padding: 10px 12px; gap: 8px; }
+}