@jxsuite/compiler 2.0.8 → 3.1.0

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;

package/src/site/service-worker.ts

@@ -20,6 +20,7 @@
  * @docs framework/site/deployment
  */
 
+import { withBase } from "@jxsuite/schema/asset-paths";
 import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
@@ -100,6 +101,7 @@ function configId(config: ServiceWorkerConfig): string {
 export function buildServiceWorker(
   config: ServiceWorkerConfig,
   outDir?: string,
+  base = "",
 ): ServiceWorkerOutput {
   const warnings: string[] = [];
   const errors: string[] = [];
@@ -140,15 +142,26 @@ export function buildServiceWorker(
     }
   }
 
+  /*
+   * The worker runs in the browser and every URL in it is a REQUEST path, so on a site served from
+   * `/m/my-site/` the base belongs on all three: a precache entry without it fetches a 404, and
+   * `CACHE_FIRST` without it never matches, so the content-addressed images it exists to serve
+   * from cache go to the network on every view. `outputFileFor` above is deliberately checked
+   * BEFORE this — those URLs are looked up in `outDir`, which has no base.
+   */
+  const cachedPrecache = precache.map((url) => withBase(base, url));
+  const cacheFirst = withBase(base, CACHE_FIRST_PREFIX);
+  const offlineFallback = fallback === undefined ? null : withBase(base, fallback);
+
   const cache = `jx-${configId(config)}`;
   const source = `/*
  * Generated by @jxsuite/compiler — configure via \`serviceWorker\` in project.json.
  * Set \`"serviceWorker": false\` to replace this with a worker that removes itself.
  */
 const CACHE = ${JSON.stringify(cache)};
-const PRECACHE = ${JSON.stringify(precache)};
-const CACHE_FIRST = ${JSON.stringify(CACHE_FIRST_PREFIX)};
-const OFFLINE_FALLBACK = ${JSON.stringify(fallback ?? null)};
+const PRECACHE = ${JSON.stringify(cachedPrecache)};
+const CACHE_FIRST = ${JSON.stringify(cacheFirst)};
+const OFFLINE_FALLBACK = ${JSON.stringify(offlineFallback)};
 
 self.addEventListener("install", (event) => {
   // Take over as soon as possible: a half-updated pair of workers is harder to reason about than
@@ -285,10 +298,14 @@ self.addEventListener("activate", (event) => {
  * @param {string} scope
  * @returns {string}
  */
-export function registrationScript(scope: string): string {
+export function registrationScript(scope: string, base = ""): string {
+  /* Both are request paths. A worker's scope may not exceed its own directory, so a worker served
+     from `/m/my-site/sw.js` with a scope of `/` fails to register outright — the one failure here
+     that is loud rather than silent. */
+  const worker = withBase(base, `/${SERVICE_WORKER_PATH}`);
   return (
     `if('serviceWorker' in navigator){addEventListener('load',function(){` +
-    `navigator.serviceWorker.register('/${SERVICE_WORKER_PATH}',{scope:${JSON.stringify(scope)}})` +
+    `navigator.serviceWorker.register('${worker}',{scope:${JSON.stringify(withBase(base, scope))}})` +
     `.catch(function(){})})}`
   );
 }