@jxsuite/compiler 1.0.0 → 1.2.0

package/src/site/bundler.ts

@@ -0,0 +1,187 @@
+/**
+ * Bundler.js — timing-aware module bundling for compiled sites
+ *
+ * One backend abstraction serving every bundling need of the build (spec.md §12, compiler.md):
+ * client-timing `$src` sidecars today, the server worker in a follow-up. Backend selection is
+ * runtime-adaptive: `Bun.build` when the build runs under Bun, esbuild (dynamically imported) under
+ * plain Node. Options are kept minimal and identical across backends so output stays as stable as
+ * possible; set `JX_BUNDLER=esbuild` to force the fallback (e.g. for parity checks).
+ *
+ * `timing: "compiler"` code is never bundled — it executes in the build host via the extension
+ * registry's `importImplementation` path.
+ */
+
+import { rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join, resolve } from "node:path";
+import { isNpmSpecifier, NPM_SPECIFIER_PREFIX } from "@jxsuite/schema/asset-paths";
+
+/** Import specifiers left external in client bundles — provided by the page importmap. */
+export const CLIENT_EXTERNALS = ["@vue/reactivity", "lit-html"];
+
+/**
+ * True when a Function-def `$src` specifier is bundled by the build: `npm:` package specifiers and
+ * project-relative files. Absolute URL paths (`/lib/x.js`, `https://…`) are served as-is.
+ */
+export function isBundleableSrc(specifier: string): boolean {
+  return isNpmSpecifier(specifier) || specifier.startsWith("./") || specifier.startsWith("../");
+}
+
+/**
+ * True when the Node code path (createRequire resolution, esbuild backend) should be used: always
+ * under plain Node, or when `JX_BUNDLER=esbuild` forces it for parity checks.
+ */
+function useNodeFallback(): boolean {
+  return typeof Bun === "undefined" || process.env.JX_BUNDLER === "esbuild";
+}
+
+/**
+ * Resolve a bundleable `$src` specifier to the absolute entry file the bundler starts from. `npm:`
+ * specifiers resolve from the project root (project node_modules first, then up-tree); relative
+ * specifiers resolve against the directory of the document that declared them.
+ */
+export function resolveSidecarEntry(
+  specifier: string,
+  docDir: string,
+  projectRoot: string,
+): string {
+  if (isNpmSpecifier(specifier)) {
+    const bare = specifier.slice(NPM_SPECIFIER_PREFIX.length);
+    if (useNodeFallback()) {
+      return createRequire(join(projectRoot, "package.json")).resolve(bare);
+    }
+    return Bun.resolveSync(bare, projectRoot);
+  }
+  return resolve(docDir, specifier);
+}
+
+export interface BundleRequest {
+  /** Absolute path of the module to bundle. */
+  entryPath: string;
+  /** Absolute path of the bundled output file. */
+  outfile: string;
+}
+
+/** Resolution/runtime targets: client sidecars use "browser"; the site worker uses the rest. */
+export type BundleTargetName = "browser" | "node" | "bun" | "workerd";
+
+export interface BundleOptions {
+  target: BundleTargetName;
+  /** Bare specifiers left unresolved in the output. */
+  external?: string[];
+  /** Package.json export conditions for resolution (e.g. ["workerd", "worker"]). */
+  conditions?: string[];
+}
+
+/**
+ * Per-adapter bundle options for the generated site worker (WinterTC runtimes). Cloudflare resolves
+ * with workerd conditions and keeps `cloudflare:*`/`node:*` imports external (nodejs_compat
+ * provides node builtins at runtime); node/bun bundle platform-native with builtins external by
+ * construction.
+ */
+export function workerBundleOptions(adapter: string): BundleOptions {
+  if (adapter === "cloudflare-workers" || adapter === "cloudflare-pages") {
+    return {
+      conditions: ["workerd", "worker"],
+      external: ["cloudflare:*", "node:*"],
+      target: "workerd",
+    };
+  }
+  return { target: adapter === "bun" ? "bun" : "node" };
+}
+
+/** 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";
+}
+
+/** Map a bundle target to Bun.build's target. */
+function bunTarget(target: BundleTargetName): "browser" | "node" | "bun" {
+  if (target === "workerd") {
+    return "browser";
+  }
+  return target;
+}
+
+/**
+ * Bundle one entry module into a single self-contained ESM file. Throws with the backend's
+ * diagnostics on failure.
+ */
+export async function bundleEntry(request: BundleRequest, opts: BundleOptions): Promise<void> {
+  const external = opts.external ?? [];
+
+  if (useNodeFallback()) {
+    // Dynamic import keeps esbuild (a native-binary dependency) out of Bun-run builds entirely.
+    const esbuild = await import("esbuild");
+    await esbuild.build({
+      bundle: true,
+      ...(opts.conditions ? { conditions: opts.conditions } : {}),
+      entryPoints: [request.entryPath],
+      external,
+      format: "esm",
+      logLevel: "silent",
+      minify: false,
+      outfile: request.outfile,
+      platform: esbuildPlatform(opts.target),
+    });
+    return;
+  }
+
+  const result = await Bun.build({
+    ...(opts.conditions ? { conditions: opts.conditions } : {}),
+    entrypoints: [request.entryPath],
+    external,
+    format: "esm",
+    minify: false,
+    target: bunTarget(opts.target),
+    throw: false,
+  });
+  if (!result.success || result.outputs.length === 0) {
+    const logs = result.logs.map(String).join("\n");
+    throw new Error(`Bun.build failed for ${request.entryPath}:\n${logs}`);
+  }
+  writeFileSync(request.outfile, await result.outputs[0]!.text(), "utf8");
+}
+
+/**
+ * Bundle generated worker source (a string, not a file) into a self-contained module for the
+ * adapter's runtime. Bare and relative specifiers resolve from the project root — exactly how the
+ * unbundled source would have resolved when served from within the project.
+ */
+export async function bundleWorkerSource(
+  source: string,
+  { projectRoot, outfile, adapter }: { projectRoot: string; outfile: string; adapter: string },
+): Promise<void> {
+  const opts = workerBundleOptions(adapter);
+
+  if (useNodeFallback()) {
+    const esbuild = await import("esbuild");
+    await esbuild.build({
+      bundle: true,
+      ...(opts.conditions ? { conditions: opts.conditions } : {}),
+      external: opts.external ?? [],
+      format: "esm",
+      logLevel: "silent",
+      minify: false,
+      outfile,
+      platform: esbuildPlatform(opts.target),
+      stdin: {
+        contents: source,
+        loader: "js",
+        resolveDir: projectRoot,
+        sourcefile: "jx-worker-entry.js",
+      },
+    });
+    return;
+  }
+
+  // Bun.build has no stdin input — write a transient entry at the project root so resolution
+  // Matches the stdin/resolveDir behavior, and always remove it.
+  const entryPath = join(projectRoot, ".jx-worker-entry.mjs");
+  writeFileSync(entryPath, source, "utf8");
+  try {
+    await bundleEntry({ entryPath, outfile }, opts);
+  } finally {
+    rmSync(entryPath, { force: true });
+  }
+}

