@joycostudio/studio 0.1.3 → 0.1.5

package/README.md

@@ -11,106 +11,231 @@ A tool's controls are an [Xyz](https://hub.joyco.studio/toolbox/xyz) debug schem
 - 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
+## Quick start: Next.js App Router
 
-Tool files are loaded by the runtime in Node too, so keep them free of DOM/three imports and `@/` aliases.
+In an existing TypeScript Next.js app:
+
+```sh
+pnpm dlx @joycostudio/studio init
+pnpm dev
+```
+
+Open `/studio` and select Example. Move the Scale slider and Save to write the adjacent JSON.
+The initializer supports `app/` and `src/app/`, installs dependencies, wraps your dev command,
+and adds generation to your typecheck script. It wraps the existing Next config with `withStudio`
+so production builds also generate their registry on a clean checkout. The home page stays yours.
+Use `studio init <directory>` to target another app, or `--no-install` to prepare files without installing.
+Reruns skip identical files; conflicting or edited files stop initialization before writes.
+If generation fails, initialization restores existing files and removes newly created setup files.
+Route checks include route groups and handlers. If Studio is already declared, install a version
+with the new exports before running init; an older or missing installation is rejected before writes.
+Existing Studio integrations and custom shell dev scripts use the manual migration below.
+
+## One folder, one tool
+
+Write these three files anywhere under your active app directory:
+
+```text
+src/app/experiments/lighting/
+  page.tsx         # Your normal Next.js preview
+  studio.tool.ts   # Controls and explicit stable ID
+  config.json      # Saved values
+```
+
+`config.json`:
+
+```json
+{ "intensity": 1 }
+```
 
 ```ts
-// src/tools/grading.ts
+// studio.tool.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
+import { property, slider } from '@joycostudio/studio/controls'
+
+export default defineTool({
+  id: 'lighting',
   controls: (config) => ({
-    exposure: slider(property(config, 'exposure'), { min: 0, max: 3 }),
-    tonemap: select(property(config, 'tonemap'), { ACES: 'aces', Filmic: 'filmic' }),
+    intensity: slider(property(config, 'intensity'), { min: 0, max: 5 }),
   }),
 })
 ```
 
-### Preview-only tools
+Studio discovers `studio.tool.ts` and infers the JSON source, save destination, preview URL,
+and title. `id` is explicit so moving the route does not change its identity. Controls receive
+the JSON's inferred TypeScript shape through a generated module augmentation; imports always
+come from `@joycostudio/studio`, never a per-tool generated helper.
 
-A tool with nothing to tune leaves out `file`, `initial`, and `controls`. It still gets a sidebar entry, a pin, and a
-⌘/Ctrl+K entry, but Studio shows only its preview, with no inspector. Register it with the rest of the tools.
+The preview consumes the live config:
+
+```tsx
+// src/app/experiments/lighting/page.tsx
+'use client'
+import { useToolConfig } from '@joycostudio/studio/react'
+import { studio } from '../../../studio'
+import lighting from './studio.tool'
+
+export default function LightingPage() {
+  const config = useToolConfig(studio.tool(lighting))
+  return <div style={{ filter: `brightness(${config.intensity})` }}>Your scene</div>
+}
+```
+
+For a render loop, read `studio.tool(lighting).config` directly, or subscribe to changes with
+`studio.tool(lighting).subscribe(apply)`. Tool definitions also load in Node: keep DOM, React
+components, and renderer imports in your page or scene, not in `studio.tool.ts`.
+
+### Overrides and discovery scope
 
 ```ts
-export const gallery = defineTool({ id: 'gallery', title: 'Gallery', preview: '/gallery' })
+export default defineTool({
+  id: 'lighting',
+  title: 'Scene Lighting',
+  config: '@/settings/lighting.json',
+  preview: '/scene',
+  controls: (config) => ({/* ... */}),
+})
 ```
 
-`studio.definitions` lists every tool in order. `studio.tools` holds handles for tools with a config, so preview-only
-tools never reach the debug pane. Over MCP they are listed without a `file` and can't be read, edited, or captured.
+`config` is a single JSON path for both initial values and saves. It defaults to `./config.json`;
+relative paths resolve from the tool file, and aliases resolve through the app's `tsconfig.json`,
+including inherited paths. JSON must exist and remain inside the project. Two tools cannot write
+the same file. For deterministic generation, default-export `defineTool({ ... })` directly:
+`id`, `config`, and explicit `preview` must be string literals, with no spread/computed option keys.
+Control callbacks can contain normal application logic.
 
