@jxsuite/site 0.1.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Shenk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+# `@jxsuite/site`
+
+**What a Jx project's page at a route consists of:** routing, layout, `<head>`, context and site
+style, as pure functions with their IO injected.
+
+Every one of these rules has to be answered identically by four things that cannot share code any
+other way: the compiler's static build, the Studio canvas, a Bun dev/desktop server, and a
+Cloudflare Worker serving a live preview. None of them can import `@jxsuite/compiler`, whose
+dependency graph carries `sharp` and `esbuild`, so neither a browser bundle nor a Worker can load
+it. 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.
+
+So the rules live here, and this package has **no platform imports at all**: no `node:`, no DOM, no
+filesystem. Where a rule genuinely needs to read something, the reader is a parameter
+(`LayoutLoader`, `DocumentParser`) and is simply absent where there are no directories.
+
+| Module          | Answers                                                                                                                       |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `./routes`      | What URL a page file has (`pages/blog/[slug].md` becomes `/blog/:slug`), and which route a request matches. Pure string math. |
+| `./layout`      | What a page wrapped in its layout looks like: `$layout` resolution and `<slot>` distribution.                                 |
+| `./context`     | What `$site.*` and `$page.*` hold before anything renders.                                                                    |
+| `./head-merger` | How a site's, a layout's and a page's `$head` become one `<head>`, and how that `<head>` serializes.                          |
+| `./site-style`  | How `project.json`'s `style` becomes a stylesheet, including the dual-emitted colour-scheme selectors.                        |
+| `./compose`     | All of the above, applied: a route and a working tree become one merged document plus its `<head>`.                           |
+| `./shell`       | That document as HTML: the page that hands itself to `@jxsuite/runtime` in the reader's browser.                              |
+| `./paths`       | What an origin serving a project as a site may hand out, as an allowlist that defaults closed.                                |
+| `./serve`       | The decision order a published site answers with: file, then route, then the host's own lane, then the project's own 404.     |
+
+**Per-file exports, never a barrel.** Studio imports `./routes` into a browser bundle; a barrel
+would drag every other module in behind it.
+
+## Composing without a compiler
+
+`compose` and `shell` are what let a page render at its real URL with no build on the path. The
+server settles what it can (routing, layout, `<head>`, `$site`/`$page`) and the runtime assembles
+the DOM. Two things the build does are deliberately skipped, and both say so in the source: `$paths`
+is not expanded, because a route matches on demand and takes its parameters from the URL; and
+`imports` are not rebased, because the source tree is the served tree.
+
+All IO is injected (`SiteIO`, `AssetIO`, `LayoutLoader`, `DocumentParser`), so the same code path
+answers off a disk, out of a Durable Object's SQLite table, or over `fetch`. A host that has the
+project's format registry passes a `DocumentParser` and `.md` pages render; one that does not omits
+it and gets a named error rather than a blank page.
+
+## Where the rules are specified
+
+`specs/site-architecture.md`: routing §4, layouts §5, `$head` §8, context §10, i18n §13. The spec is
+the source of truth; this package is its one implementation.
+
+## Related
+
+- `@jxsuite/schema` holds the document types, `parse` and `locale`. This package depends on it, and
+  the edge is one-way and must stay that way.
+- `@jxsuite/runtime` renders the document this package assembles.
+- `@jxsuite/compiler` is the static build, which is one consumer rather than the owner.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/site",
-  "version": "0.1.0",
+  "version": "1.0.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": {
@@ -13,21 +13,25 @@
   ],
   "type": "module",
   "exports": {
-    "./routes": "./src/routes.ts",
-    "./layout": "./src/layout.ts",
+    "./compose": "./src/compose.ts",
     "./context": "./src/context.ts",
     "./head-merger": "./src/head-merger.ts",
+    "./layout": "./src/layout.ts",
+    "./paths": "./src/paths.ts",
+    "./routes": "./src/routes.ts",
+    "./serve": "./src/serve.ts",
+    "./shell": "./src/shell.ts",
     "./site-style": "./src/site-style.ts"
   },
   "publishConfig": {
-    "provenance": false
+    "provenance": true
   },
   "scripts": {
     "test": "bun test --isolate",
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/runtime": "workspace:^",
-    "@jxsuite/schema": "workspace:^"
+    "@jxsuite/runtime": "^3.0.0",
+    "@jxsuite/schema": "^2.0.0"
   }
 }

