@joycostudio/studio 0.1.2 → 0.1.4

package/dist/next-config.js

@@ -0,0 +1,135 @@
+import {
+  DiscoveryInputError,
+  generate
+} from "./chunk-HVGJXFXT.js";
+
+// src/discovery/watch.ts
+import { existsSync, statSync, watch } from "fs";
+import path from "path";
+function watchDiscovery(initial, refresh) {
+  let current = initial;
+  let retryInputs = /* @__PURE__ */ new Set();
+  let watchers2 = [];
+  let timer;
+  let running = false;
+  let pending = false;
+  let closed = false;
+  const schedule = () => {
+    if (closed) return;
+    pending = true;
+    clearTimeout(timer);
+    timer = setTimeout(() => void run(), 80);
+  };
+  const run = async () => {
+    if (running || closed) return;
+    pending = false;
+    running = true;
+    try {
+      const next = await refresh();
+      if (next && !closed) {
+        current = next;
+        retryInputs.clear();
+        bind();
+      }
+    } catch (cause) {
+      if (cause instanceof DiscoveryInputError && !closed) {
+        retryInputs = cause.inputs;
+        bind();
+      }
+      console.error("[studio] discovery update rejected:", cause instanceof Error ? cause.message : cause);
+    } finally {
+      running = false;
+      if (pending) schedule();
+    }
+  };
+  const bind = () => {
+    for (const watcher of watchers2) watcher.close();
+    watchers2 = [];
+    const pages = new Map(
+      [...current.sources].flatMap(
+        (file) => ["tsx", "ts", "jsx", "js"].map((ext) => {
+          const page = path.join(path.dirname(file), `page.${ext}`);
+          return [page, existsSync(page)];
+        })
+      )
+    );
+    const add = (directory, recursive, listener) => {
+      if (!existsSync(directory)) return;
+      const watcher = watch(directory, { recursive }, listener);
+      watcher.on("error", (cause) => console.error("[studio] discovery watcher:", cause.message));
+      watcher.unref();
+      watchers2.push(watcher);
+    };
+    add(current.toolsDir, true, (event, filename) => {
+      if (!filename) return schedule();
+      const relative = filename.toString();
+      if (relative.split(path.sep).some((part) => part.startsWith(".") || part === "node_modules")) return;
+      const file = path.resolve(current.toolsDir, relative);
+      if (path.basename(file) === "studio.tool.ts" || current.dependencies.has(file)) return schedule();
+      if (pages.has(file)) {
+        if (pages.get(file) !== existsSync(file)) schedule();
+        return;
+      }
+      if (event === "rename" && (/^page\.[jt]sx?$/.test(path.basename(file)) || !path.extname(file) || statSync(file, { throwIfNoEntry: false })?.isDirectory()))
+        schedule();
+    });
+    const targets = /* @__PURE__ */ new Set([
+      ...current.dependencies,
+      ...retryInputs,
+      ...["studio.config.ts", "studio.config.mts", "studio.config.js", "studio.config.mjs", "tsconfig.json"].map(
+        (file) => path.join(current.root, file)
+      )
+    ]);
+    const byDirectory = /* @__PURE__ */ new Map();
+    for (const file of targets) {
+      let directory = path.dirname(file);
+      while (!existsSync(directory) && path.dirname(directory) !== directory) directory = path.dirname(directory);
+      const names = byDirectory.get(directory) ?? /* @__PURE__ */ new Set();
+      names.add(path.relative(directory, file).split(path.sep)[0]);
+      byDirectory.set(directory, names);
+    }
+    for (const [directory, names] of byDirectory) {
+      add(directory, false, (_, filename) => {
+        if (!filename || names.has(filename.toString())) schedule();
+      });
+    }
+    const directoryId = statSync(current.toolsDir, { throwIfNoEntry: false })?.ino;
+    add(path.dirname(current.toolsDir), false, (_, filename) => {
+      if ((!filename || filename.toString() === path.basename(current.toolsDir)) && statSync(current.toolsDir, { throwIfNoEntry: false })?.ino !== directoryId)
+        schedule();
+    });
+  };
+  bind();
+  return {
+    retry: schedule,
+    close() {
+      closed = true;
+      clearTimeout(timer);
+      for (const watcher of watchers2) watcher.close();
+    }
+  };
+}
+
+// src/next-config.ts
+var watchers = /* @__PURE__ */ new Map();
+function withStudio(config) {
+  return async (phase, context) => {
+    const next = typeof config === "function" ? await config(phase, context) : config;
+    if (phase !== "phase-production-server" && !process.env.STUDIO_DISCOVERY_MANAGED) {
+      const root = process.cwd();
+      const explicit = process.env.STUDIO_CONFIG;
+      const discovery = await generate(root, explicit);
+      if (discovery && phase === "phase-development-server" && !process.env.STUDIO_DISCOVERY_MANAGED && !watchers.has(root)) {
+        watchers.set(
+          root,
+          watchDiscovery(discovery, () => generate(root, explicit))
+        );
+      }
+    }
+    return next;
+  };
+}
+export {
+  withStudio
+};
+//# sourceMappingURL=next-config.js.map

