fix(storage)!: useLocalStorage returns a Signal on every import path

BREAKING CHANGE: `useLocalStorage` / `useSessionStorage` imported from
`@stacksjs/stx/composables` now return a Signal instead of a StorageRef.

The same identifier had five return shapes. The two that mattered disagreed:
the module path returned a StorageRef (`.value`), the signals runtime returned a
Signal (`s()`), and the ambient stx.d.ts declared the Signal for both. So
`.value` worked or silently yielded `undefined` purely according to which entry
point an import resolved — and a signal from the module impl is invisible to
the runtime anyway, so binding to one never re-rendered.

`useLocalStorage` was also not exported from the package index at all:
`import { useLocalStorage } from '@stacksjs/stx'` failed with TS2614 while
`state`/`derived` imported fine. A `functions/` composable — which stx's own
docs recommend for anything with persistence — therefore had to reach for the
subpath, i.e. the one path returning the other shape. Now exported from the
index alongside `useStorage`, `clearStorage`, `getStorageKeys`, `getStorageSize`.

Follows the precedent #1710 set when it converted `useCookie` from a Vue-style
CookieRef to a Signal, and is pinned the same way by
test/signals/use-storage-parity.test.ts (13 of its 31 cases fail if either impl
drifts).

`useStorage` is deliberately untouched and still returns a StorageRef. Options,
custom serializers, `remove()` and `subscribe()` are genuinely a different,
richer thing, so they keep their own name rather than being folded into a
signal.

Migration is narrower than it looks: Signal already carries a Vue-compatible
`.value` accessor, so `.value` reads, `.value = x` writes and `.set()` all keep
working. Only `.get()` → `s()` and `.remove()` need changing — or switch the
import to `useStorage`.

browser-composables.ts — the source of a third shape, `{ value, remove }`, and
of at least one downstream agent guide teaching that destructure for
<script client> blocks where it yields undefined for both — is now marked
deprecated at module and function level. It is imported by nothing and
re-exported from neither index; it ships only because the package's `./*`
wildcard makes the path resolve. Removal in the next major.

Closes #1797

Author: glennmichael123

docs/api/composables-ref.md

@@ -874,6 +874,35 @@ draftCart.set([...draftCart(), item])
 </script>
 ```
 
+Both return the same signal whether they come from the bare global in a
+`<script client>` block, `import … from '@stacksjs/stx'`, or
+`'@stacksjs/stx/composables'`.
+
+> **Changed in #1797.** The `/composables` subpath used to return a
+> `StorageRef` (`.value`, `.get()`, `.remove()`, `.subscribe()`) while the
+> runtime returned a signal, so `.value` worked or silently yielded `undefined`
+> depending on which entry point an import resolved to. Migration is narrow —
+> `.value` reads, `.value = x` writes and `.set()` all still work, because
+> `Signal` carries a Vue-compatible `.value` accessor. Only `.get()` → `s()`
+> and `.remove()` need changing.
+
+### useStorage
+
+```typescript
+useStorage<T>(key: string, defaultValue: T, options?: UseStorageOptions<T>): StorageRef<T>
+```
+
+The richer object API, unchanged: `.value`, `.get()`, `.set()`, `.remove()`,
+`.subscribe()`, plus `storage: 'local' | 'session'`, a custom `serializer`, and
+`mergeDefaults`. Reach for it when you need `remove()`, a non-JSON encoding, or
+subscription with the previous value; otherwise prefer the signals above.
+
+```ts
+const cart = useStorage('cart', [], { storage: 'session', mergeDefaults: true })
+cart.subscribe((next, prev) => sync(next, prev))
+cart.remove()
+```
+
 ### useCookie
 
 ```typescript

packages/stx/src/browser-composables.ts

@@ -5,6 +5,22 @@
  * Reusable composable functions for browser APIs.
  * All composables follow the `use*` naming convention.
  *