package/src/compose.ts

@@ -0,0 +1,349 @@
+/**
+ * Composing one page — routing, layout, `<head>` and context — over a project's working tree.
+ *
+ * Every rule here belongs to a sibling module in this package, not to this one: a page's URL
+ * ({@link ./routes.ts}), the layout it wraps in ({@link ./layout.ts}), the `<head>` those merge
+ * into ({@link ./head-merger.ts}) and the `$site`/`$page` state it binds against
+ * ({@link ./context.ts}) are each decided in exactly one place, so a live render and `jx build`
+ * cannot quietly disagree about what a route is. What is written here is only the assembly, and the
+ * IO is injected — the same function reads off a disk, out of a Durable Object's SQLite table, or
+ * over `fetch`.
+ *
+ * Two things the build does are deliberately NOT done:
+ *
+ * **`$paths` is not expanded.** Expanding a dynamic route means resolving a content collection or
+ * running a module. It is also not needed: this serves on demand, so `/blog/hello` MATCHES
+ * `pages/blog/[slug].json` and takes `slug` from the URL. What is lost is knowing which concrete
+ * pages exist — `/blog/anything` renders — and that is the right trade for a surface whose job is
+ * "show me this page".
+ *
+ * **`imports` are not rebased.** The build rewrites a project-level relative import onto the page's
+ * own directory because the output tree has a different shape from the source tree. This serves the
+ * source tree at the origin root, where the authored path already means what it says.
+ */
+
+import { compareRoutes, fileToRoute, isRoutedPageFile, matchRoute } from "./routes.ts";
+import type { RouteShape } from "./routes.ts";
+import { resolveLayout } from "./layout.ts";
+import { mergeHead } from "./head-merger.ts";
+import { injectContext } from "./context.ts";
+import { localeDirection, localeOfRoute, resolveI18n } from "@jxsuite/schema/locale";
+import { parseJxDocument } from "@jxsuite/schema/parse";
+import type { JxDocument, JxElement, JxHeadEntry, ProjectConfig } from "@jxsuite/schema/types";
+
+/** Everything the composer settled about a page before a renderer sees it. */
+export interface ComposedPage {
+  doc: JxDocument;
+  head: JxHeadEntry[];
+  lang: string;
+  dir: "ltr" | "rtl";
+}
+
+/**
+ * Turning a non-JSON document's bytes into a document, or null when this host has no parser for it.
+ *
+ * Named for the same reason {@link ./layout.ts}'s `LayoutLoader` is: it is the seam a host fills,
+ * and what it decides is whether non-JSON pages render at all. A host with the project's format
+ * registry (a Bun server, the desktop app) supplies one and `pages/index.md` composes; a host
+ * without one (a Worker, where a format's parser is not reachable) omits it, and the caller gets a
+ * named error instead of a blank page.
+ */
+export type DocumentParser = (
+  path: string,
+  text: string,
+) => Promise<JxDocument | null> | JxDocument | null;
+
+/** Reading the working tree — the one thing this module cannot do for itself. */
+export interface SiteIO {
+  /** A project file's text, or null when the tree has no such file. */
+  read: (path: string) => Promise<string | null>;
+  /** Every non-deleted path in the tree. */
+  paths: () => readonly string[];
+  /** Parse a non-JSON document through its format. Absent where the host has no format registry. */
+  parse?: DocumentParser;
+}
+
+/** A page file and the route it answers. */
+export interface PageRoute extends RouteShape {
+  /** Project path of the page source, e.g. `pages/blog/[slug].json`. */
+  sourcePath: string;
+}
+
+/** 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 }))
+    .toSorted(compareRoutes);
+}
+
+/** Read and parse a page document, whatever format its extension claims. */
+async function readDocument(io: SiteIO, path: string): Promise<JxDocument | null> {
+  const text = await io.read(path);
+  if (text === null) {
+    return null;
+  }
+  if (path.endsWith(".json")) {
+    return parseJxDocument(text, path);
+  }
+  return io.parse ? ((await io.parse(path, text)) ?? null) : null;
+}
+
+/** The project's configuration, or an empty one when it has none this host can read. */
+export async function readProjectConfig(io: SiteIO): Promise<ProjectConfig> {
+  const text = await io.read("project.json");
+  if (text === null) {
+    return {} as ProjectConfig;
+  }
+  try {
+    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;
+  }
+}
+
+/**
+ * Union two `$elements` lists, keeping declaration order and dropping repeats.
+ *
+ * An entry is either a bare specifier (a string) or a `{ $ref }`; both are keyed by the thing they
+ * name, so a page and its layout declaring the same component register it once.
+ */
+export function unionElements(
+  ...lists: (readonly unknown[] | 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));
+    if (!seen.has(key)) {
+      seen.add(key);
+      merged.push(entry as string | JxElement);
+    }
+  }
+  return merged.length > 0 ? merged : undefined;
+}
+
+/** A component file in the project's own library, keyed by the tag it defines. */
+const COMPONENT_FILE = /^components\/([^/]+-[^/]*)\.json$/;
+
+/**
+ * A `$ref`'s project path, so the same file written from two places is one key.
+ *
+ * A layout says `../components/nav.json` and a page says `./components/nav.json` for one file. Both
+ * resolve against the shell's base rather than against the document that wrote them, so both name
+ * `/components/nav.json` — and comparing the raw strings would register it twice.
+ */
+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") {
+    return;
+  }
+  if (Array.isArray(node)) {
+    for (const child of node) {
+      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);
+}
+
+/**
+ * The project components a document USES, as `$elements` entries it never declared.
+ *
+ * `$elements` is a declaration, and almost nothing declares one: across the shipped starters a
+ * layout names the chrome it uses and no page names anything, because in a BUILD it does not have
+ * to — the compiler scans the rendered HTML for tags it compiled and emits a module script per tag
+ * (`site-build.ts`, `injectComponentScripts`). The studio canvas reaches the same answer a third
+ * way, walking the document against its component registry. Only this composer took `$elements`
+ * literally, so a page rendered its own components as inert unknown tags while the canvas beside it
+ * rendered them correctly — and, as everywhere else in this area, with nothing reported anywhere.
+ *
+ * The walk is transitive, which the other two auto-discoveries are not: a component's own tags are
+ * found by reading it, so `sa-pricing` bringing `sa-check-item` registers both. The build gets that
+ * for free by scanning HTML it has already rendered; here the definition has to be opened. It is
+ * bounded by the components a page actually reaches, and each is opened once.
+ *
+ * Only `.json` components are discoverable, because a `$ref` is resolved by the browser: the
+ * runtime fetches the file and parses it as a document, so a component in a format needing an
+ * extension's parser cannot be registered this way whoever discovers it.
+ */
+async function discoverElements(io: SiteIO, doc: JxDocument): Promise<{ $ref: string }[]> {
+  const available = new Map<string, string>();
+  for (const path of io.paths()) {
+    const tag = COMPONENT_FILE.exec(path)?.[1];
+    if (tag !== undefined) {
+      available.set(tag, path);
+    }
+  }
+  if (available.size === 0) {
+    return [];
+  }
+
+  /* What the document already declares, at any level: the union above has run, so this is the
+     page's, the layout's and the project's together. A declared entry is still WALKED — it may
+     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") {
+      declared.add(refPath(ref));
+    }
+  }
+
+  const discovered: { $ref: string }[] = [];
+  const opened = new Set<string>();
+  let frontier: unknown[] = [doc];
+  while (frontier.length > 0) {
+    const tags = new Set<string>();
+    for (const node of frontier) {
+      collectTagNames(node, tags);
+    }
+    const next: unknown[] = [];
+    for (const tag of tags) {
+      const path = available.get(tag);
+      if (path === undefined || opened.has(tag)) {
+        continue;
+      }
+      opened.add(tag);
+      const ref = `./${path}`;
+      if (!declared.has(refPath(ref))) {
+        discovered.push({ $ref: ref });
+      }
+      const definition = await readDocument(io, path);
+      if (definition) {
+        next.push(definition);
+      }
+    }
+    frontier = next;
+  }
+  return discovered;
+}
+
+/**
+ * Why a route could not be composed — a sentence for the reader, not a stack trace.
+ *
+ * The constructor is explicit rather than a `name` field initializer, and that is a coverage fact
+ * rather than a style one: a class field on a subclass synthesizes a constructor, Bun counts that
+ * synthesized function, and `new ComposeError(...)` never marks it entered — V8 attributes the call
+ * to `Error`. The file then sits at 14/15 functions forever with every line covered, which reads
+ * like an untested branch and is not one. Writing the constructor out is what makes the count
+ * true.
+ */
+export class ComposeError extends Error {
+  override readonly name: string;
+
+  constructor(message: string) {
+    super(message);
+    this.name = "ComposeError";
+  }
+}
+
+/**
+ * Compose the page a URL asks for, or null when no route claims it.
+ *
+ * @param {SiteIO} io - Reads the working tree
+ * @param {readonly PageRoute[]} routes - The table, in match order
+ * @param {ProjectConfig} config - The project's configuration
+ * @param {string} pathname - The request path, e.g. `/blog/hello/`
+ */
+export async function composeRoute(
+  io: SiteIO,
+  routes: readonly PageRoute[],
+  config: ProjectConfig,
+  pathname: string,
+): Promise<ComposedPage | null> {
+  const match = matchRoute(routes, pathname);
+  if (!match) {
+    return null;
+  }
+  return composePage(io, match.route, config, match.params);
+}
+
+/** Compose one known route with known parameters. */
+export async function composePage(
+  io: SiteIO,
+  route: PageRoute,
+  config: ProjectConfig,
+  params: Record<string, string>,
+): Promise<ComposedPage> {
+  const pageDoc = await readDocument(io, route.sourcePath);
+  if (!pageDoc) {
+    throw new ComposeError(
+      `${route.sourcePath} could not be read as a page. Only .json pages render here; other formats need their extension's parser, which this host does not run.`,
+    );
+  }
+
+  const merged = await resolveLayout(pageDoc, config as Record<string, unknown>, async (ref) => {
+    const doc = await readDocument(io, ref.replace(/^\.\//, ""));
+    if (!doc) {
+      throw new ComposeError(`Layout not found: ${ref}`);
+    }
+    return doc;
+  });
+
+  /*
+   * `$elements` is legal on the page AND on the layout, and `resolveLayout` merges neither into the
+   * other — so the composed document has only the LAYOUT's, and every custom element a page
+   * declared for itself goes unregistered. The compiler reads both documents for exactly this
+   * reason (`site-build.ts`, "a page of inert unknown elements with no error anywhere"), and the
+   * failure is just as quiet here: the runtime renders `<site-card>` into the DOM, nothing defines
+   * it, and the browser reports nothing at all.
+   */
+  const elements = unionElements(merged.$elements, pageDoc.$elements);
+  if (elements) {
+    merged.$elements = elements;
+  }
+
+  const { i18n } = resolveI18n(config);
+  const siteRoute = {
+    _pathParams: params,
+    sourcePath: route.sourcePath,
+    urlPattern: route.urlPattern,
+  };
+  injectContext(merged, config, siteRoute, null, i18n);
+
+  /* After `injectContext`, because that is what merges the PROJECT's `$elements` in — discovering
+     before it would re-declare every component the project already names for every page. */
+  const discovered = await discoverElements(io, merged);
+  const withDiscovered = unionElements(merged.$elements, discovered);
+  if (withDiscovered) {
+    merged.$elements = withDiscovered;
+  }
+
+  const pageHead = (pageDoc.$head ?? merged._pageHead ?? []) as JxHeadEntry[];
+  const layoutHead = (merged.$head ?? []) as JxHeadEntry[];
+  const siteHead = (config.$head ?? []) as JxHeadEntry[];
+  const title = (pageDoc.title ?? merged._pageTitle ?? config.name ?? "") as string;
+  const lang =
+    (typeof pageDoc.$lang === "string" ? 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 }),
+  });
+
+  /* `$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. */
+  delete merged.$head;
+  delete merged._pageHead;
+  delete merged._pageTitle;
+
+  return { dir: localeDirection(lang), doc: merged, head, lang };
+}

