@jxsuite/compiler 2.0.8 → 3.0.0

package/src/site/site-build.ts

@@ -50,7 +50,7 @@ import type { AssetMount } from "@jxsuite/schema/asset-paths";
 import type { FormatEntry, FormatRegistry } from "@jxsuite/schema/format-registry";
 import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
 import { resolveLayout } from "./layout-resolver.ts";
-import { mergeHead, renderHead } from "./head-merger.ts";
+import { mergeHead, renderHead } from "@jxsuite/site/head-merger";
 import { unregisteredHeadRelations } from "./link-relations.ts";
 import { injectContext } from "./context-injection.ts";
 import { compile, compileServer, compileSiteServer } from "../compiler.ts";
@@ -62,6 +62,7 @@ import {
   collectServerEntries,
   collectStyles,
   colorSchemePrePaintScript,
+  escapeStyleText,
   evaluateStaticTemplate,
   isComponentFullyStatic,
   isSingleExpression,
@@ -99,7 +100,8 @@ import {
 } from "./i18n.ts";
 import type { LocaleAlternate, PageLocaleContext } from "./i18n.ts";
 import {
-  isPrefixSpecifier,
+  importMapAssets,
+  importMapAssetsInHtml,
   renderImportMap,
   resolveClientRuntime,
   writeClientRuntime,
@@ -160,6 +162,13 @@ export async function buildSite(
   const pagesDir = resolve(projectRoot, "pages");
   const publicDir = resolve(projectRoot, "public");
   const trailingSlash = projectConfig.build.trailingSlash ?? "always";
+  /*
+   * Browser bundles are minified unless the project opts out. Off, the six scripts jxsuite.com
+   * loads weigh 155 kB of source a phone has to parse before it can paint; on, 65 kB. The opt-out
+   * exists for two real cases: reading a deployed stack trace, and diffing `dist/` across bundler
+   * backends, which agree on semantics but not on minified bytes.
+   */
+  const minify = projectConfig.build.minify !== false;
 
   // Client sidecar bundles: bundleable Function-def `$src` specifiers (and lowered-def `$bundle`
   // Hints) are rewritten to their /assets/ URL during compilation, registered here, and bundled
@@ -201,6 +210,11 @@ export async function buildSite(
    */
   const clientRuntime = resolveClientRuntime();
   const runtimeImports = clientRuntime.imports;
+  /*
+   * What step 6d bundles, scanned back out of each finished page rather than recorded wherever a
+   * map is emitted. Several places emit one and only `injectComponentScripts` was recording, so a
+   * page whose interactivity came from anything else shipped a map naming files no build wrote.
+   */
   const runtimeAssetsUsed = new Set<string>();
   /*
    * Scanned from every finished page, so the hashes name the exact bytes shipped rather than what
@@ -680,10 +694,18 @@ export async function buildSite(
           staticTags,
           result.files.map((f: { content: string }) => f.content).join("\n"),
           runtimeImports,
-          runtimeAssetsUsed,
         );
       }
 
+      /*
+       * Whatever import map this page ended up with, step 6d owes it the files it names. Read from
+       * the finished HTML so the answer does not depend on which of the emission paths produced
+       * the map — the one that reported and the one that shipped were different sets (issue #227).
+       */
+      for (const assetPath of importMapAssetsInHtml(result.html)) {
+        runtimeAssetsUsed.add(assetPath);
+      }
+
       // Mounted assets this page actually references — scanned from the finished HTML so a
       // Reference is caught wherever it came from (markdown image, hand-authored page, $head).
       collectAssetRefs(result.html, assetMounts, assetRefs);
@@ -862,6 +884,8 @@ export async function buildSite(
     const runtime = await writeClientRuntime(
       { ...clientRuntime, assetPaths: [...runtimeAssetsUsed] },
       outDir,
+      undefined,
+      minify,
     );
     fileCount += runtime.written;
     for (const error of runtime.errors) {
@@ -889,7 +913,7 @@ export async function buildSite(
         mkdirSync(dirname(outfile), { recursive: true });
         await bundleEntry(
           { entryPath: bundle.entryPath, outfile },
-          { external: CLIENT_EXTERNALS, target: "browser" },
+          { external: CLIENT_EXTERNALS, minify, target: "browser" },
         );
         fileCount += 1;
         log(`  ${bundle.specifier} → ${assetPath}`);
@@ -914,7 +938,7 @@ export async function buildSite(
         await bundleSource(
           `${specifiers.map((sp) => `import ${JSON.stringify(sp)};`).join("\n")}\n`,
           { outfile, resolveDir: projectRoot },
-          { target: "browser" },
+          { minify, target: "browser" },
         );
         fileCount += 1;
         log(`  ${specifiers.length} element(s) → ${assetPath}`);
@@ -933,7 +957,7 @@ export async function buildSite(
    * discovered from their contents rather than declared anywhere (site-architecture.md §8.7).
    */
   if (runtimeAssetsUsed.size > 0) {
-    const subpaths = await writeRuntimeSubpaths(outDir);
+    const subpaths = await writeRuntimeSubpaths(outDir, undefined, minify);
     if (subpaths.written > 0) {
       log(`Bundling ${subpaths.written} runtime subpath module(s)...`);
     }
@@ -1095,12 +1119,36 @@ export async function buildSite(
     if (rules.length > 0) {
       log("Writing response headers...");
       fileCount += writeHeaders(outDir, rules);
-      const { adapter } = projectConfig.build;
+      const { adapter, deploy } = projectConfig.build;
       if (adapter === "node" || adapter === "bun") {
         console.warn(
           `The "${adapter}" adapter serves no static assets, so dist/_headers is documentation ` +
             `rather than configuration — apply these headers at the reverse proxy in front of it.`,
         );
+      } else if (adapter === undefined && deploy === undefined) {
+        /*
+         * `_headers` is a Cloudflare/Netlify convention, not a web standard, and the build has no
+         * way to know where a plain static `dist/` is going. Most static hosts — GitHub Pages among
+         * them — ignore the file entirely and serve their own `Cache-Control`, which is how a site
+         * ends up shipping a year-long `immutable` rule for its content-addressed images and
+         * getting ten minutes.
+         *
+         * A `public/CNAME` is GitHub Pages' custom-domain marker and nothing else's, so it is a
+         * specific enough signal to say so out loud rather than warn every static build.
+         */
+        if (existsSync(resolve(publicDir, "CNAME"))) {
+          console.warn(
+            "GitHub Pages ignores dist/_headers and serves its own Cache-Control: max-age=600, " +
+              "so the generated caching and security rules will not take effect. Deploy behind a " +
+              "host that reads _headers (Cloudflare Pages, Cloudflare Workers assets, Netlify) " +
+              "to apply them.",
+          );
+        } else {
+          log(
+            "  note: _headers is read by Cloudflare Pages, Cloudflare Workers assets and Netlify; " +
+              "other static hosts ignore it and serve their own Cache-Control.",
+          );
+        }
       }
     }
     fileCount += writeNoJekyll(outDir);
@@ -1171,7 +1219,7 @@ async function compilePage(
   const pageDoc = await readPageDocument(route.sourcePath as string, formatRegistry);
 
   // Resolve layout (wraps page in layout with slot distribution)
-  const layoutDoc = resolveLayout(pageDoc, projectConfig, projectRoot);
+  const layoutDoc = await resolveLayout(pageDoc, projectConfig, projectRoot);
 
   // Extract head arrays before they get lost in the merge
   const pageHead = (pageDoc.$head ?? layoutDoc._pageHead ?? []) as JxHeadEntry[];
@@ -1393,7 +1441,7 @@ async function compilePage(
   if (slotCss.rules.length > 0) {
     result.html = result.html.replace(
       "</head>",
-      `<style>\n${slotCss.rules.join("\n")}\n</style>\n</head>`,
+      `<style>\n${escapeStyleText(slotCss.rules.join("\n"))}\n</style>\n</head>`,
     );
   }
 
@@ -2074,7 +2122,6 @@ function expandComponents(
  * @param {Set<string>} [staticTags] - Tags where ALL instances are fully static (skip JS)
  * @param {string} [islandSource] - Concatenated island modules emitted for this page
  * @param {Record<string, string>} [runtimeImports] - The import map's `imports` object
- * @param {Set<string>} [runtimeAssetsUsed] - Collects the asset paths an emitted import map names
  * @returns {string}
  */
 function injectComponentScripts(
@@ -2084,7 +2131,6 @@ function injectComponentScripts(
   staticTags = new Set<string>(),
   islandSource = "",
   runtimeImports: Record<string, string> = {},
-  runtimeAssetsUsed = new Set<string>(),
 ) {
   // 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
@@ -2097,15 +2143,31 @@ function injectComponentScripts(
     return html;
   }
 
-  // Inject CSS links in <head> for ALL components that have CSS sidecars
-  const cssLinks = usedTags
-    .filter((tag: string) => cssMap.has(tag))
-    .map((tag: string) => `<link rel="stylesheet" href="/components/${tag}.css">`)
-    .join("\n  ");
-  let result = html;
-  if (cssLinks) {
-    result = result.replace("</head>", `  ${cssLinks}\n</head>`);
-  }
+  /*
+   * Component CSS is INLINED, not linked.
+   *
+   * A `<link rel="stylesheet">` per component tag is a render-blocking request per component: on
+   * jxsuite.com's home page, 11 of them totalling 22 kB — the whole of its critical request chain,
+   * for sheets averaging 2 kB each. The page already carries its project and page CSS inline
+   * (`buildStyleBlock`), so this is the same delivery, applied consistently.
+   *
+   * The trade is real and deliberate: these bytes now repeat on every page instead of caching
+   * across navigations. They are small, they gzip against the markup around them, and a round trip
+   * on a phone costs more than the bytes do. Components in shadow mode are untouched — their sheet
+   * is linked from inside the declarative shadow root and never enters `cssMap`.
+   *
+   * Emitted last in <head>, exactly where the links were, so the cascade is unchanged.
+   */
+  const componentCss = usedTags
+    .map((tag: string) => cssMap.get(tag))
+    .filter((css): css is string => css !== undefined && css !== "")
+    .join("\n");
+  const styleBlock =
+    componentCss === "" ? "" : `<style>\n${escapeStyleText(componentCss)}\n  </style>`;
+  const intoHead = (fragments: string[]) => {
+    const block = fragments.filter(Boolean).join("\n  ");
+    return block === "" ? html : html.replace("</head>", `  ${block}\n</head>`);
+  };
 
   // 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 —
@@ -2113,22 +2175,30 @@ function injectComponentScripts(
   // 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;
+    return intoHead([styleBlock]);
   }
 
   // Build import map (needed for @vue/reactivity and lit-html)
   const importMap = renderImportMap(runtimeImports);
-  for (const [specifier, url] of Object.entries(runtimeImports)) {
-    /*
-     * A prefix key's value is the DIRECTORY its subpaths are served from — `/assets/lit-html/` —
-     * not a file any build writes. `writeClientRuntime` matches this set against exact asset
-     * paths, so a directory in it bundled nothing and only inflated the count this build logged.
-     */
-    if (isPrefixSpecifier(specifier) || !url.startsWith("/")) {
-      continue;
-    }
-    runtimeAssetsUsed.add(url);
-  }
+  /*
+   * The runtime modules THIS page needs — the hints are per page, so they are read from this
+   * page's map rather than from the build-wide set, which would have every page hint at every
+   * other page's runtime.
+   */
+  const pageRuntimeAssets = importMapAssets(runtimeImports);
+
+  /*
+   * An import map declares where a bare specifier lives; it does not tell the browser to go get it.
+   * Without these hints `/assets/vue-reactivity.js` is discovered only after a component module has
+   * been fetched AND parsed — a three-deep request chain on the critical path, on a connection
+   * where each hop is a round trip. The component modules are hinted too so the whole set starts
+   * downloading while the HTML is still being parsed.
+   */
+  const preloads = [...pageRuntimeAssets, ...jsTags.map((tag: string) => `/components/${tag}.js`)]
+    .map((href) => `<link rel="modulepreload" href="${href}">`)
+    .join("\n  ");
+
+  const result = intoHead([preloads, styleBlock]);
 
   const moduleScripts = jsTags
     .map((tag: string) => `<script type="module" src="/components/${tag}.js"></script>`)

package/src/targets/compile-element.ts

@@ -17,6 +17,7 @@ import {
   escapeHtml,
   isMutating,
   isSchemaOnly,
+  srcExportName,
   srcImportBinding,
   tagNameToClassName,
 } from "../shared.ts";
@@ -351,11 +352,36 @@ export function emitElementModule(
 
   // Collect $src imports from state entries before emitting other imports
   const srcImportMap = new Map<string, string[]>();
+  /** `$lazy` `$src` modules → the (export, local binding) pairs each one supplies. */
+  const lazySrcMap = new Map<string, { binding: string; exportName: string }[]>();
   const defs = doc.state ?? {};
+  const callableRefs = collectCallableRefs(doc);
   for (const [key, def] of Object.entries(defs)) {
     const d = def as JxMutableNode;
     if (d && typeof d === "object" && !Array.isArray(d) && d.$prototype === "Function" && d.$src) {
       const srcPath = d.$src;
+      if (d.$lazy === true) {
+        /*
+         * A computed reads its value synchronously, and a lazy binding can only ever hand back a
+         * promise. Silently producing `computed(() => Promise)` would render "[object Promise]" in
+         * whatever the template bound it to, so this is a build error rather than a surprise.
+         */
+        if (!callableRefs.has(key) && !LIFECYCLE_KEYS.has(key)) {
+          throw new Error(
+            `"${key}" declares "$lazy": true but is used as a computed value, not called. ` +
+              `A lazily loaded function resolves to a promise; a computed must resolve now. ` +
+              `Remove "$lazy", or call ${key}() from a handler instead of binding its value.`,
+          );
+        }
+        if (!lazySrcMap.has(srcPath)) {
+          lazySrcMap.set(srcPath, []);
+        }
+        (lazySrcMap.get(srcPath) as { binding: string; exportName: string }[]).push({
+          binding: key,
+          exportName: srcExportName(key, d),
+        });
+        continue;
+      }
       if (!srcImportMap.has(srcPath)) {
         srcImportMap.set(srcPath, []);
       }
@@ -380,6 +406,31 @@ export function emitElementModule(
   lines.push(
     `import { reactive, computed, effect, stop } from '@vue/reactivity';`,
     `import { render, html } from 'lit-html';`,
+  );
+
+  /*
+   * `$lazy` swaps the static import for a memoized dynamic one. A static import is a download, a
+   * parse and an evaluate on every page that renders the component, whether or not anybody calls
+   * the function: jxsuite.com's search client is 70 kB of MiniSearch fetched by every visitor, most
+   * of whom never open search. The local binding keeps its name so every call site is unchanged;
+   * what changes is that it now returns a promise.
+   */
+  let lazyIndex = 0;
+  for (const [srcPath, entries] of lazySrcMap) {
+    const importPath = rewriteSrc ? rewriteSrc(srcPath) : srcPath;
+    const mod = `_jxLazy${lazyIndex}`;
+    lazyIndex += 1;
+    lines.push(
+      `let ${mod};`,
+      `const ${mod}Load = () => (${mod} ??= import('${importPath}'));`,
+      ...entries.map(
+        ({ binding, exportName }) =>
+          `const ${binding} = (...args) => ${mod}Load().then((m) => m.${exportName}(...args));`,
+      ),
+    );
+  }
+
+  lines.push(
     "",
     `class ${className} extends HTMLElement {`,
     // One registry for every effect the element creates — render, dynamic host styles, Request
@@ -401,7 +452,6 @@ export function emitElementModule(
   const formulaEntries: [string, JxExpressionDef][] = [];
   /** `"${…}"` state entries — computed, exactly as the runtime treats them. */
   const templateEntries: [string, string][] = [];
-  const callableRefs = collectCallableRefs(doc);
   for (const [key, def] of Object.entries(defs)) {
     const d = def as JxMutableNode;
     if (isExpressionDef(d)) {

package/src/types.ts

@@ -1,14 +1,8 @@
-export interface HeadMergeContext {
-  title?: string;
-  siteName?: string;
-  lang?: string;
-  charset?: string;
-  url?: string;
-  siteUrl?: string;
-  pageUrl?: string;
-  /** `rel="alternate"` links for this page's translations (site-architecture.md §13.5). */
-  alternates?: readonly { hreflang: string; href: string }[];
-}
+/**
+ * `HeadMergeContext` moved to `@jxsuite/site/head-merger` with the merger itself — a browser bundle
+ * and a Worker both assemble the same `<head>`, and neither can import this package.
+ */
+export type { HeadMergeContext } from "@jxsuite/site/head-merger";
 
 export interface SiteRoute {
   urlPattern: string;

package/src/site/head-merger.ts

@@ -1,251 +0,0 @@
-/**
- * Head-merger.js — $head merge pipeline
- *
- * Merges <head> element arrays from three levels:
- *
- * 1. Site.json.$head — global (e.g., favicon, global stylesheet)
- * 2. Layout.$head — layout-level (e.g., shared nav scripts)
- * 3. Page.$head — page-specific (e.g., per-page meta tags)
- *
- * Per site-architecture spec §8:
- *
- * - Later levels override earlier levels for the same element
- * - Deduplication by tagName + key attribute (name, property, rel+href)
- * - Charset and viewport are auto-injected if missing
- */
-
-import type { JxHeadEntry } from "@jxsuite/schema/types";
-import type { HeadMergeContext } from "../types.ts";
-
-/**
- * Merge $head arrays from site, layout, and page levels.
- *
- * @param {JxHeadEntry[]} [siteHead] - Site.json $head entries
- * @param {JxHeadEntry[]} [layoutHead] - Layout $head entries (may be empty)
- * @param {JxHeadEntry[]} [pageHead] - Page $head entries (may be empty)
- * @param {HeadMergeContext} [context] - { title, lang, charset, url, pageUrl }
- * @returns {JxHeadEntry[]} Merged, deduplicated $head array
- */
-export function mergeHead(
-  siteHead: JxHeadEntry[] = [],
-  layoutHead: JxHeadEntry[] = [],
-  pageHead: JxHeadEntry[] = [],
-  context: HeadMergeContext = {},
-) {
-  // Start with auto-injected defaults
-  const defaults: JxHeadEntry[] = [
-    { attributes: { charset: context.charset ?? "utf8" }, tagName: "meta" },
-    {
-      attributes: {
-        content: "width=device-width, initial-scale=1",
-        name: "viewport",
-      },
-      tagName: "meta",
-    },
-  ];
-
-  // Merge layers: site → layout → page (later wins)
-  const merged = new Map<string, JxHeadEntry>();
-
-  for (const entry of [...defaults, ...siteHead, ...layoutHead, ...pageHead]) {
-    const key = headEntryKey(entry);
-    merged.set(key, entry);
-  }
-
-  // Insert <title> if present
-  const title = context.title ?? context.siteName ?? "Jx Site";
-  merged.set("title", { children: [title], tagName: "title" });
-
-  // Add canonical URL if provided
-  if (context.pageUrl && context.siteUrl) {
-    const canonical = new URL(context.pageUrl, context.siteUrl).href;
-    /*
-     * An author-supplied canonical wins, like every other auto-injected entry (§8.4). This used a
-     * hand-written `link:canonical` key that `headEntryKey` never produces, so the author's entry
-     * and this one landed under different keys and the page got BOTH — which is the one thing a
-     * canonical link must not be.
-     */
-    const hasAuthored = [...merged.values()].some(
-      (e) =>
-        e && typeof e === "object" && e.tagName === "link" && e.attributes?.rel === "canonical",
-    );
-    if (!hasAuthored) {
-      const entry: JxHeadEntry = {
-        attributes: { href: canonical, rel: "canonical" },
-        tagName: "link",
-      };
-      merged.set(headEntryKey(entry), entry);
-    }
-    // Auto OpenGraph identity (site-architecture §8.4) — author-supplied values win.
-    if (!merged.has("meta:og:url")) {
-      merged.set("meta:og:url", {
-        attributes: { content: canonical, property: "og:url" },
-        tagName: "meta",
-      });
-    }
-  }
-  if (context.siteName && !merged.has("meta:og:site_name")) {
-    merged.set("meta:og:site_name", {
-      attributes: { content: context.siteName, property: "og:site_name" },
-      tagName: "meta",
-    });
-  }
-
-  /*
-   * Locale alternates (site-architecture.md §13.5). Keyed through `headEntryKey` like everything
-   * else, which is what keeps a set of them from collapsing: they share `rel="alternate"` and
-   * differ only in `hreflang`, and `x-default` conventionally shares its `href` with the default
-   * locale's entry. Before the key accounted for the qualifying attribute this whole feature was
-   * impossible — the set became one link.
-   *
-   * An author-supplied alternate for the same `hreflang` wins, like every other auto entry.
-   */
-  for (const alternate of context.alternates ?? []) {
-    const entry: JxHeadEntry = {
-      attributes: { href: alternate.href, hreflang: alternate.hreflang, rel: "alternate" },
-      tagName: "link",
-    };
-    const key = headEntryKey(entry);
-    if (!merged.has(key)) {
-      merged.set(key, entry);
-    }
-  }
-
-  return [...merged.values()];
-}
-
-/**
- * Generate a deduplication key for a <head> element. Elements with the same key are considered
- * duplicates; the last one wins.
- *
- * @param {JxHeadEntry} entry
- * @returns {string}
- */
-function headEntryKey(entry: JxHeadEntry) {
-  if (!entry || typeof entry !== "object") {
-    return String(entry);
-  }
-
-  const tag = entry.tagName ?? "unknown";
-  const attrs = entry.attributes ?? {};
-
-  // <title> — singleton
-  if (tag === "title") {
-    return "title";
-  }
-
-  // <meta charset> — singleton
-  if (attrs.charset) {
-    return "meta:charset";
-  }
-
-  // <meta name="...""> — keyed by name
-  if (tag === "meta" && attrs.name) {
-    return `meta:${attrs.name}`;
-  }
-
-  // <meta property="..."> — keyed by property (Open Graph)
-  if (tag === "meta" && attrs.property) {
-    return `meta:${attrs.property}`;
-  }
-
-  /*
-   * <link> — keyed by rel + href + the attribute that distinguishes two links sharing both.
-   *
-   * `rel` + `href` alone is not identity, and the cases where it fails are the ones a site actually
-   * needs: `hreflang="x-default"` conventionally points at the SAME href as the default locale's
-   * alternate, and an RSS and an Atom feed are both `rel="alternate"` differing only in `type`.
-   * `icon` differs by `sizes` and `stylesheet` by `media` for the same reason.
-   */
-  if (tag === "link" && attrs.rel) {
-    const qualifier = attrs.hreflang ?? attrs.type ?? attrs.media ?? attrs.sizes ?? "";
-    return `link:${attrs.rel}:${attrs.href ?? ""}:${String(qualifier)}`;
-  }
-
-  // <script src="..."> — keyed by src
-  if (tag === "script" && attrs.src) {
-    return `script:${attrs.src}`;
-  }
-
-  // <style> — unique per content hash
-  if (tag === "style") {
-    const raw = Array.isArray(entry.children) ? entry.children.join("") : entry.textContent;
-    const content = typeof raw === "object" && raw !== null ? JSON.stringify(raw) : (raw ?? "");
-    return `style:${simpleHash(content)}`;
-  }
-
-  // Fallback — use full JSON serialization
-  return `${tag}:${JSON.stringify(entry)}`;
-}
-
-/**
- * Simple string hash for deduplication (not cryptographic).
- *
- * @param {string} str
- * @returns {string}
- */
-function simpleHash(str: string) {
-  let hash = 0;
-  for (let i = 0; i < str.length; i++) {
-    // oxlint-disable-next-line no-bitwise -- classic 31x string hash; the shift is the algorithm
-    hash = Math.trunc((hash << 5) - hash + (str.codePointAt(i) ?? 0));
-  }
-  return hash.toString(36);
-}
-
-/**
- * Render a merged $head array to HTML string for insertion into <head>.
- *
- * @param {JxHeadEntry[]} headEntries - Merged head entries
- * @returns {string} HTML string
- */
-export function renderHead(headEntries: JxHeadEntry[]) {
-  return headEntries.map((e: JxHeadEntry) => renderHeadEntry(e)).join("\n  ");
-}
-
-/**
- * Render a single $head entry to an HTML string.
- *
- * @param {JxHeadEntry} entry
- * @returns {string}
- */
-function renderHeadEntry(entry: JxHeadEntry) {
-  if (typeof entry === "string") {
-    return entry;
-  }
-  if (!entry || typeof entry !== "object") {
-    return "";
-  }
-
-  const tag = entry.tagName;
-  const attrs = entry.attributes ?? {};
-  const attrStr = Object.entries(attrs)
-    .map(([k, v]) => (v === true ? k : `${k}="${escapeAttr(v)}"`))
-    .join(" ");
-
-  const open = attrStr ? `<${tag} ${attrStr}>` : `<${tag}>`;
-
-  // Void elements (no closing tag)
-  const VOID = new Set(["meta", "link", "base", "br", "hr", "img", "input"]);
-  if (VOID.has(tag)) {
-    return open;
-  }
-
-  /*
-   * Elements with content. `textContent` may be an OBJECT: that is how a JSON-LD block is authored
-   * (§8.5), and serializing it here is what the spec has always promised. Left as-is it reached the
-   * page as the string "[object Object]".
-   */
-  const raw = Array.isArray(entry.children) ? entry.children.join("") : entry.textContent;
-  const content =
-    raw !== null && typeof raw === "object" ? JSON.stringify(raw, null, 2) : (raw ?? "");
-  return `${open}${content}</${tag}>`;
-}
-
-/**
- * @param {unknown} val
- * @returns {string}
- */
-function escapeAttr(val: unknown) {
-  return String(val).replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;");
-}