@joycostudio/studio 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,204 @@
-# Temporary Holding Version
+# @joycostudio/studio
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Plug project-specific tools into a `/studio` route, the app's floating debug pane, and MCP agents, with one contract per tool.
+
+For contributor instructions on stable releases, betas, and commit previews, see the
+[release workflow guide](../../.changeset/README.md).
+
+A tool's controls are an [Xyz](https://hub.joyco.studio/toolbox/xyz) debug schema (Tweakpane). That same schema:
+
+- renders the inspector in `/studio`,
+- mounts in the app's floating pane (`?debug` / <kbd>Option</kbd>+<kbd>D</kbd>) through Xyz's `DebugManager`,
+- validates every write in the runtime (slider bounds, select options, types, and the shape of `initial`).
+
+## 1. Define a tool
+
+Tool files are loaded by the runtime in Node too, so keep them free of DOM/three imports and `@/` aliases.
+
+```ts
+// src/tools/grading.ts
+import { defineTool } from '@joycostudio/studio'
+import { property, select, slider } from '@joycostudio/xyz/debug'
+import initial from './grading.json'
+
+export const grading = defineTool({
+  id: 'color-grading',
+  file: 'src/tools/grading.json', // where saves go, repo-relative
+  initial, // the same file, imported: production ships the saved config
+  preview: '/', // route shown next to the inspector in /studio
+  controls: (config) => ({
+    exposure: slider(property(config, 'exposure'), { min: 0, max: 3 }),
+    tonemap: select(property(config, 'tonemap'), { ACES: 'aces', Filmic: 'filmic' }),
+  }),
+})
+```
+
+## 2. Register tools with the runtime
+
+```ts
+// studio.config.ts (its directory is the project root)
+import { defineConfig } from '@joycostudio/studio'
+import { grading } from './src/tools/grading'
+
+export default defineConfig({ tools: [grading] })
+```
+
+```json
+{ "scripts": { "dev": "studio dev -- next dev" } }
+```
+
+`studio dev` starts the WebSocket bridge on `ws://127.0.0.1:5179` and the HTTP MCP endpoint on
+`http://127.0.0.1:5179/mcp` (`--port` changes both). It stops when the wrapped command exits.
+
+## 3. Use it in the app
+
+```ts
+// src/studio.ts
+import { createStudio } from '@joycostudio/studio/client'
+
+export const studio = createStudio({
+  tools: [grading],
+  runtime: process.env.NODE_ENV === 'development' && 'ws://127.0.0.1:5179',
+})
+```
+
+```ts
+const tool = studio.tool(grading)
+apply(tool.config) // a live object: read it in your render loop…
+tool.subscribe(apply) // …or react to every change, local or remote
+```
+
+Floating debug pane, with the same controls (plus save/discard when the runtime is up):
+
+```ts
+import { everyFrame } from '@joycostudio/studio/client'
+import { DebugManager } from '@joycostudio/xyz/debug'
+import { Pane } from 'tweakpane'
+
+const debug = new DebugManager({ createPane: () => new Pane(), binding: { registerFrame: everyFrame } })
+for (const tool of studio.tools) debug.register(tool)
+```
+
+The `/studio` route:
+
+```tsx
+// app/studio/page.tsx
+'use client'
+import { Studio } from '@joycostudio/studio/react'
+import { studio } from '@/studio'
+
+export default function StudioPage() {
+  return <Studio studio={studio} />
+}
+```
+
+In Studio, **Command+B** (Mac) or **Ctrl+B** slides both side panels out of view; press it again to bring them back.
+This also works from the same-origin preview iframe. The sidebar's collapse/expand button controls its width separately,
+and that choice is preserved when hiding and showing the panels. Move the pointer near either screen edge to reveal a small
+tab; click it to bring both panels back. The tabs also appear on keyboard focus and stay visible on touch devices.
+With reduced motion enabled, panels toggle instantly.
+
+### Jump to tools from anywhere
+
+Mount `StudioCommandMenu` once in the host app's root layout so it stays available on every route, including `/studio`:
+
+```tsx
+// src/command-menu.tsx
+'use client'
+import '@joycostudio/studio/command-menu.css'
+import { StudioCommandMenu } from '@joycostudio/studio/react'
+import { studio } from './studio'
+
+export function CommandMenu() {
+  return <StudioCommandMenu studio={studio} />
+}
+```
+
+Render `<CommandMenu />` alongside the layout's `{children}`. The host owns mounting it, just like the floating debug pane.
+Its stylesheet is scoped to the menu and can be imported globally without applying Studio's page styles to the host app.
+
+Press **Command+K** (Mac) or **Ctrl+K** to open or close it, type a tool name or ID to search, use **↑/↓** and **Enter** to
+select, or **Escape** to dismiss. Clicking a result also opens it. Results link to `/studio#tool-id`; switching tools from
+inside Studio changes the hash without reloading the page. The shortcut also works while focus is in Studio's same-origin
+preview iframe, opening the menu above Studio rather than inside the preview.
+
+Pass `studioPath="/custom/studio"` for another route. For client-side navigation with a host router, pass its navigation
+function, for example `<StudioCommandMenu studio={studio} navigate={router.push} />` with Next.js `useRouter()`.
+Without a router callback, navigation from another route uses the browser. The menu works without a runtime connection.
+
+To run its browser tests, start the playground and run
+`STUDIO_TEST_APP_URL=http://localhost:3000 pnpm --filter @joycostudio/studio exec vitest run test/command-menu.test.ts`.
+Install Chromium first with `pnpm exec studio install-browser` if needed.
+
+## 4. Connect an MCP agent
+
+Start the app with `studio dev -- <your dev command>` as above. Add a **Streamable HTTP** MCP server to your agent with
+this URL:
+
+```text
+http://127.0.0.1:5179/mcp
+```
+
+Use the URL printed by the CLI when running on a different port. Each project's runtime needs its own port when several
+projects run at once. The endpoint is local to the machine running Studio; a remote/cloud agent cannot reach it through
+its own `localhost`.
+
+The MCP endpoint shares the running app's drafts. It supports both the 2025 MCP initialization flow and the 2026 MCP
+discovery flow, with no separate runtime or MCP process to launch.
+
+| MCP tool                 | Arguments                                      | Result                                                           |
+| ------------------------ | ---------------------------------------------- | ---------------------------------------------------------------- |
+| `studio_list_tools`      | none                                           | Registered IDs, titles, file paths, and preview routes           |
+| `studio_get_tool`        | `tool`                                         | Complete draft, revision, saved value, dirty and conflict status |
+| `studio_update_tool`     | `tool`, `revision`, `value`                    | Validated draft; all connected previews update immediately       |
+| `studio_save_tool`       | `tool`, `revision`, optional `force`           | Draft persisted to its registered JSON file                      |
+| `studio_discard_tool`    | `tool`, `revision`                             | Draft reset to the runtime's latest saved value                  |
+| `studio_capture_preview` | `tool`, optional `revision`, `width`, `height` | PNG image and draft revision from a fresh preview page           |
+
+Read before editing, copy `data.draft.value`, change the intended fields, then pass the **complete config** and
+`data.draft.revision` to `studio_update_tool`. Saving is separate. Use the new revision returned by the update to save or
+discard. If the playground or another agent edits in between, a `stale_revision` error tells you to read again and reconcile
+the changes. `force` bypasses a disk conflict, never a stale revision.
+
+Every tool returns the runtime's `{ ok: true, data }` or `{ ok: false, error, message? }` as structured content and JSON text.
+Runtime failures also set MCP's `isError`, so invalid configs, unknown tools, stale revisions, and disk conflicts remain
+visible to the agent. Expected failures leave the draft intact.
+
+### Preview images
+
+Set the running app's URL once in `studio.config.ts` (or override it with `studio dev --app-url <url>`):
+
+```ts
+export default defineConfig({ tools: [grading], appUrl: 'http://localhost:3000' })
+```
+
+Install Chromium once with `pnpm exec studio install-browser`. Then call `studio_capture_preview` with a tool ID.
+The existing `preview` route must use the Studio client connected to this runtime. No capture code or readiness hooks
+are needed in tool definitions, HTML components, or canvas renderers.
+
+Capture starts a shared headless Chromium browser on first use and opens an isolated page for each request. It reads the
+live unsaved draft, waits for the client to receive that revision, then waits for fonts, current HTML images, and two
+animation frames. CSS animations are disabled for the screenshot. This is automatic settling, not a guarantee that
+arbitrary async work, delayed UI, or WebGL assets have finished. A draft change during capture returns `stale_revision`
+instead of an image. Simultaneous captures return `capture_busy`; retry after the active capture finishes.
+
+The result includes a PNG as MCP image content and metadata with `tool`, `revision`, `url`, `width`, `height`, and
+`settling: 'automatic'`. The viewport defaults to 1200×800 at 1× scale; width accepts 320–2560 and height accepts 240–1600.
+The page starts fresh: it does not inherit your open tab's login, scroll, or interaction state. Preview routes and
+top-level navigation must stay on the configured app origin. Pages that never connect or settle time out.
+
+For the browser integration tests, run `pnpm exec studio install-browser` and
+`pnpm --filter @joycostudio/studio test:capture`. The regular test suite runs setup validation without requiring Chromium.
+
+The server binds to `127.0.0.1` by default and the MCP endpoint checks localhost Host headers and the same browser Origin
+allowlist as the WebSocket bridge. Native agent clients do not need an Origin header. This is a local development endpoint
+without authentication; do not expose it through a public proxy.
+
+## How it fits together
+
+- **Runtime** (`studio dev`) is the only writer. It validates every update, keeps a draft revision per tool, writes atomically,
+  refuses paths outside the project (symlinks included), only accepts localhost browser origins, and watches files for
+  external edits (an external edit over unsaved work becomes a `conflict` that needs discard or force save).
+- **Bridge**: WebSocket (`tools.list`, `tool.get`, `tool.update`, `tool.save`, `tool.discard` + `state` broadcasts) and HTTP MCP
+  on the same port. `/studio`, every app tab, and MCP all go through these same runtime operations.
+- **Without a runtime** (production) tools stay local: the floating pane still tweaks, nothing persists.

