@jxsuite/compiler 2.0.8 → 3.0.0

package/src/site/image-transform.ts

@@ -25,7 +25,7 @@ import { imgLoadingAttrs } from "./img-loading.ts";
 import { resolveAssetUrl } from "@jxsuite/schema/asset-paths";
 
 import type { AssetMount } from "@jxsuite/schema/asset-paths";
-import type { ImageConfig, ImageManifest } from "./image-optimizer.ts";
+import type { ImageConfig, ImageManifest, ImageVariant } from "./image-optimizer.ts";
 import type { JxDocument, JxMutableNode } from "@jxsuite/schema/types";
 import type { CacheManifest } from "./image-cache.ts";
 
@@ -267,13 +267,23 @@ async function walkAndTransform(
   metaCache: ImageMetaCache,
   imageRefs: Map<string, ImageManifest>,
   mounts: readonly AssetMount[],
+  containerWidth: number | null = null,
 ) {
   if (!node || typeof node !== "object") {
     return;
   }
 
   if (node.tagName === "img") {
-    await transformImgNode(node, config, projectRoot, cache, metaCache, imageRefs, mounts);
+    await transformImgNode(
+      node,
+      config,
+      projectRoot,
+      cache,
+      metaCache,
+      imageRefs,
+      mounts,
+      containerWidth,
+    );
     // Wrapping rewrote this node into a `<picture>` whose children this pass just authored.
     // Descending into them would find the `<img>` and wrap it again, forever.
     if (node.tagName !== "img") {
@@ -294,11 +304,22 @@ async function walkAndTransform(
   }
 
   if (Array.isArray(node.children)) {
+    // Every descendant is bounded by the narrowest literal max-width above it.
+    const inner = containerWidthOf(node, containerWidth);
     for (const child of node.children) {
       if (typeof child === "string") {
         continue;
       }
-      await walkAndTransform(child, config, projectRoot, cache, metaCache, imageRefs, mounts);
+      await walkAndTransform(
+        child,
+        config,
+        projectRoot,
+        cache,
+        metaCache,
+        imageRefs,
+        mounts,
+        inner,
+      );
     }
   }
 }
@@ -327,6 +348,8 @@ interface ResolvedVariants {
   dims: { width: number; height: number } | null;
   /** One entry per additional format, when the image is to be wrapped in a `<picture>`. */
   sources: PictureSource[];
+  /** Resized last-resort `src`, when a universally decodable format was emitted. */
+  fallbackSrc?: string | undefined;
 }
 
 /**
@@ -417,7 +440,43 @@ async function resolveVariants(
    * format information, so a browser that cannot decode AVIF would still pick an AVIF candidate.
    */
   const wrap = config.picture !== false && available.length > 1;
-  return { dims, sources: wrap ? available : [], srcset: available[0]?.srcset ?? "" };
+  return {
+    dims,
+    fallbackSrc: fallbackVariant(manifest.variants, config.formats),
+    sources: wrap ? available : [],
+    srcset: available[0]?.srcset ?? "",
+  };
+}
+
+/**
+ * Formats an `<img src>` may point at without narrowing who can see the image.
+ *
+ * `src` is the last resort — reached only by a client that understood neither `srcset` nor any
+ * `<source type>`, which in practice means it understands JPEG and PNG and little else.
+ */
+const UNIVERSAL_FORMATS: readonly string[] = ["jpeg", "png"];
+
+/**
+ * The largest emitted variant a `src` can safely fall back to, or `undefined` to keep the original.
+ *
+ * The original is a correct fallback and a terrible one: it is the unresized source, so a 3840 px
+ * screenshot leaves a 1.7 MB PNG on the end of the chain. A resized variant of the same universally
+ * decodable format is strictly better. When the project emits no such format — `["webp", "avif"]`
+ * is a common and reasonable choice — there is nothing safe to point at, and the original stays: a
+ * smaller image nobody can decode is not an improvement.
+ */
+function fallbackVariant(variants: ImageVariant[], formats: readonly string[]): string | undefined {
+  const format = UNIVERSAL_FORMATS.find((candidate) => formats.includes(candidate));
+  if (format === undefined) {
+    return undefined;
+  }
+  let best: ImageVariant | undefined;
+  for (const variant of variants) {
+    if (variant.format === format && (best === undefined || variant.width > best.width)) {
+      best = variant;
+    }
+  }
+  return best?.outputPath;
 }
 
 /**
@@ -429,6 +488,61 @@ async function resolveVariants(
  * @param {Map<string, ImageManifest>} imageRefs
  * @param {readonly AssetMount[]} mounts
  */
+const CSS_LENGTH = /^(\d+(?:\.\d+)?)(px|rem)$/;
+
+/** A CSS length in px, but only when it is a plain `px`/`rem` literal. `null` for anything else. */
+function pxLength(value: unknown): number | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const match = CSS_LENGTH.exec(value.trim());
+  if (!match) {
+    return null;
+  }
+  const n = Number(match[1]);
+  return match[2] === "rem" ? n * 16 : n;
+}
+
+/**
+ * The narrowest px `max-width`/`width` an element at this point in the tree sits inside.
+ *
+ * Only literal lengths count. A `clamp()`, a percentage or a custom property is a real constraint
+ * too, but not one the build can resolve — and a wrong `sizes` is worse than none, because the
+ * browser trusts it completely and picks its candidate before layout exists to contradict it.
+ */
+function containerWidthOf(
+  node: JxMutableNode | JxDocument,
+  inherited: number | null,
+): number | null {
+  const style = node.style as Record<string, unknown> | undefined;
+  if (!style || typeof style !== "object") {
+    return inherited;
+  }
+  const declared = pxLength(style.maxWidth) ?? pxLength(style.width);
+  if (declared === null) {
+    return inherited;
+  }
+  return inherited === null ? declared : Math.min(inherited, declared);
+}
+
+/**
+ * The `sizes` an image in a `max-width` container needs.
+ *
+ * `sizes` is a promise about layout, and the browser keeps the browser's side of it absolutely: it
+ * picks a candidate from this string before any layout has happened, and never revisits the choice.
+ * A single project-wide string therefore cannot be right — jxsuite.com's `(max-width: 768px) 100vw,
+ * 50vw` describes a half-width image, while its hero renders full-width inside a 960 px column, so
+ * the same string is too small on a wide screen and too large on a narrow one. The container width
+ * is layout the compiler already holds, so it is the better answer wherever it exists.
+ */
+function sizesForContainer(containerWidth: number | null): string | undefined {
+  if (containerWidth === null) {
+    return undefined;
+  }
+  const width = Math.round(containerWidth);
+  return `(max-width: ${width}px) 100vw, ${width}px`;
+}
+
 async function transformImgNode(
   node: JxMutableNode | JxDocument,
   config: ImageConfig,
@@ -437,6 +551,7 @@ async function transformImgNode(
   metaCache: ImageMetaCache,
   imageRefs: Map<string, ImageManifest>,
   mounts: readonly AssetMount[],
+  containerWidth: number | null = null,
 ) {
   if (!node.attributes) {
     node.attributes = {};
@@ -465,10 +580,24 @@ async function transformImgNode(
       )
     : null;
 
+  /*
+   * Precedence: what the author wrote, then what the layout says, then the project-wide default.
+   * The project default is a guess that cannot see the container; the container width is not a
+   * guess, so it outranks it — and an image with neither keeps whatever the project chose.
+   */
+  const ownWidth = containerWidthOf(node, containerWidth);
+  const resolvedSizes =
+    (attrs.sizes as string | undefined) ?? sizesForContainer(ownWidth) ?? config.sizes;
+
   if (variants) {
     if (variants.srcset !== "") {
       attrs.srcset = variants.srcset;
-      attrs.sizes ??= config.sizes;
+      if (resolvedSizes !== undefined) {
+        attrs.sizes = resolvedSizes;
+      }
+      if (variants.fallbackSrc !== undefined) {
+        attrs.src = variants.fallbackSrc;
+      }
     }
     // Intrinsic dimensions prevent layout shift; author-supplied values win.
     if (variants.dims && attrs.width === undefined && attrs.height === undefined) {
@@ -480,7 +609,7 @@ async function transformImgNode(
   Object.assign(attrs, imgLoadingAttrs(attrs, config.lazyLoad));
 
   if (variants && variants.sources.length > 0) {
-    wrapInPicture(node, variants.sources, config.sizes);
+    wrapInPicture(node, variants.sources, resolvedSizes ?? "");
   }
 }
 
@@ -515,7 +644,12 @@ function wrapInPicture(
   node.attributes = {};
   node.children = [
     ...sources.map((source) => ({
-      attributes: { sizes: inheritedSizes, srcset: source.srcset, type: source.type },
+      attributes: {
+        // An empty `sizes` is not a neutral default — omit it and let the browser assume 100vw.
+        ...(inheritedSizes === "" ? {} : { sizes: inheritedSizes }),
+        srcset: source.srcset,
+        type: source.type,
+      },
       tagName: "source",
     })),
     img,

package/src/site/layout-resolver.ts

@@ -1,210 +1,48 @@
 /**
- * Layout-resolver.js — Layout loading and slot distribution at compile time
+ * The build's filesystem half of layout resolution.
  *
- * Resolves $layout references, loads layout JSON files, and distributes page content into layout
- * <slot> elements. This is the compile-time equivalent of the runtime's distributeSlots()
- * algorithm.
- *
- * Per site-architecture spec §5:
- *
- * - Layouts are JSON files in the layouts/ directory
- * - Pages reference layouts via "$layout": "./layouts/base.json"
- * - The page's children are distributed into the layout's <slot> elements
- * - Named slots use attributes.slot on page children
+ * The rule — which layout a page uses, how its children land in the layout's slots, which
+ * properties the page extends onto it — is `@jxsuite/site/layout`, because the studio's canvas and
+ * the cloud's live preview have to reach the same answer and neither can import this package. What
+ * is left here is the part that genuinely needs a disk: turning `./layouts/base.json` into bytes,
+ * and saying which file was wrong when it is.
  */
 
 import { existsSync, readFileSync } from "node:fs";
 import { parseJxDocument } from "@jxsuite/schema/parse";
 import { resolve } from "node:path";
-import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import { resolveLayout as resolveLayoutWith } from "@jxsuite/site/layout";
+import type { LayoutLoader } from "@jxsuite/site/layout";
+import type { JxDocument } from "@jxsuite/schema/types";
+
+/** A {@link LayoutLoader} over the project's own directory. */
+export function nodeLayoutLoader(projectRoot: string): LayoutLoader {
+  return (layoutRef: string) => {
+    const layoutPath = resolve(projectRoot, layoutRef);
+    if (!existsSync(layoutPath)) {
+      throw new Error(`Layout not found: ${layoutRef} (resolved to ${layoutPath})`);
+    }
+    try {
+      return parseJxDocument(readFileSync(layoutPath, "utf8"), layoutPath);
+    } catch (error) {
+      const err = error as Error;
+      throw new Error(`Invalid layout JSON at ${layoutPath}: ${err.message}`, { cause: error });
+    }
+  };
+}
 
 /**
- * Resolve a page's layout, wrapping the page content in the layout structure.
+ * Resolve a page's layout against a project on disk.
  *
- * @param {JxDocument} pageDoc - The raw page JSON document
+ * @param {JxDocument} pageDoc - The raw page document
  * @param {Record<string, unknown>} projectConfig - Site configuration (for defaults.layout)
  * @param {string} projectRoot - Project root directory
- * @returns {JxDocument} The merged document (layout wrapping page content)
+ * @returns {Promise<JxDocument>} The merged document (layout wrapping page content)
  */
 export function resolveLayout(
   pageDoc: JxDocument,
   projectConfig: Record<string, unknown>,
   projectRoot: string,
-) {
-  // Determine which layout to use
-  const layoutRef =
-    pageDoc.$layout ?? (projectConfig.defaults as Record<string, unknown>)?.layout ?? null;
-
-  if (!layoutRef) {
-    // No layout — return page as-is
-    return pageDoc;
-  }
-
-  // Load the layout file
-  const layoutPath = resolve(projectRoot, layoutRef as string);
-  if (!existsSync(layoutPath)) {
-    throw new Error(`Layout not found: ${layoutRef} (resolved to ${layoutPath})`);
-  }
-
-  /** @type {JxDocument} */
-  let layoutDoc;
-  try {
-    layoutDoc = parseJxDocument(readFileSync(layoutPath, "utf8"), layoutPath);
-  } catch (error) {
-    const err = error as Error;
-    throw new Error(`Invalid layout JSON at ${layoutPath}: ${err.message}`, { cause: error });
-  }
-
-  // Check for nested layouts (layout inheriting from another layout)
-  if (layoutDoc.$layout) {
-    layoutDoc = resolveLayout(layoutDoc, projectConfig, projectRoot);
-  }
-
-  // Distribute page children into layout slots
-  const rawChildren = pageDoc.children ?? [];
-  const pageChildren =
-    typeof rawChildren === "string"
-      ? [rawChildren]
-      : Array.isArray(rawChildren)
-        ? rawChildren
-        : ([] as (JxElement | string)[]);
-  const merged = deepClone(layoutDoc);
-
-  distributeSlots(merged, pageChildren);
-
-  // Merge page-level properties onto the resolved document
-  // Page state extends layout state
-  if (pageDoc.state) {
-    merged.state = { ...merged.state, ...pageDoc.state };
-  }
-
-  // Page $media extends layout $media
-  if (pageDoc.$media) {
-    merged.$media = { ...merged.$media, ...pageDoc.$media };
-  }
-
-  // Page style extends layout style
-  if (pageDoc.style) {
-    merged.style = { ...merged.style, ...pageDoc.style };
-  }
-
-  // Page attributes extend layout attributes
-  if (pageDoc.attributes) {
-    merged.attributes = { ...merged.attributes, ...pageDoc.attributes };
-  }
-
-  // Preserve page-level metadata
-  if (pageDoc.$head) {
-    merged._pageHead = pageDoc.$head;
-  }
-  if (pageDoc.title) {
-    merged._pageTitle = pageDoc.title;
-  }
-
-  // Remove $layout from merged doc (already resolved)
-  delete merged.$layout;
-
-  return merged;
-}
-
-/**
- * Distribute children into <slot> elements within a layout document tree. This is the compile-time
- * equivalent of the runtime's distributeSlots().
- *
- * Algorithm:
- *
- * 1. Find all <slot> elements in the layout tree
- * 2. For each child with attributes.slot, distribute to the matching named slot
- * 3. Remaining children go into the default (unnamed) slot
- * 4. Replace each <slot> element with its distributed children
- *
- * @param {JxElement} node - Layout document tree (mutated in place)
- * @param {(JxElement | string)[]} children - Page children to distribute
- */
-function distributeSlots(node: JxElement, children: (JxElement | string)[]) {
-  if (!node || typeof node !== "object") {
-    return;
-  }
-  if (!Array.isArray(node.children)) {
-    return;
-  }
-
-  // Collect named and default children
-  const named = new Map<string, (JxElement | string)[]>(); // Slot name → children[]
-  const defaults: (JxElement | string)[] = []; // Children without a slot target
-
-  for (const child of children) {
-    if (child && typeof child === "object" && child.attributes?.slot) {
-      const slotName = child.attributes.slot as string;
-      if (!named.has(slotName)) {
-        named.set(slotName, []);
-      }
-      (named.get(slotName) as (JxElement | string)[]).push(child);
-    } else {
-      defaults.push(child);
-    }
-  }
-
-  // Walk the tree and replace <slot> elements
-  fillSlots(node, named, defaults);
-}
-
-/**
- * Recursively walk the tree and replace <slot> elements with distributed content.
- *
- * @param {JxElement} node
- * @param {Map<string, (JxElement | string)[]>} named
- * @param {(JxElement | string)[]} defaults
- */
-function fillSlots(
-  node: JxElement,
-  named: Map<string, (JxElement | string)[]>,
-  defaults: (JxElement | string)[],
-) {
-  if (!node || typeof node !== "object") {
-    return;
-  }
-  if (!Array.isArray(node.children)) {
-    return;
-  }
-
-  const newChildren: (JxElement | string)[] = [];
-
-  for (const child of node.children) {
-    if (child && typeof child === "object" && child.tagName === "slot") {
-      const slotName = child.attributes?.name;
-
-      if (slotName && named.has(slotName as string)) {
-        // Named slot — replace with matching children
-        newChildren.push(...(named.get(slotName as string) as (JxElement | string)[]));
-        named.delete(slotName as string); // Consumed
-      } else if (!slotName && defaults.length > 0) {
-        // Default slot — replace with unassigned children
-        newChildren.push(...defaults);
-        // Don't clear defaults — only one default slot should exist,
-        // But if there are multiple, the first one wins
-      } else {
-        // No matching content — keep slot's fallback children
-        if (Array.isArray(child.children)) {
-          newChildren.push(...child.children);
-        }
-      }
-    } else {
-      // Not a slot — recurse into it
-      fillSlots(child as JxElement, named, defaults);
-      newChildren.push(child);
-    }
-  }
-
-  node.children = newChildren;
-}
-
-/**
- * Deep clone a JSON-serializable object.
- *
- * @param {JxDocument} obj
- * @returns {JxDocument}
- */
-function deepClone(obj: JxDocument) {
-  return structuredClone(obj);
+): Promise<JxDocument> {
+  return resolveLayoutWith(pageDoc, projectConfig, nodeLayoutLoader(projectRoot));
 }

package/src/site/pages-discovery.ts

@@ -9,10 +9,16 @@
  * pages/about/index.json → /about pages/blog/[slug].json → /blog/:slug (dynamic)
  * pages/docs/[...path].json → /docs/* (catch-all) pages/_component.json → NOT routed (underscore
  * prefix)
+ *
+ * The conventions themselves live in `@jxsuite/site/routes`, not here. The studio and the cloud
+ * preview both have to answer "what URL is this file" and neither can import this package — its
+ * dependency graph carries `sharp` and `esbuild` — so what remains in this file is the part that
+ * genuinely needs a filesystem: the walk, the `$layout` peek, and `$paths` expansion.
  */
 
 import { readFileSync, readdirSync } from "node:fs";
 import { parseJxDocument } from "@jxsuite/schema/parse";
+import { compareRoutes, fileToRoute as routeShape } from "@jxsuite/site/routes";
 import { extname, join, relative, resolve } from "node:path";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 import type { FormatRegistry } from "@jxsuite/schema/format-registry";
@@ -176,16 +182,8 @@ export async function discoverPages(pagesDir: string, registry?: FormatRegistry)
   const pageExtensions = new Set([".json", ...(registry?.documentExtensions("page") ?? [])]);
   await walkDir(pagesDir, pagesDir, routes, pageExtensions, registry);
 
-  // Sort: static routes first, then by specificity (more segments = more specific)
-  routes.sort((a, b) => {
-    if (a.isDynamic !== b.isDynamic) {
-      return a.isDynamic ? 1 : -1;
-    }
-    if (a.isCatchAll !== b.isCatchAll) {
-      return a.isCatchAll ? 1 : -1;
-    }
-    return a.urlPattern.localeCompare(b.urlPattern);
-  });
+  // Static routes first, then dynamic, then catch-all (spec §4.4) — the shared ordering.
+  routes.sort(compareRoutes);
 
   return routes;
 }
@@ -248,45 +246,7 @@ async function walkDir(
  * @returns {Promise<Route>}
  */
 async function fileToRoute(relativePath: string, absolutePath: string, registry?: FormatRegistry) {
-  // Remove the source extension
-  const ext = extname(relativePath);
-  let urlPath = ext ? relativePath.slice(0, -ext.length) : relativePath;
-
-  // Normalize path separators
-  urlPath = urlPath.split("\\").join("/");
-
-  // Index files map to their parent directory
-  if (urlPath.endsWith("/index")) {
-    urlPath = urlPath.slice(0, -6) || "/";
-  } else if (urlPath === "index") {
-    urlPath = "/";
-  }
-
-  // Ensure leading slash
-  if (!urlPath.startsWith("/")) {
-    urlPath = `/${urlPath}`;
-  }
-
-  // Extract parameters from bracket syntax
-  const params: string[] = [];
-  let isDynamic = false;
-  let isCatchAll = false;
-
-  // Convert [param] → :param and [...param] → *
-  const urlPattern = urlPath.replaceAll(
-    /\[\.\.\.(\w+)\]|\[(\w+)\]/g,
-    (_match: string, spread: string, named: string) => {
-      if (spread) {
-        isCatchAll = true;
-        isDynamic = true;
-        params.push(spread);
-        return "*";
-      }
-      isDynamic = true;
-      params.push(named);
-      return `:${named}`;
-    },
-  );
+  const { isCatchAll, isDynamic, params, urlPattern } = routeShape(relativePath);
 
   // Peek at the page to extract $layout if present
   let $layout: string | null = null;