@jxsuite/site 2.5.1 → 2.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/site",
-  "version": "2.5.1",
+  "version": "2.7.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": {
@@ -22,7 +22,9 @@
     "./routes": "./src/routes.ts",
     "./serve": "./src/serve.ts",
     "./shell": "./src/shell.ts",
-    "./site-style": "./src/site-style.ts"
+    "./site-style": "./src/site-style.ts",
+    "./xmp-containers": "./src/xmp-containers.ts",
+    "./xmp-packet": "./src/xmp-packet.ts"
   },
   "publishConfig": {
     "provenance": true
@@ -32,7 +34,7 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/runtime": "^6.2.2",
-    "@jxsuite/schema": "^5.5.0"
+    "@jxsuite/runtime": "^7.0.0",
+    "@jxsuite/schema": "^6.0.0"
   }
 }

package/src/compose.ts

@@ -28,10 +28,18 @@ import { resolveLayout } from "./layout.ts";
 import { mergeHead, withPageDescription } from "./head-merger.ts";
 import type { HeadMergeContext } from "./head-merger.ts";
 import { injectContext } from "./context.ts";
+import { inheritableFormulas } from "@jxsuite/runtime/expression";
+import { qualifyScripts } from "@jxsuite/schema/document-scripts";
 import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 import { localeDirection, localeOfRoute, resolveI18n } from "@jxsuite/schema/locale";
 import { isNativeDocumentPath, parseNativeDocument } from "@jxsuite/schema/jxn";
-import type { JxDocument, JxElement, JxHeadEntry, ProjectConfig } from "@jxsuite/schema/types";
+import type {
+  JxDocument,
+  JxElement,
+  JxHeadEntry,
+  JxStateDefinition,
+  ProjectConfig,
+} from "@jxsuite/schema/types";
 import { PROJECT_FILE_NAMES, parseProjectSource } from "@jxsuite/schema/project-file";
 
 /** Everything the composer settled about a page before a renderer sees it. */
@@ -40,6 +48,12 @@ export interface ComposedPage {
   head: JxHeadEntry[];
   lang: string;
   dir: "ltr" | "rtl";
+  /**
+   * The project's pure named formulas a component inherits (spec.md §13.4), when it has any. The
+   * page has them in its own `state` already; a component's document is fetched as written, so the
+   * shell hands these to the runtime before it renders.
+   */
+  formulas?: Record<string, JxStateDefinition>;
 }
 
 /**
@@ -83,16 +97,23 @@ export function routeTable(paths: readonly string[]): PageRoute[] {
     .toSorted(compareRoutes);
 }
 
-/** Read and parse a page document, whatever format its extension claims. */
+/**
+ * Read and parse a document, whatever format its extension claims.
+ *
+ * Every entry naming the document's own script is qualified with the document's path here, as it is
+ * read (`spec.md` §23.2): a page is about to be merged onto its layout, and after that nothing
+ * records which of the two an entry was written in.
+ */
 async function readDocument(io: SiteIO, path: string): Promise<JxDocument | null> {
   const text = await io.read(path);
   if (text === null) {
     return null;
   }
   if (isNativeDocumentPath(path)) {
-    return parseNativeDocument(text, path);
+    return qualifyScripts(parseNativeDocument(text, path), path);
   }
-  return io.parse ? ((await io.parse(path, text)) ?? null) : null;
+  const parsed = io.parse ? await io.parse(path, text) : null;
+  return parsed ? qualifyScripts(parsed, path) : null;
 }
 
 /**
@@ -376,6 +397,15 @@ export async function composePage(
   delete merged.$head;
   delete merged._pageHead;
   delete merged._pageTitle;
+  /* A page merged onto a layout has one `$script` where there were two documents, so the text is
+     neither's to speak for; every entry already names its own document, and the page fetches the
+     client module from there. The server module is the other reason: a reader is never sent one. */
+  delete merged.$script;
 
-  return { dir: localeDirection(lang), doc: merged, head, lang };
+  const composed: ComposedPage = { dir: localeDirection(lang), doc: merged, head, lang };
+  const formulas = inheritableFormulas(config.state);
+  if (Object.keys(formulas).length > 0) {
+    composed.formulas = formulas;
+  }
+  return composed;
 }

package/src/context.ts

@@ -4,11 +4,19 @@
  * 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) $page.pagination — where a paged route's page sits in its list (§4.3)
