@fluid-app/fluid-cli-widget 0.1.26 → 0.1.28

package/dist/vite/plugin.mjs

@@ -1,14 +1,15 @@
-import { validateSingleSourceWidgetPackage } from "@fluid-app/fluid-cli-portal";
+import { i as createWidgetPackageDevelopmentDescriptor } from "../src-CVadzcYM.mjs";
 //#region src/vite/plugin.ts
 function fluidWidgetDevPlugin() {
 	return {
 		name: "fluid-widget-dev-routes",
 		apply: "serve",
+		config: createWidgetDevServerConfig,
 		configureServer(server) {
 			server.middlewares.use(async (request, response, next) => {
 				const pathname = (request.url ?? "").split("?")[0] ?? "";
 				if (pathname === "/__runtime-entry__" || pathname === "/__runtime-entry__/") {
-					sendJavaScript(request, response, "void import(\"/src/index.ts\");\n");
+					sendJavaScript(request, response, buildRuntimeEntryBootstrapScript(WIDGET_ENTRY_MODULE_PATH, getRequestOrigin(request)));
 					return;
 				}
 				if (pathname === "/__widget-packages__" || pathname === "/__widget-packages__/") {
@@ -20,24 +21,127 @@ function fluidWidgetDevPlugin() {
 		}
 	};
 }
-function createDevWidgetPackageDescriptors(configModule, origin) {
-	const validation = validateSingleSourceWidgetPackage(readSourcePackages(configModule), { owner: "droplet" });
-	if (!validation.success || !validation.value) throw new Error(validation.errors.map((error) => error.message).join("\n") || "Widget package validation failed.");
-	return [validatedPackageToDescriptor(validation.value, origin)];
+/**
+* Widget projects intentionally have no HTML entrypoint, so Vite cannot
+* discover the worker's dependency graph during its normal startup scan.
+* Without an explicit entry, the first live-preview request discovers and
+* optimizes the portal worker after the server reports ready. Vite reloads
+* the worker mid-mount, closing its message thread and stranding the preview
+* in a permanent error state.
+*
+* Pre-optimizing the worker entry makes the initial graph stable before a
+* preview can connect. Vite follows this entry's imports, so React and the
+* Remote DOM worker runtime are optimized in the same startup pass.
+*/
+function createWidgetDevServerConfig() {
+	return { optimizeDeps: { include: ["@fluid-app/portal-sdk/widgets/worker"] } };
 }
-function validatedPackageToDescriptor(validated, origin) {
-	const cssUrls = validated.sourcePackage.cssUrls ?? [];
-	return {
-		manifestVersion: 1,
-		runtime: "remote-dom",
-		packageId: validated.packageId,
-		source: validated.owner,
-		version: validated.version,
-		workerEntryUrl: new URL("/__runtime-entry__", origin).href,
-		cssUrls: cssUrls.length > 0 ? cssUrls.map((url) => new URL(url, origin).href) : [new URL("/styles.css", origin).href],
-		assetUrls: [],
-		widgets: validated.widgets.map(({ name: _name, ...widget }) => widget)
-	};
+/** Source-relative path of a widget project's entry module. The dev
+*  scaffold always places it here (see the widget template) — this is
+*  the one thing the bootstrap script below needs from the plugin
+*  that isn't itself part of the race/preamble fix. */
+const WIDGET_ENTRY_MODULE_PATH = "/src/index.ts";
+/**
+* Builds the `/__runtime-entry__` worker bootstrap. Runtime-verified
+* against a real widget dev server + `@fluid-app/widget-runtime` host
+* in a Playwright harness (styled Leaderboard widget rendering,
+* mutation records flowing, `mounted.ready` resolving) — every piece
+* below exists to fix something that reproduced in that harness:
+*
+* 1. **Message-buffer race (the silent-mount killer).** The host
+*    (widget-runtime) posts the "mount" message immediately after
+*    `new Worker(...)`. A production-built worker bundle evaluates
+*    synchronously and never races that message. In dev, though, the
+*    worker's module graph loads asynchronously over many HTTP
+*    requests (this bootstrap script, then the entry module, then
+*    everything it imports, each a separate fetch) — so the "mount"
+*    message can be dispatched and consumed by the Worker's default
+*    (listener-less) handling before the widget entry's own
+*    `message` listener, wired up deep inside the awaited import
+*    below, is ever attached. The message is dropped silently, with
+*    no error anywhere — the old `void import("/src/index.ts")` also
+*    swallowed the import's own rejections, compounding the silence.
+*    Traced live: host→worker "mount" posts, zero worker→host replies
+*    until this buffer-and-replay was added; after it, mutation
+*    records flow and `mounted.ready` resolves. Fix: buffer every
+*    message from the instant the worker boots (before anything else
+*    runs), then replay the buffer, in order, once the entry module
+*    has finished importing and has had the chance to attach its
+*    real listener.
+* 2. **React-refresh preamble.** `@vitejs/plugin-react` injects a
+*    preamble into every dev-transformed `.tsx` module referencing
+*    `window.$RefreshReg$` / `$RefreshSig$`. A Worker global scope has
+*    no `window` and no preamble, so importing a react-based widget
+*    entry throws `window is not defined`, and — once `window` is
+*    aliased to `globalThis` — throws again on the bare
+*    `$RefreshSig$` alias. Installing the canonical preamble
+*    (`RefreshRuntime.injectIntoGlobalHook` + no-op `$RefreshReg$` /
+*    `$RefreshSig$`) before the entry import fixes both. The
+*    `window = globalThis` alias was checked against widget-runtime's
+*    worker lockdown / scope detection (which is
+*    `globalThis.postMessage`-based) — no conflict. `/@react-refresh`
+*    is `@vitejs/plugin-react`'s stable virtual module id, but a
+*    widget project isn't guaranteed to use the react plugin, so the
+*    whole block is try/catch-guarded — a project with no
+*    `/@react-refresh` module (no react plugin) boots straight
+*    through to the entry import unaffected.
+* 3. **`await import`, not `void import`.** A genuine failure to
+*    import the entry module (syntax error, missing dependency, …)
+*    must reject the worker's module evaluation loudly, not vanish
+*    the way a fire-and-forget `void import` did.
+* 4. **Absolute dev-server imports.** Mist and portal previews load the
+*    worker from another origin, so the host wraps this entry in a blob URL.
+*    Root-relative specifiers inside a blob module resolve against the host
+*    page (or fail to resolve at all), not this Vite server. Anchoring both
+*    imports to the request origin keeps the entire dev module graph on the
+*    widget server.
+*
+* Dev-only: this only ever serves from `configureServer` (the
+* plugin's `apply: "serve"` gate), never a built/published package.
+*/
+function buildRuntimeEntryBootstrapScript(entryPath, origin) {
+	const refreshRuntimeUrl = new URL("/@react-refresh", origin).toString();
+	const entryUrl = new URL(entryPath, origin).toString();
+	return [
+		"// Dev-only worker bootstrap — see buildRuntimeEntryBootstrapScript",
+		"// in packages/cli/widget/src/vite/plugin.ts for why each piece",
+		"// here exists (message-buffer race, react-refresh preamble,",
+		"// await-not-void import).",
+		"const __q = [];",
+		"const __buf = (e) => { __q.push(e.data); };",
+		"self.addEventListener(\"message\", __buf);",
+		"if (typeof window === \"undefined\") { globalThis.window = globalThis; }",
+		"try {",
+		`  const { default: RefreshRuntime } = await import(${JSON.stringify(refreshRuntimeUrl)});`,
+		"  RefreshRuntime.injectIntoGlobalHook(window);",
+		"  window.$RefreshReg$ = () => {};",
+		"  window.$RefreshSig$ = () => (type) => type;",
+		"  window.__vite_plugin_react_preamble_installed__ = true;",
+		"} catch {",
+		"  // No @vitejs/plugin-react in this widget project (no",
+		"  // /@react-refresh virtual module) — nothing to preinstall.",
+		"}",
+		`await import(${JSON.stringify(entryUrl)});`,
+		"self.removeEventListener(\"message\", __buf);",
+		"for (const data of __q) {",
+		"  self.dispatchEvent(new MessageEvent(\"message\", { data }));",
+		"}",
+		""
+	].join("\n");
+}
+/**
+* The shared development descriptor workflow appends Vite's `?direct` query
+* to CSS URLs so preview hosts receive real CSS instead of JS style modules.
+* Published descriptors use a separate build path and never receive it.
+*/
+function createDevWidgetPackageDescriptors(configModule, origin) {
+	return [createWidgetPackageDevelopmentDescriptor({
+		sourceModule: configModule,
+		owner: "droplet",
+		origin,
+		workerEntryPath: "/__runtime-entry__",
+		defaultCssPath: "/styles.css"
+	})];
 }
 async function sendWidgetPackages(server, request, response) {
 	if (handleOptions(request, response)) return;
@@ -48,12 +152,6 @@ async function sendWidgetPackages(server, request, response) {
 		sendJson(response, { error: String(error) }, 500);
 	}
 }
-function readSourcePackages(configModule) {
-	const packages = configModule["widgetPackages"];
-	if (Array.isArray(packages) && packages.length > 0) return packages;
-	const widgetPackage = configModule["widgetPackage"];
-	return widgetPackage === void 0 ? [] : [widgetPackage];
-}
 function sendJavaScript(request, response, source) {
 	if (handleOptions(request, response)) return;
 	setCorsHeaders(response);
@@ -89,6 +187,6 @@ function readHeader(value) {
 	return typeof candidate === "string" && candidate.trim().length > 0 ? candidate.trim() : void 0;
 }
 //#endregion
-export { createDevWidgetPackageDescriptors, fluidWidgetDevPlugin };
+export { buildRuntimeEntryBootstrapScript, createDevWidgetPackageDescriptors, createWidgetDevServerConfig, fluidWidgetDevPlugin };
 
 //# sourceMappingURL=plugin.mjs.map

package/dist/vite/plugin.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.mjs","names":[],"sources":["../../src/vite/plugin.ts"],"sourcesContent":["import type { IncomingMessage, ServerResponse } from \"node:http\";\nimport {\n  validateSingleSourceWidgetPackage,\n  type RemoteDomWidgetPackageDescriptor,\n  type ValidatedWidgetPackageBuild,\n} from \"@fluid-app/fluid-cli-portal\";\nimport type { Plugin, ViteDevServer } from \"vite\";\n\nexport function fluidWidgetDevPlugin(): Plugin {\n  return {\n    name: \"fluid-widget-dev-routes\",\n    apply: \"serve\",\n    configureServer(server) {\n      server.middlewares.use(async (request, response, next): Promise<void> => {\n        const pathname = (request.url ?? \"\").split(\"?\")[0] ?? \"\";\n\n        if (\n          pathname === \"/__runtime-entry__\" ||\n          pathname === \"/__runtime-entry__/\"\n        ) {\n          sendJavaScript(request, response, 'void import(\"/src/index.ts\");\\n');\n          return;\n        }\n\n        if (\n          pathname === \"/__widget-packages__\" ||\n          pathname === \"/__widget-packages__/\"\n        ) {\n          await sendWidgetPackages(server, request, response);\n          return;\n        }\n\n        next();\n      });\n    },\n  };\n}\n\nexport function createDevWidgetPackageDescriptors(\n  configModule: Readonly<Record<string, unknown>>,\n  origin: string,\n): readonly RemoteDomWidgetPackageDescriptor[] {\n  const validation = validateSingleSourceWidgetPackage(\n    readSourcePackages(configModule),\n    { owner: \"droplet\" },\n  );\n  if (!validation.success || !validation.value) {\n    throw new Error(\n      validation.errors.map((error) => error.message).join(\"\\n\") ||\n        \"Widget package validation failed.\",\n    );\n  }\n\n  return [validatedPackageToDescriptor(validation.value, origin)];\n}\n\nfunction validatedPackageToDescriptor(\n  validated: ValidatedWidgetPackageBuild,\n  origin: string,\n): RemoteDomWidgetPackageDescriptor {\n  const cssUrls = validated.sourcePackage.cssUrls ?? [];\n  return {\n    manifestVersion: 1,\n    runtime: \"remote-dom\",\n    packageId: validated.packageId,\n    source: validated.owner,\n    version: validated.version,\n    workerEntryUrl: new URL(\"/__runtime-entry__\", origin).href,\n    cssUrls:\n      cssUrls.length > 0\n        ? cssUrls.map((url) => new URL(url, origin).href)\n        : [new URL(\"/styles.css\", origin).href],\n    assetUrls: [],\n    widgets: validated.widgets.map(({ name: _name, ...widget }) => widget),\n  };\n}\n\nasync function sendWidgetPackages(\n  server: ViteDevServer,\n  request: IncomingMessage,\n  response: ServerResponse,\n): Promise<void> {\n  if (handleOptions(request, response)) return;\n\n  try {\n    const configModule = (await server.ssrLoadModule(\n      \"/fluid.widget.config.ts\",\n    )) as Record<string, unknown>;\n    sendJson(\n      response,\n      createDevWidgetPackageDescriptors(\n        configModule,\n        getRequestOrigin(request),\n      ),\n    );\n  } catch (error) {\n    server.config.logger.error(\n      `[fluid] Failed to load widget packages: ${String(error)}`,\n    );\n    sendJson(response, { error: String(error) }, 500);\n  }\n}\n\nfunction readSourcePackages(\n  configModule: Readonly<Record<string, unknown>>,\n): readonly unknown[] {\n  const packages = configModule[\"widgetPackages\"];\n  if (Array.isArray(packages) && packages.length > 0) return packages;\n\n  const widgetPackage = configModule[\"widgetPackage\"];\n  return widgetPackage === undefined ? [] : [widgetPackage];\n}\n\nfunction sendJavaScript(\n  request: IncomingMessage,\n  response: ServerResponse,\n  source: string,\n): void {\n  if (handleOptions(request, response)) return;\n  setCorsHeaders(response);\n  response.setHeader(\"Content-Type\", \"text/javascript\");\n  response.statusCode = 200;\n  response.end(source);\n}\n\nfunction sendJson(\n  response: ServerResponse,\n  body: unknown,\n  statusCode = 200,\n): void {\n  setCorsHeaders(response);\n  response.setHeader(\"Content-Type\", \"application/json\");\n  response.statusCode = statusCode;\n  response.end(JSON.stringify(body, null, 2));\n}\n\nfunction handleOptions(\n  request: IncomingMessage,\n  response: ServerResponse,\n): boolean {\n  if (request.method !== \"OPTIONS\") return false;\n  setCorsHeaders(response);\n  response.statusCode = 204;\n  response.end();\n  return true;\n}\n\nfunction setCorsHeaders(response: ServerResponse): void {\n  response.setHeader(\"Access-Control-Allow-Origin\", \"*\");\n  response.setHeader(\"Access-Control-Allow-Methods\", \"GET, HEAD, OPTIONS\");\n  response.setHeader(\n    \"Access-Control-Allow-Headers\",\n    \"Content-Type, Authorization\",\n  );\n}\n\nfunction getRequestOrigin(request: IncomingMessage): string {\n  const host = readHeader(request.headers.host);\n  if (!host) throw new Error(\"Widget dev request is missing the Host header.\");\n\n  const forwardedProtocol = readHeader(request.headers[\"x-forwarded-proto\"]);\n  const protocol = forwardedProtocol === \"https\" ? \"https\" : \"http\";\n  return `${protocol}://${host}`;\n}\n\nfunction readHeader(\n  value: string | readonly string[] | undefined,\n): string | undefined {\n  const candidate = Array.isArray(value) ? value[0] : value;\n  return typeof candidate === \"string\" && candidate.trim().length > 0\n    ? candidate.trim()\n    : undefined;\n}\n"],"mappings":"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"}
+{"version":3,"file":"plugin.mjs","names":[],"sources":["../../src/vite/plugin.ts"],"sourcesContent":["import type { IncomingMessage, ServerResponse } from \"node:http\";\nimport {\n  createWidgetPackageDevelopmentDescriptor,\n  type RemoteDomWidgetPackageDescriptor,\n} from \"@fluid-app/fluid-cli-widget-tooling\";\nimport type { Plugin, UserConfig, ViteDevServer } from \"vite\";\n\nexport function fluidWidgetDevPlugin(): Plugin {\n  return {\n    name: \"fluid-widget-dev-routes\",\n    apply: \"serve\",\n    config: createWidgetDevServerConfig,\n    configureServer(server) {\n      server.middlewares.use(async (request, response, next): Promise<void> => {\n        const pathname = (request.url ?? \"\").split(\"?\")[0] ?? \"\";\n\n        if (\n          pathname === \"/__runtime-entry__\" ||\n          pathname === \"/__runtime-entry__/\"\n        ) {\n          sendJavaScript(\n            request,\n            response,\n            buildRuntimeEntryBootstrapScript(\n              WIDGET_ENTRY_MODULE_PATH,\n              getRequestOrigin(request),\n            ),\n          );\n          return;\n        }\n\n        if (\n          pathname === \"/__widget-packages__\" ||\n          pathname === \"/__widget-packages__/\"\n        ) {\n          await sendWidgetPackages(server, request, response);\n          return;\n        }\n\n        next();\n      });\n    },\n  };\n}\n\n/**\n * Widget projects intentionally have no HTML entrypoint, so Vite cannot\n * discover the worker's dependency graph during its normal startup scan.\n * Without an explicit entry, the first live-preview request discovers and\n * optimizes the portal worker after the server reports ready. Vite reloads\n * the worker mid-mount, closing its message thread and stranding the preview\n * in a permanent error state.\n *\n * Pre-optimizing the worker entry makes the initial graph stable before a\n * preview can connect. Vite follows this entry's imports, so React and the\n * Remote DOM worker runtime are optimized in the same startup pass.\n */\nexport function createWidgetDevServerConfig(): UserConfig {\n  return {\n    optimizeDeps: {\n      include: [\"@fluid-app/portal-sdk/widgets/worker\"],\n    },\n  };\n}\n\n/** Source-relative path of a widget project's entry module. The dev\n *  scaffold always places it here (see the widget template) — this is\n *  the one thing the bootstrap script below needs from the plugin\n *  that isn't itself part of the race/preamble fix. */\nconst WIDGET_ENTRY_MODULE_PATH = \"/src/index.ts\";\n\n/**\n * Builds the `/__runtime-entry__` worker bootstrap. Runtime-verified\n * against a real widget dev server + `@fluid-app/widget-runtime` host\n * in a Playwright harness (styled Leaderboard widget rendering,\n * mutation records flowing, `mounted.ready` resolving) — every piece\n * below exists to fix something that reproduced in that harness:\n *\n * 1. **Message-buffer race (the silent-mount killer).** The host\n *    (widget-runtime) posts the \"mount\" message immediately after\n *    `new Worker(...)`. A production-built worker bundle evaluates\n *    synchronously and never races that message. In dev, though, the\n *    worker's module graph loads asynchronously over many HTTP\n *    requests (this bootstrap script, then the entry module, then\n *    everything it imports, each a separate fetch) — so the \"mount\"\n *    message can be dispatched and consumed by the Worker's default\n *    (listener-less) handling before the widget entry's own\n *    `message` listener, wired up deep inside the awaited import\n *    below, is ever attached. The message is dropped silently, with\n *    no error anywhere — the old `void import(\"/src/index.ts\")` also\n *    swallowed the import's own rejections, compounding the silence.\n *    Traced live: host→worker \"mount\" posts, zero worker→host replies\n *    until this buffer-and-replay was added; after it, mutation\n *    records flow and `mounted.ready` resolves. Fix: buffer every\n *    message from the instant the worker boots (before anything else\n *    runs), then replay the buffer, in order, once the entry module\n *    has finished importing and has had the chance to attach its\n *    real listener.\n * 2. **React-refresh preamble.** `@vitejs/plugin-react` injects a\n *    preamble into every dev-transformed `.tsx` module referencing\n *    `window.$RefreshReg$` / `$RefreshSig$`. A Worker global scope has\n *    no `window` and no preamble, so importing a react-based widget\n *    entry throws `window is not defined`, and — once `window` is\n *    aliased to `globalThis` — throws again on the bare\n *    `$RefreshSig$` alias. Installing the canonical preamble\n *    (`RefreshRuntime.injectIntoGlobalHook` + no-op `$RefreshReg$` /\n *    `$RefreshSig$`) before the entry import fixes both. The\n *    `window = globalThis` alias was checked against widget-runtime's\n *    worker lockdown / scope detection (which is\n *    `globalThis.postMessage`-based) — no conflict. `/@react-refresh`\n *    is `@vitejs/plugin-react`'s stable virtual module id, but a\n *    widget project isn't guaranteed to use the react plugin, so the\n *    whole block is try/catch-guarded — a project with no\n *    `/@react-refresh` module (no react plugin) boots straight\n *    through to the entry import unaffected.\n * 3. **`await import`, not `void import`.** A genuine failure to\n *    import the entry module (syntax error, missing dependency, …)\n *    must reject the worker's module evaluation loudly, not vanish\n *    the way a fire-and-forget `void import` did.\n * 4. **Absolute dev-server imports.** Mist and portal previews load the\n *    worker from another origin, so the host wraps this entry in a blob URL.\n *    Root-relative specifiers inside a blob module resolve against the host\n *    page (or fail to resolve at all), not this Vite server. Anchoring both\n *    imports to the request origin keeps the entire dev module graph on the\n *    widget server.\n *\n * Dev-only: this only ever serves from `configureServer` (the\n * plugin's `apply: \"serve\"` gate), never a built/published package.\n */\nexport function buildRuntimeEntryBootstrapScript(\n  entryPath: string,\n  origin: string,\n): string {\n  const refreshRuntimeUrl = new URL(\"/@react-refresh\", origin).toString();\n  const entryUrl = new URL(entryPath, origin).toString();\n\n  return [\n    \"// Dev-only worker bootstrap — see buildRuntimeEntryBootstrapScript\",\n    \"// in packages/cli/widget/src/vite/plugin.ts for why each piece\",\n    \"// here exists (message-buffer race, react-refresh preamble,\",\n    \"// await-not-void import).\",\n    \"const __q = [];\",\n    \"const __buf = (e) => { __q.push(e.data); };\",\n    'self.addEventListener(\"message\", __buf);',\n    'if (typeof window === \"undefined\") { globalThis.window = globalThis; }',\n    \"try {\",\n    `  const { default: RefreshRuntime } = await import(${JSON.stringify(refreshRuntimeUrl)});`,\n    \"  RefreshRuntime.injectIntoGlobalHook(window);\",\n    \"  window.$RefreshReg$ = () => {};\",\n    \"  window.$RefreshSig$ = () => (type) => type;\",\n    \"  window.__vite_plugin_react_preamble_installed__ = true;\",\n    \"} catch {\",\n    \"  // No @vitejs/plugin-react in this widget project (no\",\n    \"  // /@react-refresh virtual module) — nothing to preinstall.\",\n    \"}\",\n    `await import(${JSON.stringify(entryUrl)});`,\n    'self.removeEventListener(\"message\", __buf);',\n    \"for (const data of __q) {\",\n    '  self.dispatchEvent(new MessageEvent(\"message\", { data }));',\n    \"}\",\n    \"\",\n  ].join(\"\\n\");\n}\n\n/**\n * The shared development descriptor workflow appends Vite's `?direct` query\n * to CSS URLs so preview hosts receive real CSS instead of JS style modules.\n * Published descriptors use a separate build path and never receive it.\n */\nexport function createDevWidgetPackageDescriptors(\n  configModule: Readonly<Record<string, unknown>>,\n  origin: string,\n): readonly RemoteDomWidgetPackageDescriptor[] {\n  return [\n    createWidgetPackageDevelopmentDescriptor({\n      sourceModule: configModule,\n      owner: \"droplet\",\n      origin,\n      workerEntryPath: \"/__runtime-entry__\",\n      defaultCssPath: \"/styles.css\",\n    }),\n  ];\n}\n\nasync function sendWidgetPackages(\n  server: ViteDevServer,\n  request: IncomingMessage,\n  response: ServerResponse,\n): Promise<void> {\n  if (handleOptions(request, response)) return;\n\n  try {\n    const configModule = (await server.ssrLoadModule(\n      \"/fluid.widget.config.ts\",\n    )) as Record<string, unknown>;\n    sendJson(\n      response,\n      createDevWidgetPackageDescriptors(\n        configModule,\n        getRequestOrigin(request),\n      ),\n    );\n  } catch (error) {\n    server.config.logger.error(\n      `[fluid] Failed to load widget packages: ${String(error)}`,\n    );\n    sendJson(response, { error: String(error) }, 500);\n  }\n}\n\nfunction sendJavaScript(\n  request: IncomingMessage,\n  response: ServerResponse,\n  source: string,\n): void {\n  if (handleOptions(request, response)) return;\n  setCorsHeaders(response);\n  response.setHeader(\"Content-Type\", \"text/javascript\");\n  response.statusCode = 200;\n  response.end(source);\n}\n\nfunction sendJson(\n  response: ServerResponse,\n  body: unknown,\n  statusCode = 200,\n): void {\n  setCorsHeaders(response);\n  response.setHeader(\"Content-Type\", \"application/json\");\n  response.statusCode = statusCode;\n  response.end(JSON.stringify(body, null, 2));\n}\n\nfunction handleOptions(\n  request: IncomingMessage,\n  response: ServerResponse,\n): boolean {\n  if (request.method !== \"OPTIONS\") return false;\n  setCorsHeaders(response);\n  response.statusCode = 204;\n  response.end();\n  return true;\n}\n\nfunction setCorsHeaders(response: ServerResponse): void {\n  response.setHeader(\"Access-Control-Allow-Origin\", \"*\");\n  response.setHeader(\"Access-Control-Allow-Methods\", \"GET, HEAD, OPTIONS\");\n  response.setHeader(\n    \"Access-Control-Allow-Headers\",\n    \"Content-Type, Authorization\",\n  );\n}\n\nfunction getRequestOrigin(request: IncomingMessage): string {\n  const host = readHeader(request.headers.host);\n  if (!host) throw new Error(\"Widget dev request is missing the Host header.\");\n\n  const forwardedProtocol = readHeader(request.headers[\"x-forwarded-proto\"]);\n  const protocol = forwardedProtocol === \"https\" ? \"https\" : \"http\";\n  return `${protocol}://${host}`;\n}\n\nfunction readHeader(\n  value: string | readonly string[] | undefined,\n): string | undefined {\n  const candidate = Array.isArray(value) ? value[0] : value;\n  return typeof candidate === \"string\" && candidate.trim().length > 0\n    ? candidate.trim()\n    : undefined;\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluid-app/fluid-cli-widget",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "description": "Fluid CLI plugin for standalone widget package workflows",
   "files": [
     "dist",
@@ -28,9 +28,11 @@
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "execa": "^8.0.0",
+    "fs-extra": "^11.2.0",
     "ora": "^8.0.0",
     "prompts": "^2.4.2",
-    "@fluid-app/fluid-cli-portal": "0.1.52",
+    "tsx": "^4.21.0",
+    "vite": "^6.4.1",
     "@fluid-app/fluid-cli": "0.1.14"
   },
   "devDependencies": {
@@ -39,8 +41,9 @@
     "@vitejs/plugin-react": "^4.3.0",
     "tsdown": "^0.21.0",
     "typescript": "^5",
-    "vite": "^6.4.1",
     "vitest": "^4.0.18",
+    "@fluid-app/fluid-cli-widget-tooling": "0.1.0",
+    "@fluid-app/fluidos-api-client": "0.1.0",
     "@fluid-app/typescript-config": "0.0.0"
   },
   "engines": {

package/templates/default/.gitignore.template

@@ -5,3 +5,9 @@ dist
 .env.local
 .fluid
 *.tsbuildinfo
+
+# Local tooling state — never belongs in the widget repo.
+# .mist-desktop/ holds Mist Desktop's private chats, attachments, and
+# screenshots for this project; .mist is its clone/slug marker.
+.mist
+.mist-desktop/

package/templates/default/package.json.template

@@ -18,6 +18,7 @@
     "@tanstack/react-query": "^5.90.11",
     "lucide-react": "~0.575.0",
     "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "react-hook-form": "^7.64.0",
     "zod": "4.3.5",
     "zustand": "^5.0.9"
@@ -29,7 +30,8 @@
     "vite": "^6.4.1",
     "@fluid-app/fluid-cli-widget": "{{widgetCliVersion}}",
     "@types/node": "^24.0.0",
-    "@types/react": "^19.2.13"
+    "@types/react": "^19.2.13",
+    "@types/react-dom": "^19.2.3"
   },
   "engines": {
     "node": ">=24.0.0"