Skip to content

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

refactor(react): schema visualizer (#20344)

ecmadaob8e8863363fa
diff --git a/docs/superpowers/specs/2026-05-13-explain-visualizer-react-migration-design.md b/docs/superpowers/specs/2026-05-13-explain-visualizer-react-migration-design.md
new file mode 100644
index 0000000000..d040d7f60a
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-13-explain-visualizer-react-migration-design.md
@@ -0,0 +1,116 @@
+# Explain Visualizer — Vue → React Migration
+
+**Date:** 2026-05-13
+**Scope:** `frontend/explain-visualizer.html` standalone entry and everything it transitively renders.
+**Status:** Implementation in progress (uncommitted; will land in the same PR as other Stage 22 work).
+
+## Context
+
+The Explain Visualizer is a standalone Vite entry (`frontend/explain-visualizer.html` → `frontend/src/explain-visualizer-main.ts`) that renders SQL EXPLAIN output passed via a `?token=...` URL parameter. The token is a `sessionStorage` handle to `{ statement, explain, engine }` stashed by `createExplainToken` in `frontend/src/utils/pev2.ts` and is opened in a separate browser tab from the SQL Editor's result view.
+
+The page dispatches on engine:
+
+| Engine | Renderer | Source |
+| --- | --- | --- |
+| Postgres | `pev2` npm package (Vue component) | external lib |
+| MSSQL | `window.QP.showPlan` from `/libs/qp.min.js` | external lib, dynamic load |
+| Spanner | Custom recursive tree (`SpannerQueryPlan` + `SpannerPlanNode`) | repo-local Vue |
+| anything else | "Unsupported engine" fallback | inline |
+
+This is the last self-contained Vue surface in the project; the SQL Editor result view that *opens* this window is already React, so closing the gap removes a Vue island in an otherwise React-leaning area.
+
+## Surface inventory
+
+Vue files in scope:
+
+- `frontend/src/ExplainVisualizerApp.vue` (156 lines) — engine dispatch + MSSQL imperative mount via `onMounted`
+- `frontend/src/components/SpannerQueryPlan/SpannerQueryPlan.vue` — wrapper, parses JSON `planSource`, finds root node by `index === 0`
+- `frontend/src/components/SpannerQueryPlan/SpannerPlanNode.vue` — recursive node with expand/collapse, kind badge, metadata
+- `frontend/src/components/SpannerQueryPlan/types.ts` — pure TS, framework-agnostic
+- `frontend/src/components/SpannerQueryPlan/index.ts` — barrel
+- `frontend/src/explain-visualizer-main.ts` — Vue `createApp(...).mount("body")`
+
+Cross-boundary helpers that stay as-is (no Vue deps already):
+
+- `frontend/src/utils/pev2.ts` — `createExplainToken` / `readExplainFromToken` (`sessionStorage` only). Already consumed by both Vue (current) and React (`SingleResultView.tsx`).
+- `frontend/src/types/proto-es/v1/common_pb` — `Engine` enum.
+
+Live callers of the in-scope Vue files: **none outside the explain-visualizer entry chain.** `rg` over `frontend/src` confirmed `pev2` (npm), `SpannerQueryPlan`, and `html-query-plan` are referenced only from `ExplainVisualizerApp.vue` and `SpannerQueryPlan/`. Safe to delete all of them at the end of this migration per the playbook deletion rule.
+
+## Strategy
+
+### Postgres — Vue island for `pev2`
+
+`[email protected]` is a Vue 3 `defineComponent`. There is no maintained React port and reimplementing the Postgres EXPLAIN renderer is well out of scope. Mount a tiny Vue subapp inside a React component:
+
+```tsx
+function PostgresPlanView({ planSource, planQuery }: Props) {
+ const hostRef = useRef<HTMLDivElement>(null);
+ useEffect(() => {
+ if (!hostRef.current) return;
+ const app = createApp(pev2, { planSource, planQuery });
+ app.mount(hostRef.current);
+ return () => app.unmount();
+ }, [planSource, planQuery]);
+ return <div ref={hostRef} className="size-full" />;
+}
+```
+
+Trade-off: Vue runtime stays in this entry's bundle. Since pev2 transitively requires Vue, that cost exists even today — this approach adds no new runtime weight, just a wrapper shim.
+
+### MSSQL — pure React + dynamic load
+
+`html-query-plan` exposes a global `window.QP.showPlan(container, planXml)`. The Vue version dynamically injects `/libs/qp.min.js` once and then calls `showPlan` in `onMounted`. Translate that 1:1 into a `useEffect` with a `ref`. Move the dynamic-load helper out of the component to keep the effect clean and let it be reused if a second caller ever needs it.
+
+### Spanner — pure React port
+
+Direct translation:
+
+- `SpannerQueryPlan.vue` → `SpannerQueryPlan.tsx`: `useMemo` for `planNodes` and `rootNode`.
+- `SpannerPlanNode.vue` → `SpannerPlanNode.tsx`: `useState(true)` for `expanded`, `useMemo` for the derived computeds. Recurses on itself like the Vue version.
+- Icons: swap `lucide-vue-next` → `lucide-react`.
+
+The original scoped CSS is preserved verbatim by importing a sibling `.css` file (these are not theme-aware tokens — they're standalone visual styling for a dedicated page). Keeping the original CSS avoids visual regressions and keeps the diff focused on framework migration.
+
+### Entry point
+
+Replace `createApp(...).mount("body")` with React's `createRoot(...).render(...)`. React requires a real container, so update the HTML to add a `<div id="app">` and mount there. Move the entry to `frontend/src/react/explain-visualizer/main.tsx` so the file lives where the `react-tsx-transform` Vite plugin already picks it up — no Vite config changes required.
+
+The HTML's `<script src="...">` updates to the new path. The Vite entry key (`explain-visualizer`) stays the same.
+
+### i18n
+
+The Vue version uses zero locale keys for its visible strings (`"Query Plan"`, `"Unsupported Database Engine"`, etc. are hardcoded English in the template). The visualizer is a single-purpose dev-tooling page that opens English-only `pev2` and `html-query-plan` UIs underneath it; adding i18n now would be scope creep and inconsistent with the embedded third-party UI. **Leave strings hardcoded** to preserve current behavior; can be promoted to locale keys in a follow-up if a translation request lands.
+
+## File mapping
+
+| Vue (current) | React (target) |
+| --- | --- |
+| `frontend/src/explain-visualizer-main.ts` | `frontend/src/react/explain-visualizer/main.tsx` |
+| `frontend/src/ExplainVisualizerApp.vue` | `frontend/src/react/explain-visualizer/ExplainVisualizerApp.tsx` |
+| (PG branch inline) | `frontend/src/react/explain-visualizer/PostgresPlanView.tsx` |
+| (MSSQL branch inline) | `frontend/src/react/explain-visualizer/MSSQLPlanView.tsx` + `loadQueryPlanScript.ts` helper |
+| `frontend/src/components/SpannerQueryPlan/SpannerQueryPlan.vue` | `frontend/src/react/explain-visualizer/SpannerQueryPlan.tsx` |
+| `frontend/src/components/SpannerQueryPlan/SpannerPlanNode.vue` | `frontend/src/react/explain-visualizer/SpannerPlanNode.tsx` |
+| `frontend/src/components/SpannerQueryPlan/types.ts` | `frontend/src/react/explain-visualizer/spanner-types.ts` |
+| `frontend/src/components/SpannerQueryPlan/index.ts` | (deleted; no callers left) |
+| `frontend/explain-visualizer.html` (mount body, ts entry) | same file, edited to add `<div id="app">` + point at the new `.tsx` entry |
+
+## Verification
+
+Minimum gate sequence per the migration playbook:
+
+1. `pnpm --dir frontend fix`
+2. `pnpm --dir frontend check`
+3. `pnpm --dir frontend type-check` (vue-tsc for Vue, separate React tsconfig for the new React tree)
+4. `pnpm --dir frontend test`
+
+Add a focused unit test for `SpannerPlanNode` (recursion, expand/collapse, metadata filtering) since the recursive tree is the largest piece of net-new React code in this migration.
+
+Manual smoke (can only be done from the SQL Editor UI in a running dev environment): run an `EXPLAIN` on each of Postgres / MSSQL / Spanner and confirm the new tab renders correctly. Listed as a follow-up the user will do; no Playwright in scope.
+
+## Risk and rollback
+
+- `pev2` Vue-island approach is reversible by reverting the migration commit — no Vite/Vue/React config changes are required to keep the surface working.
+- The Spanner CSS port preserves classnames so visual regressions, if any, are pinpointable.
+- No deletions until the React surface is verified locally; the playbook's "verify no live callers before deleting" check is already complete for the Spanner dir (no callers outside this entry).
diff --git a/frontend/explain-visualizer.html b/frontend/explain-visualizer.html
index b318135b2c..ead311d81a 100644
--- a/frontend/explain-visualizer.html
+++ b/frontend/explain-visualizer.html
@@ -8,6 +8,10 @@
</head>
<body class="text-base">
- <script type="module" src="/src/explain-visualizer-main.ts"></script>
+ <div id="app"></div>
+ <script
+ type="module"
+ src="/src/react/explain-visualizer/main.tsx"
+ ></script>
</body>
</html>
diff --git a/frontend/src/ExplainVisualizerApp.vue b/frontend/src/ExplainVisualizerApp.vue
deleted file mode 100644
index 4f9c7b04ad..0000000000
--- a/frontend/src/ExplainVisualizerApp.vue
+++ /dev/null
@@ -1,156 +0,0 @@
-<template>
- <div id="app" class="d-flex">
- <template v-if="storedQuery">
- <!-- PostgreSQL visualization using pev2 -->
- <pev2
- v-if="isPostgreSQL"
- :plan-source="storedQuery.explain"
- :plan-query="storedQuery.statement"
- />
- <!-- MSSQL visualization using html-query-plan -->
- <div
- v-else-if="isMSSQL"
- ref="mssqlContainer"
- class="mssql-query-plan-container"
- />
- <!-- Spanner visualization -->
- <SpannerQueryPlan
- v-else-if="isSpanner"
- :plan-source="storedQuery.explain"
- :plan-query="storedQuery.statement"
- />
- <!-- Fallback for unsupported engines -->
- <div v-else class="unsupported-engine">
- <h2>Unsupported Database Engine</h2>
- <p>Query plan visualization is not available for this database engine.</p>
- </div>
- </template>
- <template v-else>
- <h1>session expired</h1>
- </template>
- </div>
-</template>
-
-<script setup lang="ts">
-import { Plan as pev2 } from "pev2";
-import "pev2/dist/pev2.css";
-import "html-query-plan/css/qp.css";
-import { parse } from "qs";
-import { computed, onMounted, ref } from "vue";
-import { SpannerQueryPlan } from "@/components/SpannerQueryPlan";
-import { Engine } from "@/types/proto-es/v1/common_pb";
-import { readExplainFromToken } from "@/utils/pev2";
-
-// Declare the global QP object from html-query-plan
-declare global {
- interface Window {
- QP: {
- showPlan: (
- container: Element,
- planXml: string,
- options?: Record<string, unknown>
- ) => void;
- };
- }
-}
-
-const token = computed(() => {
- const query = location.search.replace(/^\?/, "");
- return (parse(query).token as string) || "";
-});
-
-const storedQuery = computed(() => readExplainFromToken(token.value));
-
-const isPostgreSQL = computed(
- () => storedQuery.value?.engine === Engine.POSTGRES
-);
-const isMSSQL = computed(() => storedQuery.value?.engine === Engine.MSSQL);
-const isSpanner = computed(() => storedQuery.value?.engine === Engine.SPANNER);
-
-const mssqlContainer = ref<HTMLDivElement>();
-const qpLoaded = ref(false);
-
-// Load html-query-plan script dynamically
-const loadQueryPlanScript = () => {
- return new Promise<void>((resolve, reject) => {
- // Check if already loaded
- if (window.QP) {
- qpLoaded.value = true;
- resolve();
- return;
- }
-
- // Check if script already exists
- if (document.getElementById("html-query-plan-script")) {
- qpLoaded.value = true;
- resolve();
- return;
- }
-
- const script = document.createElement("script");
- script.id = "html-query-plan-script";
- script.src = "/libs/qp.min.js";
- script.onload = () => {
- qpLoaded.value = true;
- resolve();
- };
- script.onerror = () => {
- reject(new Error("Failed to load html-query-plan script"));
- };
- document.head.appendChild(script);
- });
-};
-
-onMounted(async () => {
- if (isMSSQL.value && mssqlContainer.value && storedQuery.value) {
- try {
- await loadQueryPlanScript();
- if (window.QP && mssqlContainer.value) {
- window.QP.showPlan(mssqlContainer.value, storedQuery.value.explain);
- }
- } catch (error) {
- console.error("Failed to load query plan visualizer:", error);
- }
- }
-});
-</script>
-
-<style>
-html,
-body,
-#app {
- height: 100%;
-}
-
-.mssql-query-plan-container {
- width: 100%;
- height: 100%;
- overflow: auto;
- padding: 16px;
-}
-
-.unsupported-engine {
- display: flex;
- flex-direction: column;
- align-items: center;
- justify-content: center;
- width: 100%;
- height: 100%;
- padding: 24px;
- text-align: center;
-}
-
-.unsupported-engine h2 {
- margin-bottom: 8px;
- color: #666;
-}
-
-.unsupported-engine p {
- color: #999;
-}
-
-.qp-root {
- width: 100%;
- height: 100%;
-}
-</style>
diff --git a/frontend/src/components/SpannerQueryPlan/SpannerPlanNode.vue b/frontend/src/components/SpannerQueryPlan/SpannerPlanNode.vue
deleted file mode 100644
index 0717737a34..0000000000
--- a/frontend/src/components/SpannerQueryPlan/SpannerPlanNode.vue
+++ /dev/null
@@ -1,256 +0,0 @@
-<template>
- <div class="plan-node" :class="{ 'is-scalar': isScalar }">
- <div class="node-content" @click="toggleExpanded">
- <span class="expand-icon" v-if="hasChildren">
- <ChevronDownIcon v-if="expanded" class="w-4" />
- <ChevronUpIcon v-else class="w-4" />
- </span>
- <span v-else class="expand-icon-placeholder"></span>
-
- <span class="node-kind" :class="kindClass">{{ node.kind }}</span>
- <span class="node-name">{{ node.displayName }}</span>
-
- <span v-if="shortDescription" class="node-description">
- {{ shortDescription }}
- </span>
- </div>
-
- <div v-if="hasMetadata" class="node-metadata">
- <div
- v-for="(value, key) in displayMetadata"
- :key="key"
- class="metadata-item"
- >
- <span class="metadata-key">{{ key }}:</span>
- <span class="metadata-value">{{ formatValue(value) }}</span>
- </div>
- </div>
-
- <div v-if="expanded && hasChildren" class="node-children">
- <div
- v-for="childLink in relationalChildLinks"
- :key="childLink.childIndex"
- class="child-wrapper"
- >
- <div v-if="childLink.type" class="child-link-type">
- {{ childLink.type }}
- </div>
- <SpannerPlanNode
- :node="getChildNode(childLink.childIndex)"
- :all-nodes="allNodes"
- :depth="depth + 1"
- />
- </div>
- </div>
- </div>
-</template>
-
-<script setup lang="ts">
-import { ChevronDownIcon, ChevronUpIcon } from "lucide-vue-next";
-import { computed, ref } from "vue";
-import type { SpannerChildLink, SpannerPlanNodeData } from "./types";
-
-const props = defineProps<{
- node: SpannerPlanNodeData;
- allNodes: SpannerPlanNodeData[];
- depth: number;
-}>();
-
-const expanded = ref(true);
-
-const isScalar = computed(() => props.node.kind === "SCALAR");
-
-const kindClass = computed(() => {
- switch (props.node.kind) {
- case "RELATIONAL":
- return "kind-relational";
- case "SCALAR":
- return "kind-scalar";
- default:
- return "kind-unknown";
- }
-});
-
-const hasChildren = computed(() => {
- return relationalChildLinks.value.length > 0;
-});
-
-// Only show relational children in the tree
-const relationalChildLinks = computed((): SpannerChildLink[] => {
- if (!props.node.childLinks) return [];
- return props.node.childLinks.filter((link) => {
- const childNode = props.allNodes.find((n) => n.index === link.childIndex);
- return childNode && childNode.kind === "RELATIONAL";
- });
-});
-
-const shortDescription = computed(() => {
- return props.node.shortRepresentation?.description;
-});
-
-const hasMetadata = computed(() => {
- return props.node.metadata && Object.keys(props.node.metadata).length > 0;
-});
-
-const displayMetadata = computed(() => {
- if (!props.node.metadata) return {};
- // Filter out some internal metadata keys
- const filtered: Record<string, unknown> = {};
- for (const [key, value] of Object.entries(props.node.metadata)) {
- if (!key.startsWith("_")) {
- filtered[key] = value;
- }
- }
- return filtered;
-});
-
-const toggleExpanded = () => {
- if (hasChildren.value) {
- expanded.value = !expanded.value;
- }
-};
-
-const getChildNode = (index: number): SpannerPlanNodeData => {
- const child = props.allNodes.find((n) => n.index === index);
- if (!child) {
- return {
- index,
- kind: "UNKNOWN",
- displayName: `Unknown Node (${index})`,
- };
- }
- return child;
-};
-
-const formatValue = (value: unknown): string => {
- if (value === null || value === undefined) return "null";
- if (typeof value === "object") {
- return JSON.stringify(value);
- }
- return String(value);
-};
-</script>
-
-<style scoped>
-.plan-node {
- margin-left: 0;
- font-size: 14px;
-}
-
-.plan-node.is-scalar {
- display: inline;
-}
-
-.node-content {
- display: flex;
- align-items: center;
- gap: 8px;
- padding: 6px 8px;
- border-radius: 4px;
- cursor: pointer;
- transition: background-color 0.15s ease;
-}
-
-.node-content:hover {
- background-color: #f0f4f8;
-}
-
-.expand-icon {
- width: 16px;
- font-size: 10px;
- color: #666;
- user-select: none;
-}
-
-.expand-icon-placeholder {
- width: 16px;
-}
-
-.node-kind {
- font-size: 11px;
- font-weight: 600;
- padding: 2px 6px;
- border-radius: 3px;
- text-transform: uppercase;
-}
-
-.kind-relational {
- background-color: #e3f2fd;
- color: #1565c0;
-}
-
-.kind-scalar {
- background-color: #f3e5f5;
- color: #7b1fa2;
-}
-
-.kind-unknown {
- background-color: #f5f5f5;
- color: #666;
-}
-
-.node-name {
- font-weight: 500;
- color: #333;
-}
-
-.node-description {
- font-family: "SF Mono", Monaco, Consolas, "Liberation Mono", "Courier New",
- monospace;
- font-size: 12px;
- color: #666;
- background-color: #f5f5f5;
- padding: 2px 6px;
- border-radius: 3px;
- max-width: 400px;
- overflow: hidden;
- text-overflow: ellipsis;
- white-space: nowrap;
-}
-
-.node-metadata {
- margin-left: 40px;
- margin-top: 4px;
- padding: 8px 12px;
- background-color: #fafafa;
- border-radius: 4px;
- border-left: 3px solid #e0e0e0;
-}
-
-.metadata-item {
- display: flex;
- gap: 8px;
- font-size: 12px;
- line-height: 1.6;
-}
-
-.metadata-key {
- font-weight: 500;
- color: #666;
-}
-
-.metadata-value {
- font-family: "SF Mono", Monaco, Consolas, "Liberation Mono", "Courier New",
- monospace;
- color: #333;
- word-break: break-all;
-}
-
-.node-children {
- margin-left: 24px;
- padding-left: 16px;
- border-left: 2px solid #e0e0e0;
-}
-
-.child-wrapper {
- margin-top: 4px;
-}
-
-.child-link-type {
- font-size: 11px;
- color: #999;
- margin-left: 8px;
- margin-bottom: 2px;
- font-style: italic;
-}
-</style>
diff --git a/frontend/src/components/SpannerQueryPlan/SpannerQueryPlan.vue b/frontend/src/components/SpannerQueryPlan/SpannerQueryPlan.vue
deleted file mode 100644
index 8ad713100a..0000000000
--- a/frontend/src/components/SpannerQueryPlan/SpannerQueryPlan.vue
+++ /dev/null
@@ -1,92 +0,0 @@
-<template>
- <div class="spanner-query-plan">
- <div class="plan-header">
- <h3>Query Plan</h3>
- <div v-if="query" class="query-text">{{ query }}</div>
- </div>
- <div class="plan-tree">
- <SpannerPlanNode
- v-if="rootNode"
- :node="rootNode"
- :all-nodes="planNodes"
- :depth="0"
- />
- <div v-else class="no-plan">No query plan available</div>
- </div>
- </div>
-</template>
-
-<script setup lang="ts">
-import { computed } from "vue";
-import SpannerPlanNode from "./SpannerPlanNode.vue";
-import type { SpannerPlanNodeData } from "./types";
-
-const props = defineProps<{
- planSource: string;
- planQuery?: string;
-}>();
-
-const query = computed(() => props.planQuery);
-
-const planNodes = computed((): SpannerPlanNodeData[] => {
- try {
- const parsed = JSON.parse(props.planSource);
- return parsed.planNodes || [];
- } catch {
- return [];
- }
-});
-
-const rootNode = computed((): SpannerPlanNodeData | undefined => {
- if (planNodes.value.length === 0) return undefined;
- // The first node (index 0) is the root node in Spanner query plans
- return planNodes.value.find((node) => node.index === 0);
-});
-</script>
-
-<style scoped>
-.spanner-query-plan {
- width: 100%;
- height: 100%;
- overflow: auto;
- padding: 16px;
- font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen,
- Ubuntu, Cantarell, "Open Sans", "Helvetica Neue", sans-serif;
-}
-
-.plan-header {
- margin-bottom: 16px;
- padding-bottom: 12px;
- border-bottom: 1px solid #e0e0e0;
-}
-
-.plan-header h3 {
- margin: 0 0 8px 0;
- font-size: 18px;
- font-weight: 600;
- color: #333;
-}
-
-.query-text {
- font-family: "SF Mono", Monaco, Consolas, "Liberation Mono", "Courier New",
- monospace;
- font-size: 13px;
- color: #666;
- background-color: #f5f5f5;
- padding: 8px 12px;
- border-radius: 4px;
- white-space: pre-wrap;
- word-break: break-word;
-}
-
-.plan-tree {
- padding: 8px 0;
-}
-
-.no-plan {
- color: #999;
- font-style: italic;
- padding: 16px;
- text-align: center;
-}
-</style>
diff --git a/frontend/src/components/SpannerQueryPlan/index.ts b/frontend/src/components/SpannerQueryPlan/index.ts
deleted file mode 100644
index b90040f2e0..0000000000
--- a/frontend/src/components/SpannerQueryPlan/index.ts
+++ /dev/null
@@ -1,2 +0,0 @@
-export { default as SpannerQueryPlan } from "./SpannerQueryPlan.vue";
-export * from "./types";
diff --git a/frontend/src/explain-visualizer-main.ts b/frontend/src/explain-visualizer-main.ts
deleted file mode 100644
index c28f94498b..0000000000
--- a/frontend/src/explain-visualizer-main.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-import "bootstrap/dist/css/bootstrap.css";
-import { createApp } from "vue";
-import ExplainVisualizerApp from "./ExplainVisualizerApp.vue";
-
-// Redefine global using globalThis
-(globalThis as typeof globalThis & Record<string, unknown>).global = globalThis;
-
-const app = createApp(ExplainVisualizerApp);
-
-app.mount("body");
diff --git a/frontend/src/react/components/instance/DataSourceForm.tsx b/frontend/src/react/components/instance/DataSourceForm.tsx
index 35154d8fb0..c8bad8d8e1 100644
--- a/frontend/src/react/components/instance/DataSourceForm.tsx
+++ b/frontend/src/react/components/instance/DataSourceForm.tsx
@@ -783,17 +783,15 @@ export function DataSourceForm({
<div className="sm:col-span-3 sm:col-start-1">
<label className="textlabel flex items-center gap-x-1">
{t("common.username")}
- {isCreating &&
- onOpenInfoPanel &&
- hasAuthenticationInfo && (
- <button
- type="button"
- className="inline-flex items-center gap-x-0.5 text-accent text-xs"
- onClick={() => onOpenInfoPanel("authentication")}
- >
- <Info className="size-3.5" />
- </button>
- )}
+ {onOpenInfoPanel && hasAuthenticationInfo && (
+ <button
+ type="button"
+ className="inline-flex items-center gap-x-0.5 text-accent text-xs"
+ onClick={() => onOpenInfoPanel("authentication")}
+ >
+ <Info className="size-3.5" />
+ </button>
+ )}
</label>
<Input
value={dataSource.username}
@@ -1703,7 +1701,7 @@ export function DataSourceForm({
<div className="sm:col-span-3 sm:col-start-1">
<div className="flex items-center justify-start gap-x-2 textlabel">
{t("data-source.ssl.connection-security")}
- {isCreating && onOpenInfoPanel && hasSslInfo && (
+ {onOpenInfoPanel && hasSslInfo && (
<button
type="button"
className="inline-flex items-center gap-x-0.5 text-accent text-xs"
@@ -1827,7 +1825,7 @@ export function DataSourceForm({
<label className="textlabel block">
{t("data-source.ssh-connection")}
</label>
- {isCreating && onOpenInfoPanel && hasSshInfo && (
+ {onOpenInfoPanel && hasSshInfo && (
<button
type="button"
className="inline-flex items-center gap-x-0.5 text-accent text-xs"
diff --git a/frontend/src/react/components/instance/InstanceFormBody.tsx b/frontend/src/react/components/instance/InstanceFormBody.tsx
index e902795882..b40a1c46aa 100644
--- a/frontend/src/react/components/instance/InstanceFormBody.tsx
+++ b/frontend/src/react/components/instance/InstanceFormBody.tsx
@@ -1374,7 +1374,7 @@ export function InstanceFormBody({ onOpenInfoPanel }: InstanceFormBodyProps) {
{basicInfo.engine !== Engine.DYNAMODB && (
<span className="text-error"> *</span>
)}
- {isCreating && onOpenInfoPanel && hasHostInfo && (
+ {onOpenInfoPanel && hasHostInfo && (
<button
type="button"
className="ml-1 inline-flex items-center gap-x-0.5 text-accent text-xs"
diff --git a/frontend/src/react/components/sql-editor/StandardPanel/SQLEditor.tsx b/frontend/src/react/components/sql-editor/StandardPanel/SQLEditor.tsx
index 6c02b5b8e5..4c4c6880e9 100644
--- a/frontend/src/react/components/sql-editor/StandardPanel/SQLEditor.tsx
+++ b/frontend/src/react/components/sql-editor/StandardPanel/SQLEditor.tsx
@@ -1,4 +1,4 @@
-import type { IDisposable, IRange } from "monaco-editor";
+import type { IRange } from "monaco-editor";
import * as monaco from "monaco-editor";
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { v1 as uuidv1 } from "uuid";
@@ -279,32 +279,27 @@ export function SQLEditor({ onExecute }: SQLEditorProps) {
});
// ----- ExplainQuery action (engine-conditional) -----
- const explainActionRef = useRef<IDisposable | null>(null);
+ // Depend on state-backed `monacoState`/`editorState` (not refs) so the
+ // effect re-runs after `handleReady` publishes them. Refs alone don't
+ // trigger re-renders, which previously left this action unregistered.
useEffect(() => {
- const editor = editorRef.current;
- const m = monacoRef.current;
- if (!editor || !m || engine === undefined) return;
- explainActionRef.current?.dispose();
- explainActionRef.current = null;
-
+ if (!editorState || !monacoState || engine === undefined) return;
const allows =
instanceV1AllowsExplain(engine) || engine === Engine.BIGQUERY;
if (!allows) return;
const isBigQuery = engine === Engine.BIGQUERY;
- const action = editor.addAction({
+ const action = editorState.addAction({
id: "ExplainQuery",
label: isBigQuery ? "Dry Run Query" : "Explain Query",
- keybindings: [m.KeyMod.CtrlCmd | m.KeyCode.KeyE],
+ keybindings: [monacoState.KeyMod.CtrlCmd | monacoState.KeyCode.KeyE],
contextMenuGroupId: "operation",
contextMenuOrder: 0,
run: () => runQueryAction({ explain: true, newTab: false }),
});
- explainActionRef.current = action;
return () => {
action.dispose();
- explainActionRef.current = null;
};
- }, [engine, runQueryAction]);
+ }, [engine, runQueryAction, editorState, monacoState]);
// ----- pendingInsertAtCaret -----
const pendingInsertAtCaret = useVueState(
diff --git a/frontend/src/react/components/sql-editor/TerminalPanel/CompactSQLEditor.tsx b/frontend/src/react/components/sql-editor/TerminalPanel/CompactSQLEditor.tsx
index c2e134c48b..8b5c3a1987 100644
--- a/frontend/src/react/components/sql-editor/TerminalPanel/CompactSQLEditor.tsx
+++ b/frontend/src/react/components/sql-editor/TerminalPanel/CompactSQLEditor.tsx
@@ -1,7 +1,7 @@
import { debounce } from "lodash-es";
import type { IDisposable } from "monaco-editor";
import * as monaco from "monaco-editor";
-import { useCallback, useEffect, useMemo, useRef } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { MonacoEditor } from "@/react/components/monaco/MonacoEditor";
import type {
IStandaloneCodeEditor,
@@ -129,10 +129,16 @@ export function CompactSQLEditor({
}, [language]);
const editorRef = useRef<IStandaloneCodeEditor | null>(null);
+ // State mirror of `editorRef` so engine-conditional effects (Explain)
+ // re-run after Monaco is ready. Refs alone wouldn't trigger that.
+ const [editorState, setEditorState] = useState<IStandaloneCodeEditor | null>(
+ null
+ );
const handleReady = useCallback(
(_: MonacoModule, editor: IStandaloneCodeEditor) => {
editorRef.current = editor;
+ setEditorState(editor);
const execute = (explain = false) => {
const c = connectionRef.current;
@@ -256,13 +262,12 @@ export function CompactSQLEditor({
}, [readonly]);
// Engine-conditional Explain Query / Dry Run Query action. Re-registers
- // when the engine flips so the label and visibility track.
- const explainActionRef = useRef<IDisposable | null>(null);
+ // when the engine flips so the label and visibility track. Depends on
+ // `editorState` (not the ref) so the effect re-runs when Monaco
+ // publishes the editor instance via `handleReady`.
useEffect(() => {
- const editor = editorRef.current;
+ const editor = editorState;
if (!editor || engine === undefined) return;
- explainActionRef.current?.dispose();
- explainActionRef.current = null;
const allows =
instanceV1AllowsExplain(engine) || engine === Engine.BIGQUERY;
@@ -289,11 +294,10 @@ export function CompactSQLEditor({
});
},
});
- explainActionRef.current = action;
return () => {
action.dispose();
};
- }, [engine]);
+ }, [engine, editorState]);
// Format-content event from useSQLEditorContext (Vue `editorEvents`).
useEffect(() => {
diff --git a/frontend/src/react/explain-visualizer/ExplainVisualizerApp.tsx b/frontend/src/react/explain-visualizer/ExplainVisualizerApp.tsx
new file mode 100644
index 0000000000..5bafe50787
--- /dev/null
+++ b/frontend/src/react/explain-visualizer/ExplainVisualizerApp.tsx
@@ -0,0 +1,57 @@
+import { parse } from "qs";
+import { type ReactNode, useMemo } from "react";
+import { Engine } from "@/types/proto-es/v1/common_pb";
+import { readExplainFromToken } from "@/utils/pev2";
+import { MSSQLPlanView } from "./MSSQLPlanView";
+import { PostgresPlanView } from "./PostgresPlanView";
+import { SpannerQueryPlan } from "./SpannerQueryPlan";
+
+export function ExplainVisualizerApp() {
+ const storedQuery = useMemo(() => {
+ const query = location.search.replace(/^\?/, "");
+ const token = (parse(query).token as string) || "";
+ return readExplainFromToken(token);
+ }, []);
+
+ if (!storedQuery) {
+ return (
+ <div className="ev-app">
+ <h1>session expired</h1>
+ </div>
+ );
+ }
+
+ let body: ReactNode;
+ switch (storedQuery.engine) {
+ case Engine.POSTGRES:
+ body = (
+ <PostgresPlanView
+ planSource={storedQuery.explain}
+ planQuery={storedQuery.statement}
+ />
+ );
+ break;
+ case Engine.MSSQL:
+ body = <MSSQLPlanView planXml={storedQuery.explain} />;
+ break;
+ case Engine.SPANNER:
+ body = (
+ <SpannerQueryPlan
+ planSource={storedQuery.explain}
+ planQuery={storedQuery.statement}
+ />
+ );
+ break;
+ default:
+ body = (
+ <div className="ev-unsupported">
+ <h2>Unsupported Database Engine</h2>
+ <p>
+ Query plan visualization is not available for this database engine.
+ </p>
+ </div>
+ );
+ }
+
+ return <div className="ev-app">{body}</div>;
+}
diff --git a/frontend/src/react/explain-visualizer/MSSQLPlanView.tsx b/frontend/src/react/explain-visualizer/MSSQLPlanView.tsx
new file mode 100644
index 0000000000..72833c5a18
--- /dev/null
+++ b/frontend/src/react/explain-visualizer/MSSQLPlanView.tsx
@@ -0,0 +1,32 @@
+import { useEffect, useRef } from "react";
+import { loadQueryPlanScript } from "./loadQueryPlanScript";
+
+interface Props {
+ planXml: string;
+}
+
+export function MSSQLPlanView({ planXml }: Props) {
+ const containerRef = useRef<HTMLDivElement>(null);
+
+ useEffect(() => {
+ let cancelled = false;
+ const container = containerRef.current;
+ if (!container) return;
+ void (async () => {
+ try {
+ await loadQueryPlanScript();
+ if (cancelled) return;
+ if (window.QP && containerRef.current) {
+ window.QP.showPlan(containerRef.current, planXml);
+ }
+ } catch (error) {
+ console.error("Failed to load query plan visualizer:", error);
+ }
+ })();
+ return () => {
+ cancelled = true;
+ };
+ }, [planXml]);
+
+ return <div ref={containerRef} className="ev-mssql-container" />;
+}
diff --git a/frontend/src/react/explain-visualizer/PostgresPlanView.tsx b/frontend/src/react/explain-visualizer/PostgresPlanView.tsx
new file mode 100644
index 0000000000..39e6d0c2c1
--- /dev/null
+++ b/frontend/src/react/explain-visualizer/PostgresPlanView.tsx
@@ -0,0 +1,27 @@
+import { Plan as pev2 } from "pev2";
+import { useEffect, useRef } from "react";
+import { type App, createApp } from "vue";
+
+interface Props {
+ planSource: string;
+ planQuery?: string;
+}
+
+// pev2 is a Vue 3 component; no React port exists. Reimplementing the
+// Postgres EXPLAIN renderer is out of scope, so we mount pev2 as a
+// short-lived Vue subapp inside this React node and unmount on cleanup.
+// Vue is already in this entry's bundle transitively via pev2.
+export function PostgresPlanView({ planSource, planQuery }: Props) {
+ const hostRef = useRef<HTMLDivElement>(null);
+
+ useEffect(() => {
+ if (!hostRef.current) return;
+ const app: App = createApp(pev2, { planSource, planQuery });
+ app.mount(hostRef.current);
+ return () => {
+ app.unmount();
+ };
+ }, [planSource, planQuery]);
+
+ return <div ref={hostRef} className="qp-root" />;
+}
diff --git a/frontend/src/react/explain-visualizer/SpannerPlanNode.test.tsx b/frontend/src/react/explain-visualizer/SpannerPlanNode.test.tsx
new file mode 100644
index 0000000000..a9752fa9e3
--- /dev/null
+++ b/frontend/src/react/explain-visualizer/SpannerPlanNode.test.tsx
@@ -0,0 +1,89 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, test } from "vitest";
+import { SpannerPlanNode } from "./SpannerPlanNode";
+import type { SpannerPlanNodeData } from "./spanner-types";
+
+const node = (
+ index: number,
+ kind: string,
+ displayName: string,
+ extra: Partial<SpannerPlanNodeData> = {}
+): SpannerPlanNodeData => ({
+ index,
+ kind,
+ displayName,
+ ...extra,
+});
+
+describe("SpannerPlanNode", () => {
+ test("renders a leaf node with its kind and displayName", () => {
+ const root = node(0, "RELATIONAL", "Distributed Union");
+ render(<SpannerPlanNode node={root} allNodes={[root]} depth={0} />);
+ expect(screen.getByText("RELATIONAL")).toBeInTheDocument();
+ expect(screen.getByText("Distributed Union")).toBeInTheDocument();
+ });
+
+ test("renders only RELATIONAL child links, skipping scalar links", () => {
+ const root = node(0, "RELATIONAL", "Distributed Union", {
+ childLinks: [{ childIndex: 1 }, { childIndex: 2, type: "Reference" }],
+ });
+ const relChild = node(1, "RELATIONAL", "Hash Join");
+ const scalarChild = node(2, "SCALAR", "Param");
+ render(
+ <SpannerPlanNode
+ node={root}
+ allNodes={[root, relChild, scalarChild]}
+ depth={0}
+ />
+ );
+ expect(screen.getByText("Hash Join")).toBeInTheDocument();
+ expect(screen.queryByText("Param")).not.toBeInTheDocument();
+ });
+
+ test("collapses children when the node row is clicked", () => {
+ const root = node(0, "RELATIONAL", "Distributed Union", {
+ childLinks: [{ childIndex: 1 }],
+ });
+ const child = node(1, "RELATIONAL", "Hash Join");
+ render(<SpannerPlanNode node={root} allNodes={[root, child]} depth={0} />);
+ expect(screen.getByText("Hash Join")).toBeInTheDocument();
+ // The root's row is the first element with class `ev-spanner-row`.
+ const row = document.querySelector(".ev-spanner-row");
+ expect(row).not.toBeNull();
+ fireEvent.click(row as Element);
+ expect(screen.queryByText("Hash Join")).not.toBeInTheDocument();
+ });
+
+ test("filters out metadata keys that start with `_`", () => {
+ const root = node(0, "RELATIONAL", "Scan", {
+ metadata: {
+ table: "users",
+ _internal_id: "skip-me",
+ },
+ });
+ render(<SpannerPlanNode node={root} allNodes={[root]} depth={0} />);
+ expect(screen.getByText("table:")).toBeInTheDocument();
+ expect(screen.getByText("users")).toBeInTheDocument();
+ expect(screen.queryByText("_internal_id:")).not.toBeInTheDocument();
+ expect(screen.queryByText("skip-me")).not.toBeInTheDocument();
+ });
+
+ test("renders shortRepresentation.description when present", () => {
+ const root = node(0, "RELATIONAL", "Filter", {
+ shortRepresentation: { description: "age > 18" },
+ });
+ render(<SpannerPlanNode node={root} allNodes={[root]} depth={0} />);
+ expect(screen.getByText("age > 18")).toBeInTheDocument();
+ });
+
+ test("renders unknown placeholder for missing child indexes", () => {
+ const root = node(0, "RELATIONAL", "Union", {
+ childLinks: [{ childIndex: 42 }],
+ });
+ // Child 42 is missing from allNodes — but the parent only renders
+ // children whose RELATIONAL kind matches. With a missing child the
+ // filter drops the link, so nothing renders for it.
+ render(<SpannerPlanNode node={root} allNodes={[root]} depth={0} />);
+ expect(screen.queryByText(/Unknown Node/)).not.toBeInTheDocument();
+ });
+});
diff --git a/frontend/src/react/explain-visualizer/SpannerPlanNode.tsx b/frontend/src/react/explain-visualizer/SpannerPlanNode.tsx
new file mode 100644
index 0000000000..c1ba98cfe9
--- /dev/null
+++ b/frontend/src/react/explain-visualizer/SpannerPlanNode.tsx
@@ -0,0 +1,129 @@
+import { ChevronDownIcon, ChevronUpIcon } from "lucide-react";
+import { useMemo, useState } from "react";
+import type { SpannerChildLink, SpannerPlanNodeData } from "./spanner-types";
+
+interface Props {
+ node: SpannerPlanNodeData;
+ allNodes: SpannerPlanNodeData[];
+ depth: number;
+}
+
+const formatValue = (value: unknown): string => {
+ if (value === null || value === undefined) return "null";
+ if (typeof value === "object") return JSON.stringify(value);
+ return String(value);
+};
+
+const kindClassName = (kind: string): string => {
+ switch (kind) {
+ case "RELATIONAL":
+ return "ev-spanner-kind-relational";
+ case "SCALAR":
+ return "ev-spanner-kind-scalar";
+ default:
+ return "ev-spanner-kind-unknown";
+ }
+};
+
+export function SpannerPlanNode({ node, allNodes, depth }: Props) {
+ const [expanded, setExpanded] = useState(true);
+
+ const relationalChildLinks = useMemo<SpannerChildLink[]>(() => {
+ if (!node.childLinks) return [];
+ return node.childLinks.filter((link) => {
+ const childNode = allNodes.find((n) => n.index === link.childIndex);
+ return childNode && childNode.kind === "RELATIONAL";
+ });
+ }, [node.childLinks, allNodes]);
+
+ const hasChildren = relationalChildLinks.length > 0;
+ const isScalar = node.kind === "SCALAR";
+ const shortDescription = node.shortRepresentation?.description;
+
+ const displayMetadata = useMemo<Record<string, unknown>>(() => {
+ if (!node.metadata) return {};
+ // Filter out internal metadata keys (prefixed with `_`).
+ const filtered: Record<string, unknown> = {};
+ for (const [key, value] of Object.entries(node.metadata)) {
+ if (!key.startsWith("_")) filtered[key] = value;
+ }
+ return filtered;
+ }, [node.metadata]);
+
+ const hasMetadata = Object.keys(displayMetadata).length > 0;
+
+ const handleToggle = () => {
+ if (hasChildren) setExpanded((v) => !v);
+ };
+
+ const getChildNode = (index: number): SpannerPlanNodeData => {
+ const child = allNodes.find((n) => n.index === index);
+ return (
+ child ?? {
+ index,
+ kind: "UNKNOWN",
+ displayName: `Unknown Node (${index})`,
+ }
+ );
+ };
+
+ return (
+ <div
+ className={`ev-spanner-node${isScalar ? " is-scalar" : ""}`}
+ data-depth={depth}
+ >
+ <div className="ev-spanner-row" onClick={handleToggle}>
+ {hasChildren ? (
+ <span className="ev-spanner-toggle">
+ {expanded ? (
+ <ChevronDownIcon className="w-4" />
+ ) : (
+ <ChevronUpIcon className="w-4" />
+ )}
+ </span>
+ ) : (
+ <span className="ev-spanner-toggle-placeholder" />
+ )}
+
+ <span className={`ev-spanner-kind ${kindClassName(node.kind)}`}>
+ {node.kind}
+ </span>
+ <span className="ev-spanner-name">{node.displayName}</span>
+
+ {shortDescription ? (
+ <span className="ev-spanner-desc">{shortDescription}</span>
+ ) : null}
+ </div>
+
+ {hasMetadata ? (
+ <div className="ev-spanner-metadata">
+ {Object.entries(displayMetadata).map(([key, value]) => (
+ <div key={key} className="ev-spanner-metadata-item">
+ <span className="ev-spanner-metadata-key">{key}:</span>
+ <span className="ev-spanner-metadata-value">
+ {formatValue(value)}
+ </span>
+ </div>
+ ))}
+ </div>
+ ) : null}
+
+ {expanded && hasChildren ? (
+ <div className="ev-spanner-children">
+ {relationalChildLinks.map((childLink) => (
+ <div key={childLink.childIndex} className="ev-spanner-child">
+ {childLink.type ? (
+ <div className="ev-spanner-child-type">{childLink.type}</div>
+ ) : null}
+ <SpannerPlanNode
+ node={getChildNode(childLink.childIndex)}
+ allNodes={allNodes}
+ depth={depth + 1}
+ />
+ </div>
+ ))}
+ </div>
+ ) : null}
+ </div>
+ );
+}
diff --git a/frontend/src/react/explain-visualizer/SpannerQueryPlan.tsx b/frontend/src/react/explain-visualizer/SpannerQueryPlan.tsx
new file mode 100644
index 0000000000..4ebf618636
--- /dev/null
+++ b/frontend/src/react/explain-visualizer/SpannerQueryPlan.tsx
@@ -0,0 +1,41 @@
+import { useMemo } from "react";
+import { SpannerPlanNode } from "./SpannerPlanNode";
+import type { SpannerPlanNodeData } from "./spanner-types";
+
+interface Props {
+ planSource: string;
+ planQuery?: string;
+}
+
+export function SpannerQueryPlan({ planSource, planQuery }: Props) {
+ const planNodes = useMemo<SpannerPlanNodeData[]>(() => {
+ try {
+ const parsed = JSON.parse(planSource);
+ return parsed.planNodes || [];
+ } catch {
+ return [];
+ }
+ }, [planSource]);
+
+ // The first node (index 0) is the root node in Spanner query plans.
+ const rootNode = useMemo<SpannerPlanNodeData | undefined>(() => {
+ if (planNodes.length === 0) return undefined;
+ return planNodes.find((node) => node.index === 0);
+ }, [planNodes]);
+
+ return (
+ <div className="ev-spanner">
+ <div className="ev-spanner-header">
+ <h3>Query Plan</h3>
+ {planQuery ? <div className="ev-spanner-query">{planQuery}</div> : null}
+ </div>
+ <div className="ev-spanner-tree">
+ {rootNode ? (
+ <SpannerPlanNode node={rootNode} allNodes={planNodes} depth={0} />
+ ) : (
+ <div className="ev-spanner-empty">No query plan available</div>
+ )}
+ </div>
+ </div>
+ );
+}
diff --git a/frontend/src/react/explain-visualizer/explain-visualizer.css b/frontend/src/react/explain-visualizer/explain-visualizer.css
new file mode 100644
index 0000000000..d4c63587c8
--- /dev/null
+++ b/frontend/src/react/explain-visualizer/explain-visualizer.css
@@ -0,0 +1,264 @@
+/* Standalone styles for the Explain Visualizer entry. Classes are
+ prefixed `ev-` because the page also loads `bootstrap`, `pev2`, and
+ `html-query-plan` CSS, none of which expect to coexist with the main
+ app's design tokens. */
+
+html,
+body,
+#app,
+.ev-app {
+ height: 100%;
+}
+
+body {
+ margin: 0;
+}
+
+.ev-app {
+ display: flex;
+}
+
+/* Font Awesome SVG sizing — pev2 renders icons via
+ @fortawesome/vue-fontawesome, which expects Font Awesome's
+ `autoAddCss` to inject these rules into <head> at runtime. That
+ injection fires in the standalone Vue app but not reliably when pev2
+ is mounted as a Vue island inside React, leaving icons unsized
+ (`<svg>` defaults to filling its container). Inline the minimum
+ sizing rules so behavior is deterministic without taking a direct
+ dependency on `@fortawesome/fontawesome-svg-core`. */
+.svg-inline--fa {
+ display: var(--fa-display, inline-block);
+ height: 1em;
+ overflow: visible;
+ vertical-align: -0.125em;
+}
+svg.svg-inline--fa:not(:root) {
+ overflow: visible;
+ box-sizing: content-box;
+}
+.svg-inline--fa.fa-fw {
+ width: var(--fa-fw-width, 1.25em);
+}
+.svg-inline--fa.fa-pull-left {
+ margin-right: var(--fa-pull-margin, 0.3em);
+ width: auto;
+}
+.svg-inline--fa.fa-pull-right {
+ margin-left: var(--fa-pull-margin, 0.3em);
+ width: auto;
+}
+
+.ev-unsupported {
+ display: flex;
+ flex-direction: column;
+ align-items: center;
+ justify-content: center;
+ width: 100%;
+ height: 100%;
+ padding: 24px;
+ text-align: center;
+}
+
+.ev-unsupported h2 {
+ margin-bottom: 8px;
+ color: #666;
+}
+
+.ev-unsupported p {
+ color: #999;
+}
+
+.ev-mssql-container {
+ width: 100%;
+ height: 100%;
+ overflow: auto;
+ padding: 16px;
+}
+
+/* `.qp-root` is the wrapper that pev2 mounts into. The Vue version
+ placed pev2 directly inside `<div id="app" class="d-flex">` so pev2's
+ root (`.plan-container`) was a flex child and stretched on the cross
+ axis. Our React wrapper adds one extra layer, and `.plan-container`
+ has no explicit height in pev2's CSS — without help, it shrinks to
+ content height and the splitpanes inside (`height: 100%`) collapse.
+ Force the first child to fill so the cascade resolves. */
+.qp-root {
+ width: 100%;
+ height: 100%;
+ display: flex;
+ flex-direction: column;
+}
+.qp-root > * {
+ flex: 1 1 0;
+ min-height: 0;
+ width: 100%;
+}
+
+/* Spanner query plan tree */
+.ev-spanner {
+ width: 100%;
+ height: 100%;
+ overflow: auto;
+ padding: 16px;
+ font-family:
+ -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu,
+ Cantarell, "Open Sans", "Helvetica Neue", sans-serif;
+}
+
+.ev-spanner-header {
+ margin-bottom: 16px;
+ padding-bottom: 12px;
+ border-bottom: 1px solid #e0e0e0;
+}
+
+.ev-spanner-header h3 {
+ margin: 0 0 8px 0;
+ font-size: 18px;
+ font-weight: 600;
+ color: #333;
+}
+
+.ev-spanner-query {
+ font-family:
+ "SF Mono", Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+ font-size: 13px;
+ color: #666;
+ background-color: #f5f5f5;
+ padding: 8px 12px;
+ border-radius: 4px;
+ white-space: pre-wrap;
+ word-break: break-word;
+}
+
+.ev-spanner-tree {
+ padding: 8px 0;
+}
+
+.ev-spanner-empty {
+ color: #999;
+ font-style: italic;
+ padding: 16px;
+ text-align: center;
+}
+
+.ev-spanner-node {
+ margin-left: 0;
+ font-size: 14px;
+}
+
+.ev-spanner-node.is-scalar {
+ display: inline;
+}
+
+.ev-spanner-row {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ padding: 6px 8px;
+ border-radius: 4px;
+ cursor: pointer;
+ transition: background-color 0.15s ease;
+}
+
+.ev-spanner-row:hover {
+ background-color: #f0f4f8;
+}
+
+.ev-spanner-toggle {
+ width: 16px;
+ font-size: 10px;
+ color: #666;
+ user-select: none;
+}
+
+.ev-spanner-toggle-placeholder {
+ width: 16px;
+}
+
+.ev-spanner-kind {
+ font-size: 11px;
+ font-weight: 600;
+ padding: 2px 6px;
+ border-radius: 3px;
+ text-transform: uppercase;
+}
+
+.ev-spanner-kind-relational {
+ background-color: #e3f2fd;
+ color: #1565c0;
+}
+
+.ev-spanner-kind-scalar {
+ background-color: #f3e5f5;
+ color: #7b1fa2;
+}
+
+.ev-spanner-kind-unknown {
+ background-color: #f5f5f5;
+ color: #666;
+}
+
+.ev-spanner-name {
+ font-weight: 500;
+ color: #333;
+}
+
+.ev-spanner-desc {
+ font-family:
+ "SF Mono", Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+ font-size: 12px;
+ color: #666;
+ background-color: #f5f5f5;
+ padding: 2px 6px;
+ border-radius: 3px;
+ max-width: 400px;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+}
+
+.ev-spanner-metadata {
+ margin-left: 40px;
+ margin-top: 4px;
+ padding: 8px 12px;
+ background-color: #fafafa;
+ border-radius: 4px;
+ border-left: 3px solid #e0e0e0;
+}
+
+.ev-spanner-metadata-item {
+ display: flex;
+ gap: 8px;
+ font-size: 12px;
+ line-height: 1.6;
+}
+
+.ev-spanner-metadata-key {
+ font-weight: 500;
+ color: #666;
+}
+
+.ev-spanner-metadata-value {
+ font-family:
+ "SF Mono", Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+ color: #333;
+ word-break: break-all;
+}
+
+.ev-spanner-children {
+ margin-left: 24px;
+ padding-left: 16px;
+ border-left: 2px solid #e0e0e0;
+}
+
+.ev-spanner-child {
+ margin-top: 4px;
+}
+
+.ev-spanner-child-type {
+ font-size: 11px;
+ color: #999;
+ margin-left: 8px;
+ margin-bottom: 2px;
+ font-style: italic;
+}
diff --git a/frontend/src/react/explain-visualizer/loadQueryPlanScript.ts b/frontend/src/react/explain-visualizer/loadQueryPlanScript.ts
new file mode 100644
index 0000000000..5872f74c57
--- /dev/null
+++ b/frontend/src/react/explain-visualizer/loadQueryPlanScript.ts
@@ -0,0 +1,37 @@
+// Dynamically load `html-query-plan` from `/libs/qp.min.js` and resolve
+// when `window.QP.showPlan` is callable. The script attaches `QP` as a
+// global the first time it loads; subsequent calls short-circuit.
+
+declare global {
+ interface Window {
+ QP: {
+ showPlan: (
+ container: Element,
+ planXml: string,
+ options?: Record<string, unknown>
+ ) => void;
+ };
+ }
+}
+
+const SCRIPT_ID = "html-query-plan-script";
+
+export const loadQueryPlanScript = (): Promise<void> => {
+ return new Promise((resolve, reject) => {
+ if (window.QP) {
+ resolve();
+ return;
+ }
+ if (document.getElementById(SCRIPT_ID)) {
+ resolve();
+ return;
+ }
+ const script = document.createElement("script");
+ script.id = SCRIPT_ID;
+ script.src = "/libs/qp.min.js";
+ script.onload = () => resolve();
+ script.onerror = () =>
+ reject(new Error("Failed to load html-query-plan script"));
+ document.head.appendChild(script);
+ });
+};
diff --git a/frontend/src/react/explain-visualizer/main.tsx b/frontend/src/react/explain-visualizer/main.tsx
new file mode 100644
index 0000000000..35cb637b1d
--- /dev/null
+++ b/frontend/src/react/explain-visualizer/main.tsx
@@ -0,0 +1,36 @@
+import "bootstrap/dist/css/bootstrap.css";
+import "pev2/dist/pev2.css";
+import "html-query-plan/css/qp.css";
+import "./explain-visualizer.css";
+import { createRoot } from "react-dom/client";
+import { ExplainVisualizerApp } from "./ExplainVisualizerApp";
+
+// Some bundled dependencies expect a `global` reference on the window.
+(globalThis as typeof globalThis & Record<string, unknown>).global = globalThis;
+
+// Force Font Awesome SVG sizing into <head> before pev2 mounts. pev2
+// renders icons via @fortawesome/vue-fontawesome and relies on the
+// `autoAddCss` runtime mechanism to inject these rules. That injection
+// doesn't fire reliably when pev2 is mounted as a Vue island inside
+// React, leaving SVGs unconstrained (they expand to fill their parent,
+// blowing up the info-circle icon to viewport size). We can't import
+// `@fortawesome/fontawesome-svg-core/styles.css` directly because it's
+// a transitive dep that pnpm doesn't hoist to the top-level
+// node_modules. So inline the rules — marked `!important` because the
+// pev2 runtime can also inject conflicting CSS later.
+const STYLE_ID = "pev2-fa-svg-core";
+if (!document.getElementById(STYLE_ID)) {
+ const el = document.createElement("style");
+ el.id = STYLE_ID;
+ el.textContent = `
+ .svg-inline--fa{display:inline-block!important;height:1em!important;width:auto!important;overflow:visible!important;vertical-align:-.125em!important}
+ svg.svg-inline--fa:not(:root){overflow:visible!important;box-sizing:content-box!important}
+ .svg-inline--fa.fa-fw{width:1.25em!important}
+ `;
+ document.head.appendChild(el);
+}
+
+const container = document.getElementById("app");
+if (container) {
+ createRoot(container).render(<ExplainVisualizerApp />);
+}
diff --git a/frontend/src/components/SpannerQueryPlan/types.ts b/frontend/src/react/explain-visualizer/spanner-types.ts
similarity index 100%
rename from frontend/src/components/SpannerQueryPlan/types.ts
rename to frontend/src/react/explain-visualizer/spanner-types.ts