+ * Per site-architecture spec §10:
+ *
+ * - `$site.name`, `$site.url`: from the project file's `name` and `url`.
+ * - `$site.<key>`: each project `state` entry as written, read-only, never replacing the four names
+ *   in {@link SITE_CONTEXT_KEYS} (§10.4).
+ * - `$page.url`, `$page.title`, `$page.params`: the current page's URL path, title and dynamic route
+ *   parameters.
+ * - `$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).
+ * - `$page.pagination`: where a paged route's page sits in its list (§4.3).
+ *
+ * Each project `state` entry is also copied into the page's own `state` unless the page or its
+ * layout declares the key.
  *
  * 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}`
@@ -56,6 +64,17 @@ export interface SiteRoute {
  */
 export type ImportRebaser = (src: string, route: SiteRoute) => string;
 
+/**
+ * The names `$site` defines itself (site-architecture.md §5.5). A project `state` entry with one of
+ * these names reaches the page as bare state only (§10.4).
+ */
+export const SITE_CONTEXT_KEYS: ReadonlySet<string> = new Set([
+  "defaultLocale",
+  "locales",
+  "name",
+  "url",
+]);
+
 /**
  * Inject $site and $page context into a page document's state.
  *
@@ -86,13 +105,17 @@ export function injectContext(
     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. */
+  /* Project state goes first and the context's own names last, so a state entry called `name` can
+     never stand in for the project's name; it is left out altogether so that a project without
+     `i18n` does not grow a `$site.locales` from its state. `Object.fromEntries` and a spread, not
+     `Object.assign`: an authored `__proto__` key stays an own data property. */
   doc.state.$site = {
+    ...Object.fromEntries(
+      Object.entries(projectConfig.state ?? {}).filter(([key]) => !SITE_CONTEXT_KEYS.has(key)),
+    ),
     name: projectConfig.name ?? "Jx Site",
     url: projectConfig.url ?? "",
     ...localeFields,
-    ...projectConfig.state,
   };
 
   /*
@@ -153,7 +176,8 @@ export function injectContext(
   }
   doc.state.$page = page;
 
-  // Merge project-level state into page state (page wins on conflicts)
+  // Merge project-level state into page state: the page, then its layout, wins
+  // (site-architecture.md §10.4)
   if (projectConfig.state) {
     for (const [key, value] of Object.entries(projectConfig.state)) {
       if (key !== "$site" && key !== "$page" && !(key in doc.state)) {

package/src/serve.ts

@@ -13,6 +13,8 @@
  * site legitimately asks for that this package cannot produce.
  */
 
+import { withoutServerScript } from "@jxsuite/schema/document-scripts";
+import { isJsonObject } from "@jxsuite/schema/guards";
 import { isJxnPath, parseJxn } from "@jxsuite/schema/jxn";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { candidatePaths, contentTypeFor, normalizeRequestPath } from "./paths.ts";
@@ -20,7 +22,7 @@ import { ComposeError, composeRoute, readProjectConfig, routeTable } from "./com
 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";
+import type { JsonValue, JxDocument, ProjectConfig } from "@jxsuite/schema/types";
 
 /** Reading bytes for a servable file — separate from {@link SiteIO} because assets are binary. */
 export interface AssetIO {
@@ -110,7 +112,7 @@ export async function serveSite(
       return jxnAsJson(bytes, candidate);
     }
     if (bytes) {
-      return new Response(bytes, {
+      return new Response(isJsonPath(candidate) ? jsonForReader(bytes) : bytes, {
         headers: siteHeaders(contentTypeFor(candidate)),
       });
     }
@@ -138,6 +140,49 @@ export async function serveSite(
   return plainNotFound();
 }
 
+/** A path naming a JSON file. */
+const JSON_PATH = /\.json$/iu;
+
+function isJsonPath(path: string): boolean {
+  return JSON_PATH.test(path);
+}
+
+/** The key a document's own modules are under, as a JSON file spells it. */
+const SCRIPT_KEY = '"$script"';
+
+/**
+ * A `.json` file as a reader may have it: a document's server module left out (`spec.md` §23.2),
+ * and every other file exactly the bytes it is.
+ *
+ * A file is parsed only when its text names `$script`, so an ordinary one is never read as
+ * anything, and one that does not parse is served as it is: what is wrong with it is the author's
+ * to see, and it holds no module this could have found.
+ *
+ * @param bytes The file.
+ */
+function jsonForReader(bytes: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer> | string {
+  const text = new TextDecoder().decode(bytes);
+  if (!text.includes(SCRIPT_KEY)) {
+    return bytes;
+  }
+  let value: JsonValue;
+  try {
+    /* SAFETY: trust boundary. The file parsed as JSON, which is all the type says; it is used
+       below only after it is seen to be an object. */
+    value = JSON.parse(text) as JsonValue;
+  } catch {
+    return bytes;
+  }
+  if (!isJsonObject(value)) {
+    return bytes;
+  }
+  /* SAFETY: every member of `JxDocument` is optional and `withoutServerScript` reads only
+     `$script`, through optional access, so any JSON object is a document as far as it looks. */
+  const document = value as JxDocument;
+  const stripped = withoutServerScript(document);
+  return stripped === document ? bytes : JSON.stringify(stripped);
+}
+
 /**
  * Compose a route into a response, turning a compose failure into a page that says so.
  *
@@ -150,7 +195,8 @@ export async function serveSite(
  * The runtime fetches a `$ref` and calls `res.json()`, on any origin, so answering JSON here keeps
  * a KDL parser out of every page. A file that does not read answers 422 with the reason, because
  * the runtime reports a failed fetch by its status and this one is the author's to fix. The dev
- * server's canvas origin answers the same way, with its own headers.
+ * server's canvas origin answers the same way, with its own headers. The document's server module
+ * is left out, as it is from a `.json` document (`spec.md` §23.2).
  *
  * @param bytes The file.
  * @param path Its path, which names it in an error.
@@ -162,7 +208,7 @@ export function jxnAsJson(
   headers: (type: string) => HeadersInit = siteHeaders,
 ): Response {
   try {
-    const document = parseJxn(new TextDecoder().decode(bytes), path);
+    const document = withoutServerScript(parseJxn(new TextDecoder().decode(bytes), path));
     return Response.json(document, { headers: headers("application/json;charset=utf-8") });
   } catch (error) {
     return new Response(errorMessage(error), {

package/src/shell.ts

@@ -47,6 +47,13 @@ export interface ShellOptions {
    * host that omits this should expect a collection to render as an empty list.
    */
   resolveToken?: string | undefined;
+  /**
+   * URL of the body eraser (`@jxsuite/erase/browser`, built as its own file) on this origin. With
+   * it, the page fetches the eraser only when a function body is TypeScript (`spec.md` §23.1);
+   * without it, a typed body fails to compile and says so. This package never imports the eraser,
+   * so a host that cannot run it still loads this one.
+   */
+  eraserUrl?: string | undefined;
 }
 
 /** Escape a string for an HTML attribute value. */
@@ -64,16 +71,31 @@ 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(doc: JxDocument): string {
+function jsonPayload(doc: JxDocument | NonNullable<ComposedPage["formulas"]>): string {
   return JSON.stringify(doc).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 names = ["Jx"];
+  let setup = "";
+  if (options.resolveToken) {
+    names.push("setResolveToken");
+    setup += `\nsetResolveToken(${JSON.stringify(options.resolveToken)});`;
+  }
+  if (options.eraserUrl) {
+    names.push("setBodyEraserLoader");
+    setup += `\nsetBodyEraserLoader(() => import(${JSON.stringify(options.eraserUrl)}));`;
+  }
+  /* The project's formulas, for the components the page instantiates (spec.md §13.4). Set before
+     the render, in a block of their own for the reason the document has one. */
+  let formulas = "";
+  if (page.formulas) {
+    names.push("setProjectFormulas");
+    formulas = `\n<script type="application/json" id="jx-project-formulas">${jsonPayload(page.formulas)}</script>`;
+    setup += `\nsetProjectFormulas(JSON.parse(document.getElementById("jx-project-formulas").textContent));`;
+  }
+  const imports = names.join(", ");
   const style = options.styleUrl
     ? `\n  <link rel="stylesheet" href="${attr(options.styleUrl)}">`
     : "";
@@ -91,9 +113,9 @@ export function pageShell(page: ComposedPage, options: ShellOptions): string {
   <script>history.scrollRestoration = "manual";</script>
 </head>
 <body>
-<script type="application/json" id="jx-page-document">${jsonPayload(page.doc)}</script>
+<script type="application/json" id="jx-page-document">${jsonPayload(page.doc)}</script>${formulas}
 <script type="module">
-import { ${imports} } from "${attr(options.runtimeUrl)}";${setToken}
+import { ${imports} } from "${attr(options.runtimeUrl)}";${setup}
 const source = document.getElementById("jx-page-document").textContent;
 await Jx(JSON.parse(source), document.body, { base: ${JSON.stringify(options.base)} });
 </script>${client}