@octane-xplat/workshop 0.0.0-nightly.g14544fe

package/src/contract.ts

@@ -0,0 +1,257 @@
+/**
+ * @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 const WORKSHOP_TARGETS: readonly WorkshopTarget[] = [
+	'web',
+	'ios',
+	'android',
+	'macos',
+	'windows',
+	'linux',
+]
+
+/** Version of the authoring contract — bumped on breaking changes. */
+export 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 function defineStory<P = Record<string, never>, S = void, F = void>(
+	definition: StoryDefinition<P, S, F>,
+): StoryDefinition<P, S, F> {
+	assertLiteralAuthoring(definition)
+	return definition
+}
+
+function assertLiteralAuthoring(definition: StoryDefinition<any, any, any>): void {
+	const fail = (message: string): never => {
+		throw new Error(`defineStory: ${message}`)
+	}
+
+	if (typeof definition?.id !== 'string' || !definition.id) {
+		fail('a story requires a non-empty string id')
+	}
+
+	if (typeof definition.title !== 'string' || !definition.title) {
+		fail(`story "${definition.id}" requires a non-empty string title`)
+	}
+
+	const targets = definition.targets
+	const valid =
+		targets === 'all' ||
+		(Array.isArray(targets) &&
+			targets.length > 0 &&
+			targets.every((t) => WORKSHOP_TARGETS.includes(t)))
+
+	if (!valid) {
+		fail(
+			`story "${definition.id}" — targets must be 'all' or a subset of: ${WORKSHOP_TARGETS.join(', ')}`,
+		)
+	}
+
+	if (typeof definition.component !== 'function') {
+		fail(`story "${definition.id}" — component must be an Octane component`)
+	}
+
+	if (definition.args == null || typeof definition.args !== 'object') {
+		fail(`story "${definition.id}" — args must be an object`)
+	}
+
+	if ('state' in definition && typeof definition.state !== 'function') {
+		fail(`story "${definition.id}" — state must be a factory function`)
+	}
+
+	if ('fixture' in definition && typeof definition.fixture !== 'function') {
+		fail(`story "${definition.id}" — fixture must be a factory function`)
+	}
+
+	if (definition.args && typeof definition.args === 'object') {
+		for (const key of ['state', 'fixture'] as const) {
+			if (key in definition.args) {
+				fail(`story "${definition.id}" — args may not declare reserved injected prop "${key}"`)
+			}
+		}
+	}
+
+	if (definition.controls) {
+		for (const [key, control] of Object.entries(definition.controls)) {
+			if (!control || typeof control !== 'object') {
+				fail(`story "${definition.id}" — control "${key}" must be an object`)
+			}
+
+			const type = (control as { type?: string }).type
+			if (!['boolean', 'string', 'number', 'enum'].includes(type ?? '')) {
+				fail(
+					`story "${definition.id}" — control "${key}" has unknown type "${type}" (expected boolean, string, number or enum)`,
+				)
+			}
+
+			if (type === 'enum' && !Array.isArray((control as EnumControl<unknown>).options)) {
+				fail(`story "${definition.id}" — enum control "${key}" requires an options array`)
+			}
+
+			if (
+				type === 'number' &&
+				typeof (control as NumberControl).min === 'number' &&
+				typeof (control as NumberControl).max === 'number' &&
+				(control as NumberControl).min! > (control as NumberControl).max!
+			) {
+				fail(`story "${definition.id}" — number control "${key}" has min > max`)
+			}
+		}
+	}
+
+	if (definition.providers !== undefined && !Array.isArray(definition.providers)) {
+		fail(`story "${definition.id}" — providers must be an array`)
+	}
+}
+
+/** 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 function defineWorkshopConfig(config: WorkshopConfig): WorkshopConfig {
+	return config
+}

package/src/controls.ts

@@ -0,0 +1,159 @@
+/**
+ * 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'
+
+export const UNSET = Symbol.for('xplat-workshop.unset')
+export type ControlValueInput = boolean | string | number | typeof UNSET
+
+export interface FieldError {
+	message: string
+}
+
+export function isUnsettable(definition: StoryDefinition<any, any, any>, key: string): boolean {
+	const control = definition.controls?.[key] as { allowUnset?: boolean } | undefined
+	if (!control) {
+		return false
+	}
+
+	return control.allowUnset === true || !(key in (definition.args ?? {}))
+}
+
+/** Clone default args per generation — nested data must not leak across runs. */
+export function freshArgs(args: Record<string, unknown>): Record<string, unknown> {
+	const clone = (value: unknown): unknown => {
+		if (Array.isArray(value)) {
+			return value.map(clone)
+		}
+
+		if (value !== null && typeof value === 'object') {
+			const proto = Object.getPrototypeOf(value)
+			if (proto !== Object.prototype && proto !== null) {
+				return value // class instances / stores: pass through, do not clone
+			}
+
+			const out: Record<string, unknown> = {}
+			for (const [k, v] of Object.entries(value)) {
+				out[k] = clone(v)
+			}
+
+			return out
+		}
+
+		return value // functions and primitives pass through
+	}
+
+	return clone(args) as 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 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 } {
+	const control = definition.controls?.[key] as
+		| {
+				type: string
+				min?: number
+				max?: number
+				options?: readonly unknown[]
+				allowUnset?: boolean
+		  }
+		| undefined
+
+	if (!control) {
+		return { error: { message: `no control declared for "${key}"` } }
+	}
+
+	const next = { ...currentProps }
+	if (raw === UNSET) {
+		if (!isUnsettable(definition, key)) {
+			return { error: { message: `"${key}" is a required prop and cannot be unset` } }
+		}
+
+		delete next[key]
+		return { props: next }
+	}
+
+	switch (control.type) {
+		case 'boolean': {
+			if (typeof raw !== 'boolean') {
+				return { error: { message: 'expected a boolean' } }
+			}
+
+			next[key] = raw
+			return { props: next }
+		}
+		case 'string': {
+			if (typeof raw !== 'string') {
+				return { error: { message: 'expected a string' } }
+			}
+
+			next[key] = raw
+			return { props: next }
+		}
+		case 'number': {
+			const value =
+				typeof raw === 'number'
+					? raw
+					: typeof raw === 'string' && raw.trim() === ''
+						? NaN
+						: Number(raw)
+
+			if (!Number.isFinite(value)) {
+				return { error: { message: `"${key}" needs a finite number` } }
+			}
+
+			if (control.min !== undefined && value < control.min) {
+				return { error: { message: `"${key}" must be ≥ ${control.min}` } }
+			}
+
+			if (control.max !== undefined && value > control.max) {
+				return { error: { message: `"${key}" must be ≤ ${control.max}` } }
+			}
+
+			next[key] = value
+			return { props: next }
+		}
+		case 'enum': {
+			if (!(control.options ?? []).some((option) => Object.is(option, raw))) {
+				return {
+					error: {
+						message: `"${key}" must be one of: ${(control.options ?? []).map(String).join(', ')}`,
+					},
+				}
+			}
+
+			next[key] = raw
+			return { props: next }
+		}
+		default:
+			return { error: { message: `unsupported control type "${control.type}"` } }
+	}
+}
+
+/**
+ * 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 function reconcileProps(
+	previous: Record<string, unknown>,
+	next: Record<string, unknown>,
+): Record<string, unknown> {
+	const merged: Record<string, unknown> = { ...next }
+	for (const key of Object.keys(previous)) {
+		if (!(key in next)) {
+			merged[key] = undefined
+		}
+	}
+
+	return merged
+}

package/src/errors.ts

@@ -0,0 +1,47 @@
+/** Failure phases surfaced by the workshop shell and CLI. */
+export type WorkshopErrorPhase =
+	| 'discovery'
+	| 'compile'
+	| 'fixture'
+	| 'mount'
+	| 'interaction'
+	| 'cleanup'
+	| 'launch'
+	| 'connection'
+
+export 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 },
+	) {
+		super(message)
+		this.name = 'WorkshopError'
+		this.phase = phase
+		this.storyId = options?.storyId
+		this.sourceLocation = options?.sourceLocation
+		if (options?.cause !== undefined) {
+			;(this as { cause?: unknown }).cause = options.cause
+		}
+	}
+}
+
+export function describeCause(cause: unknown): string {
+	if (cause instanceof Error) {
+		// JSC stacks often start directly at a `fn@file:line` frame without the
+		// `Name: message` head — keep the message visible either way.
+		const head = `${cause.name}: ${cause.message}`
+		const tail = cause.stack?.split('\n').slice(0, 3).join('\n')
+		if (!tail) {
+			return head
+		}
+
+		return tail.startsWith(head) ? tail : `${head}\n${tail}`
+	}
+
+	return String(cause)
+}

