@jxsuite/compiler 6.1.0 → 7.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "6.1.0",
+  "version": "7.0.0",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {
@@ -45,11 +45,10 @@
     "upgrade": "bun update --latest && bun install"
   },
   "dependencies": {
-    "@apidevtools/json-schema-ref-parser": "^16.0.5",
-    "@jxsuite/create": "^1.4.0",
-    "@jxsuite/runtime": "^5.2.0",
-    "@jxsuite/schema": "^4.0.0",
-    "@jxsuite/site": "^2.2.0",
+    "@jxsuite/create": "^1.4.1",
+    "@jxsuite/runtime": "^6.0.0",
+    "@jxsuite/schema": "^4.1.0",
+    "@jxsuite/site": "^2.2.1",
     "@vue/reactivity": "3.5.44",
     "esbuild": "^0.28.2",
     "lit-html": "^3.3.3",
@@ -57,8 +56,8 @@
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^21.0.4",
-    "@jxsuite/connector": "^0.8.0",
-    "@jxsuite/parser": "^4.1.0",
+    "@jxsuite/connector": "^0.8.1",
+    "@jxsuite/parser": "^4.1.1",
     "@jxsuite/test-support": "^0.0.0",
     "@types/mdast": "^4.0.4"
   }

package/src/compiler.ts

@@ -6,7 +6,6 @@
  * - Fully static → compile-static.js (plain HTML/CSS, zero JS)
  * - Custom element (-) → compile-element.js (lit-html web component)
  * - Dynamic (standard) → compile-client.js (pre-rendered HTML + reactive bindings)
- * - Server → compile-server.js (Hono server handler)
  *
  * Usage (CLI): `bun packages/compiler/src/compile-cli.js <source.json> [output.html]`
  *
@@ -23,7 +22,6 @@ import {
   isDynamic,
   tagNameToClassName,
 } from "./shared.ts";
-import { compileServer } from "./targets/compile-server.ts";
 
 import { emitElementModule } from "./targets/compile-element.ts";
 import { compileStaticPage } from "./targets/compile-static.ts";
@@ -35,7 +33,7 @@ import type { FormatRegistry } from "@jxsuite/schema/format-registry";
 
 // Re-exports for consumers
 export { isDynamic } from "./shared.ts";
-export { compileServer, compileSiteServer } from "./targets/compile-server.ts";
+export { compileSiteServer } from "./targets/compile-server.ts";
 export { compileElement, compileElementPage } from "./targets/compile-element.ts";
 export { compileClient } from "./targets/compile-client.ts";
 
