@jxsuite/site 0.1.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@jxsuite/site",
+  "version": "0.1.0",
+  "description": "What a Jx project's page at a route consists of — routing, layout, context, head and the document that boots it",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jxsuite/jx.git",
+    "directory": "packages/site"
+  },
+  "files": [
+    "src/"
+  ],
+  "type": "module",
+  "exports": {
+    "./routes": "./src/routes.ts",
+    "./layout": "./src/layout.ts",
+    "./context": "./src/context.ts",
+    "./head-merger": "./src/head-merger.ts",
+    "./site-style": "./src/site-style.ts"
+  },
+  "publishConfig": {
+    "provenance": false
+  },
+  "scripts": {
+    "test": "bun test --isolate",
+    "test:coverage": "bun test --isolate --coverage"
+  },
+  "dependencies": {
+    "@jxsuite/runtime": "workspace:^",
+    "@jxsuite/schema": "workspace:^"
+  }
+}

package/src/context.ts

@@ -0,0 +1,174 @@
+/**
+ * $page and $site context injection
+ *
+ * Injects project-level and page-level context variables into a page's state before compilation.
+ * These are available as $site.* and $page.* in template expressions.
+ *
+ * Per site-architecture spec §10: $site.name — from project.json name $site.url — from project.json
+ * url $site.state.* — site-wide reactive state $page.url — current page URL path $page.title — page
+ * title $page.params — dynamic route parameters (if any) $page.locale/$page.dir — the route's
+ * language and writing direction (§13.4) $page.alternates — this page in every language it exists
+ * in (§13.5)
+ *
+ * The site build is not the only thing that has to produce this state. A page rendered live — on
+ * the studio's canvas, or by the cloud's preview origin — binds `${$site.name}` and `${$page.url}`
+ * exactly as a built page does, and a host that improvised its own subset would differ from the
+ * build in whichever field it forgot. So the injection lives here, with no platform imports; the
+ * one thing that genuinely needed a filesystem, rebasing relative `imports` onto the page's own
+ * directory, is injected as {@link ImportRebaser} and simply absent where there are no
+ * directories.
+ *
+ * @docs framework/site/i18n
+ */
+
+import type { JxDocument, JxElement, JxStateDefinition, ProjectConfig } from "@jxsuite/schema/types";
+import { localeDirection, localeLabel, localeOfRoute } from "@jxsuite/schema/locale";
+import type { ResolvedI18n } from "@jxsuite/schema/locale";
+
+/** One member of a route's translation set — the shape `<head>` and `$page.alternates` share. */
+export interface TranslationMember {
+  locale: string;
+  urlPattern: string;
+}
+
+/** The route a page is being injected for. */
+export interface SiteRoute {
+  urlPattern: string;
+  sourcePath?: string;
+  _pathParams?: Record<string, string>;
+  [key: string]: unknown;
+}
+
+/**
+ * Rewrite one project-level relative `imports` entry so it resolves from the PAGE's directory.
+ *
+ * Only a host with real directories can answer this — and only one needs to. A live renderer serves
+ * the project at a root where the authored path already means what it says, so it passes nothing
+ * and the entry is used as written.
+ */
+export type ImportRebaser = (src: string, route: SiteRoute) => string;
+
+/**
+ * Inject $site and $page context into a page document's state.
+ *
+ * @param {JxDocument} doc - The page document (mutated)
+ * @param {ProjectConfig} projectConfig - Loaded project configuration
+ * @param {SiteRoute} route - The resolved route for this page
+ * @param {ImportRebaser | null} [rebaseImport] - Rebases relative `imports` onto the page directory
+ * @param {ResolvedI18n | null} [i18n] - Validated locale config, when the project declares one
+ * @param {readonly TranslationMember[]} [translations] - This route's translation set, itself
+ *   included
+ * @returns {JxDocument} The mutated document
+ */
+export function injectContext(
+  doc: JxDocument,
+  projectConfig: ProjectConfig,
+  route: SiteRoute,
+  rebaseImport: ImportRebaser | null = null,
+  i18n: ResolvedI18n | null = null,
+  translations: readonly TranslationMember[] = [],
+) {
+  if (!doc.state) {
+    doc.state = {};
+  }
+
+  // $site context — read-only project-level data
+  doc.state.$site = {
+    name: projectConfig.name ?? "Jx Site",
+    url: projectConfig.url ?? "",
+    ...(i18n === null ? {} : { defaultLocale: i18n.defaultLocale, locales: i18n.locales }),
+    ...projectConfig.state,
+  };
+
+  /*
+   * $page context — read-only page-level data.
+   *
+   * The locale lives here rather than as a top-level `$locale` because that is what it is: a
+   * property of the route, not a third ambient namespace beside $site and $page. A document's own
+   * `$lang` still wins over the route's locale, so this is the resolved answer, not the prefix.
+   */
+  const pageLang =
+    (typeof doc.$lang === "string" ? doc.$lang : undefined) ??
+    localeOfRoute(route.urlPattern, i18n) ??
+    projectConfig.defaults?.lang;
+  /*
+   * The same translation set `<head>` advertises, in the shape a template can render: a language
+   * switcher is the one part of a multilingual site the framework cannot write for the author, and
+   * without this it could only be hand-maintained — a hardcoded list of URLs that goes stale the
+   * moment a page gains or loses a translation, silently, in the one place a reader would use it.
+   *
+   * Site-absolute URLs, not the absolute hrefs `<head>` needs: a switcher is an internal link, and
+   * it has to work before `url` is configured. `current` marks the member this route *is*, taken
+   * from the route rather than from `$page.locale`, because a document whose `$lang` disagrees with
+   * its directory is still served from that directory.
+   */
+  const alternates = translations.map((member) => ({
+    code: member.locale,
+    current: member.urlPattern === route.urlPattern,
+    dir: localeDirection(member.locale),
+    label: localeLabel(member.locale),
+    url: member.urlPattern,
+  }));
+  doc.state.$page = {
+    params: route._pathParams ?? {},
+    title: doc.title ?? doc._pageTitle ?? projectConfig.name ?? "",
+    url: route.urlPattern,
+    ...(alternates.length > 0 && { alternates }),
+    ...(pageLang === undefined ? {} : { dir: localeDirection(pageLang), locale: pageLang }),
+  };
+
+  // Merge project-level state into page state (page wins on conflicts)
+  if (projectConfig.state) {
+    for (const [key, value] of Object.entries(projectConfig.state)) {
+      if (key !== "$site" && key !== "$page" && !(key in doc.state)) {
+        doc.state[key] = value as JxStateDefinition;
+      }
+    }
+  }
+
+  // Merge project-level $media into page $media
+  if (projectConfig.$media) {
+    doc.$media = { ...projectConfig.$media, ...doc.$media };
+  }
+
+  // Merge project-level imports into page imports (page wins on collision)
+  if (projectConfig.imports && Object.keys(projectConfig.imports).length > 0) {
+    if (!doc.imports) {
+      doc.imports = {};
+    }
+    for (const [name, srcPath] of Object.entries(projectConfig.imports)) {
+      if (!(name in doc.imports)) {
+        const src = srcPath as string;
+        // Only rebase relative paths — bare/npm specifiers pass through unmodified
+        doc.imports[name] =
+          rebaseImport && (src.startsWith("./") || src.startsWith("../"))
+            ? rebaseImport(src, route)
+            : src;
+      }
+    }
+  }
+
+  // Merge project-level $elements into page $elements (union, dedup)
+  if (projectConfig.$elements?.length) {
+    if (!doc.$elements?.length) {
+      doc.$elements = [...projectConfig.$elements];
+    } else {
+      const seen = new Set<string>();
+      const merged: (string | JxElement)[] = [];
+      for (const entry of [
+        ...projectConfig.$elements,
+        ...(doc.$elements as (string | JxElement)[]),
+      ]) {
+        const key =
+          typeof entry === "string" ? entry : /** @type {{ $ref?: string }} */ entry?.$ref;
+        if (key && !seen.has(key)) {
+          seen.add(key);
+          merged.push(entry);
+        }
+      }
+      doc.$elements = merged;
+    }
+  }
+
+  return doc;
+}

