@stacksjs/stx 0.2.151 → 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/component-processing.d.ts

@@ -38,6 +38,22 @@ export declare function findComponentTags(html: string, tagPattern: RegExp, skip
  * A legacy HTML-entity-escaped JSON format is still accepted as a fallback so
  * that any externally-produced markup keeps working.
  */
+/**
+ * Decode the entities in a static attribute value.
+ *
+ * An attribute in a template is HTML source, so `title="Tom & Jerry"` names
+ * the string `Tom & Jerry`, and a component that receives it as a prop should
+ * see that string rather than the encoding of it.
+ *
+ * The narrowness is the point. This runs on attribute values, at parse time, and
+ * on nothing else: a value that reached a component any other way - from the
+ * component's own script, from the parent's context, from a `:bound="expression"`
+ * - was never encoded, so decoding it can only destroy escaping somebody meant.
+ * That is exactly what a blanket "this looks like HTML, unescape it" pass over
+ * the component context used to do, and it turned escaped user text back into
+ * live markup.
+ */
+export declare function decodeAttributeEntities(value: string): string;
 export declare function decodeStxProp(attrValue: string, options?: { debug?: boolean }): unknown;
 /**
  * Parse multiline attributes from a component tag

package/dist/component-processing.js

@@ -113,6 +113,9 @@ export function findComponentTags(html, tagPattern, skipTags) {
   }
   return matches;
 }
+export function decodeAttributeEntities(value) {
+  return value.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#0?39;/g, "'").replace(/&#x27;/gi, "'").replace(/&amp;/g, "&");
+}
 export function decodeStxProp(attrValue, options) {
   try {
     const json = Buffer.from(attrValue, "base64").toString("utf8");
@@ -606,7 +609,7 @@ export async function processCustomElements(template, context, filePath, compone
             props[attrName] = result;
           }
         } else
-          props[attrName] = attrValue;
+          props[attrName] = decodeAttributeEntities(attrValue);
       }
       const processedContent = await renderComponentWithSlot(componentPath, props, tag.content, componentsDir, context, filePath, options, processedComponents, dependencies);
       result = result.substring(0, tag.startIndex) + processedContent + result.substring(tag.endIndex);

package/dist/component-renderer.js

@@ -1,6 +1,6 @@
 import { registry } from "./component-registry.js";
 import { registerBuiltins } from "./builtins/index.js";
-import { decodeStxProp, findComponentTags, parseMultilineAttributes, pascalToKebab, restoreStashedScripts, stashScriptElements } from "./component-processing.js";
+import { decodeAttributeEntities, decodeStxProp, findComponentTags, parseMultilineAttributes, pascalToKebab, restoreStashedScripts, stashScriptElements } from "./component-processing.js";
 import { maskAtElementPosition, matchHtmlComment } from "./html-masking.js";
 import { renderComponentWithSlot, userComponentFileExists } from "./utils.js";
 import { createSafeFunction, isExpressionSafe, safeEvaluateObject } from "./safe-evaluator.js";
@@ -287,7 +287,7 @@ function parseComponentProps(rawProps, context, options) {
       }
       continue;
     }
-    setStatic(attrName, attrValue === BOOLEAN_ATTRIBUTE_SENTINEL ? "true" : attrValue);
+    setStatic(attrName, attrValue === BOOLEAN_ATTRIBUTE_SENTINEL ? "true" : decodeAttributeEntities(attrValue));
   }
   return resolved;
 }

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-device-orientation.d.ts

@@ -63,7 +63,7 @@ export declare function useDeviceMotion(): DeviceMotionRef;
  * })
  * ```
  */
-export declare function useParallax(): void;
+export declare function useParallax(): ParallaxRef;
 /**
  * Device Orientation & Motion Composables
  *
@@ -101,6 +101,13 @@ export declare interface DeviceOrientationRef {
   isSupported: () => boolean
   requestPermission: () => Promise<boolean>
 }
+/** Handle returned by {@link useParallax}. */
+export declare interface ParallaxRef {
+  get: () => { x: number, y: number }
+  subscribe: (fn: (state: { x: number, y: number }) => void) => () => void
+  isSupported: () => boolean
+  requestPermission: () => Promise<boolean>
+}
 export declare interface DeviceMotionRef {
   get: () => DeviceMotionState
   subscribe: (fn: (state: DeviceMotionState) => void) => () => void

package/dist/composables/use-event-source.d.ts

@@ -40,7 +40,7 @@ export declare function useEventSource<T = unknown>(url: string | URL, options?:
  * })
  * ```
  */
-export declare function useSSE<T = unknown>(url: string): void;
+export declare function useSSE<T = unknown>(url: string): SSERef<T>;
 export declare interface EventSourceState<T = unknown> {
   status: EventSourceStatus
   data: T | null
@@ -61,6 +61,19 @@ export declare interface EventSourceOptions {
   onMessage?: (event: MessageEvent) => void
   onError?: (event: Event) => void
 }
+/** Handle returned by {@link useSSE}. */
+export declare interface SSERef<T = unknown> {
+  data: {
+    get: () => T | null
+    subscribe: (fn: (data: T | null) => void) => () => void
+  }
+  status: {
+    get: () => EventSourceStatus
+    subscribe: (fn: (status: EventSourceStatus) => void) => () => void
+  }
+  close: () => void
+  open: () => void
+}
 export declare interface EventSourceRef<T = unknown> {
   get: () => EventSourceState<T>
   subscribe: (fn: (state: EventSourceState<T>) => void) => () => void

package/dist/composables/use-eye-dropper.d.ts

@@ -69,7 +69,7 @@ export declare function hexToHsl(hex: string): { h: number, s: number, l: number
 export declare function useColorHistory(options?: {
   maxHistory?: number
   onPick?: (color: string) => void
-}): void;
+}): ColorHistoryRef;
 /**
  * EyeDropper Composables
  *
@@ -89,6 +89,15 @@ export declare interface EyeDropperOptions {
   onAbort?: () => void
   onError?: (error: Error) => void
 }
+/** Handle returned by {@link useColorHistory}. */
+export declare interface ColorHistoryRef {
+  get: () => { current: string | null, history: string[] }
+  subscribe: (fn: (state: { current: string | null, history: string[] }) => void) => () => void
+  pick: () => Promise<string | null>
+  clearHistory: () => void
+  removeFromHistory: (color: string) => void
+  isSupported: () => boolean
+}
 export declare interface EyeDropperRef {
   get: () => EyeDropperState
   subscribe: (fn: (state: EyeDropperState) => void) => () => void

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

@@ -32,7 +32,7 @@ export declare function useIdle(options?: IdleOptions): IdleRef;
  * })
  * ```
  */
-export declare function useIdleState(timeout?: number): void;
+export declare function useIdleState(timeout?: number): IdleStateRef;
 /**
  * Track user's last active timestamp
  *
@@ -45,7 +45,7 @@ export declare function useIdleState(timeout?: number): void;
  * })
  * ```
  */
-export declare function useLastActive(): void;
+export declare function useLastActive(): LastActiveRef;
 /**
  * Auto-logout after idle timeout
  *
@@ -57,7 +57,7 @@ export declare function useLastActive(): void;
  * })
  * ```
  */
-export declare function useAutoLogout(timeout: number, onLogout: () => void, options?: { warningTime?: number, onWarning?: (remainingTime: number) => void }): void;
+export declare function useAutoLogout(timeout: number, onLogout: () => void, options?: { warningTime?: number, onWarning?: (remainingTime: number) => void }): AutoLogoutRef;
 /**
  * Idle Detection Composables
  *
@@ -82,3 +82,21 @@ export declare interface IdleRef {
   reset: () => void
   isIdle: () => boolean
 }
+/** Narrowed view of {@link IdleRef} exposing only the idle flag. */
+export declare interface IdleStateRef {
+  get: () => boolean
+  subscribe: (fn: (isIdle: boolean) => void) => () => void
+  reset: () => void
+}
+/** Narrowed view of {@link IdleRef} exposing only the last-active timestamp. */
+export declare interface LastActiveRef {
+  get: () => number
+  subscribe: (fn: (timestamp: number) => void) => () => void
+  reset: () => void
+}
+/** Handle returned by {@link useAutoLogout}. */
+export declare interface AutoLogoutRef {
+  get: () => IdleState
+  subscribe: (fn: (state: IdleState) => void) => () => void
+  reset: () => void
+}

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

@@ -1,3 +1,4 @@
+import type { Signal } from '../signals-api';
 /**
  * Create a reactive storage reference
  *
@@ -19,13 +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 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'>): void;
+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'>): void;
+export declare function useSessionStorage<T>(key: string, defaultValue: T, options?: Omit<UseStorageOptions<T>, 'storage'>): Signal<T>;
 /**
  * Clear all items from storage
  */
@@ -55,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")

package/dist/composables/use-text-selection.d.ts

@@ -36,7 +36,7 @@ export declare function useTextSelection(options?: TextSelectionOptions): TextSe
  * })
  * ```
  */
-export declare function useElementTextSelection(element: Element | null): void;
+export declare function useElementTextSelection(element: Element | null): ElementTextSelectionRef;
 /**
  * Create a selection popup that appears when text is selected
  *
@@ -56,7 +56,7 @@ export declare function useSelectionPopup(options: {
   onShow?: (text: string, position: { x: number, y: number }) => void
   onHide?: () => void
   minLength?: number
-}): void;
+}): SelectionPopupRef;
 /**
  * Copy selected text to clipboard with custom formatting
  *
@@ -71,7 +71,7 @@ export declare function useSelectionPopup(options: {
  * copy.copyWithPrefix('> ')
  * ```
  */