package/src/site/dev-command.ts

@@ -0,0 +1,84 @@
+/**
+ * Dev command — `jx dev` resolves the project's @jxsuite/server dev entry and spawns it under Bun.
+ *
+ * The compiler cannot depend on @jxsuite/server (the server already depends on the compiler), and
+ * the dev server is Bun-native while the jx bin runs under Node — so the command is pure resolution
+ * + spawn: the entry module is resolved from the PROJECT's node_modules and executed with Bun.
+ *
+ * @module dev-command
+ */
+
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { spawn } from "node:child_process";
+import type { ChildProcess } from "node:child_process";
+
+/**
+ * Resolve the project's `@jxsuite/server/dev` entry module.
+ *
+ * @param {string} projectRoot - Absolute project root
+ * @returns {string} Absolute path to the dev entry module
+ * @throws {Error} With an install hint when the package is not present
+ */
+export function resolveDevEntry(projectRoot: string): string {
+  try {
+    const projectRequire = createRequire(join(projectRoot, "package.json"));
+    return projectRequire.resolve("@jxsuite/server/dev");
+  } catch {
+    throw new Error(
+      `@jxsuite/server is not installed in ${projectRoot}. ` +
+        `Add it to devDependencies (e.g. \`bun add -d @jxsuite/server\`) and retry.`,
+    );
+  }
+}
+
+/** The slice of `process` runDev touches — injectable for tests. */
+export interface ProcessLike {
+  on: (event: string, handler: () => void) => unknown;
+  exitCode?: number | string | undefined;
+}
+
+/**
+ * Spawn the dev server under Bun with inherited stdio.
+ *
+ * @param {string} projectRoot - Absolute project root
+ * @param {number | undefined} port - Optional port override
+ * @param {typeof spawn} [spawnImpl] - Injectable for tests
+ * @param {ProcessLike} [proc] - Injectable for tests
+ * @returns {ChildProcess} The spawned Bun process
+ */
+export function runDev(
+  projectRoot: string,
+  port: number | undefined,
+  spawnImpl: typeof spawn = spawn,
+  proc: ProcessLike = process as unknown as ProcessLike,
+): ChildProcess {
+  const entry = resolveDevEntry(projectRoot);
+  const args = [entry, "--root", projectRoot];
+  if (port !== undefined) {
+    args.push("--port", String(port));
+  }
+  const child = spawnImpl("bun", args, { stdio: "inherit" });
+  child.on("error", (error: NodeJS.ErrnoException) => {
+    if (error.code === "ENOENT") {
+      console.error(
+        "The Jx dev server runs on Bun, which was not found on your PATH. " +
+          "Install it from https://bun.sh and retry.",
+      );
+    } else {
+      console.error(`Failed to start the dev server: ${error.message}`);
+    }
+    proc.exitCode = 1;
+  });
+  // Ctrl+C reaches the child through the shared process group; also mirror explicit kills.
+  proc.on("SIGINT", () => {
+    child.kill("SIGINT");
+  });
+  proc.on("SIGTERM", () => {
+    child.kill("SIGTERM");
+  });
+  child.on("exit", (code) => {
+    proc.exitCode = code ?? 0;
+  });
+  return child;
+}

