@jxsuite/site 2.0.4 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/site",
-  "version": "2.0.4",
+  "version": "2.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": {
@@ -31,7 +31,7 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/runtime": "^4.1.0",
-    "@jxsuite/schema": "^3.0.0"
+    "@jxsuite/runtime": "^5.1.0",
+    "@jxsuite/schema": "^4.0.0"
   }
 }

package/src/compose.ts

@@ -23,10 +23,12 @@
  */
 
 import { compareRoutes, fileToRoute, isRoutedPageFile, matchRoute } from "./routes.ts";
-import type { RouteShape } from "./routes.ts";
+import type { FileRoute } from "./routes.ts";
 import { resolveLayout } from "./layout.ts";
-import { mergeHead } from "./head-merger.ts";
+import { mergeHead, withPageDescription } from "./head-merger.ts";
+import type { HeadMergeContext } from "./head-merger.ts";
 import { injectContext } from "./context.ts";
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { localeDirection, localeOfRoute, resolveI18n } from "@jxsuite/schema/locale";
 import { parseJxDocument } from "@jxsuite/schema/parse";
 import type { JxDocument, JxElement, JxHeadEntry, ProjectConfig } from "@jxsuite/schema/types";
@@ -64,7 +66,7 @@ export interface SiteIO {
 }
 
 /** A page file and the route it answers. */
