@jxsuite/compiler 2.0.7 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "2.0.7",
+  "version": "3.0.0",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {
@@ -42,22 +42,23 @@
     "build:site": "bun src/cli.ts build",
     "test": "bun test --isolate",
     "test:coverage": "bun test --isolate --coverage",
-    "upgrade": "bunx npm-check-updates -u && bun install"
+    "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@apidevtools/json-schema-ref-parser": "^16.0.0",
-    "@jxsuite/create": "^1.3.6",
-    "@jxsuite/runtime": "^2.0.5",
-    "@jxsuite/schema": "^1.8.1",
+    "@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",
     "esbuild": "^0.28.2",
     "lit-html": "^3.3.3",
-    "sharp": "^0.35.3"
+    "sharp": "^0.35.4"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.11.6",
-    "@jxsuite/connector": "^0.5.4",
-    "@jxsuite/parser": "^1.5.5",
+    "@happy-dom/global-registrator": "^20.11.8",
+    "@jxsuite/connector": "^0.5.6",
+    "@jxsuite/parser": "^1.6.0",
     "@types/mdast": "^4.0.4"
   }
 }

package/src/shared.ts

@@ -10,8 +10,11 @@ import {
   COLOR_SCHEME_ATTR,
   COLOR_SCHEME_STORAGE_KEY,
   RESERVED_KEYS,
+  booleanAttrValue,
   camelToKebab,
+  isSingleExpression,
   pureSchemeOf,
+  resolveAtQuery,
   schemeSelectors,
   toCSSText,
 } from "@jxsuite/runtime";