+ * @deprecated Vestigial. Nothing in the repo imports this module and it is not
+ * re-exported from `src/index.ts` or `composables/index.ts` — it ships only
+ * because the package's `./*` wildcard export makes
+ * `@stacksjs/stx/browser-composables` resolve.
+ *
+ * Everything here exists in a canonical form elsewhere, and the duplicates
+ * disagree: `useLocalStorage` here returns `{ value, remove }`, while the
+ * canonical `composables/use-storage.ts` and the signals runtime both return a
+ * Signal. That third shape is a documented source of downstream confusion —
+ * at least one Stacks app's agent guide taught the `{ value, remove }`
+ * destructure for `<script client>` blocks, where it yields `undefined` for
+ * both (stacksjs/stx#1797).
+ *
+ * Import from `@stacksjs/stx` or `@stacksjs/stx/composables` instead. Slated
+ * for removal in the next major.
+ *
  * @module browser-composables
  */
 
@@ -29,6 +45,11 @@ function unref<T>(value: MaybeRef<T>): T {
 /**
  * Reactive localStorage with automatic serialization.
  *
+ * @deprecated Returns `{ value, remove }` — a third shape for this name, and
+ * one the signals runtime cannot see. Use `useLocalStorage` from
+ * `@stacksjs/stx`, which returns a Signal (`s()` reads, `s.set(v)` writes) on
+ * every import path (stacksjs/stx#1797).
+ *
  * @example
  * ```typescript
  * const theme = useLocalStorage('theme', 'dark')
@@ -83,6 +104,9 @@ export function useLocalStorage<T>(
 /**
  * Reactive sessionStorage with automatic serialization.
  *
+ * @deprecated See {@link useLocalStorage} above — use the Signal-returning
+ * version from `@stacksjs/stx` (stacksjs/stx#1797).
+ *
  * @example
  * ```typescript
  * const token = useSessionStorage('auth_token', null)

packages/stx/src/composables/index.ts

@@ -17,7 +17,12 @@
  * ```
  */
 
-// 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,

packages/stx/src/composables/use-storage.ts

@@ -3,7 +3,23 @@
  *
  * Similar to Nuxt's useStorage but for STX applications.
  * Provides a reactive, type-safe wrapper around Web Storage APIs.
+ *
+ * Two shapes live here, deliberately:
+ *
+ *   - `useLocalStorage` / `useSessionStorage` return a **Signal** — 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 is imported (stacksjs/stx#1797).
+ *   - `useStorage` returns a **StorageRef** — `.value`, `.get()`, `.remove()`,
+ *     `.subscribe()`, custom serializers. It is genuinely a different, richer
+ *     thing, so it keeps its own name and shape.
+ *
+ * Parity with the runtime implementation is pinned by
+ * `test/composables/use-storage-parity.test.ts`, following the precedent
+ * #1710 set for `useCookie`.
  */
+import type { Signal } from '../signals-api'
+import { effect, state } from '../signals-api'
 
 export type StorageType = 'local' | 'session'
 
@@ -213,23 +229,124 @@ catch (e) {
 }
 
 /**
- * Shorthand for useStorage with localStorage
+ * Reactive storage binding shared by useLocalStorage / useSessionStorage.
+ *
+ * Mirrors the runtime implementation in `signals.ts` exactly — `state()` seeded
+ * from storage, an `effect()` that persists every change, and a `storage`
+ * listener filtered by both key and storageArea. The runtime is the canonical
+ * contract; this file follows it (stacksjs/stx#1797).
+ */
+function storageSignal<T>(
+  storageType: StorageType,
+  label: string,
+  key: string,
+  defaultValue: T,
+  options: Omit<UseStorageOptions<T>, 'storage'> = {},
+): Signal<T> {
+  const {
+    serializer = defaultSerializer,
+    mergeDefaults = false,
+    listenToStorageChanges = true,
+  } = options
+
+  const isClient = typeof window !== 'undefined'
+  const getStorage = (): Storage | null => {
+    if (!isClient)
+      return null
+    return storageType === 'session' ? sessionStorage : localStorage
+  }
+
+  const parse = (raw: string | null): T => {
+    if (raw === null || raw === undefined)
+      return defaultValue
+    try {
+      const parsed = serializer.read(raw) as T
+      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
+    }
+  }
+
+  const read = (): T => {
+    const store = getStorage()
+    if (!store)
+      return defaultValue
+    try {
+      return parse(store.getItem(key))
+    }
+    catch (e) {
+      console.warn(`[${label}] Cannot read "${key}":`, e)
+      return defaultValue
+    }
+  }
+
+  const signal = state<T>(read())
+
+  effect(() => {
+    const value = signal()
+    const store = getStorage()
+    if (!store)
+      return
+    try {
+      if (value === null || value === undefined)
+        store.removeItem(key)
+      else
+        store.setItem(key, serializer.write(value))
+    }
+    catch (e) {
+      console.warn(`[${label}] Cannot persist "${key}":`, e)
+    }
+  })
+
+  if (isClient && listenToStorageChanges) {
+    // Named binding so it can be removed on scope teardown (#1718). The
+    // storageArea filter stops a sessionStorage write to the same key name
+    // from clobbering a localStorage signal, and vice versa; synthetic events
+    // (tests) leave it null and are still accepted.
+    const onStorage = (event: StorageEvent) => {
+      if (event.key !== key)
+        return
+      if (event.storageArea && event.storageArea !== getStorage())
+        return
+      signal.set(parse(event.newValue))
+    }
+    window.addEventListener('storage', onStorage)
+
+    // eslint-disable-next-line ts/no-explicit-any
+    const maybeOnDestroy = (globalThis as any).onDestroy
+    if (typeof maybeOnDestroy === 'function')
+      maybeOnDestroy(() => window.removeEventListener('storage', onStorage))
+  }
+
+  return signal
+}
+
+/**
+ * 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.
  *
- * 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.
+ * For the richer object API — `.value`, `.remove()`, `.subscribe()`, custom
+ * serializers — use {@link useStorage}, which is unchanged.
  */
-export function useLocalStorage<T>(key: string, defaultValue: T, options?: Omit<UseStorageOptions<T>, 'storage'>): StorageRef<T> {
-  return useStorage(key, defaultValue, { ...options, storage: 'local' })
+export function useLocalStorage<T>(key: string, defaultValue: T, options?: Omit<UseStorageOptions<T>, 'storage'>): Signal<T> {
+  return storageSignal('local', 'useLocalStorage', key, defaultValue, options)
 }
 
 /**
- * Shorthand for useStorage with sessionStorage
+ * Reactive sessionStorage binding. Returns a Signal — see {@link useLocalStorage}.
  */
-export function useSessionStorage<T>(key: string, defaultValue: T, options?: Omit<UseStorageOptions<T>, 'storage'>): StorageRef<T> {
-  return useStorage(key, defaultValue, { ...options, storage: 'session' })
+export function useSessionStorage<T>(key: string, defaultValue: T, options?: Omit<UseStorageOptions<T>, 'storage'>): Signal<T> {
+  return storageSignal('session', 'useSessionStorage', key, defaultValue, options)
 }
 
 /**

packages/stx/src/index.ts

@@ -14,6 +14,22 @@ export { type HydrationOptions } from './hydration'
 // shapes with different field sets; those are kept private to their modules
 // to avoid silently shadowing the user-facing one. Surfaced by stacksjs/stx#1707.
 export { type CookieOptions } from './composables/use-cookie'
+// Storage composables were reachable ONLY via the './composables' subpath, so
+// `import { useLocalStorage } from '@stacksjs/stx'` failed with TS2614 while
+// `state`/`derived` imported fine — and a `functions/` composable (which the
+// docs recommend for anything with persistence) had to reach for the subpath,
+// where the same identifier used to return a different shape. See #1797.
+export {
+  clearStorage,
+  getStorageKeys,
+  getStorageSize,
+  type StorageRef,
+  type StorageType,
+  useLocalStorage,
+  useSessionStorage,
+  useStorage,
+  type UseStorageOptions,
+} from './composables/use-storage'
 export { formatSize, getTotalSize } from './deploy'
 export { type ImageRenderResult, type ImageVariant, type ProcessedImage, clearImageCache, getFallbackVariant, getMimeType, groupVariantsByFormat, optimizeImage, processImage } from './image-optimization'
 export { type AnalysisResult } from './analyzer'