@fluixi/core 1.0.0-alpha.91 → 1.0.0-alpha.93

package/dist/src/lib/storage/cache.js

@@ -0,0 +1,42 @@
+/**
+ * A `cachedResource` cache kept in a storage, so fetched data outlives the page: session
+ * storage for the tab, local storage across visits. Values pass through the storage's
+ * serializer, so they must be plain data. In-flight fetches stay in memory.
+ *
+ * Give it its own namespace, since `clearCachedResources()` clears that storage, and a `ttl`
+ * so entries do not pile up after the resource that wrote them is gone.
+ *
+ * @example
+ * const cache = storageCache(useStorage({ scope: 'session', namespace: 'cache' }), { ttl: 10 * 60_000 });
+ * const orgs = cachedResource(() => api.get('/orgs'), { name: 'orgs', ttl: 60_000, cache });
+ */
+export function storageCache(storage, options = {}) {
+    const inflight = new Map();
+    return {
+        get(key) {
+            try {
+                const entry = storage.getEntry(key);
+                return entry ? { value: entry.value, timestamp: entry.createdAt } : undefined;
+            }
+            catch {
+                // Unreadable or blocked: a miss, and the resource fetches.
+                return undefined;
+            }
+        },
+        set(key, entry) {
+            try {
+                storage.set(key, entry.value, options.ttl !== undefined ? { ttl: options.ttl } : undefined);
+            }
+            catch {
+                /* quota, or a value the serializer refuses: kept for this page only by the fetch itself */
+            }
+        },
+        delete: (key) => storage.remove(key),
+        keys: () => storage.keys(),
+        clear() {
+            storage.clear();
+            inflight.clear();
+        },
+        inflight,
+    };
+}

package/dist/src/lib/storage/cache.mjs

@@ -0,0 +1,30 @@
+// src/lib/storage/cache.ts
+function storageCache(storage, options = {}) {
+  const inflight = /* @__PURE__ */ new Map();
+  return {
+    get(key) {
+      try {
+        const entry = storage.getEntry(key);
+        return entry ? { value: entry.value, timestamp: entry.createdAt } : void 0;
+      } catch {
+        return void 0;
+      }
+    },
+    set(key, entry) {
+      try {
+        storage.set(key, entry.value, options.ttl !== void 0 ? { ttl: options.ttl } : void 0);
+      } catch {
+      }
+    },
+    delete: (key) => storage.remove(key),
+    keys: () => storage.keys(),
+    clear() {
+      storage.clear();
+      inflight.clear();
+    },
+    inflight
+  };
+}
+export {
+  storageCache
+};

package/dist/src/lib/storage/index.cjs

