@jxsuite/compiler 2.0.7 → 3.0.0

package/src/site/site-build.ts

@@ -18,6 +18,7 @@ import {
   statSync,
   writeFileSync,
 } from "node:fs";
+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";
@@ -49,7 +50,7 @@ import type { AssetMount } from "@jxsuite/schema/asset-paths";
 import type { FormatEntry, FormatRegistry } from "@jxsuite/schema/format-registry";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 import { resolveLayout } from "./layout-resolver.ts";
-import { mergeHead, renderHead } from "./head-merger.ts";
+import { mergeHead, renderHead } from "@jxsuite/site/head-merger";
 import { unregisteredHeadRelations } from "./link-relations.ts";
 import { injectContext } from "./context-injection.ts";
 import { compile, compileServer, compileSiteServer } from "../compiler.ts";
@@ -61,8 +62,10 @@ import {
   collectServerEntries,
   collectStyles,
   colorSchemePrePaintScript,
+  escapeStyleText,
   evaluateStaticTemplate,
   isComponentFullyStatic,
+  isSingleExpression,
   isTemplateString,
   preRenderComponentHtml,
   pureSchemeOf,
@@ -97,7 +100,8 @@ import {
 } from "./i18n.ts";
 import type { LocaleAlternate, PageLocaleContext } from "./i18n.ts";
 import {
-  isPrefixSpecifier,
+  importMapAssets,
+  importMapAssetsInHtml,
   renderImportMap,
   resolveClientRuntime,
   writeClientRuntime,
@@ -158,6 +162,13 @@ export async function buildSite(
   const pagesDir = resolve(projectRoot, "pages");
   const publicDir = resolve(projectRoot, "public");
   const trailingSlash = projectConfig.build.trailingSlash ?? "always";
+  /*
+   * Browser bundles are minified unless the project opts out. Off, the six scripts jxsuite.com
+   * loads weigh 155 kB of source a phone has to parse before it can paint; on, 65 kB. The opt-out
+   * exists for two real cases: reading a deployed stack trace, and diffing `dist/` across bundler
+   * backends, which agree on semantics but not on minified bytes.
+   */
+  const minify = projectConfig.build.minify !== false;
 
   // Client sidecar bundles: bundleable Function-def `$src` specifiers (and lowered-def `$bundle`
   // Hints) are rewritten to their /assets/ URL during compilation, registered here, and bundled
@@ -180,7 +191,11 @@ export async function buildSite(
   const elementBundles = new Map<string, string[]>();
   const registerElementBundle = (specifiers: string[]): string => {
     const sorted = specifiers.toSorted();
-    const key = Bun.hash(sorted.join("\u0000")).toString(36);
+    /*
+     * `node:crypto` rather than `Bun.hash`: the jx bin runs under Node, where the Bun global does
+     * not exist, and this line is reached by any page registering npm `$elements`.
+     */
+    const key = createHash("sha1").update(sorted.join("\u0000")).digest("hex").slice(0, 12);
     const assetPath = `/assets/elements-${key}.js`;
     elementBundles.set(assetPath, sorted);
     return assetPath;
@@ -195,6 +210,11 @@ export async function buildSite(
    */
   const clientRuntime = resolveClientRuntime();
   const runtimeImports = clientRuntime.imports;
+  /*
+   * What step 6d bundles, scanned back out of each finished page rather than recorded wherever a
+   * map is emitted. Several places emit one and only `injectComponentScripts` was recording, so a
+   * page whose interactivity came from anything else shipped a map naming files no build wrote.
+   */
   const runtimeAssetsUsed = new Set<string>();
   /*
    * Scanned from every finished page, so the hashes name the exact bytes shipped rather than what
@@ -674,10 +694,18 @@ export async function buildSite(
           staticTags,
           result.files.map((f: { content: string }) => f.content).join("\n"),
           runtimeImports,
-          runtimeAssetsUsed,
         );
       }
 
+      /*
+       * Whatever import map this page ended up with, step 6d owes it the files it names. Read from
+       * the finished HTML so the answer does not depend on which of the emission paths produced
+       * the map — the one that reported and the one that shipped were different sets (issue #227).
+       */
+      for (const assetPath of importMapAssetsInHtml(result.html)) {
+        runtimeAssetsUsed.add(assetPath);
+      }
+
       // Mounted assets this page actually references — scanned from the finished HTML so a
       // Reference is caught wherever it came from (markdown image, hand-authored page, $head).
       collectAssetRefs(result.html, assetMounts, assetRefs);
@@ -856,6 +884,8 @@ export async function buildSite(
     const runtime = await writeClientRuntime(
       { ...clientRuntime, assetPaths: [...runtimeAssetsUsed] },
       outDir,
+      undefined,
+      minify,
     );
     fileCount += runtime.written;
     for (const error of runtime.errors) {
@@ -883,7 +913,7 @@ export async function buildSite(
         mkdirSync(dirname(outfile), { recursive: true });
         await bundleEntry(
           { entryPath: bundle.entryPath, outfile },
-          { external: CLIENT_EXTERNALS, target: "browser" },
+          { external: CLIENT_EXTERNALS, minify, target: "browser" },
         );
         fileCount += 1;
         log(`  ${bundle.specifier} → ${assetPath}`);
@@ -908,7 +938,7 @@ export async function buildSite(
         await bundleSource(
           `${specifiers.map((sp) => `import ${JSON.stringify(sp)};`).join("\n")}\n`,
           { outfile, resolveDir: projectRoot },
-          { target: "browser" },
+          { minify, target: "browser" },
         );
         fileCount += 1;
         log(`  ${specifiers.length} element(s) → ${assetPath}`);
@@ -927,7 +957,7 @@ export async function buildSite(
    * discovered from their contents rather than declared anywhere (site-architecture.md §8.7).
    */
   if (runtimeAssetsUsed.size > 0) {
-    const subpaths = await writeRuntimeSubpaths(outDir);
+    const subpaths = await writeRuntimeSubpaths(outDir, undefined, minify);
     if (subpaths.written > 0) {
       log(`Bundling ${subpaths.written} runtime subpath module(s)...`);
     }
@@ -1089,12 +1119,36 @@ export async function buildSite(
     if (rules.length > 0) {
       log("Writing response headers...");
       fileCount += writeHeaders(outDir, rules);
-      const { adapter } = projectConfig.build;
+      const { adapter, deploy } = projectConfig.build;
       if (adapter === "node" || adapter === "bun") {
         console.warn(
           `The "${adapter}" adapter serves no static assets, so dist/_headers is documentation ` +
             `rather than configuration — apply these headers at the reverse proxy in front of it.`,
         );
+      } else if (adapter === undefined && deploy === undefined) {
+        /*
+         * `_headers` is a Cloudflare/Netlify convention, not a web standard, and the build has no
+         * way to know where a plain static `dist/` is going. Most static hosts — GitHub Pages among
+         * them — ignore the file entirely and serve their own `Cache-Control`, which is how a site
+         * ends up shipping a year-long `immutable` rule for its content-addressed images and
+         * getting ten minutes.
+         *
+         * A `public/CNAME` is GitHub Pages' custom-domain marker and nothing else's, so it is a
+         * specific enough signal to say so out loud rather than warn every static build.
+         */
+        if (existsSync(resolve(publicDir, "CNAME"))) {
+          console.warn(
+            "GitHub Pages ignores dist/_headers and serves its own Cache-Control: max-age=600, " +
+              "so the generated caching and security rules will not take effect. Deploy behind a " +
+              "host that reads _headers (Cloudflare Pages, Cloudflare Workers assets, Netlify) " +
+              "to apply them.",
+          );
+        } else {
+          log(
+            "  note: _headers is read by Cloudflare Pages, Cloudflare Workers assets and Netlify; " +
+              "other static hosts ignore it and serve their own Cache-Control.",
+          );
+        }
       }
     }
     fileCount += writeNoJekyll(outDir);
@@ -1165,7 +1219,7 @@ async function compilePage(
   const pageDoc = await readPageDocument(route.sourcePath as string, formatRegistry);
 
   // Resolve layout (wraps page in layout with slot distribution)
-  const layoutDoc = resolveLayout(pageDoc, projectConfig, projectRoot);
+  const layoutDoc = await resolveLayout(pageDoc, projectConfig, projectRoot);
 
   // Extract head arrays before they get lost in the merge
   const pageHead = (pageDoc.$head ?? layoutDoc._pageHead ?? []) as JxHeadEntry[];
@@ -1387,7 +1441,7 @@ async function compilePage(
   if (slotCss.rules.length > 0) {
     result.html = result.html.replace(
       "</head>",
-      `<style>\n${slotCss.rules.join("\n")}\n</style>\n</head>`,
+      `<style>\n${escapeStyleText(slotCss.rules.join("\n"))}\n</style>\n</head>`,
     );
   }
 
@@ -1739,15 +1793,8 @@ function evaluateMapTemplate(str: string, scope: Record<string, unknown>) {
   try {
     const item = (scope.$map as Record<string, unknown>)?.item;
     const index = (scope.$map as Record<string, unknown>)?.index;
-    const singleExprMatch = str.match(/^\$\{(.+)\}$/s);
-    if (singleExprMatch) {
-      const fn = new Function(
-        "state",
-        "$map",
-        "item",
-        "index",
-        `return (${singleExprMatch[1]})`,
-      ) as (
+    if (isSingleExpression(str)) {
+      const fn = new Function("state", "$map", "item", "index", `return (${str.slice(2, -1)})`) as (
         state: Record<string, unknown>,
         $map: unknown,
         item: unknown,
@@ -2038,6 +2085,23 @@ function expandComponents(
       }
     }
 
+    /*
+     * A non-static instance discards its prerendered markup on upgrade and re-renders, so the
+     * props have to survive as data or the element comes back with its state defaults — correct
+     * content painting first and then being replaced by the wrong content. compiler.md §5.2 gives
+     * connectedCallback three prop sources and this is the first of them; the compiler read it but
+     * never wrote it, and lifting `props.*` into $props above removed the other channel too.
+     *
+     * JSON rather than re-emitted `props.*` attributes because those are strings by spec: a number
+     * or an array would arrive stringified, and a key that is not lowercase would be dropped by
+     * attribute-name folding.
+     */
+    if (!isStatic && node.$props && Object.keys(node.$props).length > 0) {
+      node.attributes = {
+        ...node.attributes,
+        "data-jx-props": JSON.stringify(node.$props),
+      };
+    }
     delete node.$props;
 
     if (isStatic) {
@@ -2058,7 +2122,6 @@ function expandComponents(
  * @param {Set<string>} [staticTags] - Tags where ALL instances are fully static (skip JS)
  * @param {string} [islandSource] - Concatenated island modules emitted for this page
  * @param {Record<string, string>} [runtimeImports] - The import map's `imports` object
- * @param {Set<string>} [runtimeAssetsUsed] - Collects the asset paths an emitted import map names
  * @returns {string}
  */
 function injectComponentScripts(
@@ -2068,7 +2131,6 @@ function injectComponentScripts(
   staticTags = new Set<string>(),
   islandSource = "",
   runtimeImports: Record<string, string> = {},
-  runtimeAssetsUsed = new Set<string>(),
 ) {
   // A component reaches a page two ways: as a literal tag in the static HTML, or referenced only
   // From inside an island's client template — in which case the tag exists solely in the island's
@@ -2081,15 +2143,31 @@ function injectComponentScripts(
     return html;
   }
 
-  // Inject CSS links in <head> for ALL components that have CSS sidecars
-  const cssLinks = usedTags
-    .filter((tag: string) => cssMap.has(tag))
-    .map((tag: string) => `<link rel="stylesheet" href="/components/${tag}.css">`)
-    .join("\n  ");
-  let result = html;
-  if (cssLinks) {
-    result = result.replace("</head>", `  ${cssLinks}\n</head>`);
-  }
+  /*
+   * Component CSS is INLINED, not linked.
+   *
+   * A `<link rel="stylesheet">` per component tag is a render-blocking request per component: on
+   * jxsuite.com's home page, 11 of them totalling 22 kB — the whole of its critical request chain,
+   * for sheets averaging 2 kB each. The page already carries its project and page CSS inline
+   * (`buildStyleBlock`), so this is the same delivery, applied consistently.
+   *
+   * The trade is real and deliberate: these bytes now repeat on every page instead of caching
+   * across navigations. They are small, they gzip against the markup around them, and a round trip
+   * on a phone costs more than the bytes do. Components in shadow mode are untouched — their sheet
+   * is linked from inside the declarative shadow root and never enters `cssMap`.
+   *
+   * Emitted last in <head>, exactly where the links were, so the cascade is unchanged.
+   */
+  const componentCss = usedTags
+    .map((tag: string) => cssMap.get(tag))
+    .filter((css): css is string => css !== undefined && css !== "")
+    .join("\n");
+  const styleBlock =
+    componentCss === "" ? "" : `<style>\n${escapeStyleText(componentCss)}\n  </style>`;
+  const intoHead = (fragments: string[]) => {
+    const block = fragments.filter(Boolean).join("\n  ");
+    return block === "" ? html : html.replace("</head>", `  ${block}\n</head>`);
+  };
 
   // Only inject JS for components that have non-static instances. An island-rendered instance is
   // Never prerendered, so it needs its module even when the component itself is fully static —
@@ -2097,22 +2175,30 @@ function injectComponentScripts(
   // The static HTML: those instances are prerendered, but the ones the island creates are not.
   const jsTags = usedTags.filter((tag: string) => inIsland(tag) || !staticTags.has(tag));
   if (jsTags.length === 0) {
-    return result;
+    return intoHead([styleBlock]);
   }
 
   // Build import map (needed for @vue/reactivity and lit-html)
   const importMap = renderImportMap(runtimeImports);
-  for (const [specifier, url] of Object.entries(runtimeImports)) {
-    /*
-     * A prefix key's value is the DIRECTORY its subpaths are served from — `/assets/lit-html/` —
-     * not a file any build writes. `writeClientRuntime` matches this set against exact asset
-     * paths, so a directory in it bundled nothing and only inflated the count this build logged.
-     */
-    if (isPrefixSpecifier(specifier) || !url.startsWith("/")) {
-      continue;
-    }
-    runtimeAssetsUsed.add(url);
-  }
+  /*
+   * The runtime modules THIS page needs — the hints are per page, so they are read from this
+   * page's map rather than from the build-wide set, which would have every page hint at every
+   * other page's runtime.
+   */
+  const pageRuntimeAssets = importMapAssets(runtimeImports);
+
+  /*
+   * An import map declares where a bare specifier lives; it does not tell the browser to go get it.
+   * Without these hints `/assets/vue-reactivity.js` is discovered only after a component module has
+   * been fetched AND parsed — a three-deep request chain on the critical path, on a connection
+   * where each hop is a round trip. The component modules are hinted too so the whole set starts
+   * downloading while the HTML is still being parsed.
+   */
+  const preloads = [...pageRuntimeAssets, ...jsTags.map((tag: string) => `/components/${tag}.js`)]
+    .map((href) => `<link rel="modulepreload" href="${href}">`)
+    .join("\n  ");
+
+  const result = intoHead([preloads, styleBlock]);
 
   const moduleScripts = jsTags
     .map((tag: string) => `<script type="module" src="/components/${tag}.js"></script>`)

package/src/targets/compile-element.ts

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

package/src/types.ts

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