@jxsuite/compiler 2.0.8 → 3.1.0

package/src/site/site-build.ts

@@ -21,7 +21,15 @@ import {
 import { createHash } from "node:crypto";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { isMappedArray, isRef } from "@jxsuite/schema/guards";
-import { isNpmSpecifier, npmAssetPath, sidecarAssetPath } from "@jxsuite/schema/asset-paths";
+import {
+  isNpmSpecifier,
+  npmAssetPath,
+  sidecarAssetPath,
+  siteAbsoluteUrl,
+  siteBasePath,
+  withBase,
+} from "@jxsuite/schema/asset-paths";
+import { rewriteHtmlBase } from "./base-path.ts";
 import {
   CLIENT_EXTERNALS,
   bundleEntry,
@@ -40,6 +48,7 @@ import {
 import {
   buildHeaderRules,
   contentTypeRules,
+  rebaseHeaderRules,
   writeHeaders,
   writeNoJekyll,
 } from "./headers-emitter.ts";
@@ -50,7 +59,7 @@ import type { AssetMount } from "@jxsuite/schema/asset-paths";
 import type { FormatEntry, FormatRegistry } from "@jxsuite/schema/format-registry";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 import { resolveLayout } from "./layout-resolver.ts";
-import { mergeHead, renderHead } from "./head-merger.ts";
+import { mergeHead, renderHead } from "@jxsuite/site/head-merger";
 import { unregisteredHeadRelations } from "./link-relations.ts";
 import { injectContext } from "./context-injection.ts";
 import { compile, compileServer, compileSiteServer } from "../compiler.ts";
@@ -62,6 +71,7 @@ import {
   collectServerEntries,
   collectStyles,
   colorSchemePrePaintScript,
+  escapeStyleText,
   evaluateStaticTemplate,
   isComponentFullyStatic,
   isSingleExpression,
@@ -99,7 +109,8 @@ import {
 } from "./i18n.ts";
 import type { LocaleAlternate, PageLocaleContext } from "./i18n.ts";
 import {
-  isPrefixSpecifier,
+  importMapAssets,
+  importMapAssetsInHtml,
   renderImportMap,
   resolveClientRuntime,
   writeClientRuntime,
@@ -160,6 +171,13 @@ export async function buildSite(
   const pagesDir = resolve(projectRoot, "pages");
   const publicDir = resolve(projectRoot, "public");
   const trailingSlash = projectConfig.build.trailingSlash ?? "always";
+  /*
+   * Browser bundles are minified unless the project opts out. Off, the six scripts jxsuite.com
+   * loads weigh 155 kB of source a phone has to parse before it can paint; on, 65 kB. The opt-out
+   * exists for two real cases: reading a deployed stack trace, and diffing `dist/` across bundler
+   * backends, which agree on semantics but not on minified bytes.
+   */
+  const minify = projectConfig.build.minify !== false;
 
   // Client sidecar bundles: bundleable Function-def `$src` specifiers (and lowered-def `$bundle`
   // Hints) are rewritten to their /assets/ URL during compilation, registered here, and bundled
@@ -201,6 +219,11 @@ export async function buildSite(
    */
   const clientRuntime = resolveClientRuntime();
   const runtimeImports = clientRuntime.imports;
+  /*
+   * What step 6d bundles, scanned back out of each finished page rather than recorded wherever a
+   * map is emitted. Several places emit one and only `injectComponentScripts` was recording, so a
+   * page whose interactivity came from anything else shipped a map naming files no build wrote.
+   */
   const runtimeAssetsUsed = new Set<string>();
   /*
    * Scanned from every finished page, so the hashes name the exact bytes shipped rather than what
@@ -505,6 +528,12 @@ export async function buildSite(
   // Sitemap is generated from the route table when a production `url` is configured
   // (absolute <loc> URLs require it) and not explicitly disabled via build.sitemap: false.
   const siteUrl = projectConfig.url;
+  /*
+   * The path the site is deployed under, read back off `url` (RFC 3986 §5 — see `base-path.ts`).
+   * `""` for a site at an origin root, which is every deployment Jx documents, so every use below
+   * is a no-op there rather than a branch.
+   */
+  const basePath = siteBasePath(siteUrl);
   const sitemapEnabled = Boolean(siteUrl) && projectConfig.build.sitemap !== false;
   const sitemapEntries: SitemapEntry[] = [];
 
@@ -680,10 +709,18 @@ export async function buildSite(
           staticTags,
           result.files.map((f: { content: string }) => f.content).join("\n"),
           runtimeImports,
-          runtimeAssetsUsed,
         );
       }
 
+      /*
+       * Whatever import map this page ended up with, step 6d owes it the files it names. Read from
+       * the finished HTML so the answer does not depend on which of the emission paths produced
+       * the map — the one that reported and the one that shipped were different sets (issue #227).
+       */
+      for (const assetPath of importMapAssetsInHtml(result.html)) {
+        runtimeAssetsUsed.add(assetPath);
+      }
+
       // Mounted assets this page actually references — scanned from the finished HTML so a
       // Reference is caught wherever it came from (markdown image, hand-authored page, $head).
       collectAssetRefs(result.html, assetMounts, assetRefs);
@@ -692,7 +729,9 @@ export async function buildSite(
       // Determine output path
       const outPath = routeToOutputPath(route.urlPattern, outDir, trailingSlash);
       mkdirSync(dirname(outPath), { recursive: true });
-      writeFileSync(outPath, result.html, "utf8");
+      /* Last, after the scans above: they ask what this page REFERENCES, and the answer is a
+         build-output path, not a deployed URL. Re-rooting first would make every one of them miss. */
+      writeFileSync(outPath, rewriteHtmlBase(result.html, basePath), "utf8");
       fileCount += 1;
 
       // Record a sitemap entry for this concrete page (skip unexpanded dynamic routes and
@@ -713,7 +752,7 @@ export async function buildSite(
             typeof route.sourceMtime === "string" && route.sourceMtime !== ""
               ? route.sourceMtime
               : toRfc3339(statSync(route.sourcePath).mtime),
-          loc: new URL(route.urlPattern, siteUrl).href,
+          loc: siteAbsoluteUrl(route.urlPattern, siteUrl),
           ...(routeAlternates.length > 0 && { alternates: routeAlternates }),
         });
       }
@@ -813,7 +852,13 @@ export async function buildSite(
     const skipWorker = adapter === "cloudflare-pages" && deduped.size === 0 && mounts.length === 0;
     const workerSource = skipWorker
       ? null
-      : compileSiteServer([...deduped.values()], { adapter, connectors, i18n, mounts });
+      : compileSiteServer([...deduped.values()], {
+          adapter,
+          base: basePath,
+          connectors,
+          i18n,
+          mounts,
+        });
 
     if (workerSource) {
       // Bundle the worker self-contained for the adapter's runtime (compiler.md §12): mount
@@ -862,6 +907,8 @@ export async function buildSite(
     const runtime = await writeClientRuntime(
       { ...clientRuntime, assetPaths: [...runtimeAssetsUsed] },
       outDir,
+      undefined,
+      minify,
     );
     fileCount += runtime.written;
     for (const error of runtime.errors) {
@@ -889,7 +936,7 @@ export async function buildSite(
         mkdirSync(dirname(outfile), { recursive: true });
         await bundleEntry(
           { entryPath: bundle.entryPath, outfile },
-          { external: CLIENT_EXTERNALS, target: "browser" },
+          { external: CLIENT_EXTERNALS, minify, target: "browser" },
         );
         fileCount += 1;
         log(`  ${bundle.specifier} → ${assetPath}`);
@@ -914,7 +961,7 @@ export async function buildSite(
         await bundleSource(
           `${specifiers.map((sp) => `import ${JSON.stringify(sp)};`).join("\n")}\n`,
           { outfile, resolveDir: projectRoot },
-          { target: "browser" },
+          { minify, target: "browser" },
         );
         fileCount += 1;
         log(`  ${specifiers.length} element(s) → ${assetPath}`);
@@ -933,7 +980,7 @@ export async function buildSite(
    * discovered from their contents rather than declared anywhere (site-architecture.md §8.7).
    */
   if (runtimeAssetsUsed.size > 0) {
-    const subpaths = await writeRuntimeSubpaths(outDir);
+    const subpaths = await writeRuntimeSubpaths(outDir, undefined, minify);
     if (subpaths.written > 0) {
       log(`Bundling ${subpaths.written} runtime subpath module(s)...`);
     }
@@ -990,6 +1037,7 @@ export async function buildSite(
     log("Generating redirects...");
     const compiledUrls = new Set(routes.map((r) => r.urlPattern));
     const redirects = generateRedirects(projectConfig.redirects, outDir, {
+      basePath,
       compiledUrls,
       trailingSlash: projectConfig.build.trailingSlash,
     });
@@ -1067,7 +1115,8 @@ export async function buildSite(
   {
     const sw = normalizeServiceWorker(projectConfig.serviceWorker);
     if (sw !== null) {
-      const output = sw === false ? tombstoneServiceWorker() : buildServiceWorker(sw, outDir);
+      const output =
+        sw === false ? tombstoneServiceWorker() : buildServiceWorker(sw, outDir, basePath);
       for (const warning of output.warnings) {
         console.warn(warning);
       }
@@ -1091,16 +1140,40 @@ export async function buildSite(
     );
     errors.push(...headerErrors);
     // Runs here, after every emitter, so it can see which of these files the build actually wrote.
-    const rules = [...securityRules, ...contentTypeRules(outDir)];
+    const rules = rebaseHeaderRules([...securityRules, ...contentTypeRules(outDir)], basePath);
     if (rules.length > 0) {
       log("Writing response headers...");
       fileCount += writeHeaders(outDir, rules);
-      const { adapter } = projectConfig.build;
+      const { adapter, deploy } = projectConfig.build;
       if (adapter === "node" || adapter === "bun") {
         console.warn(
           `The "${adapter}" adapter serves no static assets, so dist/_headers is documentation ` +
             `rather than configuration — apply these headers at the reverse proxy in front of it.`,
         );
+      } else if (adapter === undefined && deploy === undefined) {
+        /*
+         * `_headers` is a Cloudflare/Netlify convention, not a web standard, and the build has no
+         * way to know where a plain static `dist/` is going. Most static hosts — GitHub Pages among
+         * them — ignore the file entirely and serve their own `Cache-Control`, which is how a site
+         * ends up shipping a year-long `immutable` rule for its content-addressed images and
+         * getting ten minutes.
+         *
+         * A `public/CNAME` is GitHub Pages' custom-domain marker and nothing else's, so it is a
+         * specific enough signal to say so out loud rather than warn every static build.
+         */
+        if (existsSync(resolve(publicDir, "CNAME"))) {
+          console.warn(
+            "GitHub Pages ignores dist/_headers and serves its own Cache-Control: max-age=600, " +
+              "so the generated caching and security rules will not take effect. Deploy behind a " +
+              "host that reads _headers (Cloudflare Pages, Cloudflare Workers assets, Netlify) " +
+              "to apply them.",
+          );
+        } else {
+          log(
+            "  note: _headers is read by Cloudflare Pages, Cloudflare Workers assets and Netlify; " +
+              "other static hosts ignore it and serve their own Cache-Control.",
+          );
+        }
       }
     }
     fileCount += writeNoJekyll(outDir);
@@ -1167,11 +1240,15 @@ async function compilePage(
   /** Registers a page's npm `$elements` set as one bundle and returns its URL. */
   registerElementBundle: (specifiers: string[]) => string,
 ) {
+  /* Derived rather than passed as a seventeenth parameter: it is a pure function of
+     `projectConfig.url`, which is already here, so the two cannot disagree. */
+  const basePath = siteBasePath(projectConfig.url);
+
   // Load the raw page document (.json natively, other formats via the registry)
   const pageDoc = await readPageDocument(route.sourcePath as string, formatRegistry);
 
   // Resolve layout (wraps page in layout with slot distribution)
-  const layoutDoc = resolveLayout(pageDoc, projectConfig, projectRoot);
+  const layoutDoc = await resolveLayout(pageDoc, projectConfig, projectRoot);
 
   // Extract head arrays before they get lost in the merge
   const pageHead = (pageDoc.$head ?? layoutDoc._pageHead ?? []) as JxHeadEntry[];
@@ -1316,7 +1393,7 @@ async function compilePage(
   const swHead: JxHeadEntry[] =
     swConfig === null || swConfig === false
       ? []
-      : [{ tagName: "script", textContent: registrationScript(swConfig.scope ?? "/") }];
+      : [{ tagName: "script", textContent: registrationScript(swConfig.scope ?? "/", basePath) }];
 
   const resolvedSiteHead = [
     // The manifest link and theme colour are first-party and unconditional once declared, so they
@@ -1393,7 +1470,7 @@ async function compilePage(
   if (slotCss.rules.length > 0) {
     result.html = result.html.replace(
       "</head>",
-      `<style>\n${slotCss.rules.join("\n")}\n</style>\n</head>`,
+      `<style>\n${escapeStyleText(slotCss.rules.join("\n"))}\n</style>\n</head>`,
     );
   }
 
@@ -1480,6 +1557,7 @@ function buildMountSpecs(
   if (activeMounts.length === 0) {
     return { connectors: [], mounts: [] };
   }
+  const base = siteBasePath(projectConfig.url);
 
   const sections: Record<string, unknown> = {};
   for (const contribution of registry.projectContributions()) {
@@ -1498,11 +1576,15 @@ function buildMountSpecs(
           `to generate a deployable worker`,
       );
     }
+    /* Both are request paths in the deployed worker: the route it registers, and the prefix the
+       mount strips to find its own sub-path. They must carry the same base or the handler would
+       answer a URL and then mis-read it. */
+    const mountBase = withBase(base, server.basePath);
     return {
-      basePath: server.basePath,
+      basePath: mountBase,
       className: (entry.classDef.title as string | undefined) ?? entry.name,
       module,
-      options: { basePath: server.basePath, sections },
+      options: { basePath: mountBase, sections },
       order: server.order ?? 100,
     };
   });
@@ -2074,7 +2156,6 @@ function expandComponents(
  * @param {Set<string>} [staticTags] - Tags where ALL instances are fully static (skip JS)
  * @param {string} [islandSource] - Concatenated island modules emitted for this page
  * @param {Record<string, string>} [runtimeImports] - The import map's `imports` object
- * @param {Set<string>} [runtimeAssetsUsed] - Collects the asset paths an emitted import map names
  * @returns {string}
  */
 function injectComponentScripts(
@@ -2084,7 +2165,6 @@ function injectComponentScripts(
   staticTags = new Set<string>(),
   islandSource = "",
   runtimeImports: Record<string, string> = {},
-  runtimeAssetsUsed = new Set<string>(),
 ) {
   // A component reaches a page two ways: as a literal tag in the static HTML, or referenced only
   // From inside an island's client template — in which case the tag exists solely in the island's
@@ -2097,15 +2177,31 @@ function injectComponentScripts(
     return html;
   }
 
-  // Inject CSS links in <head> for ALL components that have CSS sidecars
-  const cssLinks = usedTags
-    .filter((tag: string) => cssMap.has(tag))
-    .map((tag: string) => `<link rel="stylesheet" href="/components/${tag}.css">`)
-    .join("\n  ");
-  let result = html;
-  if (cssLinks) {
-    result = result.replace("</head>", `  ${cssLinks}\n</head>`);
-  }
+  /*
+   * Component CSS is INLINED, not linked.
+   *
+   * A `<link rel="stylesheet">` per component tag is a render-blocking request per component: on
+   * jxsuite.com's home page, 11 of them totalling 22 kB — the whole of its critical request chain,
+   * for sheets averaging 2 kB each. The page already carries its project and page CSS inline
+   * (`buildStyleBlock`), so this is the same delivery, applied consistently.
+   *
+   * The trade is real and deliberate: these bytes now repeat on every page instead of caching
+   * across navigations. They are small, they gzip against the markup around them, and a round trip
+   * on a phone costs more than the bytes do. Components in shadow mode are untouched — their sheet
+   * is linked from inside the declarative shadow root and never enters `cssMap`.
+   *
+   * Emitted last in <head>, exactly where the links were, so the cascade is unchanged.
+   */
+  const componentCss = usedTags
+    .map((tag: string) => cssMap.get(tag))
+    .filter((css): css is string => css !== undefined && css !== "")
+    .join("\n");
+  const styleBlock =
+    componentCss === "" ? "" : `<style>\n${escapeStyleText(componentCss)}\n  </style>`;
+  const intoHead = (fragments: string[]) => {
+    const block = fragments.filter(Boolean).join("\n  ");
+    return block === "" ? html : html.replace("</head>", `  ${block}\n</head>`);
+  };
 
   // Only inject JS for components that have non-static instances. An island-rendered instance is
   // Never prerendered, so it needs its module even when the component itself is fully static —
@@ -2113,22 +2209,30 @@ function injectComponentScripts(
   // The static HTML: those instances are prerendered, but the ones the island creates are not.
   const jsTags = usedTags.filter((tag: string) => inIsland(tag) || !staticTags.has(tag));
   if (jsTags.length === 0) {
-    return result;
+    return intoHead([styleBlock]);
   }
 
   // Build import map (needed for @vue/reactivity and lit-html)
   const importMap = renderImportMap(runtimeImports);
-  for (const [specifier, url] of Object.entries(runtimeImports)) {
-    /*
-     * A prefix key's value is the DIRECTORY its subpaths are served from — `/assets/lit-html/` —
-     * not a file any build writes. `writeClientRuntime` matches this set against exact asset
-     * paths, so a directory in it bundled nothing and only inflated the count this build logged.
-     */
-    if (isPrefixSpecifier(specifier) || !url.startsWith("/")) {
-      continue;
-    }
-    runtimeAssetsUsed.add(url);
-  }
+  /*
+   * The runtime modules THIS page needs — the hints are per page, so they are read from this
+   * page's map rather than from the build-wide set, which would have every page hint at every
+   * other page's runtime.
+   */
+  const pageRuntimeAssets = importMapAssets(runtimeImports);
+
+  /*
+   * An import map declares where a bare specifier lives; it does not tell the browser to go get it.
+   * Without these hints `/assets/vue-reactivity.js` is discovered only after a component module has
+   * been fetched AND parsed — a three-deep request chain on the critical path, on a connection
+   * where each hop is a round trip. The component modules are hinted too so the whole set starts
+   * downloading while the HTML is still being parsed.
+   */
+  const preloads = [...pageRuntimeAssets, ...jsTags.map((tag: string) => `/components/${tag}.js`)]
+    .map((href) => `<link rel="modulepreload" href="${href}">`)
+    .join("\n  ");
+
+  const result = intoHead([preloads, styleBlock]);
 
   const moduleScripts = jsTags
     .map((tag: string) => `<script type="module" src="/components/${tag}.js"></script>`)
@@ -2299,7 +2403,7 @@ function generateRedirects(
     string | { destination: string; status?: number } | { destination: string; rewrite: true }
   >,
   outDir: string,
-  opts: { compiledUrls?: Set<string>; trailingSlash?: string } = {},
+  opts: { compiledUrls?: Set<string>; trailingSlash?: string; basePath?: string } = {},
 ) {
   let files = 0;
   const errors: string[] = [];
@@ -2326,7 +2430,11 @@ function generateRedirects(
       continue;
     }
 
-    redirectLines.push(`${source} ${dest} ${status}`);
+    /* Both halves are site URLs, and the host matches the source against a REQUEST path — which
+       arrives under the base. A rule left at the old root would never fire, and one that did would
+       send the visitor out of the deployment. */
+    const rebased = opts.basePath ?? "";
+    redirectLines.push(`${withBase(rebased, source)} ${withBase(rebased, dest)} ${status}`);
 
     // A pattern source cannot be a file on disk, so it lives only in `_redirects`.
     if (source.includes(":") || source.includes("*")) {
@@ -2493,7 +2601,7 @@ function ensureRobotsSitemap(outDir: string, siteUrl: string) {
   if (!content.endsWith("\n")) {
     content += "\n";
   }
-  content += `\nSitemap: ${new URL("/sitemap.xml", siteUrl).href}\n`;
+  content += `\nSitemap: ${siteAbsoluteUrl("/sitemap.xml", siteUrl)}\n`;
   writeFileSync(robotsPath, content, "utf8");
   return existed ? 0 : 1;
 }

package/src/site/well-known.ts

@@ -9,6 +9,7 @@
  * @docs framework/site/deployment
  */
 
+import { siteBasePath, withBase } from "@jxsuite/schema/asset-paths";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { canonicalizeLocale } from "@jxsuite/schema/locale";
@@ -48,17 +49,27 @@ export function buildManifest(projectConfig: ProjectConfig): WellKnownOutput {
   }
 
   const name = config.name ?? projectConfig.name ?? "Jx Site";
-  const icons = config.icons ?? [];
+  /*
+   * Every URL in a manifest is fetched or navigated to by the browser, so all three carry the
+   * deployment base (`base-path.ts`). `scope` is the one that fails loudly — a scope the manifest's
+   * own URL is not inside makes the manifest invalid and the site uninstallable — while a
+   * `start_url` at the old root just opens the wrong page from the home screen.
+   */
+  const base = siteBasePath(projectConfig.url);
+  const icons = [];
+  for (const icon of config.icons ?? []) {
+    icons.push(typeof icon.src === "string" ? { ...icon, src: withBase(base, icon.src) } : icon);
+  }
   const manifest: Record<string, unknown> = {
     display: config.display ?? "standalone",
     icons,
     name,
     short_name: config.shortName ?? name,
-    start_url: config.startUrl ?? "/",
+    start_url: withBase(base, config.startUrl ?? "/"),
     ...(config.description === undefined ? {} : { description: config.description }),
     ...(config.themeColor === undefined ? {} : { theme_color: config.themeColor }),
     ...(config.backgroundColor === undefined ? {} : { background_color: config.backgroundColor }),
-    ...(config.scope === undefined ? {} : { scope: config.scope }),
+    ...(config.scope === undefined ? {} : { scope: withBase(base, config.scope) }),
     ...(config.orientation === undefined ? {} : { orientation: config.orientation }),
     ...(config.lang === undefined ? {} : { lang: config.lang }),
     ...(config.dir === undefined ? {} : { dir: config.dir }),

package/src/targets/compile-element.ts

@@ -17,6 +17,7 @@ import {
   escapeHtml,
   isMutating,
   isSchemaOnly,
+  srcExportName,
   srcImportBinding,
   tagNameToClassName,
 } from "../shared.ts";
@@ -351,11 +352,36 @@ export function emitElementModule(
 
   // Collect $src imports from state entries before emitting other imports
   const srcImportMap = new Map<string, string[]>();
+  /** `$lazy` `$src` modules → the (export, local binding) pairs each one supplies. */
+  const lazySrcMap = new Map<string, { binding: string; exportName: string }[]>();
   const defs = doc.state ?? {};
+  const callableRefs = collectCallableRefs(doc);
   for (const [key, def] of Object.entries(defs)) {
     const d = def as JxMutableNode;
     if (d && typeof d === "object" && !Array.isArray(d) && d.$prototype === "Function" && d.$src) {
       const srcPath = d.$src;
+      if (d.$lazy === true) {
+        /*
+         * A computed reads its value synchronously, and a lazy binding can only ever hand back a
+         * promise. Silently producing `computed(() => Promise)` would render "[object Promise]" in
+         * whatever the template bound it to, so this is a build error rather than a surprise.
+         */
+        if (!callableRefs.has(key) && !LIFECYCLE_KEYS.has(key)) {
+          throw new Error(
+            `"${key}" declares "$lazy": true but is used as a computed value, not called. ` +
+              `A lazily loaded function resolves to a promise; a computed must resolve now. ` +
+              `Remove "$lazy", or call ${key}() from a handler instead of binding its value.`,
+          );
+        }
+        if (!lazySrcMap.has(srcPath)) {
+          lazySrcMap.set(srcPath, []);
+        }
+        (lazySrcMap.get(srcPath) as { binding: string; exportName: string }[]).push({
+          binding: key,
+          exportName: srcExportName(key, d),
+        });
+        continue;
+      }
       if (!srcImportMap.has(srcPath)) {
         srcImportMap.set(srcPath, []);
       }
@@ -380,6 +406,31 @@ export function emitElementModule(
   lines.push(
     `import { reactive, computed, effect, stop } from '@vue/reactivity';`,
     `import { render, html } from 'lit-html';`,
+  );
+
+  /*
+   * `$lazy` swaps the static import for a memoized dynamic one. A static import is a download, a
+   * parse and an evaluate on every page that renders the component, whether or not anybody calls
+   * the function: jxsuite.com's search client is 70 kB of MiniSearch fetched by every visitor, most
+   * of whom never open search. The local binding keeps its name so every call site is unchanged;
+   * what changes is that it now returns a promise.
+   */
+  let lazyIndex = 0;
+  for (const [srcPath, entries] of lazySrcMap) {
+    const importPath = rewriteSrc ? rewriteSrc(srcPath) : srcPath;
+    const mod = `_jxLazy${lazyIndex}`;
+    lazyIndex += 1;
+    lines.push(
+      `let ${mod};`,
+      `const ${mod}Load = () => (${mod} ??= import('${importPath}'));`,
+      ...entries.map(
+        ({ binding, exportName }) =>
+          `const ${binding} = (...args) => ${mod}Load().then((m) => m.${exportName}(...args));`,
+      ),
+    );
+  }
+
+  lines.push(
     "",
     `class ${className} extends HTMLElement {`,
     // One registry for every effect the element creates — render, dynamic host styles, Request
@@ -401,7 +452,6 @@ export function emitElementModule(
   const formulaEntries: [string, JxExpressionDef][] = [];
   /** `"${…}"` state entries — computed, exactly as the runtime treats them. */
   const templateEntries: [string, string][] = [];
-  const callableRefs = collectCallableRefs(doc);
   for (const [key, def] of Object.entries(defs)) {
     const d = def as JxMutableNode;
     if (isExpressionDef(d)) {

package/src/targets/compile-server.ts

@@ -5,6 +5,7 @@
  * file.
  */
 
+import { withBase } from "@jxsuite/schema/asset-paths";
 import { dereference } from "@apidevtools/json-schema-ref-parser";
 import { collectServerEntries } from "../shared.ts";
 import { localeNegotiationMiddleware } from "../site/locale-negotiation.ts";
@@ -110,15 +111,21 @@ export function compileSiteServer(
     mounts?: SiteMountSpec[];
     connectors?: SiteConnectorSpec[];
     i18n?: ResolvedI18n | null;
+    base?: string;
   } = {},
 ) {
-  const {
-    baseUrl = "/_jx/server",
-    adapter = null,
-    mounts = [],
-    connectors = [],
-    i18n = null,
-  } = opts;
+  const { adapter = null, mounts = [], connectors = [], i18n = null, base = "" } = opts;
+  /*
+   * Routes are registered under the deployment base (`site/base-path.ts`), because the worker IS
+   * the origin: the request it sees is the one the visitor's browser sent, and on a site served
+   * from `/m/my-site/` that path carries the prefix. A route left at the bare path would simply
+   * never match — the 404 nobody attributes to a config value.
+   *
+   * The dev server takes the opposite approach and strips the base at the edge (`server.ts`), so
+   * everything behind it routes on the bare path. Each is internally consistent: production serves
+   * exactly one URL space, while `jx dev` deliberately answers both.
+   */
+  const baseUrl = withBase(base, opts.baseUrl ?? "/_jx/server");
   if (entries.length === 0 && mounts.length === 0 && !adapter) {
     return null;
   }

package/src/types.ts

@@ -1,14 +1,8 @@
-export interface HeadMergeContext {
-  title?: string;
-  siteName?: string;
-  lang?: string;
-  charset?: string;
-  url?: string;
-  siteUrl?: string;
-  pageUrl?: string;
-  /** `rel="alternate"` links for this page's translations (site-architecture.md §13.5). */
-  alternates?: readonly { hreflang: string; href: string }[];
-}
+/**
+ * `HeadMergeContext` moved to `@jxsuite/site/head-merger` with the merger itself — a browser bundle
+ * and a Worker both assemble the same `<head>`, and neither can import this package.
+ */
+export type { HeadMergeContext } from "@jxsuite/site/head-merger";
 
 export interface SiteRoute {
   urlPattern: string;