-export interface PageRoute extends RouteShape {
+export interface PageRoute extends FileRoute {
   /** Project path of the page source, e.g. `pages/blog/[slug].json`. */
   sourcePath: string;
 }
@@ -72,8 +74,11 @@ export interface PageRoute extends RouteShape {
 /** The route table, in match order. Static beats dynamic beats catch-all. */
 export function routeTable(paths: readonly string[]): PageRoute[] {
   return paths
-    .filter((path) => path.startsWith("pages/") && isRoutedPageFile(path))
-    .map((path) => Object.assign(fileToRoute(path), { sourcePath: path }))
+    .flatMap((path) =>
+      path.startsWith("pages/") && isRoutedPageFile(path)
+        ? [Object.assign(fileToRoute(path), { sourcePath: path })]
+        : [],
+    )
     .toSorted(compareRoutes);
 }
 
@@ -93,14 +98,17 @@ async function readDocument(io: SiteIO, path: string): Promise<JxDocument | null
 export async function readProjectConfig(io: SiteIO): Promise<ProjectConfig> {
   const text = await io.read("project.json");
   if (text === null) {
-    return {} as ProjectConfig;
+    return {};
   }
   try {
+    /* SAFETY: only the syntax is checked here, deliberately: every ProjectConfig member is
+       optional, and shape checking is `validateProject`'s job against the per-project schema,
+       which `jx build` runs and a live preview of a half-edited config must not refuse over. */
     return JSON.parse(text) as ProjectConfig;
   } catch {
     /* A project whose config does not parse still has pages, and refusing to render any of them
        would hide the one error the author can act on behind a blank origin. */
-    return {} as ProjectConfig;
+    return {};
   }
 }
 
@@ -111,18 +119,18 @@ export async function readProjectConfig(io: SiteIO): Promise<ProjectConfig> {
  * name, so a page and its layout declaring the same component register it once.
  */
 export function unionElements(
-  ...lists: (readonly unknown[] | undefined)[]
+  ...lists: (readonly (string | JxElement)[] | undefined)[]
 ): (string | JxElement)[] | undefined {
   const seen = new Set<string>();
   const merged: (string | JxElement)[] = [];
   for (const entry of lists.flatMap((list) => list ?? [])) {
-    const key =
-      typeof entry === "string"
-        ? entry
-        : ((entry as { $ref?: string } | null)?.$ref ?? JSON.stringify(entry));
+    /* An authored list can hold a `null` its type does not admit; it is keyed by its own JSON
+       (`"null"`) like any other entry without a `$ref`, rather than throwing. */
+    const ref = isNonNullObject(entry) ? entry.$ref : undefined;
+    const key = isString(entry) ? entry : (ref ?? JSON.stringify(entry));
     if (!seen.has(key)) {
       seen.add(key);
-      merged.push(entry as string | JxElement);
+      merged.push(entry);
     }
   }
   return merged.length > 0 ? merged : undefined;
@@ -142,22 +150,26 @@ function refPath(ref: string): string {
   return new URL(ref, "file:///").pathname;
 }
 
-/** Every custom-element tag a document tree names, root included. */
-function collectTagNames(node: unknown, into: Set<string>): void {
-  if (!node || typeof node !== "object") {
+/**
+ * Every custom-element tag a document tree names, root included.
+ *
+ * Text children are skipped, and so is a `null` an authored children array can still hold.
+ */
+function collectTagNames(node: JxElement | string, into: Set<string>): void {
+  if (!isNonNullObject(node)) {
     return;
   }
-  if (Array.isArray(node)) {
-    for (const child of node) {
+  const { children, tagName } = node;
+  if (isString(tagName) && tagName.includes("-")) {
+    into.add(tagName);
+  }
+  /* A repeater filling the whole children slot names no tag of its own, and its row template
+     (`map`) is not walked, so only an array of children leads anywhere. */
+  if (Array.isArray(children)) {
+    for (const child of children) {
       collectTagNames(child, into);
     }
-    return;
-  }
-  const { children, tagName } = node as { children?: unknown; tagName?: unknown };
-  if (typeof tagName === "string" && tagName.includes("-")) {
-    into.add(tagName);
   }
-  collectTagNames(children, into);
 }
 
 /**
@@ -197,21 +209,21 @@ async function discoverElements(io: SiteIO, doc: JxDocument): Promise<{ $ref: st
      bring components of its own — it is just not declared a second time. */
   const declared = new Set<string>();
   for (const entry of doc.$elements ?? []) {
-    const ref = (entry as { $ref?: unknown } | null)?.$ref;
-    if (typeof ref === "string") {
+    const ref = isNonNullObject(entry) ? entry.$ref : undefined;
+    if (isString(ref)) {
       declared.add(refPath(ref));
     }
   }
 
   const discovered: { $ref: string }[] = [];
   const opened = new Set<string>();
-  let frontier: unknown[] = [doc];
+  let frontier: JxDocument[] = [doc];
   while (frontier.length > 0) {
     const tags = new Set<string>();
     for (const node of frontier) {
       collectTagNames(node, tags);
     }
-    const next: unknown[] = [];
+    const next: JxDocument[] = [];
     for (const tag of tags) {
       const path = available.get(tag);
       if (path === undefined || opened.has(tag)) {
@@ -286,7 +298,7 @@ export async function composePage(
     );
   }
 
-  const merged = await resolveLayout(pageDoc, config as Record<string, unknown>, async (ref) => {
+  const merged = await resolveLayout(pageDoc, config, async (ref) => {
     const doc = await readDocument(io, ref.replace(/^\.\//, ""));
     if (!doc) {
       throw new ComposeError(`Layout not found: ${ref}`);
@@ -323,21 +335,28 @@ export async function composePage(
     merged.$elements = withDiscovered;
   }
 
-  const pageHead = (pageDoc.$head ?? merged._pageHead ?? []) as JxHeadEntry[];
-  const layoutHead = (merged.$head ?? []) as JxHeadEntry[];
-  const siteHead = (config.$head ?? []) as JxHeadEntry[];
+  /* SAFETY: `_pageHead` is no authored key; `resolveLayout` is its only writer and stores a page's
+     (or a nested layout's) `$head` array in it, which is the `JxHeadEntry[]` asserted here. */
+  const pageHead = withPageDescription(
+    (pageDoc.$head ?? merged._pageHead ?? []) as JxHeadEntry[],
+    pageDoc.description,
+  );
+  const layoutHead = merged.$head ?? [];
+  const siteHead = config.$head ?? [];
+  /* SAFETY: `pageDoc.title` and `config.name` are declared strings, and `_pageTitle` is no authored
+     key: `resolveLayout` is its only writer and stores a page's (or a nested layout's) `title`. */
   const title = (pageDoc.title ?? merged._pageTitle ?? config.name ?? "") as string;
   const lang =
-    (typeof pageDoc.$lang === "string" ? pageDoc.$lang : undefined) ??
+    (isString(pageDoc.$lang) ? pageDoc.$lang : undefined) ??
     localeOfRoute(route.urlPattern, i18n) ??
     config.defaults?.lang ??
     "en";
 
-  const head = mergeHead(siteHead, layoutHead, pageHead, {
-    lang,
-    title,
-    ...(config.name === undefined ? {} : { siteName: config.name }),
-  });
+  const headContext: HeadMergeContext = { lang, title };
+  if (config.name !== undefined) {
+    headContext.siteName = config.name;
+  }
+  const head = mergeHead(siteHead, layoutHead, pageHead, headContext);
 
   /* `$head` is merged out of the document and rendered into the shell, so leaving it on the
      document would have the runtime inject every entry a second time on mount. */

package/src/context.ts

@@ -21,18 +21,19 @@
  * @docs framework/site/i18n
  */
 
-import type {
-  JxDocument,
-  JxElement,
-  JxStateDefinition,
-  ProjectConfig,
-} from "@jxsuite/schema/types";
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
+import type { JxDocument, JxElement, JxStateObject, 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. */
+/**
+ * One route in a translation set: the locale it serves, and where it lives. The shape `<head>` and
+ * `$page.alternates` share.
+ */
 export interface TranslationMember {
+  /** Canonical BCP 47 tag. */
   locale: string;
+  /** Site-absolute route pattern, e.g. `/fr-ca/about/`. */
   urlPattern: string;
 }
 
@@ -41,7 +42,6 @@ export interface SiteRoute {
   urlPattern: string;
   sourcePath?: string;
   _pathParams?: Record<string, string>;
-  [key: string]: unknown;
 }
 
 /**
@@ -78,10 +78,17 @@ export function injectContext(
   }
 
   // $site context — read-only project-level data
+  const localeFields: JxStateObject = {};
+  if (i18n !== null) {
+    localeFields.defaultLocale = i18n.defaultLocale;
+    localeFields.locales = i18n.locales;
+  }
+  /* Project state is spread last, so a key it shares with the fields above overrides it in place.
+     A spread, not `Object.assign`: an authored `__proto__` key stays an own data property. */
   doc.state.$site = {
     name: projectConfig.name ?? "Jx Site",
     url: projectConfig.url ?? "",
-    ...(i18n === null ? {} : { defaultLocale: i18n.defaultLocale, locales: i18n.locales }),
+    ...localeFields,
     ...projectConfig.state,
   };
 
@@ -93,7 +100,7 @@ export function injectContext(
    * `$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) ??
+    (isString(doc.$lang) ? doc.$lang : undefined) ??
     localeOfRoute(route.urlPattern, i18n) ??
     projectConfig.defaults?.lang;
   /*
@@ -114,19 +121,25 @@ export function injectContext(
     label: localeLabel(member.locale),
     url: member.urlPattern,
   }));
-  doc.state.$page = {
+  const page: JxStateObject = {
     params: route._pathParams ?? {},
     title: doc.title ?? doc._pageTitle ?? projectConfig.name ?? "",
     url: route.urlPattern,
-    ...(alternates.length > 0 && { alternates }),
-    ...(pageLang === undefined ? {} : { dir: localeDirection(pageLang), locale: pageLang }),
   };
+  if (alternates.length > 0) {
+    page.alternates = alternates;
+  }
+  if (pageLang !== undefined) {
+    page.dir = localeDirection(pageLang);
+    page.locale = pageLang;
+  }
+  doc.state.$page = page;
 
   // 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;
+        doc.state[key] = value;
       }
     }
   }
@@ -143,12 +156,11 @@ export function injectContext(
     }
     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;
+          rebaseImport && (srcPath.startsWith("./") || srcPath.startsWith("../"))
+            ? rebaseImport(srcPath, route)
+            : srcPath;
       }
     }
   }
@@ -160,12 +172,10 @@ export function injectContext(
     } 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;
+      for (const entry of [...projectConfig.$elements, ...doc.$elements]) {
+        /* `$elements` is authored JSON, so an entry typed as an element can still be `null`; the
+           object check keeps such an entry keyless (and dropped) instead of throwing. */
+        const key = isString(entry) ? entry : isNonNullObject(entry) ? entry.$ref : undefined;
         if (key && !seen.has(key)) {
           seen.add(key);
           merged.push(entry);

package/src/head-merger.ts

@@ -19,7 +19,16 @@
  */
 
 import { siteAbsoluteUrl } from "@jxsuite/schema/asset-paths";
-import type { JxHeadEntry } from "@jxsuite/schema/types";
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
+import type { JxDocumentValue, JxHeadEntry } from "@jxsuite/schema/types";
+
+/**
+ * A `$head` entry as authored JSON can actually hold it, which is wider than {@link JxHeadEntry}: a
+ * document may carry a raw HTML string, a hand-written element may leave out `tagName`, and a
+ * malformed entry may be `null`. The merge keys and the render tolerate all three, so one bad entry
+ * never takes the whole page down with it.
+ */
+export type AuthoredHeadEntry = Partial<JxHeadEntry> | string | null;
 
 /** What a page knows about itself while its `<head>` is being merged. */
 export interface HeadMergeContext {
@@ -34,6 +43,40 @@ export interface HeadMergeContext {
   alternates?: readonly { hreflang: string; href: string }[];
 }
 
+/**
+ * A page's `$head` with its own `description` property stated as the description meta.
+ *
+ * A page names its description the way it names its title: as a property of the document, which for
+ * a Markdown page is a frontmatter key (`description: …` beside `title: …`). It is the PAGE's
+ * description, so it beats the site's and the layout's, and it is written ahead of the page's own
+ * `$head` so an explicit `<meta name="description">` there still wins, like every entry stated
+ * twice at one level. A value that is not a non-empty string states nothing. The entry goes through
+ * the same template resolution as the rest of the page's head, so a dynamic page's
+ * `"${state.entry.data.summary}"` is filled per route.
+ *
+ * Before this, the build read no such property, so the museum starter's three pages and every
+ * migrated Markdown page carrying `description:` shipped no description at all (site-architecture
+ * §8.4), while Studio showed the value in a field of its own beside the head's empty one.
+ *
+ * @param {AuthoredHeadEntry[]} pageHead - The page's own `$head`
+ * @param {JxDocumentValue | undefined} description - The page document's `description` property, as
+ *   authored JSON holds it
+ * @returns {AuthoredHeadEntry[]} The head the page level merges
+ */
+export function withPageDescription<T extends AuthoredHeadEntry>(
+  pageHead: readonly T[],
+  description: JxDocumentValue | undefined,
+): (T | JxHeadEntry)[] {
+  if (!isString(description) || description.trim() === "") {
+    return [...pageHead];
+  }
+  const entry: JxHeadEntry = {
+    attributes: { content: description, name: "description" },
+    tagName: "meta",
+  };
+  return [entry, ...pageHead];
+}
+
 /**
  * Merge $head arrays from site, layout, and page levels.
  *
@@ -86,8 +129,8 @@ export function mergeHead(
      * canonical link must not be.
      */
     const hasAuthored = [...merged.values()].some(
-      (e) =>
-        e && typeof e === "object" && e.tagName === "link" && e.attributes?.rel === "canonical",
+      (e: AuthoredHeadEntry) =>
+        isNonNullObject(e) && e.tagName === "link" && e.attributes?.rel === "canonical",
     );
     if (!hasAuthored) {
       const entry: JxHeadEntry = {
@@ -138,11 +181,11 @@ export function mergeHead(
  * Generate a deduplication key for a <head> element. Elements with the same key are considered
  * duplicates; the last one wins.
  *
- * @param {JxHeadEntry} entry
+ * @param {AuthoredHeadEntry} entry
  * @returns {string}
  */
-function headEntryKey(entry: JxHeadEntry) {
-  if (!entry || typeof entry !== "object") {
+function headEntryKey(entry: AuthoredHeadEntry) {
+  if (!isNonNullObject(entry)) {
     return String(entry);
   }
 
@@ -190,7 +233,7 @@ function headEntryKey(entry: JxHeadEntry) {
   // <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 ?? "");
+    const content = isNonNullObject(raw) ? JSON.stringify(raw) : (raw ?? "");
     return `style:${simpleHash(content)}`;
   }
 
@@ -216,24 +259,24 @@ function simpleHash(str: string) {
 /**
  * Render a merged $head array to HTML string for insertion into <head>.
  *
- * @param {JxHeadEntry[]} headEntries - Merged head entries
+ * @param {readonly AuthoredHeadEntry[]} headEntries - Merged head entries
  * @returns {string} HTML string
  */
-export function renderHead(headEntries: JxHeadEntry[]) {
-  return headEntries.map((e: JxHeadEntry) => renderHeadEntry(e)).join("\n  ");
+export function renderHead(headEntries: readonly AuthoredHeadEntry[]) {
+  return headEntries.map((e) => renderHeadEntry(e)).join("\n  ");
 }
 
 /**
  * Render a single $head entry to an HTML string.
  *
- * @param {JxHeadEntry} entry
+ * @param {AuthoredHeadEntry} entry
  * @returns {string}
  */
-function renderHeadEntry(entry: JxHeadEntry) {
-  if (typeof entry === "string") {
+function renderHeadEntry(entry: AuthoredHeadEntry) {
+  if (isString(entry)) {
     return entry;
   }
-  if (!entry || typeof entry !== "object") {
+  if (!isNonNullObject(entry)) {
     return "";
   }
 
@@ -247,7 +290,7 @@ function renderHeadEntry(entry: JxHeadEntry) {
 
   // Void elements (no closing tag)
   const VOID = new Set(["meta", "link", "base", "br", "hr", "img", "input"]);
-  if (VOID.has(tag)) {
+  if (tag !== undefined && VOID.has(tag)) {
     return open;
   }
 
@@ -257,15 +300,14 @@ function renderHeadEntry(entry: JxHeadEntry) {
    * 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 ?? "");
+  const content = isNonNullObject(raw) ? JSON.stringify(raw, null, 2) : (raw ?? "");
   return `${open}${content}</${tag}>`;
 }
 
 /**
- * @param {unknown} val
+ * @param {string | boolean} val - An attribute value; `true` never reaches here (it renders bare)
  * @returns {string}
  */
-function escapeAttr(val: unknown) {
+function escapeAttr(val: string | boolean) {
   return String(val).replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;");
 }

package/src/layout.ts

@@ -18,7 +18,8 @@
  * only thing this module asks for is a {@link LayoutLoader}, and everything else is pure.
  */
 
-import type { JxDocument, JxElement } from "@jxsuite/schema/types";
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
+import type { JxAttributeValue, JxDocument, JxElement, ProjectConfig } from "@jxsuite/schema/types";
 
 /**
  * Read one layout document by the `$layout` reference that named it.
@@ -32,25 +33,24 @@ export type LayoutLoader = (layoutRef: string) => Promise<JxDocument> | JxDocume
  * 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 {ProjectConfig} 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>,
+  projectConfig: ProjectConfig,
   load: LayoutLoader,
 ): Promise<JxDocument> {
   // Determine which layout to use
-  const layoutRef =
-    pageDoc.$layout ?? (projectConfig.defaults as Record<string, unknown>)?.layout ?? null;
+  const layoutRef = pageDoc.$layout ?? projectConfig.defaults?.layout ?? null;
 
   if (!layoutRef) {
     // No layout — return page as-is
     return pageDoc;
   }
 
-  let layoutDoc = await load(layoutRef as string);
+  let layoutDoc = await load(layoutRef);
 
   // Check for nested layouts (layout inheriting from another layout)
   if (layoutDoc.$layout) {
@@ -59,12 +59,13 @@ export async function resolveLayout(
 
   // Distribute page children into layout slots
   const rawChildren = pageDoc.children ?? [];
-  const pageChildren =
-    typeof rawChildren === "string"
-      ? [rawChildren]
-      : Array.isArray(rawChildren)
-        ? rawChildren
-        : ([] as (JxElement | string)[]);
+  /* The declared type has no string form, but an authored page can still write `"children": "Hi"`
+     and the parser does not reject it, so the bare string is kept as the one child it means. */
+  const pageChildren: (JxElement | string)[] = isString(rawChildren)
+    ? [rawChildren]
+    : Array.isArray(rawChildren)
+      ? rawChildren
+      : [];
   const merged = deepClone(layoutDoc);
 
   distributeSlots(merged, pageChildren);
@@ -119,24 +120,20 @@ export async function resolveLayout(
  * @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[]
+  /* Collect named and default children. A layout with no children array has no slots, and
+     `fillSlots` returns before reading either collection, so collecting first changes nothing. */
+  const named = new Map<JxAttributeValue, (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, []);
+    const slotName = isNonNullObject(child) ? child.attributes?.slot : undefined;
+    if (slotName) {
+      let bucket = named.get(slotName);
+      if (!bucket) {
+        bucket = [];
+        named.set(slotName, bucket);
       }
-      (named.get(slotName) as (JxElement | string)[]).push(child);
+      bucket.push(child);
     } else {
       defaults.push(child);
     }
@@ -149,16 +146,16 @@ function distributeSlots(node: JxElement, children: (JxElement | string)[]) {
 /**
  * Recursively walk the tree and replace <slot> elements with distributed content.
  *
- * @param {JxElement} node
- * @param {Map<string, (JxElement | string)[]>} named
+ * @param {JxElement | string} node - A text child is passed through and ignored
+ * @param {Map<JxAttributeValue, (JxElement | string)[]>} named
  * @param {(JxElement | string)[]} defaults
  */
 function fillSlots(
-  node: JxElement,
-  named: Map<string, (JxElement | string)[]>,
+  node: JxElement | string,
+  named: Map<JxAttributeValue, (JxElement | string)[]>,
   defaults: (JxElement | string)[],
 ) {
-  if (!node || typeof node !== "object") {
+  if (!isNonNullObject(node)) {
     return;
   }
   if (!Array.isArray(node.children)) {
@@ -168,13 +165,14 @@ function fillSlots(
   const newChildren: (JxElement | string)[] = [];
 
   for (const child of node.children) {
-    if (child && typeof child === "object" && child.tagName === "slot") {
+    if (isNonNullObject(child) && child.tagName === "slot") {
       const slotName = child.attributes?.name;
+      const slotted = slotName ? named.get(slotName) : undefined;
 
-      if (slotName && named.has(slotName as string)) {
+      if (slotName && slotted) {
         // Named slot — replace with matching children
-        newChildren.push(...(named.get(slotName as string) as (JxElement | string)[]));
-        named.delete(slotName as string); // Consumed
+        newChildren.push(...slotted);
+        named.delete(slotName); // Consumed
       } else if (!slotName && defaults.length > 0) {
         // Default slot — replace with unassigned children
         newChildren.push(...defaults);
@@ -188,7 +186,7 @@ function fillSlots(
       }
     } else {
       // Not a slot — recurse into it
-      fillSlots(child as JxElement, named, defaults);
+      fillSlots(child, named, defaults);
       newChildren.push(child);
     }
   }

package/src/paths.ts

@@ -101,35 +101,43 @@ export function candidatePaths(requestPath: string): string[] {
   return candidates;
 }
 
-/** Content types a site origin serves by extension. Anything unlisted is served as a download. */
-const CONTENT_TYPES: Record<string, string> = {
-  avif: "image/avif",
-  css: "text/css; charset=utf-8",
-  csv: "text/csv; charset=utf-8",
-  gif: "image/gif",
-  htm: "text/html; charset=utf-8",
-  html: "text/html; charset=utf-8",
-  ico: "image/x-icon",
-  jpeg: "image/jpeg",
-  jpg: "image/jpeg",
-  js: "text/javascript; charset=utf-8",
-  json: "application/json; charset=utf-8",
-  map: "application/json; charset=utf-8",
-  md: "text/markdown; charset=utf-8",
-  mjs: "text/javascript; charset=utf-8",
-  mp4: "video/mp4",
-  otf: "font/otf",
-  pdf: "application/pdf",
-  png: "image/png",
-  svg: "image/svg+xml",
-  ttf: "font/ttf",
-  txt: "text/plain; charset=utf-8",
-  webm: "video/webm",
-  webp: "image/webp",
-  woff: "font/woff",
-  woff2: "font/woff2",
-  xml: "application/xml; charset=utf-8",
-};
+/**
+ * Content types a site origin serves by extension. Anything unlisted is served as a download.
+ *
+ * A `Map` rather than an object literal so a lookup only ever finds a listed extension: indexing a
+ * plain object by a path's extension also reaches `Object.prototype`, and `x.constructor` would
+ * come back as a function instead of falling through to the download type.
+ */
+const CONTENT_TYPES = new Map(
+  Object.entries({
+    avif: "image/avif",
+    css: "text/css; charset=utf-8",
+    csv: "text/csv; charset=utf-8",
+    gif: "image/gif",
+    htm: "text/html; charset=utf-8",
+    html: "text/html; charset=utf-8",
+    ico: "image/x-icon",
+    jpeg: "image/jpeg",
+    jpg: "image/jpeg",
+    js: "text/javascript; charset=utf-8",
+    json: "application/json; charset=utf-8",
+    map: "application/json; charset=utf-8",
+    md: "text/markdown; charset=utf-8",
+    mjs: "text/javascript; charset=utf-8",
+    mp4: "video/mp4",
+    otf: "font/otf",
+    pdf: "application/pdf",
+    png: "image/png",
+    svg: "image/svg+xml",
+    ttf: "font/ttf",
+    txt: "text/plain; charset=utf-8",
+    webm: "video/webm",
+    webp: "image/webp",
+    woff: "font/woff",
+    woff2: "font/woff2",
+    xml: "application/xml; charset=utf-8",
+  }),
+);
 
 /**
  * The Content-Type a site origin serves a path as.
@@ -142,5 +150,5 @@ const CONTENT_TYPES: Record<string, string> = {
 export function contentTypeFor(path: string): string {
   const dot = path.lastIndexOf(".");
   const extension = dot === -1 ? "" : path.slice(dot + 1).toLowerCase();
-  return CONTENT_TYPES[extension] ?? "application/octet-stream";
+  return CONTENT_TYPES.get(extension) ?? "application/octet-stream";
 }

package/src/routes.ts

@@ -18,7 +18,7 @@
 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 {
+export interface FileRoute {
   /** URL pattern with parameters, e.g. `/blog/:slug` or `/docs/*`. */
   urlPattern: string;
   /** Parameter names in declaration order, e.g. `["slug"]`. */
@@ -52,7 +52,7 @@ export function pageRelativePath(documentPath: string): string {
  * `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 {
+export function fileToRoute(relativePath: string): FileRoute {
   let urlPath = pageRelativePath(relativePath);
 
   /* Drop the extension, but only a real one. `.` is legal inside a route segment, and slicing at
@@ -121,10 +121,28 @@ export function dynamicRouteParams(documentPath?: string | null): string[] {
  * 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.
+ *
+ * The build routes only the files it can read as a page: `.json`, and each extension a page format
+ * claims (`discoverPages` in `@jxsuite/compiler`). A caller that knows the claimed extensions
+ * passes them, so `index.json.bak` or a stray `notes.txt` beside the pages is not listed as one. A
+ * caller that does not know them (no format registry) gets the name rule alone.
+ *
+ * @param relativePath A page path, `pages/…` or relative to `pages/`.
+ * @param pageExtensions The extensions the build routes, lower-case with their dot (`.json`,
+ *   `.md`). Omitted, the extension is not judged.
  */
-export function isRoutedPageFile(relativePath: string): boolean {
+export function isRoutedPageFile(relativePath: string, pageExtensions?: Iterable<string>): boolean {
   const segments = pageRelativePath(relativePath).split("/");
-  return segments.length > 0 && segments.every((segment) => segment !== "" && segment[0] !== "_");
+  if (!segments.every((segment) => segment !== "" && segment[0] !== "_")) {
+    return false;
+  }
+  if (pageExtensions === undefined) {
+    return true;
+  }
+  const name = segments.at(-1) ?? "";
+  const dot = name.lastIndexOf(".");
+  const ext = dot > 0 ? name.slice(dot).toLowerCase() : "";
+  return ext !== "" && new Set(pageExtensions).has(ext);
 }
 
 /**
@@ -133,7 +151,7 @@ export function isRoutedPageFile(relativePath: string): boolean {
  * 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 {
+export function compareRoutes(a: FileRoute, b: FileRoute): number {
   if (a.isDynamic !== b.isDynamic) {
     return a.isDynamic ? 1 : -1;
   }
@@ -144,7 +162,7 @@ export function compareRoutes(a: RouteShape, b: RouteShape): number {
 }
 
 /** One route matched against a URL, with the parameter values that matched it. */
-export interface RouteMatch<T extends RouteShape> {
+export interface RouteMatch<T extends FileRoute> {
   route: T;
   params: Record<string, string>;
 }
@@ -159,7 +177,7 @@ export interface RouteMatch<T extends RouteShape> {
  * 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>(
+export function matchRoute<T extends FileRoute>(
   routes: readonly T[],
   pathname: string,
 ): RouteMatch<T> | null {

package/src/serve.ts

@@ -22,8 +22,19 @@ import type { ProjectConfig } from "@jxsuite/schema/types";
 
 /** Reading bytes for a servable file — separate from {@link SiteIO} because assets are binary. */
 export interface AssetIO {
-  /** The file's bytes, or null when the tree cannot produce them. */
-  bytes: (path: string) => Promise<Uint8Array | null>;
+  /**
+   * The file's bytes, or null when the tree cannot produce them.
+   *
+   * ArrayBuffer-backed because they become a `Response` body as they are: a view over a
+   * `SharedArrayBuffer` is not a `BodyInit`.
+   */
+  bytes: (path: string) => Promise<Uint8Array<ArrayBuffer> | null>;
+}
+
+/** One working tree, seen through both of the readers a site origin is handed. */
+export interface SiteTree {
+  io: SiteIO;
+  assets: AssetIO;
 }
 
 /** What this origin knows about a project, computed once per request. */
@@ -40,7 +51,7 @@ export interface ServeOptions {
 }
 
 /** Headers every response from this origin carries, whatever it is serving. */
-export function siteHeaders(contentType: string): Record<string, string> {
+export function siteHeaders(contentType: string) {
   return {
     /* Never cached. A composed page is a function of a working tree that changes under it, and it
        is not revalidatable — there is no version of it to compare against. */
@@ -94,7 +105,7 @@ export async function serveSite(
   for (const candidate of candidatePaths(requestPath)) {
     const bytes = await assets.bytes(candidate);
     if (bytes) {
-      return new Response(bytes as BodyInit, {
+      return new Response(bytes, {
         headers: siteHeaders(contentTypeFor(candidate)),
       });
     }

package/src/shell.ts

@@ -27,6 +27,7 @@
 
 import { renderHead } from "./head-merger.ts";
 import type { ComposedPage } from "./compose.ts";
+import type { JxDocument } from "@jxsuite/schema/types";
 
 /** What a host must tell the shell about its own origin. */
 export interface ShellOptions {
@@ -63,8 +64,8 @@ function attr(value: string): string {
  * `<` is escaped as `\u003c`, which JSON.parse restores and an HTML parser cannot mistake for the
  * start of a tag — so no value inside the document, however it was authored, can close the block.
  */
-function jsonPayload(value: unknown): string {
-  return JSON.stringify(value).replaceAll("<", String.raw`\u003c`);
+function jsonPayload(doc: JxDocument): string {
+  return JSON.stringify(doc).replaceAll("<", String.raw`\u003c`);
 }
 
 /** The document for one composed page. */

package/src/site-style.ts

@@ -39,6 +39,8 @@ import {
   isNestedSelectorKey,
   pureSchemeOf,
 } from "@jxsuite/runtime/css";
+import type { CssBuildOptions } from "@jxsuite/runtime/css";
+import { isNonNullObject } from "@jxsuite/schema/guards";
 import type { JxRef, JxStyle } from "@jxsuite/schema/types";
 
 /** Id of the injected site-style tag (replace-in-place, never accumulate). */
@@ -60,6 +62,23 @@ export type SiteStyleValueResolver = (
   selector: string | null,
 ) => string | null;
 
+/**
+ * Where a site-style sheet puts what `project.json` addresses to the page itself: its custom
+ * properties and `color-scheme` on `root`, its plain properties on `body`.
+ *
+ * A host that IS the page (the canvas iframe, a preview tab, the build) uses the page's own
+ * {@link PAGE_ROOTS}. A host drawing a part of a page inside its own window has no `:root` or
+ * `body` of the page's to style: Studio's live previews render inside a shadow root, where both are
+ * `:host`, the box the preview is drawn in.
+ */
+export interface SiteStyleRoots {
+  root: string;
+  body: string;
+}
+
+/** The page's own root and body. */
+export const PAGE_ROOTS: SiteStyleRoots = { body: "body", root: ":root" };
+
 /**
  * Build the site-style sheet text: custom properties on `:root`, plain properties on `body`,
  * selector-keyed blocks (`"h1, h2"`, `a`, `.card`) as rules of their own, `&`-keyed blocks as
@@ -78,34 +97,34 @@ export type SiteStyleValueResolver = (
  * live-preview tab each ARE the page, with the project's `$head` in their head and the rendered
  * document as their body — so no host-side prefix is added, and nothing has to know one.
  *
- * @param {Record<string, unknown>} siteStyle
+ * @param {JxStyle} siteStyle - `project.json`'s `style` block
  * @param {Record<string, string>} mediaQueries
  * @param {(value: string) => string} transpose - Unit transposer (canvas vh→cqh etc.)
  * @param {SiteStyleValueResolver} [resolveValue] - What a reactive declaration becomes; absent, it
  *   is dropped, which is what every host does
+ * @param {SiteStyleRoots} [roots] - The selectors that stand for the page's root and body; the
+ *   page's own `:root` and `body` unless the sheet styles a page drawn inside something else
  * @returns {string}
  * @docs studio/interface/canvas
  */
 export function buildSiteStyleCSS(
-  siteStyle: Record<string, unknown>,
+  siteStyle: JxStyle,
   mediaQueries: Record<string, string>,
   transpose: (value: string) => string,
   resolveValue?: SiteStyleValueResolver,
+  roots: SiteStyleRoots = PAGE_ROOTS,
 ): string {
   const rules: string[] = [];
   const push = (style: JxStyle, selector: string | null) => {
-    for (const rule of buildStyleRules(style, {
-      mediaQueries,
-      scope: selector,
-      transposeValue: transpose,
-      /* The selector is closed over here rather than threaded through `buildStyleRules`, whose own
-         hook sees a rule TARGET (self / descendant / unscoped) and not the selector it hangs off;
-         the compiler's report names the selector, so this is where it is known. Conditionally
-         spread: `exactOptionalPropertyTypes` refuses an explicit `undefined` for an optional hook. */
-      ...(resolveValue
-        ? { resolveValue: (property, value) => resolveValue(property, value, selector) }
-        : {}),
-    })) {
+    const options: CssBuildOptions = { mediaQueries, scope: selector, transposeValue: transpose };
+    /* The selector is closed over here rather than threaded through `buildStyleRules`, whose own
+       hook sees a rule TARGET (self / descendant / unscoped) and not the selector it hangs off;
+       the compiler's report names the selector, so this is where it is known. Set only when given:
+       `exactOptionalPropertyTypes` refuses an explicit `undefined` for an optional hook. */
+    if (resolveValue) {
+      options.resolveValue = (property, value) => resolveValue(property, value, selector);
+    }
+    for (const rule of buildStyleRules(style, options)) {
       rules.push(rule.text);
     }
   };
@@ -120,9 +139,9 @@ export function buildSiteStyleCSS(
   const selectorBlocks: [string, JxStyle][] = [];
 
   for (const [key, value] of Object.entries(siteStyle)) {
-    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    if (isNonNullObject(value) && !Array.isArray(value)) {
       if (key.startsWith("@")) {
-        condBlocks.push([key, value as JxStyle]);
+        condBlocks.push([key, value]);
       } else if (!key.startsWith("--")) {
         /* A selector-keyed block is a rule of the page's stylesheet, and this is where the canvas
            used to lose it. `&`-keyed blocks were rescued first — `&[data-theme="light"]` is a STATE
@@ -134,7 +153,7 @@ export function buildSiteStyleCSS(
            canvas, which showed headings in the fallback face and links underlined (#296). A block
            under a `--name` key is not a rule at all — a custom property has no block value — and
            is skipped the way the compiler skips it. */
-        selectorBlocks.push([key, value as JxStyle]);
+        selectorBlocks.push([key, value]);
       }
       continue;
     }
@@ -147,21 +166,21 @@ export function buildSiteStyleCSS(
        every token on `:root` resolving against the wrong element, and the site builder disagreeing
        with `installTheme`, which puts the same authored block on `:root`. */
     if (key.startsWith("--") || key === "colorScheme" || key === "color-scheme") {
-      rootProps[key] = value as string;
+      rootProps[key] = value;
     } else {
-      bodyProps[key] = value as string;
+      bodyProps[key] = value;
     }
   }
 
   // Base rules precede conditional blocks so equal-specificity overrides win by source order.
-  push(rootProps, ":root");
-  push(bodyProps, "body");
+  push(rootProps, roots.root);
+  push(bodyProps, roots.body);
 
   for (const [key, block] of selectorBlocks) {
     if (key.startsWith("&")) {
       /* `&` is spliced onto `:root`, so `&[data-theme="light"]` emits `:root[data-theme="light"]`.
          The runtime resolves `&` against a scope and a project block has none but the root. */
-      push({ [key]: block } as JxStyle, ":root");
+      push({ [key]: block }, roots.root);
     } else {
       // A top-level selector key IS the selector — `.card` styles `.card`, not `:root .card`.
       push(block, key);
@@ -181,9 +200,9 @@ export function buildSiteStyleCSS(
     const condBody: JxStyle = {};
     const condSubs: [string, JxStyle][] = [];
     for (const [k, v] of Object.entries(block)) {
-      if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+      if (isNonNullObject(v) && !Array.isArray(v)) {
         if (!k.startsWith("@")) {
-          condSubs.push([k, v as JxStyle]);
+          condSubs.push([k, v]);
         }
         continue;
       }
@@ -193,8 +212,8 @@ export function buildSiteStyleCSS(
         condBody[k] = v;
       }
     }
-    push({ [atKey]: condRoot }, ":root");
-    push({ [atKey]: condBody }, "body");
+    push({ [atKey]: condRoot }, roots.root);
+    push({ [atKey]: condBody }, roots.body);
     for (const [sel, sub] of condSubs) {
       push({ [atKey]: sub }, sel);
     }
@@ -212,9 +231,9 @@ export function buildSiteStyleCSS(
     !("colorScheme" in siteStyle)
   ) {
     rules.push(
-      ":root { color-scheme: light dark }",
-      `:root:where([${COLOR_SCHEME_ATTR}="light"]) { color-scheme: light }`,
-      `:root:where([${COLOR_SCHEME_ATTR}="dark"]) { color-scheme: dark }`,
+      `${roots.root} { color-scheme: light dark }`,
+      `${roots.root}:where([${COLOR_SCHEME_ATTR}="light"]) { color-scheme: light }`,
+      `${roots.root}:where([${COLOR_SCHEME_ATTR}="dark"]) { color-scheme: dark }`,
     );
   }