@octane-xplat/workshop 0.1.0 → 0.15.0

package/src/vite.mjs

@@ -0,0 +1,315 @@
+/**
+ * xplatWorkshop — the workshop dev-server plugin.
+ *
+ * Emits a virtual catalog module whose metadata comes from static discovery
+ * (never module evaluation), a virtual entry that boots the adaptive shell,
+ * and a virtual index.html. Story modules stay lazily imported per selection;
+ * loaders exist only for stories applicable to the build target, so a
+ * platform-specific leaf is never imported into an incompatible bundle.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { discoverStories, normalizeInclude } from './discover.mjs'
+
+const CATALOG_ID = '\0xplat-workshop-catalog'
+const ENTRY_ID = '\0xplat-workshop-entry'
+const STORY_FILE_RE =
+	/\.stories(?:\.(?:web|mobile|ios|android|macos|windows|linux))?\.(?:[cm]?[jt]s|[jt]sx|[jt]srx)$/
+
+const WEB_EXTENSIONS = [
+	'.web.tsrx',
+	'.tsrx',
+	'.web.tsx',
+	'.tsx',
+	'.web.ts',
+	'.mjs',
+	'.mts',
+	'.ts',
+	'.jsx',
+	'.js',
+	'.json',
+]
+
+// Per-target resolution for DOM-rendering hosts. Linux renders the same DOM
+// inside the system webview, so its chain mirrors the consumer Linux preset
+// (apps/linux/vite.linux.config.ts): .linux → .web → shared, conditions
+// 'linux' then 'web'.
+const TARGET_RESOLUTION = {
+	web: { conditions: ['web'], extensions: WEB_EXTENSIONS },
+	linux: {
+		conditions: ['linux', 'web'],
+		extensions: [
+			'.linux.tsrx',
+			'.web.tsrx',
+			'.tsrx',
+			'.linux.tsx',
+			'.web.tsx',
+			'.tsx',
+			'.linux.ts',
+			'.web.ts',
+			'.mjs',
+			'.mts',
+			'.ts',
+			'.jsx',
+			'.js',
+			'.json',
+		],
+	},
+}
+
+const fsUrl = (file) => `/@fs/${file.split(sep).join('/')}`
+
+function catalogCode(root, config, target) {
+	const storiesConfig = config?.stories ?? {}
+	const { entries, diagnostics } = discoverStories(root, {
+		include: storiesConfig.include,
+		exclude: storiesConfig.exclude,
+		target,
+	})
+
+	const include = JSON.stringify(normalizeInclude(storiesConfig.include))
+	const loaders = entries
+		.filter((entry) => entry.applicable && diagnostics.length === 0)
+		.map(
+			(entry) => `\t${JSON.stringify(entry.id)}: (stamp) => stamp === undefined
+\t\t? import(${JSON.stringify(fsUrl(entry.file))})
+\t\t: import(/* @vite-ignore */ ${JSON.stringify(fsUrl(entry.file))} + '?t=' + encodeURIComponent(String(stamp))),`,
+		)
+		.join('\n')
+
+	return `import { catalogDidUpdate } from '@octane-xplat/workshop/web'
+
+export const catalogMeta = ${JSON.stringify(entries)}
+export const diagnostics = ${JSON.stringify(diagnostics)}
+export const includePatterns = ${include}
+
+const loaders = {
+${loaders}
+}
+
+export const catalog = catalogMeta.map((entry) =>
+	loaders[entry.id] ? { ...entry, load: loaders[entry.id] } : entry,
+)
+
+export function loadStory(id, stamp) {
+	const entry = catalog.find((item) => item.id === id)
+	if (!entry?.load) {
+		return Promise.reject(
+			new Error(
+				entry
+					? 'story "' + id + '" is not supported on this target'
+					: 'story "' + id + '" is not in the catalog',
+			),
+		)
+	}
+	return entry.load(stamp)
+}
+
+catalogDidUpdate(catalog, diagnostics)
+if (import.meta.hot) {
+	import.meta.hot.accept((next) => catalogDidUpdate(next?.catalog ?? catalog, next?.diagnostics ?? diagnostics))
+}
+`
+}
+
+function entryCode(config, target, story, packageDir, root) {
+	const providerModules = config?.providerModules ?? []
+	const imports = providerModules
+		.map((specifier, index) => {
+			const abs = resolve(root, specifier)
+			return `import * as __workshopPreset${index} from ${JSON.stringify(fsUrl(abs))}`
+		})
+		.join('\n')
+
+	const providers = providerModules
+		.map(
+			(_, index) =>
+				`...(__workshopPreset${index}.providers ?? __workshopPreset${index}.default ?? [])`,
+		)
+		.join(', ')
+
+	const shellCss = fsUrl(join(packageDir, 'web', 'shell.css'))
+
+	return `import { catalog, loadStory, diagnostics } from ${JSON.stringify(CATALOG_ID)}
+import { startWorkshop } from '@octane-xplat/workshop/web'
+import '@octane-xplat/ui/theme/tokens.css'
+import ${JSON.stringify(shellCss)}
+${imports}
+
+startWorkshop({
+	catalog,
+	diagnostics,
+	loadStory,
+	target: ${JSON.stringify(target)},
+	initialStoryId: ${JSON.stringify(story ?? null)},
+	globalProviders: [${providers}],
+	hot: import.meta.hot,
+})
+`
+}
+
+const WORKSHOP_HTML = `<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<title>octane-xplat workshop</title>
+		<style>html,body{margin:0;height:100%}#workshop-root{height:100%}</style>
+	</head>
+	<body>
+		<div id="workshop-root"></div>
+		<script type="module" src="/@id/__x00__xplat-workshop-entry"></script>
+	</body>
+</html>
+`
+
+/**
+ * @param {object} [options]
+ * @param {string} options.cwd - consumer project root
+ * @param {object} [options.config] - resolved workshop.config.* contents
+ * @param {string} [options.target] - launch target (DOM hosts: 'web' | 'linux')
+ * @param {string} [options.story] - initial stable story id
+ */
+export function xplatWorkshop(options = {}) {
+	const target = options.target ?? 'web'
+	const story = options.story ?? null
+	const resolution = TARGET_RESOLUTION[target] ?? TARGET_RESOLUTION.web
+	let root = options.cwd ?? process.cwd()
+	let config = options.config ?? {}
+
+	const virtualModules = {
+		name: 'xplat-workshop-virtual',
+		configResolved(resolved) {
+			root = options.cwd ?? resolved.root
+		},
+		resolveId(id) {
+			if (id === CATALOG_ID || id === ENTRY_ID) {
+				return id
+			}
+
+			return null
+		},
+		load(id) {
+			if (id === CATALOG_ID) {
+				return catalogCode(root, config, target)
+			}
+
+			if (id === ENTRY_ID) {
+				return entryCode(config, target, story, dirname(fileURLToPath(import.meta.url)), root)
+			}
+
+			return null
+		},
+	}
+
+	const shell = {
+		name: 'xplat-workshop-shell',
+		config() {
+			return {
+				optimizeDeps: {
+					exclude: ['@octane-xplat/workshop'],
+					// The packed workshop is excluded from compilation, so explicitly
+					// optimize its portable composition dependency and CJS transitive graph.
+					include: ['@octane-xplat/workshop > storybook/preview-api'],
+				},
+				resolve: {
+					conditions: [...resolution.conditions],
+				},
+			}
+		},
+		configResolved(resolved) {
+			// The octane plugin's extension list merges first, which would let the
+			// unsuffixed .tsrx leaf shadow the target's leaf. Environments carry
+			// their own resolved lists — rewrite every one.
+			const apply = (scope) => {
+				scope.resolve.extensions = [
+					...resolution.extensions,
+					...scope.resolve.extensions.filter((ext) => !resolution.extensions.includes(ext)),
+				]
+
+				scope.resolve.conditions = [
+					...resolution.conditions,
+					...scope.resolve.conditions.filter((cond) => !resolution.conditions.includes(cond)),
+				]
+			}
+
+			apply(resolved)
+			for (const env of Object.values(resolved.environments ?? {})) {
+				apply(env)
+			}
+		},
+		hotUpdate: {
+			// 'pre' plus registration ahead of the octane plugin: octane's own
+			// hotUpdate full-reloads every octane file whose modules are not all
+			// self-accepting, which would reset the workshop page on every story
+			// save. Answering with the accepting catalog alone makes octane's
+			// every-self-accepting early return match, while the catalog update
+			// re-discovers metadata and remounts the story through a fresh
+			// stamped loader import.
+			order: 'pre',
+			handler(ctx) {
+				if (this.environment.name !== 'client' || !STORY_FILE_RE.test(ctx.file)) {
+					return
+				}
+
+				const catalog = this.environment.moduleGraph.getModuleById(CATALOG_ID)
+				if (!catalog) {
+					return
+				}
+
+				this.environment.moduleGraph.invalidateModule(catalog)
+				// The environment-aware hook includes create/delete. Stamped story
+				// nodes carry no graph importer edge (@vite-ignore loader import),
+				// so seeding them would dead-end propagation into a full reload.
+				return [catalog]
+			},
+		},
+		configureServer(s) {
+			// The workshop page is a separate dev entry — intercept '/' before
+			// vite's own index fallback can serve the consumer app's document.
+			s.middlewares.use((req, res, next) => {
+				const url = (req.url ?? '').split('?')[0]
+				if (url === '/' || url === '/index.html') {
+					res.statusCode = 200
+					res.setHeader('content-type', 'text/html; charset=utf-8')
+					res.end(WORKSHOP_HTML)
+					return
+				}
+
+				if (url.startsWith('/@workshop-assets/')) {
+					return serveAsset(config, root, url, res, next)
+				}
+
+				next()
+			})
+		},
+	}
+
+	return [virtualModules, shell]
+}
+
+function serveAsset(config, root, url, res, next) {
+	const assets = config?.assets ?? {}
+	const rest = url.slice('/@workshop-assets/'.length)
+	const name = rest.split('/')[0]
+	const dir = assets[name] ? resolve(root, assets[name]) : null
+	if (!dir) {
+		next()
+		return
+	}
+
+	const file = resolve(dir, rest.slice(name.length + 1))
+	if (
+		!(file === dir || file.startsWith(dir + sep)) ||
+		!existsSync(file) ||
+		!statSync(file).isFile()
+	) {
+		res.statusCode = 404
+		res.end('not found')
+		return
+	}
+
+	res.statusCode = 200
+	res.end(readFileSync(file))
+}

package/src/web/entry.web.ts

@@ -0,0 +1,270 @@
+/**
+ * Workshop web entry — boots the shell, wires the session to HMR events, and
+ * receives refreshed catalogs when the virtual catalog module re-executes.
+ */
+import { createElement, createRoot } from 'octane'
+import { createStore } from '@octane-xplat/ui/data'
+import type { CatalogEntry } from '../catalog'
+import type { StoryDefinition, WorkshopTarget } from '../contract'
+import type { SessionSnapshot } from '../session'
+import { WorkshopSession } from '../session'
+import { createWebStageHost } from './mount.web'
+import { WorkshopApp } from './shell.web.tsrx'
+
+export interface ShellState {
+	mode: 'wide' | 'compact' | 'phone'
+	query: string
+	selectedId: string | null
+	expanded: ReadonlySet<string>
+	catalogCollapsed: boolean
+	controlsCollapsed: boolean
+	auxPanel: 'stories' | 'controls' | null
+	stageOnly: boolean
+	stageBackground: 'default' | 'light' | 'dark'
+	stageBounds: 'available' | 'small' | 'medium'
+	catalog: CatalogEntry[]
+	catalogError: string | undefined
+	missingId: string | null
+	session: SessionSnapshot
+	drafts: Record<string, string>
+	fieldErrors: Record<string, string>
+	unsetKeys: ReadonlySet<string>
+}
+
+export interface WorkshopRuntime {
+	store: ReturnType<typeof createStore<ShellState>>
+	session: WorkshopSession
+	mountHost: HTMLElement
+	selectEntry(entry: CatalogEntry): Promise<void>
+	updateCatalog(entries: CatalogEntry[], diagnostics?: readonly { message: string }[]): void
+	loadGeneration: number
+}
+
+let runtime: WorkshopRuntime | null = null
+
+/** Called by the generated catalog module on load and on every HMR re-execution. */
+export function catalogDidUpdate(
+	entries: CatalogEntry[],
+	diagnostics: readonly { message: string }[] = [],
+): void {
+	runtime?.updateCatalog(entries, diagnostics)
+}
+
+export interface WorkshopBootOptions {
+	catalog: CatalogEntry[]
+	diagnostics?: readonly { message: string }[]
+	target: WorkshopTarget
+	initialStoryId?: string | null
+	globalProviders?: readonly unknown[]
+	/** Vite HMR handle — passed by the generated entry because lib builds
+	 *  fold `import.meta.hot` to undefined. */
+	hot?: { on?: (event: string, cb: (payload?: unknown) => void) => void }
+}
+
+export function startWorkshop(options: WorkshopBootOptions): WorkshopRuntime {
+	const mountHost = document.createElement('div')
+	mountHost.className = 'xw-stage-host'
+
+	const session = new WorkshopSession({
+		host: createWebStageHost(mountHost),
+		target: options.target,
+		globalProviders: options.globalProviders ?? [],
+	})
+
+	const store = createStore<ShellState>({
+		mode: 'wide',
+		query: '',
+		selectedId: null,
+		expanded: new Set(groupKeys(options.catalog)),
+		catalogCollapsed: false,
+		controlsCollapsed: false,
+		auxPanel: null,
+		stageOnly: false,
+		stageBackground: 'default',
+		stageBounds: 'available',
+		catalog: options.catalog,
+		catalogError: options.diagnostics?.length
+			? options.diagnostics.map((d) => d.message).join('\n')
+			: undefined,
+		missingId: null,
+		session: session.state,
+		drafts: {},
+		fieldErrors: {},
+		unsetKeys: new Set(),
+	})
+
+	session.subscribe((snapshot) => {
+		store.update((s) => ({ ...s, session: snapshot }))
+	})
+
+	runtime = {
+		store,
+		session,
+		mountHost,
+		loadGeneration: 0,
+		async selectEntry(entry) {
+			if (!entry.load) {
+				return
+			}
+
+			const generation = ++runtime!.loadGeneration
+			try {
+				const loaded = await entry.load()
+				if (generation !== runtime!.loadGeneration) {
+					return
+				}
+
+				const definition = resolveDefinition(loaded, entry)
+				await session.select(definition)
+			} catch (error) {
+				if (generation === runtime!.loadGeneration) {
+					session.markCompileError(error)
+				}
+			}
+		},
+		updateCatalog(entries, diagnostics = []) {
+			const generation = ++runtime!.loadGeneration
+			const stamp = String(Date.now())
+			store.update((s) => ({
+				...s,
+				catalog: entries,
+				catalogError: diagnostics.length ? diagnostics.map((d) => d.message).join('\n') : undefined,
+				expanded: new Set([...s.expanded, ...groupKeys(entries)]),
+			}))
+
+			if (diagnostics.length) {
+				session.markCompileError(diagnostics.map((d) => d.message).join('\n'))
+				return
+			}
+
+			const current = store.getSnapshot().selectedId
+			if (!current) {
+				return
+			}
+
+			const entry = pickEntry(entries, current)
+			if (!entry?.load) {
+				store.update((s) => ({ ...s, missingId: current }))
+				void session.dispose()
+				return
+			}
+
+			void (async () => {
+				try {
+					const loaded = await entry.load!(stamp)
+					if (generation !== runtime!.loadGeneration) {
+						return
+					}
+
+					await session.reload(resolveDefinition(loaded, entry))
+				} catch (error) {
+					if (generation === runtime!.loadGeneration) {
+						session.markCompileError(error)
+					}
+				}
+			})()
+		},
+	}
+
+	// Automation hook — tests and the dev bridge read the live session/store.
+	;(globalThis as Record<string, unknown>).__xplatWorkshopRuntime = runtime
+
+	// Dev-server lifecycle: rebuilds mark the stage rebuilding; a failed
+	// transform keeps the last good stage and marks it stale.
+	let updateLoadGeneration = 0
+	options.hot?.on?.('vite:beforeUpdate', () => {
+		updateLoadGeneration = runtime!.loadGeneration
+		session.markRebuilding()
+	})
+
+	options.hot?.on?.('vite:afterUpdate', () => {
+		// Octane component modules self-accept HMR, which can stop propagation
+		// before the catalog. Retire/remount once the successful update has
+		// applied; a catalog update already owns its own fresh generation.
+		if (runtime!.loadGeneration === updateLoadGeneration && session.state.stale) {
+			runtime!.updateCatalog(store.getSnapshot().catalog)
+		}
+	})
+
+	options.hot?.on?.('vite:error', (payload) => {
+		const err = payload as { err?: { message?: string } } | undefined
+		session.markCompileError(err?.err?.message ?? 'source update failed')
+	})
+
+	options.hot?.on?.('vite:ws:disconnect', () => session.markDisconnected())
+	options.hot?.on?.('vite:ws:connect', () => session.markConnected())
+
+	const hostElement = document.getElementById('workshop-root') ?? document.body
+	createRoot(hostElement).render(createElement(WorkshopApp as never, { runtime } as never))
+
+	// Hash selection: #/story/<id> survives reloads and deep-links a story.
+	const idFromHash = () => {
+		const raw = location.hash.replace(/^#\/?story\//, '')
+		try {
+			return decodeURIComponent(raw) || null
+		} catch {
+			return raw || null
+		}
+	}
+
+	const pickEntry = (entries: CatalogEntry[], id: string) =>
+		entries.find((e) => e.id === id && e.load) ?? entries.find((e) => e.id === id)
+
+	const initialId = options.initialStoryId ?? idFromHash()
+	if (initialId) {
+		const entry = pickEntry(options.catalog, initialId)
+		if (entry?.load) {
+			store.update((s) => ({ ...s, selectedId: initialId }))
+			void runtime.selectEntry(entry)
+		} else {
+			store.update((s) => ({ ...s, selectedId: initialId, missingId: initialId }))
+		}
+	}
+
+	globalThis.addEventListener?.('hashchange', () => {
+		const id = idFromHash()
+		if (id && id !== store.getSnapshot().selectedId) {
+			const entry = pickEntry(store.getSnapshot().catalog, id)
+			if (entry?.load) {
+				store.update((s) => ({ ...s, selectedId: id, missingId: null }))
+				void runtime!.selectEntry(entry)
+			} else {
+				++runtime!.loadGeneration
+				store.update((s) => ({ ...s, selectedId: id, missingId: id }))
+				void session.dispose()
+			}
+		}
+	})
+
+	return runtime
+}
+
+/** Group keys (`name@depth`) for every title segment group in the catalog. */
+function groupKeys(entries: CatalogEntry[]): string[] {
+	const keys = new Set<string>()
+	for (const entry of entries) {
+		const segments = entry.title
+			.split('/')
+			.map((seg) => seg.trim())
+			.filter(Boolean)
+
+		for (let depth = 0; depth < segments.length - 1; depth++) {
+			keys.add(`${segments[depth]}@${depth}`)
+		}
+	}
+
+	return [...keys]
+}
+
+function resolveDefinition(loaded: unknown, entry: CatalogEntry): StoryDefinition<any, any, any> {
+	const mod = loaded as Record<string, unknown>
+	const candidate: unknown = mod?.[entry.exportName]
+	const definition = candidate as StoryDefinition<any, any, any> | undefined
+	if (!definition || typeof definition !== 'object' || definition.id !== entry.id) {
+		throw new Error(
+			`story module ${entry.file} did not provide a story definition at export "${entry.exportName}"`,
+		)
+	}
+
+	return definition
+}

package/src/web/index.web.ts

@@ -0,0 +1,7 @@
+/**
+ * Web runtime entry — the catalog virtual module and the generated workshop
+ * entry import this. Exposes startWorkshop plus the catalog-update seam the
+ * virtual catalog calls back into after HMR re-execution.
+ */
+export { createWebStageHost } from './mount.web'
+export { startWorkshop, catalogDidUpdate } from './entry.web'

package/src/web/mount.web.ts

@@ -0,0 +1,86 @@
+/**
+ * Web stage host — mounts a prepared story renderable inside the shell's
+ * stage element through the real Octane DOM renderer. Each generation owns
+ * its root; `unmount` disposes the subtree including owned portals.
+ */
+import { ErrorBoundary, createElement, createRoot } from 'octane'
+import { composeStory } from 'storybook/preview-api'
+import type { MountedStory, MountRequest, StageHost } from '../session'
+
+function storyTree(request: MountRequest): any {
+	let inner: any = createElement(request.component as any, request.props)
+	for (const provider of [...request.providers].reverse()) {
+		inner = createElement(provider as any, { fixture: request.fixture } as any, inner)
+	}
+
+	// A story render error swaps to a marker node and reports to the session;
+	// the shell keeps navigation/reset reachable around the failed subtree.
+	return createElement(
+		ErrorBoundary as any,
+		{
+			fallback: (error: unknown) => {
+				// The fallback runs inside the render pass — octane rejects store
+				// updates there, so report after the pass commits.
+				queueMicrotask(() => request.onRenderError(error))
+				return createElement('div', {
+					className: 'xw-stage-error-marker',
+					role: 'alert',
+				})
+			},
+		},
+		inner,
+	)
+}
+
+export function createWebStageHost(stageElement: HTMLElement): StageHost {
+	return {
+		mount(request: MountRequest): MountedStory {
+			// Pin the visual harness's portable composition subset to Storybook
+			// 10.6.1. Octane still mounts the compiled component; the session
+			// owns fixtures, providers, cancellation and every cleanup.
+			const composed = composeStory(
+				{ args: request.props },
+				{ title: request.story.title, component: request.component } as any,
+				{ render: (props: any) => storyTree({ ...request, props }) } as any,
+				{},
+				'Story',
+			)
+
+			const mountPoint = globalThis.document.createElement('div')
+			mountPoint.className = 'xw-stage-mount'
+			stageElement.append(mountPoint)
+			const root = createRoot(mountPoint)
+
+			try {
+				root.render(composed(request.props) as any)
+			} catch (error) {
+				root.unmount()
+				mountPoint.remove()
+				throw error
+			}
+
+			let disposed = false
+			return {
+				update(props: Record<string, unknown>) {
+					if (disposed) {
+						return
+					}
+
+					root.render(composed(props) as any)
+				},
+				unmount() {
+					if (disposed) {
+						return
+					}
+
+					disposed = true
+					try {
+						root.unmount()
+					} finally {
+						mountPoint.remove()
+					}
+				},
+			}
+		},
+	}
+}