@fluid-app/fluid-cli-widget 0.1.25 → 0.1.27

package/dist/index.mjs

@@ -1237,9 +1237,9 @@ const cloneCommand = new Command("clone").description("Clone a widget package's
 }));
 //#endregion
 //#region src/utils/template.ts
-const EMBEDDED_PORTAL_SDK_VERSION = "0.1.460";
+const EMBEDDED_PORTAL_SDK_VERSION = "0.1.461";
 const EMBEDDED_CLI_CORE_VERSION = "0.1.14";
-const EMBEDDED_CLI_WIDGET_VERSION = "0.1.25";
+const EMBEDDED_CLI_WIDGET_VERSION = "0.1.27";
 function getDefaultTemplatePath() {
 	return path.join(findPackageRoot(), "templates", "default");
 }

package/dist/vite/plugin.d.mts

@@ -3,7 +3,60 @@ import { Plugin } from "vite";
 
 //#region src/vite/plugin.d.ts
 declare function fluidWidgetDevPlugin(): Plugin;
+/**
+* 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.
+*
+* Dev-only: this only ever serves from `configureServer` (the
+* plugin's `apply: "serve"` gate), never a built/published package.
+*/
+declare function buildRuntimeEntryBootstrapScript(entryPath: string): string;
 declare function createDevWidgetPackageDescriptors(configModule: Readonly<Record<string, unknown>>, origin: string): readonly RemoteDomWidgetPackageDescriptor[];
 //#endregion
-export { createDevWidgetPackageDescriptors, fluidWidgetDevPlugin };
+export { buildRuntimeEntryBootstrapScript, createDevWidgetPackageDescriptors, fluidWidgetDevPlugin };
 //# sourceMappingURL=plugin.d.mts.map

package/dist/vite/plugin.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.mts","names":[],"sources":["../../src/vite/plugin.ts"],"mappings":";;;;iBAQgB,oBAAA,CAAA,GAAwB,MAAA;AAAA,iBA8BxB,iCAAA,CACd,YAAA,EAAc,QAAA,CAAS,MAAA,oBACvB,MAAA,oBACU,gCAAA"}
+{"version":3,"file":"plugin.d.mts","names":[],"sources":["../../src/vite/plugin.ts"],"mappings":";;;;iBAQgB,oBAAA,CAAA,GAAwB,MAAA;;AAAxC;;;;;AA4FA;;;;;AA6BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA7BgB,gCAAA,CAAiC,SAAA;AAAA,iBA6BjC,iCAAA,CACd,YAAA,EAAc,QAAA,CAAS,MAAA,oBACvB,MAAA,oBACU,gCAAA"}

package/dist/vite/plugin.mjs

@@ -8,7 +8,7 @@ function fluidWidgetDevPlugin() {
 			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));
 					return;
 				}
 				if (pathname === "/__widget-packages__" || pathname === "/__widget-packages__/") {
@@ -20,6 +20,91 @@ function fluidWidgetDevPlugin() {
 		}
 	};
 }
+/** 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.
+*
+* Dev-only: this only ever serves from `configureServer` (the
+* plugin's `apply: "serve"` gate), never a built/published package.
+*/
+function buildRuntimeEntryBootstrapScript(entryPath) {
+	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(\"/@react-refresh\");",
+		"  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(entryPath)});`,
+		"self.removeEventListener(\"message\", __buf);",
+		"for (const data of __q) {",
+		"  self.dispatchEvent(new MessageEvent(\"message\", { data }));",
+		"}",
+		""
+	].join("\n");
+}
 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.");
@@ -34,11 +119,32 @@ function validatedPackageToDescriptor(validated, origin) {
 		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],
+		cssUrls: cssUrls.length > 0 ? cssUrls.map((url) => toDevCssUrl(url, origin)) : [toDevCssUrl("/styles.css", origin)],
 		assetUrls: [],
 		widgets: validated.widgets.map(({ name: _name, ...widget }) => widget)
 	};
 }
