@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/doctor.js

@@ -0,0 +1,123 @@
+import fs from "node:fs";
+import path from "node:path";
+function mtimeMs(p) {
+  try {
+    return fs.statSync(p).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+function ago(ms, now) {
+  const s = Math.max(0, Math.round((now - ms) / 1000));
+  if (s < 60)
+    return `${s}s ago`;
+  if (s < 3600)
+    return `${Math.round(s / 60)}m ago`;
+  return `${Math.round(s / 3600)}h ago`;
+}
+function defaultResolve(specifier, from) {
+  try {
+    return globalThis.Bun?.resolveSync(specifier, from) ?? null;
+  } catch {
+    return null;
+  }
+}
+export function findPantryPackage(cwd, name = "stx") {
+  let dir = path.resolve(cwd);
+  for (let i = 0;i < 10; i++) {
+    const candidate = path.join(dir, "pantry", "@stacksjs", name);
+    if (fs.existsSync(candidate))
+      return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return null;
+}
+export async function runDoctor(options = {}) {
+  const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd(), resolve = options.resolve ?? defaultResolve, now = Date.now(), checks = [], stxEntry = resolve("@stacksjs/stx", cwd);
+  checks.push(stxEntry ? { name: "@stacksjs/stx resolves to", status: "ok", detail: stxEntry } : { name: "@stacksjs/stx resolves to", status: "info", detail: "not resolvable from here (running inside the stx repo, or not installed)" });
+  const pluginEntry = resolve("bun-plugin-stx", cwd);
+  if (pluginEntry)
+    checks.push({ name: "bun-plugin-stx resolves to", status: "ok", detail: pluginEntry });
+  const pantry = findPantryPackage(cwd, "stx");
+  if (!pantry)
+    checks.push({ name: "pantry", status: "info", detail: "no pantry/@stacksjs/stx found \u2014 standard install (nothing to rebuild)" });
+  else {
+    const srcSignals = path.join(pantry, "src/signals.ts"), distEntry = [path.join(pantry, "dist/index.js"), path.join(pantry, "dist/signals.js")].find((p) => fs.existsSync(p)) || null, srcMtime = mtimeMs(srcSignals), distMtime = distEntry ? mtimeMs(distEntry) : null;
+    if (srcMtime == null)
+      checks.push({ name: "pantry dist freshness", status: "info", detail: `found pantry at ${pantry} but no src/signals.ts to compare` });
+    else if (distMtime == null)
+      checks.push({
+        name: "pantry dist freshness",
+        status: "error",
+        detail: "pantry has src but no built dist \u2014 the dev server will resolve nothing (or a stale copy elsewhere)",
+        fix: `cd ${pantry} && bun build.ts`
+      });
+    else if (distMtime < srcMtime) {
+      const lagS = Math.round((srcMtime - distMtime) / 1000);
+      checks.push({
+        name: "pantry dist freshness",
+        status: "error",
+        detail: `dist (${ago(distMtime, now)}) is OLDER than src/signals.ts (${ago(srcMtime, now)}) by ${lagS}s \u2014 your edit isn't built`,
+        fix: `cd ${pantry} && bun build.ts`
+      });
+    } else
+      checks.push({ name: "pantry dist freshness", status: "ok", detail: `dist rebuilt after src (src ${ago(srcMtime, now)}, dist ${ago(distMtime, now)})` });
+    const nm = path.join(cwd, "node_modules/@stacksjs/stx");
+    let lst = null;
+    try {
+      lst = fs.lstatSync(nm);
+    } catch {
+      lst = null;
+    }
+    if (!lst)
+      checks.push({ name: "node_modules \u2192 pantry", status: "info", detail: "node_modules/@stacksjs/stx not present (not installed here)" });
+    else if (lst.isSymbolicLink()) {
+      let target = null;
+      try {
+        target = fs.realpathSync(nm);
+      } catch {}
+      const pantryReal = (() => {
+        try {
+          return fs.realpathSync(pantry);
+        } catch {
+          return pantry;
+        }
+      })();
+      checks.push(target === pantryReal ? { name: "node_modules \u2192 pantry", status: "ok", detail: "symlinked to pantry" } : { name: "node_modules \u2192 pantry", status: "warn", detail: `symlinked to ${target || "(dangling)"}, not pantry` });
+    } else
+      checks.push({
+        name: "node_modules \u2192 pantry",
+        status: "warn",
+        detail: "is a real directory, NOT symlinked to pantry \u2014 edits to pantry src/dist won't be resolved",
+        fix: "rm -rf node_modules/@stacksjs/stx && ln -s ../../pantry/@stacksjs/stx node_modules/@stacksjs/stx"
+      });
+  }
+  checks.push({
+    name: "dev runtime cache",
+    status: "info",
+    detail: "cleared automatically on source edits by the dev watcher (clearDevCaches, #1745 item C)"
+  });
+  if (options.generateRuntime)
+    try {
+      const len = options.generateRuntime().length;
+      checks.push(len > 1000 ? { name: "signals runtime", status: "ok", detail: `generated ${len.toLocaleString()} chars` } : { name: "signals runtime", status: "warn", detail: `generated only ${len} chars \u2014 suspiciously short` });
+    } catch (e) {
+      checks.push({ name: "signals runtime", status: "error", detail: `failed to generate: ${e.message}` });
+    }
+  return { checks, ok: !checks.some((c) => c.status === "error") };
+}
+export function formatDoctorReport(report) {
+  const icon = { ok: "\u2713", warn: "\u26A0", error: "\u2717", info: "\xB7" }, lines = ["stx runtime resolution:"];
+  for (const c of report.checks) {
+    lines.push(`  ${icon[c.status]} ${c.name}: ${c.detail}`);
+    if (c.fix)
+      lines.push(`     \u2192 ${c.fix}`);
+  }
+  lines.push("");
+  lines.push(report.ok ? "\u2713 All framework-runtime layers are aligned." : "\u2717 A runtime layer is stale \u2014 see the fixes above.");
+  return lines.join(`
+`);
+}

package/dist/document-shell.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Document Shell Generator
+ *
+ * Auto-generates the HTML document wrapper around page content.
+ * No .stx file needs to write <!DOCTYPE>, <html>, <head>, or <body>.
+ * The shell is configured via stx.config.ts `app.head` and enhanced
+ * at build/serve time with runtime scripts, CSS, and meta tags.
+ *
+ * @module document-shell
+ */
+import type { ColorModeBootConfig } from './color-mode-boot';
+import type { AppHeadConfig } from './types/config-types';
+/**
+ * Inline x-cloak rule shipped in the SSR <head> (stacksjs/stx#1736).
+ *
+ * Must be parsed by the browser BEFORE first paint — so it goes in the head
+ * as static markup, not injected by the runtime script (which runs after the
+ * body has already painted, the window where false `:if` branches / hidden
+ * `:show` elements flash). The `data-stx-cloak` marker makes injection
+ * idempotent. The runtime's own late injection (signals.ts) is retained as a
+ * belt-and-suspenders for SPA-nav fragments that arrive without SSR head
+ * emission.
+ */
+export declare const CLOAK_STYLE = "<style data-stx-cloak>[x-cloak]{display:none !important}</style>";
+/**
+ * Markers recording which `<html>` attributes stx itself wrote from `htmlAttrs`
+ * (stacksjs/stx#1798).
+ *
+ * The router needs them to reconcile the root element across an SPA layout
+ * change. It cannot just diff `<html>` against the incoming document: by then
+ * the color-mode boot script has added its own `dark` class / `data-theme`, and
+ * `animation.ts` has added `data-reduced-motion`, none of which exist in the
+ * server response — a blind diff would strip them on every navigation and
+ * flash the wrong theme. These say exactly what stx put there, so the router
+ * can remove precisely that much and leave runtime state alone.
+ *
+ * `class` is tracked separately because it is the one attribute that gets
+ * *merged* into at runtime, so it has to be reconciled token-by-token rather
+ * than replaced wholesale.
+ */
+export declare const HTML_ATTRS_MARKER = "data-stx-html-attrs";
+export declare const HTML_CLASS_MARKER = "data-stx-html-class";
+/** Emit `k="v"` pairs with every value attribute-escaped. */
+/**
+ * The identity of a `<meta>` tag, for deduplication.
+ *
+ * Shared by both places that merge config head tags into a page, because they
+ * disagreed: injectConfigHeadTags deduped and generateDocumentShell just
+ * concatenated, so the same `app.head.meta` produced one `<meta charset>` on a
+ * page that owned its document and two on a page built through the shell
+ * (stacksjs/stx#1840). One key, one answer.
+ *
+ * Returns '' for a tag with no identifying attribute, which the callers treat
+ * as "cannot dedup, keep it".
+ */
+export declare function metaDedupKey(m: Record<string, string>): string;
+/**
+ * Build the attribute string for the shell's `<html>` open tag.
+ *
+ * `htmlAttrs.lang` wins over the `lang` option so `useHead({ htmlAttrs: { lang } })`
+ * is not emitted twice (two `lang=` attributes on one element is a parse error
+ * that browsers resolve by keeping the first — i.e. silently ignoring the
+ * more specific one).
+ *
+ * @param htmlAttrs - Attributes from config `app.head.htmlAttrs` / `useHead()`
+ * @param lang - The `lang` option, used unless `htmlAttrs.lang` overrides it
+ * @returns Leading-space-prefixed attribute string, e.g. ` lang="en" class="marketing"`
+ */
+export declare function buildHtmlAttrs(htmlAttrs?: Record<string, string>, lang?: string): string;
+/**
+ * Merge a page's `htmlAttrs` over the config's.
+ *
+ * Per-key override, except `class`, which unions: a global
+ * `app.head.htmlAttrs.class` (`h-full`, a font class, …) shouldn't silently
+ * vanish the moment one page adds a class of its own. Same rule as
+ * `applyHtmlAttrs`, so "class unions, everything else overrides" holds at every
+ * point htmlAttrs are combined.
+ */
+export declare function mergeHtmlAttrs(base?: Record<string, string>, override?: Record<string, string>): Record<string, string>;
+/**
+ * Merge `htmlAttrs` into a document that rendered its OWN `<html>` tag.
+ *
+ * `generateDocumentShell` only runs for pages without a shell, so a page or
+ * layout that writes `<html>` itself — the common case, and what SSG emits —
+ * would otherwise drop `useHead({ htmlAttrs })` entirely. Whether the attribute
+ * lands should not depend on who wrote the document element.
+ *
+ * `class` unions with what the template already put there (the template's own
+ * classes are never dropped); every other attribute is overwritten. Only the
+ * classes stx contributed are recorded in the marker, so an SPA navigation
+ * removes those and leaves the hand-written ones in place.
+ */
+export declare function applyHtmlAttrs(html: string, htmlAttrs?: Record<string, string>): string;
+/**
+ * Insert the inline x-cloak <style> before </head> if a head exists and the
+ * style isn't already present. Idempotent (guards on the data-stx-cloak
+ * marker). No-op when the output has no </head> — those paths fall back to
+ * the runtime's late injection.
+ */
+export declare function injectCloakStyle(html: string): string;
+/**
+ * The same decision as `injectCloakStyle`, without the splice
+ * (stacksjs/stx#1945).
+ *
+ * Returns what belongs before `</head>`, or null when nothing does -- the style
+ * is already present, or there is no head to put it in. A caller collecting
+ * several of these rebuilds the document once instead of once each; the guards
+ * stay here, because whether this applies is this module's business.
+ */
+export declare function cloakStyleFragment(html: string): string | null;
+/**
+ * Pull the page's own `<link>` / `<style>` off the front of a fragment so the
+ * shell can put them in `<head>` where they belong.
+ *
+ * A fragment page (no `<html>/<head>/<body>` of its own) writes its font links
+ * and scoped styles at the top of the file. Without this they land verbatim in
+ * `<body>`, which *renders* fine — browsers honour `<link>` and `<style>` in
+ * body — but breaks SPA navigation: the router reconciles `head style` and
+ * `head link[rel=stylesheet]` only, so on a container-only swap the incoming
+ * page's CSS is never applied and the form/page paints unstyled. It looked
+ * correct on reload and wrong on navigation, which is what made it hard to see.
+ *
+ * Deliberately conservative: only the leading run is hoisted (whitespace,
+ * comments and `<script>` blocks are stepped over, never moved), so a `<style>`
+ * sitting next to the markup it styles further down the page is left alone.
+ */
+export declare function hoistLeadingHeadTags(content: string): {
+    body: string;
+    hoisted: string[];
+};
+/**
+ * Generate the full HTML document shell wrapping page content.
+ *
+ * @param content - The rendered page/layout HTML (no document wrapper)
+ * @param headConfig - Head configuration from stx.config.ts
+ * @param options - Additional options for script/style injection
+ * @returns Complete HTML document
+ */
+export declare function generateDocumentShell(content: string, headConfig?: AppHeadConfig, options?: {
+    /** Page-specific title (overrides config) */
+    title?: string;
+    /**
+     * The title is already HTML and must NOT be escaped again.
+     *
+     * Set when the title was lifted out of author-written markup — an
+     * `@head <title>` block or `@section('title')` — where entities are already
+     * in their final form and any interpolation has already been escaped by
+     * `{{ }}`. Escaping it a second time renders `Caf&eacute; &amp; Bar` as
+     * `Caf&amp;eacute; &amp;amp; Bar`.
+     *
+     * A title from `useHead({ title })` is a plain JS string and must stay
+     * escaped — that is the XSS path (#1792 item 4).
+     */
+    titleIsHtml?: boolean;
+    /** Extra styles to inject in <head> (e.g. Css CSS, scoped styles) */
+    styles?: string[];
+    /** Extra scripts to inject before </body> (e.g. signals runtime, router) */
+    bodyScripts?: string[];
+    /** Extra scripts/tags for <head> */
+    headScripts?: string[];
+    /** Stacks to inject (from @push directives) */
+    headStack?: string;
+    bodyStack?: string;
+    /**
+     * Pre-paint color-mode config (stacksjs/stx#1794). When present, the boot
+     * script is emitted at the very top of <head> — above the stylesheets,
+     * because a stylesheet link ahead of it would block its execution and
+     * delay the one thing it exists to do early.
+     */
+    colorMode?: ColorModeBootConfig;
+}): string;
+export declare function startsDocument(html: string): boolean;
+/**
+ * Does this output already carry a document wrapper?
+ *
+ * ANCHORED, and it has to be. The test used to be an unanchored
+ * `/<html[\s>]/i.test(html)`, so a DOCTYPE or an html tag mentioned ANYWHERE —
+ * including inside an HTML comment — reported a shell that was not there
+ * (stacksjs/stx#1792, part one item 3).
+ *
+ * The cascade was silent and severe: no shell means no `<head>`, so
+ * `injectCloakStyle` bails and every element stx deliberately cloaked renders
+ * VISIBLE; no `<meta name="stx-layout">`; and with neither that meta nor
+ * `data-stx-content` the router's document sniff fails, so every navigation
+ * hard-reloads. One comment mentioning the root element was enough, and the
+ * reporter ended up writing a house rule telling authors not to name the tag in
+ * prose.
+ *
+ * Shares `startsDocument` with the app-shell path, which was anchored for the
+ * same reason in #1787 and had been the outlier's correct twin ever since.
+ */
+export declare function hasDocumentShell(html: string): boolean;
+/**
+ * Inject the config `app.head` tags — script / meta / link / headRaw, but NOT
+ * `title` — into an EXISTING `<head>`.
+ *
+ * `generateDocumentShell` populates config head only when IT builds the shell.
+ * A page whose layout already renders `<html><head>` (the common case, and what
+ * SSG/static builds emit) skips that path, so global config head never lands —
+ * most visibly a site-wide analytics `<script>` (Fathom/Contentsquare/…) that
+ * silently never injects on layout-based or statically-built pages.
+ *
+ * Idempotent: skips a `<script src>`, `<link href>`, meta name/property/charset/
+ * http-equiv, or inline `<script>` content already present in the head, so it's
+ * safe to run even when the layout or `useHead` already emitted the same tag.
+ * `title` is intentionally excluded — the page/layout owns its own title.
+ */
+export declare function injectConfigHeadTags(html: string, headConfig?: AppHeadConfig): string;
+/**
+ * Wrap HTML in a document shell if it doesn't already have one.
+ * This is the main entry point — called at the top level after all
+ * directive processing is complete.
+ *
+ * When the html ALREADY has a shell we don't re-wrap (and don't touch its
+ * head here — the caller injects config-only head via `injectConfigHeadTags`,
+ * so runtime `useHead` tags aren't double-emitted).
+ */
+export declare function ensureDocumentShell(html: string, headConfig?: AppHeadConfig, options?: Parameters<typeof generateDocumentShell>[2], alreadyHasShell?: boolean): string;

package/dist/document-shell.js

@@ -0,0 +1,338 @@
+import { generateColorModeBootScript } from "./color-mode-boot.js";
+export const CLOAK_STYLE = "<style data-stx-cloak>[x-cloak]{display:none !important}</style>", HTML_ATTRS_MARKER = "data-stx-html-attrs", HTML_CLASS_MARKER = "data-stx-html-class";
+const SAFE_ATTR_NAME = /^[A-Za-z_:][\w:.-]*$/;
+function escapeAttr(value) {
+  return String(value).replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function escapeText(value) {
+  return String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+export function metaDedupKey(m) {
+  if (m.name)
+    return `name="${m.name}"`;
+  if (m.property)
+    return `property="${m.property}"`;
+  if (m.charset != null)
+    return "charset=";
+  if (m["http-equiv"])
+    return `http-equiv="${m["http-equiv"]}"`;
+  return "";
+}
+function attrPairs(entries, skip) {
+  return Object.entries(entries).filter(([k]) => !skip?.(k)).map(([k, v]) => `${k}="${escapeAttr(String(v))}"`).join(" ");
+}
+export function buildHtmlAttrs(htmlAttrs = {}, lang = "en") {
+  const rest = [], managed = [];
+  let className = "", resolvedLang = lang;
+  for (const [rawName, value] of Object.entries(htmlAttrs || {})) {
+    if (value == null)
+      continue;
+    const name = rawName.trim();
+    if (!SAFE_ATTR_NAME.test(name))
+      continue;
+    const lower = name.toLowerCase();
+    if (lower === "lang") {
+      resolvedLang = String(value);
+      continue;
+    }
+    if (lower === "class") {
+      className = String(value).trim();
+      continue;
+    }
+    rest.push(` ${name}="${escapeAttr(String(value))}"`);
+    managed.push(name);
+  }
+  let out = ` lang="${escapeAttr(resolvedLang)}"`;
+  if (className)
+    out += ` class="${escapeAttr(className)}"`;
+  out += rest.join("");
+  if (className)
+    out += ` ${HTML_CLASS_MARKER}="${escapeAttr(className)}"`;
+  if (managed.length)
+    out += ` ${HTML_ATTRS_MARKER}="${escapeAttr(managed.join(" "))}"`;
+  return out;
+}
+export function mergeHtmlAttrs(base = {}, override = {}) {
+  const merged = { ...base, ...override };
+  if (base.class && override.class) {
+    const tokens = base.class.split(/\s+/).filter(Boolean);
+    for (const token of override.class.split(/\s+/).filter(Boolean))
+      if (!tokens.includes(token))
+        tokens.push(token);
+    merged.class = tokens.join(" ");
+  }
+  return merged;
+}
+export function applyHtmlAttrs(html, htmlAttrs = {}) {
+  if (!htmlAttrs || Object.keys(htmlAttrs).length === 0)
+    return html;
+  const openTag = html.match(/<html\b([^>]*)>/i);
+  if (!openTag)
+    return html;
+  const existing = {}, order = [], attrRe = /([A-Za-z_:][\w:.-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;
+  let m;
+  while ((m = attrRe.exec(openTag[1])) !== null) {
+    const name = m[1];
+    if (!(name in existing))
+      order.push(name);
+    existing[name] = m[2] ?? m[3] ?? m[4] ?? "";
+  }
+  const addedClasses = [], managed = [];
+  for (const [rawName, value] of Object.entries(htmlAttrs)) {
+    if (value == null)
+      continue;
+    const name = rawName.trim();
+    if (!SAFE_ATTR_NAME.test(name))
+      continue;
+    const lower = name.toLowerCase();
+    if (lower === "class") {
+      const present = (existing.class || "").split(/\s+/).filter(Boolean);
+      for (const token of String(value).split(/\s+/).filter(Boolean))
+        if (!present.includes(token)) {
+          present.push(token);
+          addedClasses.push(token);
+        }
+      if (!("class" in existing))
+        order.push("class");
+      existing.class = present.join(" ");
+      continue;
+    }
+    if (!(name in existing))
+      order.push(name);
+    existing[name] = String(value);
+    if (lower !== "lang")
+      managed.push(name);
+  }
+  if (addedClasses.length) {
+    if (!(HTML_CLASS_MARKER in existing))
+      order.push(HTML_CLASS_MARKER);
+    existing[HTML_CLASS_MARKER] = addedClasses.join(" ");
+  }
+  if (managed.length) {
+    if (!(HTML_ATTRS_MARKER in existing))
+      order.push(HTML_ATTRS_MARKER);
+    existing[HTML_ATTRS_MARKER] = managed.join(" ");
+  }
+  const rebuilt = order.map((name) => ` ${name}="${escapeAttr(existing[name])}"`).join("");
+  return html.replace(openTag[0], () => `<html${rebuilt}>`);
+}
+export function injectCloakStyle(html) {
+  const fragment = cloakStyleFragment(html);
+  if (fragment === null)
+    return html;
+  const headCloseIdx = html.lastIndexOf("</head>");
+  return `${html.slice(0, headCloseIdx)}${fragment}${html.slice(headCloseIdx)}`;
+}
+export function cloakStyleFragment(html) {
+  if (html.includes("data-stx-cloak"))
+    return null;
+  if (html.lastIndexOf("</head>") === -1)
+    return null;
+  return `${CLOAK_STYLE}
+`;
+}
+export function hoistLeadingHeadTags(content) {
+  const hoisted = [];
+  let i = 0;
+  while (i < content.length) {
+    const rest = content.slice(i), ws = rest.match(/^\s+/);
+    if (ws) {
+      i += ws[0].length;
+      continue;
+    }
+    if (rest.startsWith("<!--")) {
+      const end = content.indexOf("-->", i);
+      if (end === -1)
+        break;
+      i = end + 3;
+      continue;
+    }
+    const scriptOpen = rest.match(/^<script\b[^>]*>/i);
+    if (scriptOpen) {
+      const end = content.toLowerCase().indexOf("</script>", i + scriptOpen[0].length);
+      if (end === -1)
+        break;
+      i = end + 9;
+      continue;
+    }
+    const link = rest.match(/^<link\b[^>]*>/i);
+    if (link) {
+      hoisted.push(link[0]);
+      i += link[0].length;
+      continue;
+    }
+    const meta = rest.match(/^<meta\b[^>]*>/i);
+    if (meta) {
+      hoisted.push(meta[0]);
+      i += meta[0].length;
+      continue;
+    }
+    const style = rest.match(/^<style\b[^>]*>[\s\S]*?<\/style>/i);
+    if (style) {
+      hoisted.push(style[0]);
+      i += style[0].length;
+      continue;
+    }
+    break;
+  }
+  if (hoisted.length === 0)
+    return { body: content, hoisted };
+  let body = "", j = 0;
+  while (j < content.length && j < i) {
+    const rest = content.slice(j), link = rest.match(/^<link\b[^>]*>/i);
+    if (link && hoisted.includes(link[0])) {
+      j += link[0].length;
+      continue;
+    }
+    const meta = rest.match(/^<meta\b[^>]*>/i);
+    if (meta && hoisted.includes(meta[0])) {
+      j += meta[0].length;
+      continue;
+    }
+    const style = rest.match(/^<style\b[^>]*>[\s\S]*?<\/style>/i);
+    if (style && hoisted.includes(style[0])) {
+      j += style[0].length;
+      continue;
+    }
+    body += content[j];
+    j++;
+  }
+  body += content.slice(i);
+  return { body, hoisted };
+}
+export function generateDocumentShell(content, headConfig = {}, options = {}) {
+  const {
+    title: configTitle = "stx App",
+    lang = "en",
+    meta = [],
+    link = [],
+    script: headScriptTags = [],
+    headRaw = "",
+    htmlAttrs = {},
+    bodyClass = "",
+    bodyAttrs = {}
+  } = headConfig, pageTitle = options.title || configTitle, defaultMeta = [
+    { charset: "UTF-8" },
+    { name: "viewport", content: "width=device-width, initial-scale=1.0" }
+  ], configuredMetaKeys = new Set(meta.map(metaDedupKey).filter(Boolean)), metaTags = [
+    ...defaultMeta.filter((d) => !configuredMetaKeys.has(metaDedupKey(d))),
+    ...meta
+  ].map((m) => {
+    return `  <meta ${attrPairs(m)}>`;
+  }).join(`
+`), linkTags = link.map((l) => {
+    return `  <link ${attrPairs(l)}>`;
+  }).join(`
+`), configHeadScripts = headScriptTags.map((s) => {
+    if (s.src)
+      return `  <script ${attrPairs(s, (k) => k === "content")}></script>`;
+    if (s.content)
+      return `  <script>${s.content}</script>`;
+    return "";
+  }).filter(Boolean).join(`
+`), htmlAttrStr = buildHtmlAttrs(htmlAttrs, lang), bodyAttrStr = Object.entries(bodyAttrs).map(([k, v]) => ` ${k}="${escapeAttr(String(v))}"`).join(""), bodyClassStr = bodyClass ? ` class="${escapeAttr(bodyClass)}"` : "", { body: pageBody, hoisted: pageHeadTags } = hoistLeadingHeadTags(content), headParts = [
+    metaTags,
+    options.colorMode ? `  ${generateColorModeBootScript(options.colorMode)}` : "",
+    `  <title>${options.titleIsHtml ? pageTitle : escapeText(pageTitle)}</title>`,
+    `  ${CLOAK_STYLE}`,
+    linkTags,
+    configHeadScripts,
+    headRaw ? `  ${headRaw}` : "",
+    ...(options.styles || []).map((s) => `  ${s}`),
+    ...pageHeadTags.map((s) => `  ${s}`),
+    ...(options.headScripts || []).map((s) => `  ${s}`),
+    options.headStack || ""
+  ].filter(Boolean), bodyParts = [
+    pageBody,
+    ...(options.bodyScripts || []).map((s) => s),
+    options.bodyStack || ""
+  ].filter(Boolean);
+  return `<!DOCTYPE html>
+<html${htmlAttrStr}>
+<head>
+${headParts.join(`
+`)}
+</head>
+<body${bodyClassStr}${bodyAttrStr}>
+${bodyParts.join(`
+`)}
+</body>
+</html>`;
+}
+const DOCUMENT_PREFIX_WHITESPACE = /\s+/y, DOCUMENT_PREFIX_PREAMBLE = /<(script|style)\b[^>]*>/iy, DOCUMENT_PREFIX_SCRIPT_CLOSE = /<\/script>/gi, DOCUMENT_PREFIX_STYLE_CLOSE = /<\/style>/gi, DOCUMENT_PREFIX_DOCTYPE = /<!DOCTYPE\b/iy, DOCUMENT_PREFIX_HTML = /<html[\s>]/iy;
+export function startsDocument(html) {
+  let i = 0;
+  while (i < html.length) {
+    DOCUMENT_PREFIX_WHITESPACE.lastIndex = i;
+    if (DOCUMENT_PREFIX_WHITESPACE.exec(html)) {
+      i = DOCUMENT_PREFIX_WHITESPACE.lastIndex;
+      continue;
+    }
+    if (html.startsWith("<!--", i)) {
+      const end = html.indexOf("-->", i);
+      if (end === -1)
+        return !1;
+      i = end + 3;
+      continue;
+    }
+    DOCUMENT_PREFIX_PREAMBLE.lastIndex = i;
+    const preamble = DOCUMENT_PREFIX_PREAMBLE.exec(html);
+    if (preamble) {
+      const close = preamble[1].toLowerCase() === "script" ? DOCUMENT_PREFIX_SCRIPT_CLOSE : DOCUMENT_PREFIX_STYLE_CLOSE;
+      close.lastIndex = DOCUMENT_PREFIX_PREAMBLE.lastIndex;
+      const end = close.exec(html);
+      if (end === null)
+        return !1;
+      i = end.index + end[0].length;
+      continue;
+    }
+    DOCUMENT_PREFIX_DOCTYPE.lastIndex = i;
+    if (DOCUMENT_PREFIX_DOCTYPE.test(html))
+      return !0;
+    DOCUMENT_PREFIX_HTML.lastIndex = i;
+    return DOCUMENT_PREFIX_HTML.test(html);
+  }
+  return !1;
+}
+export function hasDocumentShell(html) {
+  return startsDocument(html);
+}
+export function injectConfigHeadTags(html, headConfig = {}) {
+  const headCloseIdx = html.lastIndexOf("</head>");
+  if (headCloseIdx === -1)
+    return html;
+  const { meta = [], link = [], script = [], headRaw = "" } = headConfig, head = html.slice(0, headCloseIdx), parts = [];
+  for (const m of meta) {
+    const dedup = metaDedupKey(m);
+    if (dedup && head.includes(dedup))
+      continue;
+    parts.push(`  <meta ${attrPairs(m)}>`);
+  }
+  for (const l of link) {
+    if (l.href && head.includes(`href="${l.href}"`))
+      continue;
+    parts.push(`  <link ${attrPairs(l)}>`);
+  }
+  for (const s of script)
+    if (s.src) {
+      if (head.includes(`src="${s.src}"`))
+        continue;
+      parts.push(`  <script ${attrPairs(s, (k) => k === "content")}></script>`);
+    } else if (s.content) {
+      if (head.includes(s.content))
+        continue;
+      parts.push(`  <script>${s.content}</script>`);
+    }
+  if (headRaw && !head.includes(headRaw))
+    parts.push(`  ${headRaw}`);
+  if (parts.length === 0)
+    return html;
+  return `${html.slice(0, headCloseIdx)}${parts.join(`
+`)}
+${html.slice(headCloseIdx)}`;
+}
+export function ensureDocumentShell(html, headConfig = {}, options = {}, alreadyHasShell) {
+  if (alreadyHasShell ?? hasDocumentShell(html))
+    return html;
+  return generateDocumentShell(html, headConfig, options);
+}