package/dist/chunk-QKEAOM2U.js

@@ -0,0 +1,13 @@
+// src/core/result.ts
+var success = (data) => ({ ok: true, data });
+var error = (code, message) => ({
+  ok: false,
+  error: code,
+  ...message === void 0 ? {} : { message }
+});
+
+export {
+  success,
+  error
+};
+//# sourceMappingURL=chunk-QKEAOM2U.js.map

package/dist/chunk-QKEAOM2U.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/result.ts"],"sourcesContent":["export type Success<T> = { ok: true; data: T }\n\nexport type Failure = {\n  ok: false\n  /** snake_case wire code, e.g. `invalid_config`. */\n  error: string\n  message?: string\n}\n\nexport type Result<T> = Success<T> | Failure\n\nexport const success = <T>(data: T): Success<T> => ({ ok: true, data })\n\nexport const error = (code: string, message?: string): Failure => ({\n  ok: false,\n  error: code,\n  ...(message === undefined ? {} : { message }),\n})\n"],"mappings":";AAWO,IAAM,UAAU,CAAI,UAAyB,EAAE,IAAI,MAAM,KAAK;AAE9D,IAAM,QAAQ,CAAC,MAAc,aAA+B;AAAA,EACjE,IAAI;AAAA,EACJ,OAAO;AAAA,EACP,GAAI,YAAY,SAAY,CAAC,IAAI,EAAE,QAAQ;AAC7C;","names":[]}

