@octane-xplat/workshop 0.1.0 → 0.15.0

package/src/macos/stage.macos.ts

@@ -0,0 +1,182 @@
+import {
+	defineUniversalComponent,
+	universalChildren,
+	universalComponent,
+	universalTry,
+} from 'octane/universal/native'
+
+import { createMacOSRoot } from '@octane-xplat/macos-renderer'
+import type { StageHost, MountRequest, MountedStory } from '../session'
+
+const RENDERER = 'macos'
+const UNIVERSAL_COMPONENT = Symbol.for('octane.universal.component')
+
+/** Compiler output is already defined; plain functions need the stamp before
+ * the root will mount them (same rule hmrUniversalComponent applies). */
+const asComponent = (component: any) =>
+	component?.[UNIVERSAL_COMPONENT]
+		? component
+		: defineUniversalComponent(RENDERER, component, {
+				module: '@octane-xplat/workshop/macos-stage',
+			} as any)
+
+/**
+ * Provider/story composition in explicit universal-runtime calls — the same
+ * ABI the TSRX compiler emits, but dynamic components stay data. Compiled
+ * components are invoked by the root, never called as plain functions.
+ */
+function storyTree(request: MountRequest, args: Record<string, unknown>) {
+	const component = asComponent(request.component)
+	let tree: unknown = universalComponent(RENDERER, component, args as any)
+	for (const provider of [...request.providers].reverse() as any[]) {
+		const inner = tree
+		tree = universalComponent(RENDERER, asComponent(provider), {
+			fixture: request.fixture,
+			children: universalChildren(RENDERER, () => inner as any),
+		})
+	}
+
+	// The catch body runs inside the render pass — octane rejects store
+	// updates there, so report after the pass commits (same rule as web).
+	return universalTry(
+		() => tree as any,
+		null,
+		(error) => {
+			queueMicrotask(() => request.onRenderError(error))
+			return null
+		},
+	)
+}
+
+/** Universal roots mount compiler-defined components only — the stage root
+ * is a static wrapper; story/props arrive through its props. */
+const StoryTreeRoot = defineUniversalComponent(
+	RENDERER,
+	(p: { request: MountRequest; args: Record<string, unknown> }) => storyTree(p.request, p.args),
+	{ module: '@octane-xplat/workshop/macos-stage' } as any,
+)
+
+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 function createMacOSStageHost(options: MacOSStageOptions): StageHost {
+	return {
+		mount(request: MountRequest): MountedStory {
+			const root = createMacOSRoot(options.view, { fontFamily: options.fontFamily })
+			let disposed = false
+			const bridge = globalThis as any
+			const previousOpen = bridge.__xplatAppKitOpenWindow
+			const previousSheet = bridge.__xplatAppKitMountSheet
+			const windows = new Set<any>()
+			const open = (settings: any = {}) => {
+				if (disposed || request.signal.aborted) {
+					throw new Error('Story generation has retired')
+				}
+
+				if (typeof previousOpen !== 'function') {
+					throw new Error('Consumer AppKit window service is unavailable')
+				}
+
+				const win = previousOpen({
+					...settings,
+					parent: settings.parent ?? options.parentWindow,
+					...(settings.component
+						? {
+								component: StoryTreeRoot,
+								props: {
+									request: { ...request, component: settings.component },
+									args: { ...request.props, ...settings.props },
+								},
+							}
+						: {}),
+				})
+
+				if (!win || typeof win.close !== 'function') {
+					throw new Error(
+						'Consumer AppKit window service must return an owned closeable controller',
+					)
+				}
+
+				windows.add(win)
+				return win
+			}
+
+			const sheet = (component: any, props: any, settings: any) =>
+				open({ ...settings, kind: 'dialog', component, props })
+
+			bridge.__xplatAppKitOpenWindow = open
+			bridge.__xplatAppKitMountSheet = sheet
+			const unmount = () => {
+				if (disposed) {
+					return
+				}
+
+				disposed = true
+				if (bridge.__xplatAppKitOpenWindow === open) {
+					bridge.__xplatAppKitOpenWindow = previousOpen
+				}
+
+				if (bridge.__xplatAppKitMountSheet === sheet) {
+					bridge.__xplatAppKitMountSheet = previousSheet
+				}
+
+				const failures: unknown[] = []
+				for (const win of windows) {
+					try {
+						win.close()
+					} catch (error) {
+						failures.push(error)
+					}
+				}
+
+				windows.clear()
+				try {
+					root.unmount()
+				} catch (error) {
+					failures.push(error)
+				}
+
+				if (failures.length) {
+					throw new AggregateError(failures, 'AppKit story disposal failed')
+				}
+			}
+
+			const render = (args: Record<string, unknown>) =>
+				root.render(
+					StoryTreeRoot as any,
+					{
+						request,
+						args,
+						parentWindow: options.parentWindow,
+					} as any,
+				)
+
+			try {
+				render(request.props)
+			} catch (error: any) {
+				try {
+					unmount()
+				} catch (cleanup) {
+					throw new AggregateError([error, cleanup], 'AppKit mount and rollback failed')
+				}
+
+				throw error
+			}
+
+			return {
+				update(args) {
+					if (!disposed) {
+						render({ ...args })
+					}
+				},
+				unmount,
+			}
+		},
+	}
+}

