@jxsuite/compiler 1.4.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {
@@ -46,16 +46,16 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^15.5.0",
-    "@jxsuite/create": "^1.2.1",
-    "@jxsuite/runtime": "^1.3.1",
-    "@jxsuite/schema": "^1.4.0",
+    "@jxsuite/create": "^1.2.2",
+    "@jxsuite/runtime": "^1.3.2",
+    "@jxsuite/schema": "^1.5.0",
     "esbuild": "^0.28.1",
     "sharp": "^0.35.3"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.11.1",
-    "@jxsuite/connector": "^0.4.1",
-    "@jxsuite/parser": "^1.4.0",
+    "@jxsuite/connector": "^0.4.2",
+    "@jxsuite/parser": "^1.4.1",
     "@types/mdast": "^4.0.4"
   }
 }

package/src/shared.ts

@@ -77,8 +77,133 @@ export function emitFormulaFn(def: { parameters?: unknown[] }, compiledBody: str
   }
   return `(..._a) => { const _args = { ${entries.join(", ")} }; return ${compiledBody}; }`;
 }
+
+/**
+ * Emit the import-clause binding for one Function-def `$src` entry.
+ *
+ * `$export` names the export inside the module and defaults to the state key (spec.md §5.3 4d).
+ * When the two differ the clause has to alias, because the local name the rest of the generated
+ * module calls is the state key — importing the bare key instead requests an export the module does
+ * not have, and the browser rejects the whole module at link time.
+ *
+ * Aliasing rather than renaming call sites is what makes the awkward cases work: two keys may alias
+ * the same export, a key may collide with another entry's export name, and `$export: "default"` is
+ * only reachable as `default as key`.
+ *
+ * @param {string} key - State key, and the local binding name
+ * @param {unknown} def - The Function definition
+ * @returns {string}
+ */
+export function srcImportBinding(key: string, def: unknown) {
+  const declared = (def as { $export?: unknown } | null | undefined)?.$export;
+  const exportName = typeof declared === "string" && declared !== "" ? declared : key;
+  return exportName === key ? key : `${exportName} as ${key}`;
+}
+
+/**
+ * Emit the auto-fetch `effect()` for a `$prototype: "Request"` state entry.
+ *
+ * Shared by the client and element targets so both honour `manual`, template URLs and
+ * `method`/`headers`/`body` the same way. They diverged once: the element target emitted no fetch
+ * at all, leaving every Request entry permanently `null` with nothing thrown.
+ *
+ * A template `url` is read inside the effect, so the fetch re-runs whenever the interpolated state
+ * changes; an URL that still interpolates to `undefined` is skipped rather than fetched.
+ *
+ * @param {string} key - State key receiving the response
+ * @param {JxPrototypeDef} def - The Request definition
+ * @param {{ statePrefix?: string; indent?: string; collect?: 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.
+ * @returns {string}
+ */
+export function emitRequestFetch(
+  key: string,
+  def: JxPrototypeDef,
+  opts: { statePrefix?: string; indent?: string; collect?: string } = {},
+) {
+  const { statePrefix = "state", indent = "", collect } = opts;
+  const { url } = def;
+  const isTemplateUrl = isTemplateString(url);
+  const method = def.method ?? "GET";
+
+  if (def.manual) {
+    return `${indent}// ${key}: manual Request — fetch triggered by user action`;
+  }
+
+  const lines: string[] = [
+    `// ${key}: auto-fetch from ${isTemplateUrl ? "(dynamic URL)" : url}`,
+    collect ? `${collect}.push(effect(() => {` : "effect(() => {",
+  ];
+
+  if (isTemplateUrl) {
+    lines.push(
+      `  const url = \`${withStatePrefix(url as string, statePrefix)}\`;`,
+      '  if (!url || url === "undefined" || url.includes("undefined")) return;',
+    );
+  } else {
+    lines.push(`  const url = ${JSON.stringify(url)};`);
+  }
+
+  const fetchOpts: string[] = [];
+  if (method !== "GET") {
+    fetchOpts.push(`method: ${JSON.stringify(method)}`);
+  }
+  if (def.headers) {
+    fetchOpts.push(`headers: ${JSON.stringify(def.headers)}`);
+  }
+  if (def.body) {
+    const bodyStr =
+      typeof def.body === "object"
+        ? JSON.stringify(JSON.stringify(def.body))
+        : JSON.stringify(def.body);
+    fetchOpts.push(`body: ${bodyStr}`);
+  }
+
+  const optsStr = fetchOpts.length > 0 ? `, { ${fetchOpts.join(", ")} }` : "";
+  lines.push(
+    `  fetch(url${optsStr})`,
+    "    .then(r => r.ok ? r.json() : Promise.reject(r.statusText))",
+    `    .then(d => { ${statePrefix}.${key} = d; })`,
+    `    .catch(e => { ${statePrefix}.${key} = { error: String(e) }; });`,
+    collect ? "}));" : "});",
+  );
+
+  return lines.map((line) => `${indent}${line}`).join("\n");
+}
+
+/**
+ * Rebase the bare `state.` reads in a template string onto `statePrefix`.
+ *
+ * Only the `${…}` interpolation holes are rewritten. A blanket replace would corrupt the literal
+ * text around them — `/api/state.json?q=${state.q}` would request `/api/this.state.json` — and the
+ * `\b` guard keeps an identifier that merely ends in `state` (`substate.z`) intact. Reads already
+ * carrying the prefix are left alone.
+ *
+ * @param {string} str
+ * @param {string} statePrefix
+ * @returns {string}
+ */
+function withStatePrefix(str: string, statePrefix: string) {
+  if (statePrefix === "state") {
+    return str;
+  }
+  return str.replaceAll(
+    /\$\{([^}]*)\}/g,
+    (_match: string, expr: string) =>
+      `\${${expr.replaceAll(/(?<!this\.)\bstate\./g, `${statePrefix}.`)}}`,
+  );
+}
 export type { ExpressionNode } from "@jxsuite/runtime/expression";
 