@@ -0,0 +1,246 @@
+/*! @fluixi/core v1.0.0-alpha.93 | (c) 2026 Ibrahima Touré and Fluixi contributors | MIT */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/lib/storage/index.ts
+var index_exports = {};
+__export(index_exports, {
+  StorageProvider: () => StorageProvider,
+  hydrateStorage: () => hydrateStorage,
+  persisted: () => persisted,
+  storageCache: () => storageCache,
+  useAsyncStorage: () => useAsyncStorage,
+  useStorage: () => useStorage
+});
+module.exports = __toCommonJS(index_exports);
+var import_dom = require("@fluixi/dom");
+var import_signal2 = require("@fluixi/reactive/signal");
+var import_storage = require("@fluixi/storage");
+var import_browser = require("@fluixi/storage/browser");
+var import_server = require("@fluixi/storage/server");
+
+// src/lib/storage/persisted.ts
+var import_signal = require("@fluixi/reactive/signal");
+var isAsync = (storage) => "encryption" in storage;
+function persisted(storage, key, options = {}) {
+  const fallback = options.fallback ?? null;
+  const name = options.name ?? `storage:${storage.keyPrefix}${key}`;
+  const state = (0, import_signal.signal)(isAsync(storage) ? fallback : storage.get(key) ?? fallback, { name });
+  const put = (value) => state.set(() => value);
+  const resolve = (next) => typeof next === "function" ? next((0, import_signal.untrack)(state)) : next;
+  const writeOptions = (extra) => ({
+    ...options.ttl !== void 0 ? { ttl: options.ttl } : {},
+    ...options.encrypt ? { encrypt: true } : {},
+    ...extra
+  });
+  if (!isAsync(storage)) {
+    const off2 = storage.subscribe(key, (event) => {
+      if (event.type !== "set") return put(fallback);
+      if (event.value !== void 0) put(event.value);
+    });
+    if ((0, import_signal.getOwner)()) (0, import_signal.onCleanup)(off2);
+    return Object.assign(() => state(), {
+      set(next, extra) {
+        const value = resolve(next);
+        storage.set(key, value, writeOptions(extra));
+        put(value);
+      },
+      remove() {
+        storage.remove(key);
+        put(fallback);
+      }
+    });
+  }
+  let written = false;
+  const reread = () => storage.get(key).then(
+    (value) => put(value ?? fallback),
+    () => void 0
+  );
+  const off = storage.subscribe(key, (event) => {
+    if (event.type !== "set") return put(fallback);
+    if (event.value !== void 0) put(event.value);
+    else void reread();
+  });
+  if ((0, import_signal.getOwner)()) (0, import_signal.onCleanup)(off);
+  const ready = storage.get(key).then((value) => {
+    if (!written) put(value ?? fallback);
+  });
+  return Object.assign(() => state(), {
+    ready,
+    async set(next, extra) {
+      const previous = (0, import_signal.untrack)(state);
+      const value = resolve(next);
+      written = true;
+      put(value);
+      try {
+        await storage.set(key, value, writeOptions(extra));
+      } catch (error) {
+        put(previous);
+        throw error;
+      }
+    },
+    async remove() {
+      written = true;
+      await storage.remove(key);
+      put(fallback);
+    }
+  });
+}
+
+// src/lib/storage/cache.ts
+function storageCache(storage, options = {}) {
+  const inflight = /* @__PURE__ */ new Map();
+  return {
+    get(key) {
+      try {
+        const entry = storage.getEntry(key);
+        return entry ? { value: entry.value, timestamp: entry.createdAt } : void 0;
+      } catch {
+        return void 0;
+      }
+    },
+    set(key, entry) {
+      try {
+        storage.set(key, entry.value, options.ttl !== void 0 ? { ttl: options.ttl } : void 0);
+      } catch {
+      }
+    },
+    delete: (key) => storage.remove(key),
+    keys: () => storage.keys(),
+    clear() {
+      storage.clear();
+      inflight.clear();
+    },
+    inflight
+  };
+}
+
+// src/lib/storage/index.ts
+var StorageContext = (0, import_signal2.createContext)(void 0, "storage");
+var AsyncStorageContext = (0, import_signal2.createContext)(void 0, "asyncStorage");
+var isAsyncStorage = (storage) => "encryption" in storage;
+function StorageProvider(props) {
+  const context = isAsyncStorage(props.storage) ? AsyncStorageContext : StorageContext;
+  return context.Provider({
+    value: props.storage,
+    get children() {
+      return props.children;
+    }
+  });
+}
+var isBrowser = () => typeof window !== "undefined" && typeof document !== "undefined";
+var perRequest = /* @__PURE__ */ new WeakMap();
+var perPage = /* @__PURE__ */ new Map();
+function cached(scope, id, make) {
+  let adapter = scope.get(id);
+  if (!adapter) scope.set(id, adapter = make());
+  return adapter;
+}
+function requestRequired(scope) {
+  throw new import_storage.StorageUnavailableError(
+    `useStorage({ scope: '${scope}' }) on the server needs a request: call it during a render, a loader or a server function, or provide a storage with <StorageProvider>.`
+  );
+}
+function adapterFor(scope, cookie = {}) {
+  const ctx = (0, import_dom.getRequestContext)();
+  const options = { httpOnly: false, ...cookie };
+  switch (scope) {
+    case "local":
+      return (0, import_browser.localStorageAdapter)();
+    case "session":
+      return (0, import_browser.sessionStorageAdapter)();
+    case "request":
+      if (isBrowser()) return cached(perPage, "request", import_storage.memoryStorage);
+      if (!ctx) requestRequired(scope);
+      return cached(perRequest.get(ctx) ?? perRequest.set(ctx, /* @__PURE__ */ new Map()).get(ctx), "request", import_server.requestStorage);
+    case "cookie": {
+      const id = `cookie:${JSON.stringify(options)}`;
+      if (isBrowser()) {
+        const { httpOnly: _ignored, ...browser } = options;
+        return cached(perPage, id, () => (0, import_browser.documentCookieAdapter)(browser));
+      }
+      if (!ctx) requestRequired(scope);
+      const raw = ctx.event.request;
+      const target = raw && typeof raw === "object" ? raw : void 0;
+      return cached(
+        perRequest.get(ctx) ?? perRequest.set(ctx, /* @__PURE__ */ new Map()).get(ctx),
+        id,
+        () => (0, import_server.cookieStorage)({
+          ...options,
+          request: raw && typeof raw === "object" && ("headers" in raw || "getHeader" in raw) ? (0, import_server.toStorageRequest)(raw) : void 0,
+          response: {
+            appendHeader(name, value) {
+              if (!(0, import_dom.appendResponseHeader)(name, value, target)) {
+                throw new import_storage.StorageUnavailableError("The response headers were already sent, so this cookie cannot reach the browser. Write it before the page head goes out: in middleware, a loader, a server function or the render before its first chunk.");
+              }
+            }
+          }
+        })
+      );
+    }
+  }
+}
+function useStorage(options = {}) {
+  const { scope = "auto", cookie, ...storageOptions } = options;
+  if (scope === "auto") {
+    const provided = (0, import_signal2.useContext)(StorageContext);
+    if (provided) return options.namespace ? provided.namespace(options.namespace) : provided;
+  }
+  return (0, import_storage.createSyncStorage)({ ...storageOptions, adapter: resolveAdapter(scope, cookie) });
+}
+function useAsyncStorage(options = {}) {
+  const { scope = "auto", cookie, ...storageOptions } = options;
+  if (scope === "auto") {
+    const provided = (0, import_signal2.useContext)(AsyncStorageContext);
+    if (provided) return options.namespace ? provided.namespace(options.namespace) : provided;
+  }
+  return (0, import_storage.createAsyncStorage)({ ...storageOptions, adapter: resolveAdapter(scope, cookie) });
+}
+function resolveAdapter(scope, cookie) {
+  if (scope !== "auto") return adapterFor(scope, cookie);
+  if (isBrowser()) return adapterFor("local");
+  if (!(0, import_dom.getRequestContext)()) requestRequired(scope);
+  return adapterFor("request");
+}
+var SLOT = "__storage:";
+var seeded = /* @__PURE__ */ new Set();
+function hydrateStorage(storage, keys) {
+  const slot = SLOT + storage.keyPrefix;
+  if (!isBrowser()) {
+    const ctx = (0, import_dom.getRequestContext)();
+    if (!ctx) return;
+    const entries2 = ctx.data.get(slot) ?? {};
+    for (const key of keys) {
+      const entry = storage.getEntry(key);
+      if (entry) entries2[key] = entry;
+    }
+    ctx.data.set(slot, entries2);
+    return;
+  }
+  const entries = (0, import_dom.getServerData)()?.[slot];
+  if (!entries) return;
+  const fresh = {};
+  for (const key of keys) {
+    const id = slot + key;
+    if (seeded.has(id) || !entries[key]) continue;
+    seeded.add(id);
+    fresh[key] = entries[key];
+  }
+  storage.restore(fresh, { overwrite: true });
+}

