@jxsuite/compiler 1.1.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {
@@ -45,15 +45,16 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^15.5.0",
-    "@jxsuite/create": "^1.1.0",
-    "@jxsuite/runtime": "^1.1.0",
-    "@jxsuite/schema": "^1.1.0",
+    "@jxsuite/create": "^1.2.0",
+    "@jxsuite/runtime": "^1.3.0",
+    "@jxsuite/schema": "^1.3.0",
+    "esbuild": "^0.28.1",
     "sharp": "^0.35.3"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.10.6",
-    "@jxsuite/connector": "^0.3.0",
-    "@jxsuite/parser": "^1.1.0",
+    "@happy-dom/global-registrator": "^20.11.0",
+    "@jxsuite/connector": "^0.4.0",
+    "@jxsuite/parser": "^1.3.0",
     "@types/mdast": "^4.0.4"
   }
 }

package/src/cli.ts

@@ -26,7 +26,7 @@ Commands:
   dev [root]       Start the dev server (requires @jxsuite/server and Bun)
   preview [root]   Serve an already-built dist/ directory
   schema [root]    Generate project.schema.json + document.schema.json from project.json#/extensions
-  validate [root]  Validate project.json against its generated project.schema.json
+  validate [root]  Validate the whole project: project.json, documents, classes, and fragments
   db push [root]   Sync the data section's tables to their connections (additive-only)
 
 Options:
@@ -161,18 +161,15 @@ Options:
     }
   } else if (command === "validate") {
     try {
-      const { validateProjectFile } = await import("@jxsuite/schema/validate-project");
-      const { valid, errors } = await validateProjectFile(projectRoot);
-      if (valid) {
-        console.log(`project.json is valid (${projectRoot})`);
+      const { formatProjectTreeIssues, validateProjectTree } =
+        await import("./site/validate-command.ts");
+      const result = await validateProjectTree(projectRoot);
+      if (result.valid) {
+        console.log(`Project is valid (${result.checked} files checked in ${projectRoot})`);
       } else {
-        console.error(`project.json is INVALID (${projectRoot}):`);
-        for (const error of errors ?? []) {
-          const { instancePath, message } = (error ?? {}) as {
-            instancePath?: string;
-            message?: string;
-          };
-          console.error(`  - ${instancePath || "/"}: ${message ?? JSON.stringify(error)}`);
+        console.error(`Project is INVALID (${projectRoot}):`);
+        for (const line of formatProjectTreeIssues(result)) {
+          console.error(line);
         }
         process.exit(1);
       }

package/src/compiler.ts

@@ -46,6 +46,13 @@ export interface CompileOptions {
   litHtmlSrc?: string;
   projectStyle?: JxStyle | null;
   formats?: FormatRegistry;
+  /** Rewrite Function-def `$src` specifiers to served URLs (see CompileElementOptions). */
+  rewriteSrc?: (specifier: string) => string;
+  /**
+   * Inject the color-scheme pre-paint script when `$media` declares a pure scheme query (default
+   * true). The site pipeline disables this and injects via the merged <head> instead.
+   */
+  prePaintScheme?: boolean;
   [key: string]: unknown;
 }
 
@@ -107,6 +114,8 @@ export async function compile(sourcePath: string | JxDocument, opts: CompileOpti
       litHtmlSrc,
       projectStyle,
       reactivitySrc,
+      ...(opts.prePaintScheme === false ? { prePaintScheme: false } : {}),
+      ...(opts.rewriteSrc ? { rewriteSrc: opts.rewriteSrc } : {}),
       title,
     });
   }
@@ -115,7 +124,7 @@ export async function compile(sourcePath: string | JxDocument, opts: CompileOpti
   if (raw.tagName && raw.tagName.includes("-")) {
     const { tagName } = raw;
     const className = tagNameToClassName(tagName);
-    const moduleContent = emitElementModule(raw, className, []);
+    const moduleContent = emitElementModule(raw, className, [], opts.rewriteSrc);
     const moduleFile = {
       content: moduleContent,
       path: `${tagName}.js`,
@@ -149,7 +158,14 @@ export async function compile(sourcePath: string | JxDocument, opts: CompileOpti
   }
 
   // Route 3: Dynamic with standard tagName → pre-rendered HTML + reactive bindings
-  return compileClient(raw, { litHtmlSrc, projectStyle, reactivitySrc, title });
+  return compileClient(raw, {
+    litHtmlSrc,
+    projectStyle,
+    reactivitySrc,
+    ...(opts.prePaintScheme === false ? { prePaintScheme: false } : {}),
+    ...(opts.rewriteSrc ? { rewriteSrc: opts.rewriteSrc } : {}),
+    title,
+  });
 }
 
 // ─── CLI ──────────────────────────────────────────────────────────────────────

package/src/shared.ts

@@ -6,7 +6,15 @@
  * compilation targets (static, client, element, server).
  */
 
-import { RESERVED_KEYS, camelToKebab, toCSSText } from "@jxsuite/runtime";
+import {
+  COLOR_SCHEME_ATTR,
+  COLOR_SCHEME_STORAGE_KEY,
+  RESERVED_KEYS,
+  camelToKebab,
+  pureSchemeOf,
+  schemeSelectors,
+  toCSSText,
+} from "@jxsuite/runtime";
 import { evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
 import { runStatements } from "@jxsuite/runtime/statements";
 import {
@@ -15,6 +23,7 @@ import {
   isExpressionDef,
   isFunctionDef,
   isMappedArray,
+  bodyReturnsValue,
   isNamedFormulaDef,
   isPrototypeDef,
   isRef,
@@ -36,7 +45,15 @@ import type {
 } from "@jxsuite/schema/types";
 
 // Re-export runtime utilities used by submodules
-export { RESERVED_KEYS, camelToKebab, toCSSText } from "@jxsuite/runtime";
+export {
+  COLOR_SCHEME_ATTR,
+  COLOR_SCHEME_STORAGE_KEY,
+  RESERVED_KEYS,
+  camelToKebab,
+  pureSchemeOf,
+  schemeSelectors,
+  toCSSText,
+} from "@jxsuite/runtime";
 export { compileExpression, evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
 export { compileStatements, runStatements } from "@jxsuite/runtime/statements";
 
@@ -63,7 +80,7 @@ export function emitFormulaFn(def: { parameters?: unknown[] }, compiledBody: str
 export type { ExpressionNode } from "@jxsuite/runtime/expression";
 
 // CDN defaults
-export const DEFAULT_REACTIVITY_SRC = "https://esm.sh/@vue/reactivity@3.5.32";
+export const DEFAULT_REACTIVITY_SRC = "https://esm.sh/@vue/reactivity@3.5.40";
 export const DEFAULT_LIT_HTML_SRC = "https://esm.sh/lit-html@3.3.0";
 
 // ─── Schema keywords & detection ─────────────────────────────────────────────
@@ -347,7 +364,7 @@ export function buildInitialScope(
         const fn = new Function("state", ...names, body) as (
           state: Record<string, unknown>,
         ) => unknown;
-        if (body.includes("return")) {
+        if (bodyReturnsValue(body)) {
           defineLazyScopeValue(scope, key, () => fn(scope));
         } else {
           setOwnScopeValue(scope, key, fn);
@@ -642,6 +659,94 @@ export function buildInner(
 
 // ─── CSS extraction ───────────────────────────────────────────────────────────
 
+/**
+ * The inline pre-paint script injected into <head> when a project declares a pure color-scheme
+ * media query: restores the visitor's persisted forced scheme before first paint (no FOUC).
+ *
+ * @returns {string}
+ * @docs framework/concepts/color-schemes
+ */
+export function colorSchemePrePaintScript(): string {
+  const key = JSON.stringify(COLOR_SCHEME_STORAGE_KEY);
+  const attr = JSON.stringify(COLOR_SCHEME_ATTR);
+  return `(function(){try{var s=localStorage.getItem(${key});if(s==="light"||s==="dark"){document.documentElement.setAttribute(${attr},s)}}catch(e){}})()`;
+}
+
+/**
+ * Resolve an `@`-prefixed style key into an emit function that pushes conditional rules. Pure
+ * color-scheme queries dual-emit per the forced-scheme contract (spec §9.5): a media-guarded copy
+ * that applies while no scheme is forced plus an unconditional copy under the forced root
+ * attribute.
+ *
+ * @param {string} atKey
+ * @param {Record<string, string>} mediaQueries
+ * @param {string[]} rules
+ * @returns {(selector: string, props: string) => void}
+ * @docs framework/concepts/color-schemes
+ */
+function conditionalRuleEmitter(
+  atKey: string,
+  mediaQueries: Record<string, string>,
+  rules: string[],
+): (selector: string, props: string) => void {
+  const query = atKey.startsWith("@--")
+    ? (mediaQueries[atKey.slice(1)] ?? atKey.slice(1))
+    : atKey.startsWith("@(")
+      ? atKey.slice(1)
+      : null;
+  const atRule = query === null ? atKey : `@media ${query}`;
+  const scheme = query === null ? null : pureSchemeOf(query);
+  return (selector: string, props: string) => {
+    if (!props) {
+      return;
+    }
+    if (scheme) {
+      const { auto, forced } = schemeSelectors(selector, scheme);
+      rules.push(`${atRule} { ${auto} { ${props} } }`, `${forced} { ${props} }`);
+    } else {
+      rules.push(`${atRule} { ${selector} { ${props} } }`);
+    }
+  };
+}
+
+/**
+ * Push the rules for one `@`-prefixed style block scoped to `selector`: flat props plus one level
+ * of nested selectors, routed through conditionalRuleEmitter (scheme-aware).
+ *
+ * @param {string[]} rules
+ * @param {string} atKey
+ * @param {Record<string, string>} mediaQueries
+ * @param {string} selector
+ * @param {Record<string, unknown>} obj
+ */
+function pushConditionalRule(
+  rules: string[],
+  atKey: string,
+  mediaQueries: Record<string, string>,
+  selector: string,
+  obj: Record<string, unknown>,
+) {
+  if (obj === null || typeof obj !== "object" || Array.isArray(obj)) {
+    return;
+  }
+  const emit = conditionalRuleEmitter(atKey, mediaQueries, rules);
+  emit(selector, toCSSText(obj));
+  for (const [sel, sub] of Object.entries(obj)) {
+    if (sub === null || typeof sub !== "object" || Array.isArray(sub)) {
+      continue;
+    }
+    if (sel.startsWith("@")) {
+      continue;
+    }
+    const resolved = sel.startsWith("&")
+      ? sel.replace("&", selector)
+      : sel.startsWith(":") || sel.startsWith(".") || sel.startsWith("[")
+        ? `${selector}${sel}`
+        : `${selector} ${sel}`;
+    emit(resolved, toCSSText(sub));
+  }
+}
+
 /**
  * Walk the entire document tree and collect all static nested CSS rules.
  *
@@ -671,30 +776,7 @@ export function compileStyles(
           continue;
         }
         if (key.startsWith("@")) {
-          const atRule = key.startsWith("@--")
-            ? `@media ${mediaQueries[key.slice(1)] ?? key.slice(1)}`
-            : key;
-          const mProps = toCSSText(val);
-          if (mProps) {
-            rules.push(`${atRule} { ${selector} { ${mProps} } }`);
-          }
-          for (const [sel, sub] of Object.entries(val as Record<string, unknown>)) {
-            if (sub === null || typeof sub !== "object" || Array.isArray(sub)) {
-              continue;
-            }
-            if (sel.startsWith("@")) {
-              continue;
-            }
-            const resolved = sel.startsWith("&")
-              ? sel.replace("&", selector)
-              : sel.startsWith(":") || sel.startsWith(".") || sel.startsWith("[")
-                ? `${selector}${sel}`
-                : `${selector} ${sel}`;
-            const subProps = toCSSText(sub);
-            if (subProps) {
-              rules.push(`${atRule} { ${resolved} { ${subProps} } }`);
-            }
-          }
+          pushConditionalRule(rules, key, mediaQueries, selector, val as Record<string, unknown>);
           continue;
         }
         const resolved = key.startsWith("&")
@@ -706,27 +788,6 @@ export function compileStyles(
       }
     };
 
-    for (const [key, val] of Object.entries(projectStyle)) {
-      if (key.startsWith(":") || key.startsWith(".") || key.startsWith("[")) {
-        emitProjectRules(key, val as Record<string, unknown>);
-      } else if (
-        val !== null &&
-        typeof val === "object" &&
-        !Array.isArray(val) &&
-        !key.startsWith("@") &&
-        !key.startsWith("--")
-      ) {
-        emitProjectRules(key, val as Record<string, unknown>);
-      } else if (key.startsWith("@")) {
-        // @media block at top level
-        const atRule = key.startsWith("@--")
-          ? `@media ${mediaQueries[key.slice(1)] ?? key.slice(1)}`
-          : key.startsWith("@(")
-            ? `@media ${key.slice(1)}`
-            : key;
-        rules.push(`${atRule} { body { ${toCSSText(val as Record<string, unknown>)} } }`);
-      }
-    }
     // Collect CSS custom properties into :root {}
     const rootProps: Record<string, unknown> = {};
     // Collect direct CSS properties into body {}
@@ -749,6 +810,7 @@ export function compileStyles(
         bodyProps[key] = val;
       }
     }
+    // Base rules precede conditional blocks so equal-specificity overrides win by source order.
     const rootCSS = toCSSText(rootProps);
     if (rootCSS) {
       rules.push(`:root { ${rootCSS} }`);
@@ -757,6 +819,62 @@ export function compileStyles(
     if (bodyCSS) {
       rules.push(`body { ${bodyCSS} }`);
     }
+
+    for (const [key, val] of Object.entries(projectStyle)) {
+      if (key.startsWith(":") || key.startsWith(".") || key.startsWith("[")) {
+        emitProjectRules(key, val as Record<string, unknown>);
+      } else if (
+        val !== null &&
+        typeof val === "object" &&
+        !Array.isArray(val) &&
+        !key.startsWith("@") &&
+        !key.startsWith("--")
+      ) {
+        emitProjectRules(key, val as Record<string, unknown>);
+      } else if (
+        key.startsWith("@") &&
+        val !== null &&
+        typeof val === "object" &&
+        !Array.isArray(val)
+      ) {
+        // Conditional block at project top level: custom properties override :root, direct
+        // Properties override body, selector-keyed sub-objects their own selector.
+        const emit = conditionalRuleEmitter(key, mediaQueries, rules);
+        const condRoot: Record<string, unknown> = {};
+        const condBody: Record<string, unknown> = {};
+        const condSubs: [string, Record<string, unknown>][] = [];
+        for (const [k, v] of Object.entries(val as Record<string, unknown>)) {
+          if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+            if (!k.startsWith("@")) {
+              condSubs.push([k, v as Record<string, unknown>]);
+            }
+            continue;
+          }
+          if (k.startsWith("--")) {
+            condRoot[k] = v;
+          } else {
+            condBody[k] = v;
+          }
+        }
+        emit(":root", toCSSText(condRoot));
+        emit("body", toCSSText(condBody));
+        for (const [sel, sub] of condSubs) {
+          emit(sel, toCSSText(sub));
+        }
+      }
+    }
+  }
+
+  // Forced-scheme UA hint: native widgets follow the forced attribute, not only the OS scheme.
+  if (
+    Object.values(mediaQueries).some((q) => pureSchemeOf(q) !== null) &&
+    !(projectStyle && typeof projectStyle === "object" && "colorScheme" in projectStyle)
+  ) {
+    rules.push(
+      ":root { color-scheme: light dark }",
+      `:root:where([${COLOR_SCHEME_ATTR}="light"]) { color-scheme: light }`,
+      `:root:where([${COLOR_SCHEME_ATTR}="dark"]) { color-scheme: dark }`,
+    );
   }
 
   const counter = { n: 0 };
@@ -790,32 +908,7 @@ function emitNestedElement(
       continue;
     }
     if (key.startsWith("@")) {
-      const atRule = key.startsWith("@--")
-        ? `@media ${mediaQueries[key.slice(1)] ?? key.slice(1)}`
-        : key.startsWith("@(")
-          ? `@media ${key.slice(1)}`
-          : key;
-      const mProps = toCSSText(val);
-      if (mProps) {
-        rules.push(`${atRule} { ${selector} { ${mProps} } }`);
-      }
-      for (const [sel, sub] of Object.entries(val as Record<string, unknown>)) {
-        if (sub === null || typeof sub !== "object" || Array.isArray(sub)) {
-          continue;
-        }
-        if (sel.startsWith("@")) {
-          continue;
-        }
-        const resolved = sel.startsWith("&")
-          ? sel.replace("&", selector)
-          : sel.startsWith(":") || sel.startsWith(".") || sel.startsWith("[")
-            ? `${selector}${sel}`
-            : `${selector} ${sel}`;
-        const subProps = toCSSText(sub);
-        if (subProps) {
-          rules.push(`${atRule} { ${resolved} { ${subProps} } }`);
-        }
-      }
+      pushConditionalRule(rules, key, mediaQueries, selector, val as Record<string, unknown>);
       continue;
     }
     const resolved = key.startsWith("&")
@@ -887,35 +980,7 @@ export function collectStyles(
         continue;
       }
       if (prop.startsWith("@")) {
-        const atRule = prop.startsWith("@--")
-          ? `@media ${mediaQueries[prop.slice(1)] ?? prop.slice(1)}`
-          : prop.startsWith("@(")
-            ? `@media ${prop.slice(1)}`
-            : prop;
-        const atBaseProps = toCSSText(val);
-        if (atBaseProps) {
-          rules.push(`${atRule} { ${selector} { ${atBaseProps} } }`);
-        }
-        for (const [sel, nestedRules] of Object.entries(
-          /** @type {Record<string, unknown>} */ val,
-        )) {
-          if (
-            nestedRules === null ||
-            typeof nestedRules !== "object" ||
-            Array.isArray(nestedRules)
-          ) {
-            continue;
-          }
-          if (sel.startsWith("@")) {
-            continue;
-          }
-          const resolved = sel.startsWith("&")
-            ? sel.replace("&", selector)
-            : sel.startsWith(":") || sel.startsWith(".") || sel.startsWith("[")
-              ? `${selector}${sel}`
-              : `${selector} ${sel}`;
-          rules.push(`${atRule} { ${resolved} { ${toCSSText(nestedRules)} } }`);
-        }
+        pushConditionalRule(rules, prop, mediaQueries, selector, val as Record<string, unknown>);
       } else {
         const resolved = prop.startsWith("&")
           ? prop.replace("&", selector)
@@ -1325,12 +1390,7 @@ export function buildComponentCSS(
 
     for (const [prop, val] of Object.entries(styleDef)) {
       if (prop.startsWith("@")) {
-        const atRule = prop.startsWith("@--")
-          ? `@media ${mediaQueries[prop.slice(1)] ?? prop.slice(1)}`
-          : prop.startsWith("@(")
-            ? `@media ${prop.slice(1)}`
-            : prop;
-        rules.push(`${atRule} { ${tagName} { ${toCSSText(val as Record<string, unknown>)} } }`);
+        pushConditionalRule(rules, prop, mediaQueries, tagName, val as Record<string, unknown>);
       } else if (
         prop.startsWith(":") ||
         prop.startsWith(".") ||

package/src/site/bundler.ts

@@ -0,0 +1,187 @@
+/**
+ * Bundler.js — timing-aware module bundling for compiled sites
+ *
+ * One backend abstraction serving every bundling need of the build (spec.md §12, compiler.md):
+ * client-timing `$src` sidecars today, the server worker in a follow-up. Backend selection is
+ * runtime-adaptive: `Bun.build` when the build runs under Bun, esbuild (dynamically imported) under
+ * plain Node. Options are kept minimal and identical across backends so output stays as stable as
+ * possible; set `JX_BUNDLER=esbuild` to force the fallback (e.g. for parity checks).
+ *
+ * `timing: "compiler"` code is never bundled — it executes in the build host via the extension
+ * registry's `importImplementation` path.
+ */
+
+import { rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join, resolve } from "node:path";
+import { isNpmSpecifier, NPM_SPECIFIER_PREFIX } from "@jxsuite/schema/asset-paths";
+
+/** Import specifiers left external in client bundles — provided by the page importmap. */
+export const CLIENT_EXTERNALS = ["@vue/reactivity", "lit-html"];
+
+/**
+ * True when a Function-def `$src` specifier is bundled by the build: `npm:` package specifiers and
+ * project-relative files. Absolute URL paths (`/lib/x.js`, `https://…`) are served as-is.
+ */
+export function isBundleableSrc(specifier: string): boolean {
+  return isNpmSpecifier(specifier) || specifier.startsWith("./") || specifier.startsWith("../");
+}
+
+/**
+ * True when the Node code path (createRequire resolution, esbuild backend) should be used: always
+ * under plain Node, or when `JX_BUNDLER=esbuild` forces it for parity checks.
+ */
+function useNodeFallback(): boolean {
+  return typeof Bun === "undefined" || process.env.JX_BUNDLER === "esbuild";
+}
+
+/**
+ * Resolve a bundleable `$src` specifier to the absolute entry file the bundler starts from. `npm:`
+ * specifiers resolve from the project root (project node_modules first, then up-tree); relative
+ * specifiers resolve against the directory of the document that declared them.
+ */
+export function resolveSidecarEntry(
+  specifier: string,
+  docDir: string,
+  projectRoot: string,
+): string {
+  if (isNpmSpecifier(specifier)) {
+    const bare = specifier.slice(NPM_SPECIFIER_PREFIX.length);
+    if (useNodeFallback()) {
+      return createRequire(join(projectRoot, "package.json")).resolve(bare);
+    }
+    return Bun.resolveSync(bare, projectRoot);
+  }
+  return resolve(docDir, specifier);
+}
+
+export interface BundleRequest {
+  /** Absolute path of the module to bundle. */
+  entryPath: string;
+  /** Absolute path of the bundled output file. */
+  outfile: string;
+}
+
+/** Resolution/runtime targets: client sidecars use "browser"; the site worker uses the rest. */
+export type BundleTargetName = "browser" | "node" | "bun" | "workerd";
+
+export interface BundleOptions {
+  target: BundleTargetName;
+  /** Bare specifiers left unresolved in the output. */
+  external?: string[];
+  /** Package.json export conditions for resolution (e.g. ["workerd", "worker"]). */
+  conditions?: string[];
+}
+
+/**
+ * Per-adapter bundle options for the generated site worker (WinterTC runtimes). Cloudflare resolves
+ * with workerd conditions and keeps `cloudflare:*`/`node:*` imports external (nodejs_compat
+ * provides node builtins at runtime); node/bun bundle platform-native with builtins external by
+ * construction.
+ */
+export function workerBundleOptions(adapter: string): BundleOptions {
+  if (adapter === "cloudflare-workers" || adapter === "cloudflare-pages") {
+    return {
+      conditions: ["workerd", "worker"],
+      external: ["cloudflare:*", "node:*"],
+      target: "workerd",
+    };
+  }
+  return { target: adapter === "bun" ? "bun" : "node" };
+}
+
+/** Map a bundle target to esbuild's platform (conditions carry the workerd specifics). */
+function esbuildPlatform(target: BundleTargetName): "browser" | "node" {
+  return target === "node" || target === "bun" ? "node" : "browser";
+}
+
+/** Map a bundle target to Bun.build's target. */
+function bunTarget(target: BundleTargetName): "browser" | "node" | "bun" {
+  if (target === "workerd") {
+    return "browser";
+  }
+  return target;
+}
+
+/**
+ * Bundle one entry module into a single self-contained ESM file. Throws with the backend's
+ * diagnostics on failure.
+ */
+export async function bundleEntry(request: BundleRequest, opts: BundleOptions): Promise<void> {
+  const external = opts.external ?? [];
+
+  if (useNodeFallback()) {
+    // Dynamic import keeps esbuild (a native-binary dependency) out of Bun-run builds entirely.
+    const esbuild = await import("esbuild");
+    await esbuild.build({
+      bundle: true,
+      ...(opts.conditions ? { conditions: opts.conditions } : {}),
+      entryPoints: [request.entryPath],
+      external,
+      format: "esm",
+      logLevel: "silent",
+      minify: false,
+      outfile: request.outfile,
+      platform: esbuildPlatform(opts.target),
+    });
+    return;
+  }
+
+  const result = await Bun.build({
+    ...(opts.conditions ? { conditions: opts.conditions } : {}),
+    entrypoints: [request.entryPath],
+    external,
+    format: "esm",
+    minify: false,
+    target: bunTarget(opts.target),
+    throw: false,
+  });
+  if (!result.success || result.outputs.length === 0) {
+    const logs = result.logs.map(String).join("\n");
+    throw new Error(`Bun.build failed for ${request.entryPath}:\n${logs}`);
+  }
+  writeFileSync(request.outfile, await result.outputs[0]!.text(), "utf8");
+}
+
+/**
+ * Bundle generated worker source (a string, not a file) into a self-contained module for the
+ * adapter's runtime. Bare and relative specifiers resolve from the project root — exactly how the
+ * unbundled source would have resolved when served from within the project.
+ */
+export async function bundleWorkerSource(
+  source: string,
+  { projectRoot, outfile, adapter }: { projectRoot: string; outfile: string; adapter: string },
+): Promise<void> {
+  const opts = workerBundleOptions(adapter);
+
+  if (useNodeFallback()) {
+    const esbuild = await import("esbuild");
+    await esbuild.build({
+      bundle: true,
+      ...(opts.conditions ? { conditions: opts.conditions } : {}),
+      external: opts.external ?? [],
+      format: "esm",
+      logLevel: "silent",
+      minify: false,
+      outfile,
+      platform: esbuildPlatform(opts.target),
+      stdin: {
+        contents: source,
+        loader: "js",
+        resolveDir: projectRoot,
+        sourcefile: "jx-worker-entry.js",
+      },
+    });
+    return;
+  }
+
+  // Bun.build has no stdin input — write a transient entry at the project root so resolution
+  // Matches the stdin/resolveDir behavior, and always remove it.
+  const entryPath = join(projectRoot, ".jx-worker-entry.mjs");
+  writeFileSync(entryPath, source, "utf8");
+  try {
+    await bundleEntry({ entryPath, outfile }, opts);
+  } finally {
+    rmSync(entryPath, { force: true });
+  }
+}