package/dist/next-config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/discovery/watch.ts","../src/next-config.ts"],"sourcesContent":["import { existsSync, statSync, watch, type FSWatcher } from 'node:fs'\nimport path from 'node:path'\nimport { DiscoveryInputError, type Discovery } from './generate'\n\n/** Watch the selected tree, plus exact imported dependencies outside it. No page-content triggers. */\nexport function watchDiscovery(initial: Discovery, refresh: () => Promise<Discovery | undefined>) {\n  let current = initial\n  let retryInputs = new Set<string>()\n  let watchers: FSWatcher[] = []\n  let timer: NodeJS.Timeout | undefined\n  let running = false\n  let pending = false\n  let closed = false\n  const schedule = () => {\n    if (closed) return\n    pending = true\n    clearTimeout(timer)\n    timer = setTimeout(() => void run(), 80)\n  }\n  const run = async () => {\n    if (running || closed) return\n    pending = false\n    running = true\n    try {\n      const next = await refresh()\n      if (next && !closed) {\n        current = next\n        retryInputs.clear()\n        bind()\n      }\n    } catch (cause) {\n      if (cause instanceof DiscoveryInputError && !closed) {\n        retryInputs = cause.inputs\n        bind()\n      }\n      console.error('[studio] discovery update rejected:', cause instanceof Error ? cause.message : cause)\n    } finally {\n      running = false\n      if (pending) schedule()\n    }\n  }\n  const bind = () => {\n    for (const watcher of watchers) watcher.close()\n    watchers = []\n    const pages = new Map(\n      [...current.sources].flatMap((file) =>\n        ['tsx', 'ts', 'jsx', 'js'].map((ext) => {\n          const page = path.join(path.dirname(file), `page.${ext}`)\n          return [page, existsSync(page)] as const\n        }),\n      ),\n    )\n    const add = (directory: string, recursive: boolean, listener: (event: string, filename: string | null) => void) => {\n      if (!existsSync(directory)) return\n      const watcher = watch(directory, { recursive }, listener)\n      watcher.on('error', (cause) => console.error('[studio] discovery watcher:', cause.message))\n      watcher.unref()\n      watchers.push(watcher)\n    }\n    add(current.toolsDir, true, (event, filename) => {\n      if (!filename) return schedule()\n      const relative = filename.toString()\n      if (relative.split(path.sep).some((part) => part.startsWith('.') || part === 'node_modules')) return\n      const file = path.resolve(current.toolsDir, relative)\n      if (path.basename(file) === 'studio.tool.ts' || current.dependencies.has(file)) return schedule()\n      if (pages.has(file)) {\n        if (pages.get(file) !== existsSync(file)) schedule()\n        return\n      }\n      if (\n        event === 'rename' &&\n        (/^page\\.[jt]sx?$/.test(path.basename(file)) ||\n          !path.extname(file) ||\n          statSync(file, { throwIfNoEntry: false })?.isDirectory())\n      )\n        schedule()\n    })\n    const targets = new Set([\n      ...current.dependencies,\n      ...retryInputs,\n      ...['studio.config.ts', 'studio.config.mts', 'studio.config.js', 'studio.config.mjs', 'tsconfig.json'].map(\n        (file) => path.join(current.root, file),\n      ),\n    ])\n    const byDirectory = new Map<string, Set<string>>()\n    for (const file of targets) {\n      let directory = path.dirname(file)\n      // Watch the nearest existing parent until missing alias/relative-path directories appear.\n      while (!existsSync(directory) && path.dirname(directory) !== directory) directory = path.dirname(directory)\n      const names = byDirectory.get(directory) ?? new Set<string>()\n      names.add(path.relative(directory, file).split(path.sep)[0]!)\n      byDirectory.set(directory, names)\n    }\n    for (const [directory, names] of byDirectory) {\n      add(directory, false, (_, filename) => {\n        if (!filename || names.has(filename.toString())) schedule()\n      })\n    }\n    const directoryId = statSync(current.toolsDir, { throwIfNoEntry: false })?.ino\n    add(path.dirname(current.toolsDir), false, (_, filename) => {\n      if (\n        (!filename || filename.toString() === path.basename(current.toolsDir)) &&\n        statSync(current.toolsDir, { throwIfNoEntry: false })?.ino !== directoryId\n      )\n        schedule()\n    })\n  }\n  bind()\n  return {\n    retry: schedule,\n    close() {\n      closed = true\n      clearTimeout(timer)\n      for (const watcher of watchers) watcher.close()\n    },\n  }\n}\n","import { generate } from './discovery/generate'\nimport { watchDiscovery } from './discovery/watch'\n\nconst watchers = new Map<string, ReturnType<typeof watchDiscovery>>()\n\n/** Generate discovered tools before Next compiles, including a clean production build. */\nexport function withStudio<T extends object>(config: T | ((phase: string, context: any) => T | Promise<T>)) {\n  return async (phase: string, context: any): Promise<T> => {\n    const next = typeof config === 'function' ? await config(phase, context) : config\n    if (phase !== 'phase-production-server' && !process.env.STUDIO_DISCOVERY_MANAGED) {\n      const root = process.cwd()\n      const explicit = process.env.STUDIO_CONFIG\n      const discovery = await generate(root, explicit)\n      if (\n        discovery &&\n        phase === 'phase-development-server' &&\n        !process.env.STUDIO_DISCOVERY_MANAGED &&\n        !watchers.has(root)\n      ) {\n        watchers.set(\n          root,\n          watchDiscovery(discovery, () => generate(root, explicit)),\n        )\n      }\n    }\n    return next\n  }\n}\n"],"mappings":"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","names":["watchers"]}

package/dist/next.d.ts

@@ -0,0 +1,8 @@
+import { StudioOptions, Studio } from './client.js';
+import '@joycostudio/xyz/debug';
+import './protocol-DjrMADPm.js';
+
+/** Next.js replaces this public environment variable in browser bundles. */
+declare function createStudio(config: StudioOptions, options?: Pick<StudioOptions, 'runtime'>): Studio;
+
+export { createStudio };

package/dist/next.js

@@ -0,0 +1,15 @@
+import {
+  createStudio
+} from "./chunk-2RGQF5X5.js";
+import "./chunk-DEJYGBPJ.js";
+
+// src/next.ts
+function createStudio2(config, options = {}) {
+  return createStudio(config, {
+    runtime: options.runtime ?? config.runtime ?? (process.env.NODE_ENV === "development" && (process.env.NEXT_PUBLIC_STUDIO_RUNTIME || false))
+  });
+}
+export {
+  createStudio2 as createStudio
+};
+//# sourceMappingURL=next.js.map

package/dist/next.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/next.ts"],"sourcesContent":["import { createStudio as createClient, type StudioOptions } from './client/studio'\n\n/** Next.js replaces this public environment variable in browser bundles. */\nexport function createStudio(config: StudioOptions, options: Pick<StudioOptions, 'runtime'> = {}) {\n  return createClient(config, {\n    runtime:\n      options.runtime ??\n      config.runtime ??\n      (process.env.NODE_ENV === 'development' && (process.env.NEXT_PUBLIC_STUDIO_RUNTIME || false)),\n  })\n}\n"],"mappings":";;;;;;AAGO,SAASA,cAAa,QAAuB,UAA0C,CAAC,GAAG;AAChG,SAAO,aAAa,QAAQ;AAAA,IAC1B,SACE,QAAQ,WACR,OAAO,YACN,QAAQ,IAAI,aAAa,kBAAkB,QAAQ,IAAI,8BAA8B;AAAA,EAC1F,CAAC;AACH;","names":["createStudio"]}

package/dist/{protocol-BrHDtNkL.d.ts → protocol-DjrMADPm.d.ts}

@@ -19,18 +19,24 @@ declare const error: (code: string, message?: string) => Failure;
  * Lucide's core package (`import { Palette } from 'lucide'`) exports exactly this shape.
  */
 type ToolIcon = readonly (readonly [tag: string, attrs: Record<string, string | number | undefined>])[];
+type ToolBase = {
+    /** Unique, URL-safe identifier. */
+    id: string;
+    title?: string;
+    /** Shown next to the tool in /studio. Data, not a component, so contracts stay loadable in Node. */
+    icon?: ToolIcon;
+    /** App route that renders this tool's result, shown next to the controls in /studio. */
+    preview?: string;
+    /** Use a bare iframe for tools that already own their canvas layout and headers. */
+    previewLayout?: 'canvas' | 'custom';
+};
 /**
  * A tool's contract. Isomorphic on purpose: the runtime loads it in Node to
  * validate and persist, the app loads it in the browser to apply and debug.
  *
  * `TConfig` is the one type that is read, edited, applied, and persisted.
  */
-type ToolDefinition<TConfig extends object = object> = {
-    /** Unique, URL-safe identifier. */
-    id: string;
-    title?: string;
-    /** Shown next to the tool in /studio. Data, not a component, so contracts stay loadable in Node. */
-    icon?: ToolIcon;
+type ToolDefinition<TConfig extends object = object> = ToolBase & {
     /** Repo-relative JSON file the config persists to. Import that same file as `initial`. */
     file: string;
     /** Config used before the runtime answers (and in production). */
@@ -40,16 +46,60 @@ type ToolDefinition<TConfig extends object = object> = {
      * Doubles as the runtime validator: every control's bounds are enforced on write.
      */
     controls: (config: TConfig) => DebugSchema;
-    /** App route that renders this tool's result, shown next to the controls in /studio. */
-    preview?: string;
-    /** Use a bare iframe for tools that already own their canvas layout and headers. */
-    previewLayout?: 'canvas' | 'custom';
 };
+/** A tool with nothing to tune: a sidebar entry for its preview, without an inspector or config file. */
+type PreviewToolDefinition = ToolBase & {
+    preview: string;
+    file?: never;
+    initial?: never;
+    controls?: never;
+};
+/** A tool with a config. */
 type AnyTool = ToolDefinition<any>;
-type ConfigOf<TTool> = TTool extends ToolDefinition<infer TConfig> ? TConfig : never;
+/** Anything `defineTool` returns: the kind follows from whether it declares a config. */
+type StudioTool = AnyTool | PreviewToolDefinition;
+declare const hasConfig: (tool: StudioTool) => tool is AnyTool;
+/** Filled by .studio/types.generated.ts in each consuming project. */
+interface DiscoveredToolConfigs {
+}
+/** A discovered declaration is resolved into a full definition by the generated registry. */
+type DiscoveredToolDefinition<TConfig extends object = object> = ToolBase & {
+    /** JSON source relative to this tool file, or a tsconfig path alias. Defaults to ./config.json. */
+    config?: string;
+    controls: (config: TConfig) => DebugSchema;
+    file?: never;
+    initial?: never;
+};
+type ToolReference<TConfig extends object> = Pick<ToolDefinition<TConfig>, 'id' | 'controls'>;
+type ConfigOf<TTool> = TTool extends ToolReference<infer TConfig> ? TConfig : never;
+/** Discovered tools infer their config from the generated ID-to-JSON type map. */
+declare function defineTool<K extends keyof DiscoveredToolConfigs & string>(tool: Omit<DiscoveredToolDefinition<Extract<DiscoveredToolConfigs[K], object>>, 'id'> & {
+    id: K;
+}): DiscoveredToolDefinition<Extract<DiscoveredToolConfigs[K], object>>;
+/** Existing explicitly registered tools remain supported. */
 declare function defineTool<TConfig extends object>(tool: ToolDefinition<TConfig>): ToolDefinition<TConfig>;
+declare function defineTool(tool: PreviewToolDefinition): PreviewToolDefinition;
+/** A discovered preview-only tool may infer its preview from the adjacent page. */
+declare function defineTool(tool: ToolBase & {
+    controls?: never;
+    config?: never;
+    file?: never;
+    initial?: never;
+}): ToolBase;
 type StudioConfig = {
-    tools: readonly AnyTool[];
+    /** Explicit registry; omit to enable convention-based discovery. */
+    tools?: readonly StudioTool[];
+    /**
+     * Directory to scan and watch for `studio.tool.ts` files, relative to
+     * the project root.
+     *
+     * Defaults to the active Next.js app directory: `app/` or `src/app/`.
+     * Set a narrower directory to reduce scanning and discovery triggers.
+     * This does not change preview URLs.
+     *
+     * @example 'src/app/experiments'
+     */
+    toolsDir?: string;
     /** Runtime WebSocket and HTTP MCP port. Defaults to 5179. */
     port?: number;
     /** Browser origins allowed on the bridge and MCP endpoint. Defaults to localhost origins. */
@@ -58,7 +108,7 @@ type StudioConfig = {
     appUrl?: string;
 };
 declare const DEFAULT_PORT = 5179;
-declare function defineConfig(config: StudioConfig): StudioConfig;
+declare function defineConfig<T extends StudioConfig>(config: T): T;
 
 /** A tool's live state as owned by the runtime. */
 type ToolState<TConfig = unknown> = {
@@ -77,10 +127,11 @@ type ToolState<TConfig = unknown> = {
     /** The file changed on disk while the draft had unsaved edits. */
     conflict: boolean;
 };
+/** `file` is absent for preview-only tools, which have no config to read or edit. */
 type ToolSummary = {
     id: string;
     title: string;
-    file: string;
+    file?: string;
     icon?: ToolIcon;
     preview?: string;
 };
@@ -137,4 +188,4 @@ type ServerMessage = {
     state: ToolState;
 };
 
-export { type AnyTool as A, type ConfigOf as C, DEFAULT_PORT as D, type Failure as F, type Op as O, type Result as R, type ServerMessage as S, type ToolDefinition as T, type ToolState as a, type Operations as b, type Request as c, type StudioConfig as d, type Success as e, type ToolIcon as f, type ToolSummary as g, defineConfig as h, defineTool as i, error as j, success as s };
+export { type AnyTool as A, type ConfigOf as C, DEFAULT_PORT as D, type Failure as F, type Op as O, type PreviewToolDefinition as P, type Result as R, type ServerMessage as S, type ToolDefinition as T, type DiscoveredToolConfigs as a, type DiscoveredToolDefinition as b, type Operations as c, type Request as d, type StudioConfig as e, type StudioTool as f, type Success as g, type ToolIcon as h, type ToolReference as i, type ToolState as j, type ToolSummary as k, defineConfig as l, defineTool as m, error as n, hasConfig as o, success as s };

package/dist/react.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ComponentType, ComponentPropsWithRef, ReactNode, ComponentPropsWithoutRef, ComponentProps } from 'react';
 import { DebugSchema, DebugFolder } from '@joycostudio/xyz/debug';
-import { Select } from 'radix-ui';
+import { Select } from '@base-ui/react/select';
 
 type Success<T> = {
     ok: true;
@@ -20,18 +20,24 @@ type Result<T> = Success<T> | Failure;
  * Lucide's core package (`import { Palette } from 'lucide'`) exports exactly this shape.
  */
 type ToolIcon = readonly (readonly [tag: string, attrs: Record<string, string | number | undefined>])[];
+type ToolBase = {
+    /** Unique, URL-safe identifier. */
+    id: string;
+    title?: string;
+    /** Shown next to the tool in /studio. Data, not a component, so contracts stay loadable in Node. */
+    icon?: ToolIcon;
+    /** App route that renders this tool's result, shown next to the controls in /studio. */
+    preview?: string;
+    /** Use a bare iframe for tools that already own their canvas layout and headers. */
+    previewLayout?: 'canvas' | 'custom';
+};
 /**
  * A tool's contract. Isomorphic on purpose: the runtime loads it in Node to
  * validate and persist, the app loads it in the browser to apply and debug.
  *
  * `TConfig` is the one type that is read, edited, applied, and persisted.
  */
-type ToolDefinition<TConfig extends object = object> = {
-    /** Unique, URL-safe identifier. */
-    id: string;
-    title?: string;
-    /** Shown next to the tool in /studio. Data, not a component, so contracts stay loadable in Node. */
-    icon?: ToolIcon;
+type ToolDefinition<TConfig extends object = object> = ToolBase & {
     /** Repo-relative JSON file the config persists to. Import that same file as `initial`. */
     file: string;
     /** Config used before the runtime answers (and in production). */
@@ -41,11 +47,19 @@ type ToolDefinition<TConfig extends object = object> = {
      * Doubles as the runtime validator: every control's bounds are enforced on write.
      */
     controls: (config: TConfig) => DebugSchema;
-    /** App route that renders this tool's result, shown next to the controls in /studio. */
-    preview?: string;
-    /** Use a bare iframe for tools that already own their canvas layout and headers. */
-    previewLayout?: 'canvas' | 'custom';
 };
+/** A tool with nothing to tune: a sidebar entry for its preview, without an inspector or config file. */
+type PreviewToolDefinition = ToolBase & {
+    preview: string;
+    file?: never;
+    initial?: never;
+    controls?: never;
+};
+/** A tool with a config. */
+type AnyTool = ToolDefinition<any>;
+/** Anything `defineTool` returns: the kind follows from whether it declares a config. */
+type StudioTool = AnyTool | PreviewToolDefinition;
+type ToolReference<TConfig extends object> = Pick<ToolDefinition<TConfig>, 'id' | 'controls'>;
 
 /** A tool's live state as owned by the runtime. */
 type ToolState<TConfig = unknown> = {
@@ -117,8 +131,11 @@ type ToolHandle<TConfig extends object = any> = {
     discard(): Promise<Result<ToolState<TConfig>>>;
 };
 type Studio$1 = {
+    /** Every registered tool in order, including preview-only ones. */
+    readonly definitions: readonly StudioTool[];
+    /** A handle per tool with a config. Preview-only tools have none. */
     readonly tools: readonly ToolHandle[];
-    tool<TConfig extends object>(definition: ToolDefinition<TConfig>): ToolHandle<TConfig>;
+    tool<TConfig extends object>(definition: ToolReference<TConfig>): ToolHandle<TConfig>;
     readonly connection: Connection;
     /** Bumps on connection or any tool state change. */
     readonly version: number;
@@ -136,6 +153,11 @@ interface StudioProps {
 /** The /studio route: every registered tool, its preview, and its Tweakpane inspector. */
 declare function Studio({ studio, previewComponent, getConfigFileHref }: StudioProps): react.JSX.Element | null;
 
+/** Mount once in the host app for ?debug / Option+D controls. */
+declare function StudioDebug({ studio }: {
+    studio: Studio$1;
+}): null;
+
 type StudioCommandMenuProps = {
     studio: Studio$1;
     /** Path to the host's Studio route. Defaults to /studio. */
@@ -144,7 +166,7 @@ type StudioCommandMenuProps = {
     navigate?: (href: string) => void;
 };
 /** Mount once in the host layout, including /studio, to jump to any registered tool with ⌘/Ctrl+K. */
-declare function StudioCommandMenu({ studio, studioPath, navigate }: StudioCommandMenuProps): react.JSX.Element;
+declare function StudioCommandMenu(props: StudioCommandMenuProps): react.JSX.Element;
 
 /** Re-render on connection and tool state changes. */
 declare function useStudio(studio: Studio$1): Studio$1;
@@ -175,14 +197,15 @@ interface PreviewCanvasProps extends ComponentPropsWithoutRef<'iframe'> {
 /** Expands the same iframe in place. Native iframe props and the ref reach the iframe. */
 declare const PreviewCanvas: react.ForwardRefExoticComponent<PreviewCanvasProps & react.RefAttributes<HTMLIFrameElement>>;
 
-type StudioSelectProps = ComponentProps<typeof Select.Root> & {
+type StudioSelectProps = Omit<Select.Root.Props<string>, 'children'> & {
     label: string;
     title?: string;
     className?: string;
+    children?: ReactNode;
 };
-/** Compact Radix select shared by canvas and activity toolbars. */
+/** Compact select shared by canvas and activity toolbars. */
 declare function StudioSelect({ label, title, className, children, ...props }: StudioSelectProps): react.JSX.Element;
-declare function StudioSelectItem({ className, children, ...props }: ComponentProps<typeof Select.Item>): react.JSX.Element;
+declare function StudioSelectItem({ className, children, ...props }: Select.Item.Props): react.JSX.Element;
 
 /** Logical padding lets icon-bearing fields override only their leading inset. */
 declare const Input: react.ForwardRefExoticComponent<Omit<react.DetailedHTMLProps<react.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref"> & react.RefAttributes<HTMLInputElement>>;
@@ -196,4 +219,4 @@ declare function PanelHeader({ className, ...props }: ComponentProps<'header'>):
 declare const PanelContent: react.ForwardRefExoticComponent<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
 declare function PanelFooter({ className, ...props }: ComponentProps<'footer'>): react.JSX.Element;
 
-export { CanvasToolbar, type CanvasToolbarProps, PreviewCanvas, type PreviewCanvasProps, Studio, StudioCommandMenu, type StudioCommandMenuProps, Input as StudioInput, Panel as StudioPanel, PanelContent as StudioPanelContent, PanelFooter as StudioPanelFooter, PanelHeader as StudioPanelHeader, type StudioProps, StudioSelect, StudioSelectItem, type StudioSelectProps, StudioSurface, StudioToolbar, useStudio, useToolConfig };
+export { CanvasToolbar, type CanvasToolbarProps, PreviewCanvas, type PreviewCanvasProps, Studio, StudioCommandMenu, type StudioCommandMenuProps, StudioDebug, Input as StudioInput, Panel as StudioPanel, PanelContent as StudioPanelContent, PanelFooter as StudioPanelFooter, PanelHeader as StudioPanelHeader, type StudioProps, StudioSelect, StudioSelectItem, type StudioSelectProps, StudioSurface, StudioToolbar, useStudio, useToolConfig };