package/src/context.ts

@@ -21,7 +21,12 @@
  * @docs framework/site/i18n
  */
 
-import type { JxDocument, JxElement, JxStateDefinition, ProjectConfig } from "@jxsuite/schema/types";
+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";
 

package/src/paths.ts

@@ -0,0 +1,146 @@
+/**
+ * What a site origin serves, and — the part that matters — what it refuses.
+ *
+ * A previewed page runs the project's own JavaScript, which routinely includes third-party script,
+ * and it runs it on an origin that also answers for the project tree. The rendered site gives away
+ * its own content by design; a project's `.dev.vars` does not, and neither does the `project.json`
+ * that names the user's deployment. So this list is an ALLOWLIST and it defaults closed. A denylist
+ * would be the wrong shape: it has to be complete to be correct, and the cost of forgetting an
+ * entry is a secret readable by whatever the page loaded.
+ *
+ * This is deliberately NOT the rule an editing server uses. `@jxsuite/server`'s `serveProjectFile`
+ * serves the whole project root, which is Studio's protocol working — the editor addresses files it
+ * already holds paths for. The same latitude on an origin running project script is a hole, so the
+ * two rules stay apart even though they answer some of the same URLs.
+ *
+ * The mapping mirrors what `jx build` writes into `dist/`:
+ *
+ * - `public/**` is copied to the site root, so `/favicon.svg` is `public/favicon.svg`.
+ * - Everything else keeps its project path, so `/components/card.json` is that file — which is what
+ *   makes the runtime's own `$ref` and `$elements` resolution work with no rewriting at all.
+ */
+
+/** Project directories a site origin may read from. Everything else is not servable. */
+export const SERVABLE_ROOTS: readonly string[] = [
+  "public/",
+  "components/",
+  "layouts/",
+  "pages/",
+  "assets/",
+  "media/",
+  "content/",
+  "data/",
+  "styles/",
+];
+
+/**
+ * Files that are never servable however they are addressed.
+ *
+ * Belt and braces over {@link SERVABLE_ROOTS} — these all sit at the project root and so are
+ * already excluded, but they are the exact files whose exposure would matter and the cost of naming
+ * them twice is nothing.
+ */
+export const NEVER_SERVABLE: ReadonlySet<string> = new Set([
+  "project.json",
+  "package.json",
+  "package-lock.json",
+  "bun.lock",
+  "bun.lockb",
+  "wrangler.jsonc",
+  "wrangler.toml",
+  ".dev.vars",
+]);
+
+/** A path segment that must never appear: dotfiles, traversal, and empty interior segments. */
+function segmentIsSafe(segment: string): boolean {
+  return segment !== "" && segment !== "." && segment !== ".." && !segment.startsWith(".");
+}
+
+/**
+ * Normalise a request path into a project-relative path, or null when it is not one.
+ *
+ * Traversal is rejected rather than resolved: a `..` that a decode produced is not a path a site
+ * ever legitimately asks for, and answering it — even correctly — means the check has to be right
+ * about what it collapsed to.
+ */
+export function normalizeRequestPath(pathname: string): string | null {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    return null;
+  }
+  if (decoded.includes("\0") || decoded.includes("\\")) {
+    return null;
+  }
+  /* A TRAILING slash is stripped rather than rejected. `build.trailingSlash` defaults to `always`,
+     so `/blog/hello/` is the ordinary form of a page URL and the one Open in Browser hands over —
+     treating its empty last segment as a malformed path 404'd every page on the site. Leading and
+     interior empty segments are still refused; only the final one is a writing convention. */
+  const clean = decoded.replace(/^\/+/, "").replace(/\/+$/, "");
+  if (clean === "") {
+    return "";
+  }
+  return clean.split("/").every((segment) => segmentIsSafe(segment)) ? clean : null;
+}
+
+/**
+ * The project paths a request path could be asking for, in the order a built site would answer.
+ *
+ * `public/` first, because that is where the build copies from and an author who put `robots.txt`
+ * in both meant the one they publish.
+ */
+export function candidatePaths(requestPath: string): string[] {
+  if (requestPath === "" || NEVER_SERVABLE.has(requestPath)) {
+    return [];
+  }
+  const candidates = [`public/${requestPath}`];
+  if (SERVABLE_ROOTS.some((root) => requestPath.startsWith(root))) {
+    candidates.push(requestPath);
+  }
+  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",
+};
+
+/**
+ * The Content-Type a site origin serves a path as.
+ *
+ * Unlike an editor's raw-file mount — which never says `text/html` and attaches everything, because
+ * it answers on an origin that holds a session — this serves real types. That is the whole point of
+ * giving a preview an origin of its own: an HTML file executing here is the site working, not a
+ * privilege escalation, because there is nothing on this origin to escalate to.
+ */
+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";
+}

