@stacksjs/stx 0.2.152 → 0.2.154

package/dist/client-script-bundler.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import fs from "node:fs";
 import { getPublicEnvDefine } from "./public-env.js";
 import { stateDir } from "./state-dir.js";
+import { formatBuildFailure } from "./build-message.js";
 const BUNDLE_CACHE_VERSION = 5, BUNDLE_CACHE_METADATA_VERSION = 1;
 export function shouldLogBundlerDiagnostics(environment = process.env) {
   return environment.STX_DEBUG === "true" || environment.STX_DEBUG === "1";
@@ -267,10 +268,7 @@ ${publicAssignments}`.trim();
     }));
     return bundled;
   } catch (error) {
-    const msg = error instanceof Error ? error.message : String(error), bunErrors = error?.errors, detail = Array.isArray(bunErrors) && bunErrors.length > 0 ? `
-  ${bunErrors.map((e) => `- ${e?.message ?? e}`).join(`
-  `)}` : "";
-    console.warn(`[stx:bundler] error: ${msg}${detail}`);
+    console.warn(`[stx:bundler] error: ${formatBuildFailure(error, filePath || void 0)}`);
     return code;
   } finally {
     try {

package/dist/client-script.d.ts

@@ -46,6 +46,13 @@ export declare function injectBrowserCoreAutoImports(code: string): BrowserCoreA
 /**
  * Blank out comments and string literals, preserving length and line structure
  * so offsets still line up, so that identifier detection only ever sees code.
+ *
+ * Template-literal INTERPOLATIONS are kept, because `${...}` is code, not text.
+ * Blanking them hid every identifier that appears only inside one — a helper
+ * called as `${formatDate(d)}` looked unused to the auto-import scanner, and a
+ * server value read as `` `/api/users/${userId}` `` looked unreferenced to the
+ * data bridge, which would have withheld it and left the client throwing on an
+ * undefined name.
  */
 export declare function stripCommentsAndLiterals(code: string): string;
 /**
@@ -91,6 +98,28 @@ export declare function generateServerDataBridge(code: string, serverData?: Reco
  * @returns A complete `<script>...</script>` tag ready for browser injection
  */
 export declare function processClientScript(scriptContent: string, options?: ClientScriptOptions): Promise<string>;
+/**
+ * Exports from 'stx' auto-imported into classic `<script>` / `<script client>`
+ * blocks.
+ *
+ * Derived from {@link STX_RUNTIME_GLOBALS} rather than hand-maintained (#1804).
+ * This was a separate 82-name literal, and it had drifted: 16 of those names
+ * were not on `window.stx` at all. Because the generated prologue destructures
+ * (`var { … } = window.stx`), a missing name is not an error — it binds
+ * `undefined`, and the author sees "undefined is not a function" at the call
+ * site with nothing naming the identifier or saying why. `provide` worked and
+ * `inject` did not; `onMounted` worked and `onUpdated` did not.
+ *
+ * Five of the 16 (`isDerived`, `inject`, `useSlots`, `watchMultiple`,
+ * `onBeforeMount`) are now implemented in the runtime and live in the shared
+ * list. The remaining 11 are server- or compile-time only — `h` and `Fragment`
+ * belong to the JSX runtime, `useMeta`/`getCurrentInstance`/`useAttrs`/
+ * `onErrorCaptured`/`onBeforeUpdate`/`onUpdated`/`createStore`/`createSelector`
+ * are module exports with no client counterpart, and `action` has no
+ * implementation anywhere — so they are no longer offered. A `ReferenceError`
+ * naming the identifier beats a silent `undefined`.
+ */
+export declare const STX_AUTO_IMPORTS: readonly string[];
 export declare interface VendorCssImport {
   source: string
   resolvedPath: string

package/dist/client-script.js

@@ -1,8 +1,11 @@
 import path from "node:path";
 import fs from "node:fs";
+import { asInvocableStatement } from "./events.js";
 import { transformStoreImports } from "./store-imports.js";
 import { shouldTranspileTypeScript, transpileTypeScript } from "./utils.js";
 import { importOnce } from "./lazy-module.js";
+import { STX_RUNTIME_GLOBALS, usesReactiveRuntime } from "./runtime-globals.js";
+import { escapeScriptBody } from "./script-emit.js";
 const CSS_SIDE_EFFECT_IMPORT_REGEX = /^[ \t]*import\s+['"]([^'"]+?\.css)(\?[^'"]*)?['"]\s*;?\s*$/gm;
 function splitBareSpecifier(spec) {
   if (spec.startsWith(".") || spec.startsWith("/"))
@@ -141,90 +144,8 @@ ${s.contents}
 `)}
 `;
 }
-const STX_AUTO_IMPORTS = [
-  "state",
-  "derived",
-  "effect",
-  "batch",
-  "untrack",
-  "peek",
-  "isSignal",
-  "isDerived",
-  "onMount",
-  "onDestroy",
-  "useRef",
-  "navigate",
-  "goBack",
-  "goForward",
-  "useRoute",
-  "setRouteParams",
-  "useSearchParams",
-  "useFetch",
-  "useQuery",
-  "useMutation",
-  "useOptimistic",
-  "useId",
-  "useReactiveProp",
-  "useLocalStorage",
-  "useSessionStorage",
-  "useCookie",
-  "useWebSocket",
-  "useHead",
-  "useSeoMeta",
-  "definePageMeta",
-  "useEventListener",
-  "useMeta",
-  "useDebounce",
-  "useDebouncedValue",
-  "useThrottle",
-  "useInterval",
-  "useTimeout",
-  "useToggle",
-  "useCounter",
-  "useClickOutside",
-  "useFocus",
-  "useAsync",
-  "useColorMode",
-  "useDark",
-  "useMediaQuery",
-  "useScrollLock",
-  "usePreferredDark",
-  "usePreferredLight",
-  "usePreferredReducedMotion",
-  "usePreferredContrast",
-  "ref",
-  "reactive",
-  "computed",
-  "watch",
-  "watchEffect",
-  "watchMultiple",
-  "onBeforeMount",
-  "onMounted",
-  "onBeforeUpdate",
-  "onUpdated",
-  "onBeforeUnmount",
-  "onUnmounted",
-  "defineProps",
-  "withDefaults",
-  "defineEmits",
-  "defineExpose",
-  "defineSlots",
-  "provide",
-  "inject",
-  "nextTick",
-  "getCurrentInstance",
-  "onErrorCaptured",
-  "useSlots",
-  "useAttrs",
-  "createStore",
-  "defineStore",
-  "registerStoresClient",
-  "useStore",
-  "action",
-  "createSelector",
-  "h",
-  "Fragment"
-], BROWSER_CORE_IMPORTS = [
+export const STX_AUTO_IMPORTS = STX_RUNTIME_GLOBALS;
+const BROWSER_CORE_IMPORTS = [
   "browserQuery",
   "BrowserQueryBuilder",
   "BrowserQueryError",
@@ -342,6 +263,84 @@ const JS_BUILTINS = new Set([
   "Modal",
   "Intl"
 ]);
+function skipQuoted(code, start) {
+  const quote = code[start];
+  let i = start + 1;
+  while (i < code.length) {
+    if (code[i] === "\\") {
+      i += 2;
+      continue;
+    }
+    if (code[i] === quote)
+      return i + 1;
+    i++;
+  }
+  return code.length;
+}
+function skipTemplate(code, start) {
+  let i = start + 1;
+  while (i < code.length) {
+    if (code[i] === "\\") {
+      i += 2;
+      continue;
+    }
+    if (code[i] === "`")
+      return i + 1;
+    if (code[i] === "$" && code[i + 1] === "{") {
+      i = findInterpolationEnd(code, i + 2);
+      if (i < code.length)
+        i++;
+      continue;
+    }
+    i++;
+  }
+  return code.length;
+}
+function findInterpolationEnd(code, start) {
+  let depth = 1, i = start;
+  while (i < code.length) {
+    const ch = code[i];
+    if (ch === "\\") {
+      i += 2;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      i = skipQuoted(code, i);
+      continue;
+    }
+    if (ch === "`") {
+      i = skipTemplate(code, i);
+      continue;
+    }
+    if (ch === "/" && code[i + 1] === "/") {
+      while (i < code.length && code[i] !== `
+`)
+        i++;
+      continue;
+    }
+    if (ch === "/" && code[i + 1] === "*") {
+      i += 2;
+      while (i < code.length && code.slice(i, i + 2) !== "*/")
+        i++;
+      i += 2;
+      continue;
+    }
+    if (ch === "{") {
+      depth++;
+      i++;
+      continue;
+    }
+    if (ch === "}") {
+      depth--;
+      if (depth === 0)
+        return i;
+      i++;
+      continue;
+    }
+    i++;
+  }
+  return code.length;
+}
 export function stripCommentsAndLiterals(code) {
   let out = "", i = 0;
   while (i < code.length) {
@@ -362,7 +361,7 @@ export function stripCommentsAndLiterals(code) {
       continue;
     }
     const ch = code[i];
-    if (ch === '"' || ch === "'" || ch === "`") {
+    if (ch === '"' || ch === "'") {
       const quote = ch;
       out += " ";
       i++;
@@ -374,6 +373,33 @@ export function stripCommentsAndLiterals(code) {
         }
         out += code[i] === `
 ` ? `
+` : " ";
+        i++;
+      }
+      out += " ";
+      i++;
+      continue;
+    }
+    if (ch === "`") {
+      out += " ";
+      i++;
+      while (i < code.length && code[i] !== "`") {
+        if (code[i] === "\\") {
+          out += "  ";
+          i += 2;
+          continue;
+        }
+        if (code[i] === "$" && code[i + 1] === "{") {
+          const bodyStart = i + 2, bodyEnd = findInterpolationEnd(code, bodyStart);
+          out += "  ";
+          out += stripCommentsAndLiterals(code.slice(bodyStart, bodyEnd));
+          if (bodyEnd < code.length)
+            out += " ";
+          i = bodyEnd + 1;
+          continue;
+        }
+        out += code[i] === `
+` ? `
 ` : " ";
         i++;
       }
@@ -535,14 +561,32 @@ function declaresClientIdentifier(code, name) {
       return !0;
   return !1;
 }
+function referencesIdentifier(searchable, name) {
+  return new RegExp(`(?<![.#\\w$])${name}(?![\\w$])`).test(searchable);
+}
+const CREDENTIAL_NAME = /token|secret|passw|apikey|api_key|privatekey|private_key|credential|webhook|bearer|jwt|signature/i, warnedBridgeKeys = new Set;
+function warnAboutBridgedValue(name, json) {
+  const credential = CREDENTIAL_NAME.test(name), oversized = json.length > 32768;
+  if (!credential && !oversized)
+    return;
+  if (warnedBridgeKeys.has(name))
+    return;
+  warnedBridgeKeys.add(name);
+  if (credential)
+    console.warn(`[stx] server\u2192client bridge is publishing "${name}" into the page body. If it holds a credential, rename it with a "__" prefix (never bridged) and pass only what the template needs. See stacksjs/stx#1831.`);
+  if (oversized)
+    console.warn(`[stx] server\u2192client bridge is publishing ${(json.length / 1024).toFixed(1)}KB under "${name}". Every byte ships in the HTML on each request; prefix the binding with "__" and project just the fields the client reads.`);
+}
 export function generateServerDataBridge(code, serverData) {
   if (!serverData)
     return "";
-  const lines = [];
+  const searchable = stripCommentsAndLiterals(code), lines = [];
   for (const [name, value] of Object.entries(serverData)) {
     if (!/^[A-Za-z_$][\w$]*$/.test(name))
       continue;
-    if (!new RegExp(`\\b${name}\\b`).test(code))
+    if (name.startsWith("__") || name.startsWith("$"))
+      continue;
+    if (!referencesIdentifier(searchable, name))
       continue;
     if (declaresClientIdentifier(code, name))
       continue;
@@ -554,6 +598,7 @@ export function generateServerDataBridge(code, serverData) {
     }
     if (json === void 0)
       continue;
+    warnAboutBridgedValue(name, json);
     lines.push(`  var ${name} = ${json.replace(/</g, "\\u003c")};`);
   }
   if (lines.length === 0)
@@ -589,7 +634,7 @@ function generateModifierChecks(modifiers) {
   return checks.join("; ");
 }
 function generateSingleEventBinding(binding, index) {
-  const { elementId, event, handler, modifiers } = binding, checks = generateModifierChecks(modifiers), options = [];
+  const { elementId, event, modifiers } = binding, handler = asInvocableStatement(binding.handler), checks = generateModifierChecks(modifiers), options = [];
   if (modifiers.once)
     options.push("once: true");
   if (modifiers.capture)
@@ -910,19 +955,19 @@ export async function processClientScript(scriptContent, options = {}) {
   if (/\btype\s*=\s*["']module["']/i.test(attrs)) {
     const extraAttrs = attrs.replace(/\btype\s*=\s*["']module["']/i, "").trim(), attrStr = `type="module" data-stx-scoped${extraAttrs ? ` ${extraAttrs}` : ""}`;
     return `${vendorStyleTags}<script ${attrStr}>
-${autoImportCode}${code}
-${eventCode}
+${escapeScriptBody(`${autoImportCode}${code}
+${eventCode}`)}
 </script>`;
   }
-  const usesSignals = /\b(state|derived|effect|ref|reactive|computed|watch|watchEffect|useLocalStorage|useSessionStorage|useRef|useEventListener|useFetch|useDebounce|useDebouncedValue|useThrottle|useInterval|useTimeout|useToggle|useCounter|useClickOutside|useFocus|useAsync|useColorMode|useDark|useWebSocket|useRoute|useSearchParams|onMount|onDestroy|onMounted|onBeforeUnmount|onUnmounted|batch|untrack|peek)\s*(?:<[^>]*>)?\s*\(/.test(scriptContent), isSfcWrapped = /function __stx_setup_/.test(code), alreadyMounts = /\bstx\.mount\s*\(|\bstx\.mountEl\s*\(/.test(scriptContent);
+  const usesSignals = usesReactiveRuntime(scriptContent), isSfcWrapped = /function __stx_setup_/.test(code), alreadyMounts = /\bstx\.mount\s*\(|\bstx\.mountEl\s*\(/.test(scriptContent);
   function wrapInMount(declarations) {
     const returnStmt = declarations.length > 0 ? `
   return { ${declarations.join(", ")} };` : "";
-    return `${vendorStyleTags}<script data-stx-scoped>
+    return `${vendorStyleTags}<script data-stx-scoped data-stx-run="always">
 window.stx.mount(function() {
   'use strict';
-${autoImportCode}${code}
-${eventCode}${returnStmt}
+${escapeScriptBody(`${autoImportCode}${code}
+${eventCode}${returnStmt}`)}
 })</script>`;
   }
   if (!alreadyMounts && !isSfcWrapped) {
@@ -937,10 +982,10 @@ ${eventCode}${returnStmt}
       }
     }
   }
-  return `${vendorStyleTags}<script data-stx-scoped>
+  return `${vendorStyleTags}<script data-stx-scoped data-stx-run="always">
 ;(function() {
   'use strict';
-${autoImportCode}${code}
-${eventCode}
+${escapeScriptBody(`${autoImportCode}${code}
+${eventCode}`)}
 })()</script>`;
 }

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

@@ -21,6 +21,37 @@ export declare function generateColorModeBootScript(options?: ColorModeBootConfi
  * 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;
 /**
  * Pre-paint color-mode bootstrap (stacksjs/stx#1794).
  *
@@ -53,15 +84,17 @@ export declare function injectColorModeBootScript(html: string, options?: ColorM
  * hydration. If they disagree the flash comes back — the boot script would set
  * one thing and hydration would immediately undo it, which is worse than not
  * having a boot script at all. So this mirrors the runtime's `applyDOM` and
- * `readPersisted` precisely, including two limitations that are NOT fixed here:
+ * preference reading precisely:
  *
- *   - `attribute` and `darkClass` are either/or, never both (stacksjs/stx#1788)
- *   - the persisted vocabulary is exactly `light | dark | auto` — `'system'`
- *     is not accepted (also #1788)
+ *   - `attribute` and `darkClass` both apply when both are configured, and
+ *     `darkClass: null` opts out of the class (stacksjs/stx#1788)
+ *   - the accepted vocabulary is `light | dark | auto | system`, with
+ *     `'system'` an alias for `'auto'` (also #1788)
  *
- * Mirroring the limitation is intentional. When #1788 lands, both sides change
- * together; `test/directives/color-mode-boot.test.ts` pins them to the same
- * expectations so drift fails the suite rather than shipping a flash.
+ * `test/directives/color-mode-boot.test.ts` pins both sides to the same
+ * expectations so drift fails the suite rather than shipping a flash. This
+ * script never writes to storage — reading is all it needs, and a write here
+ * would race the composable's own persistence.
  *
  * The script publishes its resolved configuration on `window.__STX_COLOR_MODE__`
  * so a bare `useColorMode()` call picks up the app's configured storage key and
@@ -82,7 +115,10 @@ export declare const COLOR_MODE_BOOT_GLOBAL: '__STX_COLOR_MODE__';
 export declare interface ColorModeBootConfig {
   storageKey?: string
   initialMode?: ColorModeBootMode
-  darkClass?: string
-  attribute?: string
+  darkClass?: string | null
+  attribute?: string | null
+  autoValue?: ColorModeBootAutoValue
 }
-export type ColorModeBootMode = 'light' | 'dark' | 'auto';
+export type ColorModeBootMode = 'light' | 'dark' | 'auto' | 'system';
+/** Spelling written to storage for "follow the system". */
+export type ColorModeBootAutoValue = 'auto' | 'system';

package/dist/color-mode-boot.js

@@ -1,35 +1,75 @@
 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"]), ATTRIBUTE_PATTERN = /^[a-z][\w:-]*$/i, CLASS_PATTERN = /^[\w-]+$/;
+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", initialMode = options.initialMode ?? "auto", darkClass = options.darkClass ?? "dark", attribute = options.attribute ?? null;
+  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(initialMode))
-    throw Error(`colorMode.initialMode must be one of light, dark, auto \u2014 got ${JSON.stringify(initialMode)}`);
-  if (typeof darkClass !== "string" || !CLASS_PATTERN.test(darkClass))
-    throw Error(`colorMode.darkClass must be a single CSS class name \u2014 got ${JSON.stringify(darkClass)}`);
+  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)}`);
-  return { storageKey, initialMode, darkClass, 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;try{var v=localStorage.getItem(c.storageKey);if(v==="light"||v==="dark"||v==="auto")p=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)}else 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,preference:p,mode:m}}catch(e){}}());`;
+  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)}`;
+}
+function bootInsertionPoint(html) {
   const headOpen = /<head\b[^>]*>/i.exec(html);
   if (!headOpen)
-    return html;
+    return null;
   let insertAt = headOpen.index + headOpen[0].length;
-  const afterHead = html.slice(insertAt), charset = /^\s*<meta\b[^>]*\bcharset\b[^>]*>/i.exec(afterHead);
+  const charset = /^\s*<meta\b[^>]*\bcharset\b[^>]*>/i.exec(html.slice(insertAt));
   if (charset)
     insertAt += charset[0].length;
-  const script = generateColorModeBootScript(options);
-  return `${html.slice(0, insertAt)}
-  ${script}${html.slice(insertAt)}`;
+  return insertAt;
+}
+const BOOT_SCRIPT_TAG = new RegExp(`<script\\b[^>]*\\b${COLOR_MODE_BOOT_MARKER}\\b[^>]*>[\\s\\S]*?<\\/script>`, "i"), CHARSET_META = /<meta\b[^>]*\bcharset\b[^>]*>/i;
+function hoistCharsetMeta(html) {
+  const headOpen = /<head\b[^>]*>/i.exec(html);
+  if (!headOpen)
+    return html;
+  const headStart = headOpen.index + headOpen[0].length, headEnd = html.toLowerCase().indexOf("</head>", headStart), head = html.slice(headStart, headEnd === -1 ? html.length : headEnd), meta = CHARSET_META.exec(head);
+  if (!meta || head.slice(0, meta.index).trim() === "")
+    return html;
+  const withoutMeta = head.slice(0, meta.index) + head.slice(meta.index + meta[0].length);
+  return html.slice(0, headStart) + `
+  ${meta[0]}` + withoutMeta + html.slice(headStart + head.length);
+}
+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.js

@@ -32,10 +32,11 @@ export function injectComponentClientFactories(html, context) {
   const repeatedFactories = [...registry].filter(([, factory]) => factory.instances > 1);
   if (repeatedFactories.length === 0)
     return output;
-  const prelude = `<script data-stx-scoped data-stx-component-factories>
+  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]) => `  factories[${JSON.stringify(id)}] = factories[${JSON.stringify(id)}] || ${factory.body};`).join(`
+${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);

package/dist/component-renderer.js

@@ -4,10 +4,12 @@ import { decodeAttributeEntities, decodeStxProp, findComponentTags, parseMultili
 import { maskAtElementPosition, matchHtmlComment } from "./html-masking.js";
 import { renderComponentWithSlot, userComponentFileExists } from "./utils.js";
 import { createSafeFunction, isExpressionSafe, safeEvaluateObject } from "./safe-evaluator.js";
+import { BOOLEAN_ATTRIBUTE_SENTINEL } from "./prop-sentinels.js";
+import { COMPONENT_PASSTHROUGH_X_ATTRS } from "./runtime-globals.js";
 import fs from "node:fs";
 import path from "node:path";
 let builtinsRegistered = !1;
-const BOOLEAN_ATTRIBUTE_SENTINEL = "\x00stx-boolean-attribute", htmlTags = new Set([
+const htmlTags = new Set([
   "a",
   "abbr",
   "address",
@@ -29,6 +31,7 @@ const BOOLEAN_ATTRIBUTE_SENTINEL = "\x00stx-boolean-attribute", htmlTags = new S
   "code",
   "col",
   "colgroup",
+  "component",
   "data",
   "datalist",
   "dd",
@@ -180,24 +183,7 @@ function parseComponentProps(rawProps, context, options) {
     serverDynamic: {},
     clientReactive: {},
     events: {}
-  }, ALPINE_PASSTHROUGH = new Set([
-    "x-cloak",
-    "x-show",
-    "x-if",
-    "x-for",
-    "x-data",
-    "x-init",
-    "x-transition",
-    "x-ref",
-    "x-effect",
-    "x-model",
-    "x-text",
-    "x-html",
-    "x-class",
-    "x-style",
-    "x-on",
-    "x-bind"
-  ]), kebabToCamel = (key) => {
+  }, ALPINE_PASSTHROUGH = new Set(COMPONENT_PASSTHROUGH_X_ATTRS), kebabToCamel = (key) => {
     if (!key.includes("-") || key.startsWith("@") || key.startsWith(":") || key.startsWith("x-") || key.startsWith("__"))
       return key;
     if (key.startsWith("aria-") || key.startsWith("data-"))
@@ -343,6 +329,9 @@ function parseAllAttributes(attributesStr) {
   }
   return props;
 }
+function serialiseForwardedEvents(events) {
+  return Object.entries(events).map(([event, handler]) => handler === BOOLEAN_ATTRIBUTE_SENTINEL ? event : `${event}="${escapeAttribute(handler)}"`).join(" ");
+}
 function escapeAttribute(value) {
   return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
@@ -617,7 +606,7 @@ async function processCustomElementTags(template, context, filePath, options, de
         if (Object.keys(resolvedProps.clientReactive).length > 0)
           rendered = emitClientReactiveAttrs(rendered, resolvedProps.clientReactive);
         if (Object.keys(resolvedProps.events).length > 0) {
-          const eventAttrs = Object.entries(resolvedProps.events).map(([event, handler]) => `${event}="${escapeAttribute(handler)}"`).join(" ");
+          const eventAttrs = serialiseForwardedEvents(resolvedProps.events);
           rendered = rendered.replace(/^(\s*<[a-zA-Z][a-zA-Z0-9-]*)/, `$1 ${eventAttrs}`);
         }
         result = result.substring(0, tag.startIndex) + rendered + result.substring(tag.endIndex);
@@ -636,7 +625,7 @@ async function processCustomElementTags(template, context, filePath, options, de
       if (Object.keys(resolvedProps.events).length > 0) {
         const root = findRenderedComponentRoot(finalContent);
         if (root) {
-          const eventAttrs = Object.entries(resolvedProps.events).map(([event, handler]) => `${event}="${escapeAttribute(handler)}"`).join(" "), parentEvents = Object.keys(resolvedProps.events).map((event) => event.replace(/^@/, "").split(".")[0]).join(" ");
+          const eventAttrs = serialiseForwardedEvents(resolvedProps.events), parentEvents = Object.keys(resolvedProps.events).map((event) => event.replace(/^@/, "").split(".")[0]).join(" ");
           finalContent = finalContent.substring(0, root.insertPos) + ` data-stx-parent-events="${parentEvents}" ${eventAttrs}` + finalContent.substring(root.insertPos);
         }
       }

package/dist/composables/index.d.ts

@@ -16,7 +16,12 @@
  * } from '@stacksjs/stx/composables'
  * ```
  */
-// Storage
+// Storage. `useLocalStorage` / `useSessionStorage` return a Signal<T> matching
+// the runtime contract and the ambient stx.d.ts; the old StorageRef shape was
+// removed in #1797 as part of the dual-impl unification. Migrate `.value` reads
+// to `s()` and `.value = x` writes to `s.set(x)` (`.set()` is unchanged); for
+// `.remove()` / `.subscribe()` / custom serializers use `useStorage`, which
+// still returns a StorageRef.
 export {
   useStorage,
   useLocalStorage,
@@ -340,7 +345,9 @@ export {
   goForward,
   useRoute,
   useSearchParams,
+  type NavigateOptions,
   type RouteInfo,
+  type SearchParamsCommitOptions,
   type SearchParamsRef,
 } from './use-router';
 // Data Fetching (Query / Mutation)