@jxsuite/compiler 6.1.0 → 8.0.0

package/src/site/bundler.ts

@@ -2,20 +2,30 @@
  * Bundler.js — timing-aware module bundling for compiled sites
  *
  * One backend abstraction serving every bundling need of the build (spec.md §12, compiler.md):
- * client-timing `$src` sidecars today, the server worker in a follow-up. Backend selection is
- * runtime-adaptive: `Bun.build` when the build runs under Bun, esbuild (dynamically imported) under
- * plain Node. Options are kept minimal and identical across backends so output stays as stable as
- * possible; set `JX_BUNDLER=esbuild` to force the fallback (e.g. for parity checks).
+ * client-timing `$src` sidecars today, the server worker in a follow-up. The backend is chosen at
+ * resolution time by the `#bundler-backend` import (`bundler-backend.ts`): `Bun.build` under Bun,
+ * esbuild everywhere else, so a Node build of this module carries no Bun code. Options are kept
+ * minimal and identical across backends so output stays as stable as possible; set
+ * `JX_BUNDLER=esbuild` to force esbuild under Bun (e.g. for parity checks).
  *
  * `timing: "compiler"` code is never bundled — it executes in the build host via the extension
  * registry's `importImplementation` path.
  */
 
 import { rmSync, writeFileSync } from "node:fs";
