@jxsuite/compiler 1.1.0 → 1.3.0

package/src/site/prototype-resolver.ts

@@ -79,6 +79,7 @@ export async function resolvePrototypes(
     config?: Record<string, unknown>;
     sections?: Record<string, unknown>;
     registry?: ExtensionRegistry;
+    registerBundle?: (specifier: string) => void;
   } = {},
 ) {
   const imports = doc.imports ?? {};
@@ -107,6 +108,20 @@ export async function resolvePrototypes(
             root: projectRoot,
             route,
           });
+          // A lowered def may name client modules it depends on via `$bundle`
+          // (extensions.md §8.3): the site build bundles each specifier for the browser.
+          // The key is host metadata, not part of the core def shape — strip it.
+          if (lowered && typeof lowered === "object" && !Array.isArray(lowered)) {
+            const bundles = (lowered as JsonObject).$bundle;
+            if (Array.isArray(bundles)) {
+              for (const specifier of bundles) {
+                if (typeof specifier === "string") {
+                  projectContext.registerBundle?.(specifier);
+                }
+              }
+            }
+            delete (lowered as JsonObject).$bundle;
+          }
           state[key] = lowered as JxStateDefinition;
         } catch (error) {
           console.warn(

package/src/site/schema-command.ts

@@ -3,10 +3,12 @@
  *
  * Composes the per-project entry documents (project.schema.json and document.schema.json) from the
  * core schemas and each enabled extension's shipped fragments, then writes them into the project
- * root as committed artifacts. All fragment refs are PROJECT-RELATIVE, POSIX-style `./` paths:
- * paths that resolve inside the project are emitted as-is; bare-specifier packages resolving
- * through workspace symlinks (outside the root) fall back to the conventional
- * `./node_modules/<package>/<subpath>` form, which resolves once dependencies are installed.
+ * root as committed, SELF-CONTAINED bundles: every fragment ref is resolved through
+ * {@link bundleSchema}, embedding the core + fragment resources under `$defs` keyed by their
+ * canonical `$id`s. Relative `./node_modules/...` refs only resolve through Node module resolution,
+ * which editors do not perform (hoisted workspaces leave projects without their own node_modules) —
+ * the bundled form resolves offline for ajv `jx validate`, VS Code's JSON language service, and the
+ * studio's Monaco alike, with one resolution behavior for all consumers.
  */
 
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -57,11 +59,22 @@ export async function writeProjectSchemas(projectRoot: string) {
     }
   }
 
-  const projectSchema = emitProjectSchema({ corePath, fieldSchemaRefs, fragments });
-  const documentSchema = emitDocumentSchema({
-    corePath: coreSchemaRef(projectRoot, CORE_DOCUMENT_SPECIFIER),
-    pathsValueRefs,
-  });
+  // Bundle before committing: the emitted relative refs are an intermediate form only.
+  const root = resolve(projectRoot);
+  const loadJson = restrictedSchemaLoader(root);
+  const projectSchema = await bundleSchema(
+    emitProjectSchema({ corePath, fieldSchemaRefs, fragments }),
+    loadJson,
+    root,
+  );
+  const documentSchema = await bundleSchema(
+    emitDocumentSchema({
+      corePath: coreSchemaRef(projectRoot, CORE_DOCUMENT_SPECIFIER),
+      pathsValueRefs,
+    }),
+    loadJson,
+    root,
+  );
 
   const projectSchemaPath = resolve(projectRoot, "project.schema.json");
   const documentSchemaPath = resolve(projectRoot, "document.schema.json");

package/src/site/site-build.ts

@@ -9,7 +9,6 @@
  */
 
 import {
-  copyFileSync,
   cpSync,
   existsSync,
   mkdirSync,
@@ -19,8 +18,16 @@ import {
   statSync,
   writeFileSync,
 } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { isMappedArray, isRef } from "@jxsuite/schema/guards";
+import { isNpmSpecifier, sidecarAssetPath } from "@jxsuite/schema/asset-paths";
+import {
+  CLIENT_EXTERNALS,
+  bundleEntry,
+  bundleWorkerSource,
+  isBundleableSrc,
+  resolveSidecarEntry,
+} from "./bundler.ts";
 import { loadProjectConfig } from "./site-loader.ts";
 import { discoverPages, expandDynamicRoutes, readPageDocument } from "./pages-discovery.ts";
 import { buildProjectExtensionRegistry } from "./format-host.ts";
@@ -40,10 +47,12 @@ import {
   buildInitialScope,
   collectServerEntries,
   collectStyles,
+  colorSchemePrePaintScript,
   evaluateStaticTemplate,
   isComponentFullyStatic,
   isTemplateString,
   preRenderComponentHtml,
+  pureSchemeOf,
   renderStaticNode,
   resolveRefValue,
   resolveStaticValue,
@@ -106,6 +115,43 @@ export async function buildSite(
   const publicDir = resolve(projectRoot, "public");
   const trailingSlash = projectConfig.build.trailingSlash ?? "always";
 
+  // 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
+  // In step 6d (spec.md §12). Keyed by asset path so duplicate specifiers bundle once.
+  const sidecarBundles = new Map<string, { entryPath: string; specifier: string }>();
+  const rewriteSidecarSrc = (specifier: string, docDir: string | null): string => {
+    if (!isBundleableSrc(specifier)) {
+      return specifier;
+    }
+    try {
+      const entryPath = resolveSidecarEntry(specifier, docDir ?? projectRoot, projectRoot);
+      // A declared-but-absent relative sidecar keeps its verbatim import (the historical
+      // Behavior) with a warning — the doc may only ever run interpreted. Unresolvable npm
+      // Specifiers stay hard errors: a missing dependency should fail the build.
+      if (!isNpmSpecifier(specifier) && !existsSync(entryPath)) {
+        console.warn(`Sidecar "${specifier}" not found at ${entryPath} — emitting unbundled`);
+        return specifier;
+      }
+      // Relative specifiers key on their project-relative resolved path so `./x.js` declared in
+      // Two directories cannot collide on one slug; npm specifiers are location-independent.
+      const assetKey = isNpmSpecifier(specifier)
+        ? specifier
+        : `./${relative(projectRoot, entryPath)}`;
+      const assetPath = sidecarAssetPath(assetKey);
+      const existing = sidecarBundles.get(assetPath);
+      if (existing && existing.entryPath !== entryPath) {
+        throw new Error(
+          `"${specifier}" and "${existing.specifier}" both bundle to ${assetPath} — rename one`,
+        );
+      }
+      sidecarBundles.set(assetPath, { entryPath, specifier });
+      return assetPath;
+    } catch (error) {
+      errors.push(`Sidecar "${specifier}": ${(error as Error).message}`);
+      return specifier;
+    }
+  };
+
   // ── 1b. Build the extension registry from project.json#/extensions ─────
   const registry = await buildProjectExtensionRegistry(projectRoot, projectConfig);
   const formatRegistry = registry.formats;
@@ -194,6 +240,7 @@ export async function buildSite(
         const result = await compileElement(componentPath, {
           ...(projectConfig.$media ? { $media: projectConfig.$media } : {}),
           formats: formatRegistry,
+          rewriteSrc: rewriteSidecarSrc,
         });
         for (const f of result.files) {
           // Reduce the emitted path (an absolute source path with .json swapped to .js) to a bare
@@ -277,6 +324,7 @@ export async function buildSite(
         imageMetaCache,
         formatRegistry,
         registry,
+        rewriteSidecarSrc,
       );
 
       // Determine which component tags are fully static (for script omission)
@@ -412,10 +460,23 @@ export async function buildSite(
       : compileSiteServer([...deduped.values()], { adapter, connectors, mounts });
 
     if (workerSource) {
+      // Bundle the worker self-contained for the adapter's runtime (compiler.md §12): mount
+      // Modules, connectors, hono, and user server functions are inlined, so dist deploys
+      // Without node_modules or deploy-time bundling.
       const workerName = adapter === "cloudflare-pages" ? "_worker.js" : "worker.js";
-      writeFileSync(resolve(outDir, workerName), workerSource, "utf8");
-      fileCount += 1;
-      log(`  Generated dist/${workerName} (${deduped.size} server function(s))`);
+      try {
+        await bundleWorkerSource(workerSource, {
+          adapter,
+          outfile: resolve(outDir, workerName),
+          projectRoot,
+        });
+        fileCount += 1;
+        log(`  Generated dist/${workerName} (bundled, ${deduped.size} server function(s))`);
+      } catch (error) {
+        const msg = `Error bundling dist/${workerName}: ${(error as Error).message}`;
+        errors.push(msg);
+        console.error(msg);
+      }
 
       if (adapter === "cloudflare-pages") {
         // Only invoke the worker for server routes; everything else stays static.
@@ -426,17 +487,68 @@ export async function buildSite(
         );
         fileCount += 1;
       }
+    }
+  }
+
+  // ── 6d. Bundle client sidecar modules (spec.md §12) ─────────────────────
+  if (sidecarBundles.size > 0) {
+    log(`Bundling ${sidecarBundles.size} client sidecar module(s)...`);
+    for (const [assetPath, bundle] of sidecarBundles) {
+      try {
+        const outfile = resolve(outDir, assetPath.replace(/^\//, ""));
+        mkdirSync(dirname(outfile), { recursive: true });
+        await bundleEntry(
+          { entryPath: bundle.entryPath, outfile },
+          { external: CLIENT_EXTERNALS, target: "browser" },
+        );
+        fileCount += 1;
+        log(`  ${bundle.specifier} → ${assetPath}`);
+      } catch (error) {
+        const msg = `Error bundling sidecar "${bundle.specifier}": ${(error as Error).message}`;
+        errors.push(msg);
+        console.error(msg);
+      }
+    }
+  }
 
-      // Copy server source files into dist/components/ so worker imports resolve
-      const distComponentsDir = resolve(outDir, "components");
-      mkdirSync(distComponentsDir, { recursive: true });
-      for (const { src } of deduped.values()) {
-        const srcFile = resolve(projectRoot, src.replace(/^\.\//, ""));
-        const destFile = resolve(distComponentsDir, src.replace(/^\.\/components\//, ""));
-        if (existsSync(srcFile)) {
-          copyFileSync(srcFile, destFile);
+  // ── 6e. Extension-emitted assets (extensions.md §8.4) ───────────────────
+  // Section-owner classes with an `emit` capability contribute derived build artifacts
+  // (search indexes, feeds, …). The host writes the returned files so extensions stay pure;
+  // Paths are outDir-relative and guarded against traversal. Note the `public/` copy (7c)
+  // Runs later and can shadow emitted files — same semantics as sitemap.xml.
+  for (const entry of registry.emitters()) {
+    const sectionKey = entry.project?.key;
+    const sectionValue = sectionKey
+      ? (projectConfig as unknown as Record<string, unknown>)[sectionKey]
+      : undefined;
+    if (
+      sectionKey &&
+      (sectionValue == null ||
+        (typeof sectionValue === "object" && Object.keys(sectionValue).length === 0))
+    ) {
+      continue; // Section owner with nothing declared — same gating as sections/mounts
+    }
+    try {
+      const emitted = (await entry.call("emit", sectionValue ?? null, {
+        projectConfig,
+        root: projectRoot,
+        routes,
+        sections,
+      })) as { path: string; content: string | Uint8Array }[] | null;
+      for (const file of emitted ?? []) {
+        const target = resolve(outDir, file.path.replace(/^\//, ""));
+        if (!target.startsWith(outDir + sep)) {
+          throw new Error(`emit path escapes outDir: ${file.path}`);
         }
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, file.content);
+        fileCount += 1;
+        log(`  ${entry.name} emitted ${file.path}`);
       }
+    } catch (error) {
+      const msg = `Error in ${entry.name}.emit: ${(error as Error).message}`;
+      errors.push(msg);
+      console.error(msg);
     }
   }
 
@@ -517,6 +629,7 @@ async function compilePage(
   imageMetaCache: ImageMetaCache | null = null,
   formatRegistry?: FormatRegistry,
   registry?: ExtensionRegistry,
+  rewriteSidecarSrc?: (specifier: string, docDir: string | null) => string,
 ) {
   // Load the raw page document (.json natively, other formats via the registry)
   const pageDoc = await readPageDocument(route.sourcePath as string, formatRegistry);
@@ -541,6 +654,13 @@ async function compilePage(
     config: projectConfig,
     sections,
     ...(registry === undefined ? {} : { registry }),
+    ...(rewriteSidecarSrc === undefined
+      ? {}
+      : {
+          registerBundle: (specifier: string) => {
+            rewriteSidecarSrc(specifier, null);
+          },
+        }),
   });
 
   // Build scope from resolved state so template strings in title/$head can be evaluated
@@ -609,6 +729,13 @@ async function compilePage(
     layoutDoc.$media = { ...projectConfig.$media, ...layoutDoc.$media };
   }
 
+  // Declaring a pure color-scheme query opts the page into the forced-scheme contract: restore
+  // The visitor's persisted scheme before first paint (spec §9.5). Injected after the
+  // Charset/viewport defaults and ahead of every preserved <style> block.
+  if (Object.values(layoutDoc.$media ?? {}).some((q) => pureSchemeOf(String(q)) !== null)) {
+    mergedHead.splice(2, 0, { tagName: "script", textContent: colorSchemePrePaintScript() });
+  }
+
   // Transform <img> nodes for responsive image optimization
   if (projectConfig.images?.optimize && (imageCache || imageMetaCache)) {
     await transformImageNodes(
@@ -623,7 +750,14 @@ async function compilePage(
   // Compile the document using the existing compiler
   const result = await compile(layoutDoc, {
     lang: projectConfig.defaults?.lang ?? "en",
+    prePaintScheme: false, // Injected via the merged <head> above, not the target template
     projectStyle: projectConfig.style ?? null,
+    ...(rewriteSidecarSrc === undefined
+      ? {}
+      : {
+          rewriteSrc: (specifier: string) =>
+            rewriteSidecarSrc(specifier, dirname(route.sourcePath as string)),
+        }),
     title,
   });
 

package/src/site/validate-command.ts

@@ -0,0 +1,264 @@
+/**
+ * Validate-command — `jx validate` whole-project implementation.
+ *
+ * Extends the original project.json check into the full compliance walk:
+ *
+ * 1. `project.json` against the generated entry schema (validateProjectFile);
+ * 2. The committed entry documents are SELF-CONTAINED (no residual relative `$ref`s — the
+ *    editor-resolution guarantee of the bundled form, specs/extensions.md §5.4);
+ * 3. Every document under `components/`, `pages/`, and `layouts/` against the bundled document schema
+ *    (core + extension `$paths` union — the same schema the studio consumes);
+ * 4. Every project-local `*.class.json` against the generated class schema;
+ * 5. Every enabled extension's schema fragments compile standalone against the shipped default union
+ *    resources.
+ *
+ * Validation failures are data (issues in the result); infrastructure failures throw.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join, relative, resolve } from "node:path";
+import { generateClassSchema } from "@jxsuite/schema";
+import { validateProjectFile } from "@jxsuite/schema/validate-project";
+import { buildProjectExtensionRegistry } from "./format-host.ts";
+import { loadProjectConfig } from "./site-loader.ts";
+import { readBundledProjectSchemas } from "./schema-command.ts";
+
+/** Directories that hold Jx documents validated against the document schema. */
+const DOCUMENT_DIRS = ["components", "pages", "layouts"] as const;
+
+/** Directory names never walked for class files. */
+const SKIP_DIRS = new Set(["node_modules", "dist", ".git"]);
+
+/** Shipped default union resources fragments may reference by canonical URI. */
+const SHIPPED_RESOURCE_SPECIFIERS = [
+  "@jxsuite/schema/schemas/project.core.schema.json",
+  "@jxsuite/schema/schemas/project.fields.schema.json",
+  "@jxsuite/schema/schemas/document.paths.schema.json",
+];
+
+export interface ProjectTreeIssue {
+  /** Project-relative file path (or absolute for extension fragments outside the root). */
+  file: string;
+  /** Ajv error objects, or `{ message }` records for structural issues. */
+  errors: unknown[];
+}
+
+export interface ProjectTreeValidationResult {
+  valid: boolean;
+  /** Number of files checked across all five walks. */
+  checked: number;
+  issues: ProjectTreeIssue[];
+}
+
+// Minimal structural types for the optional `ajv` dependency (same pattern as validate-project).
+interface AjvValidateFn {
+  (doc: unknown): boolean;
+  errors?: unknown[] | null;
+}
+interface AjvInstance {
+  compile: (schema: unknown) => AjvValidateFn;
+  addSchema: (schema: unknown) => AjvInstance;
+}
+type AjvCtor = new (opts: {
+  allErrors: boolean;
+  ownProperties: boolean;
+  strict: boolean;
+}) => AjvInstance;
+type AddFormatsFn = (ajv: AjvInstance) => void;
+
+async function loadAjv(): Promise<{ Ajv: AjvCtor; addFormats: AddFormatsFn }> {
+  try {
+    // The schemas are JSON Schema 2020-12, so use the matching Ajv build.
+    const { default: Ajv } = (await import("ajv/dist/2020")) as unknown as { default: AjvCtor };
+    // @ts-expect-error — resolved through @jxsuite/schema's dependency
+    const { default: addFormats } = (await import("ajv-formats")) as { default: AddFormatsFn };
+    return { addFormats, Ajv };
+  } catch (error) {
+    throw new Error("Project validation requires ajv and ajv-formats: bun add ajv ajv-formats", {
+      cause: error,
+    });
+  }
+}
+
+/**
+ * Validate a whole project tree. See the module docstring for the five walks.
+ *
+ * @param {string} projectRoot - Absolute path to the project directory
+ * @returns {Promise<ProjectTreeValidationResult>}
+ */
+export async function validateProjectTree(
+  projectRoot: string,
+): Promise<ProjectTreeValidationResult> {
+  const root = resolve(projectRoot);
+  const issues: ProjectTreeIssue[] = [];
+  let checked = 0;
+
+  // 1. project.json against the generated entry schema.
+  const projectResult = await validateProjectFile(root);
+  checked += 1;
+  if (!projectResult.valid) {
+    issues.push({ errors: projectResult.errors ?? [], file: "project.json" });
+  }
+
+  // 2. Committed entry documents must be self-contained (the editor-resolution guarantee).
+  for (const name of ["project.schema.json", "document.schema.json"]) {
+    const path = resolve(root, name);
+    if (!existsSync(path)) {
+      continue;
+    }
+    checked += 1;
+    const residual: string[] = [];
+    collectRelativeRefs(JSON.parse(readFileSync(path, "utf8")), residual);
+    if (residual.length > 0) {
+      issues.push({
+        errors: residual.map((ref) => ({
+          message:
+            `relative $ref "${ref}" — committed entry documents must be self-contained; ` +
+            `regenerate with \`jx schema\``,
+        })),
+        file: name,
+      });
+    }
+  }
+
+  const { addFormats, Ajv } = await loadAjv();
+
+  // 3. Documents against the bundled document schema (the same schema the studio consumes).
+  const { document: documentSchema } = await readBundledProjectSchemas(root);
+  const docAjv = new Ajv({ allErrors: true, ownProperties: true, strict: false });
+  addFormats(docAjv);
+  const validateDoc = docAjv.compile(documentSchema);
+  for (const dir of DOCUMENT_DIRS) {
+    for (const file of walkJsonFiles(resolve(root, dir))) {
+      if (file.endsWith(".class.json")) {
+        continue; // Validated against the class schema below.
+      }
+      checked += 1;
+      const doc = JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown>;
+      if (!validateDoc(doc)) {
+        issues.push({ errors: validateDoc.errors ?? [], file: relative(root, file) });
+      }
+    }
+  }
+
+  // 4. Project-local class definitions against the generated class schema.
+  const classAjv = new Ajv({ allErrors: true, ownProperties: true, strict: false });
+  addFormats(classAjv);
+  const validateClass = classAjv.compile(generateClassSchema());
+  for (const file of walkClassFiles(root)) {
+    checked += 1;
+    const doc = JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown>;
+    if (!validateClass(doc)) {
+      issues.push({ errors: validateClass.errors ?? [], file: relative(root, file) });
+    }
+  }
+
+  // 5. Enabled extensions' schema fragments compile standalone against the shipped defaults.
+  const { config } = loadProjectConfig(root);
+  const registry = await buildProjectExtensionRegistry(root, config);
+  const selfRequire = createRequire(import.meta.url);
+  for (const ext of registry.extensions) {
+    for (const kind of ["project", "document", "fields"] as const) {
+      const fragmentPath = ext.schemas[kind];
+      if (!fragmentPath) {
+        continue;
+      }
+      checked += 1;
+      const fragAjv = new Ajv({ allErrors: true, ownProperties: true, strict: false });
+      addFormats(fragAjv);
+      for (const specifier of SHIPPED_RESOURCE_SPECIFIERS) {
+        const resourcePath = selfRequire.resolve(specifier);
+        const resource = JSON.parse(readFileSync(resourcePath, "utf8")) as Record<string, unknown>;
+        fragAjv.addSchema(resource);
+      }
+      try {
+        fragAjv.compile(JSON.parse(readFileSync(fragmentPath, "utf8")));
+      } catch (error) {
+        issues.push({
+          errors: [{ message: error instanceof Error ? error.message : String(error) }],
+          file: `${ext.specifier} (${kind} fragment)`,
+        });
+      }
+    }
+  }
+
+  return { checked, issues, valid: issues.length === 0 };
+}
+
+/** Collect relative-path `$ref`s (anything without a URI scheme that isn't a `#` pointer). */
+function collectRelativeRefs(node: unknown, out: string[]): void {
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      collectRelativeRefs(item, out);
+    }
+    return;
+  }
+  if (node === null || typeof node !== "object") {
+    return;
+  }
+  for (const [key, value] of Object.entries(node as Record<string, unknown>)) {
+    if (
+      key === "$ref" &&
+      typeof value === "string" &&
+      !value.startsWith("#") &&
+      !/^[a-zA-Z][a-zA-Z\d+.-]*:/.test(value)
+    ) {
+      out.push(value);
+    }
+    collectRelativeRefs(value, out);
+  }
+}
+
+/** Recursively list `.json` files under a directory (absent directories yield nothing). */
+function walkJsonFiles(dir: string): string[] {
+  if (!existsSync(dir)) {
+    return [];
+  }
+  const out: string[] = [];
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) {
+      out.push(...walkJsonFiles(path));
+    } else if (name.endsWith(".json")) {
+      out.push(path);
+    }
+  }
+  return out.toSorted();
+}
+
+/** Recursively list `*.class.json` files under the root, skipping vendored/output dirs. */
+function walkClassFiles(root: string): string[] {
+  const out: string[] = [];
+  const walk = (dir: string) => {
+    for (const name of readdirSync(dir)) {
+      if (SKIP_DIRS.has(name)) {
+        continue;
+      }
+      const path = join(dir, name);
+      if (statSync(path).isDirectory()) {
+        walk(path);
+      } else if (name.endsWith(".class.json")) {
+        out.push(path);
+      }
+    }
+  };
+  walk(root);
+  return out.toSorted();
+}
+
+/** Format a result's issues as printable lines (one per error) for the CLI. */
+export function formatProjectTreeIssues(result: ProjectTreeValidationResult): string[] {
+  const lines: string[] = [];
+  for (const issue of result.issues) {
+    lines.push(`${issue.file}:`);
+    for (const error of issue.errors) {
+      const { instancePath, message } = (error ?? {}) as {
+        instancePath?: string;
+        message?: string;
+      };
+      lines.push(`  - ${instancePath || "/"}: ${message ?? JSON.stringify(error)}`);
+    }
+  }
+  return lines;
+}

package/src/targets/compile-client.ts

@@ -16,6 +16,7 @@ import {
   DEFAULT_LIT_HTML_SRC,
   DEFAULT_REACTIVITY_SRC,
   buildAttrs,
+  colorSchemePrePaintScript,
   compileExpression,
   compileStatements,
   compileStyles,
@@ -26,6 +27,7 @@ import {
   isRefObject,
   isSchemaOnly,
   isTemplateString,
+  pureSchemeOf,
   resolveStaticValue,
 } from "../shared.ts";
 import {
@@ -76,6 +78,7 @@ export function compileClient(
     litHtmlSrc?: string;
     modulePath?: string;
     projectStyle?: JxStyle | null;
+    prePaintScheme?: boolean;
     [key: string]: unknown;
   },
 ) {
@@ -238,6 +241,7 @@ export function compileClient(
     srcImportMap,
     counter,
     reactivitySrc,
+    opts.rewriteSrc as ((specifier: string) => string) | undefined,
   );
 
   // Build importmap entries — always include lit-html since compiled custom elements need it
@@ -246,13 +250,20 @@ export function compileClient(
     `      "lit-html": "${litHtmlSrc}"`,
   ];
 
+  // Forced-scheme contract (spec §9.5): restore the persisted scheme before any styles apply
+  const prePaint =
+    opts.prePaintScheme !== false &&
+    Object.values(raw.$media ?? {}).some((q) => pureSchemeOf(String(q)) !== null)
+      ? `<script>${colorSchemePrePaintScript()}</script>\n  `
+      : "";
+
   const html = `<!DOCTYPE html>
 <html lang="en">
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>${escapeHtml(title)}</title>
-  <script type="importmap">
+  ${prePaint}<script type="importmap">
   {
     "imports": {
 ${importmapEntries.join(",\n")}
@@ -757,6 +768,7 @@ function emitClientModule(
     needsLit: boolean;
   },
   _reactivitySrc: string,
+  rewriteSrc?: (specifier: string) => string,
 ) {
   const lines: string[] = [];
   const { needsLit } = counter;
@@ -776,9 +788,11 @@ function emitClientModule(
     lines.push("import { html, render } from 'lit-html';");
   }
 
-  // $src imports
+  // $src imports — bundleable specifiers (npm:…, ./relative) are rewritten to their /assets/
+  // Bundle URL; the site build bundles them after all documents compile (spec.md §12).
   for (const [src, names] of srcImportMap) {
-    lines.push(`import { ${[...names].join(", ")} } from '${src}';`);
+    const importPath = rewriteSrc ? rewriteSrc(src) : src;
+    lines.push(`import { ${[...names].join(", ")} } from '${importPath}';`);
   }
 
   // State — reactive state