@joycostudio/studio 0.0.0-stage → 0.1.0

package/dist/protocol-BrHDtNkL.d.ts

@@ -0,0 +1,140 @@
+import { DebugSchema } from '@joycostudio/xyz/debug';
+
+type Success<T> = {
+    ok: true;
+    data: T;
+};
+type Failure = {
+    ok: false;
+    /** snake_case wire code, e.g. `invalid_config`. */
+    error: string;
+    message?: string;
+};
+type Result<T> = Success<T> | Failure;
+declare const success: <T>(data: T) => Success<T>;
+declare const error: (code: string, message?: string) => Failure;
+
+/**
+ * An SVG icon as data: `[tag, attributes]` children of a 24×24 stroke icon.
+ * Lucide's core package (`import { Palette } from 'lucide'`) exports exactly this shape.
+ */
+type ToolIcon = readonly (readonly [tag: string, attrs: Record<string, string | number | undefined>])[];
+/**
+ * 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;
+    /** 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). */
+    initial: TConfig;
+    /**
+     * What can be tweaked, as an Xyz/Tweakpane schema bound to `config`.
+     * 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';
+};
+type AnyTool = ToolDefinition<any>;
+type ConfigOf<TTool> = TTool extends ToolDefinition<infer TConfig> ? TConfig : never;
+declare function defineTool<TConfig extends object>(tool: ToolDefinition<TConfig>): ToolDefinition<TConfig>;
+type StudioConfig = {
+    tools: readonly AnyTool[];
+    /** Runtime WebSocket and HTTP MCP port. Defaults to 5179. */
+    port?: number;
+    /** Browser origins allowed on the bridge and MCP endpoint. Defaults to localhost origins. */
+    origins?: readonly string[];
+    /** Running app URL (e.g. http://localhost:3000), used for MCP preview captures. */
+    appUrl?: string;
+};
+declare const DEFAULT_PORT = 5179;
+declare function defineConfig(config: StudioConfig): StudioConfig;
+
+/** A tool's live state as owned by the runtime. */
+type ToolState<TConfig = unknown> = {
+    tool: string;
+    /** What is being edited. Bumps on every accepted update. */
+    draft: {
+        value: TConfig;
+        revision: number;
+    };
+    /** What is on disk. `hash` is null while the file does not exist yet. */
+    saved: {
+        value: TConfig;
+        hash: string | null;
+    };
+    dirty: boolean;
+    /** The file changed on disk while the draft had unsaved edits. */
+    conflict: boolean;
+};
+type ToolSummary = {
+    id: string;
+    title: string;
+    file: string;
+    icon?: ToolIcon;
+    preview?: string;
+};
+/** Every operation the runtime authorizes. The UI, the in-app debug pane, and MCP all go through these. */
+type Operations = {
+    'tools.list': {
+        params: {};
+        result: ToolSummary[];
+    };
+    'tool.get': {
+        params: {
+            tool: string;
+        };
+        result: ToolState;
+    };
+    /** Agents supply `revision` to avoid replacing a newer draft; browser controls can stream edits without it. */
+    'tool.update': {
+        params: {
+            tool: string;
+            value: unknown;
+            revision?: number;
+        };
+        result: ToolState;
+    };
+    /** `revision` is the draft revision being approved; a newer draft rejects the save. */
+    'tool.save': {
+        params: {
+            tool: string;
+            revision: number;
+            force?: boolean;
+        };
+        result: ToolState;
+    };
+    'tool.discard': {
+        params: {
+            tool: string;
+            revision?: number;
+        };
+        result: ToolState;
+    };
+};
+type Op = keyof Operations;
+type Request<TOp extends Op = Op> = {
+    id: number;
+    op: TOp;
+    params: Operations[TOp]['params'];
+};
+type ServerMessage = {
+    type: 'response';
+    id: number;
+    result: Result<unknown>;
+} | {
+    type: 'state';
+    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 };

package/dist/react.d.ts

