@jxsuite/compiler 3.0.0 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {
@@ -46,19 +46,19 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^16.0.1",
-    "@jxsuite/create": "^1.3.8",
-    "@jxsuite/runtime": "^3.0.0",
-    "@jxsuite/schema": "^2.0.0",
-    "@jxsuite/site": "^1.0.0",
-    "@vue/reactivity": "3.5.41",
+    "@jxsuite/create": "^1.3.9",
+    "@jxsuite/runtime": "^3.1.0",
+    "@jxsuite/schema": "^2.1.0",
+    "@jxsuite/site": "^1.1.0",
+    "@vue/reactivity": "3.5.42",
     "esbuild": "^0.28.2",
     "lit-html": "^3.3.3",
     "sharp": "^0.35.4"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.11.8",
-    "@jxsuite/connector": "^0.5.6",
-    "@jxsuite/parser": "^1.6.0",
+    "@happy-dom/global-registrator": "^20.12.0",
+    "@jxsuite/connector": "^0.5.7",
+    "@jxsuite/parser": "^1.7.0",
     "@types/mdast": "^4.0.4"
   }
 }

package/src/site/base-path.ts

@@ -0,0 +1,175 @@
+/**
+ * Base-path.ts — re-rooting a build's output onto the path the site is deployed under.
+ *
+ * A site at `https://example.pages.dev/m/my-site/` is served from `/m/my-site/`, and every
+ * absolute-path reference the build emits — `/assets/vue-reactivity.js`,
+ * `/components/site-counter.js`, `/images/hero.jpg` — resolves against `example.pages.dev/`
+ * instead, where nothing is. The page renders blank rather than merely wrong, because the runtime
+ * assets 404 first (issue 235).
+ *
+ * **The base is not a new option.** `project.json`'s `url` is the base URI every emitted reference
+ * is resolved against (RFC 3986 §5), and the compiler was resolving against its ORIGIN and
+ * discarding its path. `siteBasePath` in `@jxsuite/schema/asset-paths` reads the path back; a
+ * second `build.base` key would be a second writer on the one fact the canonical links and the
+ * sitemap are already built from, free to disagree with them.
+ *
+ * **The rewrite happens on finished HTML, and that is the point.** The alternative is to thread a
+ * prefix through the twelve emitters that can put a URL on a page — the import map and its
+ * modulepreloads, three page-template tiers that each write their own map, component scripts,
+ * island modules, sidecar and npm bundles, image `srcset`, `$head` entries, and whatever a page
+ * author wrote by hand. That list is exactly the kind that is complete until the next emitter is
+ * added, and #227 was already one emitter's map disagreeing with another's. One pass over the bytes
+ * that ship cannot drift from them.
+ *
+ * Outputs that are not HTML keep their own handling, because each has a syntax and none of them can
+ * be found by looking at a tag: `_headers`, `_redirects`, the service worker's precache list and
+ * scope, `manifest.webmanifest`, and the absolute URLs in `sitemap.xml` and `robots.txt`.
+ *
+ * Everything here is idempotent (see `withBase`), so a value an emitter already prefixed survives
+ * this pass unchanged.
+ *
+ * @docs framework/site/deployment
+ */
+
+import { formatSrcset, parseSrcset, withBase } from "@jxsuite/schema/asset-paths";
+
+/**
+ * Attributes whose value is a single URL.
+ *
+ * `href` and `src` are most of the traffic; the rest are the ones a Jx page can actually emit —
+ * `<form action>`, `<button formaction>`, `<video poster>`, `<object data>`. Anything not listed is
+ * left alone, which is the safe direction: a missed URL 404s visibly on a subpath deployment, while
+ * a rewritten non-URL corrupts a page that was working.
+ */
+const URL_ATTRS = new Set(["href", "src", "poster", "action", "formaction", "data"]);
+
+/** Attributes whose value is a `srcset` candidate list rather than one URL. */
+const SRCSET_ATTRS = new Set(["srcset", "imagesrcset"]);
+
+/**
+ * One HTML tag: the name, then attributes with quoted values consumed whole.
+ *
+ * Consuming quotes matters — a `>` inside an attribute value would otherwise end the tag early and
+ * leave the rest of its attributes as text this pass never looks at.
+ */
+const TAG_RE = /<([a-zA-Z][a-zA-Z0-9-]*)((?:"[^"]*"|'[^']*'|[^>"'])*)>/g;
+
+/** One attribute inside a tag's attribute blob. */
+const ATTR_RE = /([a-zA-Z_:][\w:.-]*)\s*=\s*("([^"]*)"|'([^']*)')/g;
+
+/** `url(...)` inside a CSS value, capturing the optional quote so it can be put back. */
+const CSS_URL_RE = /url\(\s*(['"]?)([^'")]+)\1\s*\)/g;
+
+/** A JSON string literal holding an absolute-path reference — an import map's keys and values. */
+const JSON_ABS_PATH_RE = /"(\/[^"/][^"]*)"/g;
+
+/** `<script type="importmap">…</script>`, whose body is JSON rather than markup. */
+const IMPORTMAP_RE = /(<script\b[^>]*\btype\s*=\s*["']importmap["'][^>]*>)([\s\S]*?)(<\/script>)/gi;
+
+/** `<style>…</style>`, whose body is CSS rather than markup. */
+const STYLE_BLOCK_RE = /(<style\b[^>]*>)([\s\S]*?)(<\/style>)/gi;
+
+/**
+ * `<meta>` names whose `content` is a URL.
+ *
+ * `content` is the one attribute here that usually holds prose, so it is rewritten only when the
+ * same tag says the value is a URL. OpenGraph and Twitter image/player metas are the cases a page
+ * actually produces from an author-written `/hero.jpg`.
+ */
+const URL_META_RE =
+  /\b(?:property|name)\s*=\s*["'](?:og:|twitter:)[\w:.-]*(?:image|url|video|audio|player)[\w:.-]*["']/i;
+
+/**
+ * A quote around a `url()` target that survived attribute escaping.
+ *
+ * In a `style` ATTRIBUTE the quotes inside `url("…")` are escaped, so the target arrives wrapped in
+ * `&quot;` rather than in a character {@link CSS_URL_RE} would have treated as a delimiter. Left
+ * alone the value no longer starts with `/` and is silently skipped — a background image that 404s
+ * on a subpath deployment with nothing to show for it.
+ */
+const ENTITY_QUOTE_RE = /^(&quot;|&#34;|&apos;|&#39;)([\s\S]*)\1$/;
+
+/** Rewrite every `url(...)` in a CSS fragment, in a `<style>` block or a `style` attribute. */
+function rewriteCssUrls(css: string, base: string): string {
+  return css.replaceAll(CSS_URL_RE, (match, quote: string, inner: string) => {
+    const raw = inner.trim();
+    const escaped = ENTITY_QUOTE_RE.exec(raw);
+    const target = escaped ? escaped[2]! : raw;
+    const out = withBase(base, target);
+    if (out === target) {
+      return match;
+    }
+    return `url(${quote}${escaped ? `${escaped[1]}${out}${escaped[1]}` : out}${quote})`;
+  });
+}
+
+/** Rewrite one attribute value, or return it unchanged when the attribute carries no URL. */
+function rewriteAttrValue(tag: string, attrs: string, name: string, value: string, base: string) {
+  const lower = name.toLowerCase();
+  if (URL_ATTRS.has(lower)) {
+    return withBase(base, value);
+  }
+  if (SRCSET_ATTRS.has(lower)) {
+    const candidates = parseSrcset(value);
+    return candidates.length === 0
+      ? value
+      : formatSrcset(
+          candidates.map((c) => ({ descriptor: c.descriptor, url: withBase(base, c.url) })),
+        );
+  }
+  if (lower === "style") {
+    return rewriteCssUrls(value, base);
+  }
+  if (lower === "content" && tag === "meta" && URL_META_RE.test(attrs)) {
+    return withBase(base, value);
+  }
+  return value;
+}
+
+/**
+ * Re-root every site-absolute URL in a page's HTML onto `base`.
+ *
+ * `base` of `""` is a site at an origin root, and the HTML is returned untouched — no allocation
+ * and no risk for the deployment Jx documents.
+ *
+ * @param {string} html - A finished page
+ * @param {string} base - From `siteBasePath`
+ * @returns {string} The page as it should ship
+ */
+export function rewriteHtmlBase(html: string, base: string): string {
+  if (base === "") {
+    return html;
+  }
+
+  let out = html.replaceAll(IMPORTMAP_RE, (_match, open: string, body: string, close: string) => {
+    /* The import map's KEYS are addressable too: a map may name a module by URL rather than by bare
+       specifier, and a key left at the old root would resolve to a file the build did not write. */
+    const rewritten = body.replaceAll(
+      JSON_ABS_PATH_RE,
+      (_literal, path: string) => `"${withBase(base, path)}"`,
+    );
+    return open + rewritten + close;
+  });
+
+  out = out.replaceAll(
+    STYLE_BLOCK_RE,
+    (_m, open: string, css: string, close: string) => open + rewriteCssUrls(css, base) + close,
+  );
+
+  return out.replaceAll(TAG_RE, (match, tagName: string, attrs: string) => {
+    if (attrs === "") {
+      return match;
+    }
+    const tag = tagName.toLowerCase();
+    const rewrittenAttrs = attrs.replaceAll(
+      ATTR_RE,
+      (whole, name: string, _quoted: string, dq: string | undefined, sq: string | undefined) => {
+        const quote = dq === undefined ? "'" : '"';
+        const value = dq ?? sq ?? "";
+        const next = rewriteAttrValue(tag, attrs, name, value, base);
+        return next === value ? whole : `${name}=${quote}${next}${quote}`;
+      },
+    );
+    return rewrittenAttrs === attrs ? match : `<${tagName}${rewrittenAttrs}>`;
+  });
+}

package/src/site/headers-emitter.ts

@@ -11,6 +11,7 @@
  * @docs framework/site/deployment
  */
 
+import { withBase } from "@jxsuite/schema/asset-paths";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { buildCspHeaders, normalizeCspConfig } from "./csp.ts";
@@ -181,6 +182,25 @@ export function contentTypeRules(outDir: string): HeaderRule[] {
   return rules;
 }
 
+/**
+ * Re-root every rule's pattern onto the deployment base.
+ *
+ * A `_headers` pattern is matched against the REQUEST path, so on a site served from `/m/my-site/`
+ * a rule for `/assets/*` matches nothing at all — which is silent, because a missing cache header
+ * is a slow site rather than a broken one. The generated patterns and the author's `build.headers`
+ * rules go through together: both describe the same URL space.
+ *
+ * @param {readonly HeaderRule[]} rules
+ * @param {string} base - From `siteBasePath`; `""` returns the rules untouched
+ * @returns {HeaderRule[]}
+ */
+export function rebaseHeaderRules(rules: readonly HeaderRule[], base: string): HeaderRule[] {
+  if (base === "") {
+    return [...rules];
+  }
+  return rules.map((rule) => ({ headers: rule.headers, pattern: withBase(base, rule.pattern) }));
+}
+
 /** Render rules in the Netlify / Cloudflare Pages `_headers` format. */
 export function renderHeaders(rules: readonly HeaderRule[]): string {
   const blocks = rules.map((rule) => {

package/src/site/i18n.ts

@@ -12,6 +12,7 @@
  * @docs framework/site/i18n
  */
 
+import { siteAbsoluteUrl } from "@jxsuite/schema/asset-paths";
 import {
   canonicalizeLocale,
   localeDirection,
@@ -298,13 +299,13 @@ export function localeAlternates(
     let alternates = built.get(members);
     if (alternates === undefined) {
       alternates = members.map((m) => ({
-        href: new URL(m.urlPattern, siteUrl).href,
+        href: siteAbsoluteUrl(m.urlPattern, siteUrl),
         hreflang: m.locale,
       }));
       const fallback = members.find((m) => m.locale === i18n.defaultLocale);
       if (fallback !== undefined) {
         alternates.push({
-          href: new URL(fallback.urlPattern, siteUrl).href,
+          href: siteAbsoluteUrl(fallback.urlPattern, siteUrl),
           hreflang: "x-default",
         });
       }

package/src/site/service-worker.ts

@@ -20,6 +20,7 @@
  * @docs framework/site/deployment
  */
 
+import { withBase } from "@jxsuite/schema/asset-paths";
 import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
@@ -100,6 +101,7 @@ function configId(config: ServiceWorkerConfig): string {
 export function buildServiceWorker(
   config: ServiceWorkerConfig,
   outDir?: string,
+  base = "",
 ): ServiceWorkerOutput {
   const warnings: string[] = [];
   const errors: string[] = [];
@@ -140,15 +142,26 @@ export function buildServiceWorker(
     }
   }
 
+  /*
+   * The worker runs in the browser and every URL in it is a REQUEST path, so on a site served from
+   * `/m/my-site/` the base belongs on all three: a precache entry without it fetches a 404, and
+   * `CACHE_FIRST` without it never matches, so the content-addressed images it exists to serve
+   * from cache go to the network on every view. `outputFileFor` above is deliberately checked
+   * BEFORE this — those URLs are looked up in `outDir`, which has no base.
+   */
+  const cachedPrecache = precache.map((url) => withBase(base, url));
+  const cacheFirst = withBase(base, CACHE_FIRST_PREFIX);
+  const offlineFallback = fallback === undefined ? null : withBase(base, fallback);
+
   const cache = `jx-${configId(config)}`;
   const source = `/*
  * Generated by @jxsuite/compiler — configure via \`serviceWorker\` in project.json.
  * Set \`"serviceWorker": false\` to replace this with a worker that removes itself.
  */
 const CACHE = ${JSON.stringify(cache)};
-const PRECACHE = ${JSON.stringify(precache)};
-const CACHE_FIRST = ${JSON.stringify(CACHE_FIRST_PREFIX)};
-const OFFLINE_FALLBACK = ${JSON.stringify(fallback ?? null)};
+const PRECACHE = ${JSON.stringify(cachedPrecache)};
+const CACHE_FIRST = ${JSON.stringify(cacheFirst)};
+const OFFLINE_FALLBACK = ${JSON.stringify(offlineFallback)};
 
 self.addEventListener("install", (event) => {
   // Take over as soon as possible: a half-updated pair of workers is harder to reason about than
@@ -285,10 +298,14 @@ self.addEventListener("activate", (event) => {
  * @param {string} scope
  * @returns {string}
  */
-export function registrationScript(scope: string): string {
+export function registrationScript(scope: string, base = ""): string {
+  /* Both are request paths. A worker's scope may not exceed its own directory, so a worker served
+     from `/m/my-site/sw.js` with a scope of `/` fails to register outright — the one failure here
+     that is loud rather than silent. */
+  const worker = withBase(base, `/${SERVICE_WORKER_PATH}`);
   return (
     `if('serviceWorker' in navigator){addEventListener('load',function(){` +
-    `navigator.serviceWorker.register('/${SERVICE_WORKER_PATH}',{scope:${JSON.stringify(scope)}})` +
+    `navigator.serviceWorker.register('${worker}',{scope:${JSON.stringify(withBase(base, scope))}})` +
     `.catch(function(){})})}`
   );
 }

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";
@@ -519,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[] = [];
 
@@ -714,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
@@ -735,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 }),
         });
       }
@@ -835,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
@@ -1014,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,
     });
@@ -1091,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);
       }
@@ -1115,7 +1140,7 @@ 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);
@@ -1215,6 +1240,10 @@ 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);
 
@@ -1364,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
@@ -1528,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()) {
@@ -1546,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,
     };
   });
@@ -2369,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[] = [];
@@ -2396,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("*")) {
@@ -2563,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-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;
   }