@vscode/component-explorer 0.2.1-18 → 0.2.1-180

package/dist/core/inputAggregation.d.ts

@@ -0,0 +1,31 @@
+import { IJsonSchema } from './fixtureApi.js';
+/**
+ * A single input property shared by one or more of the currently rendered fixtures.
+ * Properties are grouped by name **and** structural schema equality, so a control can edit
+ * every fixture that declares the same property at once.
+ */
+export interface AggregatedInputProperty {
+    readonly name: string;
+    readonly schema: IJsonSchema;
+    /** Ids of the fixtures that declare this exact property (same name + schema). */
+    readonly fixtureIds: readonly string[];
+}
+/** Minimal shape needed to aggregate: a fixture id and its (merged) input schema. */
+export interface ComponentInputInfo {
+    readonly id: string;
+    readonly inputSchema?: IJsonSchema;
+}
+/**
+ * Stable identity of an input property: its name plus structural schema. Two fixtures that
+ * declare the same property (same name + schema) share this key, so a chosen value can be
+ * persisted once and reused across every fixture that has it.
+ */
+export declare function inputPropertyKey(name: string, schema: IJsonSchema): string;
+/**
+ * Collects the input properties declared across the given fixtures, grouping identical
+ * (name + schema) properties so they can be edited together. Order follows first appearance.
+ */
+export declare function aggregateInputProperties(components: readonly ComponentInputInfo[]): AggregatedInputProperty[];
+/** The value currently in effect for a property: explicit override, else schema default. */
+export declare function effectiveInputValue(override: Record<string, unknown> | undefined, name: string, schema: IJsonSchema): unknown;
+//# sourceMappingURL=inputAggregation.d.ts.map

package/dist/core/inputAggregation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inputAggregation.d.ts","sourceRoot":"","sources":["../../src/core/inputAggregation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,iFAAiF;IACjF,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;CACtC;AAgBD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,MAAM,CAE1E;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACpC,UAAU,EAAE,SAAS,kBAAkB,EAAE,GAC1C,uBAAuB,EAAE,CA0B3B;AAED,4FAA4F;AAC5F,wBAAgB,mBAAmB,CAC/B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC7C,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,WAAW,GACpB,OAAO,CAKT"}

package/dist/daemon/DaemonConfig.d.ts

@@ -5,8 +5,6 @@
 export interface DaemonConfig {
     /** Name of the session this explorer instance belongs to (e.g. 'current' or 'baseline') */
     readonly sessionName: string;
-    /** Daemon API version served by the daemon process. */
-    readonly daemonApiVersion: string;
     /** Runtime version required by the vite plugin for the explorer bundle it serves. */
     readonly runtimeVersionNeededByPlugin: string;
 }