@@ -49,6 +47,11 @@ export interface CompileOptions {
   formats?: FormatRegistry;
   /** Rewrite Function-def `$src` specifiers to served URLs (see CompileElementOptions). */
   rewriteSrc?: (specifier: string) => string;
+  /**
+   * The route prefix a `timing: "server"` entry posts to, deployment base included
+   * (`serverRoutePrefix`). Default `"/_jx/server"`, for a site served from its origin root.
+   */
+  serverBaseUrl?: string;
   /**
    * Inject the color-scheme pre-paint script when `$media` declares a pure scheme query (default
    * true). The site pipeline disables this and injects via the merged <head> instead.
@@ -132,7 +135,14 @@ export async function compile(sourcePath: string | JxDocument, opts: CompileOpti
   if (raw.tagName && raw.tagName.includes("-")) {
     const { tagName } = raw;
     const className = tagNameToClassName(tagName);
-    const moduleContent = emitElementModule(raw, className, [], opts.rewriteSrc);
+    const moduleContent = emitElementModule(
+      raw,
+      className,
+      [],
+      opts.rewriteSrc,
+      null,
+      opts.serverBaseUrl,
+    );
     const moduleFile = {
       content: moduleContent,
       path: `${tagName}.js`,
@@ -166,13 +176,17 @@ export async function compile(sourcePath: string | JxDocument, opts: CompileOpti
   }
 
   // Route 3: Dynamic with standard tagName → pre-rendered HTML + reactive bindings
-  return compileClient(raw, {
+  const clientOptions: Parameters<typeof compileClient>[1] = {
     litHtmlSrc,
     projectStyle,
     reactivitySrc,
     ...pageTargetOverrides(opts),
     title,
-  });
+  };
+  if (opts.serverBaseUrl !== undefined) {
+    clientOptions.serverBaseUrl = opts.serverBaseUrl;
+  }
+  return compileClient(raw, clientOptions);
 }
 
 /**
@@ -197,7 +211,7 @@ function pageTargetOverrides(opts: CompileOptions): PageTargetOverrides {
  * @param {string} [out]
  */
 export async function runCli(src: string, out?: string) {
-  const [result, server] = await Promise.all([compile(src), compileServer(src)]);
+  const result = await compile(src);
   const { writeFileSync, mkdirSync } = await import("node:fs");
   const { dirname, join } = await import("node:path");
   if (out) {
@@ -213,9 +227,4 @@ export async function runCli(src: string, out?: string) {
   } else {
     process.stdout.write(result.html);
   }
-  if (server && out) {
-    const serverOut = out.replace(/(\.[^.]+)?$/, "-server.js");
-    writeFileSync(serverOut, /** @type {string} */ server, "utf8");
-    console.error(`Server handler written to ${serverOut}`);
-  }
 }

package/src/shared.ts

@@ -23,7 +23,8 @@ import {
   isSingleExpression,
   splitSelectorList,
 } from "@jxsuite/runtime";
-import { evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
+import { spliceNestingSelector } from "@jxsuite/runtime/css";
+import { compileOperandSource, evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
 import { runStatements } from "@jxsuite/runtime/statements";
 import { buildSiteStyleCSS } from "@jxsuite/site/site-style";
 import {
@@ -52,7 +53,7 @@ import {
 import type { TagNameSlot } from "@jxsuite/schema/guards";
 import { resolveShadowMode, styleScopePrefix } from "./shadow.ts";
 import type { ShadowMode } from "./shadow.ts";
-import { readPath } from "@jxsuite/runtime/pointer";
+import { escapeToken, objectKey, readPath, refAccessor } from "@jxsuite/runtime/pointer";
 import type { JxScope } from "@jxsuite/runtime/types";
 import type {
   CemParameter,
@@ -63,6 +64,7 @@ import type {
   JxMutableNode,
   JxPrototypeDef,
   JxRef,
+  JxServerFnDef,
   JxStateDefinition,
   JxStyle,
   ProjectConfig,
@@ -258,6 +260,84 @@ export function emitRequestFetch(
   return lines.map((line) => `${indent}${line}`).join("\n");
 }
 
+/**
+ * A `$ref` scheme that names something only a loop, an event or a formula has. A state entry sits
+ * in none of those scopes, so lowering one would emit an identifier nothing declares.
+ */
+const SERVER_CALL_REFUSED_REFS = ["$map/", "event#/", "$args/", "$reduce/"];
+
+/**
+ * Emit the call a `timing: "server"` state entry makes to its route in the site worker (compiler.md
+ * §6.1): a `POST <serverBaseUrl>/<export>` whose JSON body is the entry's `arguments`, the answer
+ * written to the entry's state key.
+ *
+ * Shared by the client and element targets, as `emitRequestFetch` is, so one rule decides what an
+ * answer, a failure and a superseded call each do. A literal argument is sent as written. A
+ * top-level `$ref` argument is lowered by the runtime's own table (`compileOperandSource`) and read
+ * inside an `effect()`, so the call repeats when it changes. Only the latest call may write: a
+ * sequence number drops the answer to a call whose arguments have since moved on, because aborting
+ * a `POST` does not stop the function that is already running on the server. A non-2xx answer is
+ * never stored: the entry keeps its last value and the error goes to the console naming the
+ * export.
+ *
+ * @param {string} key - State key receiving the answer
+ * @param {JxServerFnDef} def - The server entry
+ * @param {{ statePrefix?: string; indent?: string; collect?: string; serverBaseUrl?: string }} [opts] -
+ *   `statePrefix` is the expression the emitted code assigns through (`state` for the client module
+ *   scope, `this.state` inside a custom element); `indent` prefixes every emitted line; `collect`,
+ *   when given, is an array expression the effect runner is pushed onto so the caller can `stop()`
+ *   it on teardown; `serverBaseUrl` is the route prefix, deployment base included.
+ * @returns {string}
+ */
+export function emitServerCall(
+  key: string,
+  def: JxServerFnDef,
+  opts: { statePrefix?: string; indent?: string; collect?: string; serverBaseUrl?: string } = {},
+): string {
+  const { statePrefix = "state", indent = "", collect, serverBaseUrl = "/_jx/server" } = opts;
+  const url = JSON.stringify(`${serverBaseUrl}/${def.$export}`);
+
+  const written = Object.entries(def.arguments ?? {});
+  const args = written.map(([name, value]) => {
+    if (!isRef(value)) {
+      return `${objectKey(name)}: ${JSON.stringify(value)}`;
+    }
+    if (SERVER_CALL_REFUSED_REFS.some((prefix) => value.$ref.startsWith(prefix))) {
+      throw new Error(
+        `Server function "${key}": argument "${name}" references "${value.$ref}", which a state ` +
+          `entry cannot read. Use a #/state/, parent#/, window#/ or document#/ reference.`,
+      );
+    }
+    return `${objectKey(name)}: ${compileOperandSource({ $ref: value.$ref }, { statePrefix })}`;
+  });
+  // Any top-level reference makes the call reactive: it is read inside an effect, so it repeats.
+  const reactive = written.some(([, value]) => isRef(value));
+  const call = `${SERVER_CALL_HELPER}(${url}, ${args.length > 0 ? `{ ${args.join(", ")} }` : "{}"})`;
+  const target = refAccessor(statePrefix, escapeToken(key));
+  const failed = `console.error(${JSON.stringify(`Jx server function ${def.$export}:`)}, e)`;
+
+  const lines = reactive
+    ? [
+        `// ${key}: server function ${def.$export}, called again when an argument changes`,
+        "{",
+        "  let _jxSeq = 0;",
+        collect ? `  ${collect}.push(effect(() => {` : "  effect(() => {",
+        "    const _seq = ++_jxSeq;",
+        `    ${call}`,
+        `      .then((d) => { if (_seq === _jxSeq) ${target} = d; })`,
+        `      .catch((e) => { if (_seq === _jxSeq) ${failed}; });`,
+        collect ? "  }));" : "  });",
+        "}",
+      ]
+    : [
+        `// ${key}: server function ${def.$export}, called once`,
+        call,
+        `  .then((d) => { ${target} = d; })`,
+        `  .catch((e) => { ${failed}; });`,
+      ];
+  return lines.map((line) => `${indent}${line}`).join("\n");
+}
+
 /**
  * Rebase the bare `state.` reads in a template string onto `statePrefix`.
  *
@@ -624,6 +704,12 @@ export function buildInitialScope(
       setOwnScopeValue(scope, key, cloneValue(def.default));
       continue;
     }
+    if (isServerFnDef(def)) {
+      // Its value is an answer from the site worker. Storing the definition object instead would
+      // Let a template that reads it bake `{ $src, $export, timing }` into the page.
+      runtimeOnly.add(key);
+      continue;
+    }
     if (!def.$prototype && !("$expression" in def) && !isSchemaOnlyDef(def)) {
       setOwnScopeValue(scope, key, cloneValue(def));
     }
@@ -1282,6 +1368,39 @@ export function attrHelperSource(): string {
   );
 }
 
+/** The name of the call helper a module holding a `timing: "server"` entry declares once. */
+export const SERVER_CALL_HELPER = "__jxServerCall";
+
+/**
+ * The request a compiled server-function call makes, as source for a generated module's preamble
+ * (compiler.md §6.1), declared once per module and called by every `emitServerCall` block in it.
+ *
+ * The response rule lives here, in one place: the body is read as text and parsed when it is not
+ * empty, so a function that returns nothing answers `null`; a non-2xx answer rejects with the
+ * parsed body's `error`, else the body text, else the status text. A body that is not JSON only
+ * matters on success, where it is a defect worth surfacing, and a failure still reports its text.
+ *
+ * @returns {string} One `async function` declaration.
+ */
+export function serverCallHelperSource(): string {
+  return [
+    `async function ${SERVER_CALL_HELPER}(url, args) {`,
+    "  const r = await fetch(url, {",
+    "    method: 'POST',",
+    "    headers: { 'Content-Type': 'application/json' },",
+    "    body: JSON.stringify(args),",
+    "  });",
+    "  const text = await r.text();",
+    "  let body = null;",
+    "  if (text !== '') {",
+    "    try { body = JSON.parse(text); } catch (e) { if (r.ok) throw e; }",
+    "  }",
+    "  if (!r.ok) throw new Error((body && body.error) || text || r.statusText);",
+    "  return body;",
+    "}",
+  ].join("\n");
+}
+
 /** The capture helper a light-DOM component module calls before its first render. */
 export const SLOT_CAPTURE_HELPER = "__jxCaptureSlotted";
 
@@ -1625,24 +1744,27 @@ function _walkSrc(def: JxElement | JxMutableNode | string, srcs: Set<string>) {
 }
 
 /**
- * Recursively collect all `timing: "server"` entries from the document tree.
+ * Recursively collect all `timing: "server"` entries from the document tree: one record per entry,
+ * in walk order (the root's `state` keys, then `children` depth-first). Nothing is deduplicated, so
+ * two keys naming one export are both listed; which of them a handler serves is the caller's rule
+ * (compiler.md §6.3).
  *
  * @param {JxElement} doc
  * @returns {{ key: string; exportName: string; src: string }[]}
  */
 export function collectServerEntries(doc: JxElement) {
-  const entries = new Map<string, { key: string; exportName: string; src: string }>();
+  const entries: { key: string; exportName: string; src: string }[] = [];
   _walkServerEntries(doc, entries);
-  return [...entries.values()];
+  return entries;
 }
 
 /**
  * @param {JxElement | JxMutableNode | string} def
- * @param {Map<string, { key: string; exportName: string; src: string }>} entries
+ * @param {{ key: string; exportName: string; src: string }[]} entries
  */
 function _walkServerEntries(
   def: JxElement | JxMutableNode | string,
-  entries: Map<string, { key: string; exportName: string; src: string }>,
+  entries: { key: string; exportName: string; src: string }[],
 ) {
   if (!isNonNullObject(def)) {
     return;
@@ -1650,7 +1772,7 @@ function _walkServerEntries(
   if (def.state) {
     for (const [key, d] of Object.entries(def.state)) {
       if (isServerFnDef(d)) {
-        entries.set(d.$export, { exportName: d.$export, key, src: d.$src });
+        entries.push({ exportName: d.$export, key, src: d.$src });
       }
     }
   }
@@ -2346,8 +2468,9 @@ function resolveSelector(prop: string, scope: string): string {
 
 /** One member of {@link resolveSelector}'s list against the scope. */
 function resolveSelectorMember(prop: string, scope: string): string {
-  if (prop.startsWith("&")) {
-    return prop.replaceAll("&", scope);
+  const spliced = spliceNestingSelector(prop, scope);
+  if (spliced !== null) {
+    return spliced;
   }
   if (prop.startsWith(":host")) {
     const inner = /^:host\((.*)\)$/.exec(prop)?.[1];

package/src/site/layout-resolver.ts

@@ -12,11 +12,14 @@ import { existsSync, readFileSync } from "node:fs";
 import { errorMessage, parseJxDocument } from "@jxsuite/schema/parse";
 import { resolve } from "node:path";
 import { resolveLayout as resolveLayoutWith } from "@jxsuite/site/layout";
-import type { LayoutLoader } from "@jxsuite/site/layout";
 import type { JxDocument, ProjectConfig } from "@jxsuite/schema/types";
 
-/** A {@link LayoutLoader} over the project's own directory. */
-export function nodeLayoutLoader(projectRoot: string): LayoutLoader {
+/**
+ * A layout loader (`LayoutLoader` in `@jxsuite/site/layout`) over the project's own directory. It
+ * reads synchronously, which is what lets {@link layoutChain} walk a chain without awaiting each
+ * level, and a synchronous loader is still one `resolveLayout` accepts.
+ */
+export function nodeLayoutLoader(projectRoot: string): (layoutRef: string) => JxDocument {
   return (layoutRef: string) => {
     const layoutPath = resolve(projectRoot, layoutRef);
     if (!existsSync(layoutPath)) {
@@ -47,3 +50,40 @@ export function resolveLayout(
 ): Promise<JxDocument> {
   return resolveLayoutWith(pageDoc, projectConfig, nodeLayoutLoader(projectRoot));
 }
+
+/**
+ * Every layout a page is wrapped in, innermost first, each with the absolute path it was read from.
+ *
+ * The chain {@link resolveLayout} follows: the page's `$layout`, else `defaults.layout`, then each
+ * layout's own `$layout`. A reference that is not a non-empty string ends it, which is how
+ * `"$layout": false` opts a page out, and so does a layout already in the chain, so a layout that
+ * names itself is listed once rather than followed forever.
+ *
+ * It exists for what the merged document no longer says: which file declared what. Resolution
+ * merges state and splices children, so a relative path a layout wrote is relative to the layout's
+ * own file, and only the chain still names that file.
+ *
+ * @param {JxDocument} pageDoc - The raw page document
+ * @param {ProjectConfig} projectConfig - Site configuration (for defaults.layout)
+ * @param {string} projectRoot - Project root directory, which every `$layout` is relative to
+ * @returns {{ path: string; doc: JxDocument }[]} Each layout's absolute path and document
+ */
+export function layoutChain(
+  pageDoc: JxDocument,
+  projectConfig: ProjectConfig,
+  projectRoot: string,
+): { path: string; doc: JxDocument }[] {
+  const load = nodeLayoutLoader(projectRoot);
+  const chain: { path: string; doc: JxDocument }[] = [];
+  let ref = pageDoc.$layout ?? projectConfig.defaults?.layout;
+  while (ref) {
+    const path = resolve(projectRoot, ref);
+    if (chain.some((level) => level.path === path)) {
+      break;
+    }
+    const doc = load(ref);
+    chain.push({ doc, path });
+    ref = doc.$layout;
+  }
+  return chain;
+}

package/src/site/server-entries.ts

@@ -0,0 +1,118 @@
+/**
+ * Server-entries.ts — where the site worker's `timing: "server"` entries come from.
+ *
+ * Every document that can declare a server entry is read as written: the page, each layout in its
+ * chain, `project.json`'s `state` (which every page inherits) and every compiled component
+ * (compiler.md §6.3, site-architecture.md §14.1.1). The merged page cannot stand in for them,
+ * because layout resolution merges state and splices children, and after that nothing records which
+ * file a relative `$src` was written against.
+ *
+ * A relative `$src` (`./`, `../`) resolves against the directory of the document that declares it,
+ * and the worker receives it as a `./` path from the project root, because the worker bundle
+ * resolves every import from there (compiler.md §12). Any other specifier, a package export most
+ * often, is kept as written and resolves from the root unchanged.
+ *
+ * Each entry is served at `/_jx/server/<export>`, so an export name is one function across the
+ * whole site. One module that several documents declare is one route; two different modules
+ * exporting one name cannot both be served, and a page calling the one left out would silently
+ * receive the other's answer, so that is an error rather than a choice made for the author.
+ *
+ * @docs framework/site/deployment
+ */
+
+import { dirname, relative, resolve, sep } from "node:path";
+import { collectServerEntries } from "../shared.ts";
+import type { JxElement } from "@jxsuite/schema/types";
+
+/** One `timing: "server"` entry as one document declares it, before deduplication. */
+export interface ServerEntryRecord {
+  /** The `$export`: the name the worker imports and the route it registers it under. */
+  exportName: string;
+  /** The specifier the worker imports, resolvable from the project root. */
+  src: string;
+  /** The declaring document, project-relative with `/` separators (`layouts/base.json`). */
+  declaredIn: string;
+}
+
+/** What {@link dedupeServerEntries} hands the site worker: its routes, and a message for each clash. */
+export interface DedupedServerEntries {
+  /** One entry per export name, the `{ exportName, src }` pairs `compileSiteServer` imports. */
+  entries: { exportName: string; src: string }[];
+  /** One message per export name that two or more different modules claim. */
+  errors: string[];
+}
+
+/** `path` relative to the project root, with `/` separators whatever the platform's own. */
+function projectRelative(path: string, projectRoot: string): string {
+  return relative(projectRoot, path).split(sep).join("/");
+}
+
+/**
+ * The specifier the worker imports for a `$src` written in a document under `docDir`.
+ *
+ * A `./` or `../` path is resolved against `docDir` and returned as a `./` path from the project
+ * root, in POSIX form so the generated import is valid on every platform. Anything else is returned
+ * as written.
+ */
+export function resolveServerSrc(src: string, docDir: string, projectRoot: string): string {
+  if (!src.startsWith("./") && !src.startsWith("../")) {
+    return src;
+  }
+  return `./${projectRelative(resolve(docDir, src), projectRoot)}`;
+}
+
+/**
+ * Every server entry one document declares, in document order, each `src` resolved against the
+ * document's own directory and each record naming the document.
+ */
+export function documentServerEntries(
+  doc: JxElement,
+  docPath: string,
+  projectRoot: string,
+): ServerEntryRecord[] {
+  const docDir = dirname(docPath);
+  const declaredIn = projectRelative(docPath, projectRoot);
+  return collectServerEntries(doc).map((entry) => ({
+    exportName: entry.exportName,
+    src: resolveServerSrc(entry.src, docDir, projectRoot),
+    declaredIn,
+  }));
+}
+
+/**
+ * One entry per export name, the list the site worker serves, plus one error per export name that
+ * two or more different modules claim.
+ *
+ * Export names keep the order they were first seen in. A name declared by several documents for the
+ * same module is one entry and no message. A name two modules claim keeps the first module, so the
+ * worker can still be written, and its error names every module with the first document that
+ * declared it.
+ */
+export function dedupeServerEntries(records: readonly ServerEntryRecord[]): DedupedServerEntries {
+  // Export name → each distinct module claiming it → the first document declaring that module.
+  const claims = new Map<string, Map<string, string>>();
+  for (const { exportName, src, declaredIn } of records) {
+    const modules = claims.get(exportName) ?? new Map<string, string>();
+    claims.set(exportName, modules);
+    if (!modules.has(src)) {
+      modules.set(src, declaredIn);
+    }
+  }
+
+  const entries: { exportName: string; src: string }[] = [];
+  const errors: string[] = [];
+  for (const [exportName, modules] of claims) {
+    const claimed = [...modules];
+    entries.push({ exportName, src: claimed[0]![0] });
+    if (claimed.length > 1) {
+      const named = claimed.map(([src, declaredIn]) => `${src} (declared in ${declaredIn})`);
+      errors.push(
+        `Server function "${exportName}" is exported by ${claimed.length} different modules: ` +
+          `${named.join(", ")}. The site worker serves one function per export name, at ` +
+          `/_jx/server/${exportName}, so a call meant for any but the first would get the first's ` +
+          `answer. Rename the export in all but one module, and the $export that names it.`,
+      );
+    }
+  }
+  return { entries, errors };
+}