-import { createRequire } from "node:module";
 import { tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import { isNpmSpecifier, NPM_SPECIFIER_PREFIX } from "@jxsuite/schema/asset-paths";
+import * as backend from "#bundler-backend";
+import type {
+  BackendBuild,
+  BundlePlugin,
+  BundleTargetName,
+  PluginBuild,
+} from "./bundler-backend.ts";
+import { TRANSIENT_ENTRY_PREFIX } from "./bundler-backend.ts";
+
+export type { BundleTargetName } from "./bundler-backend.ts";
 
 /** Import specifiers left external in client bundles — provided by the page importmap. */
 export const CLIENT_EXTERNALS = ["@vue/reactivity", "lit-html"];
@@ -29,11 +39,11 @@ export function isBundleableSrc(specifier: string): boolean {
 }
 
 /**
- * True when the Node code path (createRequire resolution, esbuild backend) should be used: always
- * under plain Node, or when `JX_BUNDLER=esbuild` forces it for parity checks.
+ * True when the esbuild backend is the one bundling: always outside Bun, or when
+ * `JX_BUNDLER=esbuild` forces it for parity checks.
  */
 export function useNodeFallback(): boolean {
-  return typeof Bun === "undefined" || process.env.JX_BUNDLER === "esbuild";
+  return backend.backendName() === "esbuild";
 }
 
 /**
@@ -47,15 +57,19 @@ export function resolveSidecarEntry(
   projectRoot: string,
 ): string {
   if (isNpmSpecifier(specifier)) {
-    const bare = specifier.slice(NPM_SPECIFIER_PREFIX.length);
-    if (useNodeFallback()) {
-      return createRequire(join(projectRoot, "package.json")).resolve(bare);
-    }
-    return Bun.resolveSync(bare, projectRoot);
+    return backend.resolveBare(specifier.slice(NPM_SPECIFIER_PREFIX.length), projectRoot);
   }
   return resolve(docDir, specifier);
 }
 
+/**
+ * Resolve a bare specifier as an import from a module in `fromDir`, through the active backend's
+ * resolver. Throws when it does not resolve.
+ */
+export function resolveBareSpecifier(specifier: string, fromDir: string): string {
+  return backend.resolveBare(specifier, fromDir);
+}
+
 export interface BundleRequest {
   /** Absolute path of the module to bundle. */
   entryPath: string;
@@ -63,9 +77,6 @@ export interface BundleRequest {
   outfile: string;
 }
 
-/** Resolution/runtime targets: client sidecars use "browser"; the site worker uses the rest. */
-export type BundleTargetName = "browser" | "node" | "bun" | "workerd";
-
 /**
  * A resolution hook, in the one shape both backends accept.
  *
@@ -110,26 +121,6 @@ export interface BundleOptions {
   onFileLoaded?: (path: string) => void;
 }
 
-/**
- * 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.
- */
-interface PluginBuild {
-  onResolve: (
-    options: { filter: RegExp },
-    callback: (args: { path: string; importer: string }) => ReturnType<BundleResolver["resolve"]>,
-  ) => 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. */
-interface BundlePlugin {
-  name: string;
-  setup: (build: PluginBuild) => void;
-}
-
 /** Wrap the hooks as the one-plugin array both backends take. */
 function hookPlugins(opts: BundleOptions): BundlePlugin[] {
   const { onFileLoaded, resolver } = opts;
@@ -213,17 +204,15 @@ function sharedResolution(opts: BundleOptions): SharedResolution {
   return shared;
 }
 
-/** 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";
-}
-
-/** Map a bundle target to Bun.build's target. */
-function bunTarget(target: BundleTargetName): "browser" | "node" | "bun" {
-  if (target === "workerd") {
-    return "browser";
-  }
-  return target;
+/** Every option {@link BundleOptions} decides, in the shape a backend takes. */
+function backendOptions(opts: BundleOptions): Omit<BackendBuild, "entry"> {
+  return {
+    ...sharedResolution(opts),
+    external: opts.external ?? [],
+    minify: shouldMinify(opts),
+    plugins: hookPlugins(opts),
+    target: opts.target,
+  };
 }
 
 /**
@@ -231,46 +220,19 @@ function bunTarget(target: BundleTargetName): "browser" | "node" | "bun" {
  * diagnostics on failure.
  */
 export async function bundleEntry(request: BundleRequest, opts: BundleOptions): Promise<void> {
-  const external = opts.external ?? [];
-  const plugins = hookPlugins(opts);
-
-  if (useNodeFallback()) {
-    // Dynamic import keeps esbuild (a native-binary dependency) out of Bun-run builds entirely.
-    const esbuild = await import("esbuild");
-    await esbuild.build({
-      bundle: true,
-      ...sharedResolution(opts),
-      entryPoints: [request.entryPath],
-      external,
-      format: "esm",
-      logLevel: "silent",
-      minify: shouldMinify(opts),
-      outfile: request.outfile,
-      platform: esbuildPlatform(opts.target),
-      plugins,
-    });
-    return;
-  }
-
-  const result = await Bun.build({
-    ...sharedResolution(opts),
-    entrypoints: [request.entryPath],
-    external,
-    format: "esm",
-    minify: shouldMinify(opts),
-    plugins,
-    target: bunTarget(opts.target),
-    throw: false,
-  });
-  if (!result.success || result.outputs.length === 0) {
-    const logs = result.logs.map(String).join("\n");
-    throw new Error(`Bun.build failed for ${request.entryPath}:\n${logs}`);
-  }
-  writeFileSync(request.outfile, await result.outputs[0]!.text(), "utf8");
+  const code = await backend.build({ entry: { path: request.entryPath }, ...backendOptions(opts) });
+  writeFileSync(request.outfile, code, "utf8");
 }
 
-/** Basename prefix of the throwaway entry {@link bundleSource} writes for the Bun backend. */
-const TRANSIENT_ENTRY_PREFIX = ".jx-entry-";
+/**
+ * Bundle one entry module and return the code rather than writing it.
+ *
+ * For a host serving modules on demand (the dev server's and the desktop project server's bare
+ * specifier routes, the live preview's runtime): what it needs is the text for a response body.
+ */
+export async function bundleToString(entryPath: string, opts: BundleOptions): Promise<string> {
+  return backend.build({ entry: { path: entryPath }, ...backendOptions(opts) });
+}
 
 /**
  * True for the throwaway entry a {@link bundleSource} call is bundling, under either backend.
@@ -328,31 +290,8 @@ export async function bundleSource(
   { resolveDir, outfile }: { resolveDir: string; outfile: string },
   opts: BundleOptions,
 ): Promise<void> {
-  if (useNodeFallback()) {
-    const esbuild = await import("esbuild");
-    await esbuild.build({
-      bundle: true,
-      ...sharedResolution(opts),
-      external: opts.external ?? [],
-      format: "esm",
-      logLevel: "silent",
-      minify: shouldMinify(opts),
-      outfile,
-      platform: esbuildPlatform(opts.target),
-      stdin: { contents: source, loader: "js", resolveDir, sourcefile: "jx-entry.js" },
-    });
-    return;
-  }
-
-  // Bun.build has no stdin input — write a transient entry in `resolveDir` so resolution matches
-  // The stdin/resolveDir behavior, and always remove it.
-  const entryPath = join(resolveDir, `${TRANSIENT_ENTRY_PREFIX}${process.pid}.mjs`);
-  writeFileSync(entryPath, source, "utf8");
-  try {
-    await bundleEntry({ entryPath, outfile }, opts);
-  } finally {
-    rmSync(entryPath, { force: true });
-  }
+  const code = await backend.build({ entry: { resolveDir, source }, ...backendOptions(opts) });
+  writeFileSync(outfile, code, "utf8");
 }
 
 /**

package/src/site/client-runtime.ts

@@ -16,14 +16,13 @@
  */
 
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
-import { createRequire } from "node:module";
 import { dirname, join, relative, resolve } from "node:path";
 import type { BundleResolver } from "./bundler.ts";
 import {
   bundleSource,
   isTransientEntry,
+  resolveBareSpecifier,
   resolveThroughBundler,
-  useNodeFallback,
 } from "./bundler.ts";
 import { DEFAULT_LIT_HTML_SRC, DEFAULT_REACTIVITY_SRC } from "../shared.ts";
 import { isJsonObject, isNonNullObject, isString } from "@jxsuite/schema/guards";
@@ -230,18 +229,14 @@ export function renderImportMap(imports: Record<string, string>): string {
 /**
  * True when a bare specifier resolves from `resolveDir` under either backend.
  *
- * The backend choice is `bundler.ts`'s to make, not a second inline `typeof Bun` check: resolution
- * and bundling must agree about which one they are on, or the import map promises a module the
- * bundle then fails to produce.
+ * The backend's own resolver answers, not a second inline choice: resolution and bundling must
+ * agree about which one they are on, or the import map promises a module the bundle then fails to
+ * produce.
  */
 function canResolve(specifier: string, resolveDir: string): boolean {
   try {
-    // Both resolvers throw when the specifier does not resolve, and return its path when it does.
-    if (useNodeFallback()) {
-      createRequire(join(resolveDir, "x.js")).resolve(specifier);
-    } else {
-      Bun.resolveSync(specifier, resolveDir);
-    }
+    // The resolver throws when the specifier does not resolve, and returns its path when it does.
+    resolveBareSpecifier(specifier, resolveDir);
     return true;
   } catch {
     return false;

package/src/site/format-host.ts

@@ -62,7 +62,23 @@ export async function importImplementation(path: string): Promise<Implementation
   throw lastError instanceof Error ? lastError : new Error(String(lastError));
 }
 
-/** Create a node FormatHostIO rooted at a project (bare specifiers resolve via node_modules). */
+/**
+ * Resolve a bare specifier from the PROJECT's own node_modules, and nowhere else.
+ *
+ * There is deliberately no host fallback (specs/extensions.md §3). Extensions, first-party ones
+ * included, reach a project only through its own install, the way a third-party extension must: a
+ * host that answered for `@jxsuite/parser` would let a project missing that dependency edit on one
+ * machine and fail to build on the next.
+ *
+ * @param {string} projectRoot
+ * @param {string} specifier - Bare specifier, e.g. "@jxsuite/parser/jx-extension.json"
+ * @returns {string} Absolute resolved path
+ */
+export function resolveFromProject(projectRoot: string, specifier: string): string {
+  return createRequire(resolve(projectRoot, "package.json")).resolve(specifier);
+}
+
+/** Create a node FormatHostIO rooted at a project (bare specifiers resolve from its node_modules). */
 export function createNodeFormatIO(projectRoot: string): FormatHostIO {
   return {
     importModule: (path) => importImplementation(path),
@@ -74,75 +90,39 @@ export function createNodeFormatIO(projectRoot: string): FormatHostIO {
       if (isAbsolute(ref)) {
         return ref;
       }
-      // Bare specifier — prefer the project's own node_modules, then fall back to the host's
-      // Resolution (the desktop app and dev server ship @jxsuite/parser, so format classes work
-      // Even when the project's dependencies are not installed).
-      const projRequire = createRequire(resolve(projectRoot, "package.json"));
-      try {
-        return projRequire.resolve(ref);
-      } catch {
-        const selfRequire = createRequire(import.meta.url);
-        return selfRequire.resolve(ref);
-      }
+      return resolveFromProject(projectRoot, ref);
     },
   };
 }
 
-/**
- * Where an extension package's manifest resolves from — the two answers `createNodeFormatIO`
- * merges.
- */
+/** Where an extension package's manifest resolves from the project, if it does. */
 export interface ExtensionResolution {
-  /** Resolvable from the PROJECT's own node_modules. */
+  /** Resolvable from the PROJECT's own node_modules — the only place an extension resolves from. */
   project: boolean;
-  /** Resolvable from the HOST's module graph — `createNodeFormatIO`'s fallback branch. */
-  host: boolean;
-  /** The manifest path from whichever probe answered; the project wins, matching resolution order. */
+  /** The resolved manifest path, when `project` is true. */
   manifestPath?: string;
 }
 
 /**
- * Split `createNodeFormatIO`'s two-branch resolution into its two ANSWERS.
- *
- * The IO deliberately collapses them (project first, then host) because a caller loading a class
- * only needs the file. A catalogue needs them apart: "the project installed this" and "this host
- * ships it" are different affordances — install-then-enable versus enable — and a surface that
- * cannot tell them apart offers the wrong one.
+ * Probe whether a project resolves an extension package, without loading it.
  *
  * Probes the MANIFEST rather than the package directory, because the manifest is what the registry
  * resolves (see `loadExtension`): a package present in node_modules whose `exports` map omits
  * `./jx-extension.json` is one whose enablement would throw, so it must not read as resolvable.
  *
- * @param {string} projectRoot - The project whose node_modules is tried first
+ * @param {string} projectRoot - The project whose node_modules is probed
  * @param {string} name - Bare package specifier, e.g. "@jxsuite/parser"
  * @returns {ExtensionResolution}
  */
 export function probeExtension(projectRoot: string, name: string): ExtensionResolution {
-  const ref = `${name}/${EXTENSION_MANIFEST}`;
-  let manifestPath: string | undefined;
-
-  let project = false;
-  try {
-    manifestPath = createRequire(resolve(projectRoot, "package.json")).resolve(ref);
-    project = true;
-  } catch {
-    // Not installed in the project. The host probe below decides whether it resolves at all.
-  }
-
-  let host = false;
   try {
-    const fromHost = createRequire(import.meta.url).resolve(ref);
-    host = true;
-    manifestPath ??= fromHost;
+    return {
+      manifestPath: resolveFromProject(projectRoot, `${name}/${EXTENSION_MANIFEST}`),
+      project: true,
+    };
   } catch {
-    // Not shipped by this host either.
+    return { project: false };
   }
-
-  const resolution: ExtensionResolution = { host, project };
-  if (manifestPath !== undefined) {
-    resolution.manifestPath = manifestPath;
-  }
-  return resolution;
 }
 
 /** Build the extension registry for a project from its project.json `extensions` array. */
@@ -157,6 +137,76 @@ export async function buildProjectExtensionRegistry(
   );
 }
 
+/** A registry of what a project has installed, and the enabled packages it has not. */
+export interface InstalledExtensionRegistry {
+  registry: ExtensionRegistry;
+  /** Bare specifiers `project.json` enables whose manifest the project does not resolve. */
+  missing: string[];
+}
+
+/**
+ * Build the registry an EDITOR needs: every enabled extension the project resolves, skipping the
+ * package ones it has not installed yet.
+ *
+ * A build must fail on a missing extension, and does, through {@link buildProjectExtensionRegistry}.
+ * A studio must not: a project opened before its install has run resolves none of its package
+ * extensions, and the format list, the extensions panel and the class picker should answer with
+ * what is there rather than with an error. `missing` says what was skipped, so the host can say so
+ * once instead of logging a resolution stack per request. Relative (local) extensions are never
+ * skipped, because no install produces them.
+ *
+ * @param {string} projectRoot
+ * @param {ProjectConfig} [projectConfig]
+ * @returns {Promise<InstalledExtensionRegistry>}
+ */
+export async function buildInstalledExtensionRegistry(
+  projectRoot: string,
+  projectConfig?: ProjectConfig,
+): Promise<InstalledExtensionRegistry> {
+  const missing: string[] = [];
+  const present: string[] = [];
+  for (const specifier of projectConfig?.extensions ?? []) {
+    const local = specifier.startsWith("./") || specifier.startsWith("../");
+    if (local || probeExtension(projectRoot, specifier).project) {
+      present.push(specifier);
+    } else {
+      missing.push(specifier);
+    }
+  }
+  const registry = await buildExtensionRegistry(
+    present,
+    createNodeFormatIO(projectRoot),
+    resolve(projectRoot, "project.json"),
+  );
+  return { missing, registry };
+}
+
+/**
+ * Whether any of a previous build's `missing` packages resolves now — the cache check a host runs
+ * so that a registry built before an install does not outlive it.
+ *
+ * @param {string} projectRoot
+ * @param {string[]} missing
+ * @returns {boolean}
+ */
+export function anyNowInstalled(projectRoot: string, missing: string[]): boolean {
+  return missing.some((specifier) => probeExtension(projectRoot, specifier).project);
+}
+
+/**
+ * The one line a host logs for the packages {@link buildInstalledExtensionRegistry} skipped.
+ *
+ * @param {string[]} missing
+ * @returns {string}
+ */
+export function missingExtensionsNotice(missing: string[]): string {
+  const names = missing.map((m) => `"${m}"`).join(", ");
+  return (
+    `project.json enables ${names}, which this project has not installed, so ` +
+    `${missing.length === 1 ? "it is" : "they are"} not loaded. Install the project's dependencies.`
+  );
+}
+
 // ─── Studio extensions payload ────────────────────────────────────────────────
 
 /** One project-section contribution on the studio wire (specs/extensions.md §9/§9.1). */

package/src/site/image-cache.ts

@@ -52,30 +52,56 @@ export function _testSetNpmCacheBase(value: string | null) {
   _npmCacheBase = value;
 }
 
+/**
+ * How long the npm probe may run before the build stops waiting and caches in the project.
+ *
+ * `npm config get cache` answers in a fraction of a second, but nothing bounded it, and the call is
+ * synchronous: when npm hung, the first build of the process hung with it. On a CI runner it
+ * stalled past both of the dev server's 5 s and 20 s test timeouts with nothing to show for it but
+ * "killed 1 dangling process". Missing the npm cache only costs persistence across builds.
+ */
+const NPM_PROBE_TIMEOUT_MS = 3000;
+
+/**
+ * Where npm keeps its cache, or null when npm cannot say.
+ *
+ * Npm reads its configuration from the environment as well as from `.npmrc`, and the environment
+ * wins, so a value there is npm's own answer and no process is needed to ask for it. A script run
+ * by a package manager usually has it there.
+ */
+function npmCacheBase(): string | null {
+  const fromEnv = process.env.npm_config_cache ?? process.env.NPM_CONFIG_CACHE;
+  if (fromEnv) {
+    return fromEnv;
+  }
+  try {
+    const result = execSync("npm config get cache", {
+      cwd: tmpdir(), // Avoid ENOWORKSPACES when cwd is inside an npm workspace
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: NPM_PROBE_TIMEOUT_MS,
+    }).trim();
+    return result && result !== "undefined" ? result : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Return the image cache directory for a project.
  *
  * Prefers the npm global cache (`npm config get cache`) so CI environments that cache ~/.npm (e.g.
  * Cloudflare Pages) automatically persist optimized images across builds. Falls back to
- * .cache/images inside the project root when npm is unavailable.
+ * .cache/images inside the project root when npm is unavailable or does not answer in time.
  *
- * Result is memoized — `npm config get cache` is only spawned once per process.
+ * Result is memoized — npm is asked at most once per process.
  *
  * @param {string} projectRoot
  * @returns {string}
  */
 export function getImageCacheDir(projectRoot: string): string {
   if (_npmCacheBase === undefined) {
-    try {
-      const result = execSync("npm config get cache", {
-        cwd: tmpdir(), // Avoid ENOWORKSPACES when cwd is inside an npm workspace
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "ignore"],
-      }).trim();
-      _npmCacheBase = result && result !== "undefined" ? result : null;
-    } catch {
-      _npmCacheBase = null;
-    }
+    _npmCacheBase = npmCacheBase();
   }
   if (_npmCacheBase) {
     return resolve(_npmCacheBase, "jxsuite-images", basename(projectRoot));

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;
+}