@octane-xplat/workshop 0.1.0 → 0.15.0

package/src/windows/preflight.mjs

@@ -0,0 +1,113 @@
+/** Read-only Windows setup evidence. Prerequisites never qualify a host. */
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+
+function commandOutput(command, args) {
+	try {
+		return execFileSync(command, args, {
+			encoding: 'utf8',
+			timeout: 5000,
+			maxBuffer: 65536,
+			stdio: ['ignore', 'pipe', 'pipe'],
+			windowsHide: true,
+		}).trim()
+	} catch {
+		return null
+	}
+}
+
+export function windowsPreflight(root, { platform = process.platform, run = commandOutput } = {}) {
+	const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+	const require = createRequire(join(root, 'package.json'))
+	const installed = (name) => {
+		for (const specifier of [`${name}/package.json`, name]) {
+			try {
+				require.resolve(specifier)
+				return true
+			} catch {
+				/* Try the public entry. */
+			}
+		}
+
+		return false
+	}
+
+	const runtime =
+		manifest.devDependencies?.['@nativescript/windows'] ??
+		manifest.dependencies?.['@nativescript/windows']
+
+	const requirements = {
+		'Windows host': platform === 'win32',
+		'nativescript.config': ['ts', 'mts', 'js', 'mjs'].some((ext) =>
+			existsSync(join(root, `nativescript.config.${ext}`)),
+		),
+		'App_Resources/Windows/Package.appxmanifest': existsSync(
+			join(root, 'App_Resources/Windows/Package.appxmanifest'),
+		),
+		'@nativescript/windows exact version':
+			typeof runtime === 'string' && /^\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/.test(runtime),
+	}
+
+	for (const name of [
+		'@nativescript/windows',
+		'@nativescript/core',
+		'@nativescript-community/octane',
+		'@nativescript/vite',
+		'nativescript',
+		'vite',
+	]) {
+		requirements[name] = installed(name)
+	}
+
+	// Never run Windows commands on another host, boot a device, or change settings.
+	if (platform === 'win32') {
+		const sdk = run('dotnet', ['--version'])
+		requirements['.NET SDK >= 10'] =
+			typeof sdk === 'string' && /^\d+\.\d+\.\d+/.test(sdk) && Number(sdk.split('.')[0]) >= 10
+
+		const devMode = run('powershell', [
+			'-NoProfile',
+			'-NonInteractive',
+			'-Command',
+			'(Get-ItemProperty "HKLM:\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\AppModelUnlock" -Name AllowDevelopmentWithoutDevLicense -ErrorAction SilentlyContinue).AllowDevelopmentWithoutDevLicense',
+		])
+
+		requirements['Developer Mode (development launch)'] = devMode?.trim() === '1'
+	}
+
+	return {
+		backend: 'experimental nativescript/winui',
+		executionHost: { required: 'win32', current: platform, reachable: platform === 'win32' },
+		qualification: 'unverified',
+		requirements,
+		status:
+			platform !== 'win32'
+				? 'remote-host-required'
+				: Object.values(requirements).every(Boolean)
+					? 'unqualified-backend'
+					: 'missing-prerequisites',
+		note:
+			'Windows workshop mounting, shell and reload are not implemented or host-qualified. ' +
+			(platform !== 'win32'
+				? 'Run these commands in a Windows checkout; SDK and Developer Mode checks were not run. '
+				: '') +
+			'Prerequisites do not prove renderer compatibility, input, accessibility or lifecycle support. No web fallback is used.',
+	}
+}
+
+export function windowsLaunchBlocker(report) {
+	if (report.status === 'remote-host-required') {
+		return 'Windows workshop requires a real Windows host. Run `xplat workshop doctor` in that host’s checkout. No web fallback is used.'
+	}
+
+	const missing = Object.entries(report.requirements)
+		.filter(([, ok]) => !ok)
+		.map(([name]) => name)
+
+	return (
+		(missing.length ? `Windows prerequisites missing: ${missing.join(', ')}. ` : '') +
+		'Windows workshop mounting, shell and reload remain unimplemented and unqualified; launch is blocked. Run `xplat workshop doctor` for setup evidence.'
+	)
+}