+/**
+ * Non-enumerable marker on a build-time scope listing the state keys that hold no build-time value.
+ * Non-enumerable so it stays out of `Object.entries(scope)` and out of template evaluation.
+ */
+const RUNTIME_ONLY_KEYS = Symbol("jx.runtimeOnlyStateKeys");
+
 // CDN defaults
 export const DEFAULT_REACTIVITY_SRC = "https://esm.sh/@vue/reactivity@3.5.40";
 export const DEFAULT_LIT_HTML_SRC = "https://esm.sh/lit-html@3.3.0";
@@ -275,6 +400,8 @@ export interface CompileContext {
   scope: Record<string, unknown>;
   scopeDefs: Record<string, unknown>;
   media: Record<string, string>;
+  /** True inside a `<pre>`-like subtree, where emitters must not indent nested children. */
+  preformatted?: boolean;
 }
 
 export function createCompileContext(
@@ -299,6 +426,18 @@ export function buildInitialScope(
   parentScope: Record<string, unknown> | null = null,
 ) {
   const scope = Object.create(parentScope ?? null) as Record<string, unknown>;
+  // Keys whose real value only exists after hydration, so prerender must not interpolate them —
+  // See `readsRuntimeOnlyState`. Seeded from the parent so nested scopes inherit the marks.
+  const inherited = (parentScope as Record<PropertyKey, unknown> | null)?.[RUNTIME_ONLY_KEYS];
+  const runtimeOnly = new Set<string>(inherited instanceof Set ? (inherited as Set<string>) : []);
+  // Attached up front, and mutated in place by the passes below, so the template pass at the end can
+  // Consult the marks the earlier passes added.
+  Object.defineProperty(scope, RUNTIME_ONLY_KEYS, {
+    configurable: true,
+    enumerable: false,
+    value: runtimeOnly,
+    writable: true,
+  });
 
   for (const [key, def] of Object.entries(defs)) {
     if (typeof def !== "object" || def === null || Array.isArray(def)) {
@@ -315,9 +454,13 @@ export function buildInitialScope(
     }
   }
 
+  // Template-string entries are deferred to a third pass: whether one is resolvable depends on the
+  // Runtime-only marks the loop below adds, and key order must not decide the answer.
+  const templateDefs: [string, string][] = [];
+
   for (const [key, def] of Object.entries(defs)) {
     if (typeof def === "string" && isTemplateString(def)) {
-      defineLazyScopeValue(scope, key, () => evaluateStaticTemplate(def, scope));
+      templateDefs.push([key, def]);
       continue;
     }
     if (!def || typeof def !== "object") {
@@ -359,18 +502,27 @@ export function buildInitialScope(
           void runStatements(body, s ?? scope, event ?? null);
         });
       } else if (typeof def.body === "string") {
-        const names = def.parameters ? paramNames(def.parameters) : (def.arguments ?? []);
+        const declared = def.parameters ? paramNames(def.parameters) : (def.arguments ?? []);
         const { body } = def;
-        const fn = new Function("state", ...names, body) as (
-          state: Record<string, unknown>,
-        ) => unknown;
+        // Declared names bind by name, not by position (spec.md §5.3 4d): a parameter literally
+        // Named `state` receives the scope, anything else receives the event. `state` is prepended
+        // When undeclared so a body may always reference it. Unconditionally prepending it instead —
+        // The older behaviour here — produced a duplicate parameter for the `["state", "event"]`
+        // Form that examples/components/task-manager.json uses, leaving `state` undefined.
+        const params = declared.includes("state") ? declared : ["state", ...declared];
+        const fn = new Function(...params, body) as (...args: unknown[]) => unknown;
+        const invoke = (state: Record<string, unknown>, event?: unknown) =>
+          fn(...params.map((name) => (name === "state" ? state : event)));
         if (bodyReturnsValue(body)) {
-          defineLazyScopeValue(scope, key, () => fn(scope));
+          defineLazyScopeValue(scope, key, () => invoke(scope));
         } else {
-          setOwnScopeValue(scope, key, fn);
+          setOwnScopeValue(scope, key, invoke);
         }
       } else {
+        // Bodyless `$src` Function — the real implementation is only loaded in the browser, so this
+        // Is a placeholder standing in for its callable shape, never its value.
         setOwnScopeValue(scope, key, () => {});
+        runtimeOnly.add(key);
       }
       continue;
     }
@@ -379,9 +531,24 @@ export function buildInitialScope(
       (def.$prototype === "LocalStorage" || def.$prototype === "SessionStorage")
     ) {
       setOwnScopeValue(scope, key, cloneValue(def.default ?? null));
+      continue;
+    }
+    if (isPrototypeDef(def) && def.$prototype === "Request") {
+      // A client-timing fetch has no build-time value at all — not even a placeholder.
+      runtimeOnly.add(key);
     }
   }
 
+  for (const [key, template] of templateDefs) {
+    // A state entry that interpolates a runtime-only key cannot resolve until hydration either, so
+    // It is runtime-only in turn. Without this, prerender would bake the failed evaluation (`null`)
+    // Into every template that reads *this* entry, one step removed from the original.
+    if (readsRuntimeOnlyState(template, scope)) {
+      runtimeOnly.add(key);
+    }
+    defineLazyScopeValue(scope, key, () => evaluateStaticTemplate(template, scope));
+  }
+
   return scope;
 }
 