package/src/head-merger.ts

@@ -0,0 +1,267 @@
+/**
+ * $head merge pipeline — the three levels a page's `<head>` is assembled from.
+ *
+ * Merges <head> element arrays from three levels:
+ *
+ * 1. Site.json.$head — global (e.g., favicon, global stylesheet)
+ * 2. Layout.$head — layout-level (e.g., shared nav scripts)
+ * 3. Page.$head — page-specific (e.g., per-page meta tags)
+ *
+ * Per site-architecture spec §8:
+ *
+ * - Later levels override earlier levels for the same element
+ * - Deduplication by tagName + key attribute (name, property, rel+href)
+ * - Charset and viewport are auto-injected if missing
+ *
+ * Pure tree and string work with no platform imports, and it lives here rather than in
+ * `@jxsuite/compiler` so that hosts which cannot import that package — a browser bundle, a
+ * Cloudflare Worker serving a live preview — assemble the same `<head>` the build does.
+ */
+
+import type { JxHeadEntry } from "@jxsuite/schema/types";
+
+/** What a page knows about itself while its `<head>` is being merged. */
+export interface HeadMergeContext {
+  title?: string;
+  siteName?: string;
+  lang?: string;
+  charset?: string;
+  url?: string;
+  siteUrl?: string;
+  pageUrl?: string;
+  /** `rel="alternate"` links for this page's translations (site-architecture.md §13.5). */
+  alternates?: readonly { hreflang: string; href: string }[];
+}
+
+/**
+ * Merge $head arrays from site, layout, and page levels.
+ *
+ * @param {JxHeadEntry[]} [siteHead] - Site.json $head entries
+ * @param {JxHeadEntry[]} [layoutHead] - Layout $head entries (may be empty)
+ * @param {JxHeadEntry[]} [pageHead] - Page $head entries (may be empty)
+ * @param {HeadMergeContext} [context] - { title, lang, charset, url, pageUrl }
+ * @returns {JxHeadEntry[]} Merged, deduplicated $head array
+ */
+export function mergeHead(
+  siteHead: JxHeadEntry[] = [],
+  layoutHead: JxHeadEntry[] = [],
+  pageHead: JxHeadEntry[] = [],
+  context: HeadMergeContext = {},
+) {
+  // Start with auto-injected defaults
+  const defaults: JxHeadEntry[] = [
+    { attributes: { charset: context.charset ?? "utf8" }, tagName: "meta" },
+    {
+      attributes: {
+        content: "width=device-width, initial-scale=1",
+        name: "viewport",
+      },
+      tagName: "meta",
+    },
+  ];
+
+  // Merge layers: site → layout → page (later wins)
+  const merged = new Map<string, JxHeadEntry>();
+
+  for (const entry of [...defaults, ...siteHead, ...layoutHead, ...pageHead]) {
+    const key = headEntryKey(entry);
+    merged.set(key, entry);
+  }
+
+  // Insert <title> if present
+  const title = context.title ?? context.siteName ?? "Jx Site";
+  merged.set("title", { children: [title], tagName: "title" });
+
+  // Add canonical URL if provided
+  if (context.pageUrl && context.siteUrl) {
+    const canonical = new URL(context.pageUrl, context.siteUrl).href;
+    /*
+     * An author-supplied canonical wins, like every other auto-injected entry (§8.4). This used a
+     * hand-written `link:canonical` key that `headEntryKey` never produces, so the author's entry
+     * and this one landed under different keys and the page got BOTH — which is the one thing a
+     * canonical link must not be.
+     */
+    const hasAuthored = [...merged.values()].some(
+      (e) =>
+        e && typeof e === "object" && e.tagName === "link" && e.attributes?.rel === "canonical",
+    );
+    if (!hasAuthored) {
+      const entry: JxHeadEntry = {
+        attributes: { href: canonical, rel: "canonical" },
+        tagName: "link",
+      };
+      merged.set(headEntryKey(entry), entry);
+    }
+    // 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",
+    });
+  }
+
+  /*
+   * Locale alternates (site-architecture.md §13.5). Keyed through `headEntryKey` like everything
+   * else, which is what keeps a set of them from collapsing: they share `rel="alternate"` and
+   * differ only in `hreflang`, and `x-default` conventionally shares its `href` with the default
+   * locale's entry. Before the key accounted for the qualifying attribute this whole feature was
+   * impossible — the set became one link.
+   *
+   * An author-supplied alternate for the same `hreflang` wins, like every other auto entry.
+   */
+  for (const alternate of context.alternates ?? []) {
+    const entry: JxHeadEntry = {
+      attributes: { href: alternate.href, hreflang: alternate.hreflang, rel: "alternate" },
+      tagName: "link",
+    };
+    const key = headEntryKey(entry);
+    if (!merged.has(key)) {
+      merged.set(key, entry);
+    }
+  }
+
+  return [...merged.values()];
+}
+
+/**
+ * Generate a deduplication key for a <head> element. Elements with the same key are considered
+ * duplicates; the last one wins.
+ *
+ * @param {JxHeadEntry} entry
+ * @returns {string}
+ */
+function headEntryKey(entry: JxHeadEntry) {
+  if (!entry || typeof entry !== "object") {
+    return String(entry);
+  }
+
+  const tag = entry.tagName ?? "unknown";
+  const attrs = entry.attributes ?? {};
+
+  // <title> — singleton
+  if (tag === "title") {
+    return "title";
+  }
+
+  // <meta charset> — singleton
+  if (attrs.charset) {
+    return "meta:charset";
+  }
+
+  // <meta name="...""> — keyed by name
+  if (tag === "meta" && attrs.name) {
+    return `meta:${attrs.name}`;
+  }
+
+  // <meta property="..."> — keyed by property (Open Graph)
+  if (tag === "meta" && attrs.property) {
+    return `meta:${attrs.property}`;
+  }
+
+  /*
+   * <link> — keyed by rel + href + the attribute that distinguishes two links sharing both.
+   *
+   * `rel` + `href` alone is not identity, and the cases where it fails are the ones a site actually
+   * needs: `hreflang="x-default"` conventionally points at the SAME href as the default locale's
+   * alternate, and an RSS and an Atom feed are both `rel="alternate"` differing only in `type`.
+   * `icon` differs by `sizes` and `stylesheet` by `media` for the same reason.
+   */
+  if (tag === "link" && attrs.rel) {
+    const qualifier = attrs.hreflang ?? attrs.type ?? attrs.media ?? attrs.sizes ?? "";
+    return `link:${attrs.rel}:${attrs.href ?? ""}:${String(qualifier)}`;
+  }
+
+  // <script src="..."> — keyed by src
+  if (tag === "script" && attrs.src) {
+    return `script:${attrs.src}`;
+  }
+
+  // <style> — unique per content hash
+  if (tag === "style") {
+    const raw = Array.isArray(entry.children) ? entry.children.join("") : entry.textContent;
+    const content = typeof raw === "object" && raw !== null ? JSON.stringify(raw) : (raw ?? "");
+    return `style:${simpleHash(content)}`;
+  }
+
+  // Fallback — use full JSON serialization
+  return `${tag}:${JSON.stringify(entry)}`;
+}
+
+/**
+ * Simple string hash for deduplication (not cryptographic).
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+function simpleHash(str: string) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    // oxlint-disable-next-line no-bitwise -- classic 31x string hash; the shift is the algorithm
+    hash = Math.trunc((hash << 5) - hash + (str.codePointAt(i) ?? 0));
+  }
+  return hash.toString(36);
+}
+
+/**
+ * Render a merged $head array to HTML string for insertion into <head>.
+ *
+ * @param {JxHeadEntry[]} headEntries - Merged head entries
+ * @returns {string} HTML string
+ */
+export function renderHead(headEntries: JxHeadEntry[]) {
+  return headEntries.map((e: JxHeadEntry) => renderHeadEntry(e)).join("\n  ");
+}
+
+/**
+ * Render a single $head entry to an HTML string.
+ *
+ * @param {JxHeadEntry} entry
+ * @returns {string}
+ */
+function renderHeadEntry(entry: JxHeadEntry) {
+  if (typeof entry === "string") {
+    return entry;
+  }
+  if (!entry || typeof entry !== "object") {
+    return "";
+  }
+
+  const tag = entry.tagName;
+  const attrs = entry.attributes ?? {};
+  const attrStr = Object.entries(attrs)
+    .map(([k, v]) => (v === true ? k : `${k}="${escapeAttr(v)}"`))
+    .join(" ");
+
+  const open = attrStr ? `<${tag} ${attrStr}>` : `<${tag}>`;
+
+  // Void elements (no closing tag)
+  const VOID = new Set(["meta", "link", "base", "br", "hr", "img", "input"]);
+  if (VOID.has(tag)) {
+    return open;
+  }
+
+  /*
+   * Elements with content. `textContent` may be an OBJECT: that is how a JSON-LD block is authored
+   * (§8.5), and serializing it here is what the spec has always promised. Left as-is it reached the
+   * page as the string "[object Object]".
+   */
+  const raw = Array.isArray(entry.children) ? entry.children.join("") : entry.textContent;
+  const content =
+    raw !== null && typeof raw === "object" ? JSON.stringify(raw, null, 2) : (raw ?? "");
+  return `${open}${content}</${tag}>`;
+}
+
+/**
+ * @param {unknown} val
+ * @returns {string}
+ */
+function escapeAttr(val: unknown) {
+  return String(val).replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;");
+}