package/src/serve.ts

@@ -0,0 +1,155 @@
+/**
+ * Turning one request into a response, on an origin that serves a project as a site.
+ *
+ * The decision order mirrors what a published site does with the same URL, which is the whole
+ * contract of serving on an origin of its own: a path is a FILE if the tree has one there, and a
+ * ROUTE otherwise. Getting that order wrong in either direction is visible — a `pages/` document
+ * served as JSON instead of rendered, or a `/favicon.svg` answered with someone's index page.
+ *
+ * A host's own surfaces — a runtime bundle, a reload stream — are NOT a lane here. They are
+ * dispatched before this function is reached, because a namespace only that host knows about is not
+ * a fact about the site. What a host may add is a {@link ServeOptions.fallback}, tried after routes
+ * and before the 404, which is where a lane like on-demand npm bundling belongs: it answers paths a
+ * site legitimately asks for that this package cannot produce.
+ */
+
+import { candidatePaths, contentTypeFor, normalizeRequestPath } from "./paths.ts";
+import { ComposeError, composeRoute, readProjectConfig, routeTable } from "./compose.ts";
+import type { PageRoute, SiteIO } from "./compose.ts";
+import { pageShell, problemShell } from "./shell.ts";
+import type { ShellOptions } from "./shell.ts";
+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>;
+}
+
+/** What this origin knows about a project, computed once per request. */
+export interface SiteContext {
+  config: ProjectConfig;
+  routes: PageRoute[];
+}
+
+/** How a host wants pages shelled, and what it can answer that this package cannot. */
+export interface ServeOptions {
+  shell: ShellOptions;
+  /** Tried after routes and before the 404 — a host's own lane for site-legitimate paths. */
+  fallback?: (requestPath: string) => Promise<Response | null>;
+}
+
+/** Headers every response from this origin carries, whatever it is serving. */
+export function siteHeaders(contentType: string): Record<string, 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. */
+    "Cache-Control": "private, no-store",
+    "Content-Type": contentType,
+    /* A live render is a working copy, and an indexed one would compete with the site the author
+       actually publishes. */
+    "X-Robots-Tag": "noindex, nofollow",
+    "X-Content-Type-Options": "nosniff",
+    /* The origin this was reached from is nobody else's business — and on a desktop machine the
+       referring origin is an editor holding a token. */
+    "Referrer-Policy": "same-origin",
+  };
+}
+
+/** Read the project's configuration and route table out of the tree. */
+export async function siteContext(io: SiteIO): Promise<SiteContext> {
+  return { config: await readProjectConfig(io), routes: routeTable(io.paths()) };
+}
+
+/** A plain 404, for when neither the tree nor the project has anything to say. */
+function plainNotFound(): Response {
+  return new Response("Not found", {
+    headers: siteHeaders("text/plain; charset=utf-8"),
+    status: 404,
+  });
+}
+
+/**
+ * Serve one path.
+ *
+ * @param {string} pathname - The request path, still URL-encoded
+ * @param {SiteIO} io - Reads the working tree's text
+ * @param {AssetIO} assets - Reads a servable file's bytes
+ * @param {SiteContext} context - The project's configuration and route table
+ * @param {ServeOptions} options - The shell contract, and the host's own fallback lane
+ */
+export async function serveSite(
+  pathname: string,
+  io: SiteIO,
+  assets: AssetIO,
+  context: SiteContext,
+  options: ServeOptions,
+): Promise<Response> {
+  const requestPath = normalizeRequestPath(pathname);
+  if (requestPath === null) {
+    return plainNotFound();
+  }
+
+  // A file the tree really has, at the path the published site would serve it from.
+  for (const candidate of candidatePaths(requestPath)) {
+    const bytes = await assets.bytes(candidate);
+    if (bytes) {
+      return new Response(bytes as BodyInit, {
+        headers: siteHeaders(contentTypeFor(candidate)),
+      });
+    }
+  }
+
+  const page = await composeSafely(io, context, pathname, options.shell);
+  if (page) {
+    return page;
+  }
+
+  const fallback = await options.fallback?.(requestPath);
+  if (fallback) {
+    return fallback;
+  }
+
+  /* The project's own 404, at 404 — the same thing a built site serves, because a reader who
+     mistypes a URL should see the site's answer and not ours. */
+  const notFound = await composeSafely(io, context, "/404", options.shell);
+  if (notFound) {
+    return new Response(await notFound.text(), {
+      headers: siteHeaders("text/html; charset=utf-8"),
+      status: 404,
+    });
+  }
+  return plainNotFound();
+}
+
+/**
+ * Compose a route into a response, turning a compose failure into a page that says so.
+ *
+ * A render that 500s tells the author nothing they can act on. A page naming the file and the
+ * reason is the difference between "the preview is broken" and "this page needs a `.json` layout".
+ */
+async function composeSafely(
+  io: SiteIO,
+  context: SiteContext,
+  pathname: string,
+  shell: ShellOptions,
+): Promise<Response | null> {
+  let page;
+  try {
+    page = await composeRoute(io, context.routes, context.config, pathname);
+  } catch (error) {
+    if (error instanceof ComposeError) {
+      return new Response(problemShell(error.message), {
+        headers: siteHeaders("text/html; charset=utf-8"),
+        status: 500,
+      });
+    }
+    throw error;
+  }
+  if (!page) {
+    return null;
+  }
+  return new Response(pageShell(page, shell), {
+    headers: siteHeaders("text/html; charset=utf-8"),
+  });
+}

