@stacksjs/stx 0.2.152 → 0.2.154

package/dist/dev-server/crosswind.js

@@ -329,21 +329,23 @@ export async function generateCrosswindCSS(htmlContent, appDir) {
     const safelist = [
       ...baseConfig.safelist || [],
       ...userConfig.safelist || []
-    ], crosswindConfig = {
+    ], preflights = [
+      ...baseConfig.preflights || [],
+      ...userConfig.preflights || []
+    ], includePreflight = userConfig.preflight !== !1, minify = userConfig.minify === !0, crosswindConfig = {
       ...baseConfig,
       ...userConfig,
       content: [],
       output: "",
-      preflight: !0,
-      minify: !1,
       theme,
-      safelist
+      safelist,
+      ...preflights.length > 0 && { preflights }
     }, generator = new hw.CSSGenerator(crosswindConfig);
     for (const cls of safelist)
       generator.generate(cls);
     for (const className of classes)
       generator.generate(className);
-    let css = generator.toCSS(!0, !1);
+    let css = generator.toCSS(includePreflight, minify);
     const shortcuts = crosswindConfig.shortcuts || userConfig.shortcuts || {};
     for (const [name, classStr] of Object.entries(shortcuts)) {
       if (!classes.has(name) && !safelist.includes(name))
@@ -352,7 +354,7 @@ export async function generateCrosswindCSS(htmlContent, appDir) {
       for (const p of parts)
         generator.generate(p);
     }
-    css = generator.toCSS(!0, !1);
+    css = generator.toCSS(includePreflight, minify);
     const cssLines = css.split(`
 `);
     for (const [name, classStr] of Object.entries(shortcuts)) {

package/dist/dev-server/serve-app.js

@@ -11,6 +11,8 @@ import {
   stopHmrServer
 } from "../hot-reload.js";
 import { partialsCache } from "../includes.js";
+import { pageShipsSignalsRuntime } from "../runtime-injection.js";
+import { BUILD_ID_HEADER, getBuildId } from "../build-id.js";
 import { stateDir } from "../state-dir.js";
 import { plugin as stxPlugin } from "../plugin.js";
 import { createRouter, matchRoute, formatRoutes, findErrorPage } from "../router.js";
@@ -74,14 +76,16 @@ function serveStaticFile(filePath) {
 export async function serveApp(appDir = ".", options = {}) {
   const port = options.port || 3000, watch = options.watch !== !1, hotReload = options.hotReload !== !1 && watch;
   let hmrServer = null, actualHmrPort = options.hmrPort || port + 1;
-  const absoluteAppDir = path.resolve(appDir), { loadStxConfig } = await import("../index.js"), projectConfig = await loadStxConfig(absoluteAppDir), stxRoot = projectConfig.root && projectConfig.root !== "." ? path.join(absoluteAppDir, projectConfig.root) : absoluteAppDir, pagesDirName = projectConfig.pagesDir || "pages", pagesDir = path.join(stxRoot, pagesDirName);
+  const absoluteAppDir = path.resolve(appDir), { loadStxConfig } = await import("../index.js"), projectConfig = await loadStxConfig(absoluteAppDir), stxRoot = projectConfig.root && projectConfig.root !== "." ? path.join(absoluteAppDir, projectConfig.root) : absoluteAppDir, pagesDirName = options.pagesDir || projectConfig.pagesDir || "pages", pagesDir = path.join(stxRoot, pagesDirName);
   if (!fs.existsSync(pagesDir)) {
-    console.error(`${colors.red}Error: No '${pagesDirName}' directory found in ${colors.bright}${stxRoot}${colors.reset}`);
-    console.log(`${colors.dim}Create a ${pagesDirName}/ directory with .stx files to define your routes.${colors.reset}`);
-    console.log(`${colors.dim}Example: ${pagesDirName}/index.stx for the homepage.${colors.reset}`);
+    console.error(`${colors.red}Error: No '${pagesDirName}' directory found${colors.reset}`);
+    console.log(`${colors.dim}Looked in: ${colors.bright}${pagesDir}${colors.reset}`);
+    console.log(`${colors.dim}Run stx dev from the app directory, pass it as an argument (stx dev <dir>),${colors.reset}`);
+    console.log(`${colors.dim}point at another directory with --pages <dir>, or set pagesDir in stx.config.ts.${colors.reset}`);
+    console.log(`${colors.dim}Starting fresh? Create ${pagesDirName}/index.stx for the homepage.${colors.reset}`);
     return !1;
   }
-  const routes = createRouter(stxRoot);
+  const routes = createRouter(stxRoot, { pagesDir: pagesDirName });
   if (routes.length === 0) {
     console.error(`${colors.red}Error: No page files found in ${colors.bright}${pagesDir}${colors.reset}`);
     return !1;
@@ -254,7 +258,7 @@ export async function serveApp(appDir = ".", options = {}) {
       } else
         output = await processDirectives(templateContent, context, route.filePath, merged, dependencies);
       if (!shell)
-        output = await injectRouterScript(output);
+        output = await injectRouterScript(output, { router: merged.router });
       {
         const { interpolateScriptExpressions } = await import("../expressions.js");
         output = output.replace(/<script\b([^>]*)>([\s\S]*?)<\/script>/g, (full, attrs, body) => {
@@ -433,7 +437,7 @@ export async function serveApp(appDir = ".", options = {}) {
           }
           let content = builtPage.content;
           if (shell && isSpaNavigation(request)) {
-            const layoutMetadata = extractLayoutMetadata(content), titleMatch = content.match(/<title[^>]*>([\s\S]*?)<\/title>/i), pageTitle = titleMatch ? titleMatch[1].trim() : "";
+            const layoutMetadata = extractLayoutMetadata(content), shipsRuntime = pageShipsSignalsRuntime(content), titleMatch = content.match(/<title[^>]*>([\s\S]*?)<\/title>/i), pageTitle = titleMatch ? titleMatch[1].trim() : "";
             if (Object.keys(routeMatch.params).length > 0)
               content = injectRouteParams(content, routeMatch.params);
             content = await injectCrosswindCSS(content, absoluteAppDir);
@@ -446,7 +450,9 @@ export async function serveApp(appDir = ".", options = {}) {
                 "X-STX-Fragment": "true",
                 "X-STX-Layout": layoutMetadata.layout,
                 "X-STX-Layout-Group": layoutMetadata.group,
+                "X-STX-Runtime": shipsRuntime ? "true" : "false",
                 ...pageTitle && { "X-STX-Title": encodeURIComponent(pageTitle) },
+                [BUILD_ID_HEADER]: getBuildId(),
                 "Cache-Control": "no-store, no-cache, must-revalidate"
               }
             });

package/dist/dev-server/serve-markdown.js

@@ -44,7 +44,7 @@ export async function serveMarkdownFile(filePath, options = {}) {
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${data.title || path.basename(absolutePath)}</title>
+  <title>${escapeTitle(data.title || path.basename(absolutePath))}</title>
   <!-- Syntax highlighting styles -->
   <style id="syntax-theme">
     :root {
@@ -279,3 +279,6 @@ Press ${colors.cyan}h${colors.reset} + ${colors.cyan}Enter${colors.reset} to sho
   }
   return !0;
 }
+function escapeTitle(value) {
+  return String(value ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/dist/dev-server/serve-multi.js

@@ -8,6 +8,7 @@ import { partialsCache } from "../includes.js";
 import { stateDir } from "../state-dir.js";
 import { plugin as stxPlugin } from "../plugin.js";
 import { clearComponentCache } from "../utils.js";
+import { formatBuildFailure } from "../build-message.js";
 import { bracketPathToRegex } from "stx-router";
 import {
   colors,
@@ -73,7 +74,7 @@ export async function serveMultipleStxFiles(filePaths, options = {}) {
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${data.title || path.basename(absolutePath)}</title>
+  <title>${escapeTitle(data.title || path.basename(absolutePath))}</title>
   <!-- Syntax highlighting styles -->
   <style id="syntax-theme">
     :root {
@@ -253,25 +254,33 @@ export async function serveMultipleStxFiles(filePaths, options = {}) {
                 };
               });
             }
-          }, result = await Bun.build({
-            entrypoints: [absolutePath],
-            outdir: outputDir,
-            plugins: [publicAssetsPlugin, stxPlugin],
-            define: {
-              "process.env.NODE_ENV": '"development"'
-            },
-            ...options.stxOptions
-          });
-          if (!result.success) {
-            console.error(`${colors.red}Build failed for ${colors.bright}${filePath}${colors.reset}:`, result.logs);
-            continue;
-          }
-          const htmlOutput = result.outputs.find((o) => o.path.endsWith(".html"));
-          if (!htmlOutput) {
-            console.error(`${colors.red}No HTML output found for ${colors.bright}${filePath}${colors.reset}`);
+          };
+          let htmlContent;
+          try {
+            const result = await Bun.build({
+              entrypoints: [absolutePath],
+              outdir: outputDir,
+              plugins: [publicAssetsPlugin, stxPlugin],
+              define: {
+                "process.env.NODE_ENV": '"development"'
+              },
+              ...options.stxOptions
+            });
+            if (!result.success) {
+              console.error(`${colors.red}Build failed for ${colors.bright}${filePath}${colors.reset}:`, formatBuildFailure(result.logs, absolutePath));
+              continue;
+            }
+            const htmlOutput = result.outputs.find((o) => o.path.endsWith(".html"));
+            if (!htmlOutput) {
+              console.error(`${colors.red}No HTML output found for ${colors.bright}${filePath}${colors.reset}`);
+              continue;
+            }
+            htmlContent = await Bun.file(htmlOutput.path).text();
+          } catch (error) {
+            console.error(`${colors.red}Build failed for ${colors.bright}${filePath}${colors.reset}:
+  ${formatBuildFailure(error, absolutePath)}`);
             continue;
           }
-          const htmlContent = await Bun.file(htmlOutput.path).text();
           let routePath = `/${path.relative(commonDir, absolutePath).replace(/\.stx$/, "")}`;
           if (routePath.endsWith("/index"))
             routePath = routePath.slice(0, -6) || "/";
@@ -303,7 +312,7 @@ export async function serveMultipleStxFiles(filePaths, options = {}) {
       }
       return !0;
     } catch (error) {
-      console.error(`${colors.red}Error processing files:${colors.reset}`, error);
+      console.error(`${colors.red}Error processing files:${colors.reset}`, formatBuildFailure(error));
       return !1;
     }
   };
@@ -494,7 +503,7 @@ export async function serveMultipleStxFiles(filePaths, options = {}) {
           if (isRouterRequest) {
             const mainMatch = content.match(/<main[^>]*>([\s\S]*?)<\/main>/i);
             if (mainMatch) {
-              const titleMatch = content.match(/<title[^>]*>([\s\S]*?)<\/title>/i), partialHtml = `<!DOCTYPE html><html><head><title>${titleMatch ? titleMatch[1] : ""}</title></head><body><main>${mainMatch[1]}</main></body></html>`;
+              const titleMatch = content.match(/<title[^>]*>([\s\S]*?)<\/title>/i), title = titleMatch ? titleMatch[1] : "", partialHtml = `<!DOCTYPE html><html><head><title>${escapeTitle(title)}</title></head><body><main>${mainMatch[1]}</main></body></html>`;
               return new Response(partialHtml, {
                 headers: {
                   "Content-Type": "text/html",
@@ -579,3 +588,6 @@ Press ${colors.cyan}h${colors.reset} + ${colors.cyan}Enter${colors.reset} to sho
   }
   return !0;
 }
+function escapeTitle(value) {
+  return String(value ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/dist/dev-server/types.d.ts

@@ -37,8 +37,14 @@ export declare const MIME_TYPES: {
 };
 /**
  * Default dev server options
+ *
+ * `pagesDir` is excluded rather than defaulted: it has no static default. Its
+ * absence is meaningful — it's what lets `stx.config.ts` `pagesDir` apply.
+ * Baking `'pages'` in here would override a configured `views/` for anyone who
+ * spread these defaults (#1781). serveApp resolves it as
+ * option → config → `'pages'`.
  */
-export declare const DEFAULT_DEV_OPTIONS: Required<Omit<DevServerOptions, 'stxOptions' | 'markdown'>>;
+export declare const DEFAULT_DEV_OPTIONS: Required<Omit<DevServerOptions, 'stxOptions' | 'markdown' | 'pagesDir'>>;
 /**
  * Markdown rendering options
  */
@@ -59,6 +65,7 @@ export declare interface DevServerOptions {
   watch?: boolean
   native?: boolean
   titlebarHidden?: boolean
+  pagesDir?: string
   stxOptions?: StxOptions
   markdown?: MarkdownOptions
   cache?: boolean

package/dist/document-shell.d.ts

@@ -1,5 +1,56 @@
 import type { AppHeadConfig } from './types/config-types';
 import type { ColorModeBootConfig } from './color-mode-boot';
+/** 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
@@ -35,6 +86,19 @@ export declare function hoistLeadingHeadTags(content: string): { body: string, h
 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. Crosswind CSS, scoped styles) */
     styles?: string[]
     /** Extra scripts to inject before </body> (e.g. signals runtime, router) */
@@ -67,6 +131,44 @@ export declare function generateDocumentShell(content: string, headConfig?: AppH
  * which made the check spuriously fail and auto-shell wrap the user's
  * complete HTML doc as if it were just body content.
  */
+/**
+ * Does this string OPEN a full HTML document?
+ *
+ * Anchored, but tolerant of what stx's own pipeline prepends: whitespace, HTML
+ * comments, and `<script>` blocks (the signals runtime, scoped setup scripts,
+ * theme guards) all routinely land ahead of a layout's markup.
+ *
+ * The check used to be `/<!DOCTYPE\b/i` — unanchored — so the literal text
+ * `<!DOCTYPE` ANYWHERE made a fragment look like a document and sent it through
+ * wrapper-stripping. Easy to hit on any page that documents HTML: a doctype in
+ * a comment, in a `<pre><code>` sample, or in a JS string (stacksjs#1787). The
+ * `<html>` half was already anchored, so the asymmetry was clearly accidental.
+ *
+ * Note this is the opposite bias from `hasDocumentShell` in document-shell.ts,
+ * which stays permissive on purpose: there, a false negative double-wraps a
+ * complete document, so leaning towards "yes, it's a document" is the safe
+ * direction. Here a false positive shreds a fragment, so it leans the other way.
+ */
+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
@@ -106,3 +208,21 @@ export declare function ensureDocumentShell(html: string, headConfig?: AppHeadCo
  * 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';

package/dist/document-shell.js

@@ -1,5 +1,121 @@
 import { generateColorModeBootScript } from "./color-mode-boot.js";
-export const CLOAK_STYLE = "<style data-stx-cloak>[x-cloak]{display:none !important}</style>";
+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) {
   if (html.includes("data-stx-cloak"))
     return html;
@@ -86,28 +202,32 @@ export function generateDocumentShell(content, headConfig = {}, options = {}) {
     link = [],
     script: headScriptTags = [],
     headRaw = "",
+    htmlAttrs = {},
     bodyClass = "",
     bodyAttrs = {}
-  } = headConfig, pageTitle = options.title || configTitle, metaTags = [...[
+  } = headConfig, pageTitle = options.title || configTitle, defaultMeta = [
     { charset: "UTF-8" },
     { name: "viewport", content: "width=device-width, initial-scale=1.0" }
-  ], ...meta].map((m) => {
-    return `  <meta ${Object.entries(m).map(([k, v]) => `${k}="${v}"`).join(" ")}>`;
+  ], 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 ${Object.entries(l).map(([k, v]) => `${k}="${v}"`).join(" ")}>`;
+    return `  <link ${attrPairs(l)}>`;
   }).join(`
 `), configHeadScripts = headScriptTags.map((s) => {
     if (s.src)
-      return `  <script ${Object.entries(s).filter(([k]) => k !== "content").map(([k, v]) => `${k}="${v}"`).join(" ")}></script>`;
+      return `  <script ${attrPairs(s, (k) => k === "content")}></script>`;
     if (s.content)
       return `  <script>${s.content}</script>`;
     return "";
   }).filter(Boolean).join(`
-`), bodyAttrStr = Object.entries(bodyAttrs).map(([k, v]) => ` ${k}="${v}"`).join(""), bodyClassStr = bodyClass ? ` class="${bodyClass}"` : "", { body: pageBody, hoisted: pageHeadTags } = hoistLeadingHeadTags(content), headParts = [
+`), 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>${pageTitle}</title>`,
+    `  <title>${options.titleIsHtml ? pageTitle : escapeText(pageTitle)}</title>`,
     `  ${CLOAK_STYLE}`,
     linkTags,
     configHeadScripts,
@@ -122,7 +242,7 @@ export function generateDocumentShell(content, headConfig = {}, options = {}) {
     options.bodyStack || ""
   ].filter(Boolean);
   return `<!DOCTYPE html>
-<html lang="${lang}">
+<html${htmlAttrStr}>
 <head>
 ${headParts.join(`
 `)}
@@ -133,8 +253,35 @@ ${bodyParts.join(`
 </body>
 </html>`;
 }
+export function startsDocument(html) {
+  let i = 0;
+  while (i < html.length) {
+    const rest = html.slice(i), ws = rest.match(/^\s+/);
+    if (ws) {
+      i += ws[0].length;
+      continue;
+    }
+    if (rest.startsWith("<!--")) {
+      const end = html.indexOf("-->", i);
+      if (end === -1)
+        return !1;
+      i = end + 3;
+      continue;
+    }
+    const preamble = rest.match(/^<(script|style)\b[^>]*>/i);
+    if (preamble) {
+      const closeTag = `</${preamble[1].toLowerCase()}>`, end = html.toLowerCase().indexOf(closeTag, i + preamble[0].length);
+      if (end === -1)
+        return !1;
+      i = end + closeTag.length;
+      continue;
+    }
+    return /^<!DOCTYPE\b/i.test(rest) || /^<html[\s>]/i.test(rest);
+  }
+  return !1;
+}
 export function hasDocumentShell(html) {
-  return /<!DOCTYPE\b/i.test(html) || /<html[\s>]/i.test(html);
+  return startsDocument(html);
 }
 export function injectConfigHeadTags(html, headConfig = {}) {
   const headCloseIdx = html.lastIndexOf("</head>");
@@ -142,21 +289,21 @@ export function injectConfigHeadTags(html, headConfig = {}) {
     return html;
   const { meta = [], link = [], script = [], headRaw = "" } = headConfig, head = html.slice(0, headCloseIdx), parts = [];
   for (const m of meta) {
-    const dedup = m.name ? `name="${m.name}"` : m.property ? `property="${m.property}"` : m.charset != null ? "charset=" : m["http-equiv"] ? `http-equiv="${m["http-equiv"]}"` : "";
+    const dedup = metaDedupKey(m);
     if (dedup && head.includes(dedup))
       continue;
-    parts.push(`  <meta ${Object.entries(m).map(([k, v]) => `${k}="${v}"`).join(" ")}>`);
+    parts.push(`  <meta ${attrPairs(m)}>`);
   }
   for (const l of link) {
     if (l.href && head.includes(`href="${l.href}"`))
       continue;
-    parts.push(`  <link ${Object.entries(l).map(([k, v]) => `${k}="${v}"`).join(" ")}>`);
+    parts.push(`  <link ${attrPairs(l)}>`);
   }
   for (const s of script)
     if (s.src) {
       if (head.includes(`src="${s.src}"`))
         continue;
-      parts.push(`  <script ${Object.entries(s).filter(([k]) => k !== "content").map(([k, v]) => `${k}="${v}"`).join(" ")}></script>`);
+      parts.push(`  <script ${attrPairs(s, (k) => k === "content")}></script>`);
     } else if (s.content) {
       if (head.includes(s.content))
         continue;