@jxsuite/compiler 0.28.5 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/compiler",
-  "version": "0.28.5",
+  "version": "0.29.0",
   "description": "Jx static HTML compiler, island detector, and site builder",
   "license": "MIT",
   "repository": {
@@ -35,6 +35,7 @@
   "scripts": {
     "prepare": "bun build src/compiler.ts src/cli.ts --outdir=dist --format=esm --minify --target=node",
     "build": "bun run prepare",
+    "build:metafile": "bun build src/compiler.ts src/cli.ts --outdir=dist --format=esm --minify --target=node --metafile=metafile.json",
     "build:site": "bun src/cli.ts build",
     "test": "bun test --isolate",
     "test:coverage": "bun test --isolate --coverage",
@@ -42,9 +43,9 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^15.3.6",
-    "@jxsuite/parser": "^0.28.5",
-    "@jxsuite/runtime": "^0.28.5",
-    "@jxsuite/schema": "^0.28.5",
+    "@jxsuite/parser": "^0.29.0",
+    "@jxsuite/runtime": "^0.29.0",
+    "@jxsuite/schema": "^0.29.0",
     "sharp": "^0.35.1"
   },
   "devDependencies": {

package/src/compiler.ts

@@ -22,13 +22,9 @@ import {
   isDynamic,
   tagNameToClassName,
 } from "./shared.ts";
-import { compileServer, compileSiteServer } from "./targets/compile-server.ts";
+import { compileServer } from "./targets/compile-server.ts";
 
-import {
-  compileElement,
-  compileElementPage,
-  emitElementModule,
-} from "./targets/compile-element.ts";
+import { emitElementModule } from "./targets/compile-element.ts";
 import { compileStaticPage } from "./targets/compile-static.ts";
 import { compileClient } from "./targets/compile-client.ts";
 import { isClassDef } from "@jxsuite/schema/guards";
@@ -37,14 +33,10 @@ import type { JxDocument, JxStyle } from "@jxsuite/schema/types";
 import type { FormatRegistry } from "@jxsuite/schema/format-registry";
 
 // Re-exports for consumers
-export {
-  isDynamic,
-  compileServer,
-  compileSiteServer,
-  compileElement,
-  compileElementPage,
-  compileClient,
-};
+export { isDynamic } from "./shared.ts";
+export { compileServer, compileSiteServer } from "./targets/compile-server.ts";
+export { compileElement, compileElementPage } from "./targets/compile-element.ts";
+export { compileClient } from "./targets/compile-client.ts";
 
 // ─── Entry ────────────────────────────────────────────────────────────────────
 

package/src/shared.ts

@@ -7,10 +7,12 @@
  */
 
 import { RESERVED_KEYS, camelToKebab, toCSSText } from "@jxsuite/runtime";
-import { compileExpression, evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
+import { evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
 import {
+  childrenContainArray,
   isExpressionDef,
   isFunctionDef,
+  isMappedArray,
   isPrototypeDef,
   isRef,
   isSchemaOnlyDef as isSchemaOnly,
@@ -22,7 +24,6 @@ import type { ExpressionNode } from "@jxsuite/runtime/expression";
 import type {
   JsonValue,
   JxElement,
-  JxMappedArray,
   JxMutableNode,
   JxPrototypeDef,
   JxRef,
@@ -32,15 +33,9 @@ import type {
 } from "@jxsuite/schema/types";
 
 // Re-export runtime utilities used by submodules
-export {
-  camelToKebab,
-  toCSSText,
-  RESERVED_KEYS,
-  compileExpression,
-  isMutating,
-  evaluateExpression,
-};
-export type { ExpressionNode };
+export { RESERVED_KEYS, camelToKebab, toCSSText } from "@jxsuite/runtime";
+export { compileExpression, evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
+export type { ExpressionNode } from "@jxsuite/runtime/expression";
 
 // CDN defaults
 export const DEFAULT_REACTIVITY_SRC = "https://esm.sh/@vue/reactivity@3.5.32";
@@ -110,10 +105,7 @@ export function isDynamic(def: JxElement | JxMutableNode | string) {
   if (def.$switch) {
     return true;
   }
-  if (
-    !Array.isArray(def.children) &&
-    (def.children as JxMappedArray | undefined)?.$prototype === "Array"
-  ) {
+  if (isMappedArray(def) || childrenContainArray(def.children)) {
     return true;
   }
 
@@ -170,10 +162,7 @@ export function isNodeDynamic(def: JxElement | JxMutableNode | string) {
   if (def.$switch) {
     return true;
   }
-  if (
-    !Array.isArray(def.children) &&
-    (def.children as JxMappedArray | undefined)?.$prototype === "Array"
-  ) {
+  if (isMappedArray(def) || childrenContainArray(def.children)) {
     return true;
   }
 
@@ -252,9 +241,9 @@ export function createCompileContext(
   scopeDefs: Record<string, unknown> = {},
   media: Record<string, string> = {},
 ): CompileContext {
-  const scope = raw?.state
+  const scope: Record<string, unknown> = raw?.state
     ? buildInitialScope(raw.state, parentScope)
-    : (parentScope ?? Object.create(null));
+    : (parentScope ?? (Object.create(null) as Record<string, unknown>));
   return { media, scope, scopeDefs };
 }
 
@@ -267,7 +256,7 @@ export function buildInitialScope(
   defs: Record<string, JxStateDefinition> = {},
   parentScope: Record<string, unknown> | null = null,
 ) {
-  const scope = Object.create(parentScope ?? null);
+  const scope = Object.create(parentScope ?? null) as Record<string, unknown>;
 
   for (const [key, def] of Object.entries(defs)) {
     if (typeof def !== "object" || def === null || Array.isArray(def)) {
@@ -306,7 +295,9 @@ export function buildInitialScope(
     if (isFunctionDef(def)) {
       if (def.body) {
         const names = def.parameters ? paramNames(def.parameters) : (def.arguments ?? []);
-        const fn = new Function("state", ...names, def.body);
+        const fn = new Function("state", ...names, def.body) as (
+          state: Record<string, unknown>,
+        ) => unknown;
         if (def.body.includes("return")) {
           defineLazyScopeValue(scope, key, () => fn(scope));
         } else {
@@ -393,7 +384,7 @@ export function resolveRefValue(refValue: unknown, scope: Record<string, unknown
   }
   if (refValue.startsWith("$map/")) {
     const parts = refValue.split("/");
-    const [, key] = parts;
+    const key = parts[1]!;
     const base = (scope.$map as Record<string, unknown> | undefined)?.[key] ?? scope[`$map/${key}`];
     return parts.length > 2 ? getPathValue(base, parts.slice(2).join("/")) : base;
   }
@@ -417,10 +408,16 @@ export function evaluateStaticTemplate(str: string, scope: Record<string, unknow
   try {
     const singleExprMatch = str.match(/^\$\{(.+)\}$/s);
     if (singleExprMatch) {
-      const fn = new Function("state", "$map", `return (${singleExprMatch[1]})`);
+      const fn = new Function("state", "$map", `return (${singleExprMatch[1]})`) as (
+        state: Record<string, unknown>,
+        $map: unknown,
+      ) => unknown;
       return fn(scope, scope?.$map);
     }
-    const fn = new Function("state", "$map", `return \`${str}\``);
+    const fn = new Function("state", "$map", `return \`${str}\``) as (
+      state: Record<string, unknown>,
+      $map: unknown,
+    ) => unknown;
     return fn(scope, scope?.$map);
   } catch {
     return null;
@@ -632,7 +629,7 @@ export function compileStyles(
           if (mProps) {
             rules.push(`${atRule} { ${selector} { ${mProps} } }`);
           }
-          for (const [sel, sub] of Object.entries(/** @type {Record<string, unknown>} */ val)) {
+          for (const [sel, sub] of Object.entries(val as Record<string, unknown>)) {
             if (sub === null || typeof sub !== "object" || Array.isArray(sub)) {
               continue;
             }
@@ -753,7 +750,7 @@ function emitNestedElement(
       if (mProps) {
         rules.push(`${atRule} { ${selector} { ${mProps} } }`);
       }
-      for (const [sel, sub] of Object.entries(/** @type {Record<string, unknown>} */ val)) {
+      for (const [sel, sub] of Object.entries(val as Record<string, unknown>)) {
         if (sub === null || typeof sub !== "object" || Array.isArray(sub)) {
           continue;
         }
@@ -995,8 +992,7 @@ function _walkSrc(def: JxElement | JxMutableNode | string, srcs: Set<string>) {
  * @returns {{ key: string; exportName: string; src: string }[]}
  */
 export function collectServerEntries(doc: JxElement) {
-  /** @type {Map<string, { key: string; exportName: string; src: string }>} */
-  const entries = new Map();
+  const entries = new Map<string, { key: string; exportName: string; src: string }>();
   _walkServerEntries(doc, entries);
   return [...entries.values()];
 }

package/src/site/content-loader.ts

@@ -21,6 +21,7 @@ import type { FormatEntry, FormatRegistry } from "@jxsuite/schema/format-registr
 import type {
   ContentTypeDef,
   ContentTypeSchema,
+  ContentTypeSchemaField,
   JxMutableNode,
   ProjectConfig,
 } from "@jxsuite/schema/types";
@@ -36,16 +37,16 @@ import type { ContentLoaderEntry } from "@jxsuite/parser/types";
  * @returns {ContentLoaderEntry[]} Array of ContentEntry shapes
  */
 function loadJSONEntries(filePath: string) {
-  const raw = JSON.parse(readFileSync(filePath, "utf8"));
+  const raw = JSON.parse(readFileSync(filePath, "utf8")) as unknown;
   if (Array.isArray(raw)) {
-    return raw.map((item: Record<string, unknown>, i: number) => ({
+    return (raw as Record<string, unknown>[]).map((item: Record<string, unknown>, i: number) => ({
       body: null,
       data: item,
       id: (item.id as string) ?? `${basename(filePath, ".json")}-${i}`,
     }));
   }
   // Single object file — filename is the id
-  const rawObj: Record<string, unknown> = raw;
+  const rawObj = raw as Record<string, unknown>;
   return [
     {
       body: null,
@@ -108,7 +109,7 @@ export async function loadContentTypes(
 ) {
   const result = loadContentConfig(projectRoot, projectConfig);
   if (!result) {
-    return new Map();
+    return new Map<string, ContentLoaderEntry[]>();
   }
 
   const { config } = result;
@@ -359,7 +360,8 @@ export function resolveContentTypeRefs(
       continue;
     }
 
-    for (const [field, def] of Object.entries(schema.properties)) {
+    for (const [field, rawDef] of Object.entries(schema.properties)) {
+      const def = rawDef as ContentTypeSchemaField;
       if (!def.$ref?.startsWith("#/contentTypes/")) {
         continue;
       }

package/src/site/context-injection.ts

@@ -36,7 +36,7 @@ export function injectContext(
   doc: JxDocument,
   projectConfig: ProjectConfig,
   route: SiteRoute,
-  contentTypes = new Map<string, ContentLoaderEntry[]>(),
+  _contentTypes = new Map<string, ContentLoaderEntry[]>(),
   projectRoot: string | null = null,
 ) {
   if (!doc.state) {

package/src/site/image-cache.ts

@@ -94,13 +94,13 @@ export function cacheKey(srcPath: string, config: ImageConfig) {
  * @param {string} projectRoot
  * @returns {CacheManifest}
  */
-export function loadCache(projectRoot: string) {
+export function loadCache(projectRoot: string): CacheManifest {
   const manifestPath = resolve(getImageCacheDir(projectRoot), "manifest.json");
   if (!existsSync(manifestPath)) {
     return { entries: {}, version: 1 };
   }
   try {
-    return JSON.parse(readFileSync(manifestPath, "utf8"));
+    return JSON.parse(readFileSync(manifestPath, "utf8")) as CacheManifest;
   } catch {
     return { entries: {}, version: 1 };
   }

package/src/site/image-optimizer.ts

@@ -10,7 +10,8 @@ import { errorMessage } from "@jxsuite/schema/parse";
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { basename, extname, resolve } from "node:path";
 import { createRequire } from "node:module";
-import type { FormatEnum } from "sharp";
+// Sharp 0.35 only has a default export (function merged with a types namespace).
+import type SharpNS from "sharp";
 
 export interface ImageVariant {
   width: number; // Pixel width of the variant
@@ -41,8 +42,7 @@ export interface ImageConfig {
   remoteDomains?: string[];
 }
 
-// oxlint-disable-next-line typescript/consistent-type-imports -- sharp is an optional native dep loaded lazily; its `export =` module type is only nameable via import()
-type SharpModule = typeof import("sharp");
+type SharpModule = typeof SharpNS;
 
 let _sharp: SharpModule | null = null;
 
@@ -175,7 +175,7 @@ export async function processImage(srcPath: string, cacheImgDir: string, config:
       const quality = config.quality[format as keyof ImageConfig["quality"]] ?? 80;
       const task = sharp(srcPath)
         .resize(width)
-        .toFormat(format as keyof FormatEnum, { quality })
+        .toFormat(format as keyof SharpNS.FormatEnum, { quality })
         .toFile(absolutePath)
         .then(() => {});
 

package/src/site/image-transform.ts

@@ -340,7 +340,7 @@ async function transformImgNode(
         imageRefs.set(absoluteSrc, manifest);
       }
 
-      const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0];
+      const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0]!;
       srcset = buildSrcset(manifest.variants, preferredFormat);
     }
   }
@@ -384,8 +384,8 @@ async function transformInnerHtmlImages(
   const replacements = [];
 
   for (const m of html.matchAll(IMG_TAG_RE)) {
-    const [tag] = m;
-    const [, attrs] = m;
+    const tag = m[0]!;
+    const attrs = m[1]!;
 
     if (SRCSET_ATTR_RE.test(attrs)) {
       continue;
@@ -400,7 +400,7 @@ async function transformInnerHtmlImages(
     }
 
     // Attribute values in pre-rendered innerHTML are entity-escaped — decode for processing
-    const src = srcMatch[1].replaceAll("&", "&");
+    const src = srcMatch[1]!.replaceAll("&", "&");
     const remote = isAllowedRemote(src, config);
     if (!remote && shouldSkip(src)) {
       continue;
@@ -425,7 +425,7 @@ async function transformInnerHtmlImages(
         imageRefs.set(absoluteSrc as string, manifest);
       }
 
-      const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0];
+      const preferredFormat = config.formats.includes("avif") ? "avif" : config.formats[0]!;
       srcset = buildSrcset(manifest.variants, preferredFormat);
     }
     if (!srcset) {

package/src/site/pages-discovery.ts

@@ -169,7 +169,7 @@ async function fileToRoute(relativePath: string, absolutePath: string, registry?
   // Convert [param] → :param and [...param] → *
   const urlPattern = urlPath.replaceAll(
     /\[\.\.\.(\w+)\]|\[(\w+)\]/g,
-    (match: string, spread: string, named: string) => {
+    (_match: string, spread: string, named: string) => {
       if (spread) {
         isCatchAll = true;
         isDynamic = true;
@@ -319,10 +319,9 @@ function resolvePathEntries(
   // Data file ref: { "$ref": "./data/products.json", param: "id", field: "sku" }
   if ("$ref" in $paths && $paths.$ref) {
     const filePath = resolve(projectRoot, $paths.$ref);
-    /** @type {Record<string, unknown>[]} */
-    let data;
+    let data: unknown;
     try {
-      data = JSON.parse(readFileSync(filePath, "utf8"));
+      data = JSON.parse(readFileSync(filePath, "utf8")) as unknown;
     } catch (error) {
       const err = error as Error;
       console.warn(`Warning: $paths.$ref could not load "${$paths.$ref}": ${err.message}`);
@@ -334,7 +333,7 @@ function resolvePathEntries(
     }
     const param = $paths.param ?? "id";
     const field = $paths.field ?? "id";
-    return data.map((item: Record<string, unknown>) => ({
+    return (data as Record<string, unknown>[]).map((item: Record<string, unknown>) => ({
       [param]: item[field] ?? item.id ?? String(item),
     }));
   }

package/src/site/site-build.ts

@@ -54,6 +54,7 @@ import type {
   JxAttributeValue,
   JxElement,
   JxHeadEntry,
+  JxMappedArray,
   JxMutableNode,
   JxStateDefinition,
   JxStyle,
@@ -188,8 +189,7 @@ export async function buildSite(
   }
 
   // ── 5b. Collect server entries from components (for site-wide bundling) ──
-  /** @type {{ exportName: string; src: string }[]} */
-  const siteServerEntries = [];
+  const siteServerEntries: { exportName: string; src: string }[] = [];
   if (projectConfig.build.adapter) {
     for (const [, doc] of componentDefs) {
       const entries = collectServerEntries(doc);
@@ -207,8 +207,7 @@ export async function buildSite(
 
   const cfImages = projectConfig.images.optimize && projectConfig.images.service === "cloudflare";
   const imageCache = projectConfig.images.optimize && !cfImages ? loadCache(projectRoot) : null;
-  /** @type {import("./image-transform.ts").ImageMetaCache | null} */
-  const imageMetaCache = cfImages ? new Map() : null;
+  const imageMetaCache: ImageMetaCache | null = cfImages ? new Map() : null;
   if (cfImages) {
     console.log(
       `images.service is "cloudflare" — srcsets use /cdn-cgi/image transform URLs. ` +
@@ -274,7 +273,7 @@ export async function buildSite(
             mode: "export",
           })) as string;
           if (content) {
-            const sidecarPath = outPath.replace(/\.html$/, fmt.extensions[0]);
+            const sidecarPath = outPath.replace(/\.html$/, fmt.extensions[0]!);
             writeFileSync(sidecarPath, content, "utf8");
             fileCount += 1;
           }
@@ -326,7 +325,7 @@ export async function buildSite(
     const { adapter } = projectConfig.build;
     log("Generating site-wide server worker...");
 
-    const deduped = new Map();
+    const deduped = new Map<string, { exportName: string; src: string }>();
     for (const entry of siteServerEntries) {
       if (!deduped.has(entry.exportName)) {
         deduped.set(entry.exportName, entry);
@@ -460,7 +459,7 @@ async function compilePage(
   // Determine the page title — resolve template strings against the scope
   let title = pageTitle ?? projectConfig.name ?? "Jx Site";
   if (typeof title === "string" && isTemplateString(title)) {
-    title = evaluateStaticTemplate(title, scope) ?? (title as string);
+    title = (evaluateStaticTemplate(title, scope) as string | null) ?? (title as string);
   }
 
   // Resolve template strings in $head entries
@@ -595,14 +594,16 @@ function resolveHeadTemplates(headEntries: JxHeadEntry[], scope: Record<string,
       resolved.attributes = { ...resolved.attributes };
       for (const [k, v] of Object.entries(resolved.attributes)) {
         if (typeof v === "string" && isTemplateString(v)) {
-          resolved.attributes[k] = evaluateStaticTemplate(v, scope) ?? (v as string | boolean);
+          resolved.attributes[k] =
+            (evaluateStaticTemplate(v, scope) as string | boolean | null) ??
+            (v as string | boolean);
         }
       }
     }
     if (typeof resolved.textContent === "string" && isTemplateString(resolved.textContent)) {
       resolved.textContent =
-        evaluateStaticTemplate(resolved.textContent, scope) ??
-        (resolved.textContent as string | undefined);
+        (evaluateStaticTemplate(resolved.textContent, scope) as string | null) ??
+        resolved.textContent;
     }
     return resolved;
   });
@@ -662,11 +663,11 @@ function expandMapTemplate(template: JxElement, scope: Record<string, unknown>):
   const node = {} as JxElement;
   for (const [k, v] of Object.entries(template)) {
     if (k === "children" && Array.isArray(v)) {
-      node.children = v.map((child) => {
+      node.children = (v as (string | JxElement)[]).map((child) => {
         if (typeof child === "string") {
           return child;
         }
-        return expandMapTemplate(/** @type {JxMutableNode} */ child, scope);
+        return expandMapTemplate(child, scope);
       });
     } else if (k === "style" && v && typeof v === "object") {
       const style: JxStyle = { ...(v as JxStyle) };
@@ -718,10 +719,26 @@ function evaluateMapTemplate(str: string, scope: Record<string, unknown>) {
     const index = (scope.$map as Record<string, unknown>)?.index;
     const singleExprMatch = str.match(/^\$\{(.+)\}$/s);
     if (singleExprMatch) {
-      const fn = new Function("state", "$map", "item", "index", `return (${singleExprMatch[1]})`);
+      const fn = new Function(
+        "state",
+        "$map",
+        "item",
+        "index",
+        `return (${singleExprMatch[1]})`,
+      ) as (
+        state: Record<string, unknown>,
+        $map: unknown,
+        item: unknown,
+        index: unknown,
+      ) => unknown;
       return fn(scope, scope.$map, item, index);
     }
-    const fn = new Function("state", "$map", "item", "index", `return \`${str}\``);
+    const fn = new Function("state", "$map", "item", "index", `return \`${str}\``) as (
+      state: Record<string, unknown>,
+      $map: unknown,
+      item: unknown,
+      index: unknown,
+    ) => unknown;
     return fn(scope, scope.$map, item, index);
   } catch {
     return null;
@@ -751,49 +768,38 @@ function resolveDocTemplates(node: JxElement | string, scope: Record<string, unk
   }
   if (typeof node.textContent === "string" && isTemplateString(node.textContent)) {
     node.textContent =
-      evaluateStaticTemplate(node.textContent, scope) ?? (node.textContent as string | null);
+      (evaluateStaticTemplate(node.textContent, scope) as string | null) ??
+      (node.textContent as string | null);
   }
   if (node.style && typeof node.style === "object") {
     for (const [k, v] of Object.entries(node.style)) {
       if (typeof v === "string" && isTemplateString(v)) {
-        node.style[k] = evaluateStaticTemplate(v, scope) ?? (v as string | number | JxStyle);
+        node.style[k] =
+          (evaluateStaticTemplate(v, scope) as string | number | JxStyle | undefined) ??
+          (v as string | number | JxStyle);
       }
     }
   }
   if (node.attributes && typeof node.attributes === "object") {
     for (const [k, v] of Object.entries(node.attributes)) {
       if (typeof v === "string" && isTemplateString(v)) {
-        node.attributes[k] = evaluateStaticTemplate(v, scope) ?? v;
+        node.attributes[k] = (evaluateStaticTemplate(v, scope) as JxAttributeValue | null) ?? v;
       }
     }
   }
   if (node.$props && typeof node.$props === "object") {
     for (const [k, v] of Object.entries(node.$props)) {
       if (typeof v === "string" && isTemplateString(v)) {
-        node.$props[k] = evaluateStaticTemplate(v, scope) ?? v;
+        node.$props[k] = (evaluateStaticTemplate(v, scope) as JsonValue | null) ?? v;
       }
     }
   }
   const rawChildren = node.children;
+  // Legacy whole-children repeater: expand the items into the node's static children.
   if (isMappedArray(rawChildren)) {
-    const itemsSrc = rawChildren.items;
-    let items = null;
-    if (isRef(itemsSrc)) {
-      items = resolveRefValue(itemsSrc.$ref, scope);
-    } else if (Array.isArray(itemsSrc)) {
-      items = itemsSrc;
-    }
-    const mapTemplate = rawChildren.map;
-    if (Array.isArray(items) && mapTemplate) {
-      node.children = items.map((item, index) => {
-        const childScope = Object.create(scope);
-        childScope.$map = { index, item };
-        childScope["$map/item"] = item;
-        childScope["$map/index"] = index;
-        const expanded = expandMapTemplate(mapTemplate, childScope);
-        resolveDocTemplates(expanded, childScope);
-        return expanded;
-      });
+    const expanded = expandMappedArrayStatic(rawChildren, scope);
+    if (expanded) {
+      node.children = expanded;
       return;
     }
   }
@@ -809,7 +815,7 @@ function resolveDocTemplates(node: JxElement | string, scope: Record<string, unk
   } else if (Array.isArray(node.children)) {
     let i = 0;
     while (i < node.children.length) {
-      const child = node.children[i];
+      const child = node.children[i]!;
       if (typeof child === "string" && isTemplateString(child)) {
         const resolved = evaluateStaticTemplate(child, scope);
         if (Array.isArray(resolved)) {
@@ -822,12 +828,55 @@ function resolveDocTemplates(node: JxElement | string, scope: Record<string, unk
           continue;
         }
       }
+      // Array pseudo-element among siblings: expand its items in place.
+      if (isMappedArray(child)) {
+        const expanded = expandMappedArrayStatic(child, scope);
+        if (expanded) {
+          node.children.splice(i, 1, ...expanded);
+          i += expanded.length;
+          continue;
+        }
+      }
       resolveDocTemplates(child, scope);
       i += 1;
     }
   }
 }
 
+/**
+ * Statically expand a mapped array to its resolved item nodes when `items` resolves to an array at
+ * build time, or null otherwise (leave the array node for client-side rendering).
+ *
+ * @param {JxMappedArray} arrayDef
+ * @param {Record<string, unknown>} scope
+ * @returns {(JxElement | string)[] | null}
+ */
+function expandMappedArrayStatic(
+  arrayDef: JxMappedArray,
+  scope: Record<string, unknown>,
+): (JxElement | string)[] | null {
+  const itemsSrc = arrayDef.items;
+  let items: unknown = null;
+  if (isRef(itemsSrc)) {
+    items = resolveRefValue(itemsSrc.$ref, scope);
+  } else if (Array.isArray(itemsSrc)) {
+    items = itemsSrc;
+  }
+  const mapTemplate = arrayDef.map;
+  if (!Array.isArray(items) || !mapTemplate) {
+    return null;
+  }
+  return (items as unknown[]).map((item: unknown, index) => {
+    const childScope = Object.create(scope) as Record<string, unknown>;
+    childScope.$map = { index, item };
+    childScope["$map/item"] = item;
+    childScope["$map/index"] = index;
+    const expanded = expandMapTemplate(mapTemplate, childScope);
+    resolveDocTemplates(expanded, childScope);
+    return expanded;
+  });
+}
+
 /** Collector for CSS rules extracted from component slot content during expansion. */
 interface SlotCssCollector {
   rules: string[];
@@ -853,7 +902,7 @@ function expandComponents(
     return;
   }
   if (Array.isArray(node)) {
-    for (const n of node) {
+    for (const n of node as (JxElement | string)[]) {
       expandComponents(n, componentDefs, slotCss);
     }
     return;
@@ -1012,11 +1061,11 @@ function injectHead(html: string, headEntries: JxHeadEntry[], lang: string) {
   const existingMatch = html.match(headPattern);
   let preservedBlocks = "";
   if (existingMatch) {
-    const styles = existingMatch[1].match(/<style>[\s\S]*?<\/style>/gi);
+    const styles = existingMatch[1]!.match(/<style>[\s\S]*?<\/style>/gi);
     if (styles) {
       preservedBlocks += `\n  ${styles.join("\n  ")}`;
     }
-    const scripts = existingMatch[1].match(/<script[\s\S]*?<\/script>/gi);
+    const scripts = existingMatch[1]!.match(/<script[\s\S]*?<\/script>/gi);
     if (scripts) {
       preservedBlocks += `\n  ${scripts.join("\n  ")}`;
     }