@joycostudio/studio 0.1.2 → 0.1.4

package/README.md

@@ -11,71 +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 }),
   }),
 })
 ```
 
-## 2. Register tools with the runtime
+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.
 
-```ts
-// studio.config.ts (its directory is the project root)
-import { defineConfig } from '@joycostudio/studio'
-import { grading } from './src/tools/grading'
+The preview consumes the live config:
 
-export default defineConfig({ tools: [grading] })
-```
+```tsx
+// src/app/experiments/lighting/page.tsx
+'use client'
+import { useToolConfig } from '@joycostudio/studio/react'
+import { studio } from '../../../studio'
+import lighting from './studio.tool'
 
-```json
-{ "scripts": { "dev": "studio dev -- next dev" } }
+export default function LightingPage() {
+  const config = useToolConfig(studio.tool(lighting))
+  return <div style={{ filter: `brightness(${config.intensity})` }}>Your scene</div>
+}
 ```
 
-`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.
+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`.
 
-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:
+### Overrides and discovery scope
 
 ```ts
-// next.config.ts
-export default { env: { NEXT_PUBLIC_STUDIO_PORT: process.env.STUDIO_PORT ?? '5179' } }
+export default defineTool({
+  id: 'lighting',
+  title: 'Scene Lighting',
+  config: '@/settings/lighting.json',
+  preview: '/scene',
+  controls: (config) => ({/* ... */}),
+})
 ```
 
-## 3. Use it in the app
+`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.
+
+An optional, **user-owned** `studio.config.ts` controls discovery:
 
 ```ts
-// src/studio.ts
-import { createStudio } from '@joycostudio/studio/client'
+import { defineConfig } from '@joycostudio/studio'
 
-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 defineConfig({
+  toolsDir: 'src/app/experiments',
+  // appUrl: 'http://localhost:3000', // Optional MCP capture URL
 })
 ```
 
+`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' })`.
+
+### Generated files and startup
+
+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
+// src/studio.ts (scaffolded once)
+import { createStudio } from '@joycostudio/studio/next'
+import { tools } from '../.studio/registry.generated'
+
+export const studio = createStudio({ tools })
+```
+
 ```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
+// next.config.ts
+import { withStudio } from '@joycostudio/studio/next/config'
+
+export default withStudio({/* your existing Next options */})
+```
+
+`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
@@ -83,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'
 
@@ -107,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.
@@ -119,8 +259,10 @@ in place, and syncs like any other edit. Text fields keep their native undo whil
 
 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.
+and that choice is preserved when hiding and showing the panels. Move the pointer near a hidden panel's screen edge to
+reveal a small tab; click it to bring back only that panel, so you can work with just the tools or just the inspector.
+With one panel open, the shortcut hides it; with both hidden, it brings both back. The tabs also appear on keyboard
+focus and stay visible on touch devices.
 With reduced motion enabled, panels toggle instantly.
 
 Previews use the shared `PreviewCanvas`: Reload and the tool title sit on the left, with Expand and
@@ -129,16 +271,21 @@ pinned; enabling auto-hide overlays the header and hides it after three seconds
 focus, and open menus keep it visible, and touch devices always show the controls. Contained previews
 fit between the side panels, with the inspector stacked below on narrow screens.
 
+Each hidden panel and the expanded canvas are kept in session storage, so the layout survives a refresh
+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. |
 
@@ -156,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'
@@ -194,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'
 
@@ -204,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