diff --git a/CLAUDE.md b/CLAUDE.md
index 4c8b6990a..e56edee30 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -22,6 +22,20 @@ bun run test    # Run tests
 
 **This repo uses bun**, not pnpm. Do NOT run `pnpm install` — it creates a `pnpm-lock.yaml` that should not exist. Workspace linking relies on bun's resolution from `"workspaces"` in root `package.json`.
 
+### Studio Build
+
+Always use the dev build locally — source maps, no minification, React dev-mode warnings:
+
+```bash
+bun run --cwd packages/studio build:dev
+```
+
+The production build (`build` without `:dev`) is only run by GitHub Actions for publish. After building, copy to CLI:
+
+```bash
+rm -rf packages/cli/dist/studio && cp -r packages/studio/dist packages/cli/dist/studio
+```
+
 ### Linting & Formatting
 
 This project uses **oxlint** and **oxfmt** (not biome, not eslint, not prettier).
diff --git a/packages/studio/package.json b/packages/studio/package.json
index 0c375ee67..f4c64a882 100644
--- a/packages/studio/package.json
+++ b/packages/studio/package.json
@@ -21,6 +21,7 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build",
+    "build:dev": "vite build --mode development",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest"
diff --git a/packages/studio/vite.config.ts b/packages/studio/vite.config.ts
index e326d656e..c7c96c241 100644
--- a/packages/studio/vite.config.ts
+++ b/packages/studio/vite.config.ts
@@ -615,18 +615,26 @@ function devProjectApi(): Plugin {
   };
 }
 
-export default defineConfig({
-  plugins: [react(), devProjectApi()],
-  resolve: {
-    alias: {
-      "@hyperframes/player": resolve(__dirname, "../player/src/hyperframes-player.ts"),
+export default defineConfig(({ mode }) => {
+  const isDev = mode === "development";
+  return {
+    plugins: [react(), devProjectApi()],
+    resolve: {
+      alias: {
+        "@hyperframes/player": resolve(__dirname, "../player/src/hyperframes-player.ts"),
+      },
+    },
+    ...(isDev && {
+      define: { "process.env.NODE_ENV": JSON.stringify("development") },
+    }),
+    build: {
+      outDir: "dist",
+      emptyOutDir: true,
+      sourcemap: isDev,
+      minify: !isDev,
     },
-  },
-  build: {
-    outDir: "dist",
-    emptyOutDir: true,
-  },
-  server: {
-    port: 5190,
-  },
+    server: {
+      port: 5190,
+    },
+  };
 });