From 75d20310ed85f53ec8a850ad0ffd42f500ecd5d4 Mon Sep 17 00:00:00 2001
From: marcelo <marcelojimenezrocabado@gmail.com>
Date: Thu, 28 May 2026 09:55:54 -0700
Subject: [PATCH] refactor(playground): rename remaining AppBuilder internals
 to Playground
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

App Builder (tab) and chat-v2 (tab) are both removed; Playground is the
only consumer of the orchestration hook, context, skeleton, and onboarding
state that still carried "AppBuilder" names. Pure mechanical rename — no
behavior change.

- useAppBuilderState -> usePlaygroundState (+ co-exports, types, file rename)
- AppBuilderStateProvider / useAppBuilderStateContext -> Playground-prefixed
- APP_BUILDER_FIRST_RUN_PROMPT -> PLAYGROUND_FIRST_RUN_PROMPT
- appBuilderOnboarding state in App.tsx -> playgroundOnboarding
- AppBuilderSkeleton -> PlaygroundSkeleton (moved to components/playground/)
- PostConnectGuide moved to components/ui-playground/ (no identifier rename)
- "app-builder-send-nux-hint" testid -> "playground-send-nux-hint"
- Drop the "app-builder" arm from surface literal unions in
  shared/inspector-command.ts (no in-tree caller sends it; CLI ships
  "playground")
- Delete the now-empty components/app-builder/ directory

PostHog event names (app_builder_tab_viewed etc.) preserved for analytics
continuity; comments updated to explain the carry-over.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 mcpjam-inspector/client/src/App.tsx           | 12 +--
 .../src/components/ActiveServerSelector.tsx   |  3 +-
 .../playground/PlaygroundCenter.tsx           | 16 ++--
 .../playground/PlaygroundLeftRail.tsx         |  4 +-
 .../PlaygroundSkeleton.tsx}                   |  4 +-
 .../components/playground/PlaygroundTab.tsx   | 17 ++--
 .../playground/panes/MultiServerToolsPane.tsx |  4 +-
 .../ui-playground/HandDrawnSendHint.tsx       |  2 +-
 .../ui-playground/PlaygroundLeft.tsx          |  4 +-
 .../ui-playground/PlaygroundMain.tsx          |  2 +-
 .../PostConnectGuide.tsx                      |  0
 .../__tests__/HandDrawnSendHint.test.tsx      |  2 +-
 .../__tests__/PlaygroundMain.test.tsx         |  6 +-
 .../__tests__/PostConnectGuide.test.tsx       |  0
 ...lect-connected-active-server-names.test.ts |  2 +-
 .../components/ui-playground/hooks/index.ts   | 18 ++--
 ...ilder-state.ts => use-playground-state.ts} | 96 ++++++++-----------
 mcpjam-inspector/shared/inspector-command.ts  |  6 +-
 18 files changed, 91 insertions(+), 107 deletions(-)
 rename mcpjam-inspector/client/src/components/{app-builder/AppBuilderSkeleton.tsx => playground/PlaygroundSkeleton.tsx} (50%)
 rename mcpjam-inspector/client/src/components/{app-builder => ui-playground}/PostConnectGuide.tsx (100%)
 rename mcpjam-inspector/client/src/components/{app-builder => ui-playground}/__tests__/PostConnectGuide.test.tsx (100%)
 rename mcpjam-inspector/client/src/components/ui-playground/hooks/{use-app-builder-state.ts => use-playground-state.ts} (89%)

diff --git a/mcpjam-inspector/client/src/App.tsx b/mcpjam-inspector/client/src/App.tsx
index ff8b08ca74..0be5a71c7f 100644
--- a/mcpjam-inspector/client/src/App.tsx
+++ b/mcpjam-inspector/client/src/App.tsx
@@ -944,7 +944,7 @@ export function PlaygroundRoute() {
     projectServers,
     remoteFirstRunOnboardingShown,
     selectedMCPConfig,
-    setAppBuilderOnboarding,
+    setPlaygroundOnboarding,
     setEvalChatHandoff,
     workOsUser,
   } = useAppRouteContext();
