@jxsuite/compiler 2.0.8 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "2.0.8",
+  "version": "3.1.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.7",
-    "@jxsuite/runtime": "^2.1.0",
-    "@jxsuite/schema": "^1.9.0",
-    "@vue/reactivity": "3.5.41",
+    "@apidevtools/json-schema-ref-parser": "^16.0.1",
+    "@jxsuite/create": "^1.3.9",
+    "@jxsuite/runtime": "^3.1.0",
+    "@jxsuite/schema": "^2.1.0",
+    "@jxsuite/site": "^1.1.0",
+    "@vue/reactivity": "3.5.42",
     "esbuild": "^0.28.2",
     "lit-html": "^3.3.3",
-    "sharp": "^0.35.3"
+    "sharp": "^0.35.4"
   },
   "devDependencies": {
-    "@happy-dom/global-registrator": "^20.11.6",
-    "@jxsuite/connector": "^0.5.5",
-    "@jxsuite/parser": "^1.5.6",
+    "@happy-dom/global-registrator": "^20.12.0",
+    "@jxsuite/connector": "^0.5.7",
+    "@jxsuite/parser": "^1.7.0",
     "@types/mdast": "^4.0.4"
   }
 }

package/src/shared.ts

@@ -10,7 +10,9 @@ import {
   COLOR_SCHEME_ATTR,
   COLOR_SCHEME_STORAGE_KEY,
   RESERVED_KEYS,
+  booleanAttrValue,
   camelToKebab,
+  isSingleExpression,
   pureSchemeOf,
   resolveAtQuery,
   schemeSelectors,
@@ -55,7 +57,9 @@ export {
   COLOR_SCHEME_ATTR,
   COLOR_SCHEME_STORAGE_KEY,
   RESERVED_KEYS,
+  booleanAttrValue,
   camelToKebab,
+  isSingleExpression,
   pureSchemeOf,
   schemeSelectors,
   toCSSText,
@@ -107,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.
  *
@@ -780,37 +799,6 @@ function readsRuntimeOnlyState(str: string, scope: Record<string, unknown>) {
   return false;
 }
 
-/**
- * Whether the whole string is exactly ONE `${…}` — the interpolation that opens at index 0 also
- * closes at the final character.
- *
- * A greedy `/^\$\{(.+)\}$/` also matched `"${a} / ${b}"`, spliced the interior into `return (a} /
- * ${b)`, and the SyntaxError became a silent null: the node rendered empty, and a `$head` entry
- * shipped its own template text. A brace-depth scan is exact where a tightened regex is not —
- * `"${`${a}-x`}"` is still one expression, and must keep returning a raw value.
- *
- * @param {string} str
- * @returns {boolean}
- */
-export function isSingleExpression(str: string): boolean {
-  if (!str.startsWith("${") || !str.endsWith("}")) {
-    return false;
-  }
-  let depth = 0;
-  for (let i = 1; i < str.length; i += 1) {
-    const c = str[i];
-    if (c === "{") {
-      depth += 1;
-    } else if (c === "}") {
-      depth -= 1;
-      if (depth === 0) {
-        return i === str.length - 1;
-      }
-    }
-  }
-  return false;
-}
-
 /**
  * @param {string} str
  * @param {Record<string, unknown>} scope
@@ -927,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))}"`;
       }
@@ -1233,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`<\/`);
 }
 
 /**

package/src/site/base-path.ts

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

package/src/site/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

@@ -131,6 +131,7 @@ export async function writeClientRuntime(
   runtime: ClientRuntime,
   outDir: string,
   resolveDir: string = PACKAGE_DIR,
+  minify = true,
 ): Promise<{ written: number; errors: string[] }> {
   const errors: string[] = [];
   let written = 0;
@@ -150,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) {
@@ -160,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)
@@ -216,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 = PACKAGE_DIR,
+  minify = true,
 ): Promise<{ written: number; errors: string[] }> {
   const errors: string[] = [];
   const done = new Set<string>();
@@ -280,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",
             },