@@ -465,12 +632,51 @@ export function resolveRefValue(refValue: unknown, scope: Record<string, unknown
   return scope[refValue] ?? null;
 }
 
+/**
+ * Detect whether a template string interpolates a state value that only exists after hydration.
+ *
+ * Evaluating one of those at build time is worse than leaving it alone. The build-time scope holds
+ * a `() => {}` placeholder for a bodyless `$src` Function and nothing at all for a `Request`, so
+ * the template resolves to text like `() => {}`, `undefined` or `""` — and that text _replaces_ the
+ * template in the emitted HTML, so the client-side binding is destroyed rather than merely wrong.
+ * Returning "unresolvable" instead leaves the template in place for the client to populate.
+ *
+ * A read that _calls_ the value is left alone: invoking a build-time callable is exactly how named
+ * formulas (spec.md §19.4c) are meant to be used during prerender.
+ *
+ * @param {string} str
+ * @param {Record<string, unknown>} scope
+ * @returns {boolean}
+ */
+function readsRuntimeOnlyState(str: string, scope: Record<string, unknown>) {
+  if (!scope) {
+    return false;
+  }
+  const runtimeOnly = (scope as Record<PropertyKey, unknown>)[RUNTIME_ONLY_KEYS];
+  for (const match of str.matchAll(/\bstate\.([A-Za-z_$][\w$]*)\s*(\()?/g)) {
+    if (match[2]) {
+      continue;
+    }
+    const key = match[1] as string;
+    if (runtimeOnly instanceof Set && runtimeOnly.has(key)) {
+      return true;
+    }
+    if (typeof scope[key] === "function") {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * @param {string} str
  * @param {Record<string, unknown>} scope
  * @returns {unknown}
  */
 export function evaluateStaticTemplate(str: string, scope: Record<string, unknown>) {
+  if (readsRuntimeOnlyState(str, scope)) {
+    return null;
+  }
   try {
     const singleExprMatch = str.match(/^\$\{(.+)\}$/s);
     if (singleExprMatch) {
@@ -613,6 +819,26 @@ export function buildAttrs(def: JxElement | JxMutableNode, scope: Record<string,
   return out;
 }
 
+/**
+ * Tags rendered with `white-space: pre` by every UA, where inter-element whitespace is content
+ * rather than formatting. Emitters indent nested children for readability; inside these tags — and
+ * anywhere below them, since `white-space` inherits — that indentation would render as literal
+ * blank lines and leading spaces, so children must be concatenated with no separator.
+ */
+export const PREFORMATTED_TAGS = new Set(["pre", "textarea", "listing", "plaintext", "xmp"]);
+
+/**
+ * The separator to place between an element's compiled children: none inside a preformatted
+ * subtree, a newline plus `indent` elsewhere.
+ *
+ * @param {boolean | undefined} preformatted
+ * @param {string} [indent]
+ * @returns {string}
+ */
+export function childSeparator(preformatted: boolean | undefined, indent = "  "): string {
+  return preformatted ? "" : `\n${indent}`;
+}
+
 /**
  * Build the inner HTML (textContent or children) for a node.
  *
@@ -622,6 +848,7 @@ export function buildAttrs(def: JxElement | JxMutableNode, scope: Record<string,
  *   scope: Record<string, unknown>;
  *   scopeDefs: Record<string, unknown>;
  *   media: Record<string, string>;
+ *   preformatted?: boolean;
  * }} context
  * @param {(def: unknown, raw: unknown, context: unknown) => string} childCompiler
  * @returns {string}
@@ -633,6 +860,7 @@ export function buildInner(
     scope: Record<string, unknown> | null;
     scopeDefs: Record<string, unknown>;
     media: Record<string, string>;
+    preformatted?: boolean;
   },
   childCompiler: (def: unknown, raw: unknown, context: unknown) => string,
 ) {
@@ -652,7 +880,7 @@ export function buildInner(
         const childRaw = (rawChildren as (JxElement | string)[] | undefined)?.[i] ?? c;
         return childCompiler(c, childRaw, context);
       })
-      .join("\n  ");
+      .join(childSeparator(context.preformatted));
   }
   return "";
 }

package/src/site/schema-command.ts

@@ -3,12 +3,16 @@
  *
  * Composes the per-project entry documents (project.schema.json and document.schema.json) from the
  * core schemas and each enabled extension's shipped fragments, then writes them into the project
- * root as committed, SELF-CONTAINED bundles: every fragment ref is resolved through
- * {@link bundleSchema}, embedding the core + fragment resources under `$defs` keyed by their
- * canonical `$id`s. Relative `./node_modules/...` refs only resolve through Node module resolution,
- * which editors do not perform (hoisted workspaces leave projects without their own node_modules) —
- * the bundled form resolves offline for ajv `jx validate`, VS Code's JSON language service, and the
- * studio's Monaco alike, with one resolution behavior for all consumers.
+ * root as committed, SELF-CONTAINED, SINGLE-RESOURCE schemas: every fragment ref is resolved
+ * through {@link bundleSchema} (embedding the core + fragment resources under `$defs`) and then
+ * collapsed by {@link flattenSchema}, which drops the embedded `$id`s and rewrites every ref to a
+ * root-relative JSON Pointer. Both passes are needed for one resolution behavior across all
+ * consumers: relative `./node_modules/...` refs only resolve through Node module resolution, which
+ * editors do not perform (hoisted workspaces leave projects without their own node_modules), while
+ * `$id`-scoped refs inside a compound document resolve only in a fully compliant validator — VS
+ * Code's JSON language service and Monaco resolve `#/...` against the document root and fetch
+ * anything with a URI before the `#` over the network. Root pointers are what ajv, the language
+ * service, and Monaco all agree on.
  */
 
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -16,8 +20,8 @@ import { createRequire } from "node:module";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import {
   bundleSchema,
-  emitDocumentSchema,
-  emitProjectSchema,
+  composeProjectSchemas,
+  flattenSchema,
 } from "@jxsuite/schema/project-schemas";
 import { buildProjectExtensionRegistry } from "./format-host.ts";
 import { loadProjectConfig } from "./site-loader.ts";
@@ -37,44 +41,22 @@ export async function writeProjectSchemas(projectRoot: string) {
   const { config } = loadProjectConfig(projectRoot);
   const registry = await buildProjectExtensionRegistry(projectRoot, config);
 
-  const corePath = coreSchemaRef(projectRoot, CORE_PROJECT_SPECIFIER);
-  const fragments: string[] = [];
-  const pathsValueRefs: string[] = [];
-  const fieldSchemaRefs: string[] = [];
-  for (const ext of registry.extensions) {
-    const projectFragment = ext.schemas.project;
-    if (projectFragment) {
-      fragments.push(fragmentRef(projectRoot, ext, projectFragment));
-    }
-    const documentFragment = ext.schemas.document;
-    if (documentFragment) {
-      pathsValueRefs.push(...fragmentDefsRefs(documentFragment));
-    }
-    // The `schemas.fields` manifest convention: a fragment whose $defs members are extension
-    // Field extras, unioned into the per-project field resource (specs/extensions.md §5.3).
-    const fieldsFragment = ext.schemas.fields;
-    if (fieldsFragment) {
-      fieldSchemaRefs.push(...fragmentDefsRefs(fieldsFragment));
-      fragments.push(fragmentRef(projectRoot, ext, fieldsFragment));
-    }
-  }
-
-  // Bundle before committing: the emitted relative refs are an intermediate form only.
+  /* Composition itself is host-agnostic (@jxsuite/schema `composeProjectSchemas`) — the filesystem
+     appears only in what this host contributes: project-relative refs for the fragments the
+     registry resolved, and a loader restricted to the project root. The cloud session composes the
+     same two documents from bundled artifacts through the same function. */
   const root = resolve(projectRoot);
-  const loadJson = restrictedSchemaLoader(root);
-  const projectSchema = await bundleSchema(
-    emitProjectSchema({ corePath, fieldSchemaRefs, fragments }),
-    loadJson,
-    root,
-  );
-  const documentSchema = await bundleSchema(
-    emitDocumentSchema({
-      corePath: coreSchemaRef(projectRoot, CORE_DOCUMENT_SPECIFIER),
-      pathsValueRefs,
-    }),
-    loadJson,
-    root,
-  );
+  const { document: documentSchema, project: projectSchema } = await composeProjectSchemas({
+    baseDir: root,
+    coreDocumentRef: coreSchemaRef(projectRoot, CORE_DOCUMENT_SPECIFIER),
+    coreProjectRef: coreSchemaRef(projectRoot, CORE_PROJECT_SPECIFIER),
+    extensions: registry.extensions.map((ext) => ({
+      document: ext.schemas.document && fragmentRef(projectRoot, ext, ext.schemas.document),
+      fields: ext.schemas.fields && fragmentRef(projectRoot, ext, ext.schemas.fields),
+      project: ext.schemas.project && fragmentRef(projectRoot, ext, ext.schemas.project),
+    })),
+    loadJson: restrictedSchemaLoader(root),
+  });
 
   const projectSchemaPath = resolve(projectRoot, "project.schema.json");
   const documentSchemaPath = resolve(projectRoot, "document.schema.json");
@@ -115,16 +97,16 @@ export async function readBundledProjectSchemas(projectRoot: string) {
   }
 
   const loadJson = restrictedSchemaLoader(root);
-  const project = await bundleSchema(
-    JSON.parse(readFileSync(projectSchemaPath, "utf8")) as Record<string, unknown>,
-    loadJson,
-    root,
-  );
-  const document = await bundleSchema(
-    JSON.parse(readFileSync(documentSchemaPath, "utf8")) as Record<string, unknown>,
-    loadJson,
-    root,
-  );
+  const projectFile = JSON.parse(readFileSync(projectSchemaPath, "utf8")) as Record<
+    string,
+    unknown
+  >;
+  const documentFile = JSON.parse(readFileSync(documentSchemaPath, "utf8")) as Record<
+    string,
+    unknown
+  >;
+  const project = flattenSchema(await bundleSchema(projectFile, loadJson, root));
+  const document = flattenSchema(await bundleSchema(documentFile, loadJson, root));
   return { document, project };
 }
 
@@ -231,25 +213,3 @@ function projectRelativeRef(projectRoot: string, absPath: string, conventional:
   }
   return rel.startsWith("./") ? rel : `./${rel}`;
 }
-
-/**
- * Canonical "uri#/pointer" refs into a fragment's `$defs` shapes: one per `$defs` entry, addressed
- * by the fragment's own `$id` (refs inside the entry document's embeds resolve against canonical
- * URIs, never file locations). Serves both the document paths union and the fields-extras union.
- *
- * @param {string} fragmentPath - Resolved absolute fragment path
- * @returns {string[]}
- */
-function fragmentDefsRefs(fragmentPath: string): string[] {
-  let fragment: { $id?: unknown; $defs?: Record<string, unknown> };
-  try {
-    fragment = JSON.parse(readFileSync(fragmentPath, "utf8")) as typeof fragment;
-  } catch {
-    return [];
-  }
-  const { $id } = fragment;
-  if (typeof $id !== "string" || !fragment.$defs) {
-    return [];
-  }
-  return Object.keys(fragment.$defs).map((name) => `${$id}#/$defs/${name}`);
-}

package/src/site/site-build.ts

@@ -256,20 +256,44 @@ export async function buildSite(
     const componentOutDir = resolve(outDir, "components");
     mkdirSync(componentOutDir, { recursive: true });
 
+    // Emitted modules are named after the component's `tagName` — the name the page's loader
+    // `<script>` and the CSS sidecar both use. So a component whose source basename differs from
+    // Its tag needs its `$elements` imports renamed to match, and those get resolved before the
+    // Dependency itself is compiled. Hence: read every component's tag up front.
+    const componentTagByPath = new Map<string, string>();
+    for (const file of componentFiles) {
+      const componentPath = resolve(componentsDir, file);
+      try {
+        const { tagName: depTag } = await readPageDocument(componentPath, formatRegistry);
+        if (depTag) {
+          componentTagByPath.set(componentPath, depTag);
+        }
+      } catch {
+        // Left to the compile pass below, which reports the parse failure with its file context.
+      }
+    }
+
     for (const file of componentFiles) {
       try {
         const componentPath = resolve(componentsDir, file);
         const result = await compileElement(componentPath, {
           ...(projectConfig.$media ? { $media: projectConfig.$media } : {}),
           formats: formatRegistry,
+          resolveElementPath: (refPath: string, currentDir: string | null) => {
+            const depPath = currentDir ? resolve(currentDir, refPath) : resolve(refPath);
+            const depTag = componentTagByPath.get(depPath);
+            return depTag ? `./${depTag}.js` : refPath.replace(/\.json$/, ".js");
+          },
           rewriteSrc: rewriteSidecarSrc,
         });
         for (const f of result.files) {
-          // Reduce the emitted path (an absolute source path with .json swapped to .js) to a bare
-          // Filename for the dist/components/ output. basename handles both / and \ — a
-          // Forward-slash-only split left the full drive path on Windows, so resolve() then wrote
-          // The sidecar back into the source tree instead of dist.
-          const outName = basename(f.path);
+          // Name the output after the tag. `injectComponentScripts` emits
+          // `<script src="/components/<tag>.js">` and the CSS sidecar is written as `<tag>.css`, so
+          // A source basename here left the loader pointing at a file that was never written.
+          // Basename is the fallback, and handles both / and \ — a forward-slash-only split left
+          // The full drive path on Windows, so resolve() then wrote the sidecar back into the
+          // Source tree instead of dist.
+          const outName = f.tagName ? `${f.tagName}.js` : basename(f.path);
           writeFileSync(resolve(componentOutDir, outName), f.content, "utf8");
           if (f.tagName) {
             compiledComponentTags.push(f.tagName);
@@ -366,6 +390,7 @@ export async function buildSite(
           compiledComponentTags,
           componentCSS,
           staticTags,
+          result.files.map((f: { content: string }) => f.content).join("\n"),
         );
       }
 
@@ -1151,9 +1176,14 @@ function resolveDocTemplates(node: JxElement | string, scope: Record<string, unk
   }
   const rawChildren = node.children;
   // Legacy whole-children repeater: expand the items into the node's static children.
+  // Only when the expansion actually produced nodes. `expandMappedArrayStatic` returns `null` when
+  // `items` cannot be resolved at build time and `[]` when it resolves to an empty array — and `[]`
+  // Is truthy, so an empty build-time list used to replace the repeater with nothing, discarding the
+  // Definition the client needed. There is no prerendered output to preserve in that case, so the
+  // Repeater is left in place for the client to bind (a page containing one is never zero-JS).
   if (isMappedArray(rawChildren)) {
     const expanded = expandMappedArrayStatic(rawChildren, scope);
-    if (expanded) {
+    if (expanded && expanded.length > 0) {
       node.children = expanded;
       return;
     }
@@ -1183,10 +1213,11 @@ function resolveDocTemplates(node: JxElement | string, scope: Record<string, unk
           continue;
         }
       }
-      // Array pseudo-element among siblings: expand its items in place.
+      // Array pseudo-element among siblings: expand its items in place, on the same
+      // Produced-nothing rule as the whole-children branch above.
       if (isMappedArray(child)) {
         const expanded = expandMappedArrayStatic(child, scope);
-        if (expanded) {
+        if (expanded && expanded.length > 0) {
           node.children.splice(i, 1, ...expanded);
           i += expanded.length;
           continue;
@@ -1351,6 +1382,7 @@ function expandComponents(
  * @param {string[]} allComponentTags - All compiled component tag names
  * @param {Map<string, string>} [cssMap] - TagName → CSS text (for link injection)
  * @param {Set<string>} [staticTags] - Tags where ALL instances are fully static (skip JS)
+ * @param {string} [islandSource] - Concatenated island modules emitted for this page
  * @returns {string}
  */
 function injectComponentScripts(
@@ -1358,11 +1390,15 @@ function injectComponentScripts(
   allComponentTags: string[],
   cssMap = new Map<string, string>(),
   staticTags = new Set<string>(),
+  islandSource = "",
 ) {
-  // Find which components are actually referenced in this page
-  const usedTags = allComponentTags.filter(
-    (tag: string) => html.includes(`<${tag}`), // Matches <tag> and <tag ...>
-  );
+  // A component reaches a page two ways: as a literal tag in the static HTML, or referenced only
+  // From inside an island's client template — in which case the tag exists solely in the island's
+  // Compiled JS and never in the HTML the page ships. Searching the HTML alone missed the second
+  // Kind entirely, so its module was never loaded and the element sat in the DOM un-upgraded.
+  const inHtml = (tag: string) => html.includes(`<${tag}`); // Matches <tag> and <tag ...>
+  const inIsland = (tag: string) => islandSource.includes(`<${tag}`);
+  const usedTags = allComponentTags.filter((tag: string) => inHtml(tag) || inIsland(tag));
   if (usedTags.length === 0) {
     return html;
   }
@@ -1377,8 +1413,11 @@ function injectComponentScripts(
     result = result.replace("</head>", `  ${cssLinks}\n</head>`);
   }
 
-  // Only inject JS for components that have non-static instances
-  const jsTags = usedTags.filter((tag: string) => !staticTags.has(tag));
+  // Only inject JS for components that have non-static instances. An island-rendered instance is
+  // Never prerendered, so it needs its module even when the component itself is fully static —
+  // That module is what fills the element in client-side. This holds when the tag ALSO appears in
+  // The static HTML: those instances are prerendered, but the ones the island creates are not.
+  const jsTags = usedTags.filter((tag: string) => inIsland(tag) || !staticTags.has(tag));
   if (jsTags.length === 0) {
     return result;
   }