@jxsuite/compiler 0.5.5 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {
@@ -37,10 +37,11 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^15.3.5",
-    "@jxsuite/parser": "^0.5.0",
-    "@jxsuite/runtime": "^0.5.0",
+    "@jxsuite/parser": "^0.5.5",
+    "@jxsuite/runtime": "^0.5.5",
     "remark-gfm": "^4.0.1",
     "remark-stringify": "^11.0.0",
+    "sharp": "^0.34.5",
     "unified": "^11.0.5"
   },
   "devDependencies": {

package/src/compiler.js

@@ -22,7 +22,7 @@ import {
   DEFAULT_REACTIVITY_SRC,
   DEFAULT_LIT_HTML_SRC,
 } from "./shared.js";
-import { compileServer } from "./targets/compile-server.js";
+import { compileServer, compileSiteServer } from "./targets/compile-server.js";
 import {
   compileElement,
   compileElementPage,
@@ -32,7 +32,14 @@ import { compileStaticPage } from "./targets/compile-static.js";
 import { compileClient } from "./targets/compile-client.js";
 
 // Re-exports for consumers
-export { isDynamic, compileServer, compileElement, compileElementPage, compileClient };
+export {
+  isDynamic,
+  compileServer,
+  compileSiteServer,
+  compileElement,
+  compileElementPage,
+  compileClient,
+};
 
 // ─── Entry ────────────────────────────────────────────────────────────────────
 

package/src/shared.js

@@ -446,6 +446,11 @@ export function buildAttrs(def, scope) {
     }
   }
 
+  if (def.tagName === "img") {
+    if (!def.attributes?.loading) out += ` loading="lazy"`;
+    if (!def.attributes?.decoding) out += ` decoding="async"`;
+  }
+
   if (def.$props && typeof def.$props === "object") {
     out += ` data-jx-props="${escapeHtml(JSON.stringify(def.$props))}"`;
   }
@@ -769,7 +774,7 @@ function _walkServerEntries(def, entries) {
 // ─── Component pre-rendering ─────────────────────────────────────────────────
 
 /** @type {Set<string>} */
-const SELF_CLOSING = new Set(["input", "br", "hr", "img", "meta", "link", "area", "col"]);
+const SELF_CLOSING = new Set(["input", "br", "hr", "img", "meta", "link", "area", "col", "source"]);
 
 /**
  * Recursively render a Jx node tree to static HTML for pre-rendering.

package/src/site/image-cache.js

@@ -0,0 +1,106 @@
+/**
+ * Image-cache.js — Content-hash based cache for processed image variants.
+ *
+ * Stores a manifest of previously processed images so that unchanged sources can skip re-encoding
+ * on subsequent builds. Cache lives in .jx-cache/images/.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { contentHash, configHash } from "./image-optimizer.js";
+
+/**
+ * @typedef {import("./image-optimizer.js").ImageManifest} ImageManifest
+ *
+ * @typedef {import("./image-optimizer.js").ImageConfig} ImageConfig
+ */
+
+/**
+ * @typedef {Object} CacheEntry
+ * @property {string} source - Relative path to source image
+ * @property {ImageManifest} manifest - Processed image manifest
+ * @property {number} timestamp - When the entry was cached
+ */
+
+/**
+ * @typedef {Object} CacheManifest
+ * @property {number} version - Cache format version
+ * @property {Record<string, CacheEntry>} entries - Cached entries keyed by content+config hash
+ */
+
+/**
+ * Build a cache key from source file content and config.
+ *
+ * @param {string} srcPath - Absolute path to source image
+ * @param {ImageConfig} config
+ * @returns {string}
+ */
+export function cacheKey(srcPath, config) {
+  return `${contentHash(srcPath)}:${configHash(config)}`;
+}
+
+/**
+ * Load the cache manifest from disk, or return an empty one.
+ *
+ * @param {string} projectRoot
+ * @returns {CacheManifest}
+ */
+export function loadCache(projectRoot) {
+  const manifestPath = resolve(projectRoot, ".jx-cache/images/manifest.json");
+  if (!existsSync(manifestPath)) {
+    return { version: 1, entries: {} };
+  }
+  try {
+    return JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch {
+    return { version: 1, entries: {} };
+  }
+}
+
+/**
+ * Save the cache manifest to disk.
+ *
+ * @param {string} projectRoot
+ * @param {CacheManifest} cache
+ */
+export function saveCache(projectRoot, cache) {
+  const cacheDir = resolve(projectRoot, ".jx-cache/images");
+  mkdirSync(cacheDir, { recursive: true });
+  writeFileSync(resolve(cacheDir, "manifest.json"), JSON.stringify(cache, null, 2), "utf8");
+}
+
+/**
+ * Check if a cache entry exists and its output files are still present.
+ *
+ * @param {CacheManifest} cache
+ * @param {string} key
+ * @param {string} outDir - Absolute path to build output dir
+ * @returns {ImageManifest | null}
+ */
+export function getCached(cache, key, outDir) {
+  const entry = cache.entries[key];
+  if (!entry) return null;
+
+  const allExist = entry.manifest.variants.every((v) =>
+    existsSync(resolve(outDir, v.outputPath.slice(1))),
+  );
+  if (!allExist) return null;
+
+  return entry.manifest;
+}
+
+/**
+ * Store a processed result in the cache.
+ *
+ * @param {CacheManifest} cache
+ * @param {string} key
+ * @param {string} sourcePath - Relative source path for reference
+ * @param {ImageManifest} manifest
+ */
+export function setCached(cache, key, sourcePath, manifest) {
+  cache.entries[key] = {
+    source: sourcePath,
+    manifest,
+    timestamp: Date.now(),
+  };
+}

package/src/site/image-optimizer.js

@@ -0,0 +1,187 @@
+/**
+ * Image-optimizer.js — Sharp wrapper for image resizing and format conversion.
+ *
+ * Generates responsive image variants (WebP, AVIF) at configured breakpoint widths. Returns an
+ * ImageManifest describing all generated variants with their output paths.
+ */
+
+import { createHash } from "node:crypto";
+import { readFileSync, mkdirSync, existsSync } from "node:fs";
+import { resolve, basename, extname } from "node:path";
+
+/** @type {typeof import("sharp") | null} */
+let _sharp = null;
+
+async function getSharp() {
+  if (_sharp) return _sharp;
+  try {
+    const sharpMod = await import("sharp");
+    _sharp = sharpMod.default;
+    return _sharp;
+  } catch (e) {
+    throw new Error(
+      `Sharp is required for image optimization but failed to load: ${/** @type {any} */ (e).message}`,
+    );
+  }
+}
+
+/**
+ * @typedef {Object} ImageVariant
+ * @property {number} width - Pixel width of the variant
+ * @property {string} format - "webp", "avif", "jpeg", "png"
+ * @property {string} outputPath - Relative path from outDir (e.g.
+ *   "/images/_optimized/hero-640-a1b2c3d4.webp")
+ * @property {string} absolutePath - Absolute filesystem path to the generated file
+ */
+
+/**
+ * @typedef {Object} ImageManifest
+ * @property {{ width: number; height: number; format: string }} original - Original image
+ *   dimensions and format
+ * @property {ImageVariant[]} variants - Array of generated responsive variants
+ * @property {string} contentHash - 8-char content hash for cache busting
+ */
+
+/**
+ * @typedef {Object} ImageConfig
+ * @property {boolean} optimize - Enable image optimization
+ * @property {number[]} widths - Breakpoint widths to generate
+ * @property {string[]} formats - Output formats ("webp", "avif", etc.)
+ * @property {{ webp?: number; avif?: number; jpeg?: number; png?: number }} quality - Compression
+ *   quality per format
+ * @property {string} sizes - CSS sizes attribute for srcset
+ * @property {boolean} lazyLoad - Add loading="lazy" and decoding="async"
+ */
+
+const OPTIMIZED_DIR = "images/_optimized";
+
+/**
+ * Get image metadata (dimensions and format) via Sharp.
+ *
+ * @param {string} srcPath - Absolute path to source image
+ * @returns {Promise<{ width: number; height: number; format: string }>}
+ */
+export async function getImageMetadata(srcPath) {
+  const sharp = await getSharp();
+  const meta = await sharp(srcPath).metadata();
+  return {
+    width: meta.width ?? 0,
+    height: meta.height ?? 0,
+    format: meta.format ?? "unknown",
+  };
+}
+
+/**
+ * Compute a content hash for a source image file.
+ *
+ * @param {string} srcPath - Absolute path to source image
+ * @returns {string} 8-character hex hash
+ */
+export function contentHash(srcPath) {
+  const buf = readFileSync(srcPath);
+  return createHash("md5").update(buf).digest("hex").slice(0, 8);
+}
+
+/**
+ * Compute a config hash from the image optimization settings.
+ *
+ * @param {ImageConfig} config
+ * @returns {string}
+ */
+export function configHash(config) {
+  const key = JSON.stringify({
+    widths: config.widths,
+    formats: config.formats,
+    quality: config.quality,
+  });
+  return createHash("md5").update(key).digest("hex").slice(0, 8);
+}
+
+/**
+ * Build the output filename for a variant.
+ *
+ * @param {string} stem - Original filename without extension
+ * @param {number} width
+ * @param {string} hash8 - 8-char content hash
+ * @param {string} format - "webp", "avif", "jpeg", "png"
+ * @returns {string}
+ */
+export function variantFilename(stem, width, hash8, format) {
+  return `${stem}-${width}-${hash8}.${format}`;
+}
+
+/**
+ * Process a single source image: resize to each configured width, encode to each format.
+ *
+ * @param {string} srcPath - Absolute path to source image
+ * @param {string} outDir - Absolute path to the build output directory (dist/)
+ * @param {ImageConfig} config
+ * @returns {Promise<ImageManifest>}
+ */
+export async function processImage(srcPath, outDir, config) {
+  const sharp = await getSharp();
+  const meta = await getImageMetadata(srcPath);
+  const hash8 = contentHash(srcPath);
+  const stem = basename(srcPath, extname(srcPath));
+
+  const optimizedDir = resolve(outDir, OPTIMIZED_DIR);
+  mkdirSync(optimizedDir, { recursive: true });
+
+  /** @type {ImageVariant[]} */
+  const variants = [];
+
+  const widths = config.widths.filter((w) => w <= meta.width);
+  if (widths.length === 0 || !widths.includes(meta.width)) {
+    widths.push(meta.width);
+  }
+  widths.sort((a, b) => a - b);
+
+  /** @type {Promise<void>[]} */
+  const tasks = [];
+
+  for (const width of widths) {
+    for (const format of config.formats) {
+      const filename = variantFilename(stem, width, hash8, format);
+      const outputPath = `/${OPTIMIZED_DIR}/${filename}`;
+      const absolutePath = resolve(optimizedDir, filename);
+
+      variants.push({ width, format, outputPath, absolutePath });
+
+      if (existsSync(absolutePath)) continue;
+
+      const quality = config.quality[/** @type {keyof ImageConfig["quality"]} */ (format)] ?? 80;
+      const task = sharp(srcPath)
+        .resize(width)
+        .toFormat(/** @type {any} */ (format), { quality })
+        .toFile(absolutePath)
+        .then(() => {});
+
+      tasks.push(task);
+    }
+  }
+
+  const CONCURRENCY = 4;
+  for (let i = 0; i < tasks.length; i += CONCURRENCY) {
+    await Promise.all(tasks.slice(i, i + CONCURRENCY));
+  }
+
+  return {
+    original: { width: meta.width, height: meta.height, format: meta.format },
+    variants,
+    contentHash: hash8,
+  };
+}
+
+/**
+ * Build a srcset string from variants of a specific format.
+ *
+ * @param {ImageVariant[]} variants
+ * @param {string} format
+ * @returns {string}
+ */
+export function buildSrcset(variants, format) {
+  return variants
+    .filter((v) => v.format === format)
+    .map((v) => `${v.outputPath} ${v.width}w`)
+    .join(", ");
+}

package/src/site/image-transform.js

@@ -0,0 +1,149 @@
+/**
+ * Image-transform.js — Document tree walker for responsive image optimization.
+ *
+ * Walks a Jx document tree, finds <img> nodes with static src paths, and injects srcset, sizes,
+ * width, height, loading, and decoding attributes. Collects image references so the build
+ * orchestrator knows which files to process.
+ */
+
+import { existsSync } from "node:fs";
+import { resolve, extname } from "node:path";
+import { processImage, buildSrcset, contentHash, configHash } from "./image-optimizer.js";
+import { getCached, setCached } from "./image-cache.js";
+
+/**
+ * @typedef {import("./image-optimizer.js").ImageConfig} ImageConfig
+ *
+ * @typedef {import("./image-optimizer.js").ImageManifest} ImageManifest
+ *
+ * @typedef {import("./image-cache.js").CacheManifest} CacheManifest
+ */
+
+const SKIP_EXTENSIONS = new Set([".svg", ".gif"]);
+const EXTERNAL_PREFIXES = ["http://", "https://", "data:", "//"];
+
+/**
+ * Check if a src value should be skipped for optimization.
+ *
+ * @param {any} src
+ * @returns {boolean}
+ */
+function shouldSkip(src) {
+  if (typeof src !== "string") return true;
+  if (src.includes("${")) return true;
+  if (EXTERNAL_PREFIXES.some((p) => src.startsWith(p))) return true;
+  if (SKIP_EXTENSIONS.has(extname(src).toLowerCase())) return true;
+  return false;
+}
+
+/**
+ * Resolve a src path to an absolute filesystem path.
+ *
+ * Handles paths starting with "/" (relative to public dir or project root).
+ *
+ * @param {string} src
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+function resolveImagePath(src, projectRoot) {
+  if (src.startsWith("/")) {
+    return resolve(projectRoot, "public", src.slice(1));
+  }
+  return resolve(projectRoot, src);
+}
+
+/**
+ * Transform image nodes in a Jx document tree.
+ *
+ * Mutates img nodes in place, injecting srcset, sizes, width, height, loading, and decoding.
+ * Returns a set of absolute source paths that need processing.
+ *
+ * @param {any} doc - The Jx document tree (mutated in place)
+ * @param {ImageConfig} config
+ * @param {string} projectRoot
+ * @param {string} outDir
+ * @param {CacheManifest} cache
+ * @returns {Promise<{ imageRefs: Map<string, ImageManifest> }>}
+ */
+export async function transformImageNodes(doc, config, projectRoot, outDir, cache) {
+  /** @type {Map<string, ImageManifest>} */
+  const imageRefs = new Map();
+
+  if (!config.optimize) return { imageRefs };
+
+  await walkAndTransform(doc, config, projectRoot, outDir, cache, imageRefs);
+
+  return { imageRefs };
+}
+
+/**
+ * @param {any} node
+ * @param {ImageConfig} config
+ * @param {string} projectRoot
+ * @param {string} outDir
+ * @param {CacheManifest} cache
+ * @param {Map<string, ImageManifest>} imageRefs
+ */
+async function walkAndTransform(node, config, projectRoot, outDir, cache, imageRefs) {
+  if (!node || typeof node !== "object") return;
+
+  if (node.tagName === "img") {
+    await transformImgNode(node, config, projectRoot, outDir, cache, imageRefs);
+  }
+
+  if (Array.isArray(node.children)) {
+    for (const child of node.children) {
+      await walkAndTransform(child, config, projectRoot, outDir, cache, imageRefs);
+    }
+  }
+}
+
+/**
+ * @param {any} node
+ * @param {ImageConfig} config
+ * @param {string} projectRoot
+ * @param {string} outDir
+ * @param {CacheManifest} cache
+ * @param {Map<string, ImageManifest>} imageRefs
+ */
+async function transformImgNode(node, config, projectRoot, outDir, cache, imageRefs) {
+  if (!node.attributes) node.attributes = {};
+
+  const src = node.attributes.src ?? node.src;
+  if (shouldSkip(src)) return;
+  if (node.attributes["data-no-optimize"] !== undefined) return;
+
+  const absoluteSrc = resolveImagePath(src, projectRoot);
+  if (!existsSync(absoluteSrc)) return;
+
+  let manifest = imageRefs.get(absoluteSrc);
+
+  if (!manifest) {
+    const key = `${contentHash(absoluteSrc)}:${configHash(config)}`;
+    const cached = getCached(cache, key, outDir);
+    manifest = cached ?? (await processImage(absoluteSrc, outDir, config));
+
+    setCached(cache, key, src, manifest);
+    imageRefs.set(absoluteSrc, manifest);
+  }
+
+  const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0];
+  const srcset = buildSrcset(manifest.variants, preferredFormat);
+
+  if (srcset) {
+    node.attributes.srcset = srcset;
+    node.attributes.sizes = node.attributes.sizes ?? config.sizes;
+  }
+
+  if (!node.attributes.width && manifest.original.width) {
+    node.attributes.width = String(manifest.original.width);
+  }
+  if (!node.attributes.height && manifest.original.height) {
+    node.attributes.height = String(manifest.original.height);
+  }
+
+  if (config.lazyLoad && node.attributes.loading !== "eager") {
+    node.attributes.loading = "lazy";
+    node.attributes.decoding = "async";
+  }
+}

package/src/site/site-build.js

@@ -23,7 +23,7 @@ import { discoverPages, expandDynamicRoutes } from "./pages-discovery.js";
 import { resolveLayout } from "./layout-resolver.js";
 import { mergeHead, renderHead } from "./head-merger.js";
 import { injectContext } from "./context-injection.js";
-import { compile, compileServer } from "../compiler.js";
+import { compile, compileServer, compileSiteServer } from "../compiler.js";
 import { compileElement } from "../targets/compile-element.js";
 import {
   buildInitialScope,
@@ -32,12 +32,15 @@ import {
   preRenderComponentHtml,
   isComponentFullyStatic,
   buildComponentCSS,
+  collectServerEntries,
   DEFAULT_REACTIVITY_SRC,
   DEFAULT_LIT_HTML_SRC,
 } from "../shared.js";
 import { loadCollections, loadContentConfig, resolveCollectionRefs } from "./content-loader.js";
 import { resolvePrototypes } from "./prototype-resolver.js";
 import { compileMarkdown } from "../targets/compile-markdown.js";
+import { transformImageNodes } from "./image-transform.js";
+import { loadCache, saveCache } from "./image-cache.js";
 
 /**
  * Build an entire Jx site from a project directory.
@@ -156,12 +159,34 @@ export async function buildSite(projectRoot, options = {}) {
     );
   }
 
+  // ── 5b. Collect server entries from components (for site-wide bundling) ──
+  /** @type {{ exportName: string; src: string }[]} */
+  const siteServerEntries = [];
+  if (projectConfig.build.provider) {
+    for (const [, doc] of componentDefs) {
+      const entries = collectServerEntries(doc);
+      for (const entry of entries) {
+        const resolvedSrc = "./" + join("components", entry.src.replace(/^\.\//, ""));
+        siteServerEntries.push({ exportName: entry.exportName, src: resolvedSrc });
+      }
+    }
+  }
+
   // ── 6. Compile each route ───────────────────────────────────────────────
 
+  const imageCache = projectConfig.images.optimize ? loadCache(projectRoot) : null;
+
   for (const route of routes) {
     try {
       log(`  Compiling ${route.urlPattern} ...`);
-      const result = await compilePage(route, projectConfig, projectRoot, collections);
+      const result = await compilePage(
+        route,
+        projectConfig,
+        projectRoot,
+        collections,
+        imageCache,
+        outDir,
+      );
 
       // Inject pre-rendered component HTML scaffolding (instance-aware)
       // Must happen before script injection so we know which tags are fully static
@@ -224,6 +249,36 @@ export async function buildSite(projectRoot, options = {}) {
     }
   }
 
+  // ── 6b. Save image cache ─────────────────────────────────────────────
+  if (imageCache && projectConfig.images.optimize) {
+    saveCache(projectRoot, imageCache);
+    const totalImages = Object.keys(imageCache.entries).length;
+    if (totalImages > 0) {
+      log(`  Optimized ${totalImages} image(s)`);
+    }
+  }
+
+  // ── 6c. Generate site-wide server worker ────────────────────────────────
+  if (projectConfig.build.provider && siteServerEntries.length > 0) {
+    log("Generating site-wide server worker...");
+
+    const deduped = new Map();
+    for (const entry of siteServerEntries) {
+      if (!deduped.has(entry.exportName)) deduped.set(entry.exportName, entry);
+    }
+
+    const workerSource = compileSiteServer([...deduped.values()], {
+      provider: projectConfig.build.provider,
+    });
+
+    if (workerSource) {
+      const workerPath = resolve(projectRoot, "_worker.js");
+      writeFileSync(workerPath, workerSource, "utf8");
+      fileCount++;
+      log(`  Generated _worker.js (${deduped.size} server function(s))`);
+    }
+  }
+
   // ── 7. Generate redirects ───────────────────────────────────────────────
   if (projectConfig.redirects && Object.keys(projectConfig.redirects).length > 0) {
     log("Generating redirects...");
@@ -266,9 +321,18 @@ export async function buildSite(projectRoot, options = {}) {
  * @param {any} projectConfig
  * @param {string} projectRoot
  * @param {Map<string, any[]>} [collections]
+ * @param {import("./image-cache.js").CacheManifest | null} [imageCache]
+ * @param {string} [outDir]
  * @returns {Promise<{ html: string; files: any[]; serverHandler: string | null; doc: any }>}
  */
-async function compilePage(route, projectConfig, projectRoot, collections = new Map()) {
+async function compilePage(
+  route,
+  projectConfig,
+  projectRoot,
+  collections = new Map(),
+  imageCache = null,
+  outDir = "",
+) {
   // Load the raw page document
   let pageDoc;
   if (route.sourcePath.endsWith(".md")) {
@@ -346,6 +410,11 @@ async function compilePage(route, projectConfig, projectRoot, collections = new
     layoutDoc.$media = { ...projectConfig.$media, ...layoutDoc.$media };
   }
 
+  // Transform <img> nodes for responsive image optimization
+  if (imageCache && projectConfig.images?.optimize && outDir) {
+    await transformImageNodes(layoutDoc, projectConfig.images, projectRoot, outDir, imageCache);
+  }
+
   // Compile the document using the existing compiler
   const result = await compile(layoutDoc, {
     title,
@@ -364,16 +433,18 @@ async function compilePage(route, projectConfig, projectRoot, collections = new
     result.html = injectNpmElementScripts(result.html, npmElements);
   }
 
-  // Compile server handler if applicable
+  // Compile server handler if applicable (skip when provider bundles site-wide)
   /** @type {string | null} */
   let serverHandler = null;
-  try {
-    const serverResult = await compileServer(route.sourcePath);
-    if (serverResult) {
-      serverHandler = serverResult;
+  if (!projectConfig.build.provider) {
+    try {
+      const serverResult = await compileServer(route.sourcePath);
+      if (serverResult) {
+        serverHandler = serverResult;
+      }
+    } catch {
+      // No server entries — that's fine
     }
-  } catch {
-    // No server entries — that's fine
   }
 
   return { html: result.html, files: result.files, serverHandler, doc: layoutDoc };

package/src/site/site-loader.js

@@ -27,10 +27,19 @@ const DEFAULTS = {
   state: {},
   collections: {},
   redirects: {},
+  images: {
+    optimize: true,
+    widths: [320, 640, 960, 1280, 1920],
+    formats: ["webp", "avif"],
+    quality: { webp: 80, avif: 65, jpeg: 80, png: 80 },
+    sizes: "(max-width: 768px) 100vw, 50vw",
+    lazyLoad: true,
+  },
   build: {
     outDir: "./dist",
     format: "directory",
     trailingSlash: "always",
+    provider: null,
   },
 };
 
@@ -65,6 +74,7 @@ export function loadProjectConfig(projectRoot) {
     ...DEFAULTS,
     ...raw,
     defaults: { ...DEFAULTS.defaults, ...raw.defaults },
+    images: { ...DEFAULTS.images, ...raw.images },
     build: { ...DEFAULTS.build, ...raw.build },
   };