package/types/generated/.tsrx-typegen-manifest.json

@@ -0,0 +1,24 @@
+{
+  "version": 1,
+  "files": [
+    "catalog.d.ts",
+    "contract.d.ts",
+    "controls.d.ts",
+    "errors.d.ts",
+    "fixture.d.ts",
+    "index.d.ts",
+    "macos/controller.d.ts",
+    "macos/index.macos.d.ts",
+    "macos/stage.macos.d.ts",
+    "mobile/controller.d.ts",
+    "mobile/entry.mobile.d.ts",
+    "mobile/index.mobile.d.ts",
+    "mobile/mount.mobile.d.ts",
+    "mobile/tree.mobile.d.ts",
+    "session.d.ts",
+    "web/entry.web.d.ts",
+    "web/index.web.d.ts",
+    "web/mount.web.d.ts",
+    "web/shell.web.d.ts"
+  ]
+}

package/types/generated/catalog.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Catalog model shared by Node-side discovery, the catalog virtual module,
+ * and the shell. Metadata is literal and statically readable — discovery
+ * never evaluates story modules.
+ */
+import type { WorkshopTarget } from './contract.js';
+export interface StoryMeta {
+    id: string;
+    title: string;
+    /** Effective targets after declared targets ∩ file-suffix applicability. */
+    targets: readonly WorkshopTarget[];
+    capabilities: readonly string[];
+    /** Absolute file path of the story module. */
+    file: string;
+    /** Export binding the definition is attached to. */
+    exportName: string;
+    /** Whether this story can mount on the current build target. */
+    applicable: boolean;
+    /** Why the story cannot mount here (unsupported-by-story / leaf mismatch). */
+    reason?: string;
+}
+export interface CatalogEntry extends StoryMeta {
+    /** Present only when applicable: loads the story definition. */
+    load?: (stamp?: string | number) => Promise<unknown>;
+}
+/** Platform suffix on a story file narrows applicability to those targets. */
+export declare const SUFFIX_TARGETS: Record<string, readonly WorkshopTarget[]>;
+export declare const PLATFORM_SUFFIX_RE: RegExp;
+export declare function storyFileTag(file: string): string | null;
+export declare function applicableTargets(declared: readonly WorkshopTarget[], file: string): readonly WorkshopTarget[];