-export declare function useCopySelection(): void;
+export declare function useCopySelection(): CopySelectionRef;
 /**
  * Text Selection Composables
  *
@@ -87,6 +87,30 @@ export declare interface TextSelectionOptions {
   onSelect?: (state: TextSelectionState) => void
   onClear?: () => void
 }
+/** Handle returned by {@link useElementTextSelection}. */
+export declare interface ElementTextSelectionRef {
+  get: () => string
+  subscribe: (fn: (text: string) => void) => () => void
+  clear: () => void
+  selectAll: () => void
+}
+/** Handle returned by {@link useSelectionPopup}. */
+export declare interface SelectionPopupRef {
+  get: () => TextSelectionState
+  subscribe: (fn: (state: TextSelectionState) => void) => () => void
+  isShowing: () => boolean
+}
+/** Handle returned by {@link useCopySelection}. */
+export declare interface CopySelectionRef {
+  get: () => TextSelectionState
+  subscribe: (fn: (state: TextSelectionState) => void) => () => void
+  copy: () => Promise<boolean>
+  copyAsMarkdown: () => Promise<boolean>
+  copyWithPrefix: (prefix: string) => Promise<boolean>
+  copyWithWrapper: (start: string, end: string) => Promise<boolean>
+  getText: () => string
+  clear: () => void
+}
 export declare interface TextSelectionRef {
   get: () => TextSelectionState
   subscribe: (fn: (state: TextSelectionState) => void) => () => void