@jxsuite/site 2.6.0 → 2.8.0

package/README.md

@@ -2,7 +2,7 @@
 
 **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.
+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 a native addon 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/site",
-  "version": "2.6.0",
+  "version": "2.8.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": {
@@ -34,7 +34,7 @@
     "test:coverage": "bun test --isolate --coverage"
   },
   "dependencies": {
-    "@jxsuite/runtime": "^6.3.0",
-    "@jxsuite/schema": "^5.6.0"
+    "@jxsuite/runtime": "^7.1.0",
+    "@jxsuite/schema": "^6.0.2"
   }
 }

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/routes.ts

@@ -9,9 +9,9 @@
  * another.
  *
  * It lives HERE rather than in `@jxsuite/compiler` for the reason `resolveI18n` does (`i18n.ts`):
- * the compiler's dependency graph carries `sharp` and `esbuild`, so neither a browser bundle nor a
- * Cloudflare Worker can import it. This module is pure string math with no imports at all, so every
- * host that has to know what `/blog/:slug` means can share one answer.
+ * the compiler's dependency graph carries a native addon and `esbuild`, so neither a browser bundle
+ * nor a Cloudflare Worker can import it. This module is pure string math with no imports at all, so
+ * every host that has to know what `/blog/:slug` means can share one answer.
  */
 
 /** Bracket route segments: `[param]` (named) and `[...param]` (catch-all). */

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

@@ -71,7 +71,7 @@ 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`);
 }
 
@@ -87,6 +87,14 @@ export function pageShell(page: ComposedPage, options: ShellOptions): string {
     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)}">`
@@ -105,7 +113,7 @@ 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)}";${setup}
 const source = document.getElementById("jx-page-document").textContent;

package/src/site-style.ts

@@ -29,6 +29,10 @@
  * to differ was a nested element key, on the belief that "the document's own style pass covers page
  * content": nothing else reads `project.json#/style`, so the canvas simply dropped a site's
  * typography and link rules while the build kept them (#296).
+ *
+ * A block's `$description` is the one thing only the build renders: a static build writes it as a
+ * comment above the rule (`{ comments: true }`, spec.md §9.2), and a host never does, because every
+ * consumer but a static build ignores the description.
  */
 
 import {
@@ -36,11 +40,12 @@ import {
   buildStyleRules,
   isDeclarationAtRule,
   isKeyframesAtRule,
+  commentedRuleText,
   isNestedSelectorKey,
   pureSchemeOf,
 } from "@jxsuite/runtime/css";
 import type { CssBuildOptions } from "@jxsuite/runtime/css";
-import { isNonNullObject } from "@jxsuite/schema/guards";
+import { isNonNullObject, isString } from "@jxsuite/schema/guards";
 import type { JxRef, JxStyle } from "@jxsuite/schema/types";
 
 /** Id of the injected site-style tag (replace-in-place, never accumulate). */
@@ -76,9 +81,29 @@ export interface SiteStyleRoots {
   body: string;
 }
 
+/** What a caller may ask of the sheet beyond its rules. */
+export interface SiteStyleOptions {
+  /**
+   * Write each described rule's `$description` as a comment on the line above it. The static
+   * build's switch: the canvas and the live preview leave it off and emit the rule text alone.
+   */
+  comments?: boolean;
+}
+
 /** The page's own root and body. */
 export const PAGE_ROOTS: SiteStyleRoots = { body: "body", root: ":root" };
 
+/**
+ * Hand a block's own `$description` to the first rule its split writes: the root's when it holds a
+ * declaration, the body's otherwise. A block that writes neither rule carries no comment.
+ */
+function describeFirstRule(block: JxStyle, root: JxStyle, body: JxStyle): void {
+  const description = block["$description"];
+  if (isString(description)) {
+    (Object.keys(root).length > 0 ? root : body)["$description"] = description;
+  }
+}
+
 /**
  * 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
@@ -104,6 +129,7 @@ export const PAGE_ROOTS: SiteStyleRoots = { body: "body", root: ":root" };
  *   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
+ * @param {SiteStyleOptions} [options] - `comments: true` is the static build's form
  * @returns {string}
  * @docs studio/interface/canvas
  */
@@ -113,19 +139,20 @@ export function buildSiteStyleCSS(
   transpose: (value: string) => string,
   resolveValue?: SiteStyleValueResolver,
   roots: SiteStyleRoots = PAGE_ROOTS,
+  options: SiteStyleOptions = {},
 ): string {
   const rules: string[] = [];
   const push = (style: JxStyle, selector: string | null) => {
-    const options: CssBuildOptions = { mediaQueries, scope: selector, transposeValue: transpose };
+    const build: 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);
+      build.resolveValue = (property, value) => resolveValue(property, value, selector);
     }
-    for (const rule of buildStyleRules(style, options)) {
-      rules.push(rule.text);
+    for (const rule of buildStyleRules(style, build)) {
+      rules.push(options.comments === true ? commentedRuleText(rule) : rule.text);
     }
   };
 
@@ -157,7 +184,8 @@ export function buildSiteStyleCSS(
       }
       continue;
     }
-    if (isNestedSelectorKey(key) || key.startsWith("@")) {
+    // Metadata is no declaration; the block's own `$description` is placed after the split.
+    if (isNestedSelectorKey(key) || key.startsWith("@") || key.startsWith("$")) {
       continue;
     }
     /* Custom properties go to `:root`; so does `color-scheme`, which is the one non-custom
@@ -172,6 +200,8 @@ export function buildSiteStyleCSS(
     }
   }
 
+  describeFirstRule(siteStyle, rootProps, bodyProps);
+
   // Base rules precede conditional blocks so equal-specificity overrides win by source order.
   push(rootProps, roots.root);
   push(bodyProps, roots.body);
@@ -206,12 +236,16 @@ export function buildSiteStyleCSS(
         }
         continue;
       }
+      if (k.startsWith("$")) {
+        continue;
+      }
       if (k.startsWith("--")) {
         condRoot[k] = v;
       } else {
         condBody[k] = v;
       }
     }
+    describeFirstRule(block, condRoot, condBody);
     push({ [atKey]: condRoot }, roots.root);
     push({ [atKey]: condBody }, roots.body);
     for (const [sel, sub] of condSubs) {