@joycostudio/studio 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,687 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { spawn } from "child_process";
+import { createRequire } from "module";
+import path4 from "path";
+import { parseArgs } from "util";
+
+// src/core/tool.ts
+var DEFAULT_PORT = 5179;
+
+// src/runtime/runtime.ts
+import { watch } from "fs";
+import path2 from "path";
+
+// src/core/result.ts
+var success = (data) => ({ ok: true, data });
+var error = (code, message) => ({
+  ok: false,
+  error: code,
+  ...message === void 0 ? {} : { message }
+});
+
+// src/core/validate.ts
+function validateConfig(tool2, candidate) {
+  const mismatch = shapeMismatch(tool2.initial, candidate, "config");
+  if (mismatch) return error("invalid_config", mismatch);
+  const config = structuredClone(candidate);
+  const invalid = invalidControl(tool2.controls(config));
+  return invalid ? error("invalid_config", invalid) : success(config);
+}
+function kind(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+function shapeMismatch(reference, value, path5) {
+  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 (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}]`);
+      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(ref)) {
+      if (!(key in obj)) return `${path5}.${key}: missing`;
+      const nested = shapeMismatch(ref[key], obj[key], `${path5}.${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 = "") {
+  for (const [key, field] of Object.entries(schema)) {
+    if (field.kind === "button") continue;
+    const name = `${path5}${field.label ?? key}`;
+    if (field.kind === "folder") {
+      const nested = invalidControl(field.definition.schema(), `${name}/`);
+      if (nested) return nested;
+      continue;
+    }
+    const value = field.read();
+    if (field.kind === "slider") {
+      if (typeof value !== "number" || value < field.min || value > field.max)
+        return `${name}: expected a number in [${field.min}, ${field.max}], got ${JSON.stringify(value)}`;
+    } else if (field.kind === "bool") {
+      if (typeof value !== "boolean") return `${name}: expected a boolean`;
+    } else if (field.kind === "select") {
+      const options = Object.values(field.options);
+      if (!options.includes(value))
+        return `${name}: expected one of ${JSON.stringify(options)}, got ${JSON.stringify(value)}`;
+    } else if (field.kind === "color-string") {
+      if (typeof value !== "string") return `${name}: expected a color string`;
+    } else if (field.kind === "color") {
+      if (!isRgb(value)) return `${name}: expected an { r, g, b } color`;
+    }
+  }
+  return null;
+}
+
+// src/runtime/files.ts
+import { createHash, randomUUID } from "crypto";
+import { mkdir, readFile, realpath, rename, rm, stat } from "fs/promises";
+import { writeFile } from "fs/promises";
+import path from "path";
+var inside = (root, target) => {
+  const relative = path.relative(root, target);
+  return relative !== "" && !relative.startsWith("..") && !path.isAbsolute(relative);
+};
+var exists = (target) => stat(target).then(
+  () => true,
+  () => 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 absolute = path.resolve(root, file);
+  if (!inside(root, absolute)) throw fail("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");
+  return absolute;
+}
+var hashOf = (content) => createHash("sha256").update(content).digest("hex").slice(0, 16);
+var serialize = (value) => `${JSON.stringify(value, null, 2)}
+`;
+async function readDisk(file) {
+  try {
+    const content = await readFile(file, "utf8");
+    return { content, hash: hashOf(content) };
+  } catch (cause) {
+    if (cause.code === "ENOENT") return null;
+    throw cause;
+  }
+}
+async function writeAtomic(file, content) {
+  await mkdir(path.dirname(file), { recursive: true });
+  const temp = `${file}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temp, content, "utf8");
+    await rename(temp, file);
+  } catch (cause) {
+    await rm(temp, { force: true });
+    throw cause;
+  }
+}
+
+// src/runtime/runtime.ts
+var equal = (a, b) => {
+  if (a === b) return true;
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+  const keys = Object.keys(a);
+  return keys.length === Object.keys(b).length && keys.every((key) => equal(a[key], b[key]));
+};
+async function load(tool2, file) {
+  const disk = await readDisk(file);
+  if (!disk) return { value: structuredClone(tool2.initial), hash: null };
+  const parsed = validateConfig(tool2, JSON.parse(disk.content));
+  if (!parsed.ok)
+    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);
+  const entries = /* @__PURE__ */ new Map();
+  const files = /* @__PURE__ */ new Set();
+  for (const tool2 of tools) {
+    if (entries.has(tool2.id)) throw new Error(`[studio] duplicate tool id "${tool2.id}"`);
+    const file = await resolveToolFile(root, tool2.file);
+    if (files.has(file)) throw new Error(`[studio] tool "${tool2.id}" shares its file with another tool`);
+    files.add(file);
+    const saved = await load(tool2, file);
+    entries.set(tool2.id, {
+      tool: tool2,
+      file,
+      queue: Promise.resolve(),
+      state: {
+        tool: tool2.id,
+        draft: { value: structuredClone(saved.value), revision: 0 },
+        saved,
+        dirty: false,
+        conflict: false
+      }
+    });
+  }
+  const listeners = /* @__PURE__ */ new Set();
+  const commit = (entry, next, origin) => {
+    const state = { ...entry.state, ...next };
+    state.dirty = !equal(state.draft.value, state.saved.value);
+    if (!state.dirty) state.conflict = false;
+    entry.state = state;
+    for (const listener of listeners) listener(state, origin);
+    return state;
+  };
+  const serial = (entry, task) => {
+    const run = entry.queue.then(task);
+    entry.queue = run.catch(() => {
+    });
+    return run;
+  };
+  const handlers = {
+    "tools.list": async () => success(
+      [...entries.values()].map(({ tool: tool2 }) => ({
+        id: tool2.id,
+        title: tool2.title ?? tool2.id,
+        file: tool2.file,
+        icon: tool2.icon,
+        preview: tool2.preview
+      }))
+    ),
+    "tool.get": async ({ tool: tool2 }) => withEntry(tool2, async (entry) => success(entry.state)),
+    "tool.update": async ({ tool: tool2, value, revision: revision2 }, origin) => withEntry(tool2, async (entry) => {
+      if (revision2 !== void 0 && revision2 !== entry.state.draft.revision)
+        return error("stale_revision", `draft is at revision ${entry.state.draft.revision}, not ${revision2}`);
+      const parsed = validateConfig(entry.tool, value);
+      if (!parsed.ok) return parsed;
+      const draft = { value: parsed.data, revision: entry.state.draft.revision + 1 };
+      return success(commit(entry, { draft }, origin));
+    }),
+    "tool.save": async ({ tool: tool2, revision: revision2, force = false }, origin) => withEntry(
+      tool2,
+      (entry) => serial(entry, async () => {
+        const { draft, saved } = entry.state;
+        if (revision2 !== draft.revision)
+          return error("stale_revision", `draft is at revision ${draft.revision}, not ${revision2}`);
+        const disk = await readDisk(entry.file);
+        if (!force && (entry.state.conflict || (disk?.hash ?? null) !== saved.hash)) {
+          commit(entry, { conflict: true });
+          return error("conflict", `${entry.tool.file} changed on disk; discard to reload or save with force`);
+        }
+        const content = serialize(draft.value);
+        await writeAtomic(entry.file, content);
+        return success(
+          commit(entry, { saved: { value: structuredClone(draft.value), hash: hashOf(content) } }, origin)
+        );
+      })
+    ),
+    "tool.discard": async ({ tool: tool2, revision: revision2 }, origin) => withEntry(tool2, async (entry) => {
+      const { saved, draft } = entry.state;
+      if (revision2 !== void 0 && revision2 !== draft.revision)
+        return error("stale_revision", `draft is at revision ${draft.revision}, not ${revision2}`);
+      return success(
+        commit(entry, { draft: { value: structuredClone(saved.value), revision: draft.revision + 1 } }, origin)
+      );
+    })
+  };
+  async function withEntry(id, task) {
+    const entry = typeof id === "string" ? entries.get(id) : void 0;
+    return entry ? task(entry) : error("unknown_tool", `no tool "${String(id)}"`);
+  }
+  const reload = (entry) => serial(entry, async () => {
+    const disk = await readDisk(entry.file);
+    const { saved, draft, dirty } = entry.state;
+    if ((disk?.hash ?? null) === saved.hash) return;
+    if (!disk) return commit(entry, { saved: { ...saved, hash: null } });
+    let value;
+    try {
+      value = JSON.parse(disk.content);
+    } catch {
+      return console.warn(`[studio] ignoring unparsable ${entry.tool.file}`);
+    }
+    const parsed = validateConfig(entry.tool, value);
+    if (!parsed.ok) return console.warn(`[studio] ignoring invalid ${entry.tool.file}: ${parsed.message}`);
+    const next = { saved: { value: parsed.data, hash: disk.hash } };
+    if (dirty) next.conflict = true;
+    else next.draft = { value: structuredClone(parsed.data), revision: draft.revision + 1 };
+    commit(entry, next);
+  });
+  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)
+          );
+        }
+      });
+      watchers.push(watcher);
+    } catch {
+      console.warn(`[studio] not watching ${path2.relative(root, directory)} (it does not exist yet)`);
+    }
+  }
+  return {
+    root,
+    run: (op, params, origin) => handlers[op](params, origin),
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    close() {
+      for (const watcher of watchers) watcher.close();
+      for (const timer of timers.values()) clearTimeout(timer);
+      listeners.clear();
+    }
+  };
+}
+
+// src/runtime/server.ts
+import { createServer } from "http";
+import { localhostHostValidation, toNodeHandler } from "@modelcontextprotocol/node";
+import { createMcpHandler } from "@modelcontextprotocol/server";
+import { WebSocketServer } from "ws";
+
+// src/runtime/capture.ts
+function previewSnapshot({ port, tool: tool2, revision: revision2 }) {
+  const instances = globalThis.__joycoStudio;
+  for (const [address, studio] of instances ?? []) {
+    const url = new URL(address);
+    if (!["localhost", "127.0.0.1", "[::1]"].includes(url.hostname) || Number(url.port) !== port) continue;
+    const handle = studio.tools.find((handle2) => handle2.definition.id === tool2);
+    if (studio.connection.phase !== "connected" || !handle?.state || handle.comparing) continue;
+    if (handle.state.draft.revision < revision2) continue;
+    return { revision: handle.state.draft.revision, version: handle.version };
+  }
+  return null;
+}
+function createPreviewCapture(runtime, { appUrl, runtimePort, timeoutMs = 2e4 }) {
+  let browser;
+  let active = false;
+  let closed = false;
+  const capture = async ({
+    tool: tool2,
+    revision: revision2,
+    width = 1200,
+    height = 800
+  }) => {
+    if (closed) return error("capture_unavailable", "Studio is shutting down");
+    if (active) return error("capture_busy", "Another preview is being captured; retry when it finishes");
+    const state = await runtime.run("tool.get", { tool: tool2 });
+    if (!state.ok) return state;
+    revision2 ??= state.data.draft.revision;
+    if (revision2 !== state.data.draft.revision) return error("stale_revision", "Read the latest draft before capturing");
+    const tools = await runtime.run("tools.list", {});
+    if (!tools.ok) return tools;
+    const preview = tools.data.find((entry) => entry.id === tool2)?.preview;
+    if (!preview) return error("preview_missing", `Tool "${tool2}" has no preview route`);
+    if (!appUrl) return error("app_url_missing", "Set appUrl in studio.config.ts or pass studio dev --app-url <url>");
+    let url;
+    try {
+      const base = new URL(appUrl);
+      url = new URL(preview, base);
+      if (!["http:", "https:"].includes(base.protocol) || url.origin !== base.origin || url.username || url.password)
+        return error("invalid_preview_url", "The preview must be an HTTP(S) route on the configured app origin");
+    } catch {
+      return error("invalid_preview_url", "appUrl must be an absolute HTTP(S) URL and preview must be a valid route");
+    }
+    if (active) return error("capture_busy", "Another preview is being captured; retry when it finishes");
+    if (closed) return error("capture_unavailable", "Studio is shutting down");
+    active = true;
+    let context;
+    let timer;
+    let timedOut = false;
+    let phase = "starting the browser";
+    try {
+      browser ??= import("playwright").then(({ chromium }) => chromium.launch({ headless: true, timeout: 1e4 }));
+      let instance;
+      try {
+        instance = await browser;
+      } catch (cause) {
+        browser = void 0;
+        return error("capture_unavailable", `Run "studio install-browser" to install Chromium. ${String(cause)}`);
+      }
+      if (closed) return error("capture_unavailable", "Studio is shutting down");
+      if (!instance.isConnected()) {
+        browser = void 0;
+        return error("capture_unavailable", "The capture browser disconnected; retry to start it again");
+      }
+      context = await instance.newContext({ viewport: { width, height }, deviceScaleFactor: 1 });
+      timer = setTimeout(() => {
+        timedOut = true;
+        void context?.close().catch(() => {
+        });
+      }, timeoutMs);
+      const page = await context.newPage();
+      page.setDefaultTimeout(timeoutMs);
+      await page.route("**/*", (route) => {
+        const request = route.request();
+        return request.isNavigationRequest() && request.frame() === page.mainFrame() && new URL(request.url()).origin !== url.origin ? route.abort() : route.continue();
+      });
+      phase = "opening the preview";
+      const response = await page.goto(url.href, { waitUntil: "load" });
+      if (!response?.ok()) return error("preview_failed", `Preview returned HTTP ${response?.status() ?? "unknown"}`);
+      phase = "waiting for the preview to receive the draft";
+      const target = { port: runtimePort(), tool: tool2, revision: revision2 };
+      const synced = await page.waitForFunction(previewSnapshot, target);
+      const initial = await synced.jsonValue();
+      await synced.dispose();
+      if (initial?.revision !== revision2) return error("stale_revision", "The draft changed while opening the preview");
+      phase = "waiting for fonts, images, and animation frames";
+      await page.evaluate(async () => {
+        await document.fonts.ready;
+        await Promise.all(Array.from(document.images, (image) => image.decode().catch(() => {
+        })));
+        await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve())));
+      });
+      const before = await page.evaluate(previewSnapshot, target);
+      if (before?.revision !== revision2) return error("stale_revision", "The draft changed while settling the preview");
+      phase = "taking the screenshot";
+      const png = await page.screenshot({ type: "png", animations: "disabled", timeout: timeoutMs });
+      const after = await page.evaluate(previewSnapshot, target);
+      const latest = await runtime.run("tool.get", { tool: tool2 });
+      if (!latest.ok) return latest;
+      if (latest.data.draft.revision !== revision2 || after?.revision !== revision2 || after.version !== before.version)
+        return error("stale_revision", "The preview changed during capture; read the latest draft and retry");
+      return success({ tool: tool2, revision: revision2, url: page.url(), width, height, settling: "automatic", png });
+    } catch (cause) {
+      if (closed) return error("capture_unavailable", "Studio is shutting down");
+      return error(
+        timedOut || cause instanceof Error && cause.name === "TimeoutError" ? "preview_not_ready" : "capture_failed",
+        `${phase}: ${String(cause)}`
+      );
+    } finally {
+      clearTimeout(timer);
+      await context?.close().catch(() => {
+      });
+      active = false;
+    }
+  };
+  return {
+    capture,
+    async close() {
+      closed = true;
+      await browser?.then((instance) => instance.close()).catch(() => {
+      });
+      browser = void 0;
+    }
+  };
+}
+
+// src/runtime/mcp.ts
+import { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod/v4";
+var tool = z.string().min(1).describe("Registered Studio tool ID from studio_list_tools.");
+var revision = z.number().int().nonnegative().describe("Draft revision returned by the latest read or update.");
+function createMcpServer(runtime, previews) {
+  const server = new McpServer(
+    { name: "joyco-studio", version: "0.0.0" },
+    {
+      instructions: "List Studio tools, read the selected tool, then update its complete draft value. Updates appear live in the playground. Saving is a separate operation. If a revision is stale, read again and reconcile your changes before retrying."
+    }
+  );
+  const run = async (op, params) => {
+    const result = await runtime.run(op, params);
+    return {
+      content: [{ type: "text", text: JSON.stringify(result) }],
+      structuredContent: result,
+      isError: !result.ok
+    };
+  };
+  server.registerTool(
+    "studio_list_tools",
+    {
+      description: "List registered Studio tools with their IDs, titles, config files, and preview routes.",
+      inputSchema: z.object({}),
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    () => run("tools.list", {})
+  );
+  server.registerTool(
+    "studio_get_tool",
+    {
+      description: "Read a tool\u2019s complete draft, revision, saved value, and dirty/conflict status before editing.",
+      inputSchema: z.object({ tool }),
+      annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    (params) => run("tool.get", params)
+  );
+  server.registerTool(
+    "studio_update_tool",
+    {
+      description: "Replace the complete draft config and update all connected previews. Read first and preserve fields you are not changing. The runtime validates types, slider bounds, and select options. Does not save to disk; rejects a stale revision.",
+      inputSchema: z.object({ tool, revision, value: z.record(z.string(), z.unknown()) }),
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }
+    },
+    (params) => run("tool.update", params)
+  );
+  server.registerTool(
+    "studio_save_tool",
+    {
+      description: "Persist a draft to its registered JSON file. Pass the latest draft revision. Rejects stale revisions and changes made on disk; force explicitly overwrites a disk conflict.",
+      inputSchema: z.object({ tool, revision, force: z.boolean().optional() }),
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false }
+    },
+    (params) => run("tool.save", params)
+  );
+  server.registerTool(
+    "studio_discard_tool",
+    {
+      description: "Discard unsaved edits and restore the runtime\u2019s latest saved value in every preview. Read first; rejects a stale revision.",
+      inputSchema: z.object({ tool, revision }),
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }
+    },
+    (params) => run("tool.discard", params)
+  );
+  server.registerTool(
+    "studio_capture_preview",
+    {
+      description: "Capture a registered preview as a PNG in a fresh browser page using the live draft. Requires appUrl and Chromium (studio install-browser). Defaults to the current revision and 1200\xD7800. Waits for draft sync, fonts, images, and two animation frames; automatic settling does not guarantee arbitrary async scenes are finished. Rejects a draft change during capture. Does not share your open tab\u2019s scroll, login, or interaction state.",
+      inputSchema: z.object({
+        tool,
+        revision: revision.optional(),
+        width: z.number().int().min(320).max(2560).optional(),
+        height: z.number().int().min(240).max(1600).optional()
+      }),
+      annotations: { readOnlyHint: true, idempotentHint: false, openWorldHint: true }
+    },
+    async (params) => {
+      const captured = await previews.capture(params);
+      if (!captured.ok)
+        return {
+          content: [{ type: "text", text: JSON.stringify(captured) }],
+          structuredContent: captured,
+          isError: true
+        };
+      const { png, ...metadata } = captured.data;
+      const result = success(metadata);
+      return {
+        content: [
+          { type: "text", text: JSON.stringify(result) },
+          { type: "image", mimeType: "image/png", data: png.toString("base64") }
+        ],
+        structuredContent: result,
+        isError: false
+      };
+    }
+  );
+  return server;
+}
+
+// src/runtime/server.ts
+var LOCAL_ORIGIN = /^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/;
+var OPS = /* @__PURE__ */ new Set(["tools.list", "tool.get", "tool.update", "tool.save", "tool.discard"]);
+function parse(raw) {
+  try {
+    const message = JSON.parse(raw);
+    if (typeof message?.id !== "number" || !OPS.has(message.op)) return null;
+    return { id: message.id, op: message.op, params: message.params ?? {} };
+  } catch {
+    return null;
+  }
+}
+function serveBridge(runtime, { port, host = "127.0.0.1", origins, appUrl }) {
+  const allowed = (origin) => origin === void 0 || (origins ? origins.includes(origin) : LOCAL_ORIGIN.test(origin));
+  const onerror = (cause) => console.error("[studio] MCP request failed", cause);
+  const previews = createPreviewCapture(runtime, { appUrl, runtimePort: () => http.address().port });
+  const mcp = createMcpHandler(() => createMcpServer(runtime, previews), { onerror });
+  const handleMcp = toNodeHandler(mcp, { onerror });
+  const validateHost = localhostHostValidation();
+  const http = createServer((request, response) => {
+    if (request.url?.split("?")[0] !== "/mcp") {
+      response.writeHead(404).end();
+      return;
+    }
+    if (!validateHost(request, response)) return;
+    if (!allowed(request.headers.origin)) {
+      response.writeHead(403).end("Origin not allowed");
+      return;
+    }
+    void handleMcp(request, response);
+  });
+  const server = new WebSocketServer({
+    server: http,
+    verifyClient: ({ origin }) => allowed(origin)
+  });
+  const send = (socket, message) => {
+    if (socket.readyState === socket.OPEN) socket.send(JSON.stringify(message));
+  };
+  server.on("connection", (socket) => {
+    socket.on("message", async (raw) => {
+      const request = parse(raw.toString());
+      if (!request) return send(socket, { type: "response", id: -1, result: error("bad_request") });
+      const result = await runtime.run(request.op, request.params, socket).catch((cause) => error("internal", cause instanceof Error ? cause.message : String(cause)));
+      send(socket, { type: "response", id: request.id, result });
+    });
+  });
+  const unsubscribe = runtime.subscribe((state, origin) => {
+    for (const client of server.clients) if (client !== origin) send(client, { type: "state", state });
+  });
+  return new Promise((resolve, reject) => {
+    server.once("error", (cause) => {
+      unsubscribe();
+      server.close();
+      void mcp.close();
+      void previews.close();
+      reject(cause);
+    });
+    http.once(
+      "listening",
+      () => resolve({
+        port: http.address().port,
+        close: async () => {
+          unsubscribe();
+          await previews.close();
+          for (const client of server.clients) client.terminate();
+          await mcp.close();
+          await new Promise((done) => server.close(() => done()));
+          await new Promise((done) => {
+            http.close(() => done());
+            http.closeAllConnections();
+          });
+        }
+      })
+    );
+    http.listen(port, host);
+  });
+}
+
+// src/runtime/load.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) };
+}
+
+// src/cli.ts
+var HELP = `Usage: studio dev [--config studio.config.ts] [--port ${DEFAULT_PORT}] [--app-url http://localhost:3000] [-- <command...>]
+       studio install-browser
+
+Starts the Studio runtime with a WebSocket bridge and an HTTP MCP endpoint at /mcp.
+Anything after "--" runs alongside it (e.g. "next dev")
+and the runtime stops when that command exits.
+Set appUrl in the config or pass --app-url to enable MCP preview capture.
+Run "studio install-browser" once to install Chromium for captures.`;
+async function main(argv) {
+  if (argv[0] === "install-browser") {
+    const require2 = createRequire(import.meta.url);
+    const cli = path4.join(
+      path4.dirname(require2.resolve("playwright/package.json")),
+      require2("playwright/package.json").bin.playwright
+    );
+    const child2 = spawn(process.execPath, [cli, "install", "chromium"], { stdio: "inherit" });
+    child2.once("error", (cause) => {
+      console.error(cause.message);
+      process.exit(1);
+    });
+    child2.once("exit", (code) => process.exit(code ?? 1));
+    return;
+  }
+  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({
+    args: own,
+    allowPositionals: true,
+    options: {
+      config: { type: "string" },
+      port: { type: "string" },
+      "app-url": { type: "string" },
+      help: { type: "boolean", short: "h" }
+    }
+  });
+  if (values.help || positionals[0] !== "dev") return console.log(HELP);
+  const { config, root } = await loadConfig(process.cwd(), values.config);
+  const runtime = await createRuntime({ root, tools: config.tools });
+  const bridge = await serveBridge(runtime, {
+    port: Number(values.port ?? config.port ?? DEFAULT_PORT),
+    origins: config.origins,
+    appUrl: values["app-url"] ?? config.appUrl
+  });
+  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) || "."}`
+  );
+  console.log(`[studio] MCP ready on http://127.0.0.1:${bridge.port}/mcp`);
+  const shutdown = async (code = 0) => {
+    runtime.close();
+    await bridge.close();
+    process.exit(code);
+  };
+  const [bin, ...args] = command;
+  if (!bin) {
+    process.once("SIGINT", () => void shutdown());
+    process.once("SIGTERM", () => void shutdown());
+    return;
+  }
+  const child = spawn(bin, args, { stdio: "inherit", env: { ...process.env, STUDIO_PORT: String(bridge.port) } });
+  child.once("exit", (code) => void shutdown(code ?? 0));
+  for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => child.kill(signal));
+}
+main(process.argv.slice(2)).catch((cause) => {
+  console.error(cause instanceof Error ? cause.message : cause);
+  process.exit(1);
+});
+//# sourceMappingURL=cli.js.map