@jxsuite/compiler 6.1.0 → 8.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "6.1.0",
+  "version": "8.0.0",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {
@@ -17,6 +17,12 @@
     "dist"
   ],
   "type": "module",
+  "imports": {
+    "#bundler-backend": {
+      "bun": "./src/site/bundler-backend.bun.ts",
+      "default": "./src/site/bundler-backend.node.ts"
+    }
+  },
   "exports": {
     ".": "./src/compiler.ts",
     "./asset-mounts": "./src/site/asset-mounts.ts",
@@ -30,7 +36,8 @@
     "./site": "./src/site/site-build.ts",
     "./site-loader": "./src/site/site-loader.ts",
     "./types": "./src/types.ts",
-    "./db-push": "./src/site/db-push.ts"
+    "./db-push": "./src/site/db-push.ts",
+    "./bundler": "./src/site/bundler.ts"
   },
   "publishConfig": {
     "provenance": true
@@ -45,11 +52,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.5.0",
+    "@jxsuite/runtime": "^6.0.1",
+    "@jxsuite/schema": "^5.0.0",
+    "@jxsuite/site": "^2.2.2",
     "@vue/reactivity": "3.5.44",
     "esbuild": "^0.28.2",
     "lit-html": "^3.3.3",
@@ -57,8 +63,8 @@
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^21.0.4",
-    "@jxsuite/connector": "^0.8.0",
-    "@jxsuite/parser": "^4.1.0",
+    "@jxsuite/connector": "^0.8.2",
+    "@jxsuite/parser": "^4.1.2",
     "@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/bundler-backend.bun.ts

@@ -0,0 +1,84 @@
+/**
+ * The Bun bundler backend: `Bun.build` and `Bun.resolveSync`. Selected by the `bun` condition of
+ * `#bundler-backend` (`bundler-backend.ts`), so only a Bun process ever loads this file.
+ *
+ * `JX_BUNDLER=esbuild` hands every call to the esbuild backend instead, so a parity check can run
+ * both under one Bun.
+ */
+import { rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { BuildConfig } from "bun";
+import type { BackendBuild, BundleTargetName } from "./bundler-backend.ts";
+import { TRANSIENT_ENTRY_PREFIX } from "./bundler-backend.ts";
+import * as esbuildBackend from "./bundler-backend.node.ts";
+
+/** True when this process was told to bundle with esbuild instead. */
+function forcedToEsbuild(): boolean {
+  return process.env.JX_BUNDLER === "esbuild";
+}
+
+/** Which bundler this backend runs. */
+export function backendName(): "bun" | "esbuild" {
+  return forcedToEsbuild() ? "esbuild" : "bun";
+}
+
+/** Resolve a bare specifier as an import from a module in `fromDir`. Throws when it does not. */
+export function resolveBare(specifier: string, fromDir: string): string {
+  if (forcedToEsbuild()) {
+    return esbuildBackend.resolveBare(specifier, fromDir);
+  }
+  return Bun.resolveSync(specifier, fromDir);
+}
+
+/** Map a bundle target to Bun.build's target. */
+function bunTarget(target: BundleTargetName): "browser" | "node" | "bun" {
+  if (target === "workerd") {
+    return "browser";
+  }
+  return target;
+}
+
+/** Bundle one file with `Bun.build` and return the output's text. */
+async function buildFile(entryPath: string, request: BackendBuild): Promise<string> {
+  const config: BuildConfig = {
+    entrypoints: [entryPath],
+    external: request.external,
+    format: "esm",
+    minify: request.minify,
+    plugins: request.plugins,
+    target: bunTarget(request.target),
+    throw: false,
+  };
+  if (request.conditions) {
+    config.conditions = request.conditions;
+  }
+  if (request.define) {
+    config.define = request.define;
+  }
+  const result = await Bun.build(config);
+  if (!result.success || result.outputs.length === 0) {
+    const logs = result.logs.map(String).join("\n");
+    throw new Error(`Bun.build failed for ${entryPath}:\n${logs}`);
+  }
+  return result.outputs[0]!.text();
+}
+
+/** Bundle to one ESM module and return its text. Throws with the backend's diagnostics on failure. */
+export async function build(request: BackendBuild): Promise<string> {
+  if (forcedToEsbuild()) {
+    return esbuildBackend.build(request);
+  }
+  const { entry } = request;
+  if ("path" in entry) {
+    return buildFile(entry.path, request);
+  }
+  // Bun.build has no stdin input: write a transient entry in `resolveDir` so resolution matches
+  // The stdin/resolveDir behaviour, and always remove it.
+  const entryPath = join(entry.resolveDir, `${TRANSIENT_ENTRY_PREFIX}${process.pid}.mjs`);
+  writeFileSync(entryPath, entry.source, "utf8");
+  try {
+    return await buildFile(entryPath, request);
+  } finally {
+    rmSync(entryPath, { force: true });
+  }
+}

package/src/site/bundler-backend.node.ts

@@ -0,0 +1,58 @@
+/**
+ * The esbuild bundler backend: the default of `#bundler-backend` (`bundler-backend.ts`), so every
+ * runtime that is not Bun bundles with it, and Bun does too under `JX_BUNDLER=esbuild`.
+ */
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import type { BuildOptions } from "esbuild";
+import type { BackendBuild, BundleTargetName } from "./bundler-backend.ts";
+
+/** Which bundler this backend runs. */
+export function backendName(): "bun" | "esbuild" {
+  return "esbuild";
+}
+
+/** Resolve a bare specifier as an import from a module in `fromDir`. Throws when it does not. */
+export function resolveBare(specifier: string, fromDir: string): string {
+  return createRequire(join(fromDir, "package.json")).resolve(specifier);
+}
+
+/** Map a bundle target to esbuild's platform (conditions carry the workerd specifics). */
+function esbuildPlatform(target: BundleTargetName): "browser" | "node" {
+  return target === "node" || target === "bun" ? "node" : "browser";
+}
+
+/** Bundle to one ESM module and return its text. Throws with esbuild's diagnostics on failure. */
+export async function build(request: BackendBuild): Promise<string> {
+  // Dynamic import keeps esbuild (a native-binary dependency) off the load path until a bundle runs.
+  const esbuild = await import("esbuild");
+  const { entry } = request;
+  const options: BuildOptions = {
+    bundle: true,
+    external: request.external,
+    format: "esm",
+    logLevel: "silent",
+    minify: request.minify,
+    platform: esbuildPlatform(request.target),
+    plugins: request.plugins,
+    write: false,
+  };
+  if (request.conditions) {
+    options.conditions = request.conditions;
+  }
+  if (request.define) {
+    options.define = request.define;
+  }
+  if ("path" in entry) {
+    options.entryPoints = [entry.path];
+  } else {
+    options.stdin = {
+      contents: entry.source,
+      loader: "js",
+      resolveDir: entry.resolveDir,
+      sourcefile: "jx-entry.js",
+    };
+  }
+  const result = await esbuild.build({ ...options, write: false });
+  return result.outputFiles[0]!.text;
+}

package/src/site/bundler-backend.ts

@@ -0,0 +1,53 @@
+/**
+ * The contract between `bundler.ts` and the backend that does the bundling.
+ *
+ * The backend is chosen at **resolution time** by the `#bundler-backend` import's conditions
+ * (Node's conditional exports): `bundler-backend.bun.ts` under Bun, `bundler-backend.node.ts`
+ * (esbuild) everywhere else. A build of this package for Node therefore contains no Bun code at
+ * all, which is what lets the desktop backend run on Electron's Node (specs/desktop.md §7.1). Under
+ * Bun, `JX_BUNDLER=esbuild` still forces the esbuild backend for parity checks.
+ *
+ * `bundler.ts` owns everything both backends agree on (the defines, the minify default, the hook
+ * plugin); a backend owns only the call into its bundler and the spelling of its target.
+ */
+
+/** Resolution/runtime targets: client sidecars use "browser"; the site worker uses the rest. */
+export type BundleTargetName = "browser" | "node" | "bun" | "workerd";
+
+/**
+ * The part of a plugin builder the hooks use, typed so that both Bun's `PluginBuilder` and
+ * esbuild's `PluginBuild` are assignable to it: a plugin written against it is a plugin for either
+ * backend.
+ */
+export interface PluginBuild {
+  onResolve: (
+    options: { filter: RegExp },
+    callback: (args: {
+      path: string;
+      importer: string;
+    }) => { path: string; external: true } | undefined,
+  ) => void;
+  /** An `undefined` result hands the file back to the backend's own loader. */
+  onLoad: (options: { filter: RegExp }, callback: (args: { path: string }) => undefined) => void;
+}
+
+/** A plugin in the one shape both `Bun.build` and `esbuild.build` accept. */
+export interface BundlePlugin {
+  name: string;
+  setup: (build: PluginBuild) => void;
+}
+
+/** One bundle, with every option already decided by `bundler.ts`. */
+export interface BackendBuild {
+  /** A file to start from, or source text resolved as though it sat in `resolveDir`. */
+  entry: { path: string } | { source: string; resolveDir: string };
+  target: BundleTargetName;
+  external: string[];
+  conditions?: string[];
+  define?: Record<string, string>;
+  minify: boolean;
+  plugins: BundlePlugin[];
+}
+
+/** Basename prefix of the throwaway entry the Bun backend writes for a source entry. */
+export const TRANSIENT_ENTRY_PREFIX = ".jx-entry-";