package/dist/chunk-VYNEG5Z7.js

@@ -0,0 +1,75 @@
+import {
+  error,
+  success
+} from "./chunk-QKEAOM2U.js";
+
+// src/core/validate.ts
+function validateConfig(tool, candidate) {
+  const mismatch = shapeMismatch(tool.initial, candidate, "config");
+  if (mismatch) return error("invalid_config", mismatch);
+  const config = structuredClone(candidate);
+  const invalid = invalidControl(tool.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, path) {
+  const expected = kind(reference);
+  if (kind(value) !== expected) return `${path}: expected ${expected}, got ${kind(value)}`;
+  if (expected === "number" && !Number.isFinite(value)) return `${path}: 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, `${path}[${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 `${path}.${key}: unknown key`;
+    for (const key of Object.keys(ref)) {
+      if (!(key in obj)) return `${path}.${key}: missing`;
+      const nested = shapeMismatch(ref[key], obj[key], `${path}.${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, path = "") {
+  for (const [key, field] of Object.entries(schema)) {
+    if (field.kind === "button") continue;
+    const name = `${path}${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;
+}
+
+export {
+  validateConfig
+};
+//# sourceMappingURL=chunk-VYNEG5Z7.js.map

package/dist/chunk-VYNEG5Z7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/validate.ts"],"sourcesContent":["import type { DebugSchema } from '@joycostudio/xyz/debug'\nimport { error, success, type Result } from './result'\nimport type { ToolDefinition } from './tool'\n\n/**\n * Accept `candidate` as a config for `tool` only if it has the exact shape of\n * `tool.initial` and every control in `tool.controls` accepts its value.\n * Returns a detached copy, never the input.\n */\nexport function validateConfig<TConfig extends object>(\n  tool: ToolDefinition<TConfig>,\n  candidate: unknown,\n): Result<TConfig> {\n  const mismatch = shapeMismatch(tool.initial, candidate, 'config')\n  if (mismatch) return error('invalid_config', mismatch)\n  const config = structuredClone(candidate) as TConfig\n  const invalid = invalidControl(tool.controls(config))\n  return invalid ? error('invalid_config', invalid) : success(config)\n}\n\nfunction kind(value: unknown) {\n  if (value === null) return 'null'\n  if (Array.isArray(value)) return 'array'\n  return typeof value\n}\n\nfunction shapeMismatch(reference: unknown, value: unknown, path: string): string | null {\n  const expected = kind(reference)\n  if (kind(value) !== expected) return `${path}: expected ${expected}, got ${kind(value)}`\n  if (expected === 'number' && !Number.isFinite(value)) return `${path}: expected a finite number`\n  if (expected === 'array') {\n    const [first] = reference as unknown[]\n    if (first === undefined) return null\n    for (const [index, item] of (value as unknown[]).entries()) {\n      const nested = shapeMismatch(first, item, `${path}[${index}]`)\n      if (nested) return nested\n    }\n  }\n  if (expected === 'object') {\n    const ref = reference as Record<string, unknown>\n    const obj = value as Record<string, unknown>\n    for (const key of Object.keys(obj)) if (!(key in ref)) return `${path}.${key}: unknown key`\n    for (const key of Object.keys(ref)) {\n      if (!(key in obj)) return `${path}.${key}: missing`\n      const nested = shapeMismatch(ref[key], obj[key], `${path}.${key}`)\n      if (nested) return nested\n    }\n  }\n  return null\n}\n\nconst isRgb = (value: unknown) =>\n  typeof value === 'object' &&\n  value !== null &&\n  ['r', 'g', 'b'].every((channel) => Number.isFinite((value as Record<string, unknown>)[channel]))\n\nfunction invalidControl(schema: DebugSchema, path = ''): string | null {\n  for (const [key, field] of Object.entries(schema)) {\n    if (field.kind === 'button') continue\n    const name = `${path}${field.label ?? key}`\n    if (field.kind === 'folder') {\n      const nested = invalidControl(field.definition.schema(), `${name}/`)\n      if (nested) return nested\n      continue\n    }\n    const value: unknown = field.read()\n    if (field.kind === 'slider') {\n      if (typeof value !== 'number' || value < field.min || value > field.max)\n        return `${name}: expected a number in [${field.min}, ${field.max}], got ${JSON.stringify(value)}`\n    } else if (field.kind === 'bool') {\n      if (typeof value !== 'boolean') return `${name}: expected a boolean`\n    } else if (field.kind === 'select') {\n      const options = Object.values(field.options)\n      if (!options.includes(value as string | number))\n        return `${name}: expected one of ${JSON.stringify(options)}, got ${JSON.stringify(value)}`\n    } else if (field.kind === 'color-string') {\n      if (typeof value !== 'string') return `${name}: expected a color string`\n    } else if (field.kind === 'color') {\n      if (!isRgb(value)) return `${name}: expected an { r, g, b } color`\n    }\n  }\n  return null\n}\n"],"mappings":"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","names":[]}