package/src/layout.ts

@@ -0,0 +1,207 @@
+/**
+ * Layout resolution — $layout loading and slot distribution.
+ *
+ * Resolves $layout references, loads layout documents, 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
+ *
+ * Reading is injected rather than imported. The rule "a page wrapped in its layout looks like THIS"
+ * is the same rule whether the layout comes off a disk, out of a Durable Object's SQLite table, or
+ * over `fetch` — and the two hosts that are not the compiler cannot import `node:fs` at all. So the
+ * only thing this module asks for is a {@link LayoutLoader}, and everything else is pure.
+ */
+
+import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+
+/**
+ * Read one layout document by the `$layout` reference that named it.
+ *
+ * The reference is project-relative as authored (`./layouts/base.json`); resolving it against
+ * wherever the project actually lives is the host's job, because only the host knows.
+ */
+export type LayoutLoader = (layoutRef: string) => Promise<JxDocument> | JxDocument;
+
+/**
+ * Resolve a page's layout, wrapping the page content in the layout structure.
+ *
+ * @param {JxDocument} pageDoc - The raw page JSON document
+ * @param {Record<string, unknown>} projectConfig - Site configuration (for defaults.layout)
+ * @param {LayoutLoader} load - Reads a layout document by its `$layout` reference
+ * @returns {Promise<JxDocument>} The merged document (layout wrapping page content)
+ */
+export async function resolveLayout(
+  pageDoc: JxDocument,
+  projectConfig: Record<string, unknown>,
+  load: LayoutLoader,
+): Promise<JxDocument> {
+  // 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;
+  }
+
+  let layoutDoc = await load(layoutRef as string);
+
+  // Check for nested layouts (layout inheriting from another layout)
+  if (layoutDoc.$layout) {
+    layoutDoc = await resolveLayout(layoutDoc, projectConfig, load);
+  }
+
+  // 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);
+}