package/src/fixture.ts

@@ -0,0 +1,158 @@
+/**
+ * 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'
+
+/** The default fixture preparation budget (per-story override: fixtureTimeout). */
+export const DEFAULT_FIXTURE_TIMEOUT = 10_000
+/** Bound on owned cleanup before declaring a restart-required state. */
+export const DEFAULT_DISPOSAL_TIMEOUT = 10_000
+
+/** Rejection used to interrupt awaits when a generation is cancelled. */
+export class CancelledError extends Error {
+	constructor() {
+		super('workshop generation cancelled')
+		this.name = 'CancelledError'
+	}
+}
+
+export class Cancellation implements CancellationSignal {
+	aborted = false
+	private readonly listeners = new Set<() => void>()
+	private rejectPromise: ((error: Error) => void) | undefined
+
+	/** 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 = new Promise<never>((_resolve, reject) => {
+		this.rejectPromise = reject
+	})
+
+	constructor() {
+		// Cancellation can land while nothing is racing the promise — keep it
+		// counted as handled so it never reports an unhandled rejection.
+		this.promise.catch(() => {})
+	}
+
+	cancel(): void {
+		this.rejectPromise?.(new CancelledError())
+		if (this.aborted) {
+			return
+		}
+
+		this.aborted = true
+		for (const listener of this.listeners) {
+			try {
+				listener()
+			} catch {
+				// Listener failures must not stop sibling notifications.
+			}
+		}
+
+		this.listeners.clear()
+	}
+
+	addEventListener(_type: 'abort', listener: () => void): void {
+		if (this.aborted) {
+			listener()
+			return
+		}
+
+		this.listeners.add(listener)
+	}
+
+	removeEventListener(_type: 'abort', listener: () => void): void {
+		this.listeners.delete(listener)
+	}
+}
+
+/**
+ * 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 class OwnedResources {
+	private readonly cleanups: StoryCleanup[] = []
+	private settled = false
+	private pending = Promise.resolve()
+	constructor(
+		private readonly onLateFailure?: (error: unknown) => void,
+		private readonly lateTimeout = DEFAULT_DISPOSAL_TIMEOUT,
+	) {}
+
+	readonly failures: { cleanup: StoryCleanup; error: unknown }[] = []
+
+	register(cleanup: StoryCleanup): void {
+		if (this.settled) {
+			// Registered after cancellation/settlement: dispose exactly once, now.
+			this.pending = Promise.all([this.pending, this.runOne(cleanup, true)]).then(() => {})
+			return
+		}
+
+		this.cleanups.push(cleanup)
+	}
+
+	private async runOne(cleanup: StoryCleanup, late = false): Promise<void> {
+		try {
+			const work = cleanup()
+			await (late ? withTimeout(Promise.resolve(work), this.lateTimeout, () => {}) : work)
+		} catch (error) {
+			this.failures.push({ cleanup, error })
+			if (late) {
+				this.onLateFailure?.(error)
+			}
+		}
+	}
+
+	/** Unwind in reverse registration order; every entry is attempted. */
+	async dispose(): Promise<{ errors: unknown[] }> {
+		this.settled = true
+		const entries = this.cleanups.splice(0)
+		// Start every cleanup in reverse ownership order. A hung cleanup must
+		// not prevent siblings from being attempted before the global timeout.
+		await Promise.all(entries.reverse().map((cleanup) => this.runOne(cleanup)))
+
+		await this.pending
+		return { errors: this.failures.map((f) => f.error) }
+	}
+}
+
+export function createFixtureContext(
+	target: WorkshopTarget,
+	capabilities: readonly string[],
+	cancellation: Cancellation,
+	resources: OwnedResources,
+): FixtureContext {
+	return {
+		target,
+		capabilities,
+		signal: cancellation,
+		onCleanup: (cleanup) => resources.register(cleanup),
+	}
+}
+
+/** Race a value/promise against a budget; calls onTimeout before rejecting. */
+export async function withTimeout<T>(
+	value: T | Promise<T>,
+	ms: number,
+	onTimeout: () => void,
+): Promise<T> {
+	let timer: ReturnType<typeof setTimeout> | undefined
+	try {
+		return await Promise.race([
+			Promise.resolve(value),
+			new Promise<never>((_resolve, reject) => {
+				timer = setTimeout(() => {
+					onTimeout()
+					reject(new Error(`timed out after ${ms}ms`))
+				}, ms)
+			}),
+		])
+	} finally {
+		if (timer !== undefined) {
+			clearTimeout(timer)
+		}
+	}
+}

package/src/index.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'