package/src/site/head-merger.ts

@@ -63,6 +63,19 @@ export function mergeHead(
       attributes: { href: canonical, rel: "canonical" },
       tagName: "link",
     });
+    // Auto OpenGraph identity (site-architecture §8.4) — author-supplied values win.
+    if (!merged.has("meta:og:url")) {
+      merged.set("meta:og:url", {
+        attributes: { content: canonical, property: "og:url" },
+        tagName: "meta",
+      });
+    }
+  }
+  if (context.siteName && !merged.has("meta:og:site_name")) {
+    merged.set("meta:og:site_name", {
+      attributes: { content: context.siteName, property: "og:site_name" },
+      tagName: "meta",
+    });
   }
 
   return [...merged.values()];

package/src/site/image-cache.ts

@@ -6,7 +6,7 @@
  * CI environments (e.g. Cloudflare Pages) can persist it via their npm cache layer.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { execSync } from "node:child_process";
 import { tmpdir } from "node:os";
@@ -23,6 +23,7 @@ interface CacheEntry {
 export interface CacheManifest {
   version: number; // Cache format version
   entries: Record<string, CacheEntry>; // Cached entries keyed by content+config hash
+  touched?: Set<string>; // Keys resolved during this build — runtime only, never serialized
 }
 
 // ─── Cache directory resolution ──────────────────────────────────────────────
@@ -97,25 +98,73 @@ export function cacheKey(srcPath: string, config: ImageConfig) {
 export function loadCache(projectRoot: string): CacheManifest {
   const manifestPath = resolve(getImageCacheDir(projectRoot), "manifest.json");
   if (!existsSync(manifestPath)) {
-    return { entries: {}, version: 1 };
+    return { entries: {}, touched: new Set(), version: 1 };
   }
   try {
-    return JSON.parse(readFileSync(manifestPath, "utf8")) as CacheManifest;
+    const parsed = JSON.parse(readFileSync(manifestPath, "utf8")) as CacheManifest;
+    parsed.touched = new Set();
+    return parsed;
   } catch {
-    return { entries: {}, version: 1 };
+    return { entries: {}, touched: new Set(), version: 1 };
   }
 }
 
 /**
  * Save the cache manifest to disk.
  *
+ * With `prune: true`, entries whose key was never touched during this build (deleted/replaced
+ * sources, superseded configs) are dropped and their variant files deleted first, so a persisted
+ * cache — and the dist copy made from it — stays bounded to images the build actually uses.
+ *
  * @param {string} projectRoot
  * @param {CacheManifest} cache
+ * @param {{ prune?: boolean }} [options]
  */
-export function saveCache(projectRoot: string, cache: CacheManifest) {
+export function saveCache(
+  projectRoot: string,
+  cache: CacheManifest,
+  options: { prune?: boolean } = {},
+) {
+  if (options.prune && cache.touched) {
+    pruneStale(cache, cache.touched);
+  }
   const cacheDir = getImageCacheDir(projectRoot);
   mkdirSync(cacheDir, { recursive: true });
-  writeFileSync(resolve(cacheDir, "manifest.json"), JSON.stringify(cache, null, 2), "utf8");
+  writeFileSync(
+    resolve(cacheDir, "manifest.json"),
+    JSON.stringify({ entries: cache.entries, version: cache.version }, null, 2),
+    "utf8",
+  );
+}
+
+/**
+ * Remove entries (and their variant files) that were not touched during this build. A file shared
+ * with a surviving entry is kept — the same source under an older config produces overlapping
+ * width/format filenames, so deleting blindly would remove files a live entry still references.
+ *
+ * @param {CacheManifest} cache
+ * @param {Set<string>} touched
+ */
+function pruneStale(cache: CacheManifest, touched: Set<string>) {
+  const keep = new Set<string>();
+  for (const [key, entry] of Object.entries(cache.entries)) {
+    if (touched.has(key)) {
+      for (const variant of entry.manifest.variants ?? []) {
+        keep.add(variant.absolutePath);
+      }
+    }
+  }
+  for (const [key, entry] of Object.entries(cache.entries)) {
+    if (touched.has(key)) {
+      continue;
+    }
+    for (const variant of entry.manifest.variants ?? []) {
+      if (!keep.has(variant.absolutePath)) {
+        rmSync(variant.absolutePath, { force: true });
+      }
+    }
+    delete cache.entries[key];
+  }
 }
 
 // ─── Entry access ─────────────────────────────────────────────────────────────
@@ -128,6 +177,7 @@ export function saveCache(projectRoot: string, cache: CacheManifest) {
  * @returns {ImageManifest | null}
  */
 export function getCached(cache: CacheManifest, key: string) {
+  cache.touched?.add(key);
   const entry = cache.entries[key];
   if (!entry) {
     return null;
@@ -149,6 +199,7 @@ export function setCached(
   sourcePath: string,
   manifest: ImageManifest,
 ) {
+  cache.touched?.add(key);
   cache.entries[key] = {
     manifest,
     source: sourcePath,

package/src/site/image-transform.ts

@@ -318,6 +318,7 @@ async function transformImgNode(
   }
 
   let srcset;
+  let dims: { width: number; height: number } | null = null;
 
   if (remote) {
     // Original dimensions are unknown without fetching — emit every configured width and let
@@ -332,6 +333,7 @@ async function transformImgNode(
     if (config.service === "cloudflare") {
       const meta = await resolveCfMeta(absoluteSrc, metaCache);
       srcset = buildCloudflareSrcset(src, config, meta.width ?? Infinity, meta.hash);
+      dims = meta.width && meta.height ? { height: meta.height, width: meta.width } : null;
     } else {
       let manifest = imageRefs.get(absoluteSrc);
 
@@ -342,6 +344,10 @@ async function transformImgNode(
 
       const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0]!;
       srcset = buildSrcset(manifest.variants, preferredFormat);
+      dims =
+        manifest.original?.width && manifest.original.height
+          ? { height: manifest.original.height, width: manifest.original.width }
+          : null;
     }
   }
 
@@ -350,6 +356,12 @@ async function transformImgNode(
     node.attributes.sizes ??= config.sizes;
   }
 
+  // Intrinsic dimensions prevent layout shift; author-supplied values win.
+  if (dims && node.attributes.width === undefined && node.attributes.height === undefined) {
+    node.attributes.width = String(dims.width);
+    node.attributes.height = String(dims.height);
+  }
+
   if (config.lazyLoad && node.attributes.loading !== "eager") {
     node.attributes.loading = "lazy";
     node.attributes.decoding = "async";
@@ -412,12 +424,14 @@ async function transformInnerHtmlImages(
     }
 
     let srcset;
+    let dims: { width: number; height: number } | null = null;
 
     if (remote) {
       srcset = buildCloudflareSrcset(src, config, Infinity, null);
     } else if (config.service === "cloudflare") {
       const meta = await resolveCfMeta(absoluteSrc as string, metaCache);
       srcset = buildCloudflareSrcset(src, config, meta.width ?? Infinity, meta.hash);
+      dims = meta.width && meta.height ? { height: meta.height, width: meta.width } : null;
     } else {
       let manifest = imageRefs.get(absoluteSrc as string);
       if (!manifest) {
@@ -427,12 +441,19 @@ async function transformInnerHtmlImages(
 
       const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0]!;
       srcset = buildSrcset(manifest.variants, preferredFormat);
+      dims =
+        manifest.original?.width && manifest.original.height
+          ? { height: manifest.original.height, width: manifest.original.width }
+          : null;
     }
     if (!srcset) {
       continue;
     }
 
     let extra = ` srcset="${srcset}" sizes="${config.sizes}"`;
+    if (dims && !/\bwidth=/.test(attrs) && !/\bheight=/.test(attrs)) {
+      extra += ` width="${dims.width}" height="${dims.height}"`;
+    }
     if (config.lazyLoad && !/\bloading="eager"/.test(attrs)) {
       if (!/\bloading=/.test(attrs)) {
         extra += ` loading="lazy"`;

package/src/site/preview-server.ts

@@ -0,0 +1,93 @@
+/**
+ * Preview server — `jx preview` serves an already-built dist/ directory.
+ *
+ * Dependency-free node:http static server, so the Node-run `jx` bin needs neither Bun nor the
+ * dev-server package. Maps directory URLs to index.html (the build's trailingSlash output) and
+ * falls back to <dist>/404.html when present.
+ *
+ * @module preview-server
+ */
+
+import { createServer } from "node:http";
+import type { Server } from "node:http";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { extname, join, normalize, resolve, sep } from "node:path";
+
+const MIME_TYPES: Record<string, string> = {
+  ".avif": "image/avif",
+  ".css": "text/css; charset=utf-8",
+  ".gif": "image/gif",
+  ".html": "text/html; charset=utf-8",
+  ".ico": "image/x-icon",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".md": "text/markdown; charset=utf-8",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".txt": "text/plain; charset=utf-8",
+  ".webp": "image/webp",
+  ".woff2": "font/woff2",
+  ".xml": "application/xml; charset=utf-8",
+};
+
+/**
+ * Resolve a request pathname to a file inside distDir, or null. Directory URLs (with or without a
+ * trailing slash) map to their index.html; traversal outside distDir is rejected.
+ *
+ * @param {string} distDir - Absolute dist directory
+ * @param {string} pathname - Decoded URL pathname
+ * @returns {string | null} Absolute file path to serve, or null
+ */
+export function resolvePreviewFile(distDir: string, pathname: string): string | null {
+  const safe = normalize(pathname).replaceAll("\\", "/");
+  const candidate = resolve(distDir, `.${safe.startsWith("/") ? safe : `/${safe}`}`);
+  if (candidate !== distDir && !candidate.startsWith(distDir + sep)) {
+    return null;
+  }
+  if (existsSync(candidate)) {
+    if (statSync(candidate).isDirectory()) {
+      const index = join(candidate, "index.html");
+      return existsSync(index) ? index : null;
+    }
+    return candidate;
+  }
+  // Extensionless route without trailing slash → its directory index
+  const index = join(candidate, "index.html");
+  return existsSync(index) ? index : null;
+}
+
+/**
+ * Start the preview server on the given port (0 picks a free port).
+ *
+ * @param {string} distDir - Absolute path to the built dist directory
+ * @param {number} port - Port to listen on
+ * @returns {Server} The listening node:http server
+ */
+export function startPreviewServer(distDir: string, port: number): Server {
+  const dist = resolve(distDir);
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const filePath = resolvePreviewFile(dist, decodeURIComponent(url.pathname));
+
+    if (filePath) {
+      res.writeHead(200, {
+        "Content-Type": MIME_TYPES[extname(filePath).toLowerCase()] ?? "application/octet-stream",
+      });
+      res.end(readFileSync(filePath));
+      return;
+    }
+
+    const notFound = join(dist, "404.html");
+    if (existsSync(notFound)) {
+      res.writeHead(404, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(readFileSync(notFound));
+      return;
+    }
+    res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+    res.end("Not found");
+  });
+  server.listen(port);
+  return server;
+}

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(