package/src/routes.ts

@@ -0,0 +1,244 @@
+/**
+ * File-based routing — the one definition of what URL a page file has.
+ *
+ * The rules in this file (spec `site-architecture.md` §4) had been written down three times: the
+ * compiler's `fileToRoute` inside `pages-discovery.ts`, a mirror in the studio's `page-params.ts`
+ * whose own docblock admitted it was a mirror, and — the moment a Worker needed to answer the same
+ * question — very nearly a third. Nothing kept the copies in agreement, and a route is exactly the
+ * kind of rule where a silent disagreement is a page that 404s in one surface and renders in
+ * another.
+ *
+ * It lives HERE rather than in `@jxsuite/compiler` for the reason `resolveI18n` does (`i18n.ts`):
+ * the compiler's dependency graph carries `sharp` and `esbuild`, so neither a browser bundle nor a
+ * Cloudflare Worker can import it. This module is pure string math with no imports at all, so every
+ * host that has to know what `/blog/:slug` means can share one answer.
+ */
+
+/** Bracket route segments: `[param]` (named) and `[...param]` (catch-all). */
+const PARAM_SEGMENT = /\[\.\.\.(\w+)\]|\[(\w+)\]/g;
+
+/** What a page file's path says about its route, before anything is read from the file. */
+export interface RouteShape {
+  /** URL pattern with parameters, e.g. `/blog/:slug` or `/docs/*`. */
+  urlPattern: string;
+  /** Parameter names in declaration order, e.g. `["slug"]`. */
+  params: string[];
+  /** True when the pattern carries any parameter. */
+  isDynamic: boolean;
+  /** True when the pattern ends in a `[...rest]` spread. */
+  isCatchAll: boolean;
+}
+
+/**
+ * A page path with any addressing prefix removed, ready for {@link fileToRoute}.
+ *
+ * Callers hold these paths in two spaces — the compiler walks `pages/` and holds paths relative to
+ * it, while the studio holds a document path relative to the PROJECT (`pages/blog/[slug].json`).
+ * Normalising here means neither has to remember which space it is in.
+ */
+export function pageRelativePath(documentPath: string): string {
+  return documentPath
+    .split("\\")
+    .join("/")
+    .replace(/^\.\//, "")
+    .replace(/^\//, "")
+    .replace(/^pages\//, "");
+}
+
+/**
+ * The route a page file's path describes.
+ *
+ * `blog/[slug].json` → `/blog/:slug`, `docs/[...rest].json` → `/docs/*`, `index.json` → `/`,
+ * `about/index.md` → `/about`. The extension is dropped whatever it is: a page may be any format an
+ * enabled extension claims, and its route is a property of the NAME, not of the parser.
+ */
+export function fileToRoute(relativePath: string): RouteShape {
+  let urlPath = pageRelativePath(relativePath);
+
+  /* Drop the extension, but only a real one. `.` is legal inside a route segment, and slicing at
+     the last dot regardless would turn `pages/v1.2/index.json` into `/v1`. */
+  const lastSegment = urlPath.slice(urlPath.lastIndexOf("/") + 1);
+  const dot = lastSegment.lastIndexOf(".");
+  if (dot > 0) {
+    urlPath = urlPath.slice(0, urlPath.length - (lastSegment.length - dot));
+  }
+
+  // Index files map to their parent directory.
+  if (urlPath.endsWith("/index")) {
+    urlPath = urlPath.slice(0, -6) || "/";
+  } else if (urlPath === "index") {
+    urlPath = "/";
+  }
+
+  if (!urlPath.startsWith("/")) {
+    urlPath = `/${urlPath}`;
+  }
+
+  const params: string[] = [];
+  let isDynamic = false;
+  let isCatchAll = false;
+  const urlPattern = urlPath.replaceAll(
+    PARAM_SEGMENT,
+    (_match: string, spread: string | undefined, named: string | undefined) => {
+      isDynamic = true;
+      if (spread) {
+        isCatchAll = true;
+        params.push(spread);
+        return "*";
+      }
+      params.push(named!);
+      return `:${named}`;
+    },
+  );
+
+  return { isCatchAll, isDynamic, params, urlPattern };
+}
+
+/**
+ * URL pattern for a page document path — {@link fileToRoute} when only the pattern is wanted.
+ *
+ * A null or empty path answers `/` rather than throwing: the studio asks this of whatever document
+ * happens to be open, including none.
+ */
+export function documentUrlPattern(documentPath?: string | null): string {
+  if (!documentPath) {
+    return "/";
+  }
+  return fileToRoute(documentPath).urlPattern;
+}
+
+/** Param names declared by a document path's bracket segments, e.g. `["sku"]`. */
+export function dynamicRouteParams(documentPath?: string | null): string[] {
+  if (!documentPath) {
+    return [];
+  }
+  return fileToRoute(documentPath).params;
+}
+
+/**
+ * Whether a path under `pages/` becomes a route at all.
+ *
+ * An underscore prefix opts a file OUT — that is how a page directory holds a local component
+ * beside the pages that use it — and it opts out a whole directory the same way, so
+ * `_partials/card.json` is not a route even though `card.json` alone would be.
+ */
+export function isRoutedPageFile(relativePath: string): boolean {
+  const segments = pageRelativePath(relativePath).split("/");
+  return segments.length > 0 && segments.every((segment) => segment !== "" && segment[0] !== "_");
+}
+
+/**
+ * Route priority (spec §4.4, Astro's rules): static beats dynamic, dynamic beats catch-all.
+ *
+ * Sorting a route table with this is what makes `matchRoute` a first-match scan — `/about` is found
+ * before `/[slug]` can claim it, whatever order the directory walk produced.
+ */
+export function compareRoutes(a: RouteShape, b: RouteShape): number {
+  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);
+}
+
+/** One route matched against a URL, with the parameter values that matched it. */
+export interface RouteMatch<T extends RouteShape> {
+  route: T;
+  params: Record<string, string>;
+}
+
+/**
+ * The first route in `routes` that matches `pathname`, or null.
+ *
+ * `routes` is expected to be in {@link compareRoutes} order; the scan takes the first hit rather
+ * than the best one, because specificity is a property of the TABLE and re-deciding it per request
+ * is how two surfaces end up disagreeing about which page a URL is.
+ *
+ * A trailing slash is not significant — `build.trailingSlash` decides how a route is WRITTEN, and a
+ * reader who types the other form is asking for the same page.
+ */
+export function matchRoute<T extends RouteShape>(
+  routes: readonly T[],
+  pathname: string,
+): RouteMatch<T> | null {
+  const parts = splitPath(pathname);
+  for (const route of routes) {
+    const params = matchPattern(route.urlPattern, parts);
+    if (params) {
+      return { params, route };
+    }
+  }
+  return null;
+}
+
+/** Path segments, with the empty leading/trailing entries a slash produces removed. */
+function splitPath(pathname: string): string[] {
+  return pathname.split("/").filter((segment) => segment !== "");
+}
+
+/** Parameter values if `pattern` matches `parts`, else null. */
+function matchPattern(pattern: string, parts: string[]): Record<string, string> | null {
+  const patternParts = splitPath(pattern);
+  const params: Record<string, string> = {};
+
+  for (const [index, expected] of patternParts.entries()) {
+    if (expected === "*") {
+      /* A catch-all consumes the rest, including nothing at all: `/docs/*` serves `/docs`. Its
+         parameter is the remainder as one path, which is what the page's `$params` receives. */
+      params["*"] = parts.slice(index).join("/");
+      return params;
+    }
+    const actual = parts[index];
+    if (actual === undefined) {
+      return null;
+    }
+    if (expected.startsWith(":")) {
+      params[expected.slice(1)] = decodeURIComponent(actual);
+      continue;
+    }
+    if (expected !== actual) {
+      return null;
+    }
+  }
+
+  return patternParts.length === parts.length ? params : null;
+}
+
+/** How a site writes its URLs — `project.json`'s `build.trailingSlash`. */
+export type TrailingSlash = "always" | "never";
+
+/**
+ * The address a route's page will have when it is published.
+ *
+ * This is the URL the page's OWN markup already points at, which is why Open in Browser opens it
+ * rather than the compiler's output path: a built page links to `/blog/hello/` and pulls
+ * `/components/demo.css`, both root-absolute, and handed its output path instead a browser resolves
+ * those against the server root and every one of them misses.
+ */
+export function routeHref(
+  urlPattern: string,
+  params: Record<string, string> = {},
+  trailingSlash: TrailingSlash = "always",
+): string {
+  const filled = urlPattern
+    .replaceAll(/:(\w+)/g, (match, name: string) => {
+      const value = params[name];
+      return value === undefined ? match : encodeURIComponent(value);
+    })
+    .replace(/\*$/, (match) => {
+      const rest = params["*"];
+      return rest === undefined
+        ? match
+        : rest
+            .split("/")
+            .map((segment) => encodeURIComponent(segment))
+            .join("/");
+    });
+  if (filled === "/" || filled === "") {
+    return "/";
+  }
+  const bare = filled.endsWith("/") ? filled.slice(0, -1) : filled;
+  return trailingSlash === "always" ? `${bare}/` : bare;
+}

package/src/site-style.ts

@@ -0,0 +1,117 @@
+/// <reference lib="dom" />
+/**
+ * Site-style stylesheet builder — pure functions extracted for testability.
+ *
+ * The canvas iframe injects the project's `style` as a real stylesheet instead of inline properties
+ * on the root element: inline custom properties would defeat the forced-scheme override selectors
+ * (`:root[data-color-scheme]`, spec §9.5), and object-valued `@--name` blocks used to be dropped
+ * entirely. Scheme-query blocks dual-emit through the runtime's schemeSelectors so the canvas
+ * honors both the OS preference and the preview toggle.
+ */
+
+import { pureSchemeOf, resolveAtQuery, schemeSelectors, camelToKebab } from "@jxsuite/runtime";
+
+/** Id of the injected site-style tag (replace-in-place, never accumulate). */
+export const SITE_STYLE_ID = "jx-site-style";
+
+/** Serialize scalar declarations, kebab-casing property names and transposing values. */
+function toDecls(props: Record<string, unknown>, transpose: (value: string) => string): string {
+  return Object.entries(props)
+    .map(([key, value]) => `${camelToKebab(key)}: ${transpose(String(value))}`)
+    .join("; ");
+}
+
+/**
+ * Build the site-style sheet text: custom properties on `:root`, plain properties on `body`,
+ * conditional `@`-blocks resolved against `mediaQueries` (scheme queries dual-emitted per the
+ * forced-scheme contract), and `color-scheme: light dark` declared when a scheme query exists.
+ *
+ * @param {Record<string, unknown>} siteStyle
+ * @param {Record<string, string>} mediaQueries
+ * @param {(value: string) => string} transpose - Unit transposer (canvas vh→cqh etc.)
+ * @returns {string}
+ */
+export function buildSiteStyleCSS(
+  siteStyle: Record<string, unknown>,
+  mediaQueries: Record<string, string>,
+  transpose: (value: string) => string,
+): string {
+  const rules: string[] = [];
+  const rootProps: Record<string, unknown> = {};
+  const bodyProps: Record<string, unknown> = {};
+  const condBlocks: [string, Record<string, unknown>][] = [];
+
+  for (const [key, value] of Object.entries(siteStyle)) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+      if (key.startsWith("@")) {
+        condBlocks.push([key, value as Record<string, unknown>]);
+      }
+      // Non-@ objects (nested element selectors) are page-content styling — the resolved doc's
+      // Own style pass covers those; the site sheet handles tokens + conditional overrides.
+      continue;
+    }
+    if (key.startsWith(":") || key.startsWith(".") || key.startsWith("[") || key.startsWith("@")) {
+      continue;
+    }
+    if (key.startsWith("--")) {
+      rootProps[key] = value;
+    } else {
+      bodyProps[key] = value;
+    }
+  }
+
+  const rootCSS = toDecls(rootProps, transpose);
+  if (rootCSS) {
+    rules.push(`:root { ${rootCSS} }`);
+  }
+  const bodyCSS = toDecls(bodyProps, transpose);
+  if (bodyCSS) {
+    rules.push(`body { ${bodyCSS} }`);
+  }
+
+  for (const [atKey, block] of condBlocks) {
+    const query = resolveAtQuery(atKey, mediaQueries);
+    if (query === null) {
+      continue;
+    }
+    const scheme = pureSchemeOf(query);
+    const emit = (selector: string, props: string) => {
+      if (!props) {
+        return;
+      }
+      if (scheme) {
+        const { auto, forced } = schemeSelectors(selector, scheme);
+        rules.push(`@media ${query} { ${auto} { ${props} } }`, `${forced} { ${props} }`);
+      } else {
+        rules.push(`@media ${query} { ${selector} { ${props} } }`);
+      }
+    };
+    const condRoot: Record<string, unknown> = {};
+    const condBody: Record<string, unknown> = {};
+    const condSubs: [string, Record<string, unknown>][] = [];
+    for (const [k, v] of Object.entries(block)) {
+      if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+        if (!k.startsWith("@")) {
+          condSubs.push([k, v as Record<string, unknown>]);
+        }
+        continue;
+      }
+      if (k.startsWith("--")) {
+        condRoot[k] = v;
+      } else {
+        condBody[k] = v;
+      }
+    }
+    emit(":root", toDecls(condRoot, transpose));
+    emit("body", toDecls(condBody, transpose));
+    for (const [sel, sub] of condSubs) {
+      emit(sel, toDecls(sub, transpose));
+    }
+  }
+
+  if (Object.values(mediaQueries).some((q) => pureSchemeOf(q) !== null)) {
+    rules.push(":root { color-scheme: light dark }");
+  }
+
+  return rules.join("\n");
+}