@joycostudio/studio 0.1.3 → 0.1.5

package/dist/cli.js

@@ -2,9 +2,9 @@
 
 // src/cli.ts
 import { spawn } from "child_process";
-import { createRequire } from "module";
-import path4 from "path";
-import { parseArgs } from "util";
+import { createRequire as createRequire2 } from "module";
+import path8 from "path";
+import { parseArgs as parseArgs2 } from "util";
 
 // src/core/tool.ts
 var hasConfig = (tool2) => tool2.controls !== void 0;
@@ -35,35 +35,35 @@ function kind(value) {
   if (Array.isArray(value)) return "array";
   return typeof value;
 }
-function shapeMismatch(reference, value, path5) {
+function shapeMismatch(reference, value, path9) {
   const expected = kind(reference);
-  if (kind(value) !== expected) return `${path5}: expected ${expected}, got ${kind(value)}`;
-  if (expected === "number" && !Number.isFinite(value)) return `${path5}: expected a finite number`;
+  if (kind(value) !== expected) return `${path9}: expected ${expected}, got ${kind(value)}`;
+  if (expected === "number" && !Number.isFinite(value)) return `${path9}: expected a finite number`;
   if (expected === "array") {
     const [first] = reference;
     if (first === void 0) return null;
     for (const [index, item] of value.entries()) {
-      const nested = shapeMismatch(first, item, `${path5}[${index}]`);
+      const nested = shapeMismatch(first, item, `${path9}[${index}]`);
       if (nested) return nested;
     }
   }
   if (expected === "object") {
     const ref = reference;
     const obj = value;
-    for (const key of Object.keys(obj)) if (!(key in ref)) return `${path5}.${key}: unknown key`;
+    for (const key of Object.keys(obj)) if (!(key in ref)) return `${path9}.${key}: unknown key`;
     for (const key of Object.keys(ref)) {
-      if (!(key in obj)) return `${path5}.${key}: missing`;
-      const nested = shapeMismatch(ref[key], obj[key], `${path5}.${key}`);
+      if (!(key in obj)) return `${path9}.${key}: missing`;
+      const nested = shapeMismatch(ref[key], obj[key], `${path9}.${key}`);
       if (nested) return nested;
     }
   }
   return null;
 }
 var isRgb = (value) => typeof value === "object" && value !== null && ["r", "g", "b"].every((channel) => Number.isFinite(value[channel]));
-function invalidControl(schema, path5 = "") {
+function invalidControl(schema, path9 = "") {
   for (const [key, field] of Object.entries(schema)) {
     if (field.kind === "button") continue;
-    const name = `${path5}${field.label ?? key}`;
+    const name = `${path9}${field.label ?? key}`;
     if (field.kind === "folder") {
       const nested = invalidControl(field.definition.schema(), `${name}/`);
       if (nested) return nested;
@@ -102,14 +102,14 @@ var exists = (target) => stat(target).then(
   () => false
 );
 async function resolveToolFile(root, file) {
-  const fail = (reason) => new Error(`[studio] tool file "${file}" ${reason}`);
-  if (path.isAbsolute(file)) throw fail("must be relative to the project root");
-  if (path.extname(file) !== ".json") throw fail("must be a .json file");
+  const fail2 = (reason) => new Error(`[studio] tool file "${file}" ${reason}`);
+  if (path.isAbsolute(file)) throw fail2("must be relative to the project root");
+  if (path.extname(file) !== ".json") throw fail2("must be a .json file");
   const absolute = path.resolve(root, file);
-  if (!inside(root, absolute)) throw fail("escapes the project root");
+  if (!inside(root, absolute)) throw fail2("escapes the project root");
   let probe = absolute;
   while (!await exists(probe)) probe = path.dirname(probe);
-  if (probe !== root && !inside(await realpath(root), await realpath(probe))) throw fail("escapes the project root");
+  if (probe !== root && !inside(await realpath(root), await realpath(probe))) throw fail2("escapes the project root");
   return absolute;
 }
 var hashOf = (content) => createHash("sha256").update(content).digest("hex").slice(0, 16);
@@ -151,8 +151,7 @@ async function load(tool2, file) {
     throw new Error(`[studio] ${path2.basename(file)} is not a valid "${tool2.id}" config: ${parsed.message}`);
   return { value: parsed.data, hash: disk.hash };
 }
-async function createRuntime({ root, tools }) {
-  root = path2.resolve(root);
+async function prepare(root, tools) {
   const entries = /* @__PURE__ */ new Map();
   const files = /* @__PURE__ */ new Set();
   const ids = /* @__PURE__ */ new Set();
@@ -177,6 +176,12 @@ async function createRuntime({ root, tools }) {
       }
     });
   }
+  return { entries, ids };
+}
+async function createRuntime({ root, tools }) {
+  root = path2.resolve(root);
+  let { entries, ids } = await prepare(root, tools);
+  let changing = Promise.resolve();
   const listeners = /* @__PURE__ */ new Set();
   const commit = (entry, next, origin) => {
     const state = { ...entry.state, ...next };
@@ -263,27 +268,76 @@ async function createRuntime({ root, tools }) {
   });
   const timers = /* @__PURE__ */ new Map();
   const watchers = [];
-  const byDirectory = Map.groupBy(entries.values(), (entry) => path2.dirname(entry.file));
-  for (const [directory, group] of byDirectory) {
-    try {
-      const watcher = watch(directory, (_, filename) => {
-        for (const entry of group) {
-          if (filename && filename !== path2.basename(entry.file)) continue;
-          clearTimeout(timers.get(entry));
-          timers.set(
-            entry,
-            setTimeout(() => void reload(entry).catch((cause) => console.error("[studio] reload failed", cause)), 50)
+  const bindWatchers = () => {
+    for (const watcher of watchers.splice(0)) watcher.close();
+    for (const timer of timers.values()) clearTimeout(timer);
+    timers.clear();
+    const byDirectory = Map.groupBy(entries.values(), (entry) => path2.dirname(entry.file));
+    for (const [directory, group] of byDirectory) {
+      try {
+        const watcher = watch(directory, (_, filename) => {
+          for (const entry of group) {
+            if (filename && filename !== path2.basename(entry.file)) continue;
+            clearTimeout(timers.get(entry));
+            timers.set(
+              entry,
+              setTimeout(() => {
+                void changing.then(async () => {
+                  if (entries.get(entry.tool.id) === entry) await reload(entry);
+                }).catch((cause) => console.error("[studio] reload failed", cause));
+              }, 50)
+            );
+          }
+        });
+        watchers.push(watcher);
+      } catch {
+        console.warn(`[studio] not watching ${path2.relative(root, directory)} (it does not exist yet)`);
+      }
+    }
+  };
+  bindWatchers();
+  const replaceTools = (nextTools) => {
+    const update = changing.then(async () => {
+      await Promise.all([...entries.values()].map((entry) => entry.queue));
+      const prepared = await prepare(root, nextTools);
+      for (const [id, old] of entries) {
+        const next = prepared.entries.get(id);
+        if ((!next || next.file !== old.file) && old.state.dirty)
+          throw new Error(`Save or discard "${id}" before removing it or moving its config.`);
+        if (!next || next.file !== old.file) continue;
+        const parsed = validateConfig(next.tool, old.state.draft.value);
+        if (!parsed.ok && old.state.dirty)
+          throw new Error(
+            `Draft for "${id}" is incompatible with the new controls; save/discard it first: ${parsed.message}`
           );
+        if (parsed.ok && old.state.dirty) {
+          next.state = {
+            ...old.state,
+            saved: next.state.saved,
+            conflict: old.state.conflict || next.state.saved.hash !== old.state.saved.hash,
+            draft: { value: parsed.data, revision: old.state.draft.revision + 1 }
+          };
+        } else {
+          next.state.draft.revision = old.state.draft.revision + 1;
         }
-      });
-      watchers.push(watcher);
-    } catch {
-      console.warn(`[studio] not watching ${path2.relative(root, directory)} (it does not exist yet)`);
-    }
-  }
+      }
+      entries = prepared.entries;
+      ids = prepared.ids;
+      tools = nextTools;
+      bindWatchers();
+      for (const entry of entries.values()) commit(entry, {});
+    });
+    changing = update.catch(() => {
+    });
+    return update;
+  };
   return {
     root,
-    run: (op, params, origin) => handlers[op](params, origin),
+    run: async (op, params, origin) => {
+      await changing;
+      return handlers[op](params, origin);
+    },
+    replaceTools,
     subscribe(listener) {
       listeners.add(listener);
       return () => listeners.delete(listener);
@@ -606,19 +660,273 @@ function serveBridge(runtime, { port, host = "127.0.0.1", origins, appUrl }) {
   });
 }
 
-// src/runtime/load.ts
+// src/discovery/generate.ts
+import { existsSync as existsSync2, readFileSync, readdirSync, realpathSync } from "fs";
+import { mkdir as mkdir2, readFile as readFile2 } from "fs/promises";
+import path4 from "path";
+import ts from "typescript";
+
+// src/discovery/settings.ts
 import { existsSync } from "fs";
 import path3 from "path";
 import { createJiti } from "jiti";
 var CANDIDATES = ["studio.config.ts", "studio.config.mts", "studio.config.js", "studio.config.mjs"];
-async function loadConfig(cwd, explicit) {
-  const file = explicit ? path3.resolve(cwd, explicit) : CANDIDATES.map((name) => path3.join(cwd, name)).find((candidate) => existsSync(candidate));
-  if (!file || !existsSync(file)) throw new Error(`[studio] no ${explicit ?? "studio.config.ts"} found in ${cwd}`);
-  const jiti = createJiti(import.meta.url, { moduleCache: false });
-  const config = await jiti.import(file, { default: true });
-  if (!Array.isArray(config?.tools))
-    throw new Error(`[studio] ${path3.basename(file)} must default-export defineConfig({ tools })`);
-  return { config, root: path3.dirname(file) };
+function importer(root) {
+  return createJiti(import.meta.url, {
+    moduleCache: false,
+    fsCache: false,
+    tryNative: false,
+    tsconfigPaths: existsSync(path3.join(root, "tsconfig.json")) ? path3.join(root, "tsconfig.json") : false
+  });
+}
+async function readSettings(cwd, explicit) {
+  const file = explicit ? path3.resolve(cwd, explicit) : CANDIDATES.map((name) => path3.join(cwd, name)).find(existsSync);
+  if (explicit && !existsSync(file)) throw new Error(`[studio] no ${explicit} found in ${cwd}`);
+  const root = file ? path3.dirname(file) : path3.resolve(cwd);
+  const config = file ? await importer(root).import(file, { default: true }) : {};
+  if (!config || typeof config !== "object" || config.tools !== void 0 && !Array.isArray(config.tools))
+    throw new Error("[studio] config must default-export defineConfig({ ... })");
+  if (config.tools !== void 0 && config.toolsDir !== void 0)
+    throw new Error("[studio] Use either tools (manual registration) or toolsDir (discovery), not both.");
+  return { config, root, file };
+}
+
+// src/discovery/generate.ts
+var slash = (value) => value.split(path4.sep).join("/");
+var relativeImport = (from, to) => {
+  const relative = slash(path4.relative(path4.dirname(from), to)).replace(/\.(tsx?|jsx?|mts|mjs)$/, "");
+  return /^\.\.?\//.test(relative) ? relative : `./${relative}`;
+};
+var inside2 = (root, file) => {
+  const relative = path4.relative(root, file);
+  return relative === "" || relative !== ".." && !relative.startsWith(`..${path4.sep}`) && !path4.isAbsolute(relative);
+};
+var fail = (file, message) => {
+  throw new Error(`[studio] ${file}: ${message}`);
+};
+var HEADER = "// Generated by Studio. Do not edit.\n";
+var DiscoveryInputError = class extends Error {
+  constructor(cause, inputs) {
+    super(cause instanceof Error ? cause.message : String(cause), { cause });
+    this.inputs = inputs;
+  }
+  inputs;
+};
+function shape(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return `[${[...new Set(value.map(shape))].sort().join("|")}]`;
+  if (typeof value === "object")
+    return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${shape(item)}`).join(",")}}`;
+  return typeof value;
+}
+function declaration(file) {
+  const source = ts.createSourceFile(file, readFileSync(file, "utf8"), ts.ScriptTarget.Latest, true);
+  const exported = source.statements.find(ts.isExportAssignment);
+  const call = exported?.expression;
+  if (!call || !ts.isCallExpression(call) || !ts.isIdentifier(call.expression) || call.expression.text !== "defineTool")
+    return fail(file, "default-export defineTool({ id, controls }) directly so discovery can inspect it.");
+  const object = call.arguments[0];
+  if (!object || !ts.isObjectLiteralExpression(object)) return fail(file, "defineTool requires an object literal.");
+  const properties = /* @__PURE__ */ new Map();
+  for (const member of object.properties) {
+    if (ts.isSpreadAssignment(member) || !member.name || ts.isComputedPropertyName(member.name))
+      return fail(file, "spread/computed tool options are not supported; put dynamic logic inside controls.");
+    const key = member.name.getText(source).replace(/^['"]|['"]$/g, "");
+    if (properties.has(key)) return fail(file, `duplicate option ${key}`);
+    properties.set(key, member);
+  }
+  const literal = (key) => {
+    const member = properties.get(key);
+    if (!member) return void 0;
+    if (!ts.isPropertyAssignment(member) || !ts.isStringLiteral(member.initializer))
+      return fail(file, `${key} must be a static string literal.`);
+    return member.initializer.text;
+  };
+  const id = literal("id");
+  if (!id || !/^[a-z0-9][a-z0-9-]*$/.test(id)) return fail(file, "id must be an explicit kebab-case string.");
+  if (properties.has("file") || properties.has("initial"))
+    return fail(file, "discovered tools use config instead of file/initial; omit config for adjacent config.json.");
+  const configurable = properties.has("controls");
+  const config = literal("config");
+  if (config !== void 0 && !configurable) return fail(file, "config requires controls.");
+  return { id, config, configurable, preview: literal("preview"), source };
+}
+function pageRoute(app, file, explicit) {
+  if (explicit) return explicit;
+  const directory = path4.dirname(file);
+  if (!app || !inside2(app, directory)) return fail(file, "tools outside the app tree require an explicit preview URL.");
+  if (!["tsx", "ts", "jsx", "js"].some((ext) => existsSync2(path4.join(directory, `page.${ext}`))))
+    return fail(file, "add an adjacent page.tsx or specify preview explicitly.");
+  const segments = slash(path4.relative(app, directory)).split("/").filter(Boolean);
+  if (segments.some((part) => part.includes("[") || part.startsWith("@") || /^\(\./.test(part) || part.startsWith("_")))
+    return fail(file, "dynamic, parallel, intercepted, and private routes require an explicit preview URL.");
+  return "/" + segments.filter((part) => !/^\(.+\)$/.test(part)).join("/");
+}
+function walk(directory) {
+  return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    if (entry.name.startsWith(".") || entry.name === "node_modules" || entry.isSymbolicLink()) return [];
+    const file = path4.join(directory, entry.name);
+    return entry.isDirectory() ? walk(file) : entry.name === "studio.tool.ts" ? [file] : [];
+  }).sort();
+}
+function compilerConfig(root, dependencies) {
+  const configFile = path4.join(root, "tsconfig.json");
+  if (!existsSync2(configFile)) return fail(root, "discovery requires tsconfig.json.");
+  const host = {
+    ...ts.sys,
+    readDirectory: () => [],
+    readFile(file) {
+      dependencies.add(path4.resolve(file));
+      return ts.sys.readFile(file);
+    },
+    onUnRecoverableConfigFileDiagnostic(error2) {
+      throw new Error(ts.flattenDiagnosticMessageText(error2.messageText, "\n"));
+    }
+  };
+  const parsed = ts.getParsedCommandLineOfConfigFile(configFile, { resolveJsonModule: true }, host);
+  if (!parsed) return fail(configFile, "could not read TypeScript settings.");
+  return parsed.options;
+}
+async function writeChanged(file, content) {
+  if (await readFile2(file, "utf8").catch(() => "") === content) return;
+  await writeAtomic(file, content);
+}
+async function generate(cwd, explicit, publish = true, previous) {
+  const { root, config, file: settings } = await readSettings(cwd, explicit);
+  if (config.tools !== void 0) return void 0;
+  const app = ["app", "src/app"].map((dir) => path4.join(root, dir)).find(existsSync2);
+  const toolsDir = config.toolsDir === void 0 ? app : path4.resolve(root, config.toolsDir);
+  if (!toolsDir || !existsSync2(toolsDir))
+    return fail(root, "no tools directory found; create app/ or configure toolsDir.");
+  if (!inside2(realpathSync(root), realpathSync(toolsDir)))
+    return fail(toolsDir, "toolsDir must stay inside the project.");
+  const sources = new Set(walk(toolsDir));
+  const dependencies = /* @__PURE__ */ new Set();
+  if (settings) dependencies.add(settings);
+  const options = compilerConfig(root, dependencies);
+  const output = path4.join(root, ".studio");
+  const registry = path4.join(output, "registry.generated.ts");
+  const types = path4.join(output, "types.generated.ts");
+  const imports = [
+    HEADER,
+    '/// <reference path="./types.generated.ts" />',
+    "import type { StudioTool, DiscoveredToolConfigs } from '@joycostudio/studio'"
+  ];
+  const typeImports = [HEADER, "import '@joycostudio/studio'"];
+  const declarations = [];
+  const definitions = [];
+  const mappings = [];
+  const ids = /* @__PURE__ */ new Set();
+  const destinations = /* @__PURE__ */ new Set();
+  const seeds = /* @__PURE__ */ new Map();
+  const trackImports = (file) => {
+    if (dependencies.has(file)) return;
+    dependencies.add(file);
+    if (!/\.[cm]?[jt]sx?$/.test(file)) return;
+    for (const imported of ts.preProcessFile(readFileSync(file, "utf8")).importedFiles) {
+      const resolved = ts.resolveModuleName(imported.fileName, file, options, ts.sys).resolvedModule?.resolvedFileName;
+      if (resolved && inside2(root, resolved) && !resolved.includes(`${path4.sep}node_modules${path4.sep}`) && !inside2(output, resolved))
+        trackImports(resolved);
+    }
+  };
+  for (const [index, file] of [...sources].entries()) {
+    const tool2 = declaration(file);
+    if (ids.has(tool2.id)) return fail(file, `duplicate tool id "${tool2.id}".`);
+    ids.add(tool2.id);
+    trackImports(file);
+    const preview = pageRoute(app, file, tool2.preview);
+    const title = (preview.split("/").filter(Boolean).at(-1) || tool2.id).replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+    imports.push(`import tool${index} from ${JSON.stringify(relativeImport(registry, file))}`);
+    let values = "";
+    const resolvedTool = { source: file, title, preview };
+    if (tool2.configurable) {
+      const inputs = /* @__PURE__ */ new Set();
+      try {
+        const specifier = tool2.config ?? "./config.json";
+        const resolutionHost = {
+          ...ts.sys,
+          fileExists(candidate) {
+            if (inside2(root, candidate) && !candidate.includes(`${path4.sep}node_modules${path4.sep}`))
+              inputs.add(candidate);
+            return ts.sys.fileExists(candidate);
+          },
+          directoryExists(directory) {
+            const exists2 = ts.sys.directoryExists(directory);
+            if (!exists2 && inside2(root, directory) && !directory.includes(`${path4.sep}node_modules${path4.sep}`))
+              inputs.add(directory);
+            return exists2;
+          }
+        };
+        const resolved = ts.resolveModuleName(specifier, file, options, resolutionHost).resolvedModule?.resolvedFileName;
+        if (!resolved || !resolved.endsWith(".json"))
+          return fail(file, `cannot resolve JSON config "${specifier}" through tsconfig.json.`);
+        const target = await resolveToolFile(root, slash(path4.relative(root, resolved)));
+        inputs.add(target);
+        const real = realpathSync(target);
+        if (destinations.has(real)) return fail(file, "another tool already writes this config file.");
+        destinations.add(real);
+        const value = JSON.parse(readFileSync(target, "utf8"));
+        if (!value || typeof value !== "object" || Array.isArray(value))
+          return fail(file, "config must be a JSON object.");
+        resolvedTool.file = slash(path4.relative(root, target));
+        resolvedTool.initial = value;
+        dependencies.add(target);
+        const key = `${tool2.id}:${real}`;
+        const prior = previous?.seeds.get(key);
+        const seed = prior && shape(prior) === shape(value) ? prior : value;
+        seeds.set(key, seed);
+        typeImports.push(`import type config${index} from ${JSON.stringify(relativeImport(types, target))}`);
+        mappings.push(`    ${JSON.stringify(tool2.id)}: typeof config${index}`);
+        values = `, file: ${JSON.stringify(slash(path4.relative(root, target)))}, initial: JSON.parse(${JSON.stringify(JSON.stringify(seed))}) as DiscoveredToolConfigs[${JSON.stringify(tool2.id)}]`;
+      } catch (cause) {
+        throw new DiscoveryInputError(cause, /* @__PURE__ */ new Set([...dependencies, ...inputs]));
+      }
+    }
+    declarations.push(resolvedTool);
+    definitions.push(
+      `  { title: ${JSON.stringify(title)}, ...tool${index}, preview: ${JSON.stringify(preview)}${values} }`
+    );
+  }
+  const write = async () => {
+    await mkdir2(output, { recursive: true });
+    await writeChanged(
+      types,
+      `${typeImports.join("\n")}
+
+declare module '@joycostudio/studio' {
+  interface DiscoveredToolConfigs {
+${mappings.join("\n")}
+  }
+}
+`
+    );
+    await writeChanged(
+      registry,
+      `${imports.join("\n")}
+
+export const tools = [
+${definitions.join(",\n")}
+] satisfies readonly StudioTool[]
+`
+    );
+  };
+  if (publish) await write();
+  return { root, toolsDir, sources, dependencies, registry, seeds, declarations, write };
+}
+
+// src/runtime/load.ts
+async function loadConfig(cwd, explicit, publish = true, previous) {
+  const { config, root } = await readSettings(cwd, explicit);
+  const discovery = await generate(cwd, explicit, false, previous);
+  const jiti = importer(root);
+  const tools = config.tools ?? await Promise.all(
+    discovery.declarations.map(async ({ source, title, preview, file, initial }) => {
+      const tool2 = await jiti.import(source, { default: true });
+      return { title, ...tool2, preview, ...file ? { file, initial } : {} };
+    })
+  );
+  if (publish) await discovery?.write();
+  return { config: { ...config, tools }, root, discovery };
 }
 
 // src/runtime/ports.ts
@@ -652,9 +960,483 @@ async function freeAppPort(hostname, port) {
   throw new Error(`[studio] ports ${port}-${port + ATTEMPTS - 1} on ${hostname} are all in use`);
 }
 
+// src/init.ts
+import { spawnSync } from "child_process";
+import { existsSync as existsSync4, mkdirSync, readFileSync as readFileSync3, readdirSync as readdirSync2, rmdirSync, rmSync, writeFileSync } from "fs";
+import { createRequire } from "module";
+import path6 from "path";
+import { parseArgs } from "util";
+
+// package.json
+var package_default = {
+  name: "@joycostudio/studio",
+  version: "0.1.5",
+  description: "Plug project-specific tools into a /studio route, a floating debug pane, and MCP agents.",
+  type: "module",
+  license: "ISC",
+  author: "joyco.studio",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/joyco-studio/studio.git",
+    directory: "packages/studio"
+  },
+  publishConfig: {
+    registry: "https://registry.npmjs.org",
+    access: "public"
+  },
+  files: [
+    "dist"
+  ],
+  bin: {
+    studio: "./dist/cli.js"
+  },
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      default: "./dist/index.js"
+    },
+    "./client": {
+      types: "./dist/client.d.ts",
+      default: "./dist/client.js"
+    },
+    "./react": {
+      types: "./dist/react.d.ts",
+      default: "./dist/react.js"
+    },
+    "./runtime": {
+      types: "./dist/runtime.d.ts",
+      default: "./dist/runtime.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./command-menu.css": "./dist/command-menu.css",
+    "./next": {
+      types: "./dist/next.d.ts",
+      default: "./dist/next.js"
+    },
+    "./controls": {
+      types: "./dist/controls.d.ts",
+      default: "./dist/controls.js"
+    },
+    "./next/config": {
+      types: "./dist/next-config.d.ts",
+      default: "./dist/next-config.js"
+    }
+  },
+  scripts: {
+    build: "pnpm build:shadow-css && tsup && tailwindcss -i src/react/styles.css -o dist/styles.css --minify && cp src/react/command-menu-export.css dist/command-menu.css",
+    dev: 'pnpm build:shadow-css && pnpm run --parallel "/^dev:/"',
+    test: "vitest run",
+    "test:browser": "STUDIO_TEST_BROWSER=1 vitest run test/browser-sync.test.ts",
+    "test:capture": "STUDIO_TEST_CAPTURE=1 vitest run test/capture.test.ts",
+    typecheck: "tsc --noEmit",
+    "dev:js": "tsup --watch",
+    "dev:css": "tailwindcss -i src/react/styles.css -o dist/styles.css --watch=always",
+    "build:shadow-css": "tailwindcss -i src/react/shadow.css -o src/react/generated/studio.css --minify",
+    "dev:shadow-css": "tailwindcss -i src/react/shadow.css -o src/react/generated/studio.css --minify --watch=always"
+  },
+  dependencies: {
+    "@base-ui/react": "^1.9.0",
+    "@modelcontextprotocol/node": "^2.1.1",
+    "@modelcontextprotocol/server": "^2.3.1",
+    "class-variance-authority": "^0.7.1",
+    clsx: "^2.1.1",
+    cmdk: "^1.1.1",
+    cn: "^0.4.0",
+    jiti: "^2.7.0",
+    lucide: "^1.55.0",
+    "lucide-react": "^1.55.0",
+    playwright: "^1.64.0",
+    "radix-ui": "^1.8.0",
+    "tailwind-merge": "^3.7.0",
+    ws: "^8.22.0",
+    zod: "^4.6.6",
+    typescript: "^5.9.3"
+  },
+  peerDependencies: {
+    "@joycostudio/xyz": "^1.4.0",
+    react: ">=18",
+    "react-dom": ">=18",
+    tweakpane: "^4.0.5"
+  },
+  peerDependenciesMeta: {
+    react: {
+      optional: true
+    },
+    tweakpane: {
+      optional: true
+    },
+    "react-dom": {
+      optional: true
+    }
+  },
+  devDependencies: {
+    "@joycostudio/xyz": "^1.4.0",
+    "@modelcontextprotocol/client": "^2.3.1",
+    "@tailwindcss/cli": "^4.3.3",
+    "@tweakpane/core": "^2.0.5",
+    "@types/node": "^24.19.2",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@types/ws": "^8.18.2",
+    react: "^19.3.0",
+    "react-dom": "^19.3.0",
+    tailwindcss: "^4.3.3",
+    tsup: "^8.5.1",
+    "tw-animate-css": "^1.4.0",
+    tweakpane: "^4.0.5",
+    vitest: "^5.0.3"
+  },
+  sideEffects: [
+    "*.css"
+  ]
+};
+
+// src/discovery/scaffold.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
+import path5 from "path";
+import ts2 from "typescript";
+function nextConfigEdit(root) {
+  const name = ["next.config.ts", "next.config.mjs", "next.config.js"].find((file2) => existsSync3(path5.join(root, file2)));
+  if (!name)
+    return {
+      file: path5.join(root, "next.config.ts"),
+      content: "import { withStudio } from '@joycostudio/studio/next/config'\n\nexport default withStudio({})\n"
+    };
+  const file = path5.join(root, name);
+  const text = readFileSync2(file, "utf8");
+  const source = ts2.createSourceFile(file, text, ts2.ScriptTarget.Latest, true);
+  const wrapped = (node) => ts2.isCallExpression(node) && ts2.isIdentifier(node.expression) && /^withStudio\w*$/.test(node.expression.text) || (ts2.forEachChild(node, wrapped) ?? false);
+  if (text.includes("@joycostudio/studio/next/config") && wrapped(source)) return { file, content: text };
+  const exported = source.statements.find(ts2.isExportAssignment);
+  if (exported && !exported.isExportEquals) {
+    const expression = exported.expression;
+    let local = "withStudioSetup";
+    while (new RegExp(`\\b${local}\\b`).test(text)) local += "_";
+    return {
+      file,
+      content: `import { withStudio as ${local} } from '@joycostudio/studio/next/config'
+` + text.slice(0, expression.getStart(source)) + `${local}(${expression.getText(source)})` + text.slice(expression.end)
+    };
+  }
+  const assignment = source.statements.flatMap(
+    (statement) => ts2.isExpressionStatement(statement) && ts2.isBinaryExpression(statement.expression) && statement.expression.left.getText(source) === "module.exports" && statement.expression.operatorToken.kind === ts2.SyntaxKind.EqualsToken ? [statement.expression.right] : []
+  );
+  if (assignment.length === 1) {
+    const expression = assignment[0];
+    return {
+      file,
+      content: text.slice(0, expression.getStart(source)) + `async (...args) => { const { withStudio } = await import('@joycostudio/studio/next/config'); return withStudio(${expression.getText(source)})(...args) }` + text.slice(expression.end)
+    };
+  }
+  throw new Error(
+    `[studio] Cannot wrap ${name} automatically. Export a config object/function or wrap it with withStudio manually.`
+  );
+}
+
+// src/init.ts
+async function init(argv) {
+  const { positionals, values } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: { "no-install": { type: "boolean" } }
+  });
+  if (positionals.length > 1) throw new Error("Usage: studio init [directory] [--no-install]");
+  const root = path6.resolve(positionals[0] ?? ".");
+  const manifest = path6.join(root, "package.json");
+  const pkg = JSON.parse(readFileSync3(manifest, "utf8"));
+  if (!pkg.dependencies?.next && !pkg.devDependencies?.next)
+    throw new Error("[studio] init supports existing Next.js App Router projects.");
+  if (!existsSync4(path6.join(root, "tsconfig.json")))
+    throw new Error("[studio] init currently requires a TypeScript project (tsconfig.json).");
+  const app = ["app", "src/app"].find((dir) => existsSync4(path6.join(root, dir)));
+  if (!app) throw new Error("[studio] No app/ or src/app/ directory found.");
+  const src = app.startsWith("src/") ? "src/" : "";
+  const relative = (from, to) => {
+    const result = path6.relative(path6.dirname(from), to).split(path6.sep).join("/");
+    return /^\.\.?\//.test(result) ? result : `./${result}`;
+  };
+  const client = `${src}studio.ts`;
+  const tool2 = `${app}/studio-preview/studio.tool.ts`;
+  const data = `${app}/studio-preview/config.json`;
+  const page = `${app}/studio/page.tsx`;
+  const preview = `${app}/studio-preview/page.tsx`;
+  const files = {
+    [client]: `import { createStudio } from '@joycostudio/studio/next'
+import { tools } from '${relative(client, ".studio/registry.generated")}'
+
+export const studio = createStudio({ tools })
+`,
+    [data]: '{ "scale": 1 }\n',
+    [tool2]: `import { defineTool } from '@joycostudio/studio'
+import { property, slider } from '@joycostudio/studio/controls'
+
+export default defineTool({
+  id: 'studio-example',
+  title: 'Example',
+  controls: (config) => ({ scale: slider(property(config, 'scale'), { min: 0.5, max: 2 }) }),
+})
+`,
+    [page]: `'use client'
+
+import '@joycostudio/studio/styles.css'
+import { Studio } from '@joycostudio/studio/react'
+import { studio } from '${relative(page, client.slice(0, -3))}'
+
+export default function StudioPage() {
+  return <Studio studio={studio} />
+}
+`,
+    [preview]: `'use client'
+
+import { useToolConfig } from '@joycostudio/studio/react'
+import { studio } from '${relative(preview, client.slice(0, -3))}'
+import example from './studio.tool'
+
+export default function StudioPreview() {
+  const config = useToolConfig(studio.tool(example))
+  return (
+    <main style={{ display: 'grid', placeItems: 'center', minHeight: '100vh' }}>
+      <div style={{ width: 120, height: 120, background: '#ff5930', borderRadius: 24, transform: \`scale(\${config.scale})\` }} />
+    </main>
+  )
+}
+`
+  };
+  const checkRoute = (directory, segment, allowed) => {
+    for (const entry of readdirSync2(path6.join(root, directory), { withFileTypes: true })) {
+      const file = `${directory}/${entry.name}`;
+      if (entry.isDirectory()) {
+        if (/^\([^.)][^/]*\)$/.test(entry.name)) checkRoute(file, segment, allowed);
+        else if (entry.name === segment) checkRoute(file, void 0, allowed);
+      } else if (!segment && /^(page|route)\.[jt]sx?$/.test(entry.name) && file !== allowed) {
+        throw new Error(`[studio] Route already exists: ${file}`);
+      }
+    }
+  };
+  checkRoute(app, "studio", page);
+  checkRoute(app, "studio-preview", preview);
+  for (const [name, content] of Object.entries(files)) {
+    const target = path6.join(root, name);
+    if (existsSync4(target) && readFileSync3(target, "utf8") !== content)
+      throw new Error(`[studio] Refusing to overwrite ${name}. Use the manual setup guide for existing integrations.`);
+  }
+  for (const ext of ["ts", "mts", "js", "mjs"]) {
+    if (existsSync4(path6.join(root, `studio.config.${ext}`)))
+      throw new Error(`[studio] Found studio.config.${ext}; use the manual setup guide for existing integrations.`);
+  }
+  const nextEdit = nextConfigEdit(root);
+  const dev = pkg.scripts?.dev;
+  if (!dev || /[;&|\n]/.test(dev) || !/^studio dev(?:\s|$)/.test(dev) && !/^next dev(?:\s|$)/.test(dev))
+    throw new Error(
+      "[studio] Expected a next dev script. Configure studio dev -- <command> manually for custom scripts."
+    );
+  let manager = pkg.packageManager?.split("@")[0];
+  if (!manager) {
+    let dir = root;
+    while (true) {
+      manager = [
+        ["pnpm-lock.yaml", "pnpm"],
+        ["yarn.lock", "yarn"],
+        ["bun.lock", "bun"],
+        ["bun.lockb", "bun"],
+        ["package-lock.json", "npm"]
+      ].find(([lock]) => existsSync4(path6.join(dir, lock)))?.[1];
+      if (manager || path6.dirname(dir) === dir) break;
+      dir = path6.dirname(dir);
+    }
+  }
+  manager ??= "npm";
+  if (!["npm", "pnpm", "yarn", "bun"].includes(manager))
+    throw new Error(`[studio] Unsupported package manager: ${manager}`);
+  if (pkg.dependencies?.["@joycostudio/studio"] || pkg.devDependencies?.["@joycostudio/studio"]) {
+    try {
+      const require2 = createRequire(manifest);
+      for (const entry of ["next", "next/config", "controls", "react"]) require2.resolve(`@joycostudio/studio/${entry}`);
+    } catch {
+      throw new Error(
+        "[studio] The declared Studio dependency is missing or lacks the required exports. Install the same version (or preview) as this initializer, then rerun init. No files were changed."
+      );
+    }
+  }
+  const dependencies = {
+    "@joycostudio/studio": `^${package_default.version}`,
+    "@joycostudio/xyz": package_default.peerDependencies["@joycostudio/xyz"],
+    tweakpane: package_default.peerDependencies.tweakpane
+  };
+  pkg.dependencies ??= {};
+  for (const [name, version] of Object.entries(dependencies)) {
+    if (!pkg.dependencies[name] && !pkg.devDependencies?.[name]) pkg.dependencies[name] = version;
+  }
+  if (!/^studio dev(?:\s|$)/.test(dev)) pkg.scripts.dev = `studio dev -- ${dev}`;
+  const typecheck = pkg.scripts.typecheck ?? "tsc --noEmit";
+  if (!typecheck.startsWith("studio generate")) pkg.scripts.typecheck = `studio generate && ${typecheck}`;
+  const ignoreFile = path6.join(root, ".gitignore");
+  const targets = [
+    ...Object.keys(files).map((name) => path6.join(root, name)),
+    nextEdit.file,
+    ignoreFile,
+    manifest,
+    path6.join(root, ".studio/types.generated.ts"),
+    path6.join(root, ".studio/registry.generated.ts")
+  ];
+  const originals = new Map(targets.map((file) => [file, existsSync4(file) ? readFileSync3(file) : void 0]));
+  const createdDirectories = /* @__PURE__ */ new Set();
+  for (const file of targets) {
+    for (let dir = path6.dirname(file); !existsSync4(dir); dir = path6.dirname(dir)) createdDirectories.add(dir);
+  }
+  try {
+    for (const [name, content] of Object.entries(files)) {
+      const target = path6.join(root, name);
+      if (existsSync4(target)) continue;
+      mkdirSync(path6.dirname(target), { recursive: true });
+      writeFileSync(target, content, { flag: "wx" });
+    }
+    writeFileSync(nextEdit.file, nextEdit.content);
+    const ignore = originals.get(ignoreFile)?.toString() ?? "";
+    if (!ignore.split(/\r?\n/).some((line) => [".studio", ".studio/", "/.studio/"].includes(line)))
+      writeFileSync(ignoreFile, `${ignore}${ignore.endsWith("\n") || !ignore ? "" : "\n"}/.studio/
+`);
+    await generate(root);
+    writeFileSync(manifest, `${JSON.stringify(pkg, null, 2)}
+`);
+  } catch (cause) {
+    for (const [file, original] of originals) {
+      if (original === void 0) rmSync(file, { force: true });
+      else if (!existsSync4(file) || !readFileSync3(file).equals(original)) writeFileSync(file, original);
+    }
+    for (const dir of [...createdDirectories].sort((a, b) => b.length - a.length)) {
+      try {
+        rmdirSync(dir);
+      } catch (error2) {
+        if (!["ENOENT", "ENOTEMPTY"].includes(error2.code ?? "")) throw error2;
+      }
+    }
+    throw cause;
+  }
+  if (!values["no-install"]) {
+    const result = spawnSync(manager, ["install"], { cwd: root, stdio: "inherit", shell: process.platform === "win32" });
+    if (result.error || result.status !== 0)
+      throw new Error(`[studio] Files created, but installation failed. Run ${manager} install in ${root} to retry.`);
+  }
+  console.log(`[studio] Ready. ${values["no-install"] ? `Run ${manager} install, then ` : "Run "}${manager} run dev and open /studio.
+The example at /studio-preview reacts to edits; Save writes ${data}.
+To connect your app, read studio.tool(yourTool).config or useToolConfig(studio.tool(yourTool)).
+Optional: mount <StudioDebug studio={studio} /> or <StudioCommandMenu studio={studio} /> from @joycostudio/studio/react.
+For MCP, use the endpoint printed by studio dev. Preview capture additionally requires appUrl and studio install-browser.`);
+}
+
+// src/discovery/watch.ts
+import { existsSync as existsSync5, statSync, watch as watch2 } from "fs";
+import path7 from "path";
+function watchDiscovery(initial, refresh) {
+  let current = initial;
+  let retryInputs = /* @__PURE__ */ new Set();
+  let watchers = [];
+  let timer;
+  let running = false;
+  let pending = false;
+  let closed = false;
+  const schedule = () => {
+    if (closed) return;
+    pending = true;
+    clearTimeout(timer);
+    timer = setTimeout(() => void run(), 80);
+  };
+  const run = async () => {
+    if (running || closed) return;
+    pending = false;
+    running = true;
+    try {
+      const next = await refresh();
+      if (next && !closed) {
+        current = next;
+        retryInputs.clear();
+        bind();
+      }
+    } catch (cause) {
+      if (cause instanceof DiscoveryInputError && !closed) {
+        retryInputs = cause.inputs;
+        bind();
+      }
+      console.error("[studio] discovery update rejected:", cause instanceof Error ? cause.message : cause);
+    } finally {
+      running = false;
+      if (pending) schedule();
+    }
+  };
+  const bind = () => {
+    for (const watcher of watchers) watcher.close();
+    watchers = [];
+    const pages = new Map(
+      [...current.sources].flatMap(
+        (file) => ["tsx", "ts", "jsx", "js"].map((ext) => {
+          const page = path7.join(path7.dirname(file), `page.${ext}`);
+          return [page, existsSync5(page)];
+        })
+      )
+    );
+    const add = (directory, recursive, listener) => {
+      if (!existsSync5(directory)) return;
+      const watcher = watch2(directory, { recursive }, listener);
+      watcher.on("error", (cause) => console.error("[studio] discovery watcher:", cause.message));
+      watcher.unref();
+      watchers.push(watcher);
+    };
+    add(current.toolsDir, true, (event, filename) => {
+      if (!filename) return schedule();
+      const relative = filename.toString();
+      if (relative.split(path7.sep).some((part) => part.startsWith(".") || part === "node_modules")) return;
+      const file = path7.resolve(current.toolsDir, relative);
+      if (path7.basename(file) === "studio.tool.ts" || current.dependencies.has(file)) return schedule();
+      if (pages.has(file)) {
+        if (pages.get(file) !== existsSync5(file)) schedule();
+        return;
+      }
+      if (event === "rename" && (/^page\.[jt]sx?$/.test(path7.basename(file)) || !path7.extname(file) || statSync(file, { throwIfNoEntry: false })?.isDirectory()))
+        schedule();
+    });
+    const targets = /* @__PURE__ */ new Set([
+      ...current.dependencies,
+      ...retryInputs,
+      ...["studio.config.ts", "studio.config.mts", "studio.config.js", "studio.config.mjs", "tsconfig.json"].map(
+        (file) => path7.join(current.root, file)
+      )
+    ]);
+    const byDirectory = /* @__PURE__ */ new Map();
+    for (const file of targets) {
+      let directory = path7.dirname(file);
+      while (!existsSync5(directory) && path7.dirname(directory) !== directory) directory = path7.dirname(directory);
+      const names = byDirectory.get(directory) ?? /* @__PURE__ */ new Set();
+      names.add(path7.relative(directory, file).split(path7.sep)[0]);
+      byDirectory.set(directory, names);
+    }
+    for (const [directory, names] of byDirectory) {
+      add(directory, false, (_, filename) => {
+        if (!filename || names.has(filename.toString())) schedule();
+      });
+    }
+    const directoryId = statSync(current.toolsDir, { throwIfNoEntry: false })?.ino;
+    add(path7.dirname(current.toolsDir), false, (_, filename) => {
+      if ((!filename || filename.toString() === path7.basename(current.toolsDir)) && statSync(current.toolsDir, { throwIfNoEntry: false })?.ino !== directoryId)
+        schedule();
+    });
+  };
+  bind();
+  return {
+    retry: schedule,
+    close() {
+      closed = true;
+      clearTimeout(timer);
+      for (const watcher of watchers) watcher.close();
+    }
+  };
+}
+
 // src/cli.ts
 var HELP = `Usage: studio dev [--config studio.config.ts] [--port ${DEFAULT_PORT}] [--app-url http://localhost:3000] [-- <command...>]
+       studio generate [--config studio.config.ts]
        studio install-browser
+       studio init [directory] [--no-install]
 
 Starts the Studio runtime with a WebSocket bridge and an HTTP MCP endpoint at /mcp,
 moving to the next free port when another project's Studio already uses it.
@@ -664,10 +1446,11 @@ Set appUrl in the config or pass --app-url to enable MCP preview capture. A conf
 appUrl port is passed to the command as PORT, moved to the next free port when taken.
 Run "studio install-browser" once to install Chromium for captures.`;
 async function main(argv) {
+  if (argv[0] === "init") return init(argv.slice(1));
   if (argv[0] === "install-browser") {
-    const require2 = createRequire(import.meta.url);
-    const cli = path4.join(
-      path4.dirname(require2.resolve("playwright/package.json")),
+    const require2 = createRequire2(import.meta.url);
+    const cli = path8.join(
+      path8.dirname(require2.resolve("playwright/package.json")),
       require2("playwright/package.json").bin.playwright
     );
     const child2 = spawn(process.execPath, [cli, "install", "chromium"], { stdio: "inherit" });
@@ -681,7 +1464,7 @@ async function main(argv) {
   const split = argv.indexOf("--");
   const own = split === -1 ? argv : argv.slice(0, split);
   const command = split === -1 ? [] : argv.slice(split + 1);
-  const { positionals, values } = parseArgs({
+  const { positionals, values } = parseArgs2({
     args: own,
     allowPositionals: true,
     options: {
@@ -691,8 +1474,13 @@ async function main(argv) {
       help: { type: "boolean", short: "h" }
     }
   });
+  if (positionals[0] === "generate") {
+    await generate(process.cwd(), values.config);
+    console.log("[studio] generated tool registry and types");
+    return;
+  }
   if (values.help || positionals[0] !== "dev") return console.log(HELP);
-  const { config, root } = await loadConfig(process.cwd(), values.config);
+  const { config, root, discovery } = await loadConfig(process.cwd(), values.config);
   const [bin, ...args] = command;
   const env = { ...process.env };
   let appUrl = values["app-url"] ?? config.appUrl;
@@ -708,10 +1496,30 @@ async function main(argv) {
   const bridge = await serveBridgeNear(runtime, { port, origins: config.origins, appUrl });
   if (bridge.port !== port) console.log(`[studio] port ${port} is in use, probably by another project's Studio`);
   console.log(
-    `[studio] runtime ready on ws://127.0.0.1:${bridge.port} \u2014 ${config.tools.length} tool(s) in ${path4.relative(process.cwd(), root) || "."}`
+    `[studio] runtime ready on ws://127.0.0.1:${bridge.port} \u2014 ${config.tools.length} tool(s) in ${path8.relative(process.cwd(), root) || "."}`
   );
   console.log(`[studio] MCP ready on http://127.0.0.1:${bridge.port}/mcp`);
+  let rejected = false;
+  let accepted = discovery;
+  const watcher = discovery && watchDiscovery(discovery, async () => {
+    try {
+      const next = await loadConfig(process.cwd(), values.config, false, accepted);
+      await runtime.replaceTools(next.config.tools);
+      await next.discovery?.write();
+      accepted = next.discovery;
+      rejected = false;
+      return next.discovery;
+    } catch (cause) {
+      rejected = true;
+      throw cause;
+    }
+  });
+  const unsubscribe = runtime.subscribe((state) => {
+    if (rejected && !state.dirty) watcher?.retry();
+  });
   const shutdown = async (code = 0) => {
+    watcher?.close();
+    unsubscribe();
     runtime.close();
     await bridge.close();
     process.exit(code);
@@ -721,7 +1529,16 @@ async function main(argv) {
     process.once("SIGTERM", () => void shutdown());
     return;
   }
-  const child = spawn(bin, args, { stdio: "inherit", env: { ...env, STUDIO_PORT: String(bridge.port) } });
+  const child = spawn(bin, args, {
+    stdio: "inherit",
+    env: {
+      ...env,
+      STUDIO_PORT: String(bridge.port),
+      NEXT_PUBLIC_STUDIO_RUNTIME: `ws://127.0.0.1:${bridge.port}`,
+      STUDIO_DISCOVERY_MANAGED: discovery ? "1" : "",
+      ...values.config ? { STUDIO_CONFIG: path8.resolve(values.config) } : {}
+    }
+  });
   child.once("exit", (code) => void shutdown(code ?? 0));
   for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => child.kill(signal));
 }