-## 2. Register tools with the runtime
+An optional, **user-owned** `studio.config.ts` controls discovery:
 
 ```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] })
+export default defineConfig({
+  toolsDir: 'src/app/experiments',
+  // appUrl: 'http://localhost:3000', // Optional MCP capture URL
+})
 ```
 
-```json
-{ "scripts": { "dev": "studio dev -- next dev" } }
-```
+`toolsDir` is relative to the project root and limits scanning and watching. By default Studio uses
+`app/`, or `src/app/` when there is no root `app/`. Narrowing it does not change preview URLs.
+Hidden directories, node_modules, and symlinked directories are excluded. Route groups such as
+`(experiments)` are stripped from inferred URLs. Dynamic, parallel, intercepted, private, or
+outside-app routes need an explicit concrete `preview`; a missing adjacent page also needs one.
+A preview-only tool can omit `controls` and JSON entirely: `defineTool({ id: 'gallery' })`.
 
-`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` or `port` in the config changes both). It stops when the wrapped command exits.
+### Generated files and startup
 
-Several projects can run at once. When another project's Studio already holds the port, `studio dev` moves to the next
-free one and passes it to the wrapped command as `STUDIO_PORT`. Read that variable instead of hardcoding the port:
+Studio owns only `.studio/registry.generated.ts` and `.studio/types.generated.ts`; ignore `.studio/`
+in Git. The registry references the type map, so importing the registry includes its augmentation
+in the application's TypeScript program. Scaffolded app files remain user-owned after init.
 
 ```ts
-// next.config.ts
-export default { env: { NEXT_PUBLIC_STUDIO_PORT: process.env.STUDIO_PORT ?? '5179' } }
-```
+// src/studio.ts (scaffolded once)
+import { createStudio } from '@joycostudio/studio/next'
+import { tools } from '../.studio/registry.generated'
 
-## 3. Use it in the app
+export const studio = createStudio({ tools })
+```
 
 ```ts
-// src/studio.ts
-import { createStudio } from '@joycostudio/studio/client'
+// next.config.ts
+import { withStudio } from '@joycostudio/studio/next/config'
 
-export const studio = createStudio({
-  tools: [grading],
-  runtime: process.env.NODE_ENV === 'development' && `ws://127.0.0.1:${process.env.NEXT_PUBLIC_STUDIO_PORT}`,
-})
+export default withStudio({/* your existing Next options */})
 ```
 
-```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
+`withStudio` accepts an object or an async/sync Next configuration function and generates before
+`next dev` or `next build`. `studio dev -- next dev` generates first and owns discovery watching
+when the runtime is running. Plain `next dev` also watches, but uses browser-only config syncing.
+For standalone typechecking, run `studio generate && tsc --noEmit` (init configures this script).
+If your TypeScript project excludes the client/registry, explicitly include `.studio/types.generated.ts`.
+Restart the dev server after changing runtime port, origins, or capture URL settings.
+
+During `studio dev`, value-only config changes travel through the runtime transport without
+Next Fast Refresh or a preview remount, including saves and external JSON edits. The generated
+registry embeds stable bootstrap values instead of importing the writable JSON at runtime;
+type-only imports still infer controls from the source JSON. New pages receive current values
+when they connect to the runtime. Changes to JSON structure/types regenerate the bootstrap values.
+A new runtime session, plain `next dev`, `studio generate`, and production builds read fresh values.
+Read live values through `studio.tool(...)` or `useToolConfig`; directly importing the JSON into
+your page or tool helpers gives Next a dependency that will still trigger HMR on saves.
+
+Adding/removing/renaming tools refreshes the registry. Normal page-content edits stay with Next's
+HMR. Tool definitions and their local imported helpers are tracked, as are referenced JSON files
+outside `toolsDir` and TypeScript alias settings. Output is written only when changed.
+Missing or malformed JSON configs remain watched after a rejected update, so completing them
+retries discovery automatically, including aliases outside `toolsDir`.
+The runtime preserves valid drafts during refresh; removing or moving a dirty tool, or making
+its draft incompatible with new controls, rejects the refresh with a diagnostic. Save/discard
+that draft to retry. Invalid updates do not replace the last accepted registry. If a deleted
+source is still imported by that registry, restore it before resolving the draft; Next may show
+a temporary module-not-found error while a removed tool is being rediscovered.
+
+Mount the editor route once (init creates it):
+
+```tsx
+// src/app/studio/page.tsx
+'use client'
+import '@joycostudio/studio/styles.css'
+import { Studio } from '@joycostudio/studio/react'
+import { studio } from '../../studio'
+
+export default function StudioPage() {
+  return <Studio studio={studio} />
+}
 ```
 