package/dist/daemon/DaemonConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DaemonConfig.d.ts","sourceRoot":"","sources":["../../src/daemon/DaemonConfig.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC5B,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,qFAAqF;IACrF,QAAQ,CAAC,4BAA4B,EAAE,MAAM,CAAC;CAC9C"}
+{"version":3,"file":"DaemonConfig.d.ts","sourceRoot":"","sources":["../../src/daemon/DaemonConfig.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC5B,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qFAAqF;IACrF,QAAQ,CAAC,4BAA4B,EAAE,MAAM,CAAC;CAC9C"}

package/dist/daemon/DaemonModel.d.ts

@@ -1,12 +1,12 @@
 import { IObservable } from '@vscode/observables';
-import { DaemonApiType } from '@vscode/component-explorer-cli/daemon-types';
+import { DaemonMethods } from '@vscode/component-explorer-common/daemon-rpc';
 import { DaemonConfig } from './DaemonConfig.js';
 /** Screenshot result from the daemon */
-export type DaemonScreenshotResult = DaemonApiType['screenshots']['take']['TResult'];
+export type DaemonScreenshotResult = Awaited<ReturnType<DaemonMethods['screenshots']['take']>>;
 /** Comparison result from the daemon */
-export type DaemonCompareResult = DaemonApiType['screenshots']['compare']['TResult'];
+export type DaemonCompareResult = Awaited<ReturnType<DaemonMethods['screenshots']['compare']>>;
 /** Fixture info from the daemon */
-export type DaemonFixtureInfo = DaemonApiType['fixtures']['list']['TResult']['fixtures'][number];
+export type DaemonFixtureInfo = Awaited<ReturnType<DaemonMethods['fixtures']['list']>>['fixtures'][number];
 export interface DaemonSession {
     readonly name: string;
     readonly serverUrl: string;
@@ -21,8 +21,10 @@ export declare class DaemonModel {
     private readonly _sourceTreeIds;
     private readonly _sessions;
     private readonly _screenshotCache;
-    private readonly _client;
-    private _eventStreamAbort;
+    private _client;
+    private _stopEventStream;
+    private _reconnectTimer;
+    private _disposed;
     readonly sessionName: string;
     /** Observable map of sessionName → current sourceTreeId */
     readonly sourceTreeIds: IObservable<ReadonlyMap<string, string>>;
@@ -52,8 +54,12 @@ export declare class DaemonModel {
      */
     getSessionExplorerUrl(sessionName: string): string | undefined;
     dispose(): void;
+    private _requireClient;
+    private _connect;
     private _fetchSessionInfos;
     private _startEventStream;
+    private _onEventStreamEnded;
+    private _scheduleReconnect;
     private _handleEvent;
     private _validateProtocolVersions;
 }

package/dist/daemon/DaemonModel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DaemonModel.d.ts","sourceRoot":"","sources":["../../src/daemon/DaemonModel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGxE,OAAO,EACH,KAAK,aAAa,EAErB,MAAM,6CAA6C,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGtD,wCAAwC;AACxC,MAAM,MAAM,sBAAsB,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC;AAErF,wCAAwC;AACxC,MAAM,MAAM,mBAAmB,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC;AAErF,mCAAmC;AACnC,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjG,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,SAAS,GAAG,UAAU,CAAC;CAC5C;AAOD;;;GAGG;AACH,qBAAa,WAAW;IAeX,QAAQ,CAAC,MAAM,EAAE,YAAY;IAdzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiE;IAChG,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuD;IACjF,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAuC;IACxE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,iBAAiB,CAAgC;IAEzD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,2DAA2D;IAC3D,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAuB;IAEvF,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,SAAS,aAAa,EAAE,CAAC,CAAkB;gBAErD,MAAM,EAAE,YAAY;IAOzC;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC;;;OAGG;IACG,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAuB5F;;OAEG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAgBvH;;OAEG;IACG,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC;IAS9E;;OAEG;IACH,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAM9D,OAAO,IAAI,IAAI;YASD,kBAAkB;YAelB,iBAAiB;IAuB/B,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,yBAAyB;CAgBjC"}
+{"version":3,"file":"DaemonModel.d.ts","sourceRoot":"","sources":["../../src/daemon/DaemonModel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAExE,OAAO,EAEN,KAAK,aAAa,EAElB,MAAM,8CAA8C,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGtD,wCAAwC;AACxC,MAAM,MAAM,sBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AAE/F,wCAAwC;AACxC,MAAM,MAAM,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;AAE/F,mCAAmC;AACnC,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3G,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,SAAS,GAAG,UAAU,CAAC;CAC5C;AAOD;;;GAGG;AACH,qBAAa,WAAW;IAiBX,QAAQ,CAAC,MAAM,EAAE,YAAY;IAhBzC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiE;IAChG,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuD;IACjF,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAuC;IACxE,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,gBAAgB,CAA2B;IACnD,OAAO,CAAC,eAAe,CAA4C;IACnE,OAAO,CAAC,SAAS,CAAS;IAE1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,2DAA2D;IAC3D,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAuB;IAEvF,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,SAAS,aAAa,EAAE,CAAC,CAAkB;gBAErD,MAAM,EAAE,YAAY;IAIzC;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAKjC;;;OAGG;IACG,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAuB5F;;OAEG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAgBvH;;OAEG;IACG,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC;IAS9E;;OAEG;IACH,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAM9D,OAAO,IAAI,IAAI;IAaf,OAAO,CAAC,cAAc;YAKR,QAAQ;YAmBR,kBAAkB;IAgBhC,OAAO,CAAC,iBAAiB;IAkBzB,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,yBAAyB;CASjC"}

package/dist/daemon/browserDaemonClient.d.ts

@@ -0,0 +1,3 @@
+import { DaemonClient } from '@vscode/component-explorer-common/daemon-rpc';
+export declare function createBrowserDaemonClient(): Promise<DaemonClient>;
+//# sourceMappingURL=browserDaemonClient.d.ts.map

package/dist/daemon/browserDaemonClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browserDaemonClient.d.ts","sourceRoot":"","sources":["../../src/daemon/browserDaemonClient.ts"],"names":[],"mappings":"AACA,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,8CAA8C,CAAC;AAI1G,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,YAAY,CAAC,CAmCvE"}

package/dist/fixtureApi.d-DjVuiRlO.d.ts

@@ -0,0 +1,533 @@
+import { z } from 'zod';
+
+/**
+ * Disposable resource that can be cleaned up.
+ * `dispose` may be sync or async; the framework awaits the returned promise (if any)
+ * and captures any thrown errors.
+ */
+interface IDisposable {
+    dispose(): void | Promise<void>;
+}
+type DebugPanelPlacement = 'canvas-right' | 'bottom-panel';
+interface DebugPanelViewContext<TAction> {
+    sendAction(action: TAction): void;
+    viewState<T>(options: DebugPanelViewStateOptions<T>): DebugPanelViewState<T>;
+}
+interface DebugPanelViewStateOptions<T> {
+    readonly version: number;
+    readonly scope: 'pane' | 'fixture';
+    readonly schema: z.ZodType<T>;
+    readonly defaultValue: T;
+}
+interface DebugPanelViewState<T> {
+    get(): T;
+    set(value: T): void;
+    onChange(listener: (value: T) => void): IDisposable;
+}
+interface DebugPanelViewInstance<TState> extends IDisposable {
+    update(state: TState): void;
+}
+interface DefineDebugPanelOptions<TState, TAction> {
+    readonly id: string;
+    readonly title: string;
+    readonly placement?: DebugPanelPlacement;
+    render(container: HTMLElement, context: DebugPanelViewContext<TAction>): DebugPanelViewInstance<TState>;
+}
+interface ErasedDebugPanelViewInstance extends IDisposable {
+    update(state: unknown): void;
+}
+/**
+ * A statically declared custom panel. `TState` is published by the fixture and
+ * `TAction` is sent back by the panel UI.
+ */
+interface DebugPanelDefinition<TState = unknown, TAction = unknown> {
+    readonly id: string;
+    readonly title: string;
+    readonly placement?: DebugPanelPlacement;
+    /** @internal Viewer-side, type-erased renderer produced by defineDebugPanel. */
+    readonly _render: (container: HTMLElement, sendAction: (action: unknown) => void, viewState?: DebugPanelViewContext<unknown>['viewState']) => ErasedDebugPanelViewInstance;
+    /** @internal Carries types for inference without affecting the runtime shape. */
+    readonly _types?: {
+        readonly state: TState;
+        readonly action: TAction;
+    };
+}
+interface DebugPanelChannel<TState, TAction> {
+    publish(state: TState): void;
+    onAction(listener: (action: TAction) => void): IDisposable;
+}
+type DebugPanelActivation<TState, TAction> = (channel: DebugPanelChannel<TState, TAction>) => void | IDisposable;
+interface FixtureDebugApi {
+    connect<TState, TAction>(panel: DebugPanelDefinition<TState, TAction>, activate: DebugPanelActivation<TState, TAction>): IDisposable;
+}
+interface FixtureInputControlOptions {
+    readonly placement?: 'sidebar' | 'toolbar' | 'both';
+    readonly label?: string;
+    readonly title?: string;
+}
+/** Brand for an output that can be observed and edited while its Output panel is visible. */
+declare const interactiveOutputBrand: unique symbol;
+interface InteractiveOutput<T> {
+    readonly [interactiveOutputBrand]: true;
+    getSnapshot(): T;
+    activate(channel: DebugPanelChannel<T, T>): void | IDisposable;
+}
+/**
+ * Result of a render operation.
+ * Supports both sync and async rendering with cancellation.
+ * All fields are optional for simple use cases.
+ */
+interface RenderResult {
+    /**
+     * Resolves when the component is fully rendered and ready.
+     * For sync renders, this can be omitted (treated as immediately ready).
+     * Rejects if the render is aborted via the AbortSignal.
+     */
+    readonly ready?: Promise<void>;
+    /**
+     * Cleanup function. Called when the fixture is unmounted.
+     * May be sync or async; the framework awaits the returned promise (if any).
+     * Errors thrown (sync or async) are captured and surfaced via the
+     * `previousDispose` field of the next render report (or `currentDispose`
+     * if `disposeAfter` was requested).
+     * Can be omitted if no cleanup is needed.
+     */
+    dispose?(): void | Promise<void>;
+    /**
+     * Arbitrary data to include in the render report.
+     * Visible to the CLI and MCP tools (surfaced as `output`).
+     *
+     * Symmetric counterpart of `RenderContext.input`: input flows in, output flows out.
+     */
+    readonly output?: unknown;
+}
+/**
+ * What the render function can return.
+ * - undefined: no cleanup needed, immediately ready
+ * - RenderResult: object with optional ready/dispose
+ * - Promise<...>: async render that resolves to undefined or RenderResult
+ */
+type RenderReturn = RenderResult | undefined | void | Promise<RenderResult | undefined | void>;
+/**
+ * Context passed to the render function.
+ *
+ * @typeParam TInput - Shape of `input`, inferred from the fixture's zod `inputSchema`
+ *   (defaults to `unknown` when no schema is declared).
+ */
+interface RenderContext<TInput = unknown> {
+    /**
+     * Unique identifier of the fixture being rendered.
+     * Stable across renders of the same fixture; useful for keying caches,
+     * logging, or distinguishing between sibling fixtures sharing a render function.
+     */
+    readonly fixtureId: string;
+    /** AbortSignal for cancellation; check signal.aborted or listen to 'abort' event */
+    readonly signal: AbortSignal;
+    /** Register a disposable to be cleaned up when the fixture is unmounted. Returns the same disposable for chaining. */
+    addDisposable<T extends IDisposable>(disposable: T): T;
+    /**
+     * Observes one input property without remounting the fixture. The listener is
+     * invoked immediately and again for subsequent changes to this property.
+     * Input properties without a watcher retain the default remount behavior.
+     */
+    watchInput<TKey extends Extract<keyof TInput, string>>(key: TKey, listener: (value: TInput[TKey], input: TInput) => void): IDisposable;
+    /** Reports a component-originated change to a watched input, keeping sidebar controls synchronized without echoing it to the watcher. */
+    reportInput<TKey extends Extract<keyof TInput, string>>(key: TKey, value: TInput[TKey]): void;
+    /** Connects statically declared debug panels to this live fixture instance. */
+    readonly debug: FixtureDebugApi;
+    /**
+     * Describes where this fixture is being rendered. Use this to enable dev-only affordances
+     * (e.g. extra controls, logging) without affecting screenshots or embedded views.
+     */
+    readonly host: RenderHost;
+    /**
+     * Data passed in by the caller (CLI/MCP screenshot tool, explorer UI). Use this to
+     * parameterize the fixture: e.g. switch theme, vary props, select a scenario.
+     *
+     * When the fixture declares a zod `inputSchema`, this is typed as `z.infer<typeof schema>`
+     * and populated with the schema's defaults for any keys the caller omitted. Without a
+     * schema it is `unknown` (and `undefined` when no input was provided).
+     *
+     * Symmetric with `RenderResult.output` (which flows back out to the caller).
+     */
+    readonly input: TInput;
+}
+/**
+ * Describes the environment a fixture is rendered in.
+ */
+type RenderHost = 
+/** Rendered in the Component Explorer UI (visible to a human). */
+{
+    readonly kind: 'explorer-ui';
+    readonly interactive: true;
+}
+/** Headless render for CLI/MCP screenshots. */
+ | {
+    readonly kind: 'headless';
+    readonly interactive: false;
+}
+/** Rendered inside an isolation iframe (user-facing standalone view). */
+ | {
+    readonly kind: 'embedded';
+    readonly interactive: false;
+};
+/**
+ * Style definition for shadow DOM injection.
+ */
+type StyleDefinition = {
+    readonly type: 'css';
+    readonly content: string;
+} | {
+    readonly type: 'url';
+    readonly href: string;
+} | {
+    readonly type: 'adopted';
+    readonly sheet: CSSStyleSheet;
+};
+/**
+ * Display mode for a component.
+ */
+type DisplayMode = PageMode | ComponentMode;
+/**
+ * Page mode - component fills a viewport with device presets.
+ */
+interface PageMode {
+    readonly type: 'page';
+    readonly viewports: ViewportPreset[];
+}
+/**
+ * Component mode - renders at natural size.
+ */
+interface ComponentMode {
+    readonly type: 'component';
+}
+/**
+ * Viewport preset - either a named preset or custom dimensions.
+ */
+type ViewportPreset = ViewportPresetName | {
+    readonly name: string;
+    readonly width: number;
+    readonly height: number;
+};
+type ViewportPresetName = 'mobile' | 'tablet' | 'desktop';
+/**
+ * Minimal JSON Schema interface used to describe a fixture's expected `input` shape.
+ *
+ * This is the *derived* form: fixtures declare their input with a zod schema
+ * (`DefineFixtureOptions.inputSchema`) and the framework converts it to this JSON Schema
+ * at define time. Tools (CLI/MCP/explorer UI) read it for validation, autocompletion, or
+ * to generate input-editing controls.
+ *
+ * Intentionally a structural, recursive type covering the subset of JSON Schema we
+ * actually surface to tools — the index signature lets any additional standard JSON Schema
+ * keywords (`format`, `pattern`, `oneOf`, `$ref`, …) flow through without changing this interface.
+ */
+interface IJsonSchema {
+    readonly type?: 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
+    readonly properties?: {
+        readonly [key: string]: IJsonSchema;
+    };
+    readonly required?: readonly string[];
+    readonly items?: IJsonSchema;
+    readonly enum?: readonly unknown[];
+    readonly const?: unknown;
+    readonly default?: unknown;
+    readonly description?: string;
+    readonly title?: string;
+    readonly additionalProperties?: boolean | IJsonSchema;
+    readonly anyOf?: readonly IJsonSchema[];
+    readonly oneOf?: readonly IJsonSchema[];
+    readonly allOf?: readonly IJsonSchema[];
+    readonly [key: string]: unknown;
+}
+/** Brand symbol to identify single fixtures */
+declare const singleFixtureBrand: unique symbol;
+/** Brand symbol to identify fixture groups */
+declare const fixtureGroupBrand: unique symbol;
+/** Brand symbol to identify fixture variants */
+declare const fixtureVariantsBrand: unique symbol;
+/**
+ * Options for defining a single component fixture.
+ *
+ * @typeParam TInput - Shape of the fixture's `input`, inferred from `inputSchema`.
+ */
+interface DefineFixtureOptions<TInput = unknown> {
+    /**
+     * Path in the explorer tree.
+     * - `undefined` (default): use fixture filename only
+     * - `'Foo/Bar'`: exact path (fixture filename NOT appended)
+     * - `'Foo/Bar/'`: prefix (fixture filename IS appended → Foo/Bar/{filename})
+     *
+     * @throws Error if path contains empty segments (e.g., '/foo', 'foo//bar')
+     */
+    path?: string;
+    /** Optional description for documentation */
+    description?: string;
+    /** How to isolate: 'none' (default) renders in light DOM, 'shadow-dom' for CSS isolation, 'iframe' for full isolation */
+    isolation?: 'none' | 'shadow-dom' | 'iframe';
+    /** Display mode: defaults to { type: 'component' } */
+    displayMode?: DisplayMode;
+    /** Styles to inject (into document head for 'none', into shadow root for 'shadow-dom', into iframe head for 'iframe') */
+    styles?: StyleDefinition[];
+    /** Background pattern for the preview canvas: 'light' (default) or 'dark' for dark transparent pattern */
+    background?: 'light' | 'dark';
+    /** Labels for categorization and filtering (e.g. 'animation', 'blocks-ci') */
+    labels?: readonly string[];
+    /** Human/AI-readable description(s) of expected visual appearance. Inherited from parent group/variants and accumulated into a string[]. */
+    expectedVisualDescriptions?: string | readonly string[];
+    /**
+     * Zod schema describing the expected shape of `RenderContext.input`.
+     *
+     * Declaring it gives two things:
+     *  1. **Type safety** — `render`'s `context.input` is typed as `z.infer<typeof schema>`.
+     *  2. **Tooling** — the framework converts the schema to JSON Schema at define time so the
+     *     CLI/MCP/explorer UI can validate, autocomplete, or render input-editing controls.
+     *
+     * The schema must describe an object (`z.object({...})`) — `input` is always a JSON object
+     * (or `undefined`). Property-level `.default(...)` values are surfaced to tooling and used
+     * to populate omitted keys before `render` runs.
+     *
+     * @example
+     * ```ts
+     * inputSchema: z.object({
+     *   theme: z.enum(['light', 'dark']).default('light'),
+     *   count: z.number().int().default(1),
+     * })
+     * ```
+     */
+    inputSchema?: z.ZodType<TInput>;
+    /** Controls how selected input properties are presented in the Explorer UI. */
+    inputControls?: {
+        readonly [TKey in Extract<keyof TInput, string>]?: FixtureInputControlOptions;
+    };
+    /** Custom debug panels contributed by this fixture. */
+    debugPanels?: readonly DebugPanelDefinition<unknown, unknown>[];
+    /**
+     * Render the component into the container.
+     *
+     * @param container - The DOM element to render into
+     * @param context - Render context containing input and abort signal
+     * @returns Optional RenderResult, or a Promise that resolves to one
+     */
+    render: (container: HTMLElement, context: RenderContext<TInput>) => RenderReturn;
+}
+/** @deprecated Use DefineFixtureOptions instead */
+type DefineComponentOptions = DefineFixtureOptions;
+/**
+ * A single fixture export created by defineFixture().
+ */
+interface SingleFixtureExport {
+    readonly [singleFixtureBrand]: true;
+    readonly _options: DefineFixtureOptions;
+    readonly _path?: string;
+    /** JSON Schema derived from `_options.inputSchema` at define time (cross-version safe). */
+    readonly _inputSchemaJson?: IJsonSchema;
+}
+/**
+ * Group entry: either a single fixture, a nested group, or variants.
+ */
+type FixtureGroupEntry = SingleFixtureExport | FixtureGroupExport | FixtureVariantsExport;
+/**
+ * A fixture group export created by defineFixtureGroup().
+ */
+interface FixtureGroupExport {
+    readonly [fixtureGroupBrand]: true;
+    readonly _entries: {
+        [key: string]: FixtureGroupEntry;
+    };
+    readonly _path?: string;
+    readonly _labels?: readonly string[];
+    readonly _expectedVisualDescriptions?: string | readonly string[];
+    /** JSON Schema derived from the group's `inputSchema`; merged into every descendant fixture. */
+    readonly _inputSchemaJson?: IJsonSchema;
+}
+/**
+ * A fixture variants export created by defineFixtureVariants().
+ */
+interface FixtureVariantsExport {
+    readonly [fixtureVariantsBrand]: true;
+    readonly _variants: {
+        [key: string]: SingleFixtureExport;
+    };
+    readonly _path?: string;
+    readonly _labels?: readonly string[];
+    readonly _expectedVisualDescriptions?: string | readonly string[];
+    /** JSON Schema derived from the variants group's `inputSchema`; merged into every variant. */
+    readonly _inputSchemaJson?: IJsonSchema;
+}
+/**
+ * Fixture export type - a single fixture, a group, or variants.
+ */
+type FixtureExport = SingleFixtureExport | FixtureGroupExport | FixtureVariantsExport;
+/**
+ * Input for defineFixtureGroup.
+ */
+type FixtureGroupInput = {
+    [key: string]: FixtureGroupEntry;
+};
+/**
+ * Options for defineFixtureGroup with optional path.
+ */
+interface DefineFixtureGroupOptions {
+    /**
+     * Path in the explorer tree.
+     * - `undefined` (default): use fixture filename only
+     * - `'Foo/Bar'`: exact path (fixture filename NOT appended)
+     * - `'Foo/Bar/'`: prefix (fixture filename IS appended → Foo/Bar/{filename})
+     */
+    path?: string;
+    /** Labels for categorization and filtering (e.g. 'animation', 'blocks-ci') */
+    labels?: readonly string[];
+    /** Human/AI-readable description(s) of expected visual appearance. Inherited by nested fixtures. */
+    expectedVisualDescriptions?: string | readonly string[];
+    /**
+     * Zod schema describing `input` shared by every fixture in this group. It is converted to
+     * JSON Schema at define time and merged into each descendant fixture's own schema (the
+     * descendant's properties win on conflict). Use it to declare common input — e.g. a `theme`
+     * switch — once for a whole group instead of repeating it on each fixture.
+     */
+    inputSchema?: z.ZodType;
+}
+/**
+ * Input for defineFixtureVariants (only single fixtures, no nesting).
+ */
+type FixtureVariantsInput = {
+    [key: string]: SingleFixtureExport;
+};
+/**
+ * Options for defineFixtureVariants with optional path.
+ */
+interface DefineFixtureVariantsOptions {
+    /**
+     * Path in the explorer tree.
+     * - `undefined` (default): use fixture filename only
+     * - `'Foo/Bar'`: exact path (fixture filename NOT appended)
+     * - `'Foo/Bar/'`: prefix (fixture filename IS appended → Foo/Bar/{filename})
+     */
+    path?: string;
+    /** Labels for categorization and filtering (e.g. 'animation', 'blocks-ci') */
+    labels?: readonly string[];
+    /** Human/AI-readable description(s) of expected visual appearance. Inherited by nested fixtures. */
+    expectedVisualDescriptions?: string | readonly string[];
+    /**
+     * Zod schema describing `input` shared by every variant in this group. Converted to JSON
+     * Schema at define time and merged into each variant's own schema (the variant's properties
+     * win on conflict).
+     */
+    inputSchema?: z.ZodType;
+}
+/**
+ * Defines a single fixture.
+ *
+ * @example
+ * ```ts
+ * // Simple - no cleanup needed
+ * export default defineFixture({
+ *   render: (container) => {
+ *     container.innerHTML = `<button>Click me</button>`;
+ *   },
+ * });
+ *
+ * // Typed, parameterizable input via a zod schema
+ * export default defineFixture({
+ *   inputSchema: z.object({ label: z.string().default('Click me') }),
+ *   render: (container, { input }) => {
+ *     const root = createRoot(container);
+ *     root.render(<Button label={input.label} />);
+ *     return { dispose: () => root.unmount() };
+ *   },
+ * });
+ *
+ * // Async render
+ * export default defineFixture({
+ *   inputSchema: z.object({ url: z.string() }),
+ *   render: async (container, { input, signal }) => {
+ *     const data = await fetch(input.url, { signal });
+ *     container.innerHTML = await data.text();
+ *     return { dispose: () => { container.innerHTML = ''; } };
+ *   },
+ * });
+ * ```
+ */
+declare function defineFixture<TInput = unknown>(options: DefineFixtureOptions<TInput>): SingleFixtureExport;
+declare function defineDebugPanel<TState, TAction = never>(options: DefineDebugPanelOptions<TState, TAction>): DebugPanelDefinition<TState, TAction>;
+declare function interactiveOutput<T>(options: {
+    readonly getSnapshot: () => T;
+    readonly activate: DebugPanelActivation<T, T>;
+}): InteractiveOutput<T>;
+declare function isInteractiveOutput(value: unknown): value is InteractiveOutput<unknown>;
+/**
+ * Defines a group of fixtures with support for nesting.
+ *
+ * @example
+ * ```ts
+ * export default defineFixtureGroup({
+ *   Primary: defineFixture({
+ *     render: (container) => { ... },
+ *   }),
+ *   Variants: defineFixtureGroup({
+ *     Small: defineFixture({ ... }),
+ *     Large: defineFixture({ ... }),
+ *   }),
+ * });
+ * ```
+ */
+declare function defineFixtureGroup(entries: FixtureGroupInput): FixtureGroupExport;
+declare function defineFixtureGroup(options: DefineFixtureGroupOptions, entries: FixtureGroupInput): FixtureGroupExport;
+/**
+ * Defines a group of fixture variants (no nesting allowed).
+ * Variants are rendered horizontally by default and have a distinct icon in the tree.
+ *
+ * @example
+ * ```ts
+ * export default defineFixtureGroup({
+ *   Button: defineFixtureVariants({
+ *     Small: defineFixture({ ... }),
+ *     Medium: defineFixture({ ... }),
+ *     Large: defineFixture({ ... }),
+ *   }),
+ * });
+ * ```
+ */
+declare function defineFixtureVariants(variants: FixtureVariantsInput): FixtureVariantsExport;
+declare function defineFixtureVariants(options: DefineFixtureVariantsOptions, variants: FixtureVariantsInput): FixtureVariantsExport;
+/**
+ * Helper for synchronous renders.
+ * Executes the render function immediately and wraps the cleanup in a RenderResult.
+ *
+ * @param doRender - Function that renders synchronously and returns a cleanup function
+ * @returns A RenderResult with an already-resolved ready promise
+ *
+ * @example
+ * ```ts
+ * render: (container, { input }) => syncRender(() => {
+ *   const el = document.createElement('button');
+ *   el.textContent = input.label;
+ *   container.appendChild(el);
+ *   return () => el.remove();
+ * })
+ * ```
+ */
+declare function syncRender(doRender: () => (() => void) | IDisposable | void): RenderResult;
+/**
+ * Helper for asynchronous renders with cancellation support.
+ *
+ * @param signal - AbortSignal for cancellation
+ * @param doRender - Async function that renders and returns a cleanup function.
+ *                   Should check signal.aborted periodically for long operations.
+ * @returns A RenderResult whose ready promise rejects with AbortError if cancelled
+ *
+ * @example
+ * ```ts
+ * render: (container, { input, signal }) => asyncRender(signal, async () => {
+ *   const data = await fetchData(input.url, { signal });
+ *   if (signal.aborted) return;
+ *   container.innerHTML = data;
+ *   return () => { container.innerHTML = ''; };
+ * })
+ * ```
+ */
+declare function asyncRender(signal: AbortSignal, doRender: () => Promise<(() => void) | IDisposable | void>): RenderResult;
+
+export { defineFixture as A, defineFixtureGroup as B, defineFixtureVariants as E, fixtureGroupBrand as G, fixtureVariantsBrand as H, interactiveOutput as J, singleFixtureBrand as K, asyncRender as L, isInteractiveOutput as M, syncRender as N, defineDebugPanel as z };
+export type { ComponentMode as C, DebugPanelActivation as D, FixtureDebugApi as F, IDisposable as I, PageMode as P, RenderContext as R, SingleFixtureExport as S, ViewportPreset as V, DebugPanelChannel as a, DebugPanelDefinition as b, DebugPanelPlacement as c, DebugPanelViewContext as d, DebugPanelViewInstance as e, DebugPanelViewState as f, DebugPanelViewStateOptions as g, DefineComponentOptions as h, DefineDebugPanelOptions as i, DefineFixtureOptions as j, DisplayMode as k, FixtureExport as l, FixtureGroupEntry as m, FixtureGroupExport as n, FixtureGroupInput as o, FixtureInputControlOptions as p, FixtureVariantsExport as q, FixtureVariantsInput as r, IJsonSchema as s, InteractiveOutput as t, RenderHost as u, RenderResult as v, RenderReturn as w, StyleDefinition as x, ViewportPresetName as y };