@jxsuite/compiler 1.1.0 → 1.2.0

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/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

package/src/targets/compile-element.ts

@@ -41,6 +41,12 @@ import type {
 export interface CompileElementOptions {
   /** Resolve an `$elements` ref path to its emitted JS module path. */
   resolveElementPath?: (refPath: string, currentDir: string | null) => string;
+  /**
+   * Rewrite a Function-def `$src` specifier to its served URL (bundleable specifiers → their
+   * `/assets/` bundle path). Receives the directory of the declaring document for relative
+   * specifiers. Identity when omitted.
+   */
+  rewriteSrc?: (specifier: string, docDir: string | null) => string;
   $media?: Record<string, string>;
   formats?: FormatRegistry;
   basePath?: string | null;
@@ -135,7 +141,13 @@ export async function compileElement(
     if (optsMedia) {
       doc.$media = { ...optsMedia, ...doc.$media };
     }
-    const jsContent = emitElementModule(doc, className, elementImports);
+    const { rewriteSrc } = opts;
+    const jsContent = emitElementModule(
+      doc,
+      className,
+      elementImports,
+      rewriteSrc ? (spec: string) => rewriteSrc(spec, currentDir) : undefined,
+    );
     const outputPath = filePath ? filePath.replace(/\.json$/, ".js") : `${tagName}.js`;
     files.push({ content: jsContent, path: outputPath, tagName });
   }
@@ -244,7 +256,12 @@ function extractInitialValue(def: JxMutableNode) {
  * @param {string[]} elementImports
  * @returns {string}
  */
-export function emitElementModule(doc: JxDocument, className: string, elementImports: string[]) {
+export function emitElementModule(
+  doc: JxDocument,
+  className: string,
+  elementImports: string[],
+  rewriteSrc?: (specifier: string) => string,
+) {
   const lines: string[] = ["// Generated by @jxsuite/compiler — do not edit manually"];
 
   if (doc.$id) {
@@ -269,7 +286,10 @@ export function emitElementModule(doc: JxDocument, className: string, elementImp
     }
   }
   for (const [srcPath, names] of srcImportMap) {
-    lines.push(`import { ${names.join(", ")} } from '${srcPath}';`);
+    // Bundleable specifiers (npm:…, ./relative) are rewritten to their /assets/ bundle URL;
+    // The site build bundles them after all documents compile (spec.md §12).
+    const importPath = rewriteSrc ? rewriteSrc(srcPath) : srcPath;
+    lines.push(`import { ${names.join(", ")} } from '${importPath}';`);
   }
 
   lines.push(
@@ -486,11 +506,16 @@ export function emitElementModule(doc: JxDocument, className: string, elementImp
     );
   }
   lines.push(
+    // Lifecycle: onMount (spec §16.4) — same microtask contract as the runtime
+    "    if (typeof this.state.onMount === 'function') {",
+    "      queueMicrotask(() => this.state.onMount(this.state));",
+    "    }",
     "  }",
     "",
     // DisconnectedCallback
     "  disconnectedCallback() {",
     "    if (this.#dispose) { this.#dispose(); this.#dispose = null; }",
+    "    if (typeof this.state.onUnmount === 'function') { this.state.onUnmount(this.state); }",
     "  }",
     "}",
     "",

package/src/targets/compile-static.ts

@@ -7,10 +7,12 @@
 
 import {
   buildAttrs,
+  colorSchemePrePaintScript,
   compileStyles,
   createCompileContext,
   escapeHtml,
   isNodeDynamic,
+  pureSchemeOf,
   resolveStaticValue,
   SELF_CLOSING,
 } from "../shared.ts";
@@ -31,6 +33,7 @@ export function compileStaticPage(
     reactivitySrc?: string;
     litHtmlSrc?: string;
     projectStyle?: JxStyle | null;
+    prePaintScheme?: boolean;
     [key: string]: unknown;
   },
 ) {
@@ -51,7 +54,12 @@ export function compileStaticPage(
   let moduleScripts = "";
   if (islands.length > 0) {
     for (const island of islands) {
-      const moduleContent = emitElementModule(island.def as JxDocument, island.className, []);
+      const moduleContent = emitElementModule(
+        island.def as JxDocument,
+        island.className,
+        [],
+        opts.rewriteSrc as ((specifier: string) => string) | undefined,
+      );
       files.push({
         content: moduleContent,
         path: `_islands/${island.tagName}.js`,
@@ -73,13 +81,20 @@ export function compileStaticPage(
       .join("\n  ");
   }
 
+  // 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>
-  ${importMap}
+  ${prePaint}${importMap}
   ${styleBlock}
 </head>
 <body>