@joycostudio/studio 0.1.5 → 0.2.0

package/dist/client.d.ts

@@ -1,5 +1,13 @@
-import { DebugSchema, DebugFolder } from '@joycostudio/xyz/debug';
-import { f as StudioTool, T as ToolDefinition, j as ToolState, R as Result, i as ToolReference } from './protocol-DjrMADPm.js';
+import { DebugFolder, DebugHost } from '@joycostudio/xyz/debug';
+import { f as StudioTool, T as ToolDefinition, k as ToolState, h as ToolControls, R as Result, j as ToolReference } from './protocol-BviGBdSG.js';
+import { StudioUi } from './ui.js';
+import '@joycostudio/xyz/debug/dialkit';
+
+type Change = {
+    path: string[];
+    before: unknown;
+    after: unknown;
+};
 
 type Connection = {
     phase: 'local';
@@ -22,13 +30,15 @@ type ToolHandle<TConfig extends object = any> = {
     /** 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;
+    controls(): ToolControls;
     /** Xyz `Debuggable`: `debugManager.register(handle)` mounts this tool in the app's floating pane. */
-    debug(): DebugFolder;
+    debug(): DebugFolder<DebugHost>;
     /** The config on disk: the runtime's last reported saved value or, until one answers, the bundled `initial`. */
     readonly saved: TConfig;
     /** Dotted paths where the draft differs from `saved`. Tracked locally, so it works without a runtime too. */
     readonly changes: string[];
+    /** Each leaf where the draft differs from `saved`: `before` is the saved value, `after` the draft's. */
+    readonly diff: Change[];
     /** The draft differs from `saved`. */
     readonly dirty: boolean;
     /** True while `compare(true)` shows the saved config in place of the draft. */
@@ -56,6 +66,16 @@ type ToolHandle<TConfig extends object = any> = {
      * Undoable as its own step. Returns false when there is nothing to discard.
      */
     discard(): boolean;
+    /**
+     * Reset one changed leaf (a dotted path from `changes`, or its keys, which also address keys containing dots) to its saved value, then sync it like any
+     * other edit. Undoable as its own step. Returns false when that leaf is unchanged or while comparing.
+     */
+    revert(path: string | readonly string[]): boolean;
+    /**
+     * A link to `base` (the current page by default) carrying the draft. Opening it on another machine applies
+     * that draft as an unsaved, undoable edit; a draft that no longer fits the tool's controls is ignored.
+     */
+    shareUrl(base?: string | URL): string;
 };
 type Studio = {
     /** Every registered tool in order, including preview-only ones. */
@@ -64,6 +84,8 @@ type Studio = {
     readonly tools: readonly ToolHandle[];
     tool<TConfig extends object>(definition: ToolReference<TConfig>): ToolHandle<TConfig>;
     readonly connection: Connection;
+    /** The debug UI library tools' controls are drawn with. `<Studio>` and `<StudioDebug>` need one. */
+    readonly ui: StudioUi | undefined;
     /** Bumps on connection or any tool state change. */
     readonly version: number;
     subscribe(listener: () => void): () => void;
@@ -76,6 +98,12 @@ type StudioOptions = {
      * Only browsers connect, so a module-scope `createStudio` is safe to evaluate during SSR.
      */
     runtime?: string | false;
+    /**
+     * The debug UI library to draw controls with, from `@joycostudio/studio/ui`:
+     * `tweakpane(() => import('tweakpane'))` or `dialkit(() => import('dialkit/vanilla'))`.
+     * Required by `<Studio>` and `<StudioDebug>`; reading configs alone doesn't need one.
+     */
+    ui?: StudioUi;
 };
 /** Make the studio running in `target` (e.g. a preview iframe) compare `tool` as well. */
 declare function postCompare(target: Window | null | undefined, tool: string, showSaved: boolean): void;
@@ -83,4 +111,4 @@ declare function postCompare(target: Window | null | undefined, tool: string, sh
 declare function everyFrame(refresh: () => void): () => void;
 declare function createStudio(config: StudioOptions, options?: Pick<StudioOptions, 'runtime'>): Studio;
 
-export { type Connection, type Studio, type StudioOptions, type ToolHandle, createStudio, everyFrame, postCompare };
+export { type Change, type Connection, type Studio, type StudioOptions, StudioUi, type ToolHandle, createStudio, everyFrame, postCompare };

package/dist/client.js

@@ -2,8 +2,8 @@ import {
   createStudio,
   everyFrame,
   postCompare
-} from "./chunk-ZH3NEN4V.js";
-import "./chunk-DEJYGBPJ.js";
+} from "./chunk-ZPKMVZ67.js";
+import "./chunk-OEJWPWYJ.js";
 export {
   createStudio,
   everyFrame,

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { T as ToolDefinition, R as Result } from './protocol-DjrMADPm.js';
-export { A as AnyTool, C as ConfigOf, D as DEFAULT_PORT, a as DiscoveredToolConfigs, b as DiscoveredToolDefinition, F as Failure, O as Op, c as Operations, P as PreviewToolDefinition, d as Request, S as ServerMessage, e as StudioConfig, f as StudioTool, g as Success, h as ToolIcon, i as ToolReference, j as ToolState, k as ToolSummary, l as defineConfig, m as defineTool, n as error, o as hasConfig, s as success } from './protocol-DjrMADPm.js';
+import { T as ToolDefinition, R as Result } from './protocol-BviGBdSG.js';
+export { A as AnyTool, C as ConfigOf, D as DEFAULT_PORT, a as DiscoveredToolConfigs, b as DiscoveredToolDefinition, F as Failure, O as Op, c as Operations, P as PreviewToolDefinition, d as Request, S as ServerMessage, e as StudioConfig, f as StudioTool, g as Success, h as ToolControls, i as ToolIcon, j as ToolReference, k as ToolState, l as ToolSummary, m as defineConfig, n as defineTool, o as error, p as hasConfig, s as success } from './protocol-BviGBdSG.js';
 import '@joycostudio/xyz/debug';
 
 /**

package/dist/index.js

@@ -6,7 +6,7 @@ import {
   hasConfig,
   success,
   validateConfig
-} from "./chunk-DEJYGBPJ.js";
+} from "./chunk-OEJWPWYJ.js";
 export {
   DEFAULT_PORT,
   defineConfig,

package/dist/next.d.ts

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

package/dist/next.js

@@ -1,7 +1,7 @@
 import {
   createStudio
-} from "./chunk-ZH3NEN4V.js";
-import "./chunk-DEJYGBPJ.js";
+} from "./chunk-ZPKMVZ67.js";
+import "./chunk-OEJWPWYJ.js";
 
 // src/next.ts
 function createStudio2(config, options = {}) {

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

@@ -1,4 +1,4 @@
-import { DebugSchema } from '@joycostudio/xyz/debug';
+import { DebugSchema, DebugHost } from '@joycostudio/xyz/debug';
 
 type Success<T> = {
     ok: true;
@@ -14,6 +14,8 @@ type Result<T> = Success<T> | Failure;
 declare const success: <T>(data: T) => Success<T>;
 declare const error: (code: string, message?: string) => Failure;
 
+/** Controls as an Xyz schema. Drawn with whichever UI the app picks (`createStudio({ ui })`), so `extend` gets an unknown folder. */
+type ToolControls = DebugSchema<DebugHost>;
 /**
  * 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.
@@ -42,10 +44,10 @@ type ToolDefinition<TConfig extends object = object> = ToolBase & {
     /** Config used before the runtime answers (and in production). */
     initial: TConfig;
     /**
-     * What can be tweaked, as an Xyz/Tweakpane schema bound to `config`.
+     * What can be tweaked, as an Xyz schema bound to `config`.
      * Doubles as the runtime validator: every control's bounds are enforced on write.
      */
-    controls: (config: TConfig) => DebugSchema;
+    controls: (config: TConfig) => ToolControls;
 };
 /** A tool with nothing to tune: a sidebar entry for its preview, without an inspector or config file. */
 type PreviewToolDefinition = ToolBase & {
@@ -66,7 +68,7 @@ interface DiscoveredToolConfigs {
 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;
+    controls: (config: TConfig) => ToolControls;
     file?: never;
     initial?: never;
 };
@@ -188,4 +190,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 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 };
+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 ToolControls as h, type ToolIcon as i, type ToolReference as j, type ToolState as k, type ToolSummary as l, defineConfig as m, defineTool as n, error as o, hasConfig as p, success as s };

package/dist/react.d.ts

@@ -1,8 +1,14 @@
 import * as react from 'react';
 import { ComponentType, ComponentPropsWithRef, ReactNode, ComponentPropsWithoutRef, ComponentProps } from 'react';
-import { DebugSchema, DebugFolder } from '@joycostudio/xyz/debug';
+import { DebugSchema, DebugHost, DebugAdapter, DebugFolder } from '@joycostudio/xyz/debug';
 import { Select } from '@base-ui/react/select';
 
+type Change = {
+    path: string[];
+    before: unknown;
+    after: unknown;
+};
+
 type Success<T> = {
     ok: true;
     data: T;
@@ -15,6 +21,8 @@ type Failure = {
 };
 type Result<T> = Success<T> | Failure;
 
+/** Controls as an Xyz schema. Drawn with whichever UI the app picks (`createStudio({ ui })`), so `extend` gets an unknown folder. */
+type ToolControls = DebugSchema<DebugHost>;
 /**
  * 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.
@@ -43,10 +51,10 @@ type ToolDefinition<TConfig extends object = object> = ToolBase & {
     /** Config used before the runtime answers (and in production). */
     initial: TConfig;
     /**
-     * What can be tweaked, as an Xyz/Tweakpane schema bound to `config`.
+     * What can be tweaked, as an Xyz schema bound to `config`.
      * Doubles as the runtime validator: every control's bounds are enforced on write.
      */
-    controls: (config: TConfig) => DebugSchema;
+    controls: (config: TConfig) => ToolControls;
 };
 /** A tool with nothing to tune: a sidebar entry for its preview, without an inspector or config file. */
 type PreviewToolDefinition = ToolBase & {
@@ -79,6 +87,25 @@ type ToolState<TConfig = unknown> = {
     conflict: boolean;
 };
 
+/**
+ * The debug UI library Studio draws tool controls with: Tweakpane or DialKit. Pick one with
+ * `createStudio({ ui })`; the library loads lazily through `load`, from the host app, so only
+ * the one you pick needs to be installed.
+ */
+type StudioUi = {
+    readonly kind: string;
+    /** The floating pane `StudioDebug` opens on `?debug` / Option+D. */
+    floating: DebugAdapter;
+    /** Controls drawn inside `container`, as the /studio inspector does. */
+    inline(container: HTMLElement, options: {
+        title: string;
+    }): Promise<DebugHost & {
+        dispose(): void;
+    }>;
+    /** Copy the library's page styles into Studio's shadow root, which page stylesheets don't reach. */
+    adoptStyles(root: ShadowRoot): void | Promise<void>;
+};
+
 type Connection = {
     phase: 'local';
 } | {
@@ -100,13 +127,15 @@ type ToolHandle<TConfig extends object = any> = {
     /** 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;
+    controls(): ToolControls;
     /** Xyz `Debuggable`: `debugManager.register(handle)` mounts this tool in the app's floating pane. */
-    debug(): DebugFolder;
+    debug(): DebugFolder<DebugHost>;
     /** The config on disk: the runtime's last reported saved value or, until one answers, the bundled `initial`. */
     readonly saved: TConfig;
     /** Dotted paths where the draft differs from `saved`. Tracked locally, so it works without a runtime too. */
     readonly changes: string[];
+    /** Each leaf where the draft differs from `saved`: `before` is the saved value, `after` the draft's. */
+    readonly diff: Change[];
     /** The draft differs from `saved`. */
     readonly dirty: boolean;
     /** True while `compare(true)` shows the saved config in place of the draft. */
@@ -134,6 +163,16 @@ type ToolHandle<TConfig extends object = any> = {
      * Undoable as its own step. Returns false when there is nothing to discard.
      */
     discard(): boolean;
+    /**
+     * Reset one changed leaf (a dotted path from `changes`, or its keys, which also address keys containing dots) to its saved value, then sync it like any
+     * other edit. Undoable as its own step. Returns false when that leaf is unchanged or while comparing.
+     */
+    revert(path: string | readonly string[]): boolean;
+    /**
+     * A link to `base` (the current page by default) carrying the draft. Opening it on another machine applies
+     * that draft as an unsaved, undoable edit; a draft that no longer fits the tool's controls is ignored.
+     */
+    shareUrl(base?: string | URL): string;
 };
 type Studio$1 = {
     /** Every registered tool in order, including preview-only ones. */
@@ -142,6 +181,8 @@ type Studio$1 = {
     readonly tools: readonly ToolHandle[];
     tool<TConfig extends object>(definition: ToolReference<TConfig>): ToolHandle<TConfig>;
     readonly connection: Connection;
+    /** The debug UI library tools' controls are drawn with. `<Studio>` and `<StudioDebug>` need one. */
+    readonly ui: StudioUi | undefined;
     /** Bumps on connection or any tool state change. */
     readonly version: number;
     subscribe(listener: () => void): () => void;