@stacksjs/stx 0.2.152 → 0.2.153

package/dist/client-script.js

@@ -918,7 +918,7 @@ ${eventCode}
   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}
@@ -937,7 +937,7 @@ ${eventCode}${returnStmt}
       }
     }
   }
-  return `${vendorStyleTags}<script data-stx-scoped>
+  return `${vendorStyleTags}<script data-stx-scoped data-stx-run="always">
 ;(function() {
   'use strict';
 ${autoImportCode}${code}

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

@@ -53,15 +53,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 +84,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,22 +1,26 @@
 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 = {}) {

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/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,

package/dist/composables/use-color-mode.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Map any accepted spelling onto the canonical vocabulary, or null if the value
+ * is not a color-mode preference at all.
+ */
+export declare function normalizeColorMode(value: unknown): ColorMode | null;
 /**
  * Full-featured color-mode manager.
  *
@@ -21,16 +26,17 @@ export declare function useColorMode(options?: ColorModeOptions): ColorModeRef;
 export declare function useDark(options?: ColorModeOptions): DarkRef;
 export declare interface ColorModeOptions {
   storageKey?: string
-  initialMode?: ColorMode
-  darkClass?: string
-  attribute?: string
+  initialMode?: ColorModeInput
+  darkClass?: string | null
+  attribute?: string | null
+  autoValue?: AutoValue
   disableTransitions?: boolean
 }
 export declare interface ColorModeRef {
   readonly mode: 'light' | 'dark'
   readonly preference: ColorMode
   readonly isDark: boolean
-  set: (mode: ColorMode) => void
+  set: (mode: ColorModeInput) => void
   toggle: () => void
   subscribe: (fn: (mode: 'light' | 'dark', preference: ColorMode) => void) => () => void
 }
@@ -50,3 +56,12 @@ export declare interface DarkRef {
 // Types
 // =============================================================================
 export type ColorMode = 'light' | 'dark' | 'auto';
+/**
+ * What may be *written* into storage for "follow the system".
+ *
+ * `'system'` is a common spelling for the same concept, and an app that already
+ * persists it must not have that overwritten (stacksjs/stx#1788).
+ */
+export type AutoValue = 'auto' | 'system';
+/** Accepted on input anywhere a ColorMode is; normalised to ColorMode. */
+export type ColorModeInput = ColorMode | 'system';

package/dist/composables/use-color-mode.js

@@ -1,12 +1,21 @@
+const AUTO_VALUES = ["auto", "system"];
+export function normalizeColorMode(value) {
+  if (value === "light" || value === "dark")
+    return value;
+  if (typeof value === "string" && AUTO_VALUES.includes(value))
+    return "auto";
+  return null;
+}
 export function useColorMode(options = {}) {
   const boot = typeof window < "u" ? window.__STX_COLOR_MODE__ : null, {
     storageKey = boot?.storageKey ?? "stx-color-mode",
     initialMode = boot?.initialMode ?? "auto",
     darkClass = boot?.darkClass ?? "dark",
-    attribute = boot?.attribute,
+    attribute = boot?.attribute ?? null,
+    autoValue: autoValueOption = boot?.autoValue,
     disableTransitions = !0
   } = options;
-  let preference = initialMode, resolved = "light";
+  let preference = normalizeColorMode(initialMode) ?? "auto", resolved = "light";
   const listeners = new Set, cleanups = [], isBrowser = typeof window < "u";
   function getSystemPreference() {
     if (!isBrowser)
@@ -24,41 +33,43 @@ export function useColorMode(options = {}) {
       el.style.setProperty("transition", "none", "important");
     if (attribute)
       el.setAttribute(attribute, mode);
-    else if (mode === "dark")
-      el.classList.add(darkClass);
-    else
-      el.classList.remove(darkClass);
+    if (darkClass)
+      if (mode === "dark")
+        el.classList.add(darkClass);
+      else
+        el.classList.remove(darkClass);
     if (disableTransitions) {
       el.offsetHeight;
       el.style.removeProperty("transition");
     }
   }
-  function persist(pref) {
+  function readRaw() {
     if (!isBrowser)
-      return;
+      return null;
     try {
-      localStorage.setItem(storageKey, pref);
-    } catch {}
+      return localStorage.getItem(storageKey);
+    } catch {
+      return null;
+    }
   }
-  function readPersisted() {
+  const storedRaw = readRaw();
+  let autoValue = autoValueOption ?? (storedRaw !== null && AUTO_VALUES.includes(storedRaw) ? storedRaw : "auto");
+  function persist(pref) {
     if (!isBrowser)
-      return null;
+      return;
     try {
-      const v = localStorage.getItem(storageKey);
-      if (v === "light" || v === "dark" || v === "auto")
-        return v;
+      localStorage.setItem(storageKey, pref === "auto" ? autoValue : pref);
     } catch {}
-    return null;
   }
-  function update(pref) {
-    preference = pref;
-    resolved = resolve(pref);
+  function update(pref, persistChoice = !0) {
+    preference = normalizeColorMode(pref) ?? "auto";
+    resolved = resolve(preference);
     applyToDOM(resolved);
-    persist(pref);
+    if (persistChoice)
+      persist(preference);
     listeners.forEach((fn) => fn(resolved, preference));
   }
-  const persisted = readPersisted();
-  update(persisted ?? initialMode);
+  update(normalizeColorMode(storedRaw) ?? initialMode, !1);
   if (isBrowser) {
     const mql = window.matchMedia("(prefers-color-scheme: dark)"), onSystemChange = () => {
       if (preference === "auto") {
@@ -72,8 +83,10 @@ export function useColorMode(options = {}) {
     const onStorage = (e) => {
       if (e.key !== storageKey)
         return;
-      const v = e.newValue;
-      if (v === "light" || v === "dark" || v === "auto") {
+      const v = normalizeColorMode(e.newValue);
+      if (v) {
+        if (v === "auto" && e.newValue && AUTO_VALUES.includes(e.newValue))
+          autoValue = e.newValue;
         preference = v;
         resolved = resolve(v);
         applyToDOM(resolved);

package/dist/composables/use-storage.d.ts

@@ -1,3 +1,4 @@
+import type { Signal } from '../signals-api';
 /**
  * Create a reactive storage reference
  *
@@ -19,19 +20,23 @@
  */
 export declare function useStorage<T>(key: string, defaultValue: T, options?: UseStorageOptions<T>): StorageRef<T>;
 /**
- * Shorthand for useStorage with localStorage
+ * Reactive localStorage binding. Returns a Signal: `s()` reads, `s.set(v)`
+ * writes and persists.
  *
- * The return type is annotated rather than inferred on purpose: the shipped
- * declarations are emitted by bun-plugin-dtsx, which resolves an unannotated
- * export to `void`. Consumers importing from `@stacksjs/stx/composables` then
- * got `Property 'value' does not exist on type 'void'` for a function that
- * plainly returns a StorageRef. See stacksjs/stx#1796.
+ * The same shape the ambient `stx.d.ts` declares and the same shape a
+ * `<script client>` block gets from `window.stx` — one identifier, one
+ * contract, whichever way it's imported (stacksjs/stx#1797). It used to return
+ * a `StorageRef` here and a signal there, so `.value` worked or silently
+ * yielded `undefined` depending on which entry point resolved.
+ *
+ * For the richer object API — `.value`, `.remove()`, `.subscribe()`, custom
+ * serializers — use {@link useStorage}, which is unchanged.
  */
-export declare function useLocalStorage<T>(key: string, defaultValue: T, options?: Omit<UseStorageOptions<T>, 'storage'>): StorageRef<T>;
+export declare function useLocalStorage<T>(key: string, defaultValue: T, options?: Omit<UseStorageOptions<T>, 'storage'>): Signal<T>;
 /**
- * Shorthand for useStorage with sessionStorage
+ * Reactive sessionStorage binding. Returns a Signal — see {@link useLocalStorage}.
  */
-export declare function useSessionStorage<T>(key: string, defaultValue: T, options?: Omit<UseStorageOptions<T>, 'storage'>): StorageRef<T>;
+export declare function useSessionStorage<T>(key: string, defaultValue: T, options?: Omit<UseStorageOptions<T>, 'storage'>): Signal<T>;
 /**
  * Clear all items from storage
  */
@@ -61,10 +66,4 @@ export declare interface StorageRef<T> {
   remove: () => void
   subscribe: (callback: (value: T, prev: T | undefined) => void) => () => void
 }
-/**
- * useStorage - Reactive localStorage/sessionStorage composable
- *
- * Similar to Nuxt's useStorage but for STX applications.
- * Provides a reactive, type-safe wrapper around Web Storage APIs.
- */
 export type StorageType = 'local' | 'session';

package/dist/composables/use-storage.js

@@ -1,3 +1,4 @@
+import { effect, state } from "../signals-api.js";
 const defaultSerializer = {
   read: (value) => {
     try {
@@ -106,11 +107,71 @@ export function useStorage(key, defaultValue, options = {}) {
   };
   return ref;
 }
+function storageSignal(storageType, label, key, defaultValue, options = {}) {
+  const {
+    serializer = defaultSerializer,
+    mergeDefaults = !1,
+    listenToStorageChanges = !0
+  } = options, isClient = typeof window < "u", getStorage = () => {
+    if (!isClient)
+      return null;
+    return storageType === "session" ? sessionStorage : localStorage;
+  }, parse = (raw) => {
+    if (raw === null || raw === void 0)
+      return defaultValue;
+    try {
+      const parsed = serializer.read(raw);
+      if (mergeDefaults && typeof defaultValue === "object" && defaultValue !== null)
+        return { ...defaultValue, ...parsed };
+      return parsed;
+    } catch (e) {
+      console.warn(`[${label}] Failed to read key "${key}":`, e);
+      return defaultValue;
+    }
+  }, signal = state((() => {
+    const store = getStorage();
+    if (!store)
+      return defaultValue;
+    try {
+      return parse(store.getItem(key));
+    } catch (e) {
+      console.warn(`[${label}] Cannot read "${key}":`, e);
+      return defaultValue;
+    }
+  })());
+  effect(() => {
+    const value = signal(), store = getStorage();
+    if (!store)
+      return;
+    try {
+      if (value === null || value === void 0)
+        store.removeItem(key);
+      else
+        store.setItem(key, serializer.write(value));
+    } catch (e) {
+      console.warn(`[${label}] Cannot persist "${key}":`, e);
+    }
+  });
+  if (isClient && listenToStorageChanges) {
+    const onStorage = (event) => {
+      if (event.key !== key)
+        return;
+      if (event.storageArea && event.storageArea !== getStorage())
+        return;
+      signal.set(parse(event.newValue));
+    };
+    window.addEventListener("storage", onStorage);
+    const maybeOnDestroy = globalThis.onDestroy;
+    if (typeof maybeOnDestroy === "function")
+      maybeOnDestroy(() => window.removeEventListener("storage", onStorage));
+  }
+  return signal;
+}
 export function useLocalStorage(key, defaultValue, options) {
-  return useStorage(key, defaultValue, { ...options, storage: "local" });
+  return storageSignal("local", "useLocalStorage", key, defaultValue, options);
 }
 export function useSessionStorage(key, defaultValue, options) {
-  return useStorage(key, defaultValue, { ...options, storage: "session" });
+  return storageSignal("session", "useSessionStorage", key, defaultValue, options);
 }
 export function clearStorage(type = "local") {
   if (typeof window > "u")