package/types/generated/contract.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @octane-xplat/workshop — typed authoring contract.
+ *
+ * One `defineStory` declaration describes an isolated development run of an
+ * Octane component: stable identity, target applicability, default args,
+ * explicit controls, fresh state, a cancellable async fixture, and ordered
+ * provider wrappers. The story file compiles under the consumer's normal
+ * renderer rules; this module carries no renderer or host globals itself.
+ */
+import type { Store } from '@octane-xplat/ui/data';
+/** The six product targets. Only `web` is qualified by the current release. */
+export type WorkshopTarget = 'web' | 'ios' | 'android' | 'macos' | 'windows' | 'linux';
+export declare const WORKSHOP_TARGETS: readonly WorkshopTarget[];
+/** Version of the authoring contract — bumped on breaking changes. */
+export declare const WORKSHOP_CONTRACT_VERSION = 1;
+export type StoryTargets = 'all' | readonly WorkshopTarget[];
+/**
+ * Portable cancellation contract for fixture work. The host adapter supplies
+ * an implementation with equivalent observable semantics — do not rely on
+ * `AbortController`/`signal.throwIfAborted` being the underlying mechanism.
+ */
+export interface CancellationSignal {
+    readonly aborted: boolean;
+    addEventListener(type: 'abort', listener: () => void): void;
+    removeEventListener(type: 'abort', listener: () => void): void;
+}
+export type StoryCleanup = () => void | Promise<void>;
+/** Context handed to the fixture factory for each story generation. */
+export interface FixtureContext {
+    /** The real target this run mounts on. */
+    readonly target: WorkshopTarget;
+    /** Capabilities declared by the story. */
+    readonly capabilities: readonly string[];
+    /** Observable cancellation; aborted when the generation retires. */
+    readonly signal: CancellationSignal;
+    /**
+     * Register an owned resource for disposal. Disposal runs exactly once —
+     * including for resources registered after cancellation, which are
+     * released as soon as the fixture settles.
+     */
+    onCleanup(cleanup: StoryCleanup): void;
+}
+export type FixtureFactory<F> = (context: FixtureContext) => F | Promise<F>;
+/** A compiler-produced Octane component. Kept opaque to transport/tooling. */
+export type StoryComponent<P> = (props: P) => unknown;
+/**
+ * An ordered provider wrapper. Consumer presets wrap story providers;
+ * each receives the typed fixture result and `children`.
+ */
+export type StoryProvider<F> = (props: {
+    fixture: F;
+    children?: unknown;
+}) => unknown;
+export interface BooleanControl {
+    type: 'boolean';
+}
+export interface StringControl {
+    type: 'string';
+    placeholder?: string;
+}
+export interface NumberControl {
+    type: 'number';
+    min?: number;
+    max?: number;
+    step?: number;
+}
+export interface EnumControl<T> {
+    type: 'enum';
+    options: readonly T[];
+}
+type ControlValue<T> = 0 extends 1 & T ? BooleanControl | NumberControl | StringControl | EnumControl<T> : [T] extends [boolean] ? BooleanControl : [T] extends [number] ? NumberControl | EnumControl<T> : [T] extends [string] ? StringControl | EnumControl<T> : never;
+/**
+ * Controls may be declared only for explicitly declared, portable-valued
+ * props. `allowUnset` is legal only on optional props — Unset removes the
+ * key from the next props bag rather than merging a stale value.
+ */
+export type StoryControl<T, Optional extends boolean> = ControlValue<T> & (Optional extends true ? {
+    allowUnset?: boolean;
+} : {
+    allowUnset?: false;
+});
+export type StoryControls<P> = {
+    [K in keyof P]?: StoryControl<NonNullable<P[K]>, undefined extends P[K] ? true : false>;
+};
+/** Props the runner injects beyond `args`: fresh state store + fixture. */
+export type InjectedStoryProps<S, F> = (S extends void ? unknown : {
+    state: Store<S>;
+}) & (F extends void ? unknown : {
+    fixture: F;
+});
+type ReservedStoryKeys = 'state' | 'fixture';
+/** Reserved injected prop names cannot collide with declared props. */
+type PropsWithoutReserved<P> = Extract<keyof P, ReservedStoryKeys> extends never ? P : never;
+/**
+ * A complete story declaration. `id`, `title`, `targets`, and `capabilities`
+ * must be literal values — discovery reads them statically without
+ * evaluating the module.
+ */
+export type StoryDefinition<P = Record<string, never>, S = void, F = void> = {
+    /** Stable, unique story id — e.g. 'account/profile-card'. */
+    id: string;
+    /** Display title; '/' segments group the catalog. */
+    title: string;
+    /** Targets this story can mount on; 'all' covers the six product targets. */
+    targets: StoryTargets;
+    /** Host capabilities the story requires (e.g. 'camera', 'network-write'). */
+    capabilities?: readonly string[];
+    /** The component under development. */
+    component: StoryComponent<PropsWithoutReserved<P> & InjectedStoryProps<S, F>>;
+    /** Immutable default props for each run; cloned fresh per generation. */
+    args: PropsWithoutReserved<P>;
+    /** Explicit editable inputs for declared props. */
+    controls?: StoryControls<P>;
+    /** Fixture preparation budget in milliseconds; defaults to 10 000. */
+    fixtureTimeout?: number;
+    /** Ordered wrappers applied around the component for each generation. */
+    providers?: readonly StoryProvider<F extends void ? undefined : F>[];
+} & (S extends void ? {
+    state?: never;
+} : {
+    state: () => S;
+}) & (F extends void ? {
+    fixture?: never;
+} : {
+    fixture: FixtureFactory<F>;
+});
+/** Declare a story. Validates cheap authoring rules eagerly. */
+export declare function defineStory<P = Record<string, never>, S = void, F = void>(definition: StoryDefinition<P, S, F>): StoryDefinition<P, S, F>;
+/** Consumer workshop configuration, loaded by the dev tooling. */
+export interface WorkshopConfig {
+    stories?: {
+        /** Glob(s) matching story modules. Default: '**&#47;*.stories.{ts,tsx,tsrx}' plus platform-suffixed leaves. */
+        include?: string | readonly string[];
+        exclude?: string | readonly string[];
+    };
+    /**
+     * Module specifiers (relative to the config file) whose `providers` or
+     * `default` export is an array of provider components wrapping every story.
+     */
+    providerModules?: readonly string[];
+    /** Extra static asset roots served under /@workshop-assets/<name>/. */
+    assets?: Record<string, string>;
+}
+export declare function defineWorkshopConfig(config: WorkshopConfig): WorkshopConfig;
+export {};

