@victorylabs/params 0.1.0 → 0.3.0

package/dist/react.js

@@ -1,21 +1,36 @@
 import {
   acquire,
   release
-} from "./chunk-43PUAYQP.js";
+} from "./chunk-DSAHBEAQ.js";
 import "./chunk-4T4THPFW.js";
 import "./chunk-5NSLHAHG.js";
 import {
   defaultSerialize
-} from "./chunk-NUO3GOXV.js";
+} from "./chunk-5UKBDZTP.js";
+
+// src/react/use-debounced-value.ts
+import { useEffect, useState } from "react";
+function useDebouncedValue(value, ms) {
+  const [debounced, setDebounced] = useState(value);
+  useEffect(() => {
+    if (ms <= 0) {
+      setDebounced(value);
+      return;
+    }
+    const id = setTimeout(() => setDebounced(value), ms);
+    return () => clearTimeout(id);
+  }, [value, ms]);
+  return debounced;
+}
 
 // src/react/use-field-input.tsx
-import { useCallback, useEffect as useEffect2, useRef, useState } from "react";
+import { useCallback, useEffect as useEffect3, useRef, useState as useState2 } from "react";
 
 // src/react/use-field-value.ts
-import { useEffect, useReducer } from "react";
+import { useEffect as useEffect2, useReducer } from "react";
 function useFieldValue(store, path) {
   const [, forceRender] = useReducer((tick) => tick + 1, 0);
-  useEffect(() => store.subscribe(path, forceRender), [store, path]);
+  useEffect2(() => store.subscribe(path, forceRender), [store, path]);
   return store.getValue(path);
 }
 
