refactor(sql): route-based views, load/error fidelity, shared history

- /sql is now a layout with real child routes: the landing at /sql and the
  editor at /sql/editor with seed/run/wizard search params — deep-linkable,
  back-button friendly, no sessionStorage view state
- SQLService fallback redirect moved to the layout so it covers the landing
- useSqlCatalogs tracks catalogs+tables+identity loading and exposes
  isError/refetch; the landing renders distinct loading and error states
  instead of flashing the empty-state onboarding, and only claims
  "Connected" after a successful load
- query history extracted to sql-history.ts (one key+schema for editor and
  landing, cluster-scoped when embedded); landing-initiated auto-runs go
  through the editor's run path so they're recorded
- landing rebuilt on registry Card/Spinner/Button primitives; shared
  previewSql helper; table-id keys; prettyMilliseconds timestamps
- catalog/identity/table queries get a long staleTime (invalidation stays
  the freshness trigger); wizard topic listing fetches only when the wizard
  opens; SqlEditorView pass-through inlined; dark-border remap defined once

Author: c-julin

frontend/src/components/pages/sql/sql-editor.test.tsx

@@ -9,10 +9,11 @@
  * by the Apache License, Version 2.0
  */
 
-import { fireEvent, render, screen } from '@testing-library/react';
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { createRef } from 'react';
 import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
 
-import { SqlEditor } from './sql-editor';
+import { SqlEditor, type SqlEditorHandle } from './sql-editor';
 
 // CodeMirror's layout/measure loop doesn't run in jsdom; the editor surface is
 // exercised manually/e2e.
@@ -99,4 +100,16 @@ describe('SqlEditor', () => {
     fireEvent.click(screen.getByRole('button', { name: 'History' }));
     expect(await screen.findByText('No queries yet')).toBeInTheDocument();
   });
+
+  test('imperative run() executes and records history like a user run', async () => {
+    const onRun = vi.fn();
+    const ref = createRef<SqlEditorHandle>();
+    render(<SqlEditor catalogs={[]} initialQuery="SELECT 1;" onRun={onRun} ref={ref} />);
+
+    act(() => ref.current?.run('SELECT 42;'));
+    expect(onRun).toHaveBeenCalledWith('SELECT 42;');
+
+    fireEvent.click(screen.getByRole('button', { name: 'History' }));
+    expect(await screen.findByText('SELECT 42;', { selector: 'span' })).toBeInTheDocument();
+  });
 });

frontend/src/components/pages/sql/sql-editor.tsx

@@ -38,14 +38,20 @@ import {
   useSyncExternalStore,
 } from 'react';
 import { isMacOS } from 'utils/platform';
-import { z } from 'zod';
 
+import { type HistoryEntry, loadHistory, pushHistory, saveHistory } from './sql-history';
 import type { Catalog, TableRef } from './sql-types';
 
 // Lets the workspace open a query in a new editor tab.
 export type SqlEditorHandle = {
   /** Open `sql` in a new tab named `name` (or "Query N") and focus it. */
   setQuery: (sql: string, name?: string) => void;
+  /**
+   * Execute `sql` through the editor's run path, so it is recorded in the
+   * query history exactly like a user-initiated run. Used by the workspace's
+   * auto-run entry from the landing page.
+   */
+  run: (sql: string) => void;
 };
 
 export type SqlEditorProps = {
@@ -57,41 +63,6 @@ export type SqlEditorProps = {
   initialQuery?: string;
 };
 
-const HISTORY_KEY = 'rp_sql_history_v1';
-
-const HistoryEntrySchema = z.object({ sql: z.string(), at: z.number() });
-
-type HistoryEntry = z.infer<typeof HistoryEntrySchema>;
-
-function loadHistory(): HistoryEntry[] {
-  if (typeof localStorage === 'undefined') {
-    return [];
-  }
-  try {
-    const raw: unknown = JSON.parse(localStorage.getItem(HISTORY_KEY) ?? '[]');
-    if (!Array.isArray(raw)) {
-      return [];
-    }
-    return raw.flatMap((entry) => {
-      const parsed = HistoryEntrySchema.safeParse(entry);
-      return parsed.success ? [parsed.data] : [];
-    });
-  } catch {
-    return [];
-  }
-}
-
-function saveHistory(list: HistoryEntry[]): void {
-  if (typeof localStorage === 'undefined') {
-    return;
-  }
-  try {
-    localStorage.setItem(HISTORY_KEY, JSON.stringify(list.slice(0, 40)));
-  } catch {
-    // best-effort; ignore quota/serialization failures
-  }
-}
-
 type Tab = { id: number; name: string; sql: string };
 
 const DEFAULT_QUERY =
@@ -342,6 +313,7 @@ export const SqlEditor = forwardRef<SqlEditorHandle, SqlEditorProps>(
     // Latest run callback, bound into the Cmd/Ctrl+Enter keymap (built once per
     // catalog/theme change, not per render).
     const runRef = useRef<() => void>(() => undefined);
+    const runTextRef = useRef<(text: string) => void>(() => undefined);
 
     const active = tabs.find((t) => t.id === activeId) ?? tabs[0];
 
@@ -354,6 +326,7 @@ export const SqlEditor = forwardRef<SqlEditorHandle, SqlEditorProps>(
           setActiveId(id);
           requestAnimationFrame(() => editorRef.current?.view?.focus());
         },
+        run: (sql: string) => runTextRef.current(sql),
       }),
       [nextTabId]
     );