package/types/generated/controls.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Control application helpers — host-agnostic. The next props bag is always
+ * complete: Unset removes the key entirely; removed keys reach the renderer
+ * as explicit `undefined` so nothing stale merges forward.
+ */
+import type { StoryDefinition } from './contract.js';
+export declare const UNSET: unique symbol;
+export type ControlValueInput = boolean | string | number | typeof UNSET;
+export interface FieldError {
+    message: string;
+}
+export declare function isUnsettable(definition: StoryDefinition<any, any, any>, key: string): boolean;
+/** Clone default args per generation — nested data must not leak across runs. */
+export declare function freshArgs(args: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Validate and fold a control input into the next props bag. Returns either
+ * the next complete bag or a per-field error; invalid input never mutates.
+ */
+export declare function applyControlInput(definition: StoryDefinition<any, any, any>, currentProps: Record<string, unknown>, key: string, raw: string | boolean | number | typeof UNSET): {
+    props?: Record<string, unknown>;
+    error?: FieldError;
+};
+/**
+ * Produce the props object handed to the renderer: next bag plus explicit
+ * `undefined` for every key present before and absent now — removal is
+ * visible to hosts that reconcile keys rather than whole objects.
+ */
+export declare function reconcileProps(previous: Record<string, unknown>, next: Record<string, unknown>): Record<string, unknown>;

package/types/generated/errors.d.ts

@@ -0,0 +1,13 @@
+/** Failure phases surfaced by the workshop shell and CLI. */
+export type WorkshopErrorPhase = 'discovery' | 'compile' | 'fixture' | 'mount' | 'interaction' | 'cleanup' | 'launch' | 'connection';
+export declare class WorkshopError extends Error {
+    readonly phase: WorkshopErrorPhase;
+    readonly storyId?: string;
+    readonly sourceLocation?: string;
+    constructor(phase: WorkshopErrorPhase, message: string, options?: {
+        storyId?: string;
+        cause?: unknown;
+        sourceLocation?: string;
+    });
+}
+export declare function describeCause(cause: unknown): string;

package/types/generated/fixture.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Owned-resource and cancellation machinery for one story generation.
+ * Host-agnostic: no DOM globals, no AbortController — the portable
+ * CancellationSignal contract only.
+ */
+import type { CancellationSignal, FixtureContext, StoryCleanup, WorkshopTarget } from './contract.js';
+/** The default fixture preparation budget (per-story override: fixtureTimeout). */
+export declare const DEFAULT_FIXTURE_TIMEOUT = 10000;
+/** Bound on owned cleanup before declaring a restart-required state. */
+export declare const DEFAULT_DISPOSAL_TIMEOUT = 10000;
+/** Rejection used to interrupt awaits when a generation is cancelled. */
+export declare class CancelledError extends Error {
+    constructor();
+}
+export declare class Cancellation implements CancellationSignal {
+    aborted: boolean;
+    private readonly listeners;
+    private rejectPromise;
+    /** Rejects as soon as this generation is cancelled — race it against
+     *  fixture work so a superseded selection never waits for a dead run. */
+    readonly promise: Promise<never>;
+    constructor();
+    cancel(): void;
+    addEventListener(_type: 'abort', listener: () => void): void;
+    removeEventListener(_type: 'abort', listener: () => void): void;
+}
+/**
+ * Resources a fixture or provider registered for cleanup. Disposal runs each
+ * cleanup exactly once, attempts every entry even after a failure, and —
+ * after settle() — immediately disposes anything registered late (a fixture
+ * that ignored cancellation still has its resources released).
+ */
+export declare class OwnedResources {
+    private readonly onLateFailure?;
+    private readonly lateTimeout;
+    private readonly cleanups;
+    private settled;
+    private pending;
+    constructor(onLateFailure?: ((error: unknown) => void) | undefined, lateTimeout?: number);
+    readonly failures: {
+        cleanup: StoryCleanup;
+        error: unknown;
+    }[];
+    register(cleanup: StoryCleanup): void;
+    private runOne;
+    /** Unwind in reverse registration order; every entry is attempted. */
+    dispose(): Promise<{
+        errors: unknown[];
+    }>;
+}
+export declare function createFixtureContext(target: WorkshopTarget, capabilities: readonly string[], cancellation: Cancellation, resources: OwnedResources): FixtureContext;
+/** Race a value/promise against a budget; calls onTimeout before rejecting. */
+export declare function withTimeout<T>(value: T | Promise<T>, ms: number, onTimeout: () => void): Promise<T>;

package/types/generated/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @octane-xplat/workshop — public authoring surface.
+ * The contract lives in contract.ts so generated declarations can rewrite
+ * sibling specifiers without index-path ambiguity.
+ */
+export * from './contract.js';

package/types/generated/macos/controller.d.ts

@@ -0,0 +1,52 @@
+import { WorkshopSession } from '../session.js';
+import type { CatalogEntry } from '../catalog.js';
+import type { StageHost } from '../session.js';
+/** Selection and draft ownership are independent of the native chrome's layout. */
+export declare class MacOSWorkshopController {
+    readonly session: WorkshopSession;
+    catalog: readonly CatalogEntry[];
+    selectedId: string | null;
+    query: string;
+    panel: 'stories' | 'controls' | null;
+    stageOnly: boolean;
+    mode: 'wide' | 'compact' | 'phone';
+    drafts: Record<string, string>;
+    errors: Record<string, string>;
+    catalogError: string;
+    private loadGeneration;
+    private readonly listeners;
+    constructor(host: StageHost, providers?: readonly unknown[]);
+    subscribe(listener: () => void): () => boolean;
+    notify(): void;
+    resize(width: number, height: number): void;
+    select(id: string): Promise<void>;
+    updateCatalog(catalog: readonly CatalogEntry[], diagnostics?: readonly {
+        message: string;
+    }[]): Promise<void>;
+    control(key: string, input: unknown): void;
+    reset(): Promise<void>;
+    dispose(): Promise<void>;
+    /** Observable state for host automation and qualification evidence. */
+    inspect(): {
+        phase: import("../session.js").SessionPhase;
+        storyId: string | null;
+        selectedId: string | null;
+        revision: number;
+        mountedGeneration: number;
+        stale: boolean;
+        failure: string | null;
+        catalogError: string | null;
+        props: Record<string, unknown> | null;
+        store: {} | null;
+        fixture: {} | null;
+        mode: "wide" | "compact" | "phone";
+        panel: "controls" | "stories" | null;
+        stageOnly: boolean;
+        drafts: {
+            [x: string]: string;
+        };
+        errors: {
+            [x: string]: string;
+        };
+    };
+}

package/types/generated/macos/index.macos.d.ts

@@ -0,0 +1,2 @@
+export { createMacOSStageHost, type MacOSStageOptions } from './stage.macos.js';
+export { MacOSWorkshopController } from './controller.js';

package/types/generated/macos/stage.macos.d.ts

@@ -0,0 +1,10 @@
+import type { StageHost } from '../session.js';
+export interface MacOSStageOptions {
+    /** An isolated native stage view; shell layout may move/resize it without remounting. */
+    view: any;
+    /** The shell's window — story-owned windows and sheets anchor to it. */
+    parentWindow: any;
+    fontFamily?: string;
+}
+/** Session-owned AppKit root. Full bags remove omitted props, including Unset. */
+export declare function createMacOSStageHost(options: MacOSStageOptions): StageHost;

package/types/generated/mobile/controller.d.ts

@@ -0,0 +1,31 @@
+import type { CatalogEntry } from '../catalog.js';
+import { WorkshopSession } from '../session.js';
+import { type ControlValueInput } from '../controls.js';
+/** Window geometry changes shell presentation only, never the story root. */
+export declare function mobileShellMode(width: number, height: number): 'wide' | 'compact' | 'phone';
+export declare class MobileController {
+    readonly session: WorkshopSession;
+    readonly changed: () => void;
+    selectedId: string | null;
+    catalog: readonly CatalogEntry[];
+    query: string;
+    panel: 'stories' | 'controls' | null;
+    stageOnly: boolean;
+    missingId: string | null;
+    private generation;
+    private disposed;
+    constructor(session: WorkshopSession, catalog: readonly CatalogEntry[], changed: () => void);
+    select(id: string, revision?: string): Promise<void>;
+    updateCatalog(catalog: readonly CatalogEntry[], diagnostics?: readonly {
+        message: string;
+    }[]): void;
+    /**
+     * One Back/Escape step: dismiss shell chrome before the host treats the key
+     * as navigation. The active panel closes first; a stage-only session exits
+     * next; nothing to dismiss returns null so the key keeps its host meaning.
+     * Story content is untouched — panel/flag changes never mount or dispose.
+     */
+    dismissOverlay(): 'panel' | 'stage-only' | null;
+    control(key: string, value: ControlValueInput): string | undefined;
+    dispose(): Promise<void>;
+}

package/types/generated/mobile/entry.mobile.d.ts

@@ -0,0 +1,22 @@
+import { Page } from '@nativescript/core';
+import type { CatalogEntry } from '../catalog.js';
+import { MobileController } from './controller.js';
+export interface MobileWorkshopOptions {
+    catalog: readonly CatalogEntry[];
+    diagnostics?: readonly {
+        message: string;
+    }[];
+    target: 'ios' | 'android';
+    initialStoryId?: string | null;
+    globalProviders?: readonly unknown[];
+}
+export interface MobileWorkshopRuntime {
+    controller: MobileController;
+    page: Page;
+    dispose(): Promise<void>;
+}
+export declare function catalogDidUpdate(catalog: readonly CatalogEntry[], diagnostics?: readonly {
+    message: string;
+}[]): void;
+/** A host-native shell. Its stage ContentView is attached once for its lifetime. */
+export declare function startWorkshop(options: MobileWorkshopOptions): MobileWorkshopRuntime;

package/types/generated/mobile/index.mobile.d.ts

@@ -0,0 +1,3 @@
+export { startWorkshop, catalogDidUpdate } from './entry.mobile.js';
+export type { MobileWorkshopOptions, MobileWorkshopRuntime } from './entry.mobile.js';
+export { createMobileStageHost } from './mount.mobile.js';

package/types/generated/mobile/mount.mobile.d.ts

@@ -0,0 +1,4 @@
+import type { ContentView } from '@nativescript/core';
+import type { StageHost } from '../session.js';
+/** Owns only this stage root; never detaches a runner or application host. */
+export declare function createMobileStageHost(stage: ContentView): StageHost;

package/types/generated/mobile/tree.mobile.d.ts

@@ -0,0 +1,4 @@
+import type { MountRequest } from '../session.js';
+export declare function StoryTree(p: {
+    request: MountRequest;
+}): unknown;

package/types/generated/session.d.ts

@@ -0,0 +1,84 @@
+import type { CancellationSignal, StoryDefinition, WorkshopTarget } from './contract.js';
+import { WorkshopError } from './errors.js';
+export type SessionPhase = 'discovered' | 'preparing' | 'mounting' | 'ready' | 'rebuilding' | 'failed' | 'disposing' | 'disconnected' | 'restart-required';
+export interface SessionSnapshot {
+    phase: SessionPhase;
+    /** The story currently selected (may differ from the mounted one while preparing). */
+    storyId: string | null;
+    /** The generation that produced the visible stage. */
+    mountedGeneration: number;
+    /** True when the visible stage is a previous successful revision. */
+    stale: boolean;
+    /** Present when phase is 'failed' or 'restart-required'. */
+    failure: WorkshopError | undefined;
+    /** Number of successful mounts so far. */
+    revision: number;
+}
+export interface MountRequest {
+    story: StoryDefinition<any, any, any>;
+    component: (props: any) => unknown;
+    props: Record<string, unknown>;
+    providers: readonly unknown[];
+    fixture: unknown;
+    signal: CancellationSignal;
+    onRenderError: (error: unknown) => void;
+}
+export interface MountedStory {
+    update(props: Record<string, unknown>): void;
+    unmount(): void | Promise<void>;
+}
+/** Host adapter seam — the web adapter supplies createRoot mounting. */
+export interface StageHost {
+    mount(request: MountRequest): MountedStory | Promise<MountedStory>;
+}
+interface SessionOptions {
+    host: StageHost;
+    target: WorkshopTarget;
+    globalProviders?: readonly unknown[];
+    onChange?: (snapshot: SessionSnapshot) => void;
+    disposalTimeout?: number;
+}
+export declare class WorkshopSession {
+    private readonly options;
+    private generation;
+    private blockedFailure;
+    private current;
+    private snapshot;
+    private readonly listeners;
+    constructor(options: SessionOptions);
+    get state(): SessionSnapshot;
+    get target(): WorkshopTarget;
+    /** The story definition backing the current generation, if any. */
+    get currentStory(): StoryDefinition<any, any, any> | undefined;
+    /** The current generation's complete props bag (args + applied controls). */
+    get currentProps(): Record<string, unknown> | undefined;
+    subscribe(listener: (snapshot: SessionSnapshot) => void): () => void;
+    private emit;
+    private fail;
+    /** Begin a fresh run of `story`; any prior generation is retired first. */
+    select(story: StoryDefinition<any, any, any>, mode?: 'select' | 'reset' | 'rebuild'): Promise<void>;
+    private injectedProps;
+    /**
+     * Apply the complete next props bag — controls preserve the current
+     * fixture, providers, store and component-local state. Removed keys are
+     * forwarded as explicit `undefined`.
+     */
+    applyProps(next: Record<string, unknown>): void;
+    /** A full fresh run: fresh args, fresh store, fresh fixture, fresh root. */
+    reset(): Promise<void>;
+    /** A successful source edit remounts the selected story revision. */
+    reload(next: StoryDefinition<any, any, any>): Promise<void>;
+    /** A source edit is in flight; the next success remounts. */
+    markRebuilding(): void;
+    /** A failed source edit keeps the last successful stage, visibly stale. */
+    markCompileError(error: unknown): void;
+    markDisconnected(): void;
+    /** Back to live after a disconnect notice. */
+    markConnected(): void;
+    /** Retire a generation: cancel, unmount, run owned cleanups (all of them). */
+    private retire;
+    private disposeGeneration;
+    /** Dispose the session entirely (server shutdown / target restart). */
+    dispose(): Promise<void>;
+}
+export {};