@@ -24,10 +39,10 @@ function useFieldInput(store, path) {
   const storeValue = useFieldValue(store, path);
   const config = store.getFieldConfig(path);
   const debounceMs = config?.debounce ?? 0;
-  const [shadow, setShadow] = useState(null);
+  const [shadow, setShadow] = useState2(null);
   const debouncerRef = useRef(null);
   const lastStoreValueRef = useRef(storeValue);
-  useEffect2(() => {
+  useEffect3(() => {
     if (Object.is(lastStoreValueRef.current, storeValue)) return;
     lastStoreValueRef.current = storeValue;
     if (shadow !== null && shadow !== defaultSerialize(storeValue)) {
@@ -45,7 +60,7 @@ function useFieldInput(store, path) {
         setShadow(next);
         debouncerRef.current?.trigger(next);
       } else {
-        store.set(path, next);
+        store.setField(path, next);
       }
     },
     [store, path, debounceMs]
@@ -65,7 +80,7 @@ function createDebouncer(store, path, ms, onCommit) {
   let pendingValue = null;
   const commit = () => {
     if (pendingValue !== null) {
-      store.set(path, pendingValue);
+      store.setField(path, pendingValue);
       pendingValue = null;
       onCommit();
     }
@@ -93,16 +108,16 @@ function createDebouncer(store, path, ms, onCommit) {
 }
 
 // src/react/use-params.tsx
-import { useCallback as useCallback2, useDeferredValue, useEffect as useEffect4, useReducer as useReducer2 } from "react";
+import { useCallback as useCallback2, useDeferredValue, useEffect as useEffect5, useReducer as useReducer2 } from "react";
 
 // src/react/use-shared-store.ts
-import { useEffect as useEffect3, useRef as useRef2 } from "react";
+import { useEffect as useEffect4, useRef as useRef2 } from "react";
 function useSharedStore(def) {
   const storeRef = useRef2(null);
   if (storeRef.current === null) {
     storeRef.current = acquire(def);
   }
-  useEffect3(
+  useEffect4(
     () => () => {
       release(def);
       storeRef.current = null;
@@ -116,15 +131,13 @@ function useSharedStore(def) {
 function useParams(def) {
   const store = useSharedStore(def);
   const [, forceRender] = useReducer2((tick) => tick + 1, 0);
-  useEffect4(() => store.subscribe("", forceRender), [store]);
+  useEffect5(() => store.subscribe("", forceRender), [store]);
   const set = useCallback2(
-    ((pathOrPartial, valueOrOptions, maybeOptions) => {
-      if (typeof pathOrPartial === "string") {
-        store.set(pathOrPartial, valueOrOptions, maybeOptions);
-      } else {
-        store.set(pathOrPartial, valueOrOptions);
-      }
-    }),
+    (partial, options) => store.set(partial, options),
+    [store]
+  );
+  const setField = useCallback2(
+    (path, value2, options) => store.setField(path, value2, options),
     [store]
   );
   const toggle = useCallback2(
@@ -176,11 +189,15 @@ function useParams(def) {
   const deferred = (path) => useDeferredValue(useFieldValue(store, path));
   const input = (path) => useFieldInput(store, path);
   return {
+    // Cast: store.getValues() returns Partial<T> for the storage layer's
+    // sake, but every field in ParamsDefinition declares a default so the
+    // hydrated view is structurally complete. See ParamsController.values.
     values: store.getValues(),
     value,
     deferred,
     input,
     set,
+    setField,
     toggle,
     append,
     remove: removeFn,
@@ -195,6 +212,7 @@ function useParams(def) {
   };
 }
 export {
+  useDebouncedValue,
   useFieldInput,
   useFieldValue,
   useParams

package/dist/react.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/react/use-field-input.tsx","../src/react/use-field-value.ts","../src/react/use-params.tsx","../src/react/use-shared-store.ts"],"sourcesContent":["import type { ChangeEvent } from 'react'\nimport { useCallback, useEffect, useRef, useState } from 'react'\n\nimport type { ParamsStore } from '../params-store'\nimport { defaultSerialize } from '../schema'\nimport { useFieldValue } from './use-field-value'\n\nexport interface InputBindings {\n  name: string\n  value: string\n  onChange: (event: ChangeEvent<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>) => void\n  onBlur: () => void\n}\n\ninterface DebounceController {\n  trigger: (value: string) => void\n  flush: () => void\n  cancel: () => void\n}\n\n/**\n * Hook that returns input bindings for a single path. Handles:\n *  - Reading the current store value (debounced shadow during typing)\n *  - Per-field debounce from the field config\n *  - Shadow cancellation when an external `set()` invalidates the pending value\n *  - `onBlur` flushes any pending debounce immediately\n *\n * The bindings are spreadable directly: `<input {...p.input('query')} />`.\n */\nexport function useFieldInput(store: ParamsStore, path: string): InputBindings {\n  const storeValue = useFieldValue<unknown>(store, path)\n  const config = store.getFieldConfig(path)\n  const debounceMs = config?.debounce ?? 0\n\n  const [shadow, setShadow] = useState<string | null>(null)\n  const debouncerRef = useRef<DebounceController | null>(null)\n  const lastStoreValueRef = useRef(storeValue)\n\n  // External change → drop shadow + cancel pending debounce.\n  // Track storeValue identity so the effect ONLY reacts to actual store\n  // changes — not to local shadow updates while the user is typing.\n  useEffect(() => {\n    if (Object.is(lastStoreValueRef.current, storeValue)) return\n    lastStoreValueRef.current = storeValue\n    if (shadow !== null && shadow !== defaultSerialize(storeValue)) {\n      debouncerRef.current?.cancel()\n      setShadow(null)\n    }\n  }, [storeValue, shadow])\n\n  // Lazy-create the debounce controller for this hook instance\n  if (debounceMs > 0 && debouncerRef.current === null) {\n    debouncerRef.current = createDebouncer(store, path, debounceMs, () => setShadow(null))\n  }\n\n  const onChange = useCallback(\n    (event: ChangeEvent<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>) => {\n      const next = event.target.value\n      if (debounceMs > 0) {\n        setShadow(next)\n        debouncerRef.current?.trigger(next)\n      } else {\n        store.set(path, next)\n      }\n    },\n    [store, path, debounceMs],\n  )\n\n  const onBlur = useCallback(() => {\n    debouncerRef.current?.flush()\n  }, [])\n\n  return {\n    name: path,\n    value: shadow ?? defaultSerialize(storeValue),\n    onChange,\n    onBlur,\n  }\n}\n\nfunction createDebouncer(\n  store: ParamsStore,\n  path: string,\n  ms: number,\n  onCommit: () => void,\n): DebounceController {\n  let timer: ReturnType<typeof setTimeout> | undefined\n  let pendingValue: string | null = null\n\n  const commit = () => {\n    if (pendingValue !== null) {\n      store.set(path, pendingValue)\n      pendingValue = null\n      onCommit()\n    }\n  }\n\n  return {\n    trigger: (value: string) => {\n      pendingValue = value\n      if (timer !== undefined) clearTimeout(timer)\n      timer = setTimeout(() => {\n        timer = undefined\n        commit()\n      }, ms)\n    },\n    flush: () => {\n      if (timer !== undefined) clearTimeout(timer)\n      timer = undefined\n      commit()\n    },\n    cancel: () => {\n      if (timer !== undefined) clearTimeout(timer)\n      timer = undefined\n      pendingValue = null\n    },\n  }\n}\n","import { useEffect, useReducer } from 'react'\n\nimport type { ParamsStore } from '../params-store'\n\n/**\n * Subscribe to a single path on the store. Re-renders the calling component\n * only when that path's value changes. Sibling-path changes don't fire.\n */\nexport function useFieldValue<TValue = unknown>(store: ParamsStore, path: string): TValue {\n  const [, forceRender] = useReducer((tick: number) => tick + 1, 0)\n  useEffect(() => store.subscribe(path, forceRender), [store, path])\n  return store.getValue(path) as TValue\n}\n","import { useCallback, useDeferredValue, useEffect, useReducer } from 'react'\n\nimport type { ParamsStore, SetOptions } from '../params-store'\nimport type { ParamsDefinition } from '../types'\nimport type { InputBindings } from './use-field-input'\nimport { useFieldInput } from './use-field-input'\nimport { useFieldValue } from './use-field-value'\nimport { useSharedStore } from './use-shared-store'\n\nexport interface ParamsController<T> {\n  /** Snapshot of all values. Re-renders the calling component on any change. */\n  readonly values: Readonly<Partial<T>>\n\n  /** Hook — subscribes to a single path. Call at top level of render. */\n  value<TValue = unknown>(path: string): TValue\n\n  /** Hook — `value(path)` wrapped in `useDeferredValue`. */\n  deferred<TValue = unknown>(path: string): TValue\n\n  /** Hook — input bindings for `<input {...p.input('path')} />`. */\n  input(path: string): InputBindings\n\n  // Pass-through to the store (callable anywhere — not hooks)\n  set: ParamsStore<T>['set']\n  toggle: ParamsStore<T>['toggle']\n  append: ParamsStore<T>['append']\n  remove: ParamsStore<T>['remove']\n  removeAt: ParamsStore<T>['removeAt']\n  cycle: ParamsStore<T>['cycle']\n  clear: ParamsStore<T>['clear']\n  reset: ParamsStore<T>['reset']\n  subscribe: ParamsStore<T>['subscribe']\n  toQuery: ParamsStore<T>['toQuery']\n  href: ParamsStore<T>['href']\n\n  /** Unstable escape hatch — for devtools, advanced integrations. */\n  readonly store: ParamsStore<T>\n}\n\n/**\n * Single-hook React API for `@victorylabs/params`. Returns a controller with\n * everything a component needs:\n *\n * ```tsx\n * function Filters() {\n *   const p = useParams(filtersDef)\n *   return (\n *     <>\n *       <input {...p.input('query')} />\n *       <Pagination page={p.value('page')} onPage={(page) => p.set({ page })} />\n *       <ResultList query={p.deferred('query')} />\n *     </>\n *   )\n * }\n * ```\n *\n * Cross-component sharing is automatic — multiple `useParams(def)` calls with\n * the same definition share the same store instance via the WeakMap cache.\n */\nexport function useParams<T extends Record<string, unknown> = Record<string, unknown>>(\n  def: ParamsDefinition<T>,\n): ParamsController<T> {\n  const store = useSharedStore(def) as ParamsStore<T>\n\n  // Subscribe to root — re-renders this caller on any field change.\n  // Granular subscriptions (avoid parent re-renders) are achieved via\n  // `p.value(path)` / `p.input(path)` in CHILD components.\n  const [, forceRender] = useReducer((tick: number) => tick + 1, 0)\n  useEffect(() => store.subscribe('', forceRender), [store])\n\n  // Stable bindings for store methods (delegated as-is). The overloaded `set`\n  // needs an explicit branch so TypeScript can pick the right call signature.\n  const set = useCallback(\n    ((\n      pathOrPartial: string | Partial<T>,\n      valueOrOptions?: unknown,\n      maybeOptions?: SetOptions,\n    ): void => {\n      if (typeof pathOrPartial === 'string') {\n        store.set(pathOrPartial, valueOrOptions, maybeOptions)\n      } else {\n        store.set(pathOrPartial, valueOrOptions as SetOptions | undefined)\n      }\n    }) as ParamsStore<T>['set'],\n    [store],\n  )\n  const toggle = useCallback<ParamsStore<T>['toggle']>(\n    (path, options) => store.toggle(path, options),\n    [store],\n  )\n  const append = useCallback<ParamsStore<T>['append']>(\n    (path, value, options) => store.append(path, value, options),\n    [store],\n  )\n  const removeFn = useCallback<ParamsStore<T>['remove']>(\n    (path, value, options) => store.remove(path, value, options),\n    [store],\n  )\n  const removeAt = useCallback<ParamsStore<T>['removeAt']>(\n    (path, index, options) => store.removeAt(path, index, options),\n    [store],\n  )\n  const cycle = useCallback(\n    ((\n      path: string,\n      valuesOrOptions?: ReadonlyArray<unknown> | SetOptions,\n      maybeOptions?: SetOptions,\n    ): void => {\n      if (Array.isArray(valuesOrOptions)) {\n        store.cycle(path, valuesOrOptions, maybeOptions)\n      } else if (valuesOrOptions !== undefined) {\n        store.cycle(path, valuesOrOptions as SetOptions)\n      } else {\n        store.cycle(path)\n      }\n    }) as ParamsStore<T>['cycle'],\n    [store],\n  )\n  const clear = useCallback<ParamsStore<T>['clear']>(\n    (path, options) => store.clear(path, options),\n    [store],\n  )\n  const reset = useCallback<ParamsStore<T>['reset']>(\n    (values, options) => store.reset(values, options),\n    [store],\n  )\n  const subscribe = useCallback<ParamsStore<T>['subscribe']>(\n    (path, listener) => store.subscribe(path, listener),\n    [store],\n  )\n  const toQuery = useCallback<ParamsStore<T>['toQuery']>(\n    (overrides) => store.toQuery(overrides),\n    [store],\n  )\n  const href = useCallback<ParamsStore<T>['href']>((overrides) => store.href(overrides), [store])\n\n  // The hook-based methods need access to `store` via closure. Each call\n  // (`p.value('x')`) invokes its hook in the consumer's render scope.\n  const value = <TValue = unknown>(path: string): TValue => useFieldValue<TValue>(store, path)\n  const deferred = <TValue = unknown>(path: string): TValue =>\n    useDeferredValue(useFieldValue<TValue>(store, path))\n  const input = (path: string): InputBindings => useFieldInput(store, path)\n\n  return {\n    values: store.getValues(),\n    value,\n    deferred,\n    input,\n    set,\n    toggle,\n    append,\n    remove: removeFn,\n    removeAt,\n    cycle,\n    clear,\n    reset,\n    subscribe,\n    toQuery,\n    href,\n    store,\n  }\n}\n","import { useEffect, useRef } from 'react'\n\nimport type { ParamsStore } from '../params-store'\nimport { acquire, release } from '../store-cache'\nimport type { ParamsDefinition } from '../types'\n\n/**\n * Internal hook: acquires the shared store on mount, releases on unmount.\n * Survives React 18 Strict Mode (microtask-deferred disposal cancels itself\n * when a fresh acquire arrives in the same tick).\n *\n * Multiple components using the same definition get the same store instance\n * — that's the cross-component-sharing primitive for params.\n */\nexport function useSharedStore<T>(def: ParamsDefinition<T>): ParamsStore<T> {\n  const storeRef = useRef<ParamsStore<T> | null>(null)\n  if (storeRef.current === null) {\n    storeRef.current = acquire(def)\n  }\n\n  useEffect(\n    () => () => {\n      release(def)\n      storeRef.current = null\n    },\n    [def],\n  )\n\n  return storeRef.current\n}\n"],"mappings":"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","names":["useEffect","useEffect","useCallback","useEffect","useReducer","useEffect","useRef","useRef","useEffect","useReducer","useEffect","useCallback","value"]}
+{"version":3,"sources":["../src/react/use-debounced-value.ts","../src/react/use-field-input.tsx","../src/react/use-field-value.ts","../src/react/use-params.tsx","../src/react/use-shared-store.ts"],"sourcesContent":["import { useEffect, useState } from 'react'\n\n/**\n * Returns a copy of `value` that updates only after `ms` milliseconds of\n * stability. Rapid changes cancel pending updates so only the last one\n * settles. `ms <= 0` short-circuits to a synchronous pass-through.\n *\n * Pairs with `@victorylabs/params`' field-level `debounce:` config (which\n * lives at the URL/storage layer) for cases where a component wants to\n * debounce arbitrary local state — e.g., a search input that drives a\n * downstream query but isn't itself a params field.\n *\n * @example\n * ```tsx\n * function SearchBox() {\n *   const [query, setQuery] = useState('')\n *   const debounced = useDebouncedValue(query, 200)\n *\n *   const { data } = api.queries.search({ params: { q: debounced } })\n *   return <input value={query} onChange={(e) => setQuery(e.target.value)} />\n * }\n * ```\n */\nexport function useDebouncedValue<T>(value: T, ms: number): T {\n  const [debounced, setDebounced] = useState(value)\n\n  useEffect(() => {\n    if (ms <= 0) {\n      setDebounced(value)\n      return\n    }\n    const id = setTimeout(() => setDebounced(value), ms)\n    return () => clearTimeout(id)\n  }, [value, ms])\n\n  return debounced\n}\n","import type { ChangeEvent } from 'react'\nimport { useCallback, useEffect, useRef, useState } from 'react'\n\nimport type { ParamsStore } from '../params-store'\nimport { defaultSerialize } from '../schema'\nimport { useFieldValue } from './use-field-value'\n\nexport interface InputBindings {\n  name: string\n  value: string\n  onChange: (event: ChangeEvent<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>) => void\n  onBlur: () => void\n}\n\ninterface DebounceController {\n  trigger: (value: string) => void\n  flush: () => void\n  cancel: () => void\n}\n\n/**\n * Hook that returns input bindings for a single path. Handles:\n *  - Reading the current store value (debounced shadow during typing)\n *  - Per-field debounce from the field config\n *  - Shadow cancellation when an external `set()` invalidates the pending value\n *  - `onBlur` flushes any pending debounce immediately\n *\n * The bindings are spreadable directly: `<input {...p.input('query')} />`.\n */\nexport function useFieldInput(store: ParamsStore, path: string): InputBindings {\n  const storeValue = useFieldValue<unknown>(store, path)\n  const config = store.getFieldConfig(path)\n  const debounceMs = config?.debounce ?? 0\n\n  const [shadow, setShadow] = useState<string | null>(null)\n  const debouncerRef = useRef<DebounceController | null>(null)\n  const lastStoreValueRef = useRef(storeValue)\n\n  // External change → drop shadow + cancel pending debounce.\n  // Track storeValue identity so the effect ONLY reacts to actual store\n  // changes — not to local shadow updates while the user is typing.\n  useEffect(() => {\n    if (Object.is(lastStoreValueRef.current, storeValue)) return\n    lastStoreValueRef.current = storeValue\n    if (shadow !== null && shadow !== defaultSerialize(storeValue)) {\n      debouncerRef.current?.cancel()\n      setShadow(null)\n    }\n  }, [storeValue, shadow])\n\n  // Lazy-create the debounce controller for this hook instance\n  if (debounceMs > 0 && debouncerRef.current === null) {\n    debouncerRef.current = createDebouncer(store, path, debounceMs, () => setShadow(null))\n  }\n\n  const onChange = useCallback(\n    (event: ChangeEvent<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>) => {\n      const next = event.target.value\n      if (debounceMs > 0) {\n        setShadow(next)\n        debouncerRef.current?.trigger(next)\n      } else {\n        store.setField(path, next)\n      }\n    },\n    [store, path, debounceMs],\n  )\n\n  const onBlur = useCallback(() => {\n    debouncerRef.current?.flush()\n  }, [])\n\n  return {\n    name: path,\n    value: shadow ?? defaultSerialize(storeValue),\n    onChange,\n    onBlur,\n  }\n}\n\nfunction createDebouncer(\n  store: ParamsStore,\n  path: string,\n  ms: number,\n  onCommit: () => void,\n): DebounceController {\n  let timer: ReturnType<typeof setTimeout> | undefined\n  let pendingValue: string | null = null\n\n  const commit = () => {\n    if (pendingValue !== null) {\n      store.setField(path, pendingValue)\n      pendingValue = null\n      onCommit()\n    }\n  }\n\n  return {\n    trigger: (value: string) => {\n      pendingValue = value\n      if (timer !== undefined) clearTimeout(timer)\n      timer = setTimeout(() => {\n        timer = undefined\n        commit()\n      }, ms)\n    },\n    flush: () => {\n      if (timer !== undefined) clearTimeout(timer)\n      timer = undefined\n      commit()\n    },\n    cancel: () => {\n      if (timer !== undefined) clearTimeout(timer)\n      timer = undefined\n      pendingValue = null\n    },\n  }\n}\n","import { useEffect, useReducer } from 'react'\n\nimport type { ParamsStore } from '../params-store'\n\n/**\n * Subscribe to a single path on the store. Re-renders the calling component\n * only when that path's value changes. Sibling-path changes don't fire.\n */\nexport function useFieldValue<TValue = unknown>(store: ParamsStore, path: string): TValue {\n  const [, forceRender] = useReducer((tick: number) => tick + 1, 0)\n  useEffect(() => store.subscribe(path, forceRender), [store, path])\n  return store.getValue(path) as TValue\n}\n","import { useCallback, useDeferredValue, useEffect, useReducer } from 'react'\n\nimport type { ParamsStore, SetOptions } from '../params-store'\nimport type { ParamsDefinition } from '../types'\nimport type { InputBindings } from './use-field-input'\nimport { useFieldInput } from './use-field-input'\nimport { useFieldValue } from './use-field-value'\nimport { useSharedStore } from './use-shared-store'\n\nexport interface ParamsController<T> {\n  /**\n   * Snapshot of all values, with defaults hydrated. Re-renders the calling\n   * component on any change.\n   *\n   * Typed as `Readonly<T>` (not `Readonly<Partial<T>>`) because every field\n   * in a `ParamsDefinition` declares a default — either via the schema's\n   * `.default()` or a plain spec's `default:` field — so the controller's\n   * view is always complete. The underlying storage layer remains `Partial`\n   * (URL/localStorage may be missing keys); the controller fills those in.\n   */\n  readonly values: Readonly<T>\n\n  /** Hook — subscribes to a single path. Call at top level of render. */\n  value<TValue = unknown>(path: string): TValue\n\n  /** Hook — `value(path)` wrapped in `useDeferredValue`. */\n  deferred<TValue = unknown>(path: string): TValue\n\n  /** Hook — input bindings for `<input {...p.input('path')} />`. */\n  input(path: string): InputBindings\n\n  // Pass-through to the store (callable anywhere — not hooks)\n  /**\n   * Apply a partial update — write multiple fields at once.\n   * For single-field writes use {@link setField}.\n   */\n  set: ParamsStore<T>['set']\n  /** Write a single field by path. Replaces the old `set(path, value)` form. */\n  setField: ParamsStore<T>['setField']\n  toggle: ParamsStore<T>['toggle']\n  append: ParamsStore<T>['append']\n  remove: ParamsStore<T>['remove']\n  removeAt: ParamsStore<T>['removeAt']\n  cycle: ParamsStore<T>['cycle']\n  clear: ParamsStore<T>['clear']\n  reset: ParamsStore<T>['reset']\n  subscribe: ParamsStore<T>['subscribe']\n  toQuery: ParamsStore<T>['toQuery']\n  href: ParamsStore<T>['href']\n\n  /** Unstable escape hatch — for devtools, advanced integrations. */\n  readonly store: ParamsStore<T>\n}\n\n/**\n * Single-hook React API for `@victorylabs/params`. Returns a controller with\n * everything a component needs:\n *\n * ```tsx\n * function Filters() {\n *   const p = useParams(filtersDef)\n *   return (\n *     <>\n *       <input {...p.input('query')} />\n *       <Pagination page={p.value('page')} onPage={(page) => p.set({ page })} />\n *       <ResultList query={p.deferred('query')} />\n *     </>\n *   )\n * }\n * ```\n *\n * Cross-component sharing is automatic — multiple `useParams(def)` calls with\n * the same definition share the same store instance via the WeakMap cache.\n */\nexport function useParams<T extends Record<string, unknown> = Record<string, unknown>>(\n  def: ParamsDefinition<T>,\n): ParamsController<T> {\n  const store = useSharedStore(def) as ParamsStore<T>\n\n  // Subscribe to root — re-renders this caller on any field change.\n  // Granular subscriptions (avoid parent re-renders) are achieved via\n  // `p.value(path)` / `p.input(path)` in CHILD components.\n  const [, forceRender] = useReducer((tick: number) => tick + 1, 0)\n  useEffect(() => store.subscribe('', forceRender), [store])\n\n  // Stable bindings for store methods (delegated as-is).\n  const set = useCallback<ParamsStore<T>['set']>(\n    (partial, options) => store.set(partial, options),\n    [store],\n  )\n  const setField = useCallback<ParamsStore<T>['setField']>(\n    (path, value, options) => store.setField(path, value, options),\n    [store],\n  )\n  const toggle = useCallback<ParamsStore<T>['toggle']>(\n    (path, options) => store.toggle(path, options),\n    [store],\n  )\n  const append = useCallback<ParamsStore<T>['append']>(\n    (path, value, options) => store.append(path, value, options),\n    [store],\n  )\n  const removeFn = useCallback<ParamsStore<T>['remove']>(\n    (path, value, options) => store.remove(path, value, options),\n    [store],\n  )\n  const removeAt = useCallback<ParamsStore<T>['removeAt']>(\n    (path, index, options) => store.removeAt(path, index, options),\n    [store],\n  )\n  const cycle = useCallback(\n    ((\n      path: string,\n      valuesOrOptions?: ReadonlyArray<unknown> | SetOptions,\n      maybeOptions?: SetOptions,\n    ): void => {\n      if (Array.isArray(valuesOrOptions)) {\n        store.cycle(path, valuesOrOptions, maybeOptions)\n      } else if (valuesOrOptions !== undefined) {\n        store.cycle(path, valuesOrOptions as SetOptions)\n      } else {\n        store.cycle(path)\n      }\n    }) as ParamsStore<T>['cycle'],\n    [store],\n  )\n  const clear = useCallback<ParamsStore<T>['clear']>(\n    (path, options) => store.clear(path, options),\n    [store],\n  )\n  const reset = useCallback<ParamsStore<T>['reset']>(\n    (values, options) => store.reset(values, options),\n    [store],\n  )\n  const subscribe = useCallback<ParamsStore<T>['subscribe']>(\n    (path, listener) => store.subscribe(path, listener),\n    [store],\n  )\n  const toQuery = useCallback<ParamsStore<T>['toQuery']>(\n    (overrides) => store.toQuery(overrides),\n    [store],\n  )\n  const href = useCallback<ParamsStore<T>['href']>((overrides) => store.href(overrides), [store])\n\n  // The hook-based methods need access to `store` via closure. Each call\n  // (`p.value('x')`) invokes its hook in the consumer's render scope.\n  const value = <TValue = unknown>(path: string): TValue => useFieldValue<TValue>(store, path)\n  const deferred = <TValue = unknown>(path: string): TValue =>\n    useDeferredValue(useFieldValue<TValue>(store, path))\n  const input = (path: string): InputBindings => useFieldInput(store, path)\n\n  return {\n    // Cast: store.getValues() returns Partial<T> for the storage layer's\n    // sake, but every field in ParamsDefinition declares a default so the\n    // hydrated view is structurally complete. See ParamsController.values.\n    values: store.getValues() as Readonly<T>,\n    value,\n    deferred,\n    input,\n    set,\n    setField,\n    toggle,\n    append,\n    remove: removeFn,\n    removeAt,\n    cycle,\n    clear,\n    reset,\n    subscribe,\n    toQuery,\n    href,\n    store,\n  }\n}\n","import { useEffect, useRef } from 'react'\n\nimport type { ParamsStore } from '../params-store'\nimport { acquire, release } from '../store-cache'\nimport type { ParamsDefinition } from '../types'\n\n/**\n * Internal hook: acquires the shared store on mount, releases on unmount.\n * Survives React 18 Strict Mode (microtask-deferred disposal cancels itself\n * when a fresh acquire arrives in the same tick).\n *\n * Multiple components using the same definition get the same store instance\n * — that's the cross-component-sharing primitive for params.\n */\nexport function useSharedStore<T>(def: ParamsDefinition<T>): ParamsStore<T> {\n  const storeRef = useRef<ParamsStore<T> | null>(null)\n  if (storeRef.current === null) {\n    storeRef.current = acquire(def)\n  }\n\n  useEffect(\n    () => () => {\n      release(def)\n      storeRef.current = null\n    },\n    [def],\n  )\n\n  return storeRef.current\n}\n"],"mappings":"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","names":["useEffect","useState","useEffect","useState","useEffect","useCallback","useEffect","useReducer","useEffect","useRef","useRef","useEffect","useReducer","useEffect","useCallback","value"]}

package/dist/storage/idb.cjs

@@ -29,23 +29,41 @@ function idbStorage(opts) {
   const storeName = opts.store ?? "params";
   const recordKey = opts.key ?? "default";
   const version = opts.version ?? 1;
+  const broadcastEnabled = opts.broadcast === true;
+  const onUpgrade = opts.onUpgrade;
+  const channelName = `@victorylabs/params:${dbName}:${storeName}:${recordKey}`;
   let dbHandle;
   const openDb = async () => {
     if (!isClient) throw new Error("idbStorage: window.indexedDB unavailable");
     if (dbHandle && dbHandle.version === version) return dbHandle;
     return new Promise((resolve, reject) => {
       const req = window.indexedDB.open(dbName, version);
-      req.onupgradeneeded = () => {
+      req.onupgradeneeded = (event) => {
         const db = req.result;
         if (!db.objectStoreNames.contains(storeName)) {
           db.createObjectStore(storeName);
         }
+        if (onUpgrade && req.transaction) {
+          onUpgrade({
+            db,
+            transaction: req.transaction,
+            oldVersion: event.oldVersion,
+            newVersion: event.newVersion ?? version
+          });
+        }
       };
       req.onsuccess = () => {
         dbHandle = req.result;
         dbHandle.onclose = () => {
           dbHandle = void 0;
         };
+        dbHandle.onversionchange = () => {
+          try {
+            dbHandle?.close();
+          } catch {
+          }
+          dbHandle = void 0;
+        };
         resolve(req.result);
       };
       req.onerror = () => reject(req.error);
@@ -65,7 +83,30 @@ function idbStorage(opts) {
       return op(await openDb());
     }
   };
-  return {
+  const broadcastSupported = () => broadcastEnabled && typeof BroadcastChannel !== "undefined";
+  let sharedChannel;
+  const subscribers = /* @__PURE__ */ new Set();
+  const ensureChannel = () => {
+    if (!broadcastSupported()) return void 0;
+    if (sharedChannel === void 0) {
+      sharedChannel = new BroadcastChannel(channelName);
+      sharedChannel.onmessage = (event) => {
+        const data = event.data;
+        const values = data?.values ?? {};
+        for (const cb of [...subscribers]) cb(values);
+      };
+    }
+    return sharedChannel;
+  };
+  const broadcast = (values) => {
+    const ch = ensureChannel();
+    if (ch === void 0) return;
+    try {
+      ch.postMessage({ values });
+    } catch {
+    }
+  };
+  const storage = {
     name: "idbStorage",
     clientOnly: true,
     // IDB has no synchronous API. Engine consults `readAsync` for hydration;
@@ -97,6 +138,7 @@ function idbStorage(opts) {
             req.onerror = () => reject(req.error);
           })
         );
+        broadcast(values);
       } catch {
       }
     },
@@ -112,6 +154,7 @@ function idbStorage(opts) {
               req.onerror = () => reject(req.error);
             })
           );
+          broadcast(void 0);
           return;
         }
         const current = await withVersionRetry(
@@ -131,11 +174,21 @@ function idbStorage(opts) {
             req.onerror = () => reject(req.error);
           })
         );
+        broadcast(current);
       } catch {
       }
     }
-    // No `subscribe` — IDB doesn't fire native change events. v0.6+ via BroadcastChannel.
   };
+  if (broadcastSupported()) {
+    storage.subscribe = (callback) => {
+      ensureChannel();
+      subscribers.add(callback);
+      return () => {
+        subscribers.delete(callback);
+      };
+    };
+  }
+  return storage;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/storage/idb.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/storage/idb/index.ts"],"sourcesContent":["import type { ParamsStorage } from '../../storage'\n\nexport interface IdbStorageOptions {\n  /** Database name. Required. */\n  readonly db: string\n  /** Object store name within the database. Default: `'params'`. */\n  readonly store?: string\n  /** Record key within the store. Default: `'default'`. */\n  readonly key?: string\n  /** Schema version. Bump if you change the value shape across releases. Default: `1`. */\n  readonly version?: number\n}\n\nconst isClient = typeof window !== 'undefined' && typeof window.indexedDB !== 'undefined'\n\n/**\n * IndexedDB storage backend.\n *\n * Async-only — `read()` returns `undefined` synchronously; the engine should\n * consult `readAsync()` for hydration. Single record per definition (the\n * `key` option), stored as a structured-clonable object — no JSON\n * serialization layer.\n *\n * v0.5 limitations (likely v0.6+ candidates if a consumer asks):\n *  - **No cross-tab sync** (no BroadcastChannel). The same database is shared\n *    across tabs, but writes from one tab don't push to another. Subscribe is\n *    intentionally absent.\n *  - **No consumer-supplied `onupgradeneeded` hook.** The `version` option\n *    triggers an upgrade transaction and the lib creates the object store on\n *    first open, but you can't migrate from a previous shape.\n */\nexport function idbStorage<T = Record<string, unknown>>(opts: IdbStorageOptions): ParamsStorage<T> {\n  const dbName = opts.db\n  const storeName = opts.store ?? 'params'\n  const recordKey = opts.key ?? 'default'\n  const version = opts.version ?? 1\n\n  // Cache the database handle. Re-opens on demand if closed.\n  let dbHandle: IDBDatabase | undefined\n  const openDb = async (): Promise<IDBDatabase> => {\n    if (!isClient) throw new Error('idbStorage: window.indexedDB unavailable')\n    if (dbHandle && dbHandle.version === version) return dbHandle\n    return new Promise((resolve, reject) => {\n      const req = window.indexedDB.open(dbName, version)\n      req.onupgradeneeded = () => {\n        const db = req.result\n        if (!db.objectStoreNames.contains(storeName)) {\n          db.createObjectStore(storeName)\n        }\n      }\n      req.onsuccess = () => {\n        dbHandle = req.result\n        dbHandle.onclose = () => {\n          dbHandle = undefined\n        }\n        resolve(req.result)\n      }\n      req.onerror = () => reject(req.error)\n    })\n  }\n\n  /**\n   * v0.5: retry once on `VersionError`. Another tab opening the DB at a\n   * different version invalidates our cached handle. Close it, re-open, and\n   * retry the operation. After one retry, fall back to silent (existing\n   * contract).\n   */\n  const withVersionRetry = async <R>(op: (db: IDBDatabase) => Promise<R>): Promise<R> => {\n    try {\n      return await op(await openDb())\n    } catch (err) {\n      const isVersionError =\n        typeof DOMException !== 'undefined' &&\n        err instanceof DOMException &&\n        err.name === 'VersionError'\n      if (!isVersionError) throw err\n      try {\n        dbHandle?.close()\n      } catch {\n        // ignore — handle may already be invalid\n      }\n      dbHandle = undefined\n      return op(await openDb())\n    }\n  }\n\n  return {\n    name: 'idbStorage',\n    clientOnly: true,\n\n    // IDB has no synchronous API. Engine consults `readAsync` for hydration;\n    // `read()` always returns undefined.\n    read: () => undefined,\n\n    readAsync: async () => {\n      if (!isClient) return undefined\n      try {\n        return await withVersionRetry(\n          (db) =>\n            new Promise<Partial<T> | undefined>((resolve, reject) => {\n              const tx = db.transaction(storeName, 'readonly')\n              const req = tx.objectStore(storeName).get(recordKey)\n              req.onsuccess = () => resolve((req.result as Partial<T> | undefined) ?? undefined)\n              req.onerror = () => reject(req.error)\n            }),\n        )\n      } catch {\n        return undefined\n      }\n    },\n\n    write: async (values, _changed, _options) => {\n      if (!isClient) return\n      try {\n        await withVersionRetry(\n          (db) =>\n            new Promise<void>((resolve, reject) => {\n              const tx = db.transaction(storeName, 'readwrite')\n              const req = tx.objectStore(storeName).put(values, recordKey)\n              req.onsuccess = () => resolve()\n              req.onerror = () => reject(req.error)\n            }),\n        )\n      } catch {\n        // Silent fallback per the storage error contract — values still live in memory.\n      }\n    },\n\n    clear: async (paths, _options) => {\n      if (!isClient) return\n      try {\n        if (paths.length === 0) {\n          // Clear everything — delete the record.\n          await withVersionRetry(\n            (db) =>\n              new Promise<void>((resolve, reject) => {\n                const tx = db.transaction(storeName, 'readwrite')\n                const req = tx.objectStore(storeName).delete(recordKey)\n                req.onsuccess = () => resolve()\n                req.onerror = () => reject(req.error)\n              }),\n          )\n          return\n        }\n        // Per-path clear: read current, omit cleared paths, write back.\n        const current = await withVersionRetry(\n          (db) =>\n            new Promise<Record<string, unknown>>((resolve, reject) => {\n              const tx = db.transaction(storeName, 'readonly')\n              const req = tx.objectStore(storeName).get(recordKey)\n              req.onsuccess = () =>\n                resolve((req.result as Record<string, unknown> | undefined) ?? {})\n              req.onerror = () => reject(req.error)\n            }),\n        )\n        for (const p of paths) delete current[p]\n        await withVersionRetry(\n          (db) =>\n            new Promise<void>((resolve, reject) => {\n              const tx = db.transaction(storeName, 'readwrite')\n              const req = tx.objectStore(storeName).put(current, recordKey)\n              req.onsuccess = () => resolve()\n              req.onerror = () => reject(req.error)\n            }),\n        )\n      } catch {\n        // Silent fallback.\n      }\n    },\n\n    // No `subscribe` — IDB doesn't fire native change events. v0.6+ via BroadcastChannel.\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/storage/idb/index.ts"],"sourcesContent":["import type { ParamsStorage } from '../../storage'\n\n/**\n * Consumer-supplied schema-migration callback. Invoked inside\n * `onupgradeneeded` after the lib ensures the configured object store exists,\n * so consumers don't need to defensively check for it. The upgrade\n * `transaction` is provided so consumers can iterate cursors against the\n * existing store synchronously to migrate record shapes.\n *\n * Errors thrown here abort the upgrade — the open request fails and\n * `idbStorage`'s silent-fallback contract returns `undefined` to the engine.\n */\nexport type IdbUpgradeCallback = (ctx: {\n  readonly db: IDBDatabase\n  readonly transaction: IDBTransaction\n  readonly oldVersion: number\n  readonly newVersion: number\n}) => void\n\nexport interface IdbStorageOptions {\n  /** Database name. Required. */\n  readonly db: string\n  /** Object store name within the database. Default: `'params'`. */\n  readonly store?: string\n  /** Record key within the store. Default: `'default'`. */\n  readonly key?: string\n  /** Schema version. Bump if you change the value shape across releases. Default: `1`. */\n  readonly version?: number\n  /**\n   * Cross-tab sync via {@link BroadcastChannel}. When `true`, every successful\n   * write broadcasts the new values to other tabs subscribed to the same\n   * `(db, store, key)` triple; the receiving tab feeds them back through the\n   * `subscribe` callback exactly as it would for a `popstate` or `storage`\n   * event. Default: `false` — preserves the v0.5 \"no subscribe\" behavior so\n   * existing consumers see no change.\n   *\n   * Channel name is derived from `(dbName, storeName, recordKey)`. SSR-safe:\n   * skips registration when `BroadcastChannel` is unavailable.\n   */\n  readonly broadcast?: boolean\n  /**\n   * Schema-migration callback. See {@link IdbUpgradeCallback}. Most consumers\n   * don't need this — the lib creates the object store on first open. Reach\n   * for it only when you bump `version` and need to add indexes or migrate\n   * record shapes.\n   */\n  readonly onUpgrade?: IdbUpgradeCallback\n}\n\nconst isClient = typeof window !== 'undefined' && typeof window.indexedDB !== 'undefined'\n\n/**\n * IndexedDB storage backend.\n *\n * Async-only — `read()` returns `undefined` synchronously; the engine should\n * consult `readAsync()` for hydration. Single record per definition (the\n * `key` option), stored as a structured-clonable object — no JSON\n * serialization layer.\n *\n * v0.6 capabilities (opt-in, both backward-compatible):\n *  - **`broadcast: true`** for cross-tab sync via `BroadcastChannel`.\n *  - **`onUpgrade`** for consumer-supplied schema migrations across `version`\n *    bumps (add indexes, transform records).\n */\nexport function idbStorage<T = Record<string, unknown>>(opts: IdbStorageOptions): ParamsStorage<T> {\n  const dbName = opts.db\n  const storeName = opts.store ?? 'params'\n  const recordKey = opts.key ?? 'default'\n  const version = opts.version ?? 1\n  const broadcastEnabled = opts.broadcast === true\n  const onUpgrade = opts.onUpgrade\n  const channelName = `@victorylabs/params:${dbName}:${storeName}:${recordKey}`\n\n  // Cache the database handle. Re-opens on demand if closed.\n  let dbHandle: IDBDatabase | undefined\n  const openDb = async (): Promise<IDBDatabase> => {\n    if (!isClient) throw new Error('idbStorage: window.indexedDB unavailable')\n    if (dbHandle && dbHandle.version === version) return dbHandle\n    return new Promise((resolve, reject) => {\n      const req = window.indexedDB.open(dbName, version)\n      req.onupgradeneeded = (event) => {\n        const db = req.result\n        if (!db.objectStoreNames.contains(storeName)) {\n          db.createObjectStore(storeName)\n        }\n        if (onUpgrade && req.transaction) {\n          onUpgrade({\n            db,\n            transaction: req.transaction,\n            oldVersion: event.oldVersion,\n            newVersion: event.newVersion ?? version,\n          })\n        }\n      }\n      req.onsuccess = () => {\n        dbHandle = req.result\n        dbHandle.onclose = () => {\n          dbHandle = undefined\n        }\n        // When another tab opens the same DB at a higher version, the browser\n        // fires `versionchange` against this handle. If we don't close it,\n        // the other tab's upgrade blocks indefinitely. Close → fall through\n        // to the `withVersionRetry` path on the next op.\n        dbHandle.onversionchange = () => {\n          try {\n            dbHandle?.close()\n          } catch {\n            // ignore\n          }\n          dbHandle = undefined\n        }\n        resolve(req.result)\n      }\n      req.onerror = () => reject(req.error)\n    })\n  }\n\n  /**\n   * v0.5: retry once on `VersionError`. Another tab opening the DB at a\n   * different version invalidates our cached handle. Close it, re-open, and\n   * retry the operation. After one retry, fall back to silent (existing\n   * contract).\n   */\n  const withVersionRetry = async <R>(op: (db: IDBDatabase) => Promise<R>): Promise<R> => {\n    try {\n      return await op(await openDb())\n    } catch (err) {\n      const isVersionError =\n        typeof DOMException !== 'undefined' &&\n        err instanceof DOMException &&\n        err.name === 'VersionError'\n      if (!isVersionError) throw err\n      try {\n        dbHandle?.close()\n      } catch {\n        // ignore — handle may already be invalid\n      }\n      dbHandle = undefined\n      return op(await openDb())\n    }\n  }\n\n  // ── Cross-tab broadcast (opt-in via `broadcast: true`) ────────────────\n  // Per the BroadcastChannel spec, posting a message on a channel does NOT\n  // deliver it back to that same channel instance — but it DOES deliver it\n  // to other BroadcastChannel instances with the same name in the same agent\n  // and any other agent. We exploit that by sharing ONE channel per storage\n  // instance for both posting and receiving: local writes never re-trigger\n  // our own subscribers; cross-tab writes do.\n  const broadcastSupported = (): boolean =>\n    broadcastEnabled && typeof BroadcastChannel !== 'undefined'\n  let sharedChannel: BroadcastChannel | undefined\n  const subscribers = new Set<(values: Partial<T>) => void>()\n  const ensureChannel = (): BroadcastChannel | undefined => {\n    if (!broadcastSupported()) return undefined\n    if (sharedChannel === undefined) {\n      sharedChannel = new BroadcastChannel(channelName)\n      sharedChannel.onmessage = (event) => {\n        const data = event.data as { values?: Partial<T> } | null | undefined\n        const values = data?.values ?? ({} as Partial<T>)\n        for (const cb of [...subscribers]) cb(values)\n      }\n    }\n    return sharedChannel\n  }\n  const broadcast = (values: Partial<T> | undefined): void => {\n    const ch = ensureChannel()\n    if (ch === undefined) return\n    try {\n      ch.postMessage({ values })\n    } catch {\n      // BroadcastChannel can throw if the message isn't structured-cloneable;\n      // silent per the storage error contract.\n    }\n  }\n\n  const storage: ParamsStorage<T> = {\n    name: 'idbStorage',\n    clientOnly: true,\n\n    // IDB has no synchronous API. Engine consults `readAsync` for hydration;\n    // `read()` always returns undefined.\n    read: () => undefined,\n\n    readAsync: async () => {\n      if (!isClient) return undefined\n      try {\n        return await withVersionRetry(\n          (db) =>\n            new Promise<Partial<T> | undefined>((resolve, reject) => {\n              const tx = db.transaction(storeName, 'readonly')\n              const req = tx.objectStore(storeName).get(recordKey)\n              req.onsuccess = () => resolve((req.result as Partial<T> | undefined) ?? undefined)\n              req.onerror = () => reject(req.error)\n            }),\n        )\n      } catch {\n        return undefined\n      }\n    },\n\n    write: async (values, _changed, _options) => {\n      if (!isClient) return\n      try {\n        await withVersionRetry(\n          (db) =>\n            new Promise<void>((resolve, reject) => {\n              const tx = db.transaction(storeName, 'readwrite')\n              const req = tx.objectStore(storeName).put(values, recordKey)\n              req.onsuccess = () => resolve()\n              req.onerror = () => reject(req.error)\n            }),\n        )\n        broadcast(values)\n      } catch {\n        // Silent fallback per the storage error contract — values still live in memory.\n      }\n    },\n\n    clear: async (paths, _options) => {\n      if (!isClient) return\n      try {\n        if (paths.length === 0) {\n          // Clear everything — delete the record.\n          await withVersionRetry(\n            (db) =>\n              new Promise<void>((resolve, reject) => {\n                const tx = db.transaction(storeName, 'readwrite')\n                const req = tx.objectStore(storeName).delete(recordKey)\n                req.onsuccess = () => resolve()\n                req.onerror = () => reject(req.error)\n              }),\n          )\n          broadcast(undefined)\n          return\n        }\n        // Per-path clear: read current, omit cleared paths, write back.\n        const current = await withVersionRetry(\n          (db) =>\n            new Promise<Record<string, unknown>>((resolve, reject) => {\n              const tx = db.transaction(storeName, 'readonly')\n              const req = tx.objectStore(storeName).get(recordKey)\n              req.onsuccess = () =>\n                resolve((req.result as Record<string, unknown> | undefined) ?? {})\n              req.onerror = () => reject(req.error)\n            }),\n        )\n        for (const p of paths) delete current[p]\n        await withVersionRetry(\n          (db) =>\n            new Promise<void>((resolve, reject) => {\n              const tx = db.transaction(storeName, 'readwrite')\n              const req = tx.objectStore(storeName).put(current, recordKey)\n              req.onsuccess = () => resolve()\n              req.onerror = () => reject(req.error)\n            }),\n        )\n        broadcast(current as Partial<T>)\n      } catch {\n        // Silent fallback.\n      }\n    },\n  }\n\n  if (broadcastSupported()) {\n    storage.subscribe = (callback) => {\n      ensureChannel()\n      subscribers.add(callback)\n      return () => {\n        subscribers.delete(callback)\n        // Keep the shared channel open for the lifetime of the storage\n        // instance — the next write needs it for outbound posts, even after\n        // the last subscribe teardown.\n      }\n    }\n  }\n\n  return storage\n}\n"],"mappings":"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","names":[]}

package/dist/storage/idb.d.cts

@@ -1,5 +1,21 @@
 import { P as ParamsStorage } from '../storage-DBLIRR-4.cjs';
 
+/**
+ * Consumer-supplied schema-migration callback. Invoked inside
+ * `onupgradeneeded` after the lib ensures the configured object store exists,
+ * so consumers don't need to defensively check for it. The upgrade
+ * `transaction` is provided so consumers can iterate cursors against the
+ * existing store synchronously to migrate record shapes.
+ *
+ * Errors thrown here abort the upgrade — the open request fails and
+ * `idbStorage`'s silent-fallback contract returns `undefined` to the engine.
+ */
+type IdbUpgradeCallback = (ctx: {
+    readonly db: IDBDatabase;
+    readonly transaction: IDBTransaction;
+    readonly oldVersion: number;
+    readonly newVersion: number;
+}) => void;
 interface IdbStorageOptions {
     /** Database name. Required. */
     readonly db: string;
@@ -9,6 +25,25 @@ interface IdbStorageOptions {
     readonly key?: string;
     /** Schema version. Bump if you change the value shape across releases. Default: `1`. */
     readonly version?: number;
+    /**
+     * Cross-tab sync via {@link BroadcastChannel}. When `true`, every successful
+     * write broadcasts the new values to other tabs subscribed to the same
+     * `(db, store, key)` triple; the receiving tab feeds them back through the
+     * `subscribe` callback exactly as it would for a `popstate` or `storage`
+     * event. Default: `false` — preserves the v0.5 "no subscribe" behavior so
+     * existing consumers see no change.
+     *
+     * Channel name is derived from `(dbName, storeName, recordKey)`. SSR-safe:
+     * skips registration when `BroadcastChannel` is unavailable.
+     */
+    readonly broadcast?: boolean;
+    /**
+     * Schema-migration callback. See {@link IdbUpgradeCallback}. Most consumers
+     * don't need this — the lib creates the object store on first open. Reach
+     * for it only when you bump `version` and need to add indexes or migrate
+     * record shapes.
+     */
+    readonly onUpgrade?: IdbUpgradeCallback;
 }
 /**
  * IndexedDB storage backend.
@@ -18,14 +53,11 @@ interface IdbStorageOptions {
  * `key` option), stored as a structured-clonable object — no JSON
  * serialization layer.
  *
- * v0.5 limitations (likely v0.6+ candidates if a consumer asks):
- *  - **No cross-tab sync** (no BroadcastChannel). The same database is shared
- *    across tabs, but writes from one tab don't push to another. Subscribe is
- *    intentionally absent.
- *  - **No consumer-supplied `onupgradeneeded` hook.** The `version` option
- *    triggers an upgrade transaction and the lib creates the object store on
- *    first open, but you can't migrate from a previous shape.
+ * v0.6 capabilities (opt-in, both backward-compatible):
+ *  - **`broadcast: true`** for cross-tab sync via `BroadcastChannel`.
+ *  - **`onUpgrade`** for consumer-supplied schema migrations across `version`
+ *    bumps (add indexes, transform records).
  */
 declare function idbStorage<T = Record<string, unknown>>(opts: IdbStorageOptions): ParamsStorage<T>;
 
-export { type IdbStorageOptions, idbStorage };
+export { type IdbStorageOptions, type IdbUpgradeCallback, idbStorage };

package/dist/storage/idb.d.ts

@@ -1,5 +1,21 @@
 import { P as ParamsStorage } from '../storage-DBLIRR-4.js';
 
+/**
+ * Consumer-supplied schema-migration callback. Invoked inside
+ * `onupgradeneeded` after the lib ensures the configured object store exists,
+ * so consumers don't need to defensively check for it. The upgrade
+ * `transaction` is provided so consumers can iterate cursors against the
+ * existing store synchronously to migrate record shapes.
+ *
+ * Errors thrown here abort the upgrade — the open request fails and
+ * `idbStorage`'s silent-fallback contract returns `undefined` to the engine.
+ */
+type IdbUpgradeCallback = (ctx: {
+    readonly db: IDBDatabase;
+    readonly transaction: IDBTransaction;
+    readonly oldVersion: number;
+    readonly newVersion: number;
+}) => void;
 interface IdbStorageOptions {
     /** Database name. Required. */
     readonly db: string;
@@ -9,6 +25,25 @@ interface IdbStorageOptions {
     readonly key?: string;
     /** Schema version. Bump if you change the value shape across releases. Default: `1`. */
     readonly version?: number;
+    /**
+     * Cross-tab sync via {@link BroadcastChannel}. When `true`, every successful
+     * write broadcasts the new values to other tabs subscribed to the same
+     * `(db, store, key)` triple; the receiving tab feeds them back through the
+     * `subscribe` callback exactly as it would for a `popstate` or `storage`
+     * event. Default: `false` — preserves the v0.5 "no subscribe" behavior so
+     * existing consumers see no change.
+     *
+     * Channel name is derived from `(dbName, storeName, recordKey)`. SSR-safe:
+     * skips registration when `BroadcastChannel` is unavailable.
+     */
+    readonly broadcast?: boolean;
+    /**
+     * Schema-migration callback. See {@link IdbUpgradeCallback}. Most consumers
+     * don't need this — the lib creates the object store on first open. Reach
+     * for it only when you bump `version` and need to add indexes or migrate
+     * record shapes.
+     */
+    readonly onUpgrade?: IdbUpgradeCallback;
 }
 /**
  * IndexedDB storage backend.
@@ -18,14 +53,11 @@ interface IdbStorageOptions {
  * `key` option), stored as a structured-clonable object — no JSON
  * serialization layer.
  *
- * v0.5 limitations (likely v0.6+ candidates if a consumer asks):
- *  - **No cross-tab sync** (no BroadcastChannel). The same database is shared
- *    across tabs, but writes from one tab don't push to another. Subscribe is
- *    intentionally absent.
- *  - **No consumer-supplied `onupgradeneeded` hook.** The `version` option
- *    triggers an upgrade transaction and the lib creates the object store on
- *    first open, but you can't migrate from a previous shape.
+ * v0.6 capabilities (opt-in, both backward-compatible):
+ *  - **`broadcast: true`** for cross-tab sync via `BroadcastChannel`.
+ *  - **`onUpgrade`** for consumer-supplied schema migrations across `version`
+ *    bumps (add indexes, transform records).
  */
 declare function idbStorage<T = Record<string, unknown>>(opts: IdbStorageOptions): ParamsStorage<T>;
 
-export { type IdbStorageOptions, idbStorage };
+export { type IdbStorageOptions, type IdbUpgradeCallback, idbStorage };

package/dist/storage/idb.js

@@ -5,23 +5,41 @@ function idbStorage(opts) {
   const storeName = opts.store ?? "params";
   const recordKey = opts.key ?? "default";
   const version = opts.version ?? 1;
+  const broadcastEnabled = opts.broadcast === true;
+  const onUpgrade = opts.onUpgrade;
+  const channelName = `@victorylabs/params:${dbName}:${storeName}:${recordKey}`;
   let dbHandle;
   const openDb = async () => {
     if (!isClient) throw new Error("idbStorage: window.indexedDB unavailable");
     if (dbHandle && dbHandle.version === version) return dbHandle;
     return new Promise((resolve, reject) => {
       const req = window.indexedDB.open(dbName, version);
-      req.onupgradeneeded = () => {
+      req.onupgradeneeded = (event) => {
         const db = req.result;
         if (!db.objectStoreNames.contains(storeName)) {
           db.createObjectStore(storeName);
         }
+        if (onUpgrade && req.transaction) {
+          onUpgrade({
+            db,
+            transaction: req.transaction,
+            oldVersion: event.oldVersion,
+            newVersion: event.newVersion ?? version
+          });
+        }
       };
       req.onsuccess = () => {
         dbHandle = req.result;
         dbHandle.onclose = () => {
           dbHandle = void 0;
         };
+        dbHandle.onversionchange = () => {
+          try {
+            dbHandle?.close();
+          } catch {
+          }
+          dbHandle = void 0;
+        };
         resolve(req.result);
       };
       req.onerror = () => reject(req.error);
@@ -41,7 +59,30 @@ function idbStorage(opts) {
       return op(await openDb());
     }
   };
-  return {
+  const broadcastSupported = () => broadcastEnabled && typeof BroadcastChannel !== "undefined";
+  let sharedChannel;
+  const subscribers = /* @__PURE__ */ new Set();
+  const ensureChannel = () => {
+    if (!broadcastSupported()) return void 0;
+    if (sharedChannel === void 0) {
+      sharedChannel = new BroadcastChannel(channelName);
+      sharedChannel.onmessage = (event) => {
+        const data = event.data;
+        const values = data?.values ?? {};
+        for (const cb of [...subscribers]) cb(values);
+      };
+    }
+    return sharedChannel;
+  };
+  const broadcast = (values) => {
+    const ch = ensureChannel();
+    if (ch === void 0) return;
+    try {
+      ch.postMessage({ values });
+    } catch {
+    }
+  };
+  const storage = {
     name: "idbStorage",
     clientOnly: true,
     // IDB has no synchronous API. Engine consults `readAsync` for hydration;
@@ -73,6 +114,7 @@ function idbStorage(opts) {
             req.onerror = () => reject(req.error);
           })
         );
+        broadcast(values);
       } catch {
       }
     },
@@ -88,6 +130,7 @@ function idbStorage(opts) {
               req.onerror = () => reject(req.error);
             })
           );
+          broadcast(void 0);
           return;
         }
         const current = await withVersionRetry(
@@ -107,11 +150,21 @@ function idbStorage(opts) {
             req.onerror = () => reject(req.error);
           })
         );
+        broadcast(current);
       } catch {
       }
     }
-    // No `subscribe` — IDB doesn't fire native change events. v0.6+ via BroadcastChannel.
   };
+  if (broadcastSupported()) {
+    storage.subscribe = (callback) => {
+      ensureChannel();
+      subscribers.add(callback);
+      return () => {
+        subscribers.delete(callback);
+      };
+    };
+  }
+  return storage;
 }
 export {
   idbStorage