package/src/macos-node.mjs

@@ -0,0 +1,95 @@
+import { createRequire } from 'node:module'
+import { mkdir, mkdtemp, writeFile, rm } from 'node:fs/promises'
+import { join, relative, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** Generate a separate consumer-owned cache profile; leave app entries untouched. */
+export async function workshopMacOSDev({ root, config, story }) {
+	if (process.platform !== 'darwin' || process.arch !== 'arm64') {
+		throw new Error('The AppKit workshop requires a macOS arm64 execution host')
+	}
+
+	const require = createRequire(join(root, 'package.json'))
+	for (const name of [
+		'@octane-xplat/macos-renderer',
+		'@nativescript/macos-node-api',
+		'octane',
+		'@octanejs/vite-plugin',
+		'vite',
+	]) {
+		try {
+			require.resolve(name)
+		} catch {
+			throw new Error(
+				`AppKit workshop prerequisite missing: ${name}; use the matching versions from your app's macOS setup`,
+			)
+		}
+	}
+
+	const cache = join(root, 'node_modules/.cache/xplat/workshop-macos')
+	await mkdir(cache, { recursive: true })
+	const directory = await mkdtemp(join(cache, 'session-'))
+	const source = dirname(fileURLToPath(import.meta.url))
+	const catalogPlugin = join(source, 'macos-vite.mjs')
+	const shell = join(source, 'macos/shell.macos.mjs')
+	const bundle = join(directory, 'stories.cjs')
+	const shellBundle = join(directory, 'shell.cjs')
+	const catalogFile = join(directory, 'catalog.gen.mjs')
+	const common = `import { xplatMacOS } from '@octane-xplat/cli/macos/vite'
+import { macOSCatalogPlugin } from ${JSON.stringify(catalogPlugin)}
+const root = ${JSON.stringify(root)}
+`
+
+	await writeFile(
+		join(directory, 'stories.config.mjs'),
+		common +
+			`
+export default async ({ mode }) => {
+ const settings = await xplatMacOS(mode, { root, packaged: false, hmr: false })
+ return { ...settings, plugins: [macOSCatalogPlugin({ root, config: ${JSON.stringify(config)}, catalogFile: ${JSON.stringify(catalogFile)} }), ...settings.plugins],
+  build: { ...settings.build, outDir: ${JSON.stringify(directory)}, emptyOutDir: false,
+   lib: { entry: ${JSON.stringify(catalogFile)}, formats: ['cjs'], fileName: () => 'stories.cjs' } } }
+}
+`,
+	)
+
+	await writeFile(
+		join(directory, 'entry.mjs'),
+		`import { startMacOSWorkshop } from ${JSON.stringify(shell)}
+startMacOSWorkshop({ bundleFile: ${JSON.stringify(bundle)}, initialStoryId: ${JSON.stringify(story ?? null)},
+ offscreen: process.env.OCTANE_WORKSHOP_OFFSCREEN === '1' })
+`,
+	)
+
+	await writeFile(
+		join(directory, 'shell.config.mjs'),
+		common +
+			`
+export default async ({ mode }) => {
+ const settings = await xplatMacOS(mode, { root, packaged: true, entry: ${JSON.stringify(join(directory, 'entry.mjs'))} })
+ return { ...settings, build: { ...settings.build, outDir: ${JSON.stringify(directory)}, emptyOutDir: false,
+  lib: { entry: ${JSON.stringify(join(directory, 'entry.mjs'))}, formats: ['cjs'], fileName: () => 'shell.cjs' } } }
+}
+`,
+	)
+
+	try {
+		const { runMacOSDev } = await import('@octane-xplat/cli/macos')
+		return await runMacOSDev(root, {
+			workshop: true,
+			target: {
+				runtime: 'appkit-node-api',
+				renderer: 'appkit',
+				dev: {
+					productName: 'Octane component workshop',
+					viteConfig: relative(root, join(directory, 'stories.config.mjs')),
+					bundleFile: relative(root, bundle),
+					shellViteConfig: relative(root, join(directory, 'shell.config.mjs')),
+					shellBundleFile: relative(root, shellBundle),
+				},
+			},
+		})
+	} finally {
+		await rm(directory, { recursive: true, force: true })
+	}
+}

package/src/macos-vite.mjs

@@ -0,0 +1,47 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { discoverStories } from './discover.mjs'
+
+/**
+ * Regenerates the real catalog module on every (re)build. Static applicability
+ * is resolved before any platform leaf enters the bundle — incompatible leaves
+ * keep a catalog entry but never a `load` import.
+ */
+export function macOSCatalogPlugin({ root, config = {}, catalogFile }) {
+	const generate = (ctx) => {
+		const { entries, diagnostics } = discoverStories(root, { ...config.stories, target: 'macos' })
+		for (const entry of entries) {
+			ctx?.addWatchFile?.(entry.file)
+		}
+
+		const providers = (config.providerModules ?? []).map(
+			(file, i) => `import * as preset${i} from ${JSON.stringify(resolve(root, file))}`,
+		)
+
+		const catalog = entries.map(
+			(entry) => `{
+			...${JSON.stringify(entry)},
+			${entry.applicable ? `load: () => import(${JSON.stringify(entry.file)})` : ''}
+		}`,
+		)
+
+		const next = `${providers.join('\n')}
+export const catalog = [${catalog.join(',\n')}]
+export const diagnostics = ${JSON.stringify(diagnostics)}
+export const providers = [${(config.providerModules ?? []).map((_, i) => `...(preset${i}.providers ?? preset${i}.default ?? [])`).join(',')}]
+`
+
+		// Same-content regeneration must not retrigger the watcher.
+		if (!existsSync(catalogFile) || readFileSync(catalogFile, 'utf8') !== next) {
+			writeFileSync(catalogFile, next)
+		}
+	}
+
+	return {
+		name: 'xplat-workshop-macos-catalog',
+		buildStart() {
+			// Runs on every rebuild; story modules stay lazily imported.
+			generate.call(this)
+		},
+	}
+}

package/src/mobile/controller.ts

@@ -0,0 +1,134 @@
+import type { CatalogEntry } from '../catalog'
+import type { StoryDefinition } from '../contract'
+import { WorkshopSession } from '../session'
+import { applyControlInput, type ControlValueInput } from '../controls'
+
+/** Window geometry changes shell presentation only, never the story root. */
+export function mobileShellMode(width: number, height: number): 'wide' | 'compact' | 'phone' {
+	if (width >= 1000 && height >= 500) {
+		return 'wide'
+	}
+
+	return width <= 600 ? 'phone' : 'compact'
+}
+
+export class MobileController {
+	selectedId: string | null = null
+	catalog: readonly CatalogEntry[]
+	query = ''
+	panel: 'stories' | 'controls' | null = null
+	stageOnly = false
+	missingId: string | null = null
+	private generation = 0
+	private disposed = false
+
+	constructor(
+		readonly session: WorkshopSession,
+		catalog: readonly CatalogEntry[],
+		readonly changed: () => void,
+	) {
+		this.catalog = catalog
+	}
+
+	async select(id: string, revision?: string): Promise<void> {
+		if (this.disposed) {
+			return
+		}
+
+		const generation = ++this.generation
+		this.selectedId = id
+		this.panel = null
+		const entry = this.catalog.find((item) => item.id === id)
+		this.missingId = entry ? null : id
+		this.changed()
+		// Filtering is enforced again at the runtime boundary, before load.
+		if (!entry?.applicable || !entry.load) {
+			await this.session.dispose()
+			return
+		}
+
+		try {
+			if (revision) {
+				this.session.markRebuilding()
+			}
+
+			const module = (await entry.load(revision)) as Record<string, unknown>
+			if (generation !== this.generation || this.disposed) {
+				return
+			}
+
+			const story = module[entry.exportName] as StoryDefinition<any, any, any>
+			if (!story || story.id !== entry.id) {
+				throw new Error(`Story export ${entry.exportName} does not match ${entry.id}`)
+			}
+
+			if (revision) {
+				await this.session.reload(story)
+			} else {
+				await this.session.select(story)
+			}
+		} catch (error) {
+			if (generation === this.generation) {
+				this.session.markCompileError(error)
+			}
+		}
+	}
+
+	updateCatalog(
+		catalog: readonly CatalogEntry[],
+		diagnostics: readonly { message: string }[] = [],
+	): void {
+		if (this.disposed) {
+			return
+		}
+
+		++this.generation
+		this.catalog = catalog
+		this.changed()
+		if (diagnostics.length) {
+			this.session.markCompileError(diagnostics.map((d) => d.message).join('\n'))
+		} else if (this.selectedId) {
+			void this.select(this.selectedId, String(Date.now()))
+		}
+	}
+
+	/**
+	 * 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 {
+		if (this.panel) {
+			this.panel = null
+			return 'panel'
+		}
+
+		if (this.stageOnly) {
+			this.stageOnly = false
+			return 'stage-only'
+		}
+
+		return null
+	}
+
+	control(key: string, value: ControlValueInput): string | undefined {
+		const story = this.session.currentStory
+		if (!story || this.session.state.phase !== 'ready') {
+			return 'Wait for the story to be ready'
+		}
+
+		const result = applyControlInput(story, this.session.currentProps ?? {}, key, value)
+		if (result.props) {
+			this.session.applyProps(result.props)
+		}
+
+		return result.error?.message
+	}
+
+	async dispose(): Promise<void> {
+		this.disposed = true
+		++this.generation
+		await this.session.dispose()
+	}
+}