@octane-xplat/workshop 0.1.0 → 0.15.0

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'

package/src/macos/controller.ts

@@ -0,0 +1,170 @@
+import { WorkshopSession } from '../session'
+import { applyControlInput, UNSET } from '../controls'
+import type { CatalogEntry } from '../catalog'
+import type { StageHost } from '../session'
+import type { StoryDefinition } from '../contract'
+
+/** Selection and draft ownership are independent of the native chrome's layout. */
+export class MacOSWorkshopController {
+	readonly session: WorkshopSession
+	catalog: readonly CatalogEntry[] = []
+	selectedId: string | null = null
+	query = ''
+	panel: 'stories' | 'controls' | null = null
+	stageOnly = false
+	mode: 'wide' | 'compact' | 'phone' = 'wide'
+	drafts: Record<string, string> = {}
+	errors: Record<string, string> = {}
+	catalogError = ''
+	private loadGeneration = 0
+	private readonly listeners = new Set<() => void>()
+	constructor(host: StageHost, providers: readonly unknown[] = []) {
+		this.session = new WorkshopSession({ host, target: 'macos', globalProviders: providers })
+		this.session.subscribe(() => this.notify())
+	}
+	subscribe(listener: () => void) {
+		this.listeners.add(listener)
+		return () => this.listeners.delete(listener)
+	}
+	notify() {
+		for (const listener of this.listeners) {
+			listener()
+		}
+	}
+	resize(width: number, height: number) {
+		this.mode = width >= 1000 && height >= 480 ? 'wide' : width <= 560 ? 'phone' : 'compact'
+		this.notify()
+	}
+	async select(id: string) {
+		const serial = ++this.loadGeneration
+		this.selectedId = id
+		this.drafts = {}
+		this.errors = {}
+		this.panel = null
+		this.notify()
+		const entry =
+			this.catalog.find((e) => e.id === id && e.applicable && e.load) ??
+			this.catalog.find((e) => e.id === id)
+
+		if (!entry?.applicable || !entry.load) {
+			await this.session.dispose()
+			this.catalogError = entry?.reason ?? `Story "${id}" is missing; choose from the catalog.`
+			this.notify()
+			return
+		}
+
+		try {
+			const loaded = await entry.load()
+			if (serial !== this.loadGeneration) {
+				return
+			}
+
+			const definition = (loaded as Record<string, unknown>)[entry.exportName] as StoryDefinition<
+				any,
+				any,
+				any
+			>
+
+			if (!definition || definition.id !== id) {
+				throw new Error(`Story export ${entry.exportName} no longer declares ${id}`)
+			}
+
+			this.catalogError = ''
+			await this.session.select(definition)
+		} catch (error) {
+			if (serial === this.loadGeneration) {
+				this.session.markCompileError(error)
+			}
+		}
+	}
+	async updateCatalog(
+		catalog: readonly CatalogEntry[],
+		diagnostics: readonly { message: string }[] = [],
+	) {
+		this.catalog = catalog
+		if (diagnostics.length) {
+			++this.loadGeneration
+			this.catalogError = diagnostics.map((d) => d.message).join('\n')
+			this.session.markCompileError(this.catalogError)
+			this.notify()
+			return
+		}
+
+		this.catalogError = ''
+		if (this.selectedId) {
+			await this.select(this.selectedId)
+		}
+
+		this.notify()
+	}
+	control(key: string, input: unknown) {
+		const story = this.session.currentStory
+		const control = story?.controls?.[key]
+		if (!story || !control || this.session.state.phase !== 'ready') {
+			return
+		}
+
+		if (input !== UNSET) {
+			this.drafts[key] = String(input)
+		}
+
+		const result = applyControlInput(story, this.session.currentProps ?? {}, key, input as any)
+		if (result.error) {
+			this.errors[key] = result.error.message
+		} else if (result.props) {
+			delete this.errors[key]
+			this.session.applyProps(result.props)
+		}
+
+		this.notify()
+	}
+	async reset() {
+		this.drafts = {}
+		this.errors = {}
+		await this.session.reset()
+		this.notify()
+	}
+	async dispose() {
+		++this.loadGeneration
+		await this.session.dispose()
+		this.listeners.clear()
+	}
+	/** Observable state for host automation and qualification evidence. */
+	inspect() {
+		const state = this.session.state
+		const generation = (
+			this.session as unknown as {
+				current?: {
+					fixture: unknown
+					store?: { getSnapshot(): unknown }
+				}
+			}
+		).current
+
+		let store
+		try {
+			store = generation?.store?.getSnapshot()
+		} catch {
+			store = undefined
+		}
+
+		return {
+			phase: state.phase,
+			storyId: state.storyId ?? null,
+			selectedId: this.selectedId,
+			revision: state.revision,
+			mountedGeneration: state.mountedGeneration,
+			stale: state.stale,
+			failure: state.failure ? String(state.failure.message ?? state.failure) : null,
+			catalogError: this.catalogError || null,
+			props: this.session.currentProps ?? null,
+			store: store ?? null,
+			fixture: generation?.fixture ?? null,
+			mode: this.mode,
+			panel: this.panel,
+			stageOnly: this.stageOnly,
+			drafts: { ...this.drafts },
+			errors: { ...this.errors },
+		}
+	}
+}

package/src/macos/index.macos.ts

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