@@ -54,7 +57,9 @@ export {
   COLOR_SCHEME_ATTR,
   COLOR_SCHEME_STORAGE_KEY,
   RESERVED_KEYS,
+  booleanAttrValue,
   camelToKebab,
+  isSingleExpression,
   pureSchemeOf,
   schemeSelectors,
   toCSSText,
@@ -106,11 +111,26 @@ export function emitFormulaFn(def: { parameters?: unknown[] }, compiledBody: str
  * @returns {string}
  */
 export function srcImportBinding(key: string, def: unknown) {
-  const declared = (def as { $export?: unknown } | null | undefined)?.$export;
-  const exportName = typeof declared === "string" && declared !== "" ? declared : key;
+  const exportName = srcExportName(key, def);
   return exportName === key ? key : `${exportName} as ${key}`;
 }
 
+/**
+ * The export a Function-def `$src` entry names inside its module: `$export`, or the state key.
+ *
+ * Separate from {@link srcImportBinding} because a lazily loaded `$src` has no import clause to
+ * alias in — it reaches the export off the module namespace object a dynamic `import()` resolves
+ * to, where the local name is chosen by the generated code and only the export name is fixed.
+ *
+ * @param {string} key - State key
+ * @param {unknown} def - The Function definition
+ * @returns {string}
+ */
+export function srcExportName(key: string, def: unknown): string {
+  const declared = (def as { $export?: unknown } | null | undefined)?.$export;
+  return typeof declared === "string" && declared !== "" ? declared : key;
+}
+
 /**
  * Emit the auto-fetch `effect()` for a `$prototype: "Request"` state entry.
  *
@@ -799,8 +819,7 @@ export function evaluateStaticTemplate(str: string, scope: Record<string, unknow
   const args = ["state", "$map", "$site", "$page"] as const;
   const values = [scope, scope?.$map, scope?.$site, scope?.$page];
   try {
-    const singleExprMatch = str.match(/^\$\{(.+)\}$/s);
-    const body = singleExprMatch ? `return (${singleExprMatch[1]})` : `return \`${str}\``;
+    const body = isSingleExpression(str) ? `return (${str.slice(2, -1)})` : `return \`${str}\``;
     const fn = new Function(...args, body) as (...a: unknown[]) => unknown;
     return fn(...values);
   } catch {
@@ -896,10 +915,34 @@ export function buildAttrs(def: JxElement | JxMutableNode, scope: Record<string,
   if (def.attributes) {
     for (const [k, v] of Object.entries(def.attributes)) {
       const value = resolveStaticValue(v, scope);
+      /*
+       * A boolean is the attribute's PRESENCE or its text, depending on which family HTML puts the
+       * attribute in — `booleanAttrValue` owns that judgement, and the runtime asks it the same
+       * question so a prerendered page cannot change meaning as it hydrates.
+       *
+       * @docs framework/concepts/elements
+       *
+       * Stringifying a boolean emitted `open="false"`, and HTML reads a boolean attribute by
+       * Presence alone — so the author wrote "closed" and the page rendered open. Nor could the
+       * Template return nothing instead: `resolveDocTemplates` and `expandMapTemplate` both `?? v`,
+       * Which restores the raw `${…}` source on a null. Absence therefore has to be expressible
+       * HERE, and `false` is the only value that can mean it.
+       *
+       * A *string* is never reinterpreted, in either family. `"aria-current": "false"` is the docs
+       * Sidebar's own not-the-current-page marker, and second-guessing it would be this same defect
+       * Pointed the other way.
+       */
+      if (typeof value === "boolean") {
+        const text = booleanAttrValue(k, value);
+        if (text !== null) {
+          out += text === "" ? ` ${k}` : ` ${k}="${escapeHtml(text)}"`;
+        }
+        continue;
+      }
       if (
         value !== null &&
         value !== undefined &&
-        (typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+        (typeof value === "string" || typeof value === "number")
       ) {
         out += ` ${k}="${escapeHtml(String(value))}"`;
       }
@@ -1013,11 +1056,7 @@ function conditionalRuleEmitter(
   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 query = resolveAtQuery(atKey, mediaQueries);
   const atRule = query === null ? atKey : `@media ${query}`;
   const scheme = query === null ? null : pureSchemeOf(query);
   return (selector: string, props: string) => {
@@ -1206,7 +1245,20 @@ export function compileStyles(
   if (rules.length === 0) {
     return "";
   }
-  return `<style>\n${rules.join("\n")}\n</style>`;
+  return `<style>\n${escapeStyleText(rules.join("\n"))}\n</style>`;
+}
+
+/**
+ * Make CSS safe to sit inside a `<style>` element.
+ *
+ * An HTML parser ends a `<style>` at the first `</style` in the text, wherever it appears — inside
+ * a CSS string, inside a comment, anywhere. Since a project's style values are author data
+ * (`content: "</style>"` is a legal declaration), inlining them unescaped would let content close
+ * the element and the rest of the stylesheet would render as markup. `\/` is a valid CSS escape for
+ * `/`, so the declaration keeps its meaning.
+ */
+export function escapeStyleText(css: string): string {
+  return css.replaceAll(/<\/(?=style)/gi, String.raw`<\/`);
 }
 
 /**
@@ -1513,6 +1565,40 @@ export function resolveStaticTagName(
   return expression.cases[String(key)] ?? expression.default;
 }
 
+/**
+ * The content of one node: `textContent`, else `innerHTML`, else rendered `children`.
+ *
+ * Shared with `preRenderComponentHtml`, which returns a component's innerHTML and so cannot call
+ * `renderStaticNode` (that would wrap the result in the host tag). It used to look at `children`
+ * alone and return "" for anything else, so a component whose content is root-level `textContent` —
+ * the shape spec.md §17.2 recommends when every child is a bare string — prerendered to nothing.
+ *
+ * @param {JxElement | JxMutableNode} node
+ * @param {Record<string, unknown> | null} scope
+ * @param {string | null} slotContent
+ * @returns {string}
+ */
+function renderInner(
+  node: JxElement | JxMutableNode,
+  scope: Record<string, unknown> | null,
+  slotContent: string | null,
+): string {
+  if (node.textContent !== undefined) {
+    const val = resolveStaticValue(node.textContent, scope);
+    return val != null ? escapeHtml(String(val)) : "";
+  }
+  if (node.innerHTML) {
+    const val = resolveStaticValue(node.innerHTML, scope);
+    return val != null ? String(val) : (node.innerHTML as string);
+  }
+  if (Array.isArray(node.children)) {
+    return node.children
+      .map((c: JxElement | JxMutableNode | string) => renderStaticNode(c, scope, slotContent))
+      .join("\n");
+  }
+  return "";
+}
+
 /**
  * Recursively render a Jx node tree to static HTML for pre-rendering.
  *
@@ -1587,20 +1673,7 @@ export function renderStaticNode(
     return `<${tag}${attrs}>`;
   }
 
-  let inner = "";
-  if (node.textContent !== undefined) {
-    const val = resolveStaticValue(node.textContent, scope);
-    inner = val != null ? escapeHtml(String(val)) : "";
-  } else if (node.innerHTML) {
-    const val = resolveStaticValue(node.innerHTML, scope);
-    inner = val != null ? String(val) : (node.innerHTML as string);
-  } else if (Array.isArray(node.children)) {
-    inner = node.children
-      .map((c: JxElement | JxMutableNode | string) => renderStaticNode(c, scope, slotContent))
-      .join("\n");
-  }
-
-  return `<${tag}${attrs}>${inner}</${tag}>`;
+  return `<${tag}${attrs}>${renderInner(node, scope, slotContent)}</${tag}>`;
 }
 
 /**
@@ -1636,12 +1709,7 @@ export function preRenderComponentHtml(
     }
   }
   const scope = buildInitialScope(stateDefs, null);
-  if (!Array.isArray(doc.children)) {
-    return "";
-  }
-  return doc.children
-    .map((c: JxElement | JxMutableNode | string) => renderStaticNode(c, scope, slotContent))
-    .join("\n");
+  return renderInner(doc, scope, slotContent);
 }
 
 /**

package/src/site/bundler.ts

@@ -92,6 +92,14 @@ export interface BundleOptions {
   conditions?: string[];
   /** Resolution hooks, applied before the bundler's own resolution. */
   resolver?: BundleResolver;
+  /**
+   * Whether to minify the bundle.
+   *
+   * Defaults to true for `target: "browser"` and false everywhere else: browser output is parsed on
+   * someone else's phone, server output is read off a stack trace. Callers override it — the site
+   * build from `build.minify`, and `jx dev` to keep a breakpoint on a line somebody wrote.
+   */
+  minify?: boolean;
   /**
    * Called with the absolute path of every file the bundler loads.
    *
@@ -161,6 +169,21 @@ export function workerBundleOptions(adapter: string): BundleOptions {
  */
 const BROWSER_DEFINE = { "process.env.NODE_ENV": '"production"' } as const;
 
+/**
+ * Whether this bundle is minified.
+ *
+ * Browser output defaults to minified and everything else to readable. Measured on jxsuite.com's
+ * own deployed bytes, the six scripts a page loads go from 155,254 B to 64,994 B — and it is the 90
+ * kB of source a phone no longer has to parse, not the 16 kB it no longer downloads, that moves
+ * Total Blocking Time.
+ *
+ * This widens the backend divergence {@link BROWSER_DEFINE} warns about: the two minifiers agree on
+ * semantics, not on bytes. A build that diffs `dist/` must pin one backend (`JX_BUNDLER=esbuild`).
+ */
+function shouldMinify(opts: BundleOptions): boolean {
+  return opts.minify ?? opts.target === "browser";
+}
+
 /** 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";
@@ -193,7 +216,7 @@ export async function bundleEntry(request: BundleRequest, opts: BundleOptions):
       external,
       format: "esm",
       logLevel: "silent",
-      minify: false,
+      minify: shouldMinify(opts),
       outfile: request.outfile,
       platform: esbuildPlatform(opts.target),
       plugins: plugins as unknown as NonNullable<Parameters<typeof esbuild.build>[0]["plugins"]>,
@@ -207,7 +230,7 @@ export async function bundleEntry(request: BundleRequest, opts: BundleOptions):
     entrypoints: [request.entryPath],
     external,
     format: "esm",
-    minify: false,
+    minify: shouldMinify(opts),
     plugins,
     target: bunTarget(opts.target),
     throw: false,
@@ -254,7 +277,8 @@ export async function resolveThroughBundler(
     await bundleSource(
       `export * from ${JSON.stringify(specifier)};\n`,
       { outfile, resolveDir },
-      { ...opts, onFileLoaded: (path) => loaded.push(path) },
+      // The output is deleted in `finally` — this only wants the resolution, so never pay to minify.
+      { ...opts, minify: false, onFileLoaded: (path) => loaded.push(path) },
     );
   } catch {
     return undefined;
@@ -286,7 +310,7 @@ export async function bundleSource(
       external: opts.external ?? [],
       format: "esm",
       logLevel: "silent",
-      minify: false,
+      minify: shouldMinify(opts),
       outfile,
       platform: esbuildPlatform(opts.target),
       stdin: { contents: source, loader: "js", resolveDir, sourcefile: "jx-entry.js" },

package/src/site/client-runtime.ts

@@ -15,7 +15,7 @@
  * @docs framework/build
  */
 
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join, relative, resolve } from "node:path";
 import type { BundleResolver } from "./bundler.ts";
@@ -84,7 +84,15 @@ export interface ClientRuntime {
  * @param {string} [resolveDir] - Directory bare specifiers resolve from; defaults to this package
  * @returns {ClientRuntime}
  */
-export function resolveClientRuntime(resolveDir: string = import.meta.dir): ClientRuntime {
+/**
+ * This package's own directory, resolved under both runtimes. `import.meta.dir` is Bun-only and is
+ * `undefined` under Node — and `bin/jx.js` carries a Node shebang, so every `bunx jx build` took
+ * that path, `join(undefined, …)` threw, the bare catch read it as "cannot resolve", and the import
+ * map fell back to the esm.sh CDN. `import.meta.dirname` is defined on both.
+ */
+const PACKAGE_DIR = import.meta.dirname;
+
+export function resolveClientRuntime(resolveDir: string = PACKAGE_DIR): ClientRuntime {
   const imports: Record<string, string> = {};
   const warnings: string[] = [];
   const assetPaths: string[] = [];
@@ -122,7 +130,8 @@ export function resolveClientRuntime(resolveDir: string = import.meta.dir): Clie
 export async function writeClientRuntime(
   runtime: ClientRuntime,
   outDir: string,
-  resolveDir: string = import.meta.dir,
+  resolveDir: string = PACKAGE_DIR,
+  minify = true,
 ): Promise<{ written: number; errors: string[] }> {
   const errors: string[] = [];
   let written = 0;
@@ -142,7 +151,7 @@ export async function writeClientRuntime(
       await bundleSource(
         `export * from ${JSON.stringify(mod.specifier)};\n`,
         { outfile, resolveDir },
-        { target: "browser" },
+        { minify, target: "browser" },
       );
       written += 1;
     } catch (error) {
@@ -152,6 +161,52 @@ export async function writeClientRuntime(
   return { errors, written };
 }
 
+/**
+ * The asset paths an import map's `imports` object asks THIS build to write.
+ *
+ * Two kinds of entry are named by a map and produced by nobody: a prefix key's value is the
+ * DIRECTORY its subpaths are served from — `/assets/lit-html/` — rather than a file, and a CDN
+ * fallback belongs to a third party. What is left is the exact set `writeClientRuntime` matches
+ * against, so the promise the HTML makes and the bundles the build writes are read off one rule.
+ */
+export function importMapAssets(imports: Record<string, string>): string[] {
+  return Object.entries(imports)
+    .filter(([specifier, url]) => !isPrefixSpecifier(specifier) && url.startsWith("/"))
+    .map(([, url]) => url);
+}
+
+/**
+ * The same set, read back out of a finished page.
+ *
+ * A page reaches an import map by more than one route: `injectComponentScripts` adds one, and the
+ * page-template tiers in `compile-static`/`compile-client`/`compile-element` emit their own. Only
+ * the first of those was recording what it named, so a project with interactivity but no components
+ * shipped a map pointing at `/assets/vue-reactivity.js` while the set that gates bundling stayed
+ * empty — nothing was written, the page 404'd on both modules and rendered blank, and the build
+ * reported success (issue #227). Scanning the emitted HTML is what makes the two agree no matter
+ * which path produced the map.
+ */
+export function importMapAssetsInHtml(html: string): string[] {
+  const found: string[] = [];
+  for (const match of html.matchAll(/<script type="importmap">([\s\S]*?)<\/script>/g)) {
+    let imports: unknown;
+    try {
+      ({ imports } = JSON.parse(match[1] as string) as { imports?: unknown });
+    } catch {
+      // A map the build did not write and cannot parse names nothing this build must produce.
+      continue;
+    }
+    if (typeof imports !== "object" || imports === null) {
+      continue;
+    }
+    const entries = Object.entries(imports as Record<string, unknown>).filter(
+      (entry): entry is [string, string] => typeof entry[1] === "string",
+    );
+    found.push(...importMapAssets(Object.fromEntries(entries)));
+  }
+  return found;
+}
+
 /** Render the `<script type="importmap">` block for a resolved runtime. */
 export function renderImportMap(imports: Record<string, string>): string {
   const entries = Object.entries(imports)
@@ -208,11 +263,13 @@ const MAX_SUBPATH_PASSES = 10;
  *
  * @param {string} outDir - Build output root
  * @param {string} [resolveDir] - Directory bare specifiers resolve from
+ * @param {boolean} [minify] - Minify the emitted bundles (defaults to the browser-target default)
  * @returns {Promise<{ written: number; errors: string[] }>}
  */
 export async function writeRuntimeSubpaths(
   outDir: string,
-  resolveDir: string = import.meta.dir,
+  resolveDir: string = PACKAGE_DIR,
+  minify = true,
 ): Promise<{ written: number; errors: string[] }> {
   const errors: string[] = [];
   const done = new Set<string>();
@@ -235,7 +292,7 @@ export async function writeRuntimeSubpaths(
 
   /** `from "lit-html/directives/class-map.js"` — the import forms a bundler emits. */
   const importedSpecifiers = async (file: string): Promise<string[]> => {
-    const text = await Bun.file(file).text();
+    const text = readFileSync(file, "utf8");
     return [...text.matchAll(/(?:from|import)\s*["']([^"']+)["']/g)].map((m) => m[1] as string);
   };
 
@@ -243,9 +300,10 @@ export async function writeRuntimeSubpaths(
     let discovered = 0;
     let files: string[] = [];
     try {
-      files = await Array.fromAsync(
-        new Bun.Glob("**/*.js").scan({ absolute: true, cwd: assetsDir }),
-      );
+      files = readdirSync(assetsDir, { recursive: true })
+        .map(String)
+        .filter((entry) => entry.endsWith(".js"))
+        .map((entry) => join(assetsDir, entry));
     } catch {
       return finish(outDir, mirrors, errors, written);
     }
@@ -271,6 +329,7 @@ export async function writeRuntimeSubpaths(
             `export * from ${JSON.stringify(specifier)};\n`,
             { outfile, resolveDir },
             {
+              minify,
               resolver: shareRuntimeCore(mod, outfile, await coreOf(mod), mirrors),
               target: "browser",
             },

package/src/site/context-injection.ts

@@ -1,40 +1,39 @@
 /**
- * Context-injection.js — $page and $site context injection
+ * The build's filesystem half of context injection.
  *
- * Injects project-level and page-level context variables into a page's state before compilation.
- * These are available as $site.* and $page.* in template expressions.
- *
- * Per site-architecture spec §10: $site.name — from project.json name $site.url — from project.json
- * url $site.state.* — site-wide reactive state $page.url — current page URL path $page.title — page
- * title $page.params — dynamic route parameters (if any) $page.locale/$page.dir — the route's
- * language and writing direction (§13.4) $page.alternates — this page in every language it exists
- * in (§13.5)
+ * `injectContext` itself is `@jxsuite/site/context` — a live renderer binds `${$site.name}` and
+ * `${$page.url}` exactly as a built page does, so the two must not be separate implementations.
+ * What is left here is the one thing that needs real directories: rebasing a project-level relative
+ * `imports` entry onto the page's own directory.
  *
  * @docs framework/site/i18n
  */
 
 import { dirname, relative, resolve } from "node:path";
-import type {
-  JxDocument,
-  JxElement,
-  JxStateDefinition,
-  ProjectConfig,
-} from "@jxsuite/schema/types";
-import { localeDirection, localeLabel } from "@jxsuite/schema/locale";
-import { localeOfRoute } from "./i18n.ts";
-import type { ResolvedI18n, TranslationMember } from "./i18n.ts";
-import type { SiteRoute } from "../types.ts";
+import { injectContext as injectContextWith } from "@jxsuite/site/context";
+import type { ImportRebaser, SiteRoute, TranslationMember } from "@jxsuite/site/context";
+import type { ResolvedI18n } from "@jxsuite/schema/locale";
+import type { JxDocument, ProjectConfig } from "@jxsuite/schema/types";
+
+/** An {@link ImportRebaser} over a project on disk. */
+export function nodeImportRebaser(projectRoot: string): ImportRebaser {
+  return (src, route) => {
+    if (!route.sourcePath) {
+      return src;
+    }
+    return `./${relative(dirname(route.sourcePath), resolve(projectRoot, src))}`;
+  };
+}
 
 /**
- * Inject $site and $page context into a page document's state.
+ * Inject $site and $page context for a page compiled from a project on disk.
  *
  * @param {JxDocument} doc - The page document (mutated)
  * @param {ProjectConfig} projectConfig - Loaded project configuration
  * @param {SiteRoute} route - The resolved route for this page
  * @param {string | null} [projectRoot] - Absolute path to the project root (for import rebasing)
  * @param {ResolvedI18n | null} [i18n] - Validated locale config, when the project declares one
- * @param {readonly TranslationMember[]} [translations] - This route's translation set, itself
- *   included
+ * @param {readonly TranslationMember[]} [translations] - This route's translation set
  * @returns {JxDocument} The mutated document
  */
 export function injectContext(
@@ -44,110 +43,13 @@ export function injectContext(
   projectRoot: string | null = null,
   i18n: ResolvedI18n | null = null,
   translations: readonly TranslationMember[] = [],
-) {
-  if (!doc.state) {
-    doc.state = {};
-  }
-
-  // $site context — read-only project-level data
-  doc.state.$site = {
-    name: projectConfig.name ?? "Jx Site",
-    url: projectConfig.url ?? "",
-    ...(i18n === null ? {} : { defaultLocale: i18n.defaultLocale, locales: i18n.locales }),
-    ...projectConfig.state,
-  };
-
-  /*
-   * $page context — read-only page-level data.
-   *
-   * The locale lives here rather than as a top-level `$locale` because that is what it is: a
-   * property of the route, not a third ambient namespace beside $site and $page. A document's own
-   * `$lang` still wins over the route's locale, so this is the resolved answer, not the prefix.
-   */
-  const pageLang =
-    (typeof doc.$lang === "string" ? doc.$lang : undefined) ??
-    localeOfRoute(route.urlPattern, i18n) ??
-    projectConfig.defaults?.lang;
-  /*
-   * The same translation set `<head>` advertises, in the shape a template can render: a language
-   * switcher is the one part of a multilingual site the framework cannot write for the author, and
-   * without this it could only be hand-maintained — a hardcoded list of URLs that goes stale the
-   * moment a page gains or loses a translation, silently, in the one place a reader would use it.
-   *
-   * Site-absolute URLs, not the absolute hrefs `<head>` needs: a switcher is an internal link, and
-   * it has to work before `url` is configured. `current` marks the member this route *is*, taken
-   * from the route rather than from `$page.locale`, because a document whose `$lang` disagrees with
-   * its directory is still served from that directory.
-   */
-  const alternates = translations.map((member) => ({
-    code: member.locale,
-    current: member.urlPattern === route.urlPattern,
-    dir: localeDirection(member.locale),
-    label: localeLabel(member.locale),
-    url: member.urlPattern,
-  }));
-  doc.state.$page = {
-    params: route._pathParams ?? {},
-    title: doc.title ?? doc._pageTitle ?? projectConfig.name ?? "",
-    url: route.urlPattern,
-    ...(alternates.length > 0 && { alternates }),
-    ...(pageLang === undefined ? {} : { dir: localeDirection(pageLang), locale: pageLang }),
-  };
-
-  // Merge project-level state into page state (page wins on conflicts)
-  if (projectConfig.state) {
-    for (const [key, value] of Object.entries(projectConfig.state)) {
-      if (key !== "$site" && key !== "$page" && !(key in doc.state)) {
-        doc.state[key] = value as JxStateDefinition;
-      }
-    }
-  }
-
-  // Merge project-level $media into page $media
-  if (projectConfig.$media) {
-    doc.$media = { ...projectConfig.$media, ...doc.$media };
-  }
-
-  // Merge project-level imports into page imports (page wins on collision)
-  if (projectConfig.imports && Object.keys(projectConfig.imports).length > 0) {
-    if (!doc.imports) {
-      doc.imports = {};
-    }
-    for (const [name, srcPath] of Object.entries(projectConfig.imports)) {
-      if (!(name in doc.imports)) {
-        const src = srcPath as string;
-        // Only rebase relative paths — bare/npm specifiers pass through unmodified
-        if (projectRoot && route.sourcePath && (src.startsWith("./") || src.startsWith("../"))) {
-          const abs = resolve(projectRoot, src);
-          doc.imports[name] = `./${relative(dirname(route.sourcePath), abs)}`;
-        } else {
-          doc.imports[name] = src;
-        }
-      }
-    }
-  }
-
-  // Merge project-level $elements into page $elements (union, dedup)
-  if (projectConfig.$elements?.length) {
-    if (!doc.$elements?.length) {
-      doc.$elements = [...projectConfig.$elements];
-    } else {
-      const seen = new Set<string>();
-      const merged: (string | JxElement)[] = [];
-      for (const entry of [
-        ...projectConfig.$elements,
-        ...(doc.$elements as (string | JxElement)[]),
-      ]) {
-        const key =
-          typeof entry === "string" ? entry : /** @type {{ $ref?: string }} */ entry?.$ref;
-        if (key && !seen.has(key)) {
-          seen.add(key);
-          merged.push(entry);
-        }
-      }
-      doc.$elements = merged;
-    }
-  }
-
-  return doc;
+): JxDocument {
+  return injectContextWith(
+    doc,
+    projectConfig,
+    route,
+    projectRoot === null ? null : nodeImportRebaser(projectRoot),
+    i18n,
+    translations,
+  );
 }