@@ -965,7 +965,7 @@ export function PlaygroundRoute() {
       onConnect={handleConnect}
       onSaveHostContext={handleUpdateHostContext}
       ensureServersReady={ensureServersReady}
-      onOnboardingChange={setAppBuilderOnboarding}
+      onOnboardingChange={setPlaygroundOnboarding}
       playgroundServerSelectorProps={playgroundServerSelectorProps}
       activeHost={activeHost}
       evalChatHandoff={evalChatHandoff}
@@ -1084,7 +1084,7 @@ export default function App() {
     optimisticallyDeletedOrganizationIds,
     setOptimisticallyDeletedOrganizationIds,
   ] = useState<string[]>([]);
-  const [appBuilderOnboarding, setAppBuilderOnboarding] = useState(false);
+  const [playgroundOnboarding, setPlaygroundOnboarding] = useState(false);
   const [callbackCompleted, setCallbackCompleted] = useState(false);
   const [callbackRecoveryExpired, setCallbackRecoveryExpired] = useState(false);
   const billingDeepLinkNavRef = useRef(false);
@@ -2895,7 +2895,7 @@ export default function App() {
     saveServerConfigWithoutConnecting,
     selectedMCPConfig,
     selectedServerEntry,
-    setAppBuilderOnboarding,
+    setPlaygroundOnboarding,
     setActiveHostId,
     setEvalChatHandoff,
     setHostsTabSelectedHostId,
@@ -2911,7 +2911,7 @@ export default function App() {
   const appContent = (
     <SidebarProvider defaultOpen={true}>
       <AppChromeSidebar
-        hidden={appBuilderOnboarding}
+        hidden={playgroundOnboarding}
         onNavigate={handleNavigate}
         activeTab={activeTab}
         projects={projects}
@@ -2934,7 +2934,7 @@ export default function App() {
       />
       <SidebarInset className="flex flex-col min-h-0">
         <AppChromeHeader
-          hidden={appBuilderOnboarding}
+          hidden={playgroundOnboarding}
           activeServerSelectorProps={activeServerSelectorProps}
           globalHostBarProps={globalHostBarProps}
         />
diff --git a/mcpjam-inspector/client/src/components/ActiveServerSelector.tsx b/mcpjam-inspector/client/src/components/ActiveServerSelector.tsx
index 403ab987bd..7c3a3d63d6 100644
--- a/mcpjam-inspector/client/src/components/ActiveServerSelector.tsx
+++ b/mcpjam-inspector/client/src/components/ActiveServerSelector.tsx
@@ -35,8 +35,7 @@ export interface ActiveServerSelectorProps {
    * Bulk-replace the multi-server selection. Wired in for the Playground
    * tab's host snapshot — picking a named host should toggle on the host's
    * required + optional servers in one shot, not per-server. Optional on
-   * the shared interface so the AppBuilder (single-select) doesn't need
-   * it.
+   * the shared interface so single-select callers don't need it.
    */
   onSelectMultipleServers?: (serverNames: string[]) => void;
   onConnect: (formData: ServerFormData) => void;
diff --git a/mcpjam-inspector/client/src/components/playground/PlaygroundCenter.tsx b/mcpjam-inspector/client/src/components/playground/PlaygroundCenter.tsx
index bbdbe7f927..e2bb6529a0 100644
--- a/mcpjam-inspector/client/src/components/playground/PlaygroundCenter.tsx
+++ b/mcpjam-inspector/client/src/components/playground/PlaygroundCenter.tsx
@@ -1,20 +1,20 @@
 /**
  * PlaygroundCenter
  *
- * Center pane of the Playground IDE shell. Consumes `useAppBuilderState`
+ * Center pane of the Playground IDE shell. Consumes `usePlaygroundState`
  * via context (PlaygroundTab owns the single hook call so the docked tools
  * pane and the center share state). Renders `PlaygroundMain` directly — the
  * tools sidebar UI lives in the docked `tools` pane instead.
  */
 import { Wrench } from "lucide-react";
 import { EmptyState } from "@/components/ui/empty-state";
-import { AppBuilderSkeleton } from "@/components/app-builder/AppBuilderSkeleton";
+import { PlaygroundSkeleton } from "@/components/playground/PlaygroundSkeleton";
 import { PlaygroundMain } from "@/components/ui-playground/PlaygroundMain";
 import SaveRequestDialog from "@/components/tools/SaveRequestDialog";
 import {
-  APP_BUILDER_FIRST_RUN_PROMPT,
-  useAppBuilderStateContext,
-} from "@/components/ui-playground/hooks/use-app-builder-state";
+  PLAYGROUND_FIRST_RUN_PROMPT,
+  usePlaygroundStateContext,
+} from "@/components/ui-playground/hooks/use-playground-state";
 import type { PlaygroundServerSelectorProps } from "@/components/ActiveServerSelector";
 import type { ProjectHostContextDraft } from "@/lib/client-config";
 import type { EnsureServersReadyResult } from "@/hooks/use-app-state";
@@ -46,12 +46,12 @@ export function PlaygroundCenter({
   evalChatHandoff = null,
   onEvalChatHandoffConsumed,
 }: PlaygroundCenterProps) {
-  const state = useAppBuilderStateContext();
+  const state = usePlaygroundStateContext();
 
   if (state.loadingState.kind === "skeleton") {
     return (
       <div className="h-full flex flex-col overflow-hidden relative">
-        <AppBuilderSkeleton />
+        <PlaygroundSkeleton />
       </div>
     );
   }
@@ -92,7 +92,7 @@ export function PlaygroundCenter({
         playgroundServerSelectorProps={playgroundServerSelectorProps}
         initialInput={
           state.firstRunComposerSeed
-            ? APP_BUILDER_FIRST_RUN_PROMPT
+            ? PLAYGROUND_FIRST_RUN_PROMPT
             : undefined
         }
         initialInputTypewriter={state.firstRunComposerSeed}
diff --git a/mcpjam-inspector/client/src/components/playground/PlaygroundLeftRail.tsx b/mcpjam-inspector/client/src/components/playground/PlaygroundLeftRail.tsx
index 57f258a854..6458f7d595 100644
--- a/mcpjam-inspector/client/src/components/playground/PlaygroundLeftRail.tsx
+++ b/mcpjam-inspector/client/src/components/playground/PlaygroundLeftRail.tsx
@@ -3,7 +3,7 @@ import { Hammer, History } from "lucide-react";
 import { useFeatureFlagEnabled, usePostHog } from "posthog-js/react";
 import { standardEventProps } from "@/lib/PosthogUtils";
 import { ChatHistoryRail } from "@/components/chat-v2/history/ChatHistoryRail";
-import { useAppBuilderStateContext } from "@/components/ui-playground/hooks/use-app-builder-state";
+import { usePlaygroundStateContext } from "@/components/ui-playground/hooks/use-playground-state";
 import { PlaygroundLeft } from "@/components/ui-playground/PlaygroundLeft";
 import { MultiServerToolsPaneInner } from "./panes/MultiServerToolsPane";
 import { usePlaygroundChatHistoryBridge } from "./playground-chat-history-bridge";
@@ -130,7 +130,7 @@ function SessionsBody() {
 }
 
 function ToolsBody() {
-  const state = useAppBuilderStateContext();
+  const state = usePlaygroundStateContext();
   const isMulti = state.activeServerNames.length > 1;
 
   if (isMulti) {
diff --git a/mcpjam-inspector/client/src/components/app-builder/AppBuilderSkeleton.tsx b/mcpjam-inspector/client/src/components/playground/PlaygroundSkeleton.tsx
similarity index 50%
rename from mcpjam-inspector/client/src/components/app-builder/AppBuilderSkeleton.tsx
rename to mcpjam-inspector/client/src/components/playground/PlaygroundSkeleton.tsx
index 68321f73f0..b8c160128b 100644
--- a/mcpjam-inspector/client/src/components/app-builder/AppBuilderSkeleton.tsx
+++ b/mcpjam-inspector/client/src/components/playground/PlaygroundSkeleton.tsx
@@ -1,7 +1,7 @@
 /**
- * Lightweight loading shell for App Builder while auth or first-run connect settles.
+ * Lightweight loading shell for the Playground while auth or first-run connect settles.
  * Sidebars are collapsed during onboarding so no skeleton is needed.
  */
-export function AppBuilderSkeleton() {
+export function PlaygroundSkeleton() {
   return <div className="h-full bg-background" />;
 }
diff --git a/mcpjam-inspector/client/src/components/playground/PlaygroundTab.tsx b/mcpjam-inspector/client/src/components/playground/PlaygroundTab.tsx
index 1e822d7168..69a12f296a 100644
--- a/mcpjam-inspector/client/src/components/playground/PlaygroundTab.tsx
+++ b/mcpjam-inspector/client/src/components/playground/PlaygroundTab.tsx
@@ -3,9 +3,9 @@ import { useConvexAuth } from "convex/react";
 import { usePostHog } from "posthog-js/react";
 import { standardEventProps } from "@/lib/PosthogUtils";
 import {
-  AppBuilderStateProvider,
-  useAppBuilderState,
-} from "@/components/ui-playground/hooks/use-app-builder-state";
+  PlaygroundStateProvider,
+  usePlaygroundState,
+} from "@/components/ui-playground/hooks/use-playground-state";
 import {
   ChatboxChatUiOverrideProvider,
   ChatboxHostStyleProvider,
@@ -93,8 +93,8 @@ interface PlaygroundTabProps {
  * in v2. Chat-v2 also keeps these local, and matching that behavior keeps the
  * mental model simple ("rails are workspace chrome, not part of a view").
  *
- * Owns the single `useAppBuilderState()` call for the surface; the
- * `AppBuilderStateProvider` exposes it to both the left rail's Tools tab and
+ * Owns the single `usePlaygroundState()` call for the surface; the
+ * `PlaygroundStateProvider` exposes it to both the left rail's Tools tab and
  * the center pane.
  */
 export function PlaygroundTab(props: PlaygroundTabProps) {
@@ -186,7 +186,7 @@ export function PlaygroundTab(props: PlaygroundTabProps) {
     requiredServerNames: effectiveHostRequiredNames,
   });
 
-  const appBuilderState = useAppBuilderState({
+  const playgroundState = usePlaygroundState({
     activeProjectId: props.activeProjectId,
     serverConfig: props.serverConfig,
     serverName: props.serverName,
@@ -201,7 +201,6 @@ export function PlaygroundTab(props: PlaygroundTabProps) {
     onSaveHostContext: props.onSaveHostContext,
     ensureServersReady: props.ensureServersReady,
     onOnboardingChange: props.onOnboardingChange,
-    surface: "playground",
     // Playground supports multi-server tool selection — pass the active
     // multi-server set through so the docked tools pane aggregates across
     // all of them and execution routes to the right server per tool.
@@ -221,7 +220,7 @@ export function PlaygroundTab(props: PlaygroundTabProps) {
   const rightPanelRef = useRef<ImperativePanelHandle | null>(null);
 
   return (
-    <AppBuilderStateProvider value={appBuilderState}>
+    <PlaygroundStateProvider value={playgroundState}>
       <ActiveMcpProfileProvider value={activeMcpProfile}>
         <ActiveHostCapsResolverScope
           // Preview-mode (explicit picker selection) wins; otherwise fall
@@ -356,6 +355,6 @@ export function PlaygroundTab(props: PlaygroundTabProps) {
           </ChatboxHostStyleProvider>
         </ActiveHostCapsResolverScope>
       </ActiveMcpProfileProvider>
-    </AppBuilderStateProvider>
+    </PlaygroundStateProvider>
   );
 }
diff --git a/mcpjam-inspector/client/src/components/playground/panes/MultiServerToolsPane.tsx b/mcpjam-inspector/client/src/components/playground/panes/MultiServerToolsPane.tsx
index bc493d2930..973e262cdd 100644
--- a/mcpjam-inspector/client/src/components/playground/panes/MultiServerToolsPane.tsx
+++ b/mcpjam-inspector/client/src/components/playground/panes/MultiServerToolsPane.tsx
@@ -27,7 +27,7 @@ import { ScrollArea } from "@mcpjam/design-system/scroll-area";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@mcpjam/design-system/tooltip";
 import { RefreshCw } from "lucide-react";
 import { useAggregatedTools } from "@/hooks/use-aggregated-tools";
-import { useAppBuilderStateContext } from "@/components/ui-playground/hooks/use-app-builder-state";
+import { usePlaygroundStateContext } from "@/components/ui-playground/hooks/use-playground-state";
 import { ParametersForm } from "@/components/ui-playground/ParametersForm";
 import { SelectedToolHeader } from "@/components/ui-playground/SelectedToolHeader";
 import { TabHeader } from "@/components/ui-playground/TabHeader";
@@ -54,7 +54,7 @@ interface Selection {
 }
 
 export function MultiServerToolsPaneInner({ activeServerNames }: InnerProps) {
-  const state = useAppBuilderStateContext();
+  const state = usePlaygroundStateContext();
   const { flat, collidingNames, loadingByServer, refetch } =
     useAggregatedTools(activeServerNames);
 
diff --git a/mcpjam-inspector/client/src/components/ui-playground/HandDrawnSendHint.tsx b/mcpjam-inspector/client/src/components/ui-playground/HandDrawnSendHint.tsx
index 6d2f69dca9..4839d17bd9 100644
--- a/mcpjam-inspector/client/src/components/ui-playground/HandDrawnSendHint.tsx
+++ b/mcpjam-inspector/client/src/components/ui-playground/HandDrawnSendHint.tsx
@@ -65,7 +65,7 @@ export function HandDrawnSendHint({
     >
       <div
         className="flex flex-col items-end gap-0"
-        data-testid="app-builder-send-nux-hint"
+        data-testid="playground-send-nux-hint"
       >
         <span
           className="inline-block"
diff --git a/mcpjam-inspector/client/src/components/ui-playground/PlaygroundLeft.tsx b/mcpjam-inspector/client/src/components/ui-playground/PlaygroundLeft.tsx
index 5a7e56caac..a20fcd779e 100644
--- a/mcpjam-inspector/client/src/components/ui-playground/PlaygroundLeft.tsx
+++ b/mcpjam-inspector/client/src/components/ui-playground/PlaygroundLeft.tsx
@@ -57,8 +57,8 @@ interface PlaygroundLeftProps {
   onClose?: () => void;
   /**
    * Whether to render the inline LoggerView in the bottom resizable slot.
-   * Defaults to true for backward compat with AppBuilderTab. The Playground
-   * left rail passes `false` because the logger lives in the right rail.
+   * Defaults to true for legacy callers. The Playground left rail passes
+   * `false` because the logger lives in the right rail.
    */
   showLogger?: boolean;
 }
diff --git a/mcpjam-inspector/client/src/components/ui-playground/PlaygroundMain.tsx b/mcpjam-inspector/client/src/components/ui-playground/PlaygroundMain.tsx
index 1d7cb3dd26..bfdf018771 100644
--- a/mcpjam-inspector/client/src/components/ui-playground/PlaygroundMain.tsx
+++ b/mcpjam-inspector/client/src/components/ui-playground/PlaygroundMain.tsx
@@ -116,7 +116,7 @@ import {
   extractHostTheme,
   type ProjectHostContextDraft,
 } from "@/lib/client-config";
-import { PostConnectGuide } from "@/components/app-builder/PostConnectGuide";
+import { PostConnectGuide } from "@/components/ui-playground/PostConnectGuide";
 import {
   ChatboxHostStyleProvider,
   ChatboxHostThemeProvider,
diff --git a/mcpjam-inspector/client/src/components/app-builder/PostConnectGuide.tsx b/mcpjam-inspector/client/src/components/ui-playground/PostConnectGuide.tsx
similarity index 100%
rename from mcpjam-inspector/client/src/components/app-builder/PostConnectGuide.tsx
rename to mcpjam-inspector/client/src/components/ui-playground/PostConnectGuide.tsx
diff --git a/mcpjam-inspector/client/src/components/ui-playground/__tests__/HandDrawnSendHint.test.tsx b/mcpjam-inspector/client/src/components/ui-playground/__tests__/HandDrawnSendHint.test.tsx
index 1465bf68bd..1453116d13 100644
--- a/mcpjam-inspector/client/src/components/ui-playground/__tests__/HandDrawnSendHint.test.tsx
+++ b/mcpjam-inspector/client/src/components/ui-playground/__tests__/HandDrawnSendHint.test.tsx
@@ -19,7 +19,7 @@ describe("HandDrawnSendHint", () => {
 
   it("renders the hint label", () => {
     render(<HandDrawnSendHint theme="light" />);
-    expect(screen.getByTestId("app-builder-send-nux-hint")).toHaveTextContent(
+    expect(screen.getByTestId("playground-send-nux-hint")).toHaveTextContent(
       "Try this prompt with a demo MCP server",
     );
   });
diff --git a/mcpjam-inspector/client/src/components/ui-playground/__tests__/PlaygroundMain.test.tsx b/mcpjam-inspector/client/src/components/ui-playground/__tests__/PlaygroundMain.test.tsx
index c86b3b47b7..d2d2028fb4 100644
--- a/mcpjam-inspector/client/src/components/ui-playground/__tests__/PlaygroundMain.test.tsx
+++ b/mcpjam-inspector/client/src/components/ui-playground/__tests__/PlaygroundMain.test.tsx
@@ -1571,7 +1571,7 @@ describe("PlaygroundMain", () => {
         />,
       );
 
-      const hint = screen.getByTestId("app-builder-send-nux-hint");
+      const hint = screen.getByTestId("playground-send-nux-hint");
       const chatInput = screen.getByTestId("chat-input");
       expect(hint).toHaveTextContent("Try this prompt with a demo MCP server");
       expect(hint.closest('[data-testid="chat-input"]')).toBeNull();
@@ -1582,7 +1582,7 @@ describe("PlaygroundMain", () => {
       expect(hint.querySelector("svg")).toBeTruthy();
     });
 
-    it("keeps App Builder send NUX hint visible after server connects", () => {
+    it("keeps Playground send NUX hint visible after server connects", () => {
       mockSharedAppState.servers["test-server"] = {
         connectionStatus: "connected",
       };
@@ -1596,7 +1596,7 @@ describe("PlaygroundMain", () => {
         />,
       );
 
-      expect(screen.getByTestId("app-builder-send-nux-hint")).toHaveTextContent(
+      expect(screen.getByTestId("playground-send-nux-hint")).toHaveTextContent(
         "Try this prompt with a demo MCP server",
       );
     });
diff --git a/mcpjam-inspector/client/src/components/app-builder/__tests__/PostConnectGuide.test.tsx b/mcpjam-inspector/client/src/components/ui-playground/__tests__/PostConnectGuide.test.tsx
similarity index 100%
rename from mcpjam-inspector/client/src/components/app-builder/__tests__/PostConnectGuide.test.tsx
rename to mcpjam-inspector/client/src/components/ui-playground/__tests__/PostConnectGuide.test.tsx
diff --git a/mcpjam-inspector/client/src/components/ui-playground/hooks/__tests__/select-connected-active-server-names.test.ts b/mcpjam-inspector/client/src/components/ui-playground/hooks/__tests__/select-connected-active-server-names.test.ts
index 18dcb67783..9cd9ddf50a 100644
--- a/mcpjam-inspector/client/src/components/ui-playground/hooks/__tests__/select-connected-active-server-names.test.ts
+++ b/mcpjam-inspector/client/src/components/ui-playground/hooks/__tests__/select-connected-active-server-names.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import type { ServerWithName } from "@/hooks/use-app-state";
-import { selectConnectedActiveServerNames } from "../use-app-builder-state";
+import { selectConnectedActiveServerNames } from "../use-playground-state";
 
 function server(
   name: string,
diff --git a/mcpjam-inspector/client/src/components/ui-playground/hooks/index.ts b/mcpjam-inspector/client/src/components/ui-playground/hooks/index.ts
index 6c6735253c..4e65308cf2 100644
--- a/mcpjam-inspector/client/src/components/ui-playground/hooks/index.ts
+++ b/mcpjam-inspector/client/src/components/ui-playground/hooks/index.ts
@@ -19,13 +19,13 @@ export type {
 } from "./useToolExecution";
 export { useToolExecution } from "./useToolExecution";
 export type {
-  AppBuilderLoadingState,
-  UseAppBuilderStateOptions,
-  UseAppBuilderStateReturn,
-} from "./use-app-builder-state";
+  PlaygroundLoadingState,
+  UsePlaygroundStateOptions,
+  UsePlaygroundStateReturn,
+} from "./use-playground-state";
 export {
-  APP_BUILDER_FIRST_RUN_PROMPT,
-  AppBuilderStateProvider,
-  useAppBuilderState,
-  useAppBuilderStateContext,
-} from "./use-app-builder-state";
+  PLAYGROUND_FIRST_RUN_PROMPT,
+  PlaygroundStateProvider,
+  usePlaygroundState,
+  usePlaygroundStateContext,
+} from "./use-playground-state";
diff --git a/mcpjam-inspector/client/src/components/ui-playground/hooks/use-app-builder-state.ts b/mcpjam-inspector/client/src/components/ui-playground/hooks/use-playground-state.ts
similarity index 89%
rename from mcpjam-inspector/client/src/components/ui-playground/hooks/use-app-builder-state.ts
rename to mcpjam-inspector/client/src/components/ui-playground/hooks/use-playground-state.ts
index 2ea02a261b..a1aa1b9e33 100644
--- a/mcpjam-inspector/client/src/components/ui-playground/hooks/use-app-builder-state.ts
+++ b/mcpjam-inspector/client/src/components/ui-playground/hooks/use-playground-state.ts
@@ -1,16 +1,16 @@
 /**
- * useAppBuilderState
+ * usePlaygroundState
  *
- * Owns the orchestration that previously lived inline in `AppBuilderTab`:
- * tool fetching, form-field sync, saved-requests bridge, execution + result
- * injection waiters, onboarding integration, and the inspector command
- * handlers (`selectTool` / `executeTool` / `renderToolResult` / `setAppContext`
- * / `snapshotApp`).
+ * Owns the Playground tab's orchestration: tool fetching, form-field sync,
+ * saved-requests bridge, execution + result injection waiters, onboarding
+ * integration, and the inspector command handlers (`selectTool` /
+ * `executeTool` / `renderToolResult` / `setAppContext` / `snapshotApp`).
  *
- * Both `AppBuilderTab` (legacy route) and `PlaygroundTab` (new IDE shell) can
- * call this hook and compose their own JSX around the returned values. Keeps
- * the two surfaces in lockstep so an inspector command sent at one is
- * indistinguishable from one sent at the other.
+ * `PlaygroundTab` is the only consumer; the returned values are exposed to
+ * both the left rail's Tools pane and the center pane via
+ * `PlaygroundStateProvider` so the hook is called exactly once per surface
+ * (it owns React state, refs, and inspector command registrations — calling
+ * it twice would double-register handlers).
  */
 import {
   createContext,
@@ -69,7 +69,7 @@ import { PANEL_SIZES } from "../constants";
 const SERVER_SYNC_TIMEOUT_MS = 10000;
 const EXECUTION_INJECTION_TIMEOUT_MS = 5000;
 
-export const APP_BUILDER_FIRST_RUN_PROMPT =
+export const PLAYGROUND_FIRST_RUN_PROMPT =
   "Draw me an MCP architecture diagram";
 
 type ExecutionInjectionWaiter = {
@@ -79,7 +79,7 @@ type ExecutionInjectionWaiter = {
   timeoutId: ReturnType<typeof setTimeout>;
 };
 
-export interface UseAppBuilderStateOptions {
+export interface UsePlaygroundStateOptions {
   activeProjectId?: string | null;
   serverConfig?: MCPServerConfig;
   serverName?: string;
@@ -106,26 +106,21 @@ export interface UseAppBuilderStateOptions {
    * Empty / undefined falls back to single-server mode driven by `serverName`.
    */
   selectedServerNames?: string[];
-  /**
-   * Which surface is hosting this hook. Tagged onto the view-event for
-   * PostHog so we can split Playground vs App Builder usage. The event name
-   * itself stays `app_builder_tab_viewed` for continuity.
-   */
-  surface?: "app-builder" | "playground";
 }
 
 /**
  * Render-phase signal so consumers can switch on a discriminated union
  * instead of chaining if-elses. `ready` is the steady state; the others are
- * the early-return branches AppBuilderTab used to handle inline.
+ * the early-return branches the Playground handles before mounting the
+ * full IDE shell.
  */
-export type AppBuilderLoadingState =
+export type PlaygroundLoadingState =
   | { kind: "ready" }
   | { kind: "skeleton" }
   | { kind: "sync-timed-out" }
   | { kind: "no-server" };
 
-export type UseAppBuilderStateReturn = ReturnType<typeof useAppBuilderState>;
+export type UsePlaygroundStateReturn = ReturnType<typeof usePlaygroundState>;
 
 /**
  * Pick the servers whose tools should appear in the Playground tools pane
@@ -134,9 +129,9 @@ export type UseAppBuilderStateReturn = ReturnType<typeof useAppBuilderState>;
  * already use, so all three surfaces agree on what "in-use" means and the
  * pane stays in sync with the user's connection toggle.
  *
- * Multi-server (Playground) passes `selectedServerNames`; single-server
- * (App Builder) passes `serverName`. Either way the filter rejects anything
- * not currently in `connectionStatus === "connected"`.
+ * Multi-server mode passes `selectedServerNames`; single-server mode passes
+ * `serverName`. Either way the filter rejects anything not currently in
+ * `connectionStatus === "connected"`.
  */
 export function selectConnectedActiveServerNames(input: {
   selectedServerNames: ReadonlyArray<string> | undefined;
@@ -152,7 +147,7 @@ export function selectConnectedActiveServerNames(input: {
   return serverName && isConnected(serverName) ? [serverName] : [];
 }
 
-export function useAppBuilderState(options: UseAppBuilderStateOptions) {
+export function usePlaygroundState(options: UsePlaygroundStateOptions) {
   const {
     serverConfig,
     serverName,
@@ -166,7 +161,6 @@ export function useAppBuilderState(options: UseAppBuilderStateOptions) {
     onConnect,
     onOnboardingChange,
     selectedServerNames,
-    surface = "app-builder",
   } = options;
 
   const activeServerNames = useMemo(
@@ -254,14 +248,11 @@ export function useAppBuilderState(options: UseAppBuilderStateOptions) {
     };
   }, [onOnboardingChange, setMcpSidebarOpen, setSidebarVisible]);
 
-  // Log when the app-builder surface is viewed. The event name stays
-  // `app_builder_tab_viewed` even for the Playground surface — telemetry
-  // continuity is more valuable than a name swap here. `surface` lets PostHog
-  // split Playground vs App Builder usage.
+  // Event name `app_builder_tab_viewed` is kept for analytics continuity
+  // (the only surface that still mounts this hook is the Playground tab).
   useEffect(() => {
     posthog.capture("app_builder_tab_viewed", {
       location: "app_builder_tab",
-      surface,
       platform: detectPlatform(),
       environment: detectEnvironment(),
     });
@@ -491,7 +482,7 @@ export function useAppBuilderState(options: UseAppBuilderStateOptions) {
     [serverName, setExecutionError, setTools, tools, toolsMetadata]
   );
 
-  const buildAppBuilderSnapshot = useCallback(() => {
+  const buildPlaygroundSnapshot = useCallback(() => {
     const playgroundState = useUIPlaygroundStore.getState();
 
     return {
@@ -582,13 +573,9 @@ export function useAppBuilderState(options: UseAppBuilderStateOptions) {
         | ExecuteToolInspectorCommand
         | RenderToolResultInspectorCommand
     ) => {
-      // Accept both `app-builder` (legacy) and `playground` (transition). Only
-      // the Playground surface mounts now, so at most one consumer is alive at
-      // a time — no double-handler race.
-      if (
-        command.payload.surface !== "app-builder" &&
-        command.payload.surface !== "playground"
-      ) {
+      // Only the Playground surface mounts this hook, so the inspector
+      // command must target `"playground"`.
+      if (command.payload.surface !== "playground") {
         throw createInspectorCommandClientError(
           "unsupported_in_mode",
           `Playground cannot handle ${command.type} for ${command.payload.surface}.`
@@ -675,7 +662,7 @@ export function useAppBuilderState(options: UseAppBuilderStateOptions) {
         const command = rawCommand as SelectToolInspectorCommand;
         const selection = await selectToolForCommand(command);
         return {
-          ...buildAppBuilderSnapshot(),
+          ...buildPlaygroundSnapshot(),
           serverName: selection.serverName,
           toolName: command.payload.toolName,
           parameterKeys: Object.keys(selection.parameters),
@@ -703,7 +690,7 @@ export function useAppBuilderState(options: UseAppBuilderStateOptions) {
         }
 
         return {
-          ...buildAppBuilderSnapshot(),
+          ...buildPlaygroundSnapshot(),
           serverName: selection.serverName,
           toolName: outcome.toolName,
           parameters: outcome.parameters,
@@ -736,7 +723,7 @@ export function useAppBuilderState(options: UseAppBuilderStateOptions) {
         await waitForUiCommit();
 
         return {
-          ...buildAppBuilderSnapshot(),
+          ...buildPlaygroundSnapshot(),
           serverName: selection.serverName,
           toolName: outcome.toolName,
           parameters: outcome.parameters,
@@ -767,7 +754,7 @@ export function useAppBuilderState(options: UseAppBuilderStateOptions) {
         }
 
         await waitForUiCommit();
-        return buildAppBuilderSnapshot();
+        return buildPlaygroundSnapshot();
       }
     );
 
@@ -777,7 +764,6 @@ export function useAppBuilderState(options: UseAppBuilderStateOptions) {
         const command = rawCommand as SnapshotAppInspectorCommand;
         if (
           command.payload.surface &&
-          command.payload.surface !== "app-builder" &&
           command.payload.surface !== "playground"
         ) {
           throw createInspectorCommandClientError(
@@ -786,7 +772,7 @@ export function useAppBuilderState(options: UseAppBuilderStateOptions) {
           );
         }
 
-        return buildAppBuilderSnapshot();
+        return buildPlaygroundSnapshot();
       }
     );
 
@@ -798,7 +784,7 @@ export function useAppBuilderState(options: UseAppBuilderStateOptions) {
       unregisterSnapshotApp();
     };
   }, [
-    buildAppBuilderSnapshot,
+    buildPlaygroundSnapshot,
     executeTool,
     injectToolResult,
     selectToolForCommand,
@@ -845,7 +831,7 @@ export function useAppBuilderState(options: UseAppBuilderStateOptions) {
     }
   }, [onboarding.markOnboardingShown, shouldMarkFirstRunNuxShown]);
 
-  const loadingState: AppBuilderLoadingState =
+  const loadingState: PlaygroundLoadingState =
     isResolvingRemoteCompletion ||
     isBootstrappingFirstRunConnection ||
     isWaitingForServerSync
@@ -904,29 +890,29 @@ export function useAppBuilderState(options: UseAppBuilderStateOptions) {
 
 /**
  * Context bridge so the docked Playground tools pane and the playground center
- * pane can share a single `useAppBuilderState()` call (the hook owns React
+ * pane can share a single `usePlaygroundState()` call (the hook owns React
  * state, refs, and inspector command registrations — calling it twice would
  * double-register handlers).
  */
-const AppBuilderStateContext = createContext<UseAppBuilderStateReturn | null>(
+const PlaygroundStateContext = createContext<UsePlaygroundStateReturn | null>(
   null
 );
 
-export function AppBuilderStateProvider({
+export function PlaygroundStateProvider({
   value,
   children,
 }: {
-  value: UseAppBuilderStateReturn;
+  value: UsePlaygroundStateReturn;
   children: ReactNode;
 }) {
-  return createElement(AppBuilderStateContext.Provider, { value }, children);
+  return createElement(PlaygroundStateContext.Provider, { value }, children);
 }
 
-export function useAppBuilderStateContext(): UseAppBuilderStateReturn {
-  const ctx = useContext(AppBuilderStateContext);
+export function usePlaygroundStateContext(): UsePlaygroundStateReturn {
+  const ctx = useContext(PlaygroundStateContext);
   if (!ctx) {
     throw new Error(
-      "useAppBuilderStateContext must be used inside an AppBuilderStateProvider"
+      "usePlaygroundStateContext must be used inside a PlaygroundStateProvider"
     );
   }
   return ctx;
diff --git a/mcpjam-inspector/shared/inspector-command.ts b/mcpjam-inspector/shared/inspector-command.ts
index 6fe57fb043..ae0da97ee9 100644
--- a/mcpjam-inspector/shared/inspector-command.ts
+++ b/mcpjam-inspector/shared/inspector-command.ts
@@ -76,7 +76,7 @@ export interface SetAppContextInspectorCommand {
 }
 
 export interface ToolInvocationPayload {
-  surface: "tools" | "app-builder" | "playground";
+  surface: "tools" | "playground";
   serverName?: string;
   toolName: string;
   parameters?: Record<string, unknown>;
@@ -100,7 +100,7 @@ export interface RenderToolResultInspectorCommand {
   id: string;
   type: "renderToolResult";
   payload: {
-    surface: "tools" | "app-builder" | "playground";
+    surface: "tools" | "playground";
     serverName?: string;
     toolName: string;
     parameters?: Record<string, unknown>;
@@ -112,7 +112,7 @@ export interface RenderToolResultInspectorCommand {
 export interface SnapshotAppInspectorCommand {
   id: string;
   type: "snapshotApp";
-  payload: { surface?: "app-builder" | "playground" };
+  payload: { surface?: "playground" };
   timeoutMs?: number;
 }