package/src/shell.ts

@@ -0,0 +1,126 @@
+/**
+ * The HTML a composed page is served as.
+ *
+ * A built page is prerendered; a live one cannot be, because prerendering is the compiler's job and
+ * the compiler is not on this path. So the shell carries what the SERVER can settle — the merged
+ * `<head>`, the page's language and writing direction — and hands the composed document to
+ * `@jxsuite/runtime`, which builds the DOM in the reader's browser exactly as the studio's canvas
+ * does.
+ *
+ * Two details are load-bearing:
+ *
+ * **`base`.** Handed a document object rather than a URL, the runtime has no base to resolve
+ * `$ref`, `$elements` and asset paths against and falls back to `location.href` — which is right
+ * only at the site root. At `/blog/hello/` every relative reference would resolve two directories
+ * too deep. A host serving the project tree AT its origin root passes `"/"`, and saying so is what
+ * makes an authored `./components/card.json` find its file.
+ *
+ * **The document travels in a `<script type="application/json">`, not in a JS literal.** The only
+ * sequence that can end such a block is `</script`, so escaping `<` in the payload closes the one
+ * hole; a JS string literal would have to be right about backslashes, line separators and
+ * `</script` all at once.
+ *
+ * Everything else is a parameter rather than a constant, because the two hosts that serve this
+ * disagree about all of it: where the runtime bundle lives, whether there is a site stylesheet,
+ * whether a reload client is injected, and whether the runtime may reach a resolver.
+ */
+
+import { renderHead } from "./head-merger.ts";
+import type { ComposedPage } from "./compose.ts";
+
+/** What a host must tell the shell about its own origin. */
+export interface ShellOptions {
+  /** URL of the `@jxsuite/runtime` browser bundle on this origin. */
+  runtimeUrl: string;
+  /** What relative references resolve against — `"/"` for a tree served at the origin root. */
+  base: string;
+  /** Stylesheet carrying `project.json`'s `style`, when the host emits one. */
+  styleUrl?: string | undefined;
+  /** A module the host appends after the render — a live-reload client, typically. */
+  clientScriptUrl?: string | undefined;
+  /**
+   * Token for the runtime's `/__jx_resolve__` and `/__jx_server__` proxies.
+   *
+   * Present only where the host can actually answer them. Without it the runtime still renders;
+   * what it cannot do is resolve `$src` classes, content collections or `timing: "server"`, so a
+   * host that omits this should expect a collection to render as an empty list.
+   */
+  resolveToken?: string | undefined;
+}
+
+/** Escape a string for an HTML attribute value. */
+function attr(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;");
+}
+
+/**
+ * Serialize a document for a `<script type="application/json">` block.
+ *
+ * `<` 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`);
+}
+
+/** The document for one composed page. */
+export function pageShell(page: ComposedPage, options: ShellOptions): string {
+  const imports = options.resolveToken ? "Jx, setResolveToken" : "Jx";
+  const setToken = options.resolveToken
+    ? `\nsetResolveToken(${JSON.stringify(options.resolveToken)});`
+    : "";
+  const style = options.styleUrl
+    ? `\n  <link rel="stylesheet" href="${attr(options.styleUrl)}">`
+    : "";
+  /* Scroll restoration is turned off before first paint, and it has to be an inline classic script
+     to land there: a module script is deferred, so the browser would have restored against an empty
+     body — a client-rendered page has no height yet — and left the reader at the top. Whoever
+     restores the position does it after the render instead. */
+  const client = options.clientScriptUrl
+    ? `\n<script type="module" src="${attr(options.clientScriptUrl)}"></script>`
+    : "";
+  return `<!doctype html>
+<html lang="${attr(page.lang)}" dir="${attr(page.dir)}">
+<head>
+  ${renderHead(page.head)}${style}
+  <script>history.scrollRestoration = "manual";</script>
+</head>
+<body>
+<script type="application/json" id="jx-page-document">${jsonPayload(page.doc)}</script>
+<script type="module">
+import { ${imports} } from "${attr(options.runtimeUrl)}";${setToken}
+const source = document.getElementById("jx-page-document").textContent;
+await Jx(JSON.parse(source), document.body, { base: ${JSON.stringify(options.base)} });
+</script>${client}
+</body>
+</html>
+`;
+}
+
+/**
+ * A page that names what stopped a route from rendering.
+ *
+ * A preview that 500s tells the author nothing they can act on. A page naming the file and the
+ * reason — a layout that is not there, a format whose parser does not run here — is the difference
+ * between "the preview is broken" and "this page needs a `.json` layout".
+ */
+export function problemShell(message: string): string {
+  const escaped = message.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>This page could not be rendered</title>
+</head>
+<body>
+  <h1>This page could not be rendered</h1>
+  <p>${escaped}</p>
+</body>
+</html>
+`;
+}

package/src/site-style.ts

@@ -1,12 +1,16 @@
 /// <reference lib="dom" />
 /**
- * Site-style stylesheet builder — pure functions extracted for testability.
+ * Site-style stylesheet builder — `project.json`'s `style` as a real stylesheet.
  *
- * 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
+ * A host emits the project's `style` as a stylesheet rather than as 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.
+ * entirely. Scheme-query blocks dual-emit through the runtime's schemeSelectors so a host honors
+ * both the OS preference and its own forced-scheme toggle.
+ *
+ * Two hosts share it, which is why it is here rather than in either of them: the studio canvas,
+ * which passes a transposer rewriting viewport units to container units, and the live preview
+ * origin, which passes identity because a browser tab IS the viewport.
  */
 
 import { pureSchemeOf, resolveAtQuery, schemeSelectors, camelToKebab } from "@jxsuite/runtime";