+/**
+* Vite's dev server serves a `.css` source file as a JS module by
+* default (so `import "./x.css"` hot-reloads) — fetching that URL
+* directly, as the widget-runtime host does to inject real
+* `<style>`/adopted-stylesheet content into a widget's shadow root,
+* returns `text/javascript`, not CSS. Vite's own dev server
+* recognizes a `?direct` query as a request for the genuine `text/css`
+* response, bypassing the JS-module transform.
+*
+* This descriptor builder only ever runs inside `configureServer`
+* (the plugin's `apply: "serve"` gate — see `fluidWidgetDevPlugin`
+* above), i.e. only for the dev preview's `/__widget-packages__`
+* response. A published/built widget package's `cssUrls` are produced
+* by a completely different path (the CLI's build pipeline) and point
+* at real static `.css` files with no Vite transform in front of
+* them, so this suffix can never leak into a production descriptor.
+*/
+function toDevCssUrl(url, origin) {
+	const { href } = new URL(url, origin);
+	return href.includes("?") ? `${href}&direct` : `${href}?direct`;
+}
 async function sendWidgetPackages(server, request, response) {
 	if (handleOptions(request, response)) return;
 	try {
@@ -89,6 +195,6 @@ function readHeader(value) {
 	return typeof candidate === "string" && candidate.trim().length > 0 ? candidate.trim() : void 0;
 }
 //#endregion
-export { createDevWidgetPackageDescriptors, fluidWidgetDevPlugin };
+export { buildRuntimeEntryBootstrapScript, createDevWidgetPackageDescriptors, 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":";;AAQA,SAAgB,uBAA+B;AAC7C,QAAO;EACL,MAAM;EACN,OAAO;EACP,gBAAgB,QAAQ;AACtB,UAAO,YAAY,IAAI,OAAO,SAAS,UAAU,SAAwB;IACvE,MAAM,YAAY,QAAQ,OAAO,IAAI,MAAM,IAAI,CAAC,MAAM;AAEtD,QACE,aAAa,wBACb,aAAa,uBACb;AACA,oBAAe,SAAS,UAAU,oCAAkC;AACpE;;AAGF,QACE,aAAa,0BACb,aAAa,yBACb;AACA,WAAM,mBAAmB,QAAQ,SAAS,SAAS;AACnD;;AAGF,UAAM;KACN;;EAEL;;AAGH,SAAgB,kCACd,cACA,QAC6C;CAC7C,MAAM,aAAa,kCACjB,mBAAmB,aAAa,EAChC,EAAE,OAAO,WAAW,CACrB;AACD,KAAI,CAAC,WAAW,WAAW,CAAC,WAAW,MACrC,OAAM,IAAI,MACR,WAAW,OAAO,KAAK,UAAU,MAAM,QAAQ,CAAC,KAAK,KAAK,IACxD,oCACH;AAGH,QAAO,CAAC,6BAA6B,WAAW,OAAO,OAAO,CAAC;;AAGjE,SAAS,6BACP,WACA,QACkC;CAClC,MAAM,UAAU,UAAU,cAAc,WAAW,EAAE;AACrD,QAAO;EACL,iBAAiB;EACjB,SAAS;EACT,WAAW,UAAU;EACrB,QAAQ,UAAU;EAClB,SAAS,UAAU;EACnB,gBAAgB,IAAI,IAAI,sBAAsB,OAAO,CAAC;EACtD,SACE,QAAQ,SAAS,IACb,QAAQ,KAAK,QAAQ,IAAI,IAAI,KAAK,OAAO,CAAC,KAAK,GAC/C,CAAC,IAAI,IAAI,eAAe,OAAO,CAAC,KAAK;EAC3C,WAAW,EAAE;EACb,SAAS,UAAU,QAAQ,KAAK,EAAE,MAAM,OAAO,GAAG,aAAa,OAAO;EACvE;;AAGH,eAAe,mBACb,QACA,SACA,UACe;AACf,KAAI,cAAc,SAAS,SAAS,CAAE;AAEtC,KAAI;AAIF,WACE,UACA,kCALoB,MAAM,OAAO,cACjC,0BACD,EAKG,iBAAiB,QAAQ,CAC1B,CACF;UACM,OAAO;AACd,SAAO,OAAO,OAAO,MACnB,2CAA2C,OAAO,MAAM,GACzD;AACD,WAAS,UAAU,EAAE,OAAO,OAAO,MAAM,EAAE,EAAE,IAAI;;;AAIrD,SAAS,mBACP,cACoB;CACpB,MAAM,WAAW,aAAa;AAC9B,KAAI,MAAM,QAAQ,SAAS,IAAI,SAAS,SAAS,EAAG,QAAO;CAE3D,MAAM,gBAAgB,aAAa;AACnC,QAAO,kBAAkB,KAAA,IAAY,EAAE,GAAG,CAAC,cAAc;;AAG3D,SAAS,eACP,SACA,UACA,QACM;AACN,KAAI,cAAc,SAAS,SAAS,CAAE;AACtC,gBAAe,SAAS;AACxB,UAAS,UAAU,gBAAgB,kBAAkB;AACrD,UAAS,aAAa;AACtB,UAAS,IAAI,OAAO;;AAGtB,SAAS,SACP,UACA,MACA,aAAa,KACP;AACN,gBAAe,SAAS;AACxB,UAAS,UAAU,gBAAgB,mBAAmB;AACtD,UAAS,aAAa;AACtB,UAAS,IAAI,KAAK,UAAU,MAAM,MAAM,EAAE,CAAC;;AAG7C,SAAS,cACP,SACA,UACS;AACT,KAAI,QAAQ,WAAW,UAAW,QAAO;AACzC,gBAAe,SAAS;AACxB,UAAS,aAAa;AACtB,UAAS,KAAK;AACd,QAAO;;AAGT,SAAS,eAAe,UAAgC;AACtD,UAAS,UAAU,+BAA+B,IAAI;AACtD,UAAS,UAAU,gCAAgC,qBAAqB;AACxE,UAAS,UACP,gCACA,8BACD;;AAGH,SAAS,iBAAiB,SAAkC;CAC1D,MAAM,OAAO,WAAW,QAAQ,QAAQ,KAAK;AAC7C,KAAI,CAAC,KAAM,OAAM,IAAI,MAAM,iDAAiD;AAI5E,QAAO,GAFmB,WAAW,QAAQ,QAAQ,qBAAqB,KACnC,UAAU,UAAU,OACxC,KAAK;;AAG1B,SAAS,WACP,OACoB;CACpB,MAAM,YAAY,MAAM,QAAQ,MAAM,GAAG,MAAM,KAAK;AACpD,QAAO,OAAO,cAAc,YAAY,UAAU,MAAM,CAAC,SAAS,IAC9D,UAAU,MAAM,GAChB,KAAA"}
+{"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(\n            request,\n            response,\n            buildRuntimeEntryBootstrapScript(WIDGET_ENTRY_MODULE_PATH),\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/** 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 *\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(entryPath: string): string {\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(\"/@react-refresh\");',\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(entryPath)});`,\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\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) => toDevCssUrl(url, origin))\n        : [toDevCssUrl(\"/styles.css\", origin)],\n    assetUrls: [],\n    widgets: validated.widgets.map(({ name: _name, ...widget }) => widget),\n  };\n}\n\n/**\n * Vite's dev server serves a `.css` source file as a JS module by\n * default (so `import \"./x.css\"` hot-reloads) — fetching that URL\n * directly, as the widget-runtime host does to inject real\n * `<style>`/adopted-stylesheet content into a widget's shadow root,\n * returns `text/javascript`, not CSS. Vite's own dev server\n * recognizes a `?direct` query as a request for the genuine `text/css`\n * response, bypassing the JS-module transform.\n *\n * This descriptor builder only ever runs inside `configureServer`\n * (the plugin's `apply: \"serve\"` gate — see `fluidWidgetDevPlugin`\n * above), i.e. only for the dev preview's `/__widget-packages__`\n * response. A published/built widget package's `cssUrls` are produced\n * by a completely different path (the CLI's build pipeline) and point\n * at real static `.css` files with no Vite transform in front of\n * them, so this suffix can never leak into a production descriptor.\n */\nfunction toDevCssUrl(url: string, origin: string): string {\n  const { href } = new URL(url, origin);\n  return href.includes(\"?\") ? `${href}&direct` : `${href}?direct`;\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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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluid-app/fluid-cli-widget",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "Fluid CLI plugin for standalone widget package workflows",
   "files": [
     "dist",
@@ -31,7 +31,7 @@
     "ora": "^8.0.0",
     "prompts": "^2.4.2",
     "@fluid-app/fluid-cli": "0.1.14",
-    "@fluid-app/fluid-cli-portal": "0.1.51"
+    "@fluid-app/fluid-cli-portal": "0.1.52"
   },
   "devDependencies": {
     "@types/node": "24.10.12",