@octane-xplat/workshop 0.1.0 → 0.16.0

package/dist/build/vite.js

@@ -0,0 +1,230 @@
+import { discoverStories, normalizeInclude } from "./discover.js";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region src/build/vite.ts
+/**
+* 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.
+*/
+var CATALOG_ID = "\0xplat-workshop-catalog";
+var ENTRY_ID = "\0xplat-workshop-entry";
+var STORY_FILE_RE = /\.stories(?:\.(?:web|mobile|ios|android|macos|windows|linux))?\.(?:[cm]?[jt]s|[jt]sx|[jt]srx)$/;
+var TARGET_RESOLUTION = {
+	web: {
+		conditions: ["web"],
+		extensions: [
+			".web.tsrx",
+			".tsrx",
+			".web.tsx",
+			".tsx",
+			".web.ts",
+			".ts",
+			".mts",
+			".ts",
+			".jsx",
+			".js",
+			".json"
+		]
+	},
+	linux: {
+		conditions: ["linux", "web"],
+		extensions: [
+			".linux.tsrx",
+			".web.tsrx",
+			".tsrx",
+			".linux.tsx",
+			".web.tsx",
+			".tsx",
+			".linux.ts",
+			".web.ts",
+			".ts",
+			".mts",
+			".ts",
+			".jsx",
+			".js",
+			".json"
+		]
+	}
+};
+var 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,
+})
+`;
+}
+var 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
+*/
+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 ?? {};
+	return [{
+		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;
+		}
+	}, {
+		name: "xplat-workshop-shell",
+		config() {
+			return {
+				optimizeDeps: {
+					exclude: ["@octane-xplat/workshop"],
+					include: ["@octane-xplat/workshop > storybook/preview-api"]
+				},
+				resolve: { conditions: [...resolution.conditions] }
+			};
+		},
+		configResolved(resolved) {
+			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: {
+			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);
+				return [catalog];
+			}
+		},
+		configureServer(s) {
+			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();
+			});
+		}
+	}];
+}
+function serveAsset(config, root, url, res, next) {
+	const assets = config?.assets ?? {};
+	const rest = url.slice(18);
+	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));
+}
+//#endregion
+export { xplatWorkshop };

package/dist/build/windows/preflight.js

@@ -0,0 +1,83 @@
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+//#region src/build/windows/preflight.ts
+/** Read-only Windows setup evidence. Prerequisites never qualify a host. */
+function commandOutput(command, args) {
+	try {
+		return execFileSync(command, args, {
+			encoding: "utf8",
+			timeout: 5e3,
+			maxBuffer: 65536,
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			],
+			windowsHide: true
+		}).trim();
+	} catch {
+		return null;
+	}
+}
+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 {}
+		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);
+	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;
+		requirements["Developer Mode (development launch)"] = run("powershell", [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			"(Get-ItemProperty \"HKLM:\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\AppModelUnlock\" -Name AllowDevelopmentWithoutDevLicense -ErrorAction SilentlyContinue).AllowDevelopmentWithoutDevLicense"
+		])?.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."
+	};
+}
+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.";
+}
+//#endregion
+export { windowsLaunchBlocker, windowsPreflight };

package/dist/contract.js

@@ -0,0 +1,50 @@
+//#region src/contract.ts
+var WORKSHOP_TARGETS = [
+	"web",
+	"ios",
+	"android",
+	"macos",
+	"windows",
+	"linux"
+];
+/** Version of the authoring contract — bumped on breaking changes. */
+var WORKSHOP_CONTRACT_VERSION = 1;
+/** Declare a story. Validates cheap authoring rules eagerly. */
+function defineStory(definition) {
+	assertLiteralAuthoring(definition);
+	return definition;
+}
+function assertLiteralAuthoring(definition) {
+	const fail = (message) => {
+		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;
+	if (!(targets === "all" || Array.isArray(targets) && targets.length > 0 && targets.every((t) => WORKSHOP_TARGETS.includes(t)))) 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"]) 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.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.options)) fail(`story "${definition.id}" — enum control "${key}" requires an options array`);
+		if (type === "number" && typeof control.min === "number" && typeof control.max === "number" && control.min > control.max) fail(`story "${definition.id}" — number control "${key}" has min > max`);
+	}
+	if (definition.providers !== void 0 && !Array.isArray(definition.providers)) fail(`story "${definition.id}" — providers must be an array`);
+}
+function defineWorkshopConfig(config) {
+	return config;
+}
+//#endregion
+export { WORKSHOP_CONTRACT_VERSION, WORKSHOP_TARGETS, defineStory, defineWorkshopConfig };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { WORKSHOP_CONTRACT_VERSION, WORKSHOP_TARGETS, defineStory, defineWorkshopConfig } from "./contract.js";
+export { WORKSHOP_CONTRACT_VERSION, WORKSHOP_TARGETS, defineStory, defineWorkshopConfig };

package/package.json

@@ -1,7 +1,18 @@
 {
   "name": "@octane-xplat/workshop",
-  "version": "0.1.0",
-  "description": "Bootstrap placeholder. No supported API; automated releases will supply the implementation.",
+  "version": "0.16.0",
+  "description": "Development-only component workshop for Octane Xplat — typed stories, metadata discovery, adaptive shell, lifecycle and warm reload",
+  "keywords": [
+    "components",
+    "cross-platform",
+    "dev-tools",
+    "octane",
+    "stories",
+    "storybook",
+    "workshop",
+    "xplat"
+  ],
+  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/workshop",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -9,6 +20,108 @@
     "directory": "packages/workshop"
   },
   "files": [
-    "README.md"
-  ]
-}
+    "types",
+    "dist",
+    "src",
+    "MOBILE.md",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types/generated/index.d.ts",
+      "node": "./dist/index.js",
+      "default": "./src/index.ts"
+    },
+    "./web": {
+      "types": "./types/generated/web/index.web.d.ts",
+      "default": "./src/web/index.web.ts"
+    },
+    "./vite": {
+      "types": "./src/build/vite.d.ts",
+      "default": "./dist/build/vite.js"
+    },
+    "./node": {
+      "types": "./src/build/node.d.ts",
+      "default": "./dist/build/node.js"
+    },
+    "./package.json": "./package.json",
+    "./mobile": {
+      "types": "./types/generated/mobile/index.mobile.d.ts",
+      "default": "./src/mobile/index.mobile.ts"
+    },
+    "./vite-mobile": {
+      "types": "./src/build/vite-mobile.d.ts",
+      "default": "./dist/build/vite-mobile.js"
+    },
+    "./macos": {
+      "types": "./types/generated/macos/index.macos.d.ts",
+      "default": "./src/macos/index.macos.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@babel/core": "7.29.7",
+    "@babel/plugin-transform-unicode-property-regex": "7.29.7",
+    "@octane-xplat/cli": "0.16.0",
+    "@octane-xplat/platform": "0.16.0",
+    "@octane-xplat/ui": "0.16.0",
+    "storybook": "10.6.1",
+    "tinyglobby": "0.2.17"
+  },
+  "devDependencies": {
+    "@nativescript-community/octane": "0.2.5",
+    "@nativescript/core": "9.1.3",
+    "@nativescript/macos-node-api": "0.4.4-next.2026-08-09-31292056208",
+    "@nativescript/types": "9.1.4",
+    "@octane-xplat/macos-renderer": "0.16.0",
+    "@octanejs/vite-plugin": "0.1.61",
+    "octane": "0.11.0",
+    "tsrx-typegen": "0.3.1",
+    "typescript": "5.9.3",
+    "vite": "8.3.0"
+  },
+  "peerDependencies": {
+    "@nativescript-community/octane": ">=0.2.4 <1",
+    "@nativescript/core": ">=9.1.3 <10",
+    "@nativescript/macos-node-api": "0.4.4-next.2026-08-09-31292056208",
+    "@octane-xplat/macos-renderer": ">=0.14.0 <1",
+    "@octanejs/vite-plugin": ">=0.1.61",
+    "octane": ">=0.6.3 <1",
+    "vite": ">=8"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    },
+    "@nativescript/core": {
+      "optional": true
+    },
+    "@nativescript-community/octane": {
+      "optional": true
+    },
+    "@octane-xplat/macos-renderer": {
+      "optional": true
+    },
+    "@nativescript/macos-node-api": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "typegen": "tsrx-typegen --target workshop",
+    "typecheck": "node ../../scripts/typecheck.ts",
+    "test": "vitest run && tsrx-tsc --noEmit -p tsconfig.test.json",
+    "test:e2e": "pnpm --filter @xplat/workshop-demo test:e2e",
+    "test:packed": "pnpm build && node tests/packed-consumer.web.mjs",
+    "test:packed:linux": "node tests/packed-consumer.linux.mjs",
+    "test:packed:macos": "node tests/packed-consumer.macos.mjs",
+    "test:packed:windows": "node tests/packed-windows-preflight.mjs",
+    "pack:check": "tsrx-typegen --pack-check",
+    "test:types": "tsrx-tsc --noEmit -p tsconfig.test.json",
+    "test:packed:mobile": "node tests/packed-consumer.mobile.mjs",
+    "build": "vite build"
+  }
+}