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

package/dist/client.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Hydrate all islands with the given handlers
+ */
+export declare function hydrateIslands(handlers: IslandHandlers): void;
+/**
+ * Add preload links for island scripts
+ */
+export declare function preloadIslandHandlers(handlers: IslandHandlers): void;
+/**
+ * Client-side hydration functionality for stx templates
+ * This file is meant to be used in the browser only
+ */
+/**
+ * Island handler registry
+ */
+declare type IslandHandlers = Record<string, () => Promise<any>>;
+/**
+ * Island hydration function
+ */
+// eslint-disable-next-line pickier/no-unused-vars
+declare type IslandHydrationFn = (element: any, props: any) => void | Promise<void>;

package/dist/client.js

@@ -0,0 +1,73 @@
+const isBrowser = typeof window < "u" && typeof document < "u";
+async function hydrateIsland(element, name, handler) {
+  if (!isBrowser)
+    return;
+  try {
+    const id = element.getAttribute("data-island-id"), propsScript = document.querySelector(`script[data-island-props="${id}"]`), props = propsScript ? JSON.parse(propsScript.textContent || "{}") : {}, module = await handler(), hydrateFn = module.default || module.hydrate;
+    if (typeof hydrateFn !== "function") {
+      console.error(`Island handler for "${name}" does not export a valid hydration function`);
+      return;
+    }
+    await hydrateFn(element, props);
+    element.setAttribute("data-hydrated", "true");
+  } catch (error) {
+    console.error(`Failed to hydrate island "${name}":`, error);
+  }
+}
+export function hydrateIslands(handlers) {
+  if (!isBrowser)
+    return;
+  const islands = document.querySelectorAll("[data-island]"), lazyIslands = [];
+  islands.forEach((island) => {
+    const name = island.getAttribute("data-island"), priority = island.getAttribute("data-priority") || "lazy";
+    if (!name || !handlers[name] || island.getAttribute("data-hydrated") === "true")
+      return;
+    if (priority === "eager")
+      hydrateIsland(island, name, handlers[name]);
+    else
+      lazyIslands.push([island, name]);
+  });
+  if (lazyIslands.length > 0 && "IntersectionObserver" in window) {
+    const observer = new IntersectionObserver((entries) => {
+      entries.forEach((entry) => {
+        if (entry.isIntersecting) {
+          const element = entry.target, name = element.getAttribute("data-island");
+          if (name && handlers[name] && element.getAttribute("data-hydrated") !== "true") {
+            hydrateIsland(element, name, handlers[name]);
+            observer.unobserve(element);
+          }
+        }
+      });
+    }, {
+      rootMargin: "200px",
+      threshold: 0
+    });
+    lazyIslands.forEach(([element]) => {
+      observer.observe(element);
+    });
+  } else
+    setTimeout(() => {
+      lazyIslands.forEach(([element, name]) => {
+        if (element.getAttribute("data-hydrated") !== "true")
+          hydrateIsland(element, name, handlers[name]);
+      });
+    }, 1000);
+}
+export function preloadIslandHandlers(handlers) {
+  if (!isBrowser)
+    return;
+  Object.entries(handlers).forEach(([name, getHandler]) => {
+    try {
+      const moduleMatch = getHandler.toString().match(/import\(['"](.+)['"]\)/);
+      if (moduleMatch && moduleMatch[1]) {
+        const link = document.createElement("link");
+        link.rel = "modulepreload";
+        link.href = moduleMatch[1];
+        link.setAttribute("data-island-module", name);
+        document.head.appendChild(link);
+      }
+    } catch (error) {
+      console.warn(`Failed to preload island handler for "${name}":`, error);
+    }
+  });
+}

package/dist/codemod.d.ts

@@ -0,0 +1,33 @@
+/** Run the codemods over one file's source. */
+export declare function codemodSource(source: string, options?: CodemodOptions): CodemodFileResult;
+/** Human-readable report. */
+export declare function formatCodemodFindings(findings: CodemodFinding[], wrote: boolean): string;
+export declare interface CodemodFinding {
+  file: string
+  line: number
+  rule: CodemodRule
+  applied: boolean
+  reason?: string
+  snippet: string
+}
+export declare interface CodemodFileResult {
+  code: string
+  findings: CodemodFinding[]
+}
+export declare interface CodemodOptions {
+  rules?: CodemodRule[]
+  file?: string
+}
+export type CodemodRule = | 'confirm'
+    | 'alert'
+    | 'tooltip'
+    | 'route-params'
+    | 'search-params'
+    | 'navigate'
+    | 'fetch'
+    | 'polling'
+    | 'debounce'
+    | 'click-outside'
+    | 'focus'
+    | 'clipboard'
+    | 'watch';

package/dist/codemod.js

@@ -0,0 +1,244 @@
+import { stripCommentsAndLiterals } from "./strip-literals.js";
+function contextAfter(source, index, length = 240) {
+  return source.slice(index, index + length);
+}
+const REPORT_RULES = [
+  {
+    rule: "route-params",
+    pattern: /\blocation\s*\.\s*pathname\s*\.\s*(?:match|split)\s*\(/g,
+    primitive: "useRoute() / useRouteParams() / useRouteParam(name)",
+    why: "parsing the URL by hand re-implements the router and does not update on SPA navigation"
+  },
+  {
+    rule: "alert",
+    pattern: /(?<![.#\w$])(?:(?:window|globalThis)\s*\.\s*)?alert\s*\(/g,
+    primitive: "stxAlert(message)",
+    why: "themed, focus-trapped and non-blocking \u2014 but `await` it if the code after it " + "depended on the native dialog blocking until dismissal",
+    reject: (source) => /\b(?:async\s+)?function\s+alert\s*\(/.test(source) || /\b(?:const|let|var)\s+alert\s*=/.test(source)
+  },
+  {
+    rule: "search-params",
+    pattern: /new\s+URLSearchParams\s*\(/g,
+    primitive: "useSearchParams()",
+    why: "reactive, and writes back through the router instead of history.replaceState",
+    reject: (source, index) => {
+      const open = source.indexOf("(", index);
+      if (open === -1)
+        return !0;
+      const arg = source.slice(open + 1, source.indexOf(")", open) + 1);
+      return !/\b(?:location|search|href|url)\b/i.test(arg);
+    }
+  },
+  {
+    rule: "navigate",
+    pattern: /\blocation\s*\.\s*(?:assign|replace)\s*\(|\blocation\s*\.\s*href\s*=/g,
+    primitive: "navigate(path) / goBack()",
+    why: "a full document load throws away every store and the scroll position; navigate() is an SPA transition",
+    reject: (source, index) => /^[^\n]*?(?:['"`]\s*)?(?:mailto:|tel:|sms:|https?:\/\/|\/\/)/.test(contextAfter(source, index, 160))
+  },
+  {
+    rule: "fetch",
+    pattern: /new\s+AbortController\s*\(/g,
+    primitive: "useFetch(url) / useAsyncData(key, fn)",
+    why: "cancellation, loading and error state are already wired; hand-rolling them is where the races live"
+  },
+  {
+    rule: "polling",
+    pattern: /setInterval\s*\(/g,
+    primitive: "useEventSource() / useSSE() / useWebSocket() / useChannel()",
+    why: "polling burns requests and lags; the push primitives are delivered",
+    reject: (source, index) => !/\bfetch\s*\(|\$fetch\b|useFetch\b|\.get\s*\(|axios\b/.test(contextAfter(source, index))
+  },
+  {
+    rule: "debounce",
+    pattern: /\bclearTimeout\s*\(/g,
+    primitive: "useDebounce(fn, ms) / useThrottle(fn, ms)",
+    why: "a hand-held timer handle per call site is the usual source of stale-result bugs",
+    requires: (source) => /setTimeout\s*\(/.test(source)
+  },
+  {
+    rule: "click-outside",
+    pattern: /document\s*\.\s*addEventListener\s*\(\s*['"](?:click|mousedown|pointerdown)['"]/g,
+    primitive: "useClickOutside(ref, fn)",
+    why: "the document-level listener plus the blur race is exactly what this composable exists to remove"
+  },
+  {
+    rule: "focus",
+    pattern: /\.\s*(?:getElementById|querySelector)\s*\([^)]*\)\s*(?:\?\.)?\s*\.?focus\s*\(/g,
+    primitive: "useFocus(ref) with x-ref",
+    why: "a query by id breaks under nested scopes and SPA navigation; a ref does not"
+  },
+  {
+    rule: "clipboard",
+    pattern: /navigator\s*\.\s*(?:clipboard|share)\b/g,
+    primitive: "useClipboard() / useShare()",
+    why: "permission state, the copied flag and the unsupported-browser fallback are already handled"
+  },
+  {
+    rule: "watch",
+    pattern: /\beffect\s*\(\s*\(\s*\)\s*=>\s*\{[^}]*\bvoid\s+\w+\s*\(\s*\)/g,
+    primitive: "watch(source, cb) / watchMultiple([...], cb)",
+    why: "the `void a(); void b()` dance is a manual dependency list; watch takes one directly"
+  }
+], DEFAULT_RULES = ["confirm", "tooltip", ...REPORT_RULES.map((r) => r.rule)];
+function lineOf(source, index) {
+  let line = 1;
+  for (let i = 0;i < index; i++)
+    if (source[i] === `
+`)
+      line++;
+  return line;
+}
+function snippetAt(source, index) {
+  const start = source.lastIndexOf(`
+`, index) + 1, end = source.indexOf(`
+`, index);
+  return source.slice(start, end === -1 ? source.length : end).trim().slice(0, 120);
+}
+function isInsideAsyncFunction(source, index) {
+  const before = source.slice(0, index), fnKeyword = before.lastIndexOf("function"), arrow = before.lastIndexOf("=>"), boundary = Math.max(fnKeyword, arrow);
+  if (boundary === -1)
+    return !1;
+  const window = source.slice(Math.max(0, boundary - 120), boundary);
+  return /\basync\b[^;{}]*$/.test(window);
+}
+function declaresOwnConfirm(source) {
+  return /\b(?:async\s+)?function\s+confirm\s*\(/.test(source) || /\b(?:const|let|var)\s+confirm\s*=/.test(source) || /\bimport\s*\{[^}]*\bconfirm\b[^}]*\}/.test(source);
+}
+function applyConfirmRule(source, file, findings) {
+  if (declaresOwnConfirm(source))
+    return source;
+  const pattern = /(^|[^\w$.])(?:(?:window|globalThis)\s*\.\s*)?confirm\s*\(/g, searchable = searchableSource(source);
+  let out = "", last = 0, match;
+  while ((match = pattern.exec(searchable)) !== null) {
+    const callAt = match.index + match[1].length, line = lineOf(source, callAt), snippet = snippetAt(source, callAt);
+    if (/stxConfirm\s*\($/.test(source.slice(0, callAt + 8)))
+      continue;
+    const safe = isInsideAsyncFunction(source, callAt);
+    findings.push({
+      file,
+      line,
+      rule: "confirm",
+      applied: safe,
+      snippet,
+      reason: safe ? void 0 : "stxConfirm() returns a Promise and native confirm() is synchronous, so this needs `await` inside an async function. Rewriting it here would make the condition always true."
+    });
+    if (safe) {
+      out += source.slice(last, callAt) + "await stxConfirm(";
+      last = callAt + (match[0].length - match[1].length);
+    }
+  }
+  return out + source.slice(last);
+}
+function applyTooltipRule(source, file, findings) {
+  const pattern = /(<[a-z][\w-]*\b[^>]*?)\stitle=(["'])(.*?)\2/gis, searchable = markupSearchable(source);
+  let out = "", last = 0, match;
+  while ((match = pattern.exec(searchable)) !== null) {
+    const [whole, openTag, quote, value] = match, line = lineOf(source, match.index), snippet = snippetAt(source, match.index), tagName = openTag.match(/^<([A-Za-z][\w-]*)/)?.[1] ?? "";
+    if (/^[A-Z]/.test(tagName)) {
+      findings.push({
+        file,
+        line,
+        rule: "tooltip",
+        applied: !1,
+        snippet,
+        reason: `\`title\` on <${tagName}> is a component prop, not an HTML attribute \u2014 ` + "adding x-tooltip here would put a tooltip on a component and may duplicate text it already renders."
+      });
+      continue;
+    }
+    if (/\bx-tooltip[=\s]/.test(openTag) || value.trim() === "") {
+      findings.push({
+        file,
+        line,
+        rule: "tooltip",
+        applied: !1,
+        snippet,
+        reason: /\bx-tooltip[=\s]/.test(openTag) ? "already has x-tooltip" : "empty title"
+      });
+      continue;
+    }
+    findings.push({ file, line, rule: "tooltip", applied: !0, snippet });
+    out += source.slice(last, match.index) + `${openTag} x-tooltip=${quote}${value}${quote} title=${quote}${value}${quote}`;
+    last = match.index + whole.length;
+  }
+  return out + source.slice(last);
+}
+function markupSearchable(source) {
+  return source.replace(/<!--[\s\S]*?-->/g, (match) => match.replace(/[^\n]/g, " ")).replace(/\{\{--[\s\S]*?--\}\}/g, (match) => match.replace(/[^\n]/g, " "));
+}
+function blankJsComments(source) {
+  const blank = (match) => match.replace(/[^\n]/g, " ");
+  return source.replace(/\/\*[\s\S]*?\*\//g, blank).replace(/\/\/[^\n]*/g, blank);
+}
+function searchableSource(source, keepStrings = !1) {
+  const markupOnly = markupSearchable(source);
+  return (keepStrings ? blankJsComments(markupOnly) : stripCommentsAndLiterals(markupOnly)).replace(/<script\b([^>]*)>([\s\S]*?)<\/script\s*>/gi, (match, attrs) => /\bclient\b/i.test(attrs) ? match : match.replace(/[^\n]/g, " "));
+}
+function applyReportRules(source, file, rules, findings) {
+  const codeView = searchableSource(source), stringView = searchableSource(source, !0);
+  for (const entry of REPORT_RULES) {
+    if (!rules.includes(entry.rule))
+      continue;
+    if (entry.requires && !entry.requires(source))
+      continue;
+    entry.pattern.lastIndex = 0;
+    let match;
+    const searchable = /['"]/.test(entry.pattern.source) ? stringView : codeView;
+    entry.pattern.lastIndex = 0;
+    while ((match = entry.pattern.exec(searchable)) !== null) {
+      if (entry.reject?.(source, match.index))
+        continue;
+      findings.push({
+        file,
+        line: lineOf(source, match.index),
+        rule: entry.rule,
+        applied: !1,
+        snippet: snippetAt(source, match.index),
+        reason: `${entry.primitive} \u2014 ${entry.why}`
+      });
+    }
+  }
+}
+export function codemodSource(source, options = {}) {
+  const rules = options.rules ?? DEFAULT_RULES, file = options.file ?? "<source>", findings = [];
+  applyReportRules(source, file, rules, findings);
+  let code = source;
+  if (rules.includes("confirm"))
+    code = applyConfirmRule(code, file, findings);
+  if (rules.includes("tooltip"))
+    code = applyTooltipRule(code, file, findings);
+  findings.sort((a, b) => a.line - b.line);
+  const seen = new Set, unique = findings.filter((finding) => {
+    const key = `${finding.rule}:${finding.line}`;
+    if (seen.has(key))
+      return !1;
+    seen.add(key);
+    return !0;
+  });
+  return { code, findings: unique };
+}
+const REWRITABLE = new Set(["confirm", "tooltip"]);
+export function formatCodemodFindings(findings, wrote) {
+  if (findings.length === 0)
+    return "No hand-rolled equivalents found.";
+  const applied = findings.filter((f) => f.applied), declined = findings.filter((f) => !f.applied && REWRITABLE.has(f.rule)), adopt = findings.filter((f) => !f.applied && !REWRITABLE.has(f.rule)), lines = [];
+  if (applied.length > 0) {
+    lines.push(wrote ? `Rewrote ${applied.length} site(s):` : `Would rewrite ${applied.length} site(s) (pass --fix):`);
+    for (const f of applied)
+      lines.push(`  ${f.file}:${f.line}  [${f.rule}]  ${f.snippet}`);
+  }
+  if (declined.length > 0) {
+    lines.push("", `Needs a human \u2014 ${declined.length} site(s):`);
+    for (const f of declined)
+      lines.push(`  ${f.file}:${f.line}  [${f.rule}]  ${f.snippet}
+      ${f.reason}`);
+  }
+  if (adopt.length > 0) {
+    lines.push("", `An stx primitive already covers this \u2014 ${adopt.length} site(s):`);
+    for (const f of adopt)
+      lines.push(`  ${f.file}:${f.line}  [${f.rule}]  ${f.snippet}
+      use ${f.reason}`);
+  }
+  return lines.join(`
+`);
+}

package/dist/color-mode-boot.d.ts

@@ -0,0 +1,92 @@
+/** Marker attribute — makes injection idempotent and findable by tests. */
+export declare const COLOR_MODE_BOOT_MARKER = "data-stx-color-mode-boot";
+/** The global the boot script publishes its resolved config on. */
+export declare const COLOR_MODE_BOOT_GLOBAL = "__STX_COLOR_MODE__";
+export type ColorModeBootMode = 'light' | 'dark' | 'auto' | 'system';
+/** Spelling written to storage for "follow the system". */
+export type ColorModeBootAutoValue = 'auto' | 'system';
+/**
+ * Pre-paint options. A strict subset of `ColorModeOptions` — only the fields
+ * that affect what lands on the root element before paint. `disableTransitions`
+ * is deliberately absent: nothing has painted yet, so there is no transition to
+ * suppress, and forcing a reflow in the critical path would only cost time.
+ */
+export interface ColorModeBootConfig {
+    /** localStorage key holding the preference. @default 'stx-color-mode' */
+    storageKey?: string;
+    /**
+     * Mode used when nothing valid is stored. @default 'auto'
+     * `'system'` is accepted as an alias for `'auto'`.
+     */
+    initialMode?: ColorModeBootMode;
+    /**
+     * Class applied to `<html>` when dark. @default 'dark'
+     * Pass `null` to opt out — the attribute alone then carries the mode.
+     */
+    darkClass?: string | null;
+    /**
+     * Attribute set to the resolved mode on `<html>`, e.g. `'data-theme'`.
+     * Applied *alongside* `darkClass`, mirroring `useColorMode` (#1788).
+     */
+    attribute?: string | null;
+    /**
+     * Spelling `useColorMode` writes back for "follow the system". Published to
+     * the client so the composable doesn't convert an app's existing `'system'`
+     * key to `'auto'`. @default whatever is stored, else 'auto'
+     */
+    autoValue?: ColorModeBootAutoValue;
+}
+/**
+ * Build the synchronous pre-paint `<script>`.
+ *
+ * Every storage access is wrapped: a sandboxed origin or disabled storage must
+ * degrade to the default mode, never throw. A throw here is unusually costly
+ * because the script sits above the application shell — an uncaught error would
+ * block the rest of the document.
+ */
+export declare function generateColorModeBootScript(options?: ColorModeBootConfig): string;
+/**
+ * Insert the boot script as the first thing in `<head>`.
+ *
+ * Placement matters twice over: the script must run before the browser paints,
+ * and a stylesheet `<link>` above it would block its execution (CSS blocks JS),
+ * delaying the very thing it exists to make early.
+ *
+ * `<meta charset>` is stepped over when it leads the head, so the encoding
+ * declaration keeps its place at the top of the document.
+ *
+ * Idempotent — a document that already carries the marker is returned
+ * unchanged, so this is safe on paths that run it more than once.
+ */
+export declare function injectColorModeBootScript(html: string, options?: ColorModeBootConfig): string;
+/**
+ * Re-assert the ordering of the two head tags whose position is load-bearing:
+ * `<meta charset>` first, then the color-mode boot script, then everything else.
+ *
+ * Run this LAST, after every other head injection. Ordering the injectors
+ * against each other would hold only until the next one is added; re-asserting
+ * the result once at the end holds regardless of what ran before.
+ */
+export declare function normalizeCriticalHeadOrder(html: string): string;
+/**
+ * Move an already-injected boot script back to the top of `<head>`.
+ *
+ * `injectColorModeBootScript` puts it first, but later stages of the pipeline
+ * then insert *ahead* of it and push it down (#1803): the signals runtime is
+ * relocated before the first `<script>` on the page — which is this one — and
+ * the store and composable bundles anchor themselves to the runtime tag. The
+ * boot script ended up fifth, behind all three.
+ *
+ * That is not merely a paint-timing problem. The bundles that overtook it read
+ * `window.__STX_COLOR_MODE__`, which this script publishes, so a `useColorMode()`
+ * inside a store saw `undefined` and silently fell back to the default storage
+ * key and a null attribute — writing the user's preference somewhere the boot
+ * script will never read it back, and never applying the configured attribute.
+ *
+ * Run this last, after every other head injection. Ordering the injectors
+ * against each other would work only until the next one is added; re-asserting
+ * the position once at the end holds regardless of what ran before.
+ *
+ * A no-op when the document has no boot script or it is already in place.
+ */
+export declare function hoistColorModeBootScript(html: string): string;

package/dist/color-mode-boot.js

@@ -0,0 +1,72 @@
+import { headInsertionPoint } from "./head-injection.js";
+export const COLOR_MODE_BOOT_MARKER = "data-stx-color-mode-boot", COLOR_MODE_BOOT_GLOBAL = "__STX_COLOR_MODE__";
+const MODES = new Set(["light", "dark", "auto", "system"]), AUTO_VALUES = new Set(["auto", "system"]), ATTRIBUTE_PATTERN = /^[a-z][\w:-]*$/i, CLASS_PATTERN = /^[\w-]+$/;
+function resolveConfig(options) {
+  const storageKey = options.storageKey ?? "stx-color-mode", rawInitial = options.initialMode ?? "auto", darkClass = options.darkClass === void 0 ? "dark" : options.darkClass, attribute = options.attribute ?? null, autoValue = options.autoValue ?? null;
+  if (typeof storageKey !== "string" || storageKey.length === 0)
+    throw Error("colorMode.storageKey must be a non-empty string");
+  if (!MODES.has(rawInitial))
+    throw Error(`colorMode.initialMode must be one of light, dark, auto, system \u2014 got ${JSON.stringify(rawInitial)}`);
+  if (darkClass !== null && (typeof darkClass !== "string" || !CLASS_PATTERN.test(darkClass)))
+    throw Error(`colorMode.darkClass must be a single CSS class name, or null to opt out \u2014 got ${JSON.stringify(darkClass)}`);
+  if (attribute !== null && (typeof attribute !== "string" || !ATTRIBUTE_PATTERN.test(attribute)))
+    throw Error(`colorMode.attribute must be a valid HTML attribute name \u2014 got ${JSON.stringify(attribute)}`);
+  if (autoValue !== null && !AUTO_VALUES.has(autoValue))
+    throw Error(`colorMode.autoValue must be 'auto' or 'system' \u2014 got ${JSON.stringify(autoValue)}`);
+  if (darkClass === null && attribute === null)
+    throw Error("colorMode needs at least one of darkClass or attribute \u2014 with both null nothing would mark the mode on <html>");
+  return { storageKey, initialMode: rawInitial === "system" ? "auto" : rawInitial, darkClass, attribute, autoValue };
+}
+function serializeForScript(value) {
+  return JSON.stringify(value).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+export function generateColorModeBootScript(options = {}) {
+  const config = resolveConfig(options), body = `(function(){"use strict";var c=${serializeForScript(config)};var p=c.initialMode;var a=c.autoValue;try{var v=localStorage.getItem(c.storageKey);if(v==="light"||v==="dark"){p=v}else if(v==="auto"||v==="system"){p="auto";if(!a)a=v}}catch(e){}var m=p;if(p==="auto"){try{m=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light"}catch(e){m="light"}}var r=document.documentElement;if(c.attribute)r.setAttribute(c.attribute,m);if(c.darkClass){if(m==="dark")r.classList.add(c.darkClass);else r.classList.remove(c.darkClass)}try{window.${COLOR_MODE_BOOT_GLOBAL}={storageKey:c.storageKey,initialMode:c.initialMode,darkClass:c.darkClass,attribute:c.attribute,autoValue:a||"auto",preference:p,mode:m}}catch(e){}}());`;
+  return `<script ${COLOR_MODE_BOOT_MARKER}>${body}</script>`;
+}
+export function injectColorModeBootScript(html, options = {}) {
+  if (html.includes(COLOR_MODE_BOOT_MARKER))
+    return html;
+  const insertAt = bootInsertionPoint(html);
+  if (insertAt === null)
+    return html;
+  const script = generateColorModeBootScript(options);
+  return `${html.slice(0, insertAt)}
+  ${script}${html.slice(insertAt)}`;
+}
+const bootInsertionPoint = headInsertionPoint, BOOT_SCRIPT_TAG = new RegExp(`<script\\b[^>]*\\b${COLOR_MODE_BOOT_MARKER}\\b[^>]*>[\\s\\S]*?<\\/script>`, "i"), CHARSET_META = /<meta\b[^>]*\bcharset\b[^>]*>/gi, HEAD_CLOSE = /<\/head>/gi;
+function hoistCharsetMeta(html) {
+  const headOpen = /<head\b[^>]*>/i.exec(html);
+  if (!headOpen)
+    return html;
+  const headStart = headOpen.index + headOpen[0].length;
+  HEAD_CLOSE.lastIndex = headStart;
+  const headClose = HEAD_CLOSE.exec(html), headEnd = headClose ? headClose.index : html.length;
+  CHARSET_META.lastIndex = headStart;
+  const meta = CHARSET_META.exec(html);
+  if (!meta || meta.index >= headEnd)
+    return html;
+  if (html.slice(headStart, meta.index).trim() === "")
+    return html;
+  const metaEnd = meta.index + meta[0].length;
+  return `${html.slice(0, headStart)}
+  ${meta[0]}${html.slice(headStart, meta.index)}${html.slice(metaEnd, headEnd)}${html.slice(headEnd)}`;
+}
+export function normalizeCriticalHeadOrder(html) {
+  return hoistColorModeBootScript(hoistCharsetMeta(html));
+}
+export function hoistColorModeBootScript(html) {
+  const tag = BOOT_SCRIPT_TAG.exec(html);
+  if (!tag)
+    return html;
+  const target = bootInsertionPoint(html);
+  if (target === null)
+    return html;
+  if (tag.index <= target || html.slice(target, tag.index).trim() === "")
+    return html;
+  const withoutTag = html.slice(0, tag.index) + html.slice(tag.index + tag[0].length), insertAt = bootInsertionPoint(withoutTag);
+  if (insertAt === null)
+    return html;
+  return `${withoutTag.slice(0, insertAt)}
+  ${tag[0]}${withoutTag.slice(insertAt)}`;
+}

package/dist/component-client-factories.d.ts

@@ -0,0 +1,33 @@
+export declare const COMPONENT_CLIENT_FACTORIES_CONTEXT_KEY = "__stx_component_client_factories";
+export declare function initializeComponentClientFactories(context: Record<string, unknown>): void;
+export declare function registerComponentClientFactory(context: Record<string, unknown>, factoryBody: string): string | null;
+export declare function injectComponentClientFactories(html: string, context: Record<string, unknown>): string;
+/**
+ * The registrations a memoised component render would otherwise not make
+ * (stacksjs/stx#1945).
+ *
+ * `instances` decides how a factory reaches the page: at one instance
+ * `injectComponentClientFactories` inlines the definition over the call, and at
+ * more than one it emits a shared prelude instead. So the count is an input to
+ * the document's final bytes, not bookkeeping. A component whose output is
+ * served from a cache never reaches `registerComponentClientFactory`, the count
+ * stays at zero, and the definition is never inlined — the call survives into
+ * the page referring to a factory nothing ever defined, and the component does
+ * not hydrate. The whole page also stops being byte-identical between renders,
+ * which is the property #1945 exists to establish.
+ *
+ * Replaying the registrations on a cache hit keeps the count exactly what a
+ * full render would have produced. Bodies are replayed rather than ids because
+ * the id is derived from the body, so re-registering reproduces it.
+ */
+export declare function snapshotComponentClientFactoryCounts(context: Record<string, unknown>): Map<string, number>;
+/** The factories registered since `before`, with how many instances each gained. */
+export declare function componentClientFactoriesRegisteredSince(context: Record<string, unknown>, before: Map<string, number>): Array<{
+    body: string;
+    count: number;
+}>;
+/** Re-register what a cached render registered, so the instance counts match. */
+export declare function replayComponentClientFactories(context: Record<string, unknown>, registered: Array<{
+    body: string;
+    count: number;
+}>): void;

package/dist/component-client-factories.js

@@ -0,0 +1,77 @@
+import { createHash } from "node:crypto";
+export const COMPONENT_CLIENT_FACTORIES_CONTEXT_KEY = "__stx_component_client_factories";
+function registryFrom(context) {
+  const registry = context[COMPONENT_CLIENT_FACTORIES_CONTEXT_KEY];
+  return registry instanceof Map ? registry : null;
+}
+export function initializeComponentClientFactories(context) {
+  context[COMPONENT_CLIENT_FACTORIES_CONTEXT_KEY] = new Map;
+}
+export function registerComponentClientFactory(context, factoryBody) {
+  const registry = registryFrom(context);
+  if (!registry)
+    return null;
+  const id = createHash("sha256").update(factoryBody).digest("hex").slice(0, 16), existing = registry.get(id);
+  if (existing)
+    existing.instances++;
+  else
+    registry.set(id, { body: factoryBody, instances: 1 });
+  return id;
+}
+export function injectComponentClientFactories(html, context) {
+  const registry = registryFrom(context);
+  if (!registry?.size)
+    return html;
+  const inlinable = new Map;
+  for (const [id, factory] of registry)
+    if (factory.instances === 1)
+      inlinable.set(id, factory.body);
+  let output = html;
+  if (inlinable.size > 0) {
+    const alternation = [...inlinable.keys()].map((id) => JSON.stringify(id).replace(/[$()*+.?[\\\]^{|}]/g, "\\$&")).join("|"), invocation = new RegExp(`window\\.__stxComponentFactories\\[(${alternation})\\]\\(("[^"]+")\\);`, "g");
+    output = output.replace(invocation, (match, idLiteral, scopeId) => {
+      const body = inlinable.get(JSON.parse(idLiteral));
+      return body === void 0 ? match : `(${body})(${scopeId});`;
+    });
+  }
+  const repeatedFactories = [...registry].filter(([, factory]) => factory.instances > 1);
+  if (repeatedFactories.length === 0)
+    return output;
+  const prelude = `<script data-stx-scoped data-stx-run="always" data-stx-component-factories>
+(function() {
+  const factories = window.__stxComponentFactories = window.__stxComponentFactories || {};
+${repeatedFactories.map(([id, factory]) => `  try { factories[${JSON.stringify(id)}] = factories[${JSON.stringify(id)}] || ${factory.body}; }
+  catch (e) { console.error('[stx] component factory ' + ${JSON.stringify(id)} + ' failed to register; instances of it will not hydrate.', e); }`).join(`
+`)}
+})();
+</script>`, firstScopedScript = output.search(/<script\b(?=[^>]*\bdata-stx-scoped\b)/i);
+  if (firstScopedScript < 0)
+    return `${prelude}
+${output}`;
+  return `${output.slice(0, firstScopedScript)}${prelude}
+${output.slice(firstScopedScript)}`;
+}
+export function snapshotComponentClientFactoryCounts(context) {
+  const registry = registryFrom(context), counts = new Map;
+  if (registry)
+    for (const [id, factory] of registry)
+      counts.set(id, factory.instances);
+  return counts;
+}
+export function componentClientFactoriesRegisteredSince(context, before) {
+  const registry = registryFrom(context);
+  if (!registry)
+    return [];
+  const registered = [];
+  for (const [id, factory] of registry) {
+    const gained = factory.instances - (before.get(id) ?? 0);
+    if (gained > 0)
+      registered.push({ body: factory.body, count: gained });
+  }
+  return registered;
+}
+export function replayComponentClientFactories(context, registered) {
+  for (const { body, count } of registered)
+    for (let instance = 0;instance < count; instance++)
+      registerComponentClientFactory(context, body);
+}