@joycostudio/studio 0.1.3 → 0.1.4

package/README.md

@@ -11,83 +11,188 @@ 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
@@ -95,22 +200,41 @@ config from an open peer. Nothing is persisted: closing every page resets these
 config. Save, Discard, and MCP still require a runtime. If a configured runtime disconnects, browser
 sync continues; reconnecting restores the runtime's draft.
 
-Floating debug pane, with the same controls (plus save/discard when the runtime is up):
+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'
+
+;<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 +243,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 +276,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 +303,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 +343,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 +352,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