package/dist/src/lib/storage/index.d.ts

@@ -0,0 +1,83 @@
+import { type AsyncTypedStorage, type EncryptionOptions, type StorageKey, type StorageOptions, type StorageSchema, type TypedStorage } from '@fluixi/storage';
+import type { CookieOptions } from '@fluixi/utils/cookie';
+/**
+ * Where `useStorage` keeps values.
+ *
+ * - `auto`: a storage from `<StorageProvider>` when there is one; else localStorage in the
+ *   browser and the request's own storage during a server render.
+ * - `local`, `session`: the browser's storages. Reading them on a server throws.
+ * - `request`: values for one server request, or for the page's lifetime in the browser.
+ * - `cookie`: the request's cookies on the server, `document.cookie` in the browser. Both sides
+ *   read the same value, which is what server-rendered preferences such as a theme need.
+ */
+export type UseStorageScope = 'auto' | 'local' | 'session' | 'request' | 'cookie';
+export interface UseStorageCookieOptions extends CookieOptions {
+    /** Largest `name=value` in bytes. Defaults to 4096. */
+    maxSize?: number;
+}
+export interface UseStorageOptions<S extends StorageSchema = StorageSchema> extends Omit<StorageOptions<S>, 'adapter'> {
+    scope?: UseStorageScope;
+    /**
+     * Cookie attributes for `scope: 'cookie'`. `httpOnly` defaults to false here, since the browser
+     * half has to read the cookie; set it to true for a value only the server reads.
+     */
+    cookie?: UseStorageCookieOptions;
+}
+export interface UseAsyncStorageOptions<S extends StorageSchema = StorageSchema> extends UseStorageOptions<S> {
+    /** Per-item encryption: `set(key, value, { encrypt: true })`, reads decrypt on their own. */
+    encryption?: EncryptionOptions;
+}
+/**
+ * Hands `storage` to every `useStorage()` below that asks for `scope: 'auto'` (the default), or
+ * to every `useAsyncStorage()` when it is an asynchronous one: a test's memory storage, an
+ * encrypted or app-specific one.
+ *
+ * @example
+ * <StorageProvider storage={createStorage({ adapter: memoryStorage() })}>
+ *   <Settings />
+ * </StorageProvider>
+ */
+export declare function StorageProvider(props: {
+    storage: TypedStorage<any> | AsyncTypedStorage<any>;
+    children?: unknown;
+}): any;
+/**
+ * A typed storage for the place this code runs. Call it in a component, a loader or a server
+ * function; the scope decides the backend (see `UseStorageScope`) and the rest of the options
+ * are those of `createStorage`.
+ *
+ * Server-side state never lives in a module: each request gets its own adapters, so two
+ * visitors rendering at once never see each other's values.
+ *
+ * @example
+ * const prefs = useStorage<{ theme: 'light' | 'dark' }>({ scope: 'cookie', namespace: 'ui', cookie: { maxAge: 31536000 } });
+ * const theme = prefs.get('theme') ?? 'light';
+ */
+export declare function useStorage<S extends StorageSchema = StorageSchema>(options?: UseStorageOptions<S>): TypedStorage<S>;
+/**
+ * `useStorage` with every operation awaited, and the one that can encrypt. Same scopes, same
+ * per-request isolation; with `scope: 'auto'` it takes an asynchronous storage from
+ * `<StorageProvider>` first.
+ *
+ * @example
+ * const vault = useAsyncStorage<{ token: string }>({ namespace: 'auth', encryption: { keyProvider } });
+ * await vault.set('token', token, { encrypt: true });
+ */
+export declare function useAsyncStorage<S extends StorageSchema = StorageSchema>(options?: UseAsyncStorageOptions<S>): AsyncTypedStorage<S>;
+/**
+ * Carries `keys` from the server render to the browser. On the server it puts their values,
+ * with expiry and version, in the page data; in the browser, the first call for a key writes
+ * the server's value into `storage`, and later calls leave the browser's own value alone.
+ *
+ * Meant for request-scoped values the page needs again: call it with the same keys on both
+ * sides. The page data is readable by anyone who sees the page, so never hydrate a secret,
+ * and an encrypted value throws here rather than travel in clear.
+ *
+ * @example
+ * const scratch = useStorage<{ draft: Draft }>({ scope: 'request', namespace: 'editor' });
+ * hydrateStorage(scratch, ['draft']);
+ */
+export declare function hydrateStorage<S extends StorageSchema>(storage: TypedStorage<S>, keys: StorageKey<S>[]): void;
+export { persisted, type Persisted, type AsyncPersisted, type PersistedOptions } from './persisted.js';
+export { storageCache } from './cache.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/lib/storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/storage/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAKL,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EAGtB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAElF,MAAM,WAAW,uBAAwB,SAAQ,aAAa;IAC5D,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,CAAE,SAAQ,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC;IACpH,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,uBAAuB,CAAC;CAClC;AAED,MAAM,WAAW,sBAAsB,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,CAAE,SAAQ,iBAAiB,CAAC,CAAC,CAAC;IAC3G,6FAA6F;IAC7F,UAAU,CAAC,EAAE,iBAAiB,CAAC;CAChC;AAOD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IAAE,OAAO,EAAE,YAAY,CAAC,GAAG,CAAC,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,GAAG,CAQvH;AA6DD;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,EAAE,OAAO,GAAE,iBAAiB,CAAC,CAAC,CAAM,GAAG,YAAY,CAAC,CAAC,CAAC,CAOvH;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,aAAa,GAAG,aAAa,EAAE,OAAO,GAAE,sBAAsB,CAAC,CAAC,CAAM,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAOtI;AAYD;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,aAAa,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAuB7G;AAED,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvG,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/src/lib/storage/index.js

