Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

chore: init theme design (#20563)

ecmadao5b87cc4057f0
diff --git a/docs/superpowers/plans/2026-06-09-sql-editor-theme-pattern.md b/docs/superpowers/plans/2026-06-09-sql-editor-theme-pattern.md
new file mode 100644
index 0000000000..706fc7aed6
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-09-sql-editor-theme-pattern.md
@@ -0,0 +1,1913 @@
+# SQL Editor Theme Pattern Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Extract the SQL Editor's colors into a data-driven theme model and add a runtime preset switcher (6 themes) scoped to the SQL Editor, compatible with admin/terminal mode.
+
+**Architecture:** A theme is one plain object (`tokens` chrome layer + `editor`/`syntax` Monaco layer). Chrome is themed per-scope by writing the `tokens` as inline `--color-*` CSS vars on a `<SQLEditorThemeScope>` container (CSS cascade re-themes Tailwind classes). Monaco — whose theme is necessarily global — is driven by a single controller off the foreground panel. Admin mode is a nested scope whose theme is `selected.isDark ? selected : dark`. Selection persists in localStorage.
+
+**Tech Stack:** React, Zustand (+ immer), Tailwind v4 CSS-variable utilities, Base UI `Select`, monaco-editor, Vitest + Testing Library.
+
+**Spec:** `docs/superpowers/specs/2026-06-09-sql-editor-theme-pattern-design.md`
+
+**Phasing / handoff value:**
+- **Phase 1–3** deliver a working theme switch for the editor chrome + Monaco surface (the named-theme look lands, though some hardcoded islands still show until Phase 5).
+- **Phase 4** wires scopes (root, admin, portals) so admin mode and portaled surfaces theme correctly.
+- **Phase 5** removes hardcoded colors so every surface follows the theme.
+- **Phase 6** adds the user-facing switcher. **Phase 7** verifies.
+
+---
+
+## File Structure
+
+New (theme module under the SQL Editor React tree):
+- `frontend/src/react/components/sql-editor/theme/types.ts` — `SQLEditorTheme` + supporting types.
+- `frontend/src/react/components/sql-editor/theme/derive.ts` — `themeToCssVars`, `buildMonacoTheme`, `monacoThemeName`, `resolveAdminTheme`, `validateTheme`.
+- `frontend/src/react/components/sql-editor/theme/derive.test.ts`
+- `frontend/src/react/components/sql-editor/theme/presets/{light,dark,solarized-light,solarized-dark,monokai,nord}.ts`
+- `frontend/src/react/components/sql-editor/theme/presets/index.ts` — `PRESETS`, `PRESET_BY_ID`, `DEFAULT_THEME_ID`.
+- `frontend/src/react/components/sql-editor/theme/presets/presets.test.ts`
+- `frontend/src/react/components/sql-editor/theme/SQLEditorThemeScope.tsx` — context + scope component + `useSQLEditorTheme`.
+- `frontend/src/react/components/sql-editor/theme/SQLEditorThemeScope.test.tsx`
+- `frontend/src/react/components/sql-editor/theme/useMonacoThemeController.ts` — global Monaco theme controller.
+- `frontend/src/react/components/sql-editor/ThemeSelect.tsx` — switcher.
+
+Modified:
+- `frontend/src/utils/storage-keys.ts` — add `storageKeySqlEditorTheme`.
+- `frontend/src/react/stores/sqlEditor/editor.ts` (+ `editor.test.ts`) — `themeId` + `setThemeId`.
+- `frontend/src/react/components/monaco/core.ts` — register the 6 generated themes.
+- `frontend/src/react/components/monaco/themes/{bb,bb-dark}.ts` — deleted (superseded by generated themes).
+- `frontend/src/react/components/sql-editor/SQLEditorLayout.tsx` — root scope + Monaco controller mount.
+- `frontend/src/react/components/sql-editor/TerminalPanel/TerminalPanel.tsx` — nested admin scope, `bg-dark-bg`→token.
+- `frontend/src/react/components/sql-editor/TerminalPanel/CompactSQLEditor.tsx` — drop hardcoded `vs-dark`.
+- `frontend/src/react/components/sql-editor/ResultView/ResultView.tsx` — drop `dark` prop.
+- Result-view + standard-mode components — hardcoded color migration (Phase 5, exact list).
+- `frontend/src/react/components/sql-editor/SQLEditorHomePage.tsx` — portal scopes.
+- `frontend/src/react/components/sql-editor/RequestDrawerHost.tsx` / `AccessGrantRequestDrawer.tsx` — drawer chrome scope.
+- `frontend/src/react/components/sql-editor/EditorAction.tsx` — mount `ThemeSelect`.
+- `frontend/src/locales/{en-US,zh-CN,ja-JP,es-ES,vi-VN}.json` — i18n key.
+
+**Commands** (run from repo root):
+- Test one file: `pnpm --dir frontend test -- run src/react/components/sql-editor/theme/derive.test.ts`
+- Test all: `pnpm --dir frontend test`
+- Lint/format/imports: `pnpm --dir frontend fix`
+- Type check: `pnpm --dir frontend type-check`
+
+---
+
+## Phase 1 — Theme model foundation
+
+### Task 1: Theme types
+
+**Files:**
+- Create: `frontend/src/react/components/sql-editor/theme/types.ts`
+
+- [ ] **Step 1: Write the types**
+
+```ts
+// frontend/src/react/components/sql-editor/theme/types.ts
+
+// Chrome tokens are "r g b" triples (Tailwind utilities resolve to
+// `rgb(var(--color-x) / <alpha>)`). Monaco values are "#rrggbb" hex.
+export type RGB = string;
+export type Hex = string;
+
+// The SQL-Editor subset of the existing --color-* names. Every preset MUST
+// fill all of these (enforced by validateTheme).
+export type SQLEditorThemeToken =
+ | "--color-control"
+ | "--color-control-hover"
+ | "--color-control-light"
+ | "--color-control-light-hover"
+ | "--color-control-bg"
+ | "--color-control-bg-hover"
+ | "--color-control-placeholder"
+ | "--color-control-border"
+ | "--color-accent"
+ | "--color-accent-hover"
+ | "--color-accent-disabled"
+ | "--color-accent-text"
+ | "--color-main"
+ | "--color-main-hover"
+ | "--color-main-text"
+ | "--color-background"
+ | "--color-block-border"
+ | "--color-link-hover"
+ | "--color-info"
+ | "--color-info-hover"
+ | "--color-warning"
+ | "--color-warning-hover"
+ | "--color-error"
+ | "--color-error-hover"
+ | "--color-success"
+ | "--color-success-hover"
+ | "--color-matrix-green"
+ | "--color-matrix-green-hover"
+ | "--color-dark-bg";
+
+// Monaco editor-surface colors (canvas — unreachable by CSS cascade).
+export interface EditorChromeColors {
+ background: Hex;
+ selectionBackground: Hex;
+ cursor: Hex;
+ lineHighlight: Hex;
+ gutterBackground: Hex;
+ lineNumber: Hex;
+ activeLineNumber: Hex;
+}
+
+// Normalized, language-agnostic syntax palette. buildMonacoTheme maps these
+// onto Monaco token rules (incl. SQL scopes).
+export interface SyntaxPalette {
+ comment: Hex;
+ keyword: Hex;
+ string: Hex;
+ number: Hex;
+ type: Hex;
+ function: Hex;
+ variable: Hex;
+ operator: Hex;
+ delimiter: Hex;
+ predefined: Hex;
+}
+
+export interface SQLEditorTheme {
+ id: string;
+ // i18n key for the display label (built-in palette proper nouns may be literal).
+ name: string;
+ isDark: boolean;
+ monacoBase: "vs" | "vs-dark";
+ tokens: Record<SQLEditorThemeToken, RGB>;
+ editor: EditorChromeColors;
+ syntax: SyntaxPalette;
+}
+
+// All chrome token names, for iteration/validation.
+export const SQL_EDITOR_THEME_TOKENS: SQLEditorThemeToken[] = [
+ "--color-control",
+ "--color-control-hover",
+ "--color-control-light",
+ "--color-control-light-hover",
+ "--color-control-bg",
+ "--color-control-bg-hover",
+ "--color-control-placeholder",
+ "--color-control-border",
+ "--color-accent",
+ "--color-accent-hover",
+ "--color-accent-disabled",
+ "--color-accent-text",
+ "--color-main",
+ "--color-main-hover",
+ "--color-main-text",
+ "--color-background",
+ "--color-block-border",
+ "--color-link-hover",
+ "--color-info",
+ "--color-info-hover",
+ "--color-warning",
+ "--color-warning-hover",
+ "--color-error",
+ "--color-error-hover",
+ "--color-success",
+ "--color-success-hover",
+ "--color-matrix-green",
+ "--color-matrix-green-hover",
+ "--color-dark-bg",
+];
+```
+
+- [ ] **Step 2: Type-check**
+
+Run: `pnpm --dir frontend type-check`
+Expected: PASS (no references yet; file compiles).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add frontend/src/react/components/sql-editor/theme/types.ts
+git commit -m "feat(sql-editor): add theme model types"
+```
+
+---
+
+### Task 2: Derivation functions (TDD)
+
+**Files:**
+- Create: `frontend/src/react/components/sql-editor/theme/derive.ts`
+- Test: `frontend/src/react/components/sql-editor/theme/derive.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+```ts
+// frontend/src/react/components/sql-editor/theme/derive.test.ts
+import { describe, expect, test } from "vitest";
+import {
+ buildMonacoTheme,
+ monacoThemeName,
+ resolveAdminTheme,
+ themeToCssVars,
+ validateTheme,
+} from "./derive";
+import type { SQLEditorTheme } from "./types";
+import { SQL_EDITOR_THEME_TOKENS } from "./types";
+
+// Minimal complete fixture (values arbitrary but every key present).
+const fixture = (over: Partial<SQLEditorTheme> = {}): SQLEditorTheme => {
+ const tokens = Object.fromEntries(
+ SQL_EDITOR_THEME_TOKENS.map((k) => [k, "1 2 3"])
+ ) as SQLEditorTheme["tokens"];
+ return {
+ id: "fixture",
+ name: "Fixture",
+ isDark: false,
+ monacoBase: "vs",
+ tokens,
+ editor: {
+ background: "#ffffff",
+ selectionBackground: "#cccccc",
+ cursor: "#000000",
+ lineHighlight: "#eeeeee",
+ gutterBackground: "#ffffff",
+ lineNumber: "#999999",
+ activeLineNumber: "#111111",
+ },
+ syntax: {
+ comment: "#777777",
+ keyword: "#0000ff",
+ string: "#008000",
+ number: "#098658",
+ type: "#267f99",
+ function: "#795e26",
+ variable: "#001080",
+ operator: "#000000",
+ delimiter: "#000000",
+ predefined: "#0000ff",
+ },
+ ...over,
+ };
+};
+
+describe("themeToCssVars", () => {
+ test("maps every chrome token to a --color-* CSS property", () => {
+ const vars = themeToCssVars(fixture().tokens);
+ expect(vars["--color-control"]).toBe("1 2 3");
+ expect(Object.keys(vars)).toHaveLength(SQL_EDITOR_THEME_TOKENS.length);
+ });
+});
+
+describe("monacoThemeName", () => {
+ test("prefixes the theme id", () => {
+ expect(monacoThemeName(fixture({ id: "monokai" }))).toBe("bb-monokai");
+ });
+});
+
+describe("buildMonacoTheme", () => {
+ test("maps editor colors and syntax onto Monaco theme data", () => {
+ const data = buildMonacoTheme(fixture({ monacoBase: "vs-dark" }));
+ expect(data.base).toBe("vs-dark");
+ expect(data.inherit).toBe(true);
+ expect(data.colors["editor.background"]).toBe("#ffffff");
+ expect(data.colors["editor.selectionBackground"]).toBe("#cccccc");
+ expect(data.colors["editorCursor.foreground"]).toBe("#000000");
+ // syntax → rules; keyword present without the leading "#".
+ const keyword = data.rules.find((r) => r.token === "keyword");
+ expect(keyword?.foreground).toBe("0000ff");
+ });
+});
+
+describe("resolveAdminTheme", () => {
+ test("keeps a dark selected theme", () => {
+ const dark = fixture({ id: "monokai", isDark: true });
+ expect(resolveAdminTheme(dark).id).toBe("monokai");
+ });
+ test("falls back to the dark preset for a light selected theme", () => {
+ const light = fixture({ id: "light", isDark: false });
+ expect(resolveAdminTheme(light).id).toBe("dark");
+ });
+});
+
+describe("validateTheme", () => {
+ test("passes a complete theme", () => {
+ expect(() => validateTheme(fixture())).not.toThrow();
+ });
+ test("throws when a chrome token is missing", () => {
+ const bad = fixture();
+ // @ts-expect-error intentionally drop a token
+ delete bad.tokens["--color-accent"];
+ expect(() => validateTheme(bad)).toThrow(/--color-accent/);
+ });
+ test("throws when a syntax key is missing", () => {
+ const bad = fixture();
+ // @ts-expect-error intentionally drop a syntax key
+ delete bad.syntax.keyword;
+ expect(() => validateTheme(bad)).toThrow(/keyword/);
+ });
+});
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `pnpm --dir frontend test -- run src/react/components/sql-editor/theme/derive.test.ts`
+Expected: FAIL — `derive.ts` does not exist / functions undefined.
+
+- [ ] **Step 3: Write the implementation**
+
+```ts
+// frontend/src/react/components/sql-editor/theme/derive.ts
+import type { CSSProperties } from "react";
+import type { editor as Editor } from "monaco-editor";
+import { PRESET_BY_ID } from "./presets";
+import type {
+ EditorChromeColors,
+ SQLEditorTheme,
+ SyntaxPalette,
+} from "./types";
+import { SQL_EDITOR_THEME_TOKENS } from "./types";
+
+// Monaco wants hex without the leading "#" in rule foregrounds.
+const bare = (hex: string): string => hex.replace(/^#/, "");
+
+/** Chrome: tokens → inline CSS custom properties for a container's `style`. */
+export function themeToCssVars(
+ tokens: SQLEditorTheme["tokens"]
+): CSSProperties {
+ const vars: Record<string, string> = {};
+ for (const token of SQL_EDITOR_THEME_TOKENS) {
+ vars[token] = tokens[token];
+ }
+ return vars as CSSProperties;
+}
+
+/** Monaco theme name registered via defineTheme + used by setTheme. */
+export function monacoThemeName(theme: SQLEditorTheme): string {
+ return `bb-${theme.id}`;
+}
+
+// Map the normalized syntax palette onto Monaco token scopes. SQL is the
+// primary language; the generic scopes cover other languages Monaco loads.
+const syntaxRules = (s: SyntaxPalette): Editor.ITokenThemeRule[] => {
+ const rule = (token: string, hex: string): Editor.ITokenThemeRule => ({
+ token,
+ foreground: bare(hex),
+ });
+ return [
+ rule("comment", s.comment),
+ rule("keyword", s.keyword),
+ rule("keyword.sql", s.keyword),
+ rule("string", s.string),
+ rule("string.sql", s.string),
+ rule("number", s.number),
+ rule("number.sql", s.number),
+ rule("type", s.type),
+ rule("type.sql", s.type),
+ rule("identifier", s.variable),
+ rule("predefined", s.predefined),
+ rule("predefined.sql", s.predefined),
+ rule("operator", s.operator),
+ rule("operator.sql", s.operator),
+ rule("delimiter", s.delimiter),
+ ];
+};
+
+const editorColors = (e: EditorChromeColors): Editor.IColors => ({
+ "editor.background": e.background,
+ "editor.selectionBackground": e.selectionBackground,
+ "editorCursor.foreground": e.cursor,
+ "editor.lineHighlightBackground": e.lineHighlight,
+ "editorGutter.background": e.gutterBackground,
+ "editorLineNumber.foreground": e.lineNumber,
+ "editorLineNumber.activeForeground": e.activeLineNumber,
+ // Keep the existing "no word highlight box" behavior from bb/bb-dark.
+ "editor.wordHighlightBackground": "#00000000",
+ "editor.wordHighlightStrongBackground": "#00000000",
+});
+
+/** Monaco: whole theme → registered standalone theme data. */
+export function buildMonacoTheme(
+ theme: SQLEditorTheme
+): Editor.IStandaloneThemeData {
+ return {
+ base: theme.monacoBase,
+ inherit: true,
+ rules: syntaxRules(theme.syntax),
+ colors: editorColors(theme.editor),
+ };
+}
+
+/** Admin foreground resolution: keep dark themes, else fall back to dark. */
+export function resolveAdminTheme(selected: SQLEditorTheme): SQLEditorTheme {
+ return selected.isDark ? selected : PRESET_BY_ID.dark;
+}
+
+/** Throws if any chrome token / editor key / syntax key is missing. */
+export function validateTheme(theme: SQLEditorTheme): void {
+ for (const token of SQL_EDITOR_THEME_TOKENS) {
+ if (typeof theme.tokens[token] !== "string") {
+ throw new Error(`theme "${theme.id}" missing chrome token ${token}`);
+ }
+ }
+ const editorKeys: (keyof EditorChromeColors)[] = [
+ "background",
+ "selectionBackground",
+ "cursor",
+ "lineHighlight",
+ "gutterBackground",
+ "lineNumber",
+ "activeLineNumber",
+ ];
+ for (const key of editorKeys) {
+ if (typeof theme.editor[key] !== "string") {
+ throw new Error(`theme "${theme.id}" missing editor.${key}`);
+ }
+ }
+ const syntaxKeys: (keyof SyntaxPalette)[] = [
+ "comment",
+ "keyword",
+ "string",
+ "number",
+ "type",
+ "function",
+ "variable",
+ "operator",
+ "delimiter",
+ "predefined",
+ ];
+ for (const key of syntaxKeys) {
+ if (typeof theme.syntax[key] !== "string") {
+ throw new Error(`theme "${theme.id}" missing syntax.${key}`);
+ }
+ }
+}
+```
+
+> Note: `derive.ts` imports `PRESET_BY_ID` from `./presets` (Task 3). The
+> `derive.test.ts` above does not, so it passes before presets exist **only if**
+> the import resolves. To keep Task 2 self-contained, create a temporary stub
+> `presets/index.ts` now: `export const PRESET_BY_ID = {} as Record<string, never>;`
+> — Task 3 replaces it. (Alternatively do Task 2 + Task 3 together.)
+
+- [ ] **Step 4: Add the temporary presets stub**
+
+```ts
+// frontend/src/react/components/sql-editor/theme/presets/index.ts (temporary)
+import type { SQLEditorTheme } from "../types";
+export const PRESET_BY_ID: Record<string, SQLEditorTheme> = {};
+```
+
+- [ ] **Step 5: Run the test to verify it passes**
+
+Run: `pnpm --dir frontend test -- run src/react/components/sql-editor/theme/derive.test.ts`
+Expected: PASS (all `describe` blocks green). `resolveAdminTheme` light-fallback test exercises `PRESET_BY_ID.dark`, which is `undefined` in the stub — its `.id` read throws. **Therefore include a local mock in the test** by re-importing: instead, the light-fallback assertion must run after Task 3. Mark that one test `test.skip` here and un-skip in Task 3 Step 4.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add frontend/src/react/components/sql-editor/theme/derive.ts frontend/src/react/components/sql-editor/theme/derive.test.ts frontend/src/react/components/sql-editor/theme/presets/index.ts
+git commit -m "feat(sql-editor): add theme derivation functions"
+```
+
+---
+
+### Task 3: Default presets (light, dark) + catalog
+
+**Files:**
+- Create: `frontend/src/react/components/sql-editor/theme/presets/light.ts`, `dark.ts`
+- Replace: `frontend/src/react/components/sql-editor/theme/presets/index.ts`
+- Test: `frontend/src/react/components/sql-editor/theme/presets/presets.test.ts`
+
+- [ ] **Step 1: Write the `light` preset (values verbatim from `:root` in `tailwind.css`)**
+
+```ts
+// frontend/src/react/components/sql-editor/theme/presets/light.ts
+import type { SQLEditorTheme } from "../types";
+
+// Chrome tokens copied verbatim from :root (frontend/src/assets/css/tailwind.css)
+// so "Default Light" renders byte-for-byte identical to today.
+export const light: SQLEditorTheme = {
+ id: "light",
+ name: "sql-editor.theme.light",
+ isDark: false,
+ monacoBase: "vs",
+ tokens: {
+ "--color-control": "82 82 91",
+ "--color-control-hover": "24 24 27",
+ "--color-control-light": "113 113 122",
+ "--color-control-light-hover": "82 82 91",
+ "--color-control-bg": "243 244 246",
+ "--color-control-bg-hover": "229 231 235",
+ "--color-control-placeholder": "161 161 170",
+ "--color-control-border": "209 213 219",
+ "--color-accent": "79 70 229",
+ "--color-accent-hover": "55 48 163",
+ "--color-accent-disabled": "165 180 252",
+ "--color-accent-text": "255 255 255",
+ "--color-main": "24 24 27",
+ "--color-main-hover": "63 63 70",
+ "--color-main-text": "255 255 255",
+ "--color-background": "255 255 255",
+ "--color-block-border": "229 231 235",
+ "--color-link-hover": "229 231 235",
+ "--color-info": "37 99 235",
+ "--color-info-hover": "29 78 216",
+ "--color-warning": "245 158 11",
+ "--color-warning-hover": "180 83 9",
+ "--color-error": "220 38 38",
+ "--color-error-hover": "185 28 28",
+ "--color-success": "22 163 74",
+ "--color-success-hover": "21 128 61",
+ "--color-matrix-green": "0 204 0",
+ "--color-matrix-green-hover": "136 255 136",
+ "--color-dark-bg": "30 30 30",
+ },
+ // Reproduces the old `bb` Monaco theme (transparent bg, accent cursor).
+ editor: {
+ background: "#ffffff",
+ selectionBackground: "#add6ff",
+ cursor: "#4f46e5",
+ lineHighlight: "#f3f4f6",
+ gutterBackground: "#ffffff",
+ lineNumber: "#a1a1aa",
+ activeLineNumber: "#18181b",
+ },
+ // VS light defaults (inherited from base "vs"; listed for completeness).
+ syntax: {
+ comment: "#008000",
+ keyword: "#0000ff",
+ string: "#a31515",
+ number: "#098658",
+ type: "#267f99",
+ function: "#795e26",
+ variable: "#001080",
+ operator: "#000000",
+ delimiter: "#000000",
+ predefined: "#0000ff",
+ },
+};
+```
+
+- [ ] **Step 2: Write the `dark` preset (Default Dark — spec §2 starting values)**
+
+```ts
+// frontend/src/react/components/sql-editor/theme/presets/dark.ts
+import type { SQLEditorTheme } from "../types";
+
+export const dark: SQLEditorTheme = {
+ id: "dark",
+ name: "sql-editor.theme.dark",
+ isDark: true,
+ monacoBase: "vs-dark",
+ tokens: {
+ "--color-control": "229 231 235",
+ "--color-control-hover": "243 244 246",
+ "--color-control-light": "209 213 219",
+ "--color-control-light-hover": "229 231 235",
+ "--color-control-bg": "55 65 81",
+ "--color-control-bg-hover": "75 85 99",
+ "--color-control-placeholder": "156 163 175",
+ "--color-control-border": "113 113 122",
+ "--color-accent": "129 140 248",
+ "--color-accent-hover": "165 180 252",
+ "--color-accent-disabled": "67 56 202",
+ "--color-accent-text": "255 255 255",
+ "--color-main": "244 244 245",
+ "--color-main-hover": "212 212 216",
+ "--color-main-text": "24 24 27",
+ "--color-background": "30 30 30",
+ "--color-block-border": "82 82 91",
+ "--color-link-hover": "63 63 70",
+ "--color-info": "96 165 250",
+ "--color-info-hover": "147 197 253",
+ "--color-warning": "251 191 36",
+ "--color-warning-hover": "253 224 71",
+ "--color-error": "248 113 113",
+ "--color-error-hover": "252 165 165",
+ "--color-success": "74 222 128",
+ "--color-success-hover": "134 239 172",
+ "--color-matrix-green": "0 204 0",
+ "--color-matrix-green-hover": "136 255 136",
+ "--color-dark-bg": "30 30 30",
+ },
+ editor: {
+ background: "#1e1e1e",
+ selectionBackground: "#264f78",
+ cursor: "#818cf8",
+ lineHighlight: "#2a2a2a",
+ gutterBackground: "#1e1e1e",
+ lineNumber: "#858585",
+ activeLineNumber: "#c6c6c6",
+ },
+ // VS dark defaults.
+ syntax: {
+ comment: "#6a9955",
+ keyword: "#569cd6",
+ string: "#ce9178",
+ number: "#b5cea8",
+ type: "#4ec9b0",
+ function: "#dcdcaa",
+ variable: "#9cdcfe",
+ operator: "#d4d4d4",
+ delimiter: "#d4d4d4",
+ predefined: "#569cd6",
+ },
+};
+```
+
+- [ ] **Step 3: Replace the catalog index**
+
+```ts
+// frontend/src/react/components/sql-editor/theme/presets/index.ts
+import type { SQLEditorTheme } from "../types";
+import { dark } from "./dark";
+import { light } from "./light";
+import { monokai } from "./monokai";
+import { nord } from "./nord";
+import { solarizedDark } from "./solarized-dark";
+import { solarizedLight } from "./solarized-light";
+
+// Display order in the switcher.
+export const PRESETS: SQLEditorTheme[] = [
+ light,
+ dark,
+ solarizedLight,
+ solarizedDark,
+ monokai,
+ nord,
+];
+
+export const PRESET_BY_ID: Record<string, SQLEditorTheme> = Object.fromEntries(
+ PRESETS.map((p) => [p.id, p])
+);
+
+export const DEFAULT_THEME_ID = "light";
+
+export const resolveThemeId = (id: string | undefined): SQLEditorTheme =>
+ (id && PRESET_BY_ID[id]) || PRESET_BY_ID[DEFAULT_THEME_ID];
+```
+
+> This imports the four named presets (Task 4). Create Task 4 files **before**
+> running tests, or temporarily comment the four imports + array entries and
+> restore them in Task 4. Recommended: do Task 3 + Task 4 in one sitting.
+
+- [ ] **Step 4: Write the catalog test + un-skip the light-fallback test from Task 2**
+
+```ts
+// frontend/src/react/components/sql-editor/theme/presets/presets.test.ts
+import { describe, expect, test } from "vitest";
+import { validateTheme } from "../derive";
+import { DEFAULT_THEME_ID, PRESETS, PRESET_BY_ID } from "./index";
+
+describe("theme presets catalog", () => {
+ test("every preset is structurally complete", () => {
+ for (const preset of PRESETS) {
+ expect(() => validateTheme(preset)).not.toThrow();
+ }
+ });
+ test("ids are unique", () => {
+ const ids = PRESETS.map((p) => p.id);
+ expect(new Set(ids).size).toBe(ids.length);
+ });
+ test("contains the six v1 themes in order", () => {
+ expect(PRESETS.map((p) => p.id)).toEqual([
+ "light",
+ "dark",
+ "solarized-light",
+ "solarized-dark",
+ "monokai",
+ "nord",
+ ]);
+ });
+ test("default theme exists and is light", () => {
+ expect(DEFAULT_THEME_ID).toBe("light");
+ expect(PRESET_BY_ID[DEFAULT_THEME_ID]).toBeDefined();
+ });
+});
+```
+
+Then in `derive.test.ts` remove the `.skip` added in Task 2 Step 5 on the
+`resolveAdminTheme` light-fallback test.
+
+- [ ] **Step 5: Run tests to verify they pass**
+
+Run: `pnpm --dir frontend test -- run src/react/components/sql-editor/theme/`
+Expected: PASS (catalog complete; `validateTheme` green across all six — requires Task 4 done).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add frontend/src/react/components/sql-editor/theme/presets/
+git commit -m "feat(sql-editor): add light + dark theme presets and catalog"
+```
+
+---
+
+### Task 4: Named presets (Solarized Light/Dark, Monokai, Nord)
+
+Author each from its canonical palette. Each object has the exact same shape as
+`light` (Task 3). Use the chrome-token mapping convention below so every named
+theme is filled deterministically.
+
+**Chrome-token mapping convention** (same as light/dark): `background` = base bg;
+`control-bg` = nearest surface; `control` / `control-light` / `control-placeholder`
+= foreground ramp (bright→dim); `control-border` / `block-border` = subtle border;
+`main` = brightest fg; `accent` = primary accent; status = theme blue/yellow/red/green;
+`matrix-green*` = `0 204 0` / `136 255 136` (constant); `dark-bg` = `30 30 30` (constant).
+
+**Files:** create `solarized-light.ts`, `solarized-dark.ts`, `monokai.ts`, `nord.ts`.
+
+- [ ] **Step 1: Monokai** (`bg #272822`, `fg #f8f8f2`, comment `#75715e`, pink `#f92672`, orange `#fd971f`, yellow `#e6db74`, green `#a6e22e`, cyan `#66d9ef`, purple `#ae81ff`, selection `#49483e`, line `#3e3d32`)
+
+```ts
+// frontend/src/react/components/sql-editor/theme/presets/monokai.ts
+import type { SQLEditorTheme } from "../types";
+
+export const monokai: SQLEditorTheme = {
+ id: "monokai",
+ name: "Monokai",
+ isDark: true,
+ monacoBase: "vs-dark",
+ tokens: {
+ "--color-control": "248 248 242",
+ "--color-control-hover": "255 255 255",
+ "--color-control-light": "204 204 196",
+ "--color-control-light-hover": "248 248 242",
+ "--color-control-bg": "62 61 50",
+ "--color-control-bg-hover": "73 72 62",
+ "--color-control-placeholder": "117 113 94",
+ "--color-control-border": "73 72 62",
+ "--color-accent": "166 226 46",
+ "--color-accent-hover": "182 234 80",
+ "--color-accent-disabled": "117 113 94",
+ "--color-accent-text": "39 40 34",
+ "--color-main": "248 248 242",
+ "--color-main-hover": "255 255 255",
+ "--color-main-text": "39 40 34",
+ "--color-background": "39 40 34",
+ "--color-block-border": "73 72 62",
+ "--color-link-hover": "73 72 62",
+ "--color-info": "102 217 239",
+ "--color-info-hover": "140 226 244",
+ "--color-warning": "253 151 31",
+ "--color-warning-hover": "253 175 80",
+ "--color-error": "249 38 114",
+ "--color-error-hover": "251 90 147",
+ "--color-success": "166 226 46",
+ "--color-success-hover": "182 234 80",
+ "--color-matrix-green": "0 204 0",
+ "--color-matrix-green-hover": "136 255 136",
+ "--color-dark-bg": "30 30 30",
+ },
+ editor: {
+ background: "#272822",
+ selectionBackground: "#49483e",
+ cursor: "#f8f8f0",
+ lineHighlight: "#3e3d32",
+ gutterBackground: "#272822",
+ lineNumber: "#90908a",
+ activeLineNumber: "#f8f8f2",
+ },
+ syntax: {
+ comment: "#75715e",
+ keyword: "#f92672",
+ string: "#e6db74",
+ number: "#ae81ff",
+ type: "#66d9ef",
+ function: "#a6e22e",
+ variable: "#f8f8f2",
+ operator: "#f92672",
+ delimiter: "#f8f8f2",
+ predefined: "#66d9ef",
+ },
+};
+```
+
+- [ ] **Step 2: Nord** (Polar Night `#2e3440/#3b4252/#434c5e/#4c566a`, Snow Storm `#d8dee9/#e5e9f0/#eceff4`, Frost `#8fbcbb/#88c0d0/#81a1c1/#5e81ac`, Aurora `#bf616a/#d08770/#ebcb8b/#a3be8c/#b48ead`)
+
+```ts
+// frontend/src/react/components/sql-editor/theme/presets/nord.ts
+import type { SQLEditorTheme } from "../types";
+
+export const nord: SQLEditorTheme = {
+ id: "nord",
+ name: "Nord",
+ isDark: true,
+ monacoBase: "vs-dark",
+ tokens: {
+ "--color-control": "216 222 233",
+ "--color-control-hover": "236 239 244",
+ "--color-control-light": "180 192 211",
+ "--color-control-light-hover": "216 222 233",
+ "--color-control-bg": "59 66 82",
+ "--color-control-bg-hover": "67 76 94",
+ "--color-control-placeholder": "118 128 146",
+ "--color-control-border": "76 86 106",
+ "--color-accent": "136 192 208",
+ "--color-accent-hover": "143 188 187",
+ "--color-accent-disabled": "76 86 106",
+ "--color-accent-text": "46 52 64",
+ "--color-main": "236 239 244",
+ "--color-main-hover": "255 255 255",
+ "--color-main-text": "46 52 64",
+ "--color-background": "46 52 64",
+ "--color-block-border": "67 76 94",
+ "--color-link-hover": "67 76 94",
+ "--color-info": "129 161 193",
+ "--color-info-hover": "136 192 208",
+ "--color-warning": "235 203 139",
+ "--color-warning-hover": "242 218 165",
+ "--color-error": "191 97 106",
+ "--color-error-hover": "208 135 112",
+ "--color-success": "163 190 140",
+ "--color-success-hover": "181 205 161",
+ "--color-matrix-green": "0 204 0",
+ "--color-matrix-green-hover": "136 255 136",
+ "--color-dark-bg": "30 30 30",
+ },
+ editor: {
+ background: "#2e3440",
+ selectionBackground: "#434c5e",
+ cursor: "#d8dee9",
+ lineHighlight: "#3b4252",
+ gutterBackground: "#2e3440",
+ lineNumber: "#4c566a",
+ activeLineNumber: "#d8dee9",
+ },
+ syntax: {
+ comment: "#616e88",
+ keyword: "#81a1c1",
+ string: "#a3be8c",
+ number: "#b48ead",
+ type: "#8fbcbb",
+ function: "#88c0d0",
+ variable: "#d8dee9",
+ operator: "#81a1c1",
+ delimiter: "#eceff4",
+ predefined: "#8fbcbb",
+ },
+};
+```
+
+- [ ] **Step 3: Solarized Dark** (base03 `#002b36`, base02 `#073642`, base01 `#586e75`, base00 `#657b83`, base0 `#839496`, base1 `#93a1a1`, accents yellow `#b58900`/orange `#cb4b16`/red `#dc322f`/magenta `#d33682`/violet `#6c71c4`/blue `#268bd2`/cyan `#2aa198`/green `#859900`)
+
+```ts
+// frontend/src/react/components/sql-editor/theme/presets/solarized-dark.ts
+import type { SQLEditorTheme } from "../types";
+
+export const solarizedDark: SQLEditorTheme = {
+ id: "solarized-dark",
+ name: "Solarized Dark",
+ isDark: true,
+ monacoBase: "vs-dark",
+ tokens: {
+ "--color-control": "131 148 150",
+ "--color-control-hover": "147 161 161",
+ "--color-control-light": "101 123 131",
+ "--color-control-light-hover": "131 148 150",
+ "--color-control-bg": "7 54 66",
+ "--color-control-bg-hover": "20 70 84",
+ "--color-control-placeholder": "88 110 117",
+ "--color-control-border": "88 110 117",
+ "--color-accent": "38 139 210",
+ "--color-accent-hover": "42 161 152",
+ "--color-accent-disabled": "88 110 117",
+ "--color-accent-text": "253 246 227",
+ "--color-main": "147 161 161",
+ "--color-main-hover": "238 232 213",
+ "--color-main-text": "0 43 54",
+ "--color-background": "0 43 54",
+ "--color-block-border": "7 54 66",
+ "--color-link-hover": "7 54 66",
+ "--color-info": "38 139 210",
+ "--color-info-hover": "42 161 152",
+ "--color-warning": "181 137 0",
+ "--color-warning-hover": "203 75 22",
+ "--color-error": "220 50 47",
+ "--color-error-hover": "211 54 130",
+ "--color-success": "133 153 0",
+ "--color-success-hover": "159 181 0",
+ "--color-matrix-green": "0 204 0",
+ "--color-matrix-green-hover": "136 255 136",
+ "--color-dark-bg": "30 30 30",
+ },
+ editor: {
+ background: "#002b36",
+ selectionBackground: "#073642",
+ cursor: "#839496",
+ lineHighlight: "#073642",
+ gutterBackground: "#002b36",
+ lineNumber: "#586e75",
+ activeLineNumber: "#93a1a1",
+ },
+ syntax: {
+ comment: "#586e75",
+ keyword: "#859900",
+ string: "#2aa198",
+ number: "#d33682",
+ type: "#b58900",
+ function: "#268bd2",
+ variable: "#839496",
+ operator: "#859900",
+ delimiter: "#93a1a1",
+ predefined: "#cb4b16",
+ },
+};
+```
+
+- [ ] **Step 4: Solarized Light** (same accents; light base: base3 `#fdf6e3`, base2 `#eee8d5`, base1 `#93a1a1`, base00 `#657b83`, base01 `#586e75`, base03 `#002b36`)
+
+```ts
+// frontend/src/react/components/sql-editor/theme/presets/solarized-light.ts
+import type { SQLEditorTheme } from "../types";
+
+export const solarizedLight: SQLEditorTheme = {
+ id: "solarized-light",
+ name: "Solarized Light",
+ isDark: false,
+ monacoBase: "vs",
+ tokens: {
+ "--color-control": "101 123 131",
+ "--color-control-hover": "88 110 117",
+ "--color-control-light": "131 148 150",
+ "--color-control-light-hover": "101 123 131",
+ "--color-control-bg": "238 232 213",
+ "--color-control-bg-hover": "224 218 199",
+ "--color-control-placeholder": "147 161 161",
+ "--color-control-border": "147 161 161",
+ "--color-accent": "38 139 210",
+ "--color-accent-hover": "42 161 152",
+ "--color-accent-disabled": "147 161 161",
+ "--color-accent-text": "253 246 227",
+ "--color-main": "0 43 54",
+ "--color-main-hover": "7 54 66",
+ "--color-main-text": "253 246 227",
+ "--color-background": "253 246 227",
+ "--color-block-border": "238 232 213",
+ "--color-link-hover": "238 232 213",
+ "--color-info": "38 139 210",
+ "--color-info-hover": "29 110 168",
+ "--color-warning": "181 137 0",
+ "--color-warning-hover": "203 75 22",
+ "--color-error": "220 50 47",
+ "--color-error-hover": "211 54 130",
+ "--color-success": "133 153 0",
+ "--color-success-hover": "107 123 0",
+ "--color-matrix-green": "0 204 0",
+ "--color-matrix-green-hover": "136 255 136",
+ "--color-dark-bg": "30 30 30",
+ },
+ editor: {
+ background: "#fdf6e3",
+ selectionBackground: "#eee8d5",
+ cursor: "#657b83",
+ lineHighlight: "#eee8d5",
+ gutterBackground: "#fdf6e3",
+ lineNumber: "#93a1a1",
+ activeLineNumber: "#586e75",
+ },
+ syntax: {
+ comment: "#93a1a1",
+ keyword: "#859900",
+ string: "#2aa198",
+ number: "#d33682",
+ type: "#b58900",
+ function: "#268bd2",
+ variable: "#657b83",
+ operator: "#859900",
+ delimiter: "#586e75",
+ predefined: "#cb4b16",
+ },
+};
+```
+
+- [ ] **Step 5: Run the catalog test (now all six resolve)**
+
+Run: `pnpm --dir frontend test -- run src/react/components/sql-editor/theme/`
+Expected: PASS — `validateTheme` green for all six; order test green.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add frontend/src/react/components/sql-editor/theme/presets/
+git commit -m "feat(sql-editor): add solarized, monokai, nord presets"
+```
+
+---
+
+## Phase 2 — Store & persistence
+
+### Task 5: Add the storage key
+
+**Files:**
+- Modify: `frontend/src/utils/storage-keys.ts` (SQL Editor section)
+
+- [ ] **Step 1: Add the builder** (alongside `storageKeySqlEditorLastProject`)
+
+```ts
+// Workspace-scoped like other SQL Editor prefs.
+export const storageKeySqlEditorTheme = (scope: string) =>
+ withScope("bb.sql-editor.theme", scope);
+```
+
+- [ ] **Step 2: Type-check**
+
+Run: `pnpm --dir frontend type-check`
+Expected: PASS.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add frontend/src/utils/storage-keys.ts
+git commit -m "feat(sql-editor): add theme storage key"
+```
+
+---
+
+### Task 6: Store `themeId` + persistence (TDD)
+
+**Files:**
+- Modify: `frontend/src/react/stores/sqlEditor/editor.ts`
+- Test: `frontend/src/react/stores/sqlEditor/editor.test.ts`
+
+- [ ] **Step 1: Write the failing test** (append to `editor.test.ts`; mirror existing localStorage mock there)
+
+```ts
+import { storageKeySqlEditorTheme } from "@/utils/storage-keys";
+import { DEFAULT_THEME_ID } from "@/react/components/sql-editor/theme/presets";
+
+describe("theme persistence", () => {
+ test("setThemeId updates state and persists", () => {
+ getSQLEditorEditorState().setThemeId("monokai");
+ expect(useSQLEditorEditorStore.getState().themeId).toBe("monokai");
+ expect(storage.get(storageKeySqlEditorTheme(""))).toBe(
+ JSON.stringify("monokai")
+ );
+ });
+
+ test("invalid persisted id falls back to the default", () => {
+ storage.set(storageKeySqlEditorTheme(""), JSON.stringify("does-not-exist"));
+ // readThemeId() runs at store init; assert the reader's fallback.
+ const raw = storage.get(storageKeySqlEditorTheme(""));
+ expect(raw).toBeDefined();
+ // The store reset in beforeEach sets themeId to DEFAULT; setThemeId guards.
+ getSQLEditorEditorState().setThemeId("does-not-exist");
+ expect(useSQLEditorEditorStore.getState().themeId).toBe(DEFAULT_THEME_ID);
+ });
+});
+```
+
+Also extend the `beforeEach` store reset object in `editor.test.ts` to include
+`themeId: "light",`.
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `pnpm --dir frontend test -- run src/react/stores/sqlEditor/editor.test.ts`
+Expected: FAIL — `setThemeId` / `themeId` undefined.
+
+- [ ] **Step 3: Implement in `editor.ts`**
+
+Add the import:
+
+```ts
+import { storageKeySqlEditorTheme } from "@/utils/storage-keys";
+import {
+ DEFAULT_THEME_ID,
+ PRESET_BY_ID,
+} from "@/react/components/sql-editor/theme/presets";
+```
+
+Add to the `SQLEditorEditorState` interface:
+
+```ts
+ themeId: string;
+ setThemeId: (id: string) => void;
+```
+
+Add reader helpers (near `lastProjectKey` / `readProject`):
+
+```ts
+const themeKey = () => {
+ const state = useAppStore.getState();
+ const isSaaS =
+ typeof state?.isSaaSMode === "function" ? state.isSaaSMode() : false;
+ return storageKeySqlEditorTheme(
+ workspaceCacheScope(isSaaS, state?.currentUser?.workspace ?? "")
+ );
+};
+
+const readThemeId = () =>
+ safeRead<string>(
+ themeKey(),
+ (v) => (typeof v === "string" && PRESET_BY_ID[v] ? v : undefined),
+ DEFAULT_THEME_ID
+ );
+```
+
+Add to the `create(...)` initial object:
+
+```ts
+ themeId: readThemeId(),
+```
+
+Add the action (next to `setResultRowsLimit`):
+
+```ts
+ setThemeId(id) {
+ // Ignore ids not in the catalog so a stale/garbage value can't break theming.
+ const next = PRESET_BY_ID[id] ? id : DEFAULT_THEME_ID;
+ set((s) => {
+ s.themeId = next;
+ });
+ safeWrite(themeKey(), next);
+ },
+```
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `pnpm --dir frontend test -- run src/react/stores/sqlEditor/editor.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add frontend/src/react/stores/sqlEditor/editor.ts frontend/src/react/stores/sqlEditor/editor.test.ts
+git commit -m "feat(sql-editor): persist selected theme id in editor store"
+```
+
+---
+
+## Phase 3 — Monaco integration
+
+### Task 7: Register generated Monaco themes
+
+**Files:**
+- Modify: `frontend/src/react/components/monaco/core.ts`
+- Delete: `frontend/src/react/components/monaco/themes/bb.ts`, `bb-dark.ts`
+
+- [ ] **Step 1: Rewrite `initializeTheme` to register every preset**
+
+Replace the `getBBTheme`/`getBBDarkTheme` imports and `initializeTheme` body:
+
+```ts
+import { PRESETS } from "@/react/components/sql-editor/theme/presets";
+import {
+ buildMonacoTheme,
+ monacoThemeName,
+} from "@/react/components/sql-editor/theme/derive";
+
+const initializeTheme = () => {
+ if (state.themeInitialized) return;
+ state.themeInitialized = true;
+ if (!monacoModule) return;
+ for (const preset of PRESETS) {
+ const name = monacoThemeName(preset);
+ try {
+ monacoModule.editor.defineTheme(name, buildMonacoTheme(preset));
+ state.registeredThemes.add(name);
+ } catch {
+ // The vscode theme-service override owns themes in some runtime modes;
+ // an un-registered theme falls back to `vs` via getResolvedTheme.
+ }
+ }
+};
+```
+
+- [ ] **Step 2: Update the default editor theme** — change `theme: "bb"` to `theme: "bb-light"` in both `defaultEditorOptions()` and `defaultDiffEditorOptions()`. Update `getResolvedTheme`'s no-arg fallback:
+
+```ts
+export const getResolvedTheme = (requested?: string): string => {
+ const fallback = "vs";
+ if (!requested) {
+ return state.registeredThemes.has("bb-light") ? "bb-light" : fallback;
+ }
+ return state.registeredThemes.has(requested) ? requested : fallback;
+};
+```
+
+- [ ] **Step 3: Delete the obsolete theme files**
+
+```bash
+git rm frontend/src/react/components/monaco/themes/bb.ts frontend/src/react/components/monaco/themes/bb-dark.ts
+```
+
+- [ ] **Step 4: Type-check + targeted test**
+
+Run: `pnpm --dir frontend type-check`
+Expected: PASS (no remaining `getBBTheme` references — grep to confirm: `grep -rn "getBBTheme\|getBBDarkTheme\|\"bb\"" frontend/src/react/components/monaco` returns nothing except updated lines).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add -A frontend/src/react/components/monaco
+git commit -m "feat(monaco): register generated themes from SQL editor presets"
+```
+
+---
+
+### Task 8: Global Monaco theme controller
+
+The controller sets the one global Monaco theme from the foreground panel. It is
+the **only** caller of `setTheme` in the SQL Editor. `CompactSQLEditor` and the
+default options no longer pin a theme.
+
+**Files:**
+- Create: `frontend/src/react/components/sql-editor/theme/useMonacoThemeController.ts`
+- Modify: `frontend/src/react/components/sql-editor/TerminalPanel/CompactSQLEditor.tsx`
+
+- [ ] **Step 1: Write the controller hook**
+
+```ts
+// frontend/src/react/components/sql-editor/theme/useMonacoThemeController.ts
+import { useEffect } from "react";
+import {
+ getResolvedTheme,
+ loadMonacoEditor,
+} from "@/react/components/monaco/core";
+import { useSQLEditorEditorState } from "@/react/stores/sqlEditor/editor";
+import { useSQLEditorTabState } from "@/react/stores/sqlEditor/tab";
+import { monacoThemeName, resolveAdminTheme } from "./derive";
+import { resolveThemeId } from "./presets";
+
+/**
+ * Drives the single global Monaco theme from the foreground code panel:
+ * worksheet → selected theme, admin → resolveAdminTheme(selected). Mount once
+ * at the SQL Editor root. Monaco's theme is global, so no other component may
+ * call setTheme.
+ */
+export function useMonacoThemeController() {
+ const themeId = useSQLEditorEditorState((s) => s.themeId);
+ const mode = useSQLEditorTabState(
+ (s) => s.tabsById.get(s.currentTabId)?.mode
+ );
+
+ useEffect(() => {
+ const selected = resolveThemeId(themeId);
+ const active =
+ mode === "ADMIN" ? resolveAdminTheme(selected) : selected;
+ let cancelled = false;
+ void loadMonacoEditor().then((monaco) => {
+ if (cancelled) return;
+ monaco.editor.setTheme(getResolvedTheme(monacoThemeName(active)));
+ });
+ return () => {
+ cancelled = true;
+ };
+ }, [themeId, mode]);
+}
+```
+
+- [ ] **Step 2: Stop `CompactSQLEditor` pinning `vs-dark`** — in `CompactSQLEditor.tsx` `editorOptions` (~line 323), delete the `theme: "vs-dark",` line. The controller now owns the theme.
+
+- [ ] **Step 3: Stop `MonacoEditor` re-pinning a per-instance theme** — in `MonacoEditor.tsx` (~line 346), the post-construction `monaco.editor.setTheme(getResolvedTheme(optionsRef.current?.theme))` would fight the controller when `options.theme` is unset. Guard it so it only applies when an explicit theme option was passed:
+
+```ts
+ if (optionsRef.current?.theme) {
+ monaco.editor.setTheme(
+ getResolvedTheme(optionsRef.current.theme)
+ );
+ }
+```
+
+(Default SQL Editor editors pass no `theme` now, so the controller's global theme stands.)
+
+- [ ] **Step 4: Type-check**
+
+Run: `pnpm --dir frontend type-check`
+Expected: PASS.
+
+- [ ] **Step 5: Commit** (controller is mounted in Task 10)
+
+```bash
+git add frontend/src/react/components/sql-editor/theme/useMonacoThemeController.ts frontend/src/react/components/sql-editor/TerminalPanel/CompactSQLEditor.tsx frontend/src/react/components/monaco/MonacoEditor.tsx
+git commit -m "feat(sql-editor): add global Monaco theme controller"
+```
+
+---
+
+## Phase 4 — Theme scope & wiring
+
+### Task 9: `SQLEditorThemeScope` context + component (TDD)
+
+**Files:**
+- Create: `frontend/src/react/components/sql-editor/theme/SQLEditorThemeScope.tsx`
+- Test: `frontend/src/react/components/sql-editor/theme/SQLEditorThemeScope.test.tsx`
+
+- [ ] **Step 1: Write the failing test**
+
+```tsx
+// frontend/src/react/components/sql-editor/theme/SQLEditorThemeScope.test.tsx
+import { render, screen } from "@testing-library/react";
+import { describe, expect, test } from "vitest";
+import { PRESET_BY_ID } from "./presets";
+import {
+ SQLEditorThemeScope,
+ useSQLEditorTheme,
+} from "./SQLEditorThemeScope";
+
+function Probe() {
+ const theme = useSQLEditorTheme();
+ return <span data-testid="id">{theme.id}</span>;
+}
+
+describe("SQLEditorThemeScope", () => {
+ test("writes the theme tokens as inline CSS vars on its container", () => {
+ const { container } = render(
+ <SQLEditorThemeScope theme={PRESET_BY_ID.monokai}>
+ <div>child</div>
+ </SQLEditorThemeScope>
+ );
+ const el = container.firstChild as HTMLElement;
+ expect(el.style.getPropertyValue("--color-background")).toBe("39 40 34");
+ });
+
+ test("provides the theme via context", () => {
+ render(
+ <SQLEditorThemeScope theme={PRESET_BY_ID.nord}>
+ <Probe />
+ </SQLEditorThemeScope>
+ );
+ expect(screen.getByTestId("id").textContent).toBe("nord");
+ });
+
+ test("nested scope overrides the parent for context consumers", () => {
+ render(
+ <SQLEditorThemeScope theme={PRESET_BY_ID.light}>
+ <SQLEditorThemeScope theme={PRESET_BY_ID.dark}>
+ <Probe />
+ </SQLEditorThemeScope>
+ </SQLEditorThemeScope>
+ );
+ expect(screen.getByTestId("id").textContent).toBe("dark");
+ });
+});
+```
+
+- [ ] **Step 2: Run to verify it fails**
+
+Run: `pnpm --dir frontend test -- run src/react/components/sql-editor/theme/SQLEditorThemeScope.test.tsx`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Implement**
+
+```tsx
+// frontend/src/react/components/sql-editor/theme/SQLEditorThemeScope.tsx
+import {
+ createContext,
+ useContext,
+ useMemo,
+ type ReactNode,
+} from "react";
+import { cn } from "@/react/lib/utils";
+import { themeToCssVars } from "./derive";
+import { PRESET_BY_ID } from "./presets";
+import type { SQLEditorTheme } from "./types";
+
+const SQLEditorThemeContext = createContext<SQLEditorTheme>(PRESET_BY_ID.light);
+
+export const useSQLEditorTheme = (): SQLEditorTheme =>
+ useContext(SQLEditorThemeContext);
+
+type Props = {
+ theme: SQLEditorTheme;
+ children: ReactNode;
+ className?: string;
+ // Render as a bare wrapper (default) or pass `display: contents` so the scope
+ // adds no box (used where an extra div would break layout).
+ asContents?: boolean;
+};
+
+/**
+ * Provides `theme` via context AND writes its chrome tokens as inline CSS
+ * custom properties so descendant Tailwind classes (text-control, bg-*, …)
+ * re-theme via cascade. Nest it to override a subtree (admin terminal, portals).
+ */
+export function SQLEditorThemeScope({
+ theme,
+ children,
+ className,
+ asContents = false,
+}: Props) {
+ const style = useMemo(() => themeToCssVars(theme.tokens), [theme]);
+ return (
+ <SQLEditorThemeContext.Provider value={theme}>
+ <div
+ className={cn(asContents && "contents", className)}
+ style={style}
+ >
+ {children}
+ </div>
+ </SQLEditorThemeContext.Provider>
+ );
+}
+```
+
+> Note: with `display: contents` the element generates no box, but inline CSS
+> custom properties on it **still cascade** to children — so `asContents` scopes
+> tokens without affecting layout. Use it for the root and portal wrappers where
+> an extra flex/block box would disturb sizing.
+
+- [ ] **Step 4: Run to verify it passes**
+
+Run: `pnpm --dir frontend test -- run src/react/components/sql-editor/theme/SQLEditorThemeScope.test.tsx`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add frontend/src/react/components/sql-editor/theme/SQLEditorThemeScope.tsx frontend/src/react/components/sql-editor/theme/SQLEditorThemeScope.test.tsx
+git commit -m "feat(sql-editor): add SQLEditorThemeScope context + container"
+```
+
+---
+
+### Task 10: Mount the root scope + Monaco controller
+
+**Files:**
+- Modify: `frontend/src/react/components/sql-editor/SQLEditorLayout.tsx`
+
+- [ ] **Step 1: Wrap the layout body in the root scope and mount the controller**
+
+In `SQLEditorLayout.tsx`, add imports and a tiny inner component so the
+controller (which reads stores) runs inside the scope:
+
+```tsx
+import { SQLEditorThemeScope } from "./theme/SQLEditorThemeScope";
+import { useMonacoThemeController } from "./theme/useMonacoThemeController";
+import { useSQLEditorEditorState } from "@/react/stores/sqlEditor/editor";
+import { resolveThemeId } from "./theme/presets";
+
+function SQLEditorThemeRoot({ children }: { children: React.ReactNode }) {
+ const themeId = useSQLEditorEditorState((s) => s.themeId);
+ useMonacoThemeController();
+ return (
+ <SQLEditorThemeScope theme={resolveThemeId(themeId)} asContents>
+ {children}
+ </SQLEditorThemeScope>
+ );
+}
+```
+
+Wrap the existing `RequestDrawerHost` + `SQLEditorRouteShell` subtree
+(`SQLEditorLayout.tsx:62`) so the scope sits above both the route content and the
+drawer host:
+
+```tsx
+ <SQLEditorThemeRoot>
+ <RequestDrawerHost>
+ <SQLEditorRouteShell />
+ </RequestDrawerHost>
+ </SQLEditorThemeRoot>
+```
+
+- [ ] **Step 2: Type-check + run dev to smoke-test**
+
+Run: `pnpm --dir frontend type-check`
+Then `pnpm --dir frontend dev`, open the SQL Editor: it still renders normally on the default `light` theme (no visual change yet — switcher not added).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add frontend/src/react/components/sql-editor/SQLEditorLayout.tsx
+git commit -m "feat(sql-editor): mount root theme scope + Monaco controller"
+```
+
+---
+
+### Task 11: Nested admin scope + drop `ResultView` `dark` prop
+
+**Files:**
+- Modify: `frontend/src/react/components/sql-editor/TerminalPanel/TerminalPanel.tsx`
+- Modify: `frontend/src/react/components/sql-editor/ResultView/ResultView.tsx`
+
+- [ ] **Step 1: Wrap `TerminalPanel`'s root in the nested admin scope**
+
+In `TerminalPanel.tsx`, add imports:
+
+```tsx
+import { SQLEditorThemeScope } from "../theme/SQLEditorThemeScope";
+import { resolveAdminTheme } from "../theme/derive";
+import { resolveThemeId } from "../theme/presets";
+import { useSQLEditorEditorState } from "@/react/stores/sqlEditor/editor";
+```
+
+Inside the component, compute the admin theme and wrap the outermost `<div>`
+(currently `<div className="… bg-dark-bg">` at line 206). Replace `bg-dark-bg`
+on the outer and inner containers with the token-driven `bg-background`:
+
+```tsx
+ const themeId = useSQLEditorEditorState((s) => s.themeId);
+ const adminTheme = resolveAdminTheme(resolveThemeId(themeId));
+
+ return (
+ <SQLEditorThemeScope theme={adminTheme} className="h-full w-full">
+ <div className="flex h-full w-full flex-col justify-start items-stretch overflow-hidden bg-background">
+ {/* …existing children, inner bg-dark-bg → bg-background… */}
+ </div>
+ </SQLEditorThemeScope>
+ );
+```
+
+- [ ] **Step 2: Remove the hardcoded `dark` prop from the `ResultView` call** in `TerminalPanel.tsx:236` (delete the `dark` prop entirely).
+
+- [ ] **Step 3: Drop the `dark` prop from `ResultView`**
+
+In `ResultView.tsx`: remove `dark?: boolean` from `ResultViewProps`, remove
+`dark = false` from the destructure, and replace the wrapper className
+(`ResultView.tsx:237`):
+
+```tsx
+import { useSQLEditorTheme } from "../theme/SQLEditorThemeScope";
+// …
+ const { isDark } = useSQLEditorTheme();
+// …
+ <div
+ className={cn(
+ "relative flex flex-col justify-start items-start pb-1 overflow-y-auto h-full w-full",
+ isDark && "bg-background"
+ )}
+ >
+```
+
+(The `dark` Tailwind-variant class is removed; descendants re-theme via the
+scope tokens. `isDark` remains available for any boolean-only need.)
+
+- [ ] **Step 4: Type-check + grep for stragglers**
+
+Run: `pnpm --dir frontend type-check`
+Then `grep -rn "dark={" frontend/src/react/components/sql-editor/ResultView` → expect nothing. `grep -rn "dark=" frontend/src/react/components/sql-editor/TerminalPanel` → expect nothing.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add frontend/src/react/components/sql-editor/TerminalPanel/TerminalPanel.tsx frontend/src/react/components/sql-editor/ResultView/ResultView.tsx
+git commit -m "feat(sql-editor): nest admin theme scope, drop ResultView dark prop"
+```
+
+---
+
+### Task 12: Portal scopes (overlay + request drawer)
+
+**Files:**
+- Modify: `frontend/src/react/components/sql-editor/SQLEditorHomePage.tsx`
+- Modify: `frontend/src/react/components/sql-editor/AccessGrantRequestDrawer.tsx`
+
+- [ ] **Step 1: Wrap portaled overlay children** — in `SQLEditorHomePage.tsx`, each `createPortal(<…>, getLayerRoot("overlay"))` (lines ~160 and ~191) puts DOM outside the chrome subtree, so CSS vars don't cascade. Wrap each portal's element tree in a scope reading the current theme:
+
+```tsx
+import { SQLEditorThemeScope } from "./theme/SQLEditorThemeScope";
+import { useSQLEditorEditorState } from "@/react/stores/sqlEditor/editor";
+import { resolveThemeId } from "./theme/presets";
+// inside the component:
+ const themeId = useSQLEditorEditorState((s) => s.themeId);
+ const theme = resolveThemeId(themeId);
+// for each portal payload:
+ createPortal(
+ <SQLEditorThemeScope theme={theme} asContents>
+ {/* existing FAB / sidebar overlay markup */}
+ </SQLEditorThemeScope>,
+ getLayerRoot("overlay")
+ )
+```
+
+- [ ] **Step 2: Wrap the drawer's `Sheet` content** — in `AccessGrantRequestDrawer.tsx`, the `Sheet` portals to the overlay layer. Wrap its content body in a scope so the drawer chrome (form controls, labels) re-themes. Its embedded `<MonacoEditor>` (line 262) gets no `theme` prop — it shares the global Monaco theme set by the controller:
+
+```tsx
+import { SQLEditorThemeScope } from "./theme/SQLEditorThemeScope";
+import { useSQLEditorTheme } from "./theme/SQLEditorThemeScope";
+// wrap the sheet content's root element:
+ <SQLEditorThemeScope theme={useSQLEditorTheme()} asContents>
+ {/* existing drawer body */}
+ </SQLEditorThemeScope>
+```
+
+(`useSQLEditorTheme()` works because the drawer is under the layout-level root
+scope's React context even though its DOM is portaled.)
+
+- [ ] **Step 3: Confirm the drawer Monaco passes no theme** — grep `AccessGrantRequestDrawer.tsx` around line 262; if the `<MonacoEditor>` `options`/props set `theme`, remove it.
+
+- [ ] **Step 4: Type-check + visual smoke** (after the switcher exists you re-verify; for now just type-check)
+
+Run: `pnpm --dir frontend type-check`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add frontend/src/react/components/sql-editor/SQLEditorHomePage.tsx frontend/src/react/components/sql-editor/AccessGrantRequestDrawer.tsx
+git commit -m "feat(sql-editor): apply theme scope to portaled overlays + drawer"
+```
+
+---
+
+## Phase 5 — Hardcoded color migration
+
+Each task replaces raw palette classes / `dark:` variants / inline colors with
+semantic tokens (per spec §5). Replacement convention:
+
+| Hardcoded | Token class |
+|---|---|
+| `bg-gray-100/200`, `bg-gray-50` | `bg-control-bg` |
+| `bg-white` (surface) | `bg-background` |
+| `bg-white/NN` (overlay) | `bg-background/NN` |
+| `bg-black/NN` (overlay) | `bg-overlay/NN` |
+| `bg-gray-900` (tooltip) | `bg-main` |
+| `text-gray-400` | `text-control-placeholder` |
+| `text-gray-500/600` | `text-control-light` |
+| `text-white` (on dark surface) | `text-main-text` or `text-control` per context |
+| `border-gray-100/200/400`, `border-zinc-500/600` | `border-block-border` (cells) / `border-control-border` (controls) |
+
+All `dark:`-prefixed variants are **deleted** (the scope tokens carry dark values).
+
+### Task 13: Result-view color migration
+
+**Files (exact lines from spec §5):**
+- `ResultView/VirtualDataTable.tsx` — 271, 275, 311, 313, 397, 436, 496
+- `ResultView/VirtualDataBlock.tsx` — 147, 153, 166, 237
+- `ResultView/SelectionCopyTooltips.tsx` — 56, 62, 75, 153
+- `ResultView/SingleResultView.tsx` — 602, 617
+- `ResultPanel/DatabaseQueryContext.tsx` — 75, 93
+
+- [ ] **Step 1: VirtualDataTable** — delete all `dark:` variants on the listed lines; keep the light token classes already present (`bg-control-bg`, `text-control-light`, `border-block-border`). Where a line had only `dark:` (e.g. `dark:border-zinc-500`), ensure a base token class exists (`border-block-border`). Example, line 271:
+
+```tsx
+// before: className="... border-block-border dark:border-zinc-500"
+// after: className="... border-block-border"
+```
+
+- [ ] **Step 2: VirtualDataBlock** — same treatment on lines 147/153/166/237 (`dark:bg-gray-700`→ drop; base stays `bg-control-bg`).
+
+- [ ] **Step 3: SelectionCopyTooltips** — lines 56/62/75/153: drop `dark:*`; replace `dark:bg-dark-bg` with base `bg-background`, `dark:border-zinc-600` with base `border-control-border`.
+
+- [ ] **Step 4: SingleResultView** — lines 602/617: drop the `dark:bg-gray-700 dark:text-gray-100 dark:border-zinc-600 dark:hover:bg-gray-600` cluster; base becomes `bg-control-bg text-control border-control-border hover:bg-control-bg-hover`.
+
+- [ ] **Step 5: DatabaseQueryContext** — lines 75/93: `bg-white/80 dark:bg-black/80` → `bg-background/80`.
+
+- [ ] **Step 6: Type-check + grep**
+
+Run: `pnpm --dir frontend type-check`
+Then `grep -rn "dark:\|-gray-\|-zinc-" frontend/src/react/components/sql-editor/ResultView frontend/src/react/components/sql-editor/ResultPanel/DatabaseQueryContext.tsx` → expect zero.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add frontend/src/react/components/sql-editor/ResultView frontend/src/react/components/sql-editor/ResultPanel/DatabaseQueryContext.tsx
+git commit -m "refactor(sql-editor): route result-view colors through theme tokens"
+```
+
+---
+
+### Task 14: Standard-mode color migration
+
+**Files (spec §5):**
+- `ConnectionPane/DatabaseHoverPanel/DatabaseHoverPanel.tsx` — 97, 114, 124, 133, 142, 149
+- `ConnectionPane/ConnectionPane.tsx` — 680
+- `SQLEditorHomePage.tsx` — 164, 194
+- `SchemaPane/FlatTableList.tsx` — 169, 174, 206, 209, 218, 221, 227, 228, 237, 240
+- `SchemaPane/TreeNode/icons.tsx` — 43, 54, 59, 71, 87, 91, 126
+- `SchemaPane/HoverPanel/HoverPanel.tsx` — 142; `HoverPanel/InfoItem.tsx` — 22
+- `SharePopoverBody.tsx` — 182, 197, 198, 236, 247
+- `Panels/common/EllipsisCell.tsx` — 70
+
+- [ ] **Step 1: Hover panels** — `DatabaseHoverPanel.tsx` & `SchemaPane/HoverPanel`: `border-gray-100`→`border-block-border`, `bg-white`→`bg-background`, `text-gray-500`→`text-control-light`, `bg-gray-200/75`→`bg-control-bg`.
+
+- [ ] **Step 2: Loading overlays** — `ConnectionPane.tsx:680` `bg-white/75`→`bg-background/75`; `SQLEditorHomePage.tsx:164` `bg-white`→`bg-background`, `:194` `bg-black/40`→`bg-overlay/40`.
+
+- [ ] **Step 3: Schema pane** — `FlatTableList.tsx` & `TreeNode/icons.tsx`: `text-gray-400`→`text-control-placeholder`, `text-gray-500/600`→`text-control-light`, `bg-gray-50`→`bg-control-bg`, `border-gray-200`→`border-block-border`.
+
+- [ ] **Step 4: Share + tooltip** — `SharePopoverBody.tsx`: `border-gray-200`→`border-control-border`, `text-gray-400`→`text-control-placeholder`, `hover:bg-gray-200`/`bg-gray-200`→`hover:bg-control-bg-hover`/`bg-control-bg`, `bg-white`→`bg-background`. `EllipsisCell.tsx:70` `bg-gray-900 text-white`→`bg-main text-main-text`.
+
+- [ ] **Step 5: Type-check + grep**
+
+Run: `pnpm --dir frontend type-check`
+Then grep the touched files for `-gray-`, `-zinc-`, `bg-white`, `bg-black` → expect only the documented dynamic cases (none in these files).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add frontend/src/react/components/sql-editor
+git commit -m "refactor(sql-editor): route standard-mode colors through theme tokens"
+```
+
+---
+
+### Task 15: Terminal residual colors
+
+**Files:**
+- `TerminalPanel/TerminalPanel.tsx` — 246, 251
+
+- [ ] **Step 1: Overlays/text** — line 246 `bg-black/20`→`bg-overlay/20`; line 251 `text-gray-400`→`text-control-placeholder`. (The `bg-dark-bg`→`bg-background` swap was done in Task 11.)
+
+- [ ] **Step 2: Type-check + grep**
+
+Run: `pnpm --dir frontend type-check`
+Then `grep -rn "bg-dark-bg\|-gray-\|bg-black" frontend/src/react/components/sql-editor/TerminalPanel` → expect zero.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add frontend/src/react/components/sql-editor/TerminalPanel
+git commit -m "refactor(sql-editor): route terminal residual colors through tokens"
+```
+
+---
+
+## Phase 6 — Switcher UI
+
+### Task 16: i18n keys
+
+**Files:**
+- Modify: `frontend/src/locales/en-US.json`, `zh-CN.json`, `ja-JP.json`, `es-ES.json`, `vi-VN.json`
+
+- [ ] **Step 1: Add keys under the `sql-editor` object** (light/dark labels + the section label). Named-palette labels are literal proper nouns (no key). en-US:
+
+```json
+"theme": {
+ "self": "Theme",
+ "light": "Default Light",
+ "dark": "Default Dark"
+}
+```
+
+Add the locale-appropriate translations for the other four files (translate
+`self`, `light`, `dark`; keep the same JSON shape). Example zh-CN:
+
+```json
+"theme": { "self": "主题", "light": "默认浅色", "dark": "默认深色" }
+```
+
+(ja-JP: `"テーマ" / "デフォルト(ライト)" / "デフォルト(ダーク)"`; es-ES:
+`"Tema" / "Claro predeterminado" / "Oscuro predeterminado"`; vi-VN: `"Giao diện" /
+"Sáng mặc định" / "Tối mặc định"`.)
+
+- [ ] **Step 2: Verify no empty objects + valid JSON**
+
+Run: `pnpm --dir frontend type-check` (i18n types) and `node -e "require('./frontend/src/locales/en-US.json')"` for each file (valid JSON).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add frontend/src/locales
+git commit -m "i18n(sql-editor): add theme switcher labels"
+```
+
+---
+
+### Task 17: `ThemeSelect` + mount in `EditorAction`
+
+**Files:**
+- Create: `frontend/src/react/components/sql-editor/ThemeSelect.tsx`
+- Modify: `frontend/src/react/components/sql-editor/EditorAction.tsx`
+
+- [ ] **Step 1: Build `ThemeSelect`** using the shared Base UI `Select` (confirm the exported subcomponent names in `ui/select.tsx`: `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`/`SelectPositioner`+`SelectPopup`, `SelectItem`). Drive options off `PRESETS`:
+
+```tsx
+// frontend/src/react/components/sql-editor/ThemeSelect.tsx
+import { useTranslation } from "react-i18next";
+import {
+ Select,
+ SelectContent,
+ SelectItem,
+ SelectTrigger,
+ SelectValue,
+} from "@/react/components/ui/select";
+import {
+ getSQLEditorEditorState,
+ useSQLEditorEditorState,
+} from "@/react/stores/sqlEditor/editor";
+import { PRESETS } from "./theme/presets";
+
+// Named-palette ids whose label is a literal proper noun (not an i18n key).
+const LITERAL_NAME = new Set([
+ "solarized-light",
+ "solarized-dark",
+ "monokai",
+ "nord",
+]);
+
+export function ThemeSelect() {
+ const { t } = useTranslation();
+ const themeId = useSQLEditorEditorState((s) => s.themeId);
+ const label = (id: string, name: string) =>
+ LITERAL_NAME.has(id) ? name : t(name);
+
+ return (
+ <Select
+ value={themeId}
+ onValueChange={(id: string) =>
+ getSQLEditorEditorState().setThemeId(id)
+ }
+ >
+ <SelectTrigger size="sm" aria-label={t("sql-editor.theme.self")}>
+ <SelectValue />
+ </SelectTrigger>
+ <SelectContent>
+ {PRESETS.map((p) => (
+ <SelectItem key={p.id} value={p.id}>
+ {label(p.id, p.name)}
+ </SelectItem>
+ ))}
+ </SelectContent>
+ </Select>
+ );
+}
+```
+
+> Match the exact Base UI `Select` API used elsewhere (e.g. `MaxRowCountSelect`
+> or another `ui/select` consumer). If the wrapper uses
+> `onValueChange`/`value` vs `value`/`onChange`, follow that file. Confirm
+> with: `grep -rln "from \"@/react/components/ui/select\"" frontend/src` and read
+> one consumer.
+
+- [ ] **Step 2: Mount in `EditorAction.tsx`** `action-right` group (always visible in both modes), before `ChooserGroup`:
+
+```tsx
+import { ThemeSelect } from "./ThemeSelect";
+// …
+ <div className="action-right gap-x-2 flex …">
+ <ThemeSelect />
+ <ChooserGroup />
+ <OpenAIButton … />
+ </div>
+```
+
+- [ ] **Step 3: Type-check + test the component renders all six**
+
+Add `frontend/src/react/components/sql-editor/ThemeSelect.test.tsx`:
+
+```tsx
+import { render, screen } from "@testing-library/react";
+import { describe, expect, test } from "vitest";
+import { ThemeSelect } from "./ThemeSelect";
+
+describe("ThemeSelect", () => {
+ test("renders the trigger with the current theme", () => {
+ render(<ThemeSelect />);
+ // Trigger shows the selected value; default store themeId is "light".
+ expect(screen.getByLabelText(/theme/i)).toBeInTheDocument();
+ });
+});
+```
+
+Run: `pnpm --dir frontend test -- run src/react/components/sql-editor/ThemeSelect.test.tsx`
+Expected: PASS. (If i18n isn't set up in the test env, wrap with the project's test i18n provider — copy from a sibling `*.test.tsx`.)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add frontend/src/react/components/sql-editor/ThemeSelect.tsx frontend/src/react/components/sql-editor/ThemeSelect.test.tsx frontend/src/react/components/sql-editor/EditorAction.tsx
+git commit -m "feat(sql-editor): add theme switcher to editor toolbar"
+```
+
+---
+
+## Phase 7 — Verification
+
+### Task 18: Full verification sweep
+
+- [ ] **Step 1: No hardcoded colors remain** (excluding documented dynamic/animation cases + admin terminal already migrated)
+
+Run:
+```bash
+grep -rn "dark:\|-gray-\|-zinc-\|-slate-\|-neutral-\|bg-white\|bg-black\|text-white\|text-black" \
+ frontend/src/react/components/sql-editor | \
+ grep -v -E "Label.tsx|TabItem.tsx|BatchQuerySelect.tsx|AccessGrantItem.tsx"
+```
+Expected: empty (any hit is an un-migrated island — fix it).
+
+- [ ] **Step 2: Only the controller calls `setTheme`**
+
+Run: `grep -rn "setTheme(" frontend/src/react/components/sql-editor frontend/src/react/components/monaco`
+Expected: occurrences only in `useMonacoThemeController.ts` and `MonacoEditor.tsx` (guarded) — no per-component `setTheme`.
+
+- [ ] **Step 3: Gates**
+
+Run, in order, until clean:
+```bash
+pnpm --dir frontend fix
+pnpm --dir frontend check
+pnpm --dir frontend type-check
+pnpm --dir frontend test
+```
+Expected: all PASS.
+
+- [ ] **Step 4: Manual visual check** (`pnpm --dir frontend dev`)
+
+For each theme in the switcher:
+- Chrome (sidebars, tabs, toolbar, schema pane), Monaco surface, and result grid all match the theme — no light islands on dark themes.
+- **Default Light** is visually identical to `main`.
+- **Admin mode:** enter admin with a **light** theme selected → terminal subtree (editor + result) is dark, surrounding chrome stays light. With a **dark/named** theme selected → terminal matches it.
+- **Portals:** mobile FAB + sidebar overlay themed; open the access-request drawer → its chrome themed; its Monaco shares the active global theme without flicker, including when opened over an admin terminal.
+- Reload the page → the selected theme persists (localStorage).
+
+- [ ] **Step 5: Final commit** (if `fix`/`check` reformatted anything)
+
+```bash
+git add -A frontend
+git commit -m "chore(sql-editor): lint/format pass for theme feature"
+```
+
+---
+
+## Self-Review notes
+
+- **Spec coverage:** model (T1–2), 6 presets (T3–4), store+persistence (T5–6), Monaco generation (T7) + global controller resolving the drawer conflict (T8), scope component (T9), root/admin/portal scopes (T10–12), full color migration incl. `dark`-prop removal (T11, T13–15), switcher in always-visible `EditorAction` (T16–17), verification incl. portal + drawer-Monaco checks (T18). All spec sections map to a task.
+- **Known authoring follow-up:** named-theme palettes (T4) and the `dark` chrome values (T3) are spec-flagged as visually tunable — T18 Step 4 is where they get the visual pass.
+- **API confirmations the implementer must make before coding the UI:** exact Base UI `Select` subcomponent names/props (`ui/select.tsx`) in T17, and the test-env i18n provider pattern from a sibling `*.test.tsx`.
diff --git a/docs/superpowers/specs/2026-06-09-sql-editor-theme-pattern-design.md b/docs/superpowers/specs/2026-06-09-sql-editor-theme-pattern-design.md
new file mode 100644
index 0000000000..10255b0b5c
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-09-sql-editor-theme-pattern-design.md
@@ -0,0 +1,645 @@
+# SQL Editor Theme Pattern — Design
+
+**Date:** 2026-06-09
+**Status:** Implemented — the sections below are the original design; the box
+immediately below records what actually shipped and where it diverged.
+**Scope:** SQL Editor only (UI chrome + Monaco editor surface + result views)
+
+## Implementation notes — as shipped (supersedes design details below)
+
+The data-driven model, the `SQLEditorThemeScope`, the workspace-scoped localStorage
+preference, and the `ThemeSelect` toolbar switcher all landed as designed. The
+following diverged during implementation (driven by how the codingame VSCode Monaco
+runtime and the real DOM behave):
+
+- **Catalog reduced to two themes: `light` + `dark`.** Solarized×2, Monokai, and Nord
+ were dropped — two polished themes beat six half-finished ones. `syntax` is therefore
+ unused in practice: both presets omit it and inherit `vs`/`vs-dark` verbatim (the
+ `SyntaxPalette` machinery stays for the documented custom-theme future).
+- **Monaco theming is per-editor + a *change-only* controller, not a mount-time global
+ `setTheme`.** Calling `monaco.editor.setTheme` while an editor is still constructing
+ races the codingame theme service and throws → the editor falls back to a read-only
+ `<pre>`. So: each SQL-Editor editor passes `options.theme` (themes at construction),
+ and `useMonacoThemeController` re-applies the global theme **only on a genuine theme
+ change** (StrictMode-safe via a prev-value ref), never on mount.
+- **`getResolvedTheme` falls back to each theme's *base* (`vs` / `vs-dark`).** Custom
+ `bb-*` themes do not register in this runtime (the service silently swallows
+ `defineTheme`), so a dark theme used to fall back to the light `vs` — leaving the
+ editor light under Dark. `core.ts` records each preset's `monacoBase` and falls back
+ to it.
+- **Chrome theming was a *transparent-container* problem, not hardcoded colors.** The
+ big panels already use semantic tokens; they're just transparent / un-classed, so on
+ the white default they looked fine and under Dark showed white. Fixes: `bg-background`
+ + `text-main` on the `sqleditor--wrapper` (themed backdrop + default text), and the
+ global default border now uses `rgb(var(--color-block-border))` (identical to the old
+ gray-200 in light, themed inside a scope). The active-statement decoration was
+ tokenized (`bg-control-bg-hover`). Only a handful of genuinely-hardcoded colors needed
+ migrating.
+- **Portaled overlays are themed at the overlay *layer root*, not per component.**
+ Dialogs (Save Sheet, …), the access drawer, and Base-UI Select/Popover/Tooltip popups
+ all portal to the app-global overlay root, outside the scope's DOM — CSS vars can't
+ cascade. `useSQLEditorOverlayTheme` sets the theme's vars + a default text color on
+ `getLayerRoot("overlay")` while the SQL Editor is mounted (reverted on unmount), which
+ themes **all** of them from one place. (In light the vars equal `:root`, so it's a
+ no-op outside a dark theme.)
+- **Admin (terminal) nested scope, drawer chrome, and the `dark`-prop removal** landed as
+ designed.
+- **`isDark` is fully deprecated — no light/dark branching in components.** The original
+ design exposed `SQLEditorTheme.isDark` "for the few spots that need a boolean," but in
+ practice components used `isDark ? colorA : colorB`, which bakes colors into the
+ component and can't extend to a 3rd/custom theme. So: the property is **removed** from
+ `SQLEditorTheme`; all `isDark ? colorA : colorB` became plain semantic-token classes
+ (each theme defines the value); `resolveAdminTheme` keys off `monacoBase === "vs-dark"`;
+ and the one genuine terminal-vs-worksheet *layout* difference uses an explicit `compact`
+ prop (`TerminalPanel` → `ResultView` → `SingleResultView`), not the theme. Net: colors
+ are 100% token-driven and a custom theme is just another token map.
+
+Net new files vs. the design: `theme/useSQLEditorOverlayTheme.ts`. The `getResolvedTheme`
+base-fallback is unit-tested in `monaco/core.test.ts`.
+
+## Goal
+
+Extract the colors the SQL Editor uses today into a **data-driven theme model** and
+add a **runtime preset switcher** scoped to the SQL Editor. The current look becomes
+the `light` preset (zero visual change as the default); a `dark` preset plus several
+named pre-defined themes ship alongside it. The model is shaped so that user-defined
+**custom themes** can be added later with no re-architecture — a custom theme is just
+another theme object.
+
+> **Shipped reality:** the catalog was reduced to **two** themes (`light` + `dark`)
+> before merge, and the `isDark` property was removed entirely — see
+> [Implementation notes — as shipped](#implementation-notes--as-shipped) above, which
+> is authoritative wherever it conflicts with the original design below.
+
+This phase ships a **catalog of pre-defined preset themes** (below), each with its
+authentic Monaco syntax palette. Custom-theme editing UI, a "System" option, and
+backend persistence are explicitly out of scope (see [Future work](#future-work)).
+
+### Theme catalog
+
+| id | name | monacoBase | notes |
+| --- | --- | --- | --- |
+| `light` | Default Light | `vs` | today's `:root`/`bb` look, verbatim — the default |
+| `dark` | Default Dark | `vs-dark` | Bytebase dark, inherits `vs-dark` chrome + tokens |
+
+## Locked decisions
+
+| Decision | Choice |
+| --- | --- |
+| End goal | Build the foundation for runtime-switchable themes |
+| Scope | SQL Editor only — chrome + Monaco + result views |
+| Granularity | Preset themes only — `light` + `dark` shipped (catalog above) |
+| Syntax fidelity | Each named theme ships its full, authentic Monaco syntax palette |
+| Token scoping | Scoped override — re-declare `--color-*` on the SQL Editor container |
+| Persistence | localStorage, client-only, workspace-scoped |
+| Theme representation | Approach A — theme is a plain JS token map; both layers derive from it |
+| Admin (terminal) mode | A **nested theme scope**; effective theme = `selected.monacoBase === "vs-dark" ? selected : dark` |
+
+### Why Approach A (data-driven) over a static CSS-class model
+
+A theme is **data**: a `{ token: "r g b" }` object. The chrome consumes it by writing
+the tokens as inline CSS custom properties on the container; Monaco consumes it via a
+theme **generated from the same object**. Presets and (future) custom themes are the
+same shape and the same code path — custom is just an object we did not ship. A static
+model (a `.sqle-theme-dark` CSS class + a hand-authored Monaco theme file) cannot
+represent values unknown at build time, so custom themes would force re-introducing
+the data-driven mechanism anyway, on top of two diverging sources of truth.
+
+## Current state (as found)
+
+- **Tokens.** Semantic CSS variables live at `:root` in
+ `frontend/src/assets/css/tailwind.css` (`--color-control*`, `--color-accent*`,
+ `--color-main*`, status colors, `--color-block-border`, `--color-background`,
+ `--color-dark-bg`, `--color-matrix-green*`). Tailwind utilities resolve to
+ `rgb(var(--color-x) / <alpha-value>)` (`frontend/tailwind.config.js`), so overriding
+ a variable on a parent element cascades to all descendants. **This is the mechanism
+ the whole design relies on.**
+- **Monaco.** Two themes (`bb` light, `bb-dark`) are defined once in
+ `frontend/src/react/components/monaco/core.ts` via `initializeTheme()`; they read
+ CSS vars from `:root` through `callCssVariable()`. `monaco.editor.setTheme()` is
+ global and is currently called once per editor at construction
+ (`MonacoEditor.tsx:346`). The admin terminal uses `vs-dark` intentionally.
+- **Settings store.** `useSQLEditorEditorStore` (Zustand) in
+ `frontend/src/react/stores/sqlEditor/editor.ts` already persists prefs to
+ localStorage via `safeRead`/`safeWrite`, workspace-scoped through
+ `frontend/src/utils/storage-keys.ts`.
+- **Root container.** `<div className="sqleditor--wrapper …">` in
+ `SQLEditorHomePage.tsx:187` wraps the editor body, but **not** everything: portaled
+ overlays (FAB/sidebar → `getLayerRoot("overlay")`) and `RequestDrawerHost`
+ (`SQLEditorLayout.tsx:62`, a sibling above the wrapper) render outside it. The scoped
+ CSS-variable attach point is therefore the **layout** (`SQLEditorLayout`), with
+ per-portal re-application (see Architecture §4 → Portals & sibling hosts).
+- **Admin (terminal) mode is a nested dark subtree, not whole-editor dark.** A tab's
+ `mode` (`"WORKSHEET"` | `"ADMIN"`, in the tab store) drives `Panels.tsx:162` to swap
+ the code panel between `StandardPanel` and `TerminalPanel`. Only `<TerminalPanel>`
+ (outermost `<div class="… bg-dark-bg">` at `TerminalPanel.tsx:206`) goes dark — its
+ `EditorAction`, `CompactSQLEditor` (Monaco `vs-dark`, `CompactSQLEditor.tsx:323`), and
+ `ResultView` (`dark` prop hardcoded `true`, `TerminalPanel.tsx:236`). The surrounding
+ chrome (tabs, schema pane, connection pane) stays light. This subtree is the natural
+ **nested scope boundary** for the theme system.
+- **Hardcoded colors.** Many SQL Editor components bypass the tokens with raw
+ palette classes (`bg-gray-200`, `border-zinc-500`), `dark:`-prefixed variants, and
+ inline `rgb()`/hex. These must be migrated for scoped theming to work end-to-end
+ (full inventory in [Color migration](#5-color-migration-prerequisite)).
+
+## Architecture
+
+### 1. Theme token model
+
+A theme has **two layers**: the **chrome** layer (CSS-variable token map that re-themes
+the SQL Editor UI) and the **Monaco** layer (editor-surface colors + syntax palette
+that the chrome `--color-*` set does not cover). A named theme like Monokai is defined
+largely by its Monaco layer.
+
+```ts
+// frontend/src/react/components/sql-editor/theme/types.ts
+type RGB = string; // "r g b" for chrome tokens, e.g. "82 82 91"
+type Hex = string; // "#rrggbb" for Monaco (Monaco consumes hex)
+
+interface SQLEditorTheme {
+ id: string; // "light" | "dark" | … (stable, persisted)
+ name: string; // i18n key for the display label
+ // NOTE: `isDark` was REMOVED before merge (see Implementation notes). Components
+ // never branch on a boolean; light/dark differences are encoded in `tokens`, and
+ // the one place that needs the Monaco family reads `monacoBase` directly.
+ monacoBase: "vs" | "vs-dark";
+ tokens: Record<SQLEditorThemeToken, RGB>; // chrome layer
+ editor: Partial<EditorChromeColors>; // Monaco surface (bg, gutter, selection, cursor, lineHighlight, …)
+ syntax?: SyntaxPalette; // Monaco token colors; omitted → inherit monacoBase verbatim
+}
+```
+
+- **`tokens`** — the SQL-Editor subset of the existing `--color-*` names (control\*,
+ accent\*, main\*, background, block-border, link-hover, status colors,
+ matrix-green\*, dark-bg). Names are **unchanged**; we only override values per theme,
+ so existing `text-control` / `bg-control-bg` classes keep working.
+- **`editor`** — Monaco `colors{}` entries: `editor.background`, `editorGutter.*`,
+ `editor.selectionBackground`, `editorCursor.foreground`,
+ `editorLineNumber.foreground`/`activeForeground`, line-highlight, etc.
+- **`syntax`** — a normalized palette (`comment`, `keyword`, `string`, `number`,
+ `type`, `function`, `variable`, `operator`, `delimiter`, `predefined`) that
+ `buildMonacoTheme` maps onto Monaco token rules (incl. SQL scopes like
+ `predefined.sql`, `operator.sql`, `string.sql`). Defining `syntax` once per theme,
+ language-agnostic, keeps each preset to a single small palette rather than per-grammar
+ rule lists.
+
+**Supporting types** (the keys each layer must fill — `validateTheme` enforces them):
+
+```ts
+// chrome layer — the SQL-Editor subset of existing --color-* names
+type SQLEditorThemeToken =
+ | "--color-control" | "--color-control-hover"
+ | "--color-control-light" | "--color-control-light-hover"
+ | "--color-control-bg" | "--color-control-bg-hover"
+ | "--color-control-placeholder" | "--color-control-border"
+ | "--color-accent" | "--color-accent-hover" | "--color-accent-disabled" | "--color-accent-text"
+ | "--color-main" | "--color-main-hover" | "--color-main-text"
+ | "--color-background" | "--color-block-border" | "--color-link-hover"
+ | "--color-info" | "--color-info-hover" | "--color-warning" | "--color-warning-hover"
+ | "--color-error" | "--color-error-hover" | "--color-success" | "--color-success-hover"
+ | "--color-matrix-green" | "--color-matrix-green-hover" | "--color-dark-bg";
+
+// Monaco surface (canvas — not reachable by CSS vars)
+interface EditorChromeColors {
+ background: Hex; selectionBackground: Hex; cursor: Hex; lineHighlight: Hex;
+ gutterBackground: Hex; lineNumber: Hex; activeLineNumber: Hex;
+}
+
+// Monaco token colors, normalized & language-agnostic
+interface SyntaxPalette {
+ comment: Hex; keyword: Hex; string: Hex; number: Hex; type: Hex;
+ function: Hex; variable: Hex; operator: Hex; delimiter: Hex; predefined: Hex;
+}
+```
+
+**Derivation functions** — the single `SQLEditorTheme` object is the source; both layers
+are *computed* from it (this is the whole point of Approach A: presets and future custom
+themes flow through the exact same functions):
+
+```ts
+// theme/derive.ts
+
+// CHROME: tokens → inline CSS custom properties, spread onto a container's `style` prop.
+// { "--color-control": "82 82 91", … } → <div style={vars}>
+function themeToCssVars(tokens: SQLEditorTheme["tokens"]): CSSProperties;
+
+// MONACO: whole theme → registered standalone theme data.
+// maps `editor` → IStandaloneThemeData.colors, `syntax` → .rules (incl. SQL scopes).
+function buildMonacoTheme(theme: SQLEditorTheme): monaco.editor.IStandaloneThemeData;
+
+// MONACO name used by defineTheme(name, …) and the global setTheme controller.
+function monacoThemeName(theme: SQLEditorTheme): string; // `bb-${theme.id}`
+
+// ADMIN: foreground-panel resolution for the nested terminal scope + Monaco controller.
+function resolveAdminTheme(selected: SQLEditorTheme): SQLEditorTheme; // selected.monacoBase === "vs-dark" ? selected : presets.dark
+
+// VALIDATION: throws if any chrome token / editor key / syntax key is missing.
+// Unit-tested across every entry in PRESETS so no theme can ship with holes.
+function validateTheme(theme: SQLEditorTheme): void;
+```
+
+`<SQLEditorThemeScope>` (§4) is the only consumer of `themeToCssVars` (for the chrome) and
+context; `monaco/core.ts` calls `buildMonacoTheme` once per preset at init, and the single
+Monaco controller (§4 → Monaco) is the only caller of `setTheme(monacoThemeName(active))`.
+
+### 2. Presets
+
+One file per theme under `frontend/src/react/components/sql-editor/theme/presets/`
+(`light.ts`, `dark.ts`, `solarized-light.ts`, `solarized-dark.ts`, `monokai.ts`,
+`nord.ts`), re-exported from an `index.ts` as an ordered `PRESETS` array. One file per
+theme keeps each palette small and reviewable, and makes adding a theme a single new
+file.
+
+- **`light`** — `tokens` copied **verbatim** from today's `:root`; `editor`/`syntax`
+ reproduce the current `bb` look so the default render is byte-for-byte identical to
+ current. `monacoBase: "vs"`.
+- **`dark`** — derived from existing `dark:` choices (`gray-700/800`, `zinc-500/600`,
+ `--color-dark-bg`) and `bb-dark`. Starting chrome palette below; **tunable**, final
+ values confirmed visually during implementation.
+
+ | Token | Light (current) | Dark (proposed start) |
+ | --- | --- | --- |
+ | `--color-background` | `255 255 255` | `30 30 30` (dark-bg) |
+ | `--color-control-bg` | `243 244 246` | `55 65 81` (gray-700) |
+ | `--color-control-bg-hover` | `229 231 235` | `75 85 99` (gray-600) |
+ | `--color-control` | `82 82 91` | `229 231 235` (gray-200) |
+ | `--color-control-light` | `113 113 122` | `209 213 219` (gray-300) |
+ | `--color-control-placeholder` | `161 161 170` | `156 163 175` (gray-400) |
+ | `--color-control-border` | `209 213 219` | `113 113 122` (zinc-500) |
+ | `--color-block-border` | `229 231 235` | `82 82 91` (zinc-600) |
+ | `--color-main` | `24 24 27` | `244 244 245` |
+ | `--color-accent` | `79 70 229` | `129 140 248` (indigo-400) |
+ | status colors | unchanged hue, may lighten slightly for contrast on dark bg | |
+
+- **`solarized-light` / `solarized-dark` / `monokai` / `nord`** — authored from each
+ theme's published palette. Each derives its **chrome** `tokens` from its base/bg and
+ accent colors (so the SQL Editor UI matches), plus its authentic **`editor`** and
+ **`syntax`** values. Reference palettes:
+ - Solarized: base03–base3 + accent set (yellow/orange/red/magenta/violet/blue/cyan/green)
+ - Monokai: bg `#272822`, fg `#f8f8f2`, green `#a6e22e`, pink `#f92672`, orange `#fd971f`, blue `#66d9ef`, comment `#75715e`
+ - Nord: Polar Night `#2e3440…#4c566a`, Snow Storm `#d8dee9…#eceff4`, Frost `#8fbcbb/#88c0d0/#81a1c1/#5e81ac`, Aurora accents
+
+ Each theme must define **every** required chrome token (no holes) so it renders
+ coherently; a `validateTheme()` helper + a unit test enforce completeness across the
+ whole catalog.
+
+### 3. Store & persistence
+
+Extend `useSQLEditorEditorStore`:
+
+- State: `themeId: string` (default `"light"`).
+- Action: `setThemeId(id)`.
+- Persistence: read on init / write on change via the existing `safeRead`/`safeWrite`
+ + a new workspace-scoped key in `storage-keys.ts`, e.g.
+ `storageKeySqlEditorTheme(scope)` → `bb.sql-editor.theme[.${workspaceId}]`,
+ matching the current scoping scheme. Unknown/invalid persisted id falls back to
+ `"light"`.
+
+No backend or proto changes.
+
+### 4. Applying the theme — context + nested scopes
+
+Theming flows through a small **React context** so a subtree can override the active
+theme (this is what makes admin mode compose cleanly):
+
+```ts
+const SQLEditorThemeContext = createContext<SQLEditorTheme>(/* light */);
+const useSQLEditorTheme = () => useContext(SQLEditorThemeContext);
+```
+
+A `<SQLEditorThemeScope theme={…}>` component does two things for whatever it wraps:
+1. provides the theme via context (so descendants can read `theme.monacoBase` / the
+ Monaco theme name), and
+2. applies the theme's `tokens` as inline CSS custom properties on its container
+ element. Because every SQL Editor component uses the semantic Tailwind classes,
+ the subtree re-themes via CSS cascade.
+
+**Root scope.** Wrap the SQL Editor at the **layout level** — `SQLEditorLayout`,
+around both the route content (`SQLEditorRouteShell` → `SQLEditorHomePage`) **and**
+`RequestDrawerHost` (`SQLEditorLayout.tsx:62`) — in a `SQLEditorThemeScope` whose theme
+is the selected preset (from `useSQLEditorEditorStore.themeId`). The rest of Bytebase
+keeps the global `:root` values; only the SQL Editor subtree is re-themed. (An earlier
+draft scoped only `.sqleditor--wrapper`; that misses SQL-Editor UI rendered outside that
+subtree — see **Portals & sibling hosts** below.)
+
+**Portals & sibling hosts.** Scoped CSS variables re-theme via **DOM cascade**, but
+React portals mount their DOM elsewhere: **React context still propagates through a
+portal, CSS custom properties do not.** Several SQL-Editor surfaces render outside the
+chrome DOM subtree and would otherwise keep the global (light) `:root` tokens under a
+dark/named theme:
+
+- `SQLEditorHomePage` portals the mobile FAB and the sidebar overlay to
+ `getLayerRoot("overlay")` (`SQLEditorHomePage.tsx:160-182, 191-208`).
+- `AccessGrantRequestDrawer` (rendered by `RequestDrawerHost`, `RequestDrawerHost.tsx:74`)
+ is a `Sheet` that portals to the overlay layer **and** hosts its own `MonacoEditor`
+ (`AccessGrantRequestDrawer.tsx:262`).
+
+The layer roots are **app-global** (shared with the rest of Bytebase), so we cannot wrap
+them in a SQL-Editor-only scope. Instead, each portaled SQL-Editor surface re-applies the
+**chrome** theme on its own container: wrap the portal's children in a nested
+`SQLEditorThemeScope` whose theme comes from `useSQLEditorTheme()` (read through the
+context that the portal preserves) so it re-writes the `--color-*` vars onto the portaled
+DOM. For the request drawer this re-themes its `Sheet` chrome (form controls, labels).
+Its embedded **Monaco**, however, cannot have its own theme — Monaco's theme is global
+(see **Monaco** below); the drawer's editor shares the one active Monaco theme. No new
+global *chrome* theming — only the specific SQL-Editor portal subtrees re-apply vars.
+
+**Portal coverage for v1 (scope decision).** The portal inventory is larger than the
+FAB/sidebar + drawer: other SQL-Editor surfaces also mount under the app-global overlay
+root — the custom hover panels (`DatabaseHoverPanel`, `SchemaPane/HoverPanel`), the
+`RequestRoleSheet` (same `RequestDrawerHost` path), and **Base-UI-internal** popups
+(`ConnectChooser`'s `Select` dropdown, `EllipsisCell`'s tooltip). For the first ship we
+wrap **our own** `createPortal`/`Sheet` surfaces (overlays, drawer, RequestRoleSheet,
+hover panels) in a nested scope. The Base-UI-internal popups portal through shared `ui/*`
+primitives and can't be re-scoped per-SQL-Editor without touching app-wide components, so
+they are a **tracked follow-up** — under a dark/named theme they may briefly show the
+default (light) tokens. Visual tests (§ Testing) enumerate covered vs deferred surfaces.
+(If app-scope chrome lands later, the whole portal problem disappears: tokens applied at
+app root cascade into the shared overlay root automatically.)
+
+**Nested admin scope.** Wrap `<TerminalPanel>`'s root div (`TerminalPanel.tsx:206`) in a
+nested `SQLEditorThemeScope` whose theme is the **resolved admin theme**:
+
+```ts
+resolveAdminTheme(selected) = selected.monacoBase === "vs-dark" ? selected : presets.dark;
+```
+
+Its inline CSS-var overrides win over the parent scope for the terminal subtree (CSS
+cascade), so the terminal + its `ResultView`s render dark (or in the selected dark
+theme), while the surrounding chrome keeps the selected theme. Worksheet mode renders
+under the root scope only — no nesting.
+
+This is the **replacement for the `dark` boolean prop**: `ResultView` reads nothing —
+its styling comes entirely from the scope's tokens rather than `dark:` variants or a
+boolean. (As shipped, `ResultView` keeps only a `compact` prop, which is a terminal-vs-
+worksheet *layout* difference, not a theme one.) The `dark` prop and the
+`dark && "dark bg-dark-bg"` class at `ResultView.tsx:237` are removed; `TerminalPanel`'s
+hardcoded `bg-dark-bg` becomes the token-driven `bg-background` (the nested dark theme
+sets `--color-background` to the dark value).
+
+**Monaco.** In `monaco/core.ts`, register one Monaco theme **per preset** via
+`buildMonacoTheme(preset)`, which maps the preset's `editor` colors → Monaco `colors{}`
+and its `syntax` palette → Monaco token `rules[]` (including SQL scopes). This replaces
+the current `callCssVariable()`/`:root` reads — required because Monaco is
+canvas-rendered and cannot see container-scoped CSS overrides, and because named themes
+carry their own syntax colors rather than tinting `vs`/`vs-dark`. All six themes are
+defined at init (`monaco.editor.defineTheme(\`bb-${id}\`, …)`).
+
+**The Monaco theme is a single global value — it cannot be per-scope.**
+`monaco.editor.setTheme` applies to **all** standalone editors at once; Monaco has no
+per-instance theme. So unlike the chrome (which is genuinely per-scope via CSS cascade),
+every visible Monaco editor shares **one** theme. Concretely, more than one Monaco can be
+on screen simultaneously: the access-request drawer hosts its own editor
+(`AccessGrantRequestDrawer.tsx:262`) and can be open **over** an admin terminal — so a
+"one code panel at a time" assumption does **not** hold.
+
+The SQL Editor therefore maintains **one active Monaco theme**, derived from the
+**foreground code surface**: worksheet → the **selected** theme; admin →
+`resolveAdminTheme(selected)` (`useActiveSQLEditorTheme()`). It is applied two ways that
+agree on the value:
+
+- The SQL-Editor editors (`StandardPanel/SQLEditor`, `TerminalPanel/CompactSQLEditor`,
+ and the drawer's editor) pass an explicit `theme` option = `monacoThemeName(active)`,
+ so the shared `MonacoEditor` sets the right theme on construction (no `bb-light`
+ flash). `CompactSQLEditor` drops its hardcoded `theme: "vs-dark"` for this.
+- A single controller hook `useMonacoThemeController()` (mounted once at the SQL-Editor
+ root) re-applies the active theme on `themeId`/`mode` change via
+ `monaco.editor.setTheme(getResolvedTheme(monacoThemeName(active)))` — covering live
+ switches while editors stay mounted.
+
+`getResolvedTheme` is **mandatory** here: in runtime modes where the vscode theme-service
+override prevents a custom theme from registering (`initializeTheme` only adds a name to
+`registeredThemes` after `defineTheme` succeeds), calling `setTheme` with an unregistered
+name is a silent no-op; `getResolvedTheme` falls back to the always-available
+`bb-light`/`vs`, so a named theme can never leave Monaco stuck on a stale theme.
+
+**Boundary & non-SQL Monaco (scope decision).** `setTheme` is global, but the shared
+`MonacoEditor` is **left unchanged**: editors that pass no explicit theme — every non-SQL
+Monaco surface in the app — keep resetting to the default `bb-light` on construction. So
+while the SQL Editor is mounted the controller owns the global Monaco theme; elsewhere
+each editor resets itself. **Containment guarantee:** `useMonacoThemeController` also
+resets the global Monaco theme back to `bb-light` on **unmount** (a separate `[]`-effect
+cleanup), so the SQL Editor's selected theme never lingers on app-scope Monaco after the
+user leaves — covering even an already-mounted/kept-alive non-SQL editor that wouldn't
+re-run its own construction reset. Because the SQL Editor is a full-page view, non-SQL
+Monaco is never on screen alongside it, so this split is invisible in normal navigation —
+no app-wide Monaco change is needed now. (Monaco's hard limit: two editors visible at the
+same instant cannot have different themes — there is one global theme. This never occurs
+here because the SQL Editor doesn't share the screen with another Monaco surface.) App-level Monaco (all editors follow the preference)
+was considered and **rejected for v1**: it would require coupling the shared `MonacoEditor`
+to the theme preference + an app-root controller + an app-level store — broad blast radius
+for a benefit that is only theoretical today. See **Extensibility to app scope** (Future
+work) for the small lift path.
+
+When the access drawer is open, its Monaco **adopts the active theme** (passes the same
+active Monaco name), so it never competes with the terminal for the global theme.
+Consequence: opening the drawer over a light-selected admin tab shows a dark statement
+editor (matching the visible terminal) — acceptable, since per-editor Monaco themes are
+impossible.
+
+### 5. Color migration (prerequisite)
+
+Scoped overrides only reach components that use the tokens. The following bypass them
+and must be migrated. Two rules:
+
+1. Replace raw palette classes / inline colors with the semantic token equivalent.
+2. **Delete `dark:`-prefixed variants** — dark theming now flows through token
+ *values* supplied by the active (root or nested) theme scope, not a global `.dark`
+ class. The `dark` boolean prop threaded through `ResultView` is removed; the rare
+ consumer that needs the Monaco family reads `useSQLEditorTheme().monacoBase`, but no
+ component branches colors on a boolean. In admin mode the result grid renders dark because it
+ sits inside the nested admin scope, not because of `dark:` classes.
+
+**Result views (currently `dark:`-driven):**
+- `ResultView/VirtualDataTable.tsx` — lines 271, 275, 311, 313, 397, 436, 496
+ (grid borders, header bg/text/hover, data cells, resize handle)
+- `ResultView/VirtualDataBlock.tsx` — lines 147, 153, 166, 237
+ (block title/content/card bg, delete button)
+- `ResultView/SelectionCopyTooltips.tsx` — lines 56, 62, 75, 153
+ (selection toolbar, info icon, copy button, menu item)
+- `ResultView/SingleResultView.tsx` — lines 602, 617 (copy-cell buttons)
+- `ResultPanel/DatabaseQueryContext.tsx` — lines 75, 93 (`bg-white/80` +
+ `dark:bg-black/80` overlays → token-based overlay)
+
+**Standard-mode raw palette colors:**
+- `ConnectionPane/DatabaseHoverPanel/DatabaseHoverPanel.tsx` — 97, 114, 124, 133, 142, 149
+- `ConnectionPane/ConnectionPane.tsx` — 680 (`bg-white/75` loading overlay)
+- `SQLEditorHomePage.tsx` — 164 (`bg-white` FAB), 194 (`bg-black/40` backdrop)
+- `SQLEditorLayout.tsx` — 58 (debug panel; low priority, dev-only)
+- `SchemaPane/FlatTableList.tsx` — 169, 174, 206, 209, 218, 221, 227, 228, 237, 240
+- `SchemaPane/TreeNode/icons.tsx` — 43, 54, 59, 71, 87, 91, 126
+- `SchemaPane/HoverPanel/HoverPanel.tsx` — 142; `HoverPanel/InfoItem.tsx` — 22
+- `SharePopoverBody.tsx` — 182, 197, 198, 236, 247
+- `Panels/common/EllipsisCell.tsx` — 70 (`bg-gray-900 text-white` tooltip)
+
+**Inline rgb/hex — keep as-is (dynamic, not theme tokens):**
+- `ConnectionPane/TreeNode/Label.tsx` 90–91, `TabItem/TabItem.tsx` 72/77/78,
+ `ResultPanel/BatchQuerySelect.tsx` 451–455 — these derive from per-environment
+ colors and the indigo fallback; out of scope for theming.
+- `AccessGrantItem.tsx` 233–234 — animation keyframe; leave unless it clashes on dark.
+
+**Admin / terminal — now themed via the nested scope (not pinned):**
+- `TerminalPanel/TerminalPanel.tsx` — outermost `bg-dark-bg` (206) and inner
+ `bg-dark-bg` (208) become `bg-background`; wrap the root div in the nested
+ `SQLEditorThemeScope` (resolved admin theme). Overlays at 246 (`bg-black/20`), 251
+ (`text-gray-400`) route through tokens.
+- `CompactSQLEditor.tsx:323` — drop hardcoded `theme: "vs-dark"`; let the global Monaco
+ controller (§4 → Monaco) drive the theme.
+- The result-view `dark:` variants listed above are removed here too — in admin mode
+ they now get dark token *values* from the nested scope. The admin terminal is no
+ longer a special-cased aesthetic; it is just the resolved admin theme applied to a
+ nested scope.
+
+### 6. Switcher UI
+
+Add a preset selector using the shared React `Select` (a dropdown — preferred over a
+radio group now that the catalog has six entries). It is its own small component
+`ThemeSelect` placed in **`EditorAction.tsx`**'s `action-right` group (next to
+`ChooserGroup` / `OpenAIButton`).
+
+> **Why not `QueryContextSettingPopover` (the original draft target):** that popover
+> early-returns `null` in admin mode (`currentTabMode !== "ADMIN"`), so a switcher there
+> would disappear in exactly the mode we are theming. `EditorAction` is rendered by
+> **both** `StandardPanel` and `TerminalPanel`, and its `action-right` group is always
+> visible — so the theme control is reachable in worksheet and admin alike.
+
+Options are driven off the `PRESETS` array (so adding a theme needs no UI change). Each
+label uses the preset's `name` i18n key; built-in palette names (Solarized, Monokai,
+Nord) are proper nouns and stay untranslated as values. The current value and `onChange`
+bind to `useSQLEditorEditorState((s) => s.themeId)` / `setThemeId`.
+
+## Data flow
+
+CHROME (per-scope, CSS cascade):
+```
+localStorage ──load──▶ useSQLEditorEditorStore.themeId ──set by──▶ QueryContextSettingPopover (Select)
+ │
+ ▼
+ Root SQLEditorThemeScope at SQLEditorLayout (selected preset)
+ · inline --color-* on the layout container → CSS cascade re-themes chrome
+ · provides theme via context (reaches RequestDrawerHost + portals)
+ │
+ ┌──────────────────┬───────┴───────────────────┬───────────────────────────┐
+ ▼ (worksheet tab) ▼ (admin tab) ▼ (overlay portals + request drawer)
+ root scope only Nested SQLEditorThemeScope Nested SQLEditorThemeScope per portal
+ (selected tokens) theme=resolveAdminTheme(sel) · context read via useSQLEditorTheme()
+ · --color-* on TerminalPanel (portals preserve context, not CSS)
+ root (overrides parent) · re-applies --color-* on portaled DOM
+ · ResultView is token-driven (drawer Sheet chrome, FAB, sidebar)
+ (compact prop = layout only)
+```
+
+MONACO (single global, driven by foreground panel — cannot be per-scope):
+```
+{ tab mode, selected themeId } ──▶ active = mode==="ADMIN" ? resolveAdminTheme(sel) : sel
+ │
+ ▼
+ monaco.editor.setTheme(`bb-${active.id}`) // one global theme
+ │
+ ┌─────────────────────────┼─────────────────────────┐
+ ▼ ▼ ▼
+ worksheet/terminal editor drawer's Monaco (if open) any other Monaco
+ ── all share the one active theme ──
+```
+
+## Testing
+
+- **Unit:** `validateTheme()` passes for **all six** presets (every required chrome
+ token, every `editor` key, every `syntax` key present — no holes);
+ `themeToCssVars(theme)` (the helper `SQLEditorThemeScope` uses) returns the correct
+ `CSSProperties` for a given theme;
+ `buildMonacoTheme` maps `editor`/`syntax` onto Monaco `colors`/`rules` correctly;
+ store persists/restores `themeId` and falls back to `light` on invalid input.
+- **Component:** rendering `sqleditor--wrapper` with each preset applies the expected
+ CSS vars; switching `themeId` updates them. `resolveAdminTheme` returns the selected
+ theme when dark and `dark` when light. A nested `SQLEditorThemeScope` overrides the
+ parent's CSS vars for its subtree.
+- **Manual/visual:** Light preset is visually identical to current `main`; each of the
+ other five renders chrome + result grid + Monaco coherently (no un-themed islands,
+ syntax colors match the named theme's identity). Admin mode: with a light theme
+ selected, the terminal subtree is dark while chrome stays light; with a dark theme
+ selected, the terminal matches it. With a non-light theme selected, also confirm the
+ **portaled** surfaces theme correctly: the mobile FAB + sidebar overlay, and the
+ access-request drawer (`AccessGrantRequestDrawer`) **chrome** — none should fall back to
+ light. Drawer-Monaco conflict: open the drawer over an admin terminal and confirm
+ neither editor flickers/ends on the wrong theme — both share the one active global
+ Monaco theme (the documented trade-off), not a fight that leaves one wrong.
+ Checked through `pnpm --dir frontend dev`.
+- Gates: `pnpm --dir frontend fix`, `check`, `type-check`, `test`.
+
+## Risks
+
+- **Migration breadth (Section 5) is the bulk of the work and the main risk.** Missing
+ an offender shows up as an un-themed element on dark. Mitigate by grepping for
+ `dark:`, `-gray-`, `-zinc-`, `-slate-`, `bg-white`, `bg-black` under the SQL Editor
+ tree after migration and confirming zero remain (excluding the admin terminal and
+ the documented dynamic/animation cases).
+- **Portals break CSS-variable cascade.** Surfaces portaled to the app-global layer
+ roots (mobile FAB / sidebar overlay) and the `RequestDrawerHost` sibling (incl. its
+ Monaco) do not inherit the chrome scope's `--color-*` by DOM cascade. Mitigate by
+ raising the root scope to `SQLEditorLayout` (context reaches the drawer) and wrapping
+ each portal's children in a nested `SQLEditorThemeScope` that re-applies the vars (it
+ reads the theme via the context the portal preserves). Verify each portaled surface
+ under a dark/named theme; a missed portal renders light-on-dark.
+- **Removing the `dark` prop / nested admin scope.** `ResultView` is shared between
+ worksheet and terminal; after dropping the prop it must read the theme from context.
+ Verify: (a) worksheet result grid follows the selected theme, (b) terminal result grid
+ is dark via the nested scope, (c) entering/leaving admin mid-session re-themes both the
+ chrome boundary and Monaco, (d) the nested scope's CSS-var override actually wins over
+ the root scope for the whole terminal subtree (no leaked light tokens).
+- **Monaco theme generation** replaces `callCssVariable` reads; confirm the generated
+ `bb`-equivalent matches the current editor look pixel-for-pixel on light.
+- **Monaco's theme is global, not per-instance.** Multiple editors can be visible at once
+ (terminal + access-drawer Monaco), but `setTheme` repaints all of them. The design
+ resolves this by driving one global theme from the foreground panel and having the
+ drawer adopt it (§4 → Monaco), rather than per-editor themes (impossible in Monaco).
+ Risk if implemented naively as "each editor sets its own theme": last-writer-wins
+ flicker / wrong theme. The single-controller approach must own every `setTheme` call;
+ no component should call `setTheme` independently.
+- **Named-theme authoring fidelity.** Six palettes (incl. four named themes with full
+ syntax sets) must be derived from published references and checked against contrast
+ needs for both chrome text and result-grid readability. This is real per-theme design
+ effort and the second-largest cost after the migration. Author each as its own file
+ so they can be reviewed/tuned independently; the `validateTheme()` test guards
+ structural completeness but not aesthetic quality — that needs a visual pass.
+
+## Future work (out of scope)
+
+- Custom theme editor (color pickers / JSON), validation, and storage of arbitrary
+ palettes. The model already supports it — only UI + persistence of custom objects
+ is missing.
+- "System" preset following `prefers-color-scheme`.
+- Backend/cross-device persistence of the theme choice.
+- The deferred Base-UI-internal portal popups (ConnectChooser dropdown, EllipsisCell
+ tooltip) — re-scope their content under a dark/named theme.
+
+### Extensibility to app scope
+
+The architecture is deliberately **liftable to app-wide** with a small, well-understood
+change — not a rewrite — should that ever be wanted (a maintainer raised it; deferred as
+out of scope for v1 to keep complexity/time down):
+
+- **Chrome.** `SQLEditorThemeScope` and the token model already override the *global*
+ `--color-*` names. Lifting = mount the scope at the app root instead of the SQL-Editor
+ container. As a bonus, the portal problem vanishes (tokens at app root cascade into the
+ shared overlay root).
+- **Monaco.** Move `useMonacoThemeController()` from the SQL-Editor root to the app root,
+ and change the shared `MonacoEditor`'s construction-time reset to use the active
+ preference instead of the hardcoded `bb-light` default — then every Monaco surface
+ follows the preference.
+- **Preference.** Move `themeId` from the SQL-Editor store to an app-level (workspace/
+ user-scoped) store, and relocate the switcher from the editor toolbar to a global
+ appearance/settings surface.
+
+Each step is independent and the token/preset/scope code is unchanged.
+
+## Open questions
+
+1. Exact palette values for `dark` and the four named themes — the tables/references
+ above are starting points; confirm chrome + syntax values visually during
+ implementation.
+2. Ordering of presets in the switcher dropdown (proposed: Default Light, Default Dark,
+ Solarized Light, Solarized Dark, Monokai, Nord).
+3. Admin scope when the selected theme is light: falls back to `dark` (decided). Confirm
+ that picking a *dark* theme and entering admin simply keeps that theme (no separate
+ "terminal" identity / matrix-green) — assumed yes.