+### Existing manual integrations
+
+Explicit `defineTool({ id, file, initial, controls, preview })` definitions and
+`defineConfig({ tools: [...] })` remain supported. An explicit tools list disables discovery;
+do not combine `tools` with `toolsDir`. To migrate, move the declarations into `studio.tool.ts`,
+keep their IDs, replace `file`/`initial` with an optional `config` path, and default-export them.
+Point the client at the generated registry and wrap Next config with `withStudio`.
+For manual setups, install `@joycostudio/studio`, `@joycostudio/xyz`, and `tweakpane` in the app.
+
 Live edits also work without `studio dev`, including in production. Studio shares configs between
 same-origin previews and tabs in the same browser using `BroadcastChannel`. Peers match by tool ID,
 config file, and runtime URL (or no runtime); a newly opened or reloaded preview receives the current
 config from an open peer. Nothing is persisted: closing every page resets these edits to the shipped
-config. Save, Discard, and MCP still require a runtime. If a configured runtime disconnects, browser
-sync continues; reconnecting restores the runtime's draft.
+config. Discard works the same either way: it resets the draft to the saved config (the runtime's last
+reported one, or the shipped config) and syncs like any edit. Save and MCP require a runtime. If a configured
+runtime disconnects, browser sync continues; reconnecting restores the runtime's draft.
+
+Floating debug pane, with the same controls and save/discard actions:
+
+```tsx
+// Mount once in a client component that imports your studio instance.
+import { StudioDebug } from '@joycostudio/studio/react'
 
-Floating debug pane, with the same controls (plus save/discard when the runtime is up):
+;<StudioDebug studio={studio} />
+```
+
+Studio owns lazy pane creation, frame refresh, registration, and cleanup through Xyz's
+DebugManager. `?debug` and Option+D keep their existing behavior. The pane and command menu
+are optional; neither is needed for `/studio`.
+
+The Next.js adapter reads the endpoint passed by `studio dev`, including port overrides and
+collision fallback. No `next.config` changes or hand-written environment variables are needed.
+It defaults to browser-only mode without the CLI or in production. Restart the dev server when
+changing runtime settings. Other frameworks can use the explicit client API:
 
 ```ts
-import { everyFrame } from '@joycostudio/studio/client'
-import { DebugManager } from '@joycostudio/xyz/debug'
-import { Pane } from 'tweakpane'
+import { createStudio } from '@joycostudio/studio/client'
+import config from '../studio.config'
 
-const debug = new DebugManager({ createPane: () => new Pane(), binding: { registerFrame: everyFrame } })
-for (const tool of studio.tools) debug.register(tool)
+export const studio = createStudio(config, { runtime: 'ws://127.0.0.1:5179' })
+// Pass runtime: false for browser-only operation.
 ```
 
+Existing `createStudio({ tools, runtime })` calls remain supported. Both entry points accept
+an explicit runtime override, including `false`.
+
 The `/studio` route:
 
 ```tsx
 // app/studio/page.tsx
 'use client'
+import '@joycostudio/studio/styles.css'
 import { Studio } from '@joycostudio/studio/react'
 import { studio } from '@/studio'
 
@@ -119,6 +244,10 @@ export default function StudioPage() {
 }
 ```
 
+Studio and the command menu render in their own shadow roots and bundle their styles, so neither needs a
+stylesheet import. Host page CSS (global resets, `!important` rules, theme variables such as shadcn's
+`--foreground`, or a resized `<html>` font) can't change them, and their styles never reach the host page.
+
 Use the pin button beside a sidebar tool to keep it at the top. Pinned tools also appear first in the
 **Command/Ctrl+K** menu. Pins are saved in this browser for the current origin and shared across tabs;
 unpinning restores registration order. Pinning a tool keeps the current preview selected.
@@ -148,14 +277,16 @@ in the same tab. New tabs start with panels shown and the canvas contained.
 
 ### Shared canvas and panel components
 
-Import these from `@joycostudio/studio/react` with `@joycostudio/studio/styles.css`:
+Import these from `@joycostudio/studio/react`. Inside Studio (for example, in a `previewComponent`) they
+are already styled; to use them on your own pages, such as a custom-layout tool preview, also import
+`@joycostudio/studio/styles.css` there:
 
 | Component                                                                     | Use                                                                                    |
 | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
 | `StudioSurface`, `StudioToolbar`                                              | Shared inset card and compact action row, including button states.                     |
 | `CanvasToolbar`                                                               | Pinned/auto-hide header; `label`, optional `expanded`/`onToggle`, and child controls.  |
 | `PreviewCanvas`                                                               | Iframe panel with reload, expansion, and a `toolbar` slot replacing the title.         |