@@ -0,0 +1,179 @@
+/**
+ * Storage inside a Fluixi app: `useStorage` picks the backend for where the code runs, so one
+ * component reads the same value on the server and in the browser. The storage itself is
+ * `@fluixi/storage`; this module only binds it to the request, the owner tree and the page data.
+ */
+import { appendResponseHeader, getRequestContext, getServerData } from '@fluixi/dom';
+import { createContext, useContext } from '@fluixi/reactive/signal';
+import { createAsyncStorage, createSyncStorage, memoryStorage, StorageUnavailableError, } from '@fluixi/storage';
+import { documentCookieAdapter, localStorageAdapter, sessionStorageAdapter } from '@fluixi/storage/browser';
+import { cookieStorage, requestStorage, toStorageRequest } from '@fluixi/storage/server';
+const StorageContext = createContext(undefined, 'storage');
+const AsyncStorageContext = createContext(undefined, 'asyncStorage');
+const isAsyncStorage = (storage) => 'encryption' in storage;
+/**
+ * Hands `storage` to every `useStorage()` below that asks for `scope: 'auto'` (the default), or
+ * to every `useAsyncStorage()` when it is an asynchronous one: a test's memory storage, an
+ * encrypted or app-specific one.
+ *
+ * @example
+ * <StorageProvider storage={createStorage({ adapter: memoryStorage() })}>
+ *   <Settings />
+ * </StorageProvider>
+ */
+export function StorageProvider(props) {
+    const context = isAsyncStorage(props.storage) ? AsyncStorageContext : StorageContext;
+    return context.Provider({
+        value: props.storage,
+        get children() {
+            return props.children;
+        },
+    });
+}
+const isBrowser = () => typeof window !== 'undefined' && typeof document !== 'undefined';
+// One adapter per request and kind, so a cookie written early in a render reads back later in
+// the same render. Weakly held: they go with the request.
+const perRequest = new WeakMap();
+// In the browser there is one user and one page, so the page is the scope.
+const perPage = new Map();
+function cached(scope, id, make) {
+    let adapter = scope.get(id);
+    if (!adapter)
+        scope.set(id, (adapter = make()));
+    return adapter;
+}
+function requestRequired(scope) {
+    throw new StorageUnavailableError(`useStorage({ scope: '${scope}' }) on the server needs a request: call it during a render, a loader or a server function, or provide a storage with <StorageProvider>.`);
+}
+function adapterFor(scope, cookie = {}) {
+    const ctx = getRequestContext();
+    const options = { httpOnly: false, ...cookie };
+    switch (scope) {
+        case 'local':
+            return localStorageAdapter();
+        case 'session':
+            return sessionStorageAdapter();
+        case 'request':
+            if (isBrowser())
+                return cached(perPage, 'request', memoryStorage);
+            if (!ctx)
+                requestRequired(scope);
+            return cached(perRequest.get(ctx) ?? perRequest.set(ctx, new Map()).get(ctx), 'request', requestStorage);
+        case 'cookie': {
+            const id = `cookie:${JSON.stringify(options)}`;
+            if (isBrowser()) {
+                const { httpOnly: _ignored, ...browser } = options;
+                return cached(perPage, id, () => documentCookieAdapter(browser));
+            }
+            if (!ctx)
+                requestRequired(scope);
+            const raw = ctx.event.request;
+            // Bound now: an async write resumes after awaits, where the ambient request may be gone.
+            const target = (raw && typeof raw === 'object' ? raw : undefined);
+            return cached(perRequest.get(ctx) ?? perRequest.set(ctx, new Map()).get(ctx), id, () => cookieStorage({
+                ...options,
+                request: raw && typeof raw === 'object' && ('headers' in raw || 'getHeader' in raw) ? toStorageRequest(raw) : undefined,
+                response: {
+                    appendHeader(name, value) {
+                        if (!appendResponseHeader(name, value, target)) {
+                            throw new StorageUnavailableError('The response headers were already sent, so this cookie cannot reach the browser. Write it before the page head goes out: in middleware, a loader, a server function or the render before its first chunk.');
+                        }
+                    },
+                },
+            }));
+        }
+    }
+}
+/**
+ * A typed storage for the place this code runs. Call it in a component, a loader or a server
+ * function; the scope decides the backend (see `UseStorageScope`) and the rest of the options
+ * are those of `createStorage`.
+ *
+ * Server-side state never lives in a module: each request gets its own adapters, so two
+ * visitors rendering at once never see each other's values.
+ *
+ * @example
+ * const prefs = useStorage<{ theme: 'light' | 'dark' }>({ scope: 'cookie', namespace: 'ui', cookie: { maxAge: 31536000 } });
+ * const theme = prefs.get('theme') ?? 'light';
+ */
+export function useStorage(options = {}) {
+    const { scope = 'auto', cookie, ...storageOptions } = options;
+    if (scope === 'auto') {
+        const provided = useContext(StorageContext);
+        if (provided)
+            return (options.namespace ? provided.namespace(options.namespace) : provided);
+    }
+    return createSyncStorage({ ...storageOptions, adapter: resolveAdapter(scope, cookie) });
+}
+/**
+ * `useStorage` with every operation awaited, and the one that can encrypt. Same scopes, same
+ * per-request isolation; with `scope: 'auto'` it takes an asynchronous storage from
+ * `<StorageProvider>` first.
+ *
+ * @example
+ * const vault = useAsyncStorage<{ token: string }>({ namespace: 'auth', encryption: { keyProvider } });
+ * await vault.set('token', token, { encrypt: true });
+ */
+export function useAsyncStorage(options = {}) {
+    const { scope = 'auto', cookie, ...storageOptions } = options;
+    if (scope === 'auto') {
+        const provided = useContext(AsyncStorageContext);
+        if (provided)
+            return (options.namespace ? provided.namespace(options.namespace) : provided);
+    }
+    return createAsyncStorage({ ...storageOptions, adapter: resolveAdapter(scope, cookie) });
+}
+function resolveAdapter(scope, cookie) {
+    if (scope !== 'auto')
+        return adapterFor(scope, cookie);
+    if (isBrowser())
+        return adapterFor('local');
+    if (!getRequestContext())
+        requestRequired(scope);
+    return adapterFor('request');
+}
+const SLOT = '__storage:';
+const seeded = new Set();
+/**
+ * Carries `keys` from the server render to the browser. On the server it puts their values,
+ * with expiry and version, in the page data; in the browser, the first call for a key writes
+ * the server's value into `storage`, and later calls leave the browser's own value alone.
+ *
+ * Meant for request-scoped values the page needs again: call it with the same keys on both
+ * sides. The page data is readable by anyone who sees the page, so never hydrate a secret,
+ * and an encrypted value throws here rather than travel in clear.
+ *
+ * @example
+ * const scratch = useStorage<{ draft: Draft }>({ scope: 'request', namespace: 'editor' });
+ * hydrateStorage(scratch, ['draft']);
+ */
+export function hydrateStorage(storage, keys) {
+    const slot = SLOT + storage.keyPrefix;
+    if (!isBrowser()) {
+        const ctx = getRequestContext();
+        if (!ctx)
+            return;
+        const entries = ctx.data.get(slot) ?? {};
+        for (const key of keys) {
+            const entry = storage.getEntry(key);
+            if (entry)
+                entries[key] = entry;
+        }
+        ctx.data.set(slot, entries);
+        return;
+    }
+    const entries = getServerData()?.[slot];
+    if (!entries)
+        return;
+    const fresh = {};
+    for (const key of keys) {
+        const id = slot + key;
+        if (seeded.has(id) || !entries[key])
+            continue;
+        seeded.add(id);
+        fresh[key] = entries[key];
+    }
+    storage.restore(fresh, { overwrite: true });
+}
+export { persisted } from './persisted.js';
+export { storageCache } from './cache.js';