@@ -367,12 +340,14 @@ export const SqlEditor = forwardRef<SqlEditorHandle, SqlEditorProps>(
       if (!trimmed) {
         return;
       }
-      const entry: HistoryEntry = { sql: trimmed, at: Date.now() };
-      const nh = [entry, ...history.filter((h) => h.sql !== entry.sql)].slice(0, 40);
+      const nh = pushHistory(history, trimmed, Date.now());
       setHistory(nh);
       saveHistory(nh);
       runQuery(trimmed);
     };
+    // Latest runText, so the imperative handle (built once) records history
+    // against the current state instead of a stale closure.
+    runTextRef.current = runText;
 
     // Run the current selection if any, else the whole tab.
     const doRun = () => {

frontend/src/components/pages/sql/sql-history.test.ts

@@ -0,0 +1,91 @@
+/**
+ * Copyright 2026 Redpanda Data, Inc.
+ *
+ * Use of this software is governed by the Business Source License
+ * included in the file https://github.com/redpanda-data/redpanda/blob/dev/licenses/bsl.md
+ *
+ * As of the Change Date specified in that file, in accordance with
+ * the Business Source License, use of this software will be governed
+ * by the Apache License, Version 2.0
+ */
+
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { type HistoryEntry, loadHistory, MAX_HISTORY, pushHistory, saveHistory } from './sql-history';
+
+const HISTORY_KEY = 'rp_sql_history_v1';
+
+function createMemoryStorage(): Storage {
+  const values = new Map<string, string>();
+  return {
+    get length() {
+      return values.size;
+    },
+    clear: () => values.clear(),
+    getItem: (key: string) => values.get(key) ?? null,
+    key: (index: number) => [...values.keys()][index] ?? null,
+    removeItem: (key: string) => values.delete(key),
+    setItem: (key: string, value: string) => values.set(key, value),
+  };
+}
+
+beforeEach(() => {
+  vi.stubGlobal('localStorage', createMemoryStorage());
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('pushHistory', () => {
+  test('prepends the newest entry', () => {
+    const list = pushHistory([{ sql: 'SELECT 1', at: 1 }], 'SELECT 2', 2);
+    expect(list.map((entry) => entry.sql)).toEqual(['SELECT 2', 'SELECT 1']);
+  });
+
+  test('dedupes an identical earlier run instead of listing it twice', () => {
+    const list = pushHistory(
+      [
+        { sql: 'SELECT 1', at: 1 },
+        { sql: 'SELECT 2', at: 2 },
+      ],
+      'SELECT 1',
+      3
+    );
+    expect(list).toEqual([
+      { sql: 'SELECT 1', at: 3 },
+      { sql: 'SELECT 2', at: 2 },
+    ]);
+  });
+
+  test('caps the list length', () => {
+    let list: HistoryEntry[] = [];
+    for (let i = 0; i < MAX_HISTORY + 10; i += 1) {
+      list = pushHistory(list, `SELECT ${i}`, i);
+    }
+    expect(list).toHaveLength(MAX_HISTORY);
+    expect(list[0].sql).toBe(`SELECT ${MAX_HISTORY + 9}`);
+  });
+});
+
+describe('loadHistory / saveHistory', () => {
+  test('round-trips entries through localStorage', () => {
+    saveHistory([{ sql: 'SELECT 1', at: 42 }]);
+    expect(loadHistory()).toEqual([{ sql: 'SELECT 1', at: 42 }]);
+  });
+
+  test('drops malformed entries but keeps valid ones', () => {
+    localStorage.setItem(HISTORY_KEY, JSON.stringify([{ sql: 'SELECT 1', at: 1 }, { sql: 7 }, 'nope', null]));
+    expect(loadHistory()).toEqual([{ sql: 'SELECT 1', at: 1 }]);
+  });
+
+  test('returns empty for a non-array value', () => {
+    localStorage.setItem(HISTORY_KEY, JSON.stringify({ not: 'a list' }));
+    expect(loadHistory()).toEqual([]);
+  });
+
+  test('returns empty for invalid JSON', () => {
+    localStorage.setItem(HISTORY_KEY, '{broken');
+    expect(loadHistory()).toEqual([]);
+  });
+});

frontend/src/components/pages/sql/sql-history.ts

@@ -0,0 +1,70 @@
+/**
+ * Copyright 2026 Redpanda Data, Inc.
+ *
+ * Use of this software is governed by the Business Source License
+ * included in the file https://github.com/redpanda-data/redpanda/blob/dev/licenses/bsl.md
+ *
+ * As of the Change Date specified in that file, in accordance with
+ * the Business Source License, use of this software will be governed
+ * by the Apache License, Version 2.0
+ */
+
+import { config, isEmbedded } from 'config';
+import { z } from 'zod';
+
+// The single source of truth for the SQL query-run history persisted in
+// localStorage. Written by the editor on every run and read back by both the
+// editor's History popover and the landing page's "Recent queries" card —
+// shared here so the key and entry shape can't drift between the two.
+
+export const HistoryEntrySchema = z.object({ sql: z.string(), at: z.number() });
+
+export type HistoryEntry = z.infer<typeof HistoryEntrySchema>;
+
+export const MAX_HISTORY = 40;
+
+// Tolerates individually malformed entries: keeps the valid ones, drops the rest.
+const StoredHistorySchema = z.array(z.unknown()).transform((list) =>
+  list.flatMap((entry) => {
+    const parsed = HistoryEntrySchema.safeParse(entry);
+    return parsed.success ? [parsed.data] : [];
+  })
+);
+
+const HISTORY_KEY_BASE = 'rp_sql_history_v1';
+
+// localStorage is origin-scoped, and embedded Console serves every cluster
+// from the same Cloud UI origin — an unscoped key would surface cluster A's
+// queries as one-click runs on cluster B. Standalone serves one cluster per
+// origin, so the bare key suffices there.
+function historyKey(): string {
+  return isEmbedded() ? `${HISTORY_KEY_BASE}:${config.clusterId ?? 'default'}` : HISTORY_KEY_BASE;
+}
+
+// Kept defensive so a malformed or truncated stored value never throws.
+export function loadHistory(): HistoryEntry[] {
+  if (typeof localStorage === 'undefined') {
+    return [];
+  }
+  try {
+    return StoredHistorySchema.catch([]).parse(JSON.parse(localStorage.getItem(historyKey()) ?? '[]'));
+  } catch {
+    return [];
+  }
+}
+
+export function saveHistory(list: HistoryEntry[]): void {
+  if (typeof localStorage === 'undefined') {
+    return;
+  }
+  try {
+    localStorage.setItem(historyKey(), JSON.stringify(list.slice(0, MAX_HISTORY)));
+  } catch {
+    // best-effort; ignore quota/serialization failures
+  }
+}
+
+/** Prepend `sql` to `list`, deduping an identical earlier run and capping the length. */
+export function pushHistory(list: HistoryEntry[], sql: string, at: number): HistoryEntry[] {
+  return [{ sql, at }, ...list.filter((entry) => entry.sql !== sql)].slice(0, MAX_HISTORY);
+}

frontend/src/components/pages/sql/sql-landing.test.tsx

@@ -58,19 +58,22 @@ function renderLanding(overrides: Partial<SqlLandingProps> = {}) {
   const onRunQuery = vi.fn();
   const onOpenEditor = vi.fn();
   const onAddTopic = vi.fn();
+  const onRetry = vi.fn();
   render(
     <SqlLanding
       catalogs={catalogs}
       hasTables={true}
+      isError={false}
       isLoading={false}
       onAddTopic={onAddTopic}
       onOpenEditor={onOpenEditor}
+      onRetry={onRetry}
       onRunQuery={onRunQuery}
       sqlRole="admin"
       {...overrides}
     />
   );
-  return { onAddTopic, onOpenEditor, onRunQuery };
+  return { onAddTopic, onOpenEditor, onRetry, onRunQuery };
 }
 
 afterEach(() => {
@@ -106,6 +109,24 @@ describe('SqlLanding populated overview', () => {
   });
 });
 
+describe('SqlLanding loading and error states', () => {
+  test('a load in flight shows the loading row, not the empty-state onboarding', () => {
+    renderLanding({ isLoading: true, catalogs: [], hasTables: false });
+    expect(screen.getByText('Loading catalogs…')).toBeInTheDocument();
+    expect(screen.queryByText('No tables yet')).toBeNull();
+    expect(screen.queryByText(/Connected/)).toBeNull();
+  });
+
+  test('a failed catalog load shows the error state with retry, not the empty state', async () => {
+    const { onRetry } = renderLanding({ isError: true, catalogs: [], hasTables: false });
+    expect(screen.getByText("Couldn't load the SQL catalog")).toBeInTheDocument();
+    expect(screen.queryByText('No tables yet')).toBeNull();
+    expect(screen.queryByText(/Connected/)).toBeNull();
+    await userEvent.click(screen.getByRole('button', { name: /Retry/ }));
+    expect(onRetry).toHaveBeenCalledOnce();
+  });
+});
+
 describe('SqlLanding onboarding (empty catalog)', () => {
   test('admin sees the add-topic CTA', async () => {
     const { onAddTopic } = renderLanding({ hasTables: false, catalogs: [] });