@@ -0,0 +1,184 @@
+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';
+
+type Success<T> = {
+    ok: true;
+    data: T;
+};
+type Failure = {
+    ok: false;
+    /** snake_case wire code, e.g. `invalid_config`. */
+    error: string;
+    message?: string;
+};
+type Result<T> = Success<T> | Failure;
+
+/**
+ * An SVG icon as data: `[tag, attributes]` children of a 24×24 stroke icon.
+ * Lucide's core package (`import { Palette } from 'lucide'`) exports exactly this shape.
+ */
+type ToolIcon = readonly (readonly [tag: string, attrs: Record<string, string | number | undefined>])[];
+/**
+ * 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;
+    /** 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). */
+    initial: TConfig;
+    /**
+     * What can be tweaked, as an Xyz/Tweakpane schema bound to `config`.
+     * 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's live state as owned by the runtime. */
+type ToolState<TConfig = unknown> = {
+    tool: string;
+    /** What is being edited. Bumps on every accepted update. */
+    draft: {
+        value: TConfig;
+        revision: number;
+    };
+    /** What is on disk. `hash` is null while the file does not exist yet. */
+    saved: {
+        value: TConfig;
+        hash: string | null;
+    };
+    dirty: boolean;
+    /** The file changed on disk while the draft had unsaved edits. */
+    conflict: boolean;
+};
+
+type Connection = {
+    phase: 'local';
+} | {
+    phase: 'connecting';
+} | {
+    phase: 'connected';
+} | {
+    phase: 'offline';
+};
+
+type ToolHandle<TConfig extends object = any> = {
+    readonly definition: ToolDefinition<TConfig>;
+    /** The live config. Read it to apply; writes (from any pane, or your code) sync to the runtime. */
+    readonly config: TConfig;
+    /** Runtime-owned state; null until the runtime answers (always null without one). */
+    readonly state: ToolState<TConfig> | null;
+    /** Bumps on every config change. Handy as a React snapshot. */
+    readonly version: number;
+    /** Called after every config change, local or remote. */
+    subscribe(listener: (config: TConfig) => void): () => void;
+    /** The tool's Xyz schema bound to the live config. */
+    controls(): DebugSchema;
+    /** Xyz `Debuggable`: `debugManager.register(handle)` mounts this tool in the app's floating pane. */
+    debug(): DebugFolder;
+    /** True while `compare(true)` shows the saved config in place of the draft. */
+    readonly comparing: boolean;
+    /**
+     * Temporarily show the saved config (true) or go back to the draft (false). Local only: nothing
+     * reaches the runtime, and edits made while comparing are dropped when it ends.
+     */
+    compare(showSaved: boolean): void;
+    save(options?: {
+        force?: boolean;
+    }): Promise<Result<ToolState<TConfig>>>;
+    discard(): Promise<Result<ToolState<TConfig>>>;
+};
+type Studio$1 = {
+    readonly tools: readonly ToolHandle[];
+    tool<TConfig extends object>(definition: ToolDefinition<TConfig>): ToolHandle<TConfig>;
+    readonly connection: Connection;
+    /** Bumps on connection or any tool state change. */
+    readonly version: number;
+    subscribe(listener: () => void): () => void;
+    close(): void;
+};
+
+interface StudioProps {
+    studio: Studio$1;
+    /** Forward the iframe ref and native props to preserve Studio shortcuts and compare. */
+    previewComponent?: ComponentType<ComponentPropsWithRef<'iframe'>> | 'iframe';
+    /** Resolve config paths using the host's editor URL or source browser. */
+    getConfigFileHref?: (file: string) => string;
+}
+/** The /studio route: every registered tool, its preview, and its Tweakpane inspector. */
+declare function Studio({ studio, previewComponent, getConfigFileHref }: StudioProps): react.JSX.Element | null;
+
+type StudioCommandMenuProps = {
+    studio: Studio$1;
+    /** Path to the host's Studio route. Defaults to /studio. */
+    studioPath?: string;
+    /** Optional host router navigation (for example, Next.js router.push). */
+    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;
+
+/** Re-render on connection and tool state changes. */
+declare function useStudio(studio: Studio$1): Studio$1;
+/** The tool's live config; re-renders on every change, local or remote. */
+declare function useToolConfig<TConfig extends object>(handle: ToolHandle<TConfig>): TConfig;
+
+/** The inset card surface shared by canvas headers, toolbars, and detail panels. */
+declare const StudioSurface: react.ForwardRefExoticComponent<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
+    asChild?: boolean;
+} & react.RefAttributes<HTMLDivElement>>;
+declare const StudioToolbar: react.ForwardRefExoticComponent<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+
+interface CanvasToolbarProps {
+    label: string;
+    expanded?: boolean;
+    onToggle?: () => void;
+    children?: ReactNode;
+}
+/** Pinned by default; auto-hide preserves pointer, keyboard, open-menu, and touch access. */
+declare function CanvasToolbar({ label, expanded, onToggle, children }: CanvasToolbarProps): react.JSX.Element;
+
+interface PreviewCanvasProps extends ComponentPropsWithoutRef<'iframe'> {
+    expanded?: boolean;
+    onExpandedChange?: (expanded: boolean) => void;
+    onReload?: () => void;
+    toolbar?: ReactNode;
+}
+/** 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> & {
+    label: string;
+    title?: string;
+    className?: string;
+};
+/** Compact Radix 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;
+
+/** 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>>;
+
+/** Shared floating surface. Layout and visibility belong to the caller. */
+declare const Panel: react.ForwardRefExoticComponent<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
+    asChild?: boolean;
+} & react.RefAttributes<HTMLDivElement>>;
+/** Raised sections sit inside the panel's 4px padding with concentric corners. */
+declare function PanelHeader({ className, ...props }: ComponentProps<'header'>): react.JSX.Element;
+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 };