-| `StudioSelect`, `StudioSelectItem`                                            | Labeled Radix select with Studio field and portaled menu styling.                      |
+| `StudioSelect`, `StudioSelectItem`                                            | Labeled Base UI select with Studio field and portaled menu styling.                    |
 | `StudioInput`                                                                 | Standard input with logical padding (`ps-*`/`pe-*`) for icon-bearing fields.           |
 | `StudioPanel`, `StudioPanelHeader`, `StudioPanelContent`, `StudioPanelFooter` | Floating panel surface, inset sections, and scrolling body used by Studio's inspector. |
 
@@ -173,7 +304,9 @@ these imports. Module graphs, tracing, and scene-specific controls remain host-o
 
 `Studio` accepts `previewComponent` and `getConfigFileHref`, so integrations no longer need to patch
 the built package. Keep a custom preview component at module scope and forward its iframe ref and
-props; Studio uses them for keyboard shortcuts, comparison, and tool-switch lifecycle:
+props; Studio uses them for keyboard shortcuts, comparison, and tool-switch lifecycle. The component
+renders inside Studio's shadow root, so host stylesheets don't apply to it: build its chrome from the
+shared components below (Studio's Tailwind utilities are available too) or inline styles.
 
 ```tsx
 import { forwardRef, type ComponentPropsWithoutRef } from 'react'
@@ -211,7 +344,6 @@ Mount `StudioCommandMenu` once in the host app's root layout so it stays availab
 ```tsx
 // src/command-menu.tsx
 'use client'
-import '@joycostudio/studio/command-menu.css'
 import { StudioCommandMenu } from '@joycostudio/studio/react'
 import { studio } from './studio'
 
@@ -221,7 +353,8 @@ export function CommandMenu() {
 ```
 
 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.
+It renders in its own shadow root with its styles bundled, so it needs no stylesheet import and is unaffected by the
+host's CSS. (`@joycostudio/studio/command-menu.css` is now empty and only kept so existing imports resolve.)
 
 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

package/dist/{chunk-OIMLF2CL.js → chunk-DEJYGBPJ.js}

@@ -3,10 +3,11 @@ var hasConfig = (tool) => tool.controls !== void 0;
 var ID = /^[a-z0-9][a-z0-9-]*$/;
 function defineTool(tool) {
   if (!ID.test(tool.id)) throw new Error(`[studio] tool id "${tool.id}" must be kebab-case`);
-  const config = [tool.file, tool.initial, tool.controls].filter((part) => part !== void 0).length;
-  if (config === 1 || config === 2)
-    throw new Error(`[studio] tool "${tool.id}" needs all of file, initial, and controls, or none of them`);
-  if (!config && !tool.preview) throw new Error(`[studio] tool "${tool.id}" needs a preview or a config`);
+  const value = tool;
+  if (value.file !== void 0 || value.initial !== void 0) {
+    if (value.file === void 0 || value.initial === void 0 || value.controls === void 0)
+      throw new Error(`[studio] tool "${tool.id}" needs all of file, initial, and controls, or none of them`);
+  }
   return tool;
 }
 var DEFAULT_PORT = 5179;
@@ -97,4 +98,4 @@ export {
   error,
   validateConfig
 };
-//# sourceMappingURL=chunk-OIMLF2CL.js.map
+//# sourceMappingURL=chunk-DEJYGBPJ.js.map

package/dist/chunk-DEJYGBPJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/tool.ts","../src/core/result.ts","../src/core/validate.ts"],"sourcesContent":["import type { DebugSchema } from '@joycostudio/xyz/debug'\n\n/**\n * An SVG icon as data: `[tag, attributes]` children of a 24×24 stroke icon.\n * Lucide's core package (`import { Palette } from 'lucide'`) exports exactly this shape.\n */\nexport type ToolIcon = readonly (readonly [tag: string, attrs: Record<string, string | number | undefined>])[]\n\ntype ToolBase = {\n  /** Unique, URL-safe identifier. */\n  id: string\n  title?: string\n  /** Shown next to the tool in /studio. Data, not a component, so contracts stay loadable in Node. */\n  icon?: ToolIcon\n  /** App route that renders this tool's result, shown next to the controls in /studio. */\n  preview?: string\n  /** Use a bare iframe for tools that already own their canvas layout and headers. */\n  previewLayout?: 'canvas' | 'custom'\n}\n\n/**\n * A tool's contract. Isomorphic on purpose: the runtime loads it in Node to\n * validate and persist, the app loads it in the browser to apply and debug.\n *\n * `TConfig` is the one type that is read, edited, applied, and persisted.\n */\nexport type ToolDefinition<TConfig extends object = object> = ToolBase & {\n  /** Repo-relative JSON file the config persists to. Import that same file as `initial`. */\n  file: string\n  /** Config used before the runtime answers (and in production). */\n  initial: TConfig\n  /**\n   * What can be tweaked, as an Xyz/Tweakpane schema bound to `config`.\n   * Doubles as the runtime validator: every control's bounds are enforced on write.\n   */\n  controls: (config: TConfig) => DebugSchema\n}\n\n/** A tool with nothing to tune: a sidebar entry for its preview, without an inspector or config file. */\nexport type PreviewToolDefinition = ToolBase & {\n  preview: string\n  file?: never\n  initial?: never\n  controls?: never\n}\n\n/** A tool with a config. */\nexport type AnyTool = ToolDefinition<any>\n\n/** Anything `defineTool` returns: the kind follows from whether it declares a config. */\nexport type StudioTool = AnyTool | PreviewToolDefinition\n\nexport const hasConfig = (tool: StudioTool): tool is AnyTool => tool.controls !== undefined\n\n/** Filled by .studio/types.generated.ts in each consuming project. */\nexport interface DiscoveredToolConfigs {}\n\n/** A discovered declaration is resolved into a full definition by the generated registry. */\nexport type DiscoveredToolDefinition<TConfig extends object = object> = ToolBase & {\n  /** JSON source relative to this tool file, or a tsconfig path alias. Defaults to ./config.json. */\n  config?: string\n  controls: (config: TConfig) => DebugSchema\n  file?: never\n  initial?: never\n}\nexport type ToolReference<TConfig extends object> = Pick<ToolDefinition<TConfig>, 'id' | 'controls'>\nexport type ConfigOf<TTool> = TTool extends ToolReference<infer TConfig> ? TConfig : never\n\nconst ID = /^[a-z0-9][a-z0-9-]*$/\n\n/** Discovered tools infer their config from the generated ID-to-JSON type map. */\nexport function defineTool<K extends keyof DiscoveredToolConfigs & string>(\n  tool: Omit<DiscoveredToolDefinition<Extract<DiscoveredToolConfigs[K], object>>, 'id'> & { id: K },\n): DiscoveredToolDefinition<Extract<DiscoveredToolConfigs[K], object>>\n/** Existing explicitly registered tools remain supported. */\nexport function defineTool<TConfig extends object>(tool: ToolDefinition<TConfig>): ToolDefinition<TConfig>\nexport function defineTool(tool: PreviewToolDefinition): PreviewToolDefinition\n/** A discovered preview-only tool may infer its preview from the adjacent page. */\nexport function defineTool(\n  tool: ToolBase & { controls?: never; config?: never; file?: never; initial?: never },\n): ToolBase\nexport function defineTool(tool: StudioTool | DiscoveredToolDefinition<any> | ToolBase) {\n  if (!ID.test(tool.id)) throw new Error(`[studio] tool id \"${tool.id}\" must be kebab-case`)\n  const value = tool as Partial<AnyTool>\n  if (value.file !== undefined || value.initial !== undefined) {\n    if (value.file === undefined || value.initial === undefined || value.controls === undefined)\n      throw new Error(`[studio] tool \"${tool.id}\" needs all of file, initial, and controls, or none of them`)\n  }\n  return tool\n}\n\nexport type StudioConfig = {\n  /** Explicit registry; omit to enable convention-based discovery. */\n  tools?: readonly StudioTool[]\n  /**\n   * Directory to scan and watch for `studio.tool.ts` files, relative to\n   * the project root.\n   *\n   * Defaults to the active Next.js app directory: `app/` or `src/app/`.\n   * Set a narrower directory to reduce scanning and discovery triggers.\n   * This does not change preview URLs.\n   *\n   * @example 'src/app/experiments'\n   */\n  toolsDir?: string\n  /** Runtime WebSocket and HTTP MCP port. Defaults to 5179. */\n  port?: number\n  /** Browser origins allowed on the bridge and MCP endpoint. Defaults to localhost origins. */\n  origins?: readonly string[]\n  /** Running app URL (e.g. http://localhost:3000), used for MCP preview captures. */\n  appUrl?: string\n}\n\nexport const DEFAULT_PORT = 5179\n\nexport function defineConfig<T extends StudioConfig>(config: T): T {\n  return config\n}\n","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","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":[]}