@getforma/core 1.1.0 → 1.2.0

package/dist/index.d.cts

@@ -943,6 +943,8 @@ interface HistoryControls<T> {
     cursor: () => number;
     /** Clear all history, keeping only the current value. */
     clear: () => void;
+    /** Stop tracking the source signal and release the history stack. */
+    destroy: () => void;
 }
 /**
  * Create undo/redo history tracking for a signal.
@@ -957,6 +959,13 @@ interface HistoryControls<T> {
  * h.redo();            // count() === 2
  * h.canUndo();         // true (reactive)
  * ```
+ *
+ * **Limitation:** the source must be a signal whose getter returns a stable
+ * value (a primitive or a stable object reference). A `createStore` slice whose
+ * getter returns a *fresh proxy on every read* is not supported: the undo/redo
+ * echo guard compares by identity, so a new proxy each read makes every
+ * undo/redo look like an external change and clears the redo history. Track
+ * store state with `setState`/direct mutation, not `createHistory`.
  */
 declare function createHistory<T>(source: [get: () => T, set: (v: T) => void], options?: {
     maxLength?: number;
@@ -969,6 +978,8 @@ declare function createHistory<T>(source: [get: () => T, set: (v: T) => void], o
  * Reads stored value on creation; writes on every signal change.
  * Zero dependencies -- native browser APIs only.
  */
+/** The phase in which a persist operation failed, passed to {@link PersistOptions.onError}. */
+type PersistErrorPhase = 'hydrate' | 'serialize' | 'write' | 'migrate';
 /** Options for {@link persist} — storage backend, serialization, and validation. */
 interface PersistOptions<T> {
     /** Storage backend. Defaults to localStorage. */
@@ -979,6 +990,14 @@ interface PersistOptions<T> {
     deserialize?: (s: string) => T;
     /** Optional validator — return true if the deserialized value is valid. Rejects corrupt/tampered data. */
     validate?: (v: unknown) => v is T;
+    /** Current schema version. When set, values are stored in a versioned envelope. */
+    version?: number;
+    /** Migrate stored data whose version is older than {@link version}. Runs before validate. */
+    migrate?: (oldValue: unknown, oldVersion: number) => T;
+    /** Re-hydrate when another tab writes this key. Defaults to true for localStorage. */
+    syncTabs?: boolean;
+    /** Report hydrate/serialize/write/migrate failures instead of swallowing them. */
+    onError?: (err: unknown, phase: PersistErrorPhase) => void;
 }
 /**
  * Persist a signal's value to storage.
@@ -993,7 +1012,7 @@ interface PersistOptions<T> {
  * setTheme('dark'); // auto-saved to localStorage under key 'app:theme'
  * ```
  */
-declare function persist<T>(source: [get: () => T, set: (v: T) => void], key: string, options?: PersistOptions<T>): void;
+declare function persist<T>(source: [get: () => T, set: (v: T) => void], key: string, options?: PersistOptions<T>): () => void;
 
 /**
  * A typed publish/subscribe event bus.
@@ -1156,4 +1175,4 @@ declare function onIntersect(el: HTMLElement, handler: (entry: IntersectionObser
  */
 declare function onMutation(el: HTMLElement, handler: (mutations: MutationRecord[]) => void, options?: MutationObserverInit): () => void;
 
-export { $, $$, type CleanupFn, type ComponentDef, type Context, type CreateListOptions, type Dispatch, type ErrorHandler, type EventBus, Fragment, type HistoryControls, type IslandHydrateFn, type KeyOptions, type ListTransitionHooks, type PersistOptions, type ReconcileResult, type Ref, type SetupFn, SignalGetter, type StoreSetter, type SwitchCase, activateIslands, addClass, batch, children, cleanup, closest, createBus, createComputed, createContext, createEffect, createErrorBoundary, createHistory, createList, createMemo, createPortal, createReducer, createRef, createRoot, createShow, createStore, createSuspense, createSwitch, createText, createUnownedRoot, deactivateAllIslands, deactivateIsland, defineComponent, delegate, disposeComponent, fragment, h, hydrateIsland, inject, mount, nextSibling, on, onCleanup, onError, onIntersect, onKey, onMount, onMutation, onResize, onUnmount, parent, persist, prevSibling, provide, reconcileList, removeClass, setAttr, setHTMLUnsafe, setStyle, setText, siblings, template, templateMany, toggleClass, trackDisposer, unprovide, untrack };
+export { $, $$, type CleanupFn, type ComponentDef, type Context, type CreateListOptions, type Dispatch, type ErrorHandler, type EventBus, Fragment, type HistoryControls, type IslandHydrateFn, type KeyOptions, type ListTransitionHooks, type PersistErrorPhase, type PersistOptions, type ReconcileResult, type Ref, type SetupFn, SignalGetter, type StoreSetter, type SwitchCase, activateIslands, addClass, batch, children, cleanup, closest, createBus, createComputed, createContext, createEffect, createErrorBoundary, createHistory, createList, createMemo, createPortal, createReducer, createRef, createRoot, createShow, createStore, createSuspense, createSwitch, createText, createUnownedRoot, deactivateAllIslands, deactivateIsland, defineComponent, delegate, disposeComponent, fragment, h, hydrateIsland, inject, mount, nextSibling, on, onCleanup, onError, onIntersect, onKey, onMount, onMutation, onResize, onUnmount, parent, persist, prevSibling, provide, reconcileList, removeClass, setAttr, setHTMLUnsafe, setStyle, setText, siblings, template, templateMany, toggleClass, trackDisposer, unprovide, untrack };

package/dist/index.d.ts

@@ -943,6 +943,8 @@ interface HistoryControls<T> {
     cursor: () => number;
     /** Clear all history, keeping only the current value. */
     clear: () => void;
+    /** Stop tracking the source signal and release the history stack. */
+    destroy: () => void;
 }
 /**
  * Create undo/redo history tracking for a signal.
@@ -957,6 +959,13 @@ interface HistoryControls<T> {
  * h.redo();            // count() === 2
  * h.canUndo();         // true (reactive)
  * ```
+ *
+ * **Limitation:** the source must be a signal whose getter returns a stable
+ * value (a primitive or a stable object reference). A `createStore` slice whose
+ * getter returns a *fresh proxy on every read* is not supported: the undo/redo
+ * echo guard compares by identity, so a new proxy each read makes every
+ * undo/redo look like an external change and clears the redo history. Track
+ * store state with `setState`/direct mutation, not `createHistory`.
  */
 declare function createHistory<T>(source: [get: () => T, set: (v: T) => void], options?: {
     maxLength?: number;
@@ -969,6 +978,8 @@ declare function createHistory<T>(source: [get: () => T, set: (v: T) => void], o
  * Reads stored value on creation; writes on every signal change.
  * Zero dependencies -- native browser APIs only.
  */
+/** The phase in which a persist operation failed, passed to {@link PersistOptions.onError}. */
+type PersistErrorPhase = 'hydrate' | 'serialize' | 'write' | 'migrate';
 /** Options for {@link persist} — storage backend, serialization, and validation. */
 interface PersistOptions<T> {
     /** Storage backend. Defaults to localStorage. */
@@ -979,6 +990,14 @@ interface PersistOptions<T> {
     deserialize?: (s: string) => T;
     /** Optional validator — return true if the deserialized value is valid. Rejects corrupt/tampered data. */
     validate?: (v: unknown) => v is T;
+    /** Current schema version. When set, values are stored in a versioned envelope. */
+    version?: number;
+    /** Migrate stored data whose version is older than {@link version}. Runs before validate. */
+    migrate?: (oldValue: unknown, oldVersion: number) => T;
+    /** Re-hydrate when another tab writes this key. Defaults to true for localStorage. */
+    syncTabs?: boolean;
+    /** Report hydrate/serialize/write/migrate failures instead of swallowing them. */
+    onError?: (err: unknown, phase: PersistErrorPhase) => void;
 }
 /**
  * Persist a signal's value to storage.
@@ -993,7 +1012,7 @@ interface PersistOptions<T> {
  * setTheme('dark'); // auto-saved to localStorage under key 'app:theme'
  * ```
  */
-declare function persist<T>(source: [get: () => T, set: (v: T) => void], key: string, options?: PersistOptions<T>): void;
+declare function persist<T>(source: [get: () => T, set: (v: T) => void], key: string, options?: PersistOptions<T>): () => void;
 
 /**
  * A typed publish/subscribe event bus.
@@ -1156,4 +1175,4 @@ declare function onIntersect(el: HTMLElement, handler: (entry: IntersectionObser
  */
 declare function onMutation(el: HTMLElement, handler: (mutations: MutationRecord[]) => void, options?: MutationObserverInit): () => void;
 
-export { $, $$, type CleanupFn, type ComponentDef, type Context, type CreateListOptions, type Dispatch, type ErrorHandler, type EventBus, Fragment, type HistoryControls, type IslandHydrateFn, type KeyOptions, type ListTransitionHooks, type PersistOptions, type ReconcileResult, type Ref, type SetupFn, SignalGetter, type StoreSetter, type SwitchCase, activateIslands, addClass, batch, children, cleanup, closest, createBus, createComputed, createContext, createEffect, createErrorBoundary, createHistory, createList, createMemo, createPortal, createReducer, createRef, createRoot, createShow, createStore, createSuspense, createSwitch, createText, createUnownedRoot, deactivateAllIslands, deactivateIsland, defineComponent, delegate, disposeComponent, fragment, h, hydrateIsland, inject, mount, nextSibling, on, onCleanup, onError, onIntersect, onKey, onMount, onMutation, onResize, onUnmount, parent, persist, prevSibling, provide, reconcileList, removeClass, setAttr, setHTMLUnsafe, setStyle, setText, siblings, template, templateMany, toggleClass, trackDisposer, unprovide, untrack };
+export { $, $$, type CleanupFn, type ComponentDef, type Context, type CreateListOptions, type Dispatch, type ErrorHandler, type EventBus, Fragment, type HistoryControls, type IslandHydrateFn, type KeyOptions, type ListTransitionHooks, type PersistErrorPhase, type PersistOptions, type ReconcileResult, type Ref, type SetupFn, SignalGetter, type StoreSetter, type SwitchCase, activateIslands, addClass, batch, children, cleanup, closest, createBus, createComputed, createContext, createEffect, createErrorBoundary, createHistory, createList, createMemo, createPortal, createReducer, createRef, createRoot, createShow, createStore, createSuspense, createSwitch, createText, createUnownedRoot, deactivateAllIslands, deactivateIsland, defineComponent, delegate, disposeComponent, fragment, h, hydrateIsland, inject, mount, nextSibling, on, onCleanup, onError, onIntersect, onKey, onMount, onMutation, onResize, onUnmount, parent, persist, prevSibling, provide, reconcileList, removeClass, setAttr, setHTMLUnsafe, setStyle, setText, siblings, template, templateMany, toggleClass, trackDisposer, unprovide, untrack };

package/dist/index.js

@@ -1,20 +1,20 @@
-import { hydrateIsland } from './chunk-MIOMT2CB.js';
-export { Fragment, cleanup, createList, createShow, fragment, h, hydrateIsland, reconcileList } from './chunk-MIOMT2CB.js';
-import { internalEffect, createUnownedRoot, createRoot, untrack, registerDisposer, createEffect, pushSuspenseContext, popSuspenseContext, batch } from './chunk-INNOI6TG.js';
-export { batch, createEffect, createMemo, createReducer, createRef, createResource, createRoot, createUnownedRoot, getBatchDepth, isComputed, isEffect, isEffectScope, isSignal, on, onCleanup, trigger, untrack } from './chunk-INNOI6TG.js';
-import { createSignal, __DEV__, reportError } from './chunk-XLVBYXOU.js';
-export { createComputed, createSignal, onError } from './chunk-XLVBYXOU.js';
+import { hydrateIsland } from './chunk-YRNYOZF3.js';
+export { Fragment, cleanup, createList, createShow, fragment, h, hydrateIsland, reconcileList } from './chunk-YRNYOZF3.js';
+import { internalEffect, createUnownedRoot, createRoot, untrack, registerDisposer, createEffect, pushSuspenseContext, popSuspenseContext, batch } from './chunk-Y3A2EVVS.js';
+export { batch, createEffect, createMemo, createReducer, createRef, createResource, createRoot, createUnownedRoot, getBatchDepth, isComputed, isEffect, isEffectScope, isSignal, on, onCleanup, trigger, untrack } from './chunk-Y3A2EVVS.js';
+import { createSignal, __DEV__, reportError, value } from './chunk-ETPJTPYD.js';
+export { createComputed, createSignal, onError } from './chunk-ETPJTPYD.js';
 
 // src/dom/text.ts
-function createText(value) {
-  if (typeof value === "function") {
+function createText(value2) {
+  if (typeof value2 === "function") {
     const node = new Text("");
     internalEffect(() => {
-      node.data = value();
+      node.data = value2();
     });
     return node;
   }
-  return new Text(value);
+  return new Text(value2);
 }
 
 // src/dom/mount.ts
@@ -47,7 +47,7 @@ function mount(component, container) {
 }
 
 // src/dom/switch.ts
-function createSwitch(value, cases, fallback) {
+function createSwitch(value2, cases, fallback) {
   const startMarker = document.createComment("forma-switch");
   const endMarker = document.createComment("/forma-switch");
   const fragment2 = document.createDocumentFragment();
@@ -57,7 +57,7 @@ function createSwitch(value, cases, fallback) {
   let currentNode = null;
   let currentMatch = UNSET;
   const switchDispose = internalEffect(() => {
-    const val = value();
+    const val = value2();
     if (val === currentMatch) return;
     const DEBUG = typeof globalThis.__FORMA_DEBUG__ !== "undefined";
     if (DEBUG) console.log("[forma:switch] transition", String(currentMatch), "\u2192", String(val));
@@ -437,13 +437,13 @@ function createContext(defaultValue) {
     defaultValue
   };
 }
-function provide(ctx, value) {
+function provide(ctx, value2) {
   let stack = contextStacks.get(ctx.id);
   if (stack === void 0) {
     stack = [];
     contextStacks.set(ctx.id, stack);
   }
-  stack.push(value);
+  stack.push(value2);
 }
 function inject(ctx) {
   const stack = contextStacks.get(ctx.id);
@@ -499,6 +499,19 @@ function deepClone(obj, seen) {
 function createStore(initial) {
   const signals = /* @__PURE__ */ new Map();
   const children2 = /* @__PURE__ */ new Map();
+  const arrayVersions = /* @__PURE__ */ new Map();
+  function getArrayVersion(path) {
+    let p = arrayVersions.get(path);
+    if (!p) {
+      p = createSignal(0);
+      arrayVersions.set(path, p);
+    }
+    return p;
+  }
+  function bumpArrayVersion(path) {
+    const p = arrayVersions.get(path);
+    if (p) p[1]((n) => n + 1);
+  }
   function registerChild(path) {
     const lastDot = path.lastIndexOf(".");
     if (lastDot === -1) return;
@@ -530,14 +543,37 @@ function createStore(initial) {
     }
     childSet.clear();
   }
+  function lastSegment(path) {
+    const d = path.lastIndexOf(".");
+    return d === -1 ? path : path.substring(d + 1);
+  }
+  function setLiteral(pair, v) {
+    pair[1](typeof v === "function" ? value(v) : v);
+  }
+  function reconcileChildren(parentPath, rawParent) {
+    const set = children2.get(parentPath);
+    if (!set) return;
+    for (const childPath of set) {
+      const key = lastSegment(childPath);
+      const nv = rawParent[key];
+      const pair = signals.get(childPath);
+      if (pair) setLiteral(pair, nv);
+      if (nv != null && typeof nv === "object") {
+        reconcileChildren(childPath, nv);
+      } else {
+        invalidateChildren(childPath);
+      }
+    }
+  }
   function wrap(raw, basePath) {
     if (!shouldWrap(raw)) return raw;
-    const cached = proxyCache.get(raw);
-    if (cached) return cached;
+    let byPath = proxyCache.get(raw);
+    if (byPath) {
+      const hit = byPath.get(basePath);
+      if (hit) return hit;
+    }
     const isArr = Array.isArray(raw);
     const basePrefix = basePath ? basePath + "." : "";
-    let lastKey = "";
-    let lastSignal;
     const proxy = new Proxy(raw, {
       // -------------------------------------------------------------------
       // GET
@@ -558,12 +594,10 @@ function createStore(initial) {
                 (a) => a != null && typeof a === "object" && a[RAW] ? a[RAW] : a
               );
               result = target[key].apply(target, rawArgs);
-              invalidateChildren(basePath);
-              const [, setLen] = getSignal(
-                basePrefix + "length",
-                target.length
-              );
-              setLen(target.length);
+              reconcileChildren(basePath, target);
+              const lenPair = signals.get(basePrefix + "length");
+              if (lenPair) lenPair[1](target.length);
+              if (basePath) bumpArrayVersion(basePath);
             });
             return result;
           };
@@ -573,34 +607,32 @@ function createStore(initial) {
           getter();
           return target.length;
         }
-        const value = Reflect.get(target, prop);
-        let pair;
-        if (key === lastKey && lastSignal) {
-          pair = lastSignal;
-        } else {
-          pair = getSignal(childPath, value);
-          lastKey = key;
-          lastSignal = pair;
-        }
+        const value2 = Reflect.get(target, prop);
+        const pair = getSignal(childPath, value2);
         pair[0]();
-        if (shouldWrap(value)) {
-          return wrap(value, childPath);
+        if (Array.isArray(value2)) {
+          getArrayVersion(childPath)[0]();
+        }
+        if (shouldWrap(value2)) {
+          return wrap(value2, childPath);
         }
-        return value;
+        return value2;
       },
       // -------------------------------------------------------------------
       // SET
       // -------------------------------------------------------------------
-      set(target, prop, value) {
+      set(target, prop, value2) {
         if (typeof prop === "symbol") {
-          return Reflect.set(target, prop, value);
+          return Reflect.set(target, prop, value2);
         }
         const key = String(prop);
         const childPath = basePrefix + key;
-        const rawValue = value != null && typeof value === "object" && value[RAW] ? value[RAW] : value;
+        const rawValue = value2 != null && typeof value2 === "object" && value2[RAW] ? value2[RAW] : value2;
+        const oldRaw = Reflect.get(target, prop);
         Reflect.set(target, prop, rawValue);
-        if (rawValue != null && typeof rawValue === "object") {
+        if (rawValue != null && typeof rawValue === "object" && oldRaw !== rawValue) {
           invalidateChildren(childPath);
+          evictProxy(oldRaw, childPath);
         }
         if (isArr && key !== "length") {
           const lengthPath = basePrefix + "length";
@@ -609,6 +641,12 @@ function createStore(initial) {
             lenPair[1](target.length);
           }
         }
+        if (isArr && key === "length") {
+          batch(() => {
+            reconcileChildren(basePath, target);
+            if (basePath) bumpArrayVersion(basePath);
+          });
+        }
         const [, setter2] = getSignal(childPath, rawValue);
         setter2(rawValue);
         return true;
@@ -647,24 +685,30 @@ function createStore(initial) {
         }
         const key = String(prop);
         const childPath = basePrefix + key;
+        const oldRaw = Reflect.get(target, prop);
         const result = Reflect.deleteProperty(target, prop);
+        const delPair = signals.get(childPath);
+        if (delPair) delPair[1](void 0);
+        evictProxy(oldRaw, childPath);
         invalidateChildren(childPath);
-        signals.delete(childPath);
-        const parentPath = basePath;
-        if (parentPath !== void 0) {
-          const parentSet = children2.get(parentPath);
-          if (parentSet) {
-            parentSet.delete(childPath);
-            if (parentSet.size === 0) children2.delete(parentPath);
-          }
-        }
-        children2.delete(childPath);
         return result;
       }
     });
-    proxyCache.set(raw, proxy);
+    if (!byPath) {
+      byPath = /* @__PURE__ */ new Map();
+      proxyCache.set(raw, byPath);
+    }
+    byPath.set(basePath, proxy);
     return proxy;
   }
+  function evictProxy(oldRaw, path) {
+    if (oldRaw == null || typeof oldRaw !== "object") return;
+    const om = proxyCache.get(oldRaw);
+    if (om) {
+      om.delete(path);
+      if (om.size === 0) proxyCache.delete(oldRaw);
+    }
+  }
   const rootProxy = wrap(initial, "");
   function getCurrentSnapshot() {
     return untrack(() => deepClone(initial));
@@ -681,10 +725,24 @@ function createStore(initial) {
 }
 
 // src/state/history.ts
+function cloneEntry(v, seen) {
+  if (v === null || typeof v !== "object") return v;
+  const proto = Object.getPrototypeOf(v);
+  if (!Array.isArray(v) && proto !== Object.prototype && proto !== null) return v;
+  if (!seen) seen = /* @__PURE__ */ new WeakSet();
+  if (seen.has(v)) return v;
+  seen.add(v);
+  if (Array.isArray(v)) return v.map((i) => cloneEntry(i, seen));
+  const out = {};
+  for (const k of Object.keys(v)) {
+    out[k] = cloneEntry(v[k], seen);
+  }
+  return out;
+}
 function createHistory(source, options) {
   const [sourceGet, sourceSet] = source;
-  const maxLength = options?.maxLength ?? 100;
-  let _stack = [sourceGet()];
+  const maxLength = Math.max(1, options?.maxLength ?? 100);
+  let _stack = [cloneEntry(sourceGet())];
   let _cursor = 0;
   const [stackSignal, setStackSignal] = createSignal([..._stack]);
   const [cursorSignal, setCursorSignal] = createSignal(_cursor);
@@ -696,45 +754,52 @@ function createHistory(source, options) {
       setStackLenSignal(_stack.length);
     });
   }
-  let ignoreNext = false;
+  const NONE = /* @__PURE__ */ Symbol("none");
+  let _expected = NONE;
   let isFirstRun = true;
-  internalEffect(() => {
-    const value = sourceGet();
+  const disposeEffect = internalEffect(() => {
+    const value2 = sourceGet();
     if (isFirstRun) {
       isFirstRun = false;
       return;
     }
-    if (ignoreNext) {
-      ignoreNext = false;
+    if (_expected !== NONE && Object.is(value2, _expected)) {
+      _expected = NONE;
       return;
     }
+    _expected = NONE;
     _stack = _stack.slice(0, _cursor + 1);
-    _stack.push(value);
+    _stack.push(cloneEntry(value2));
     if (_stack.length > maxLength) {
       _stack.splice(0, _stack.length - maxLength);
     }
     _cursor = _stack.length - 1;
     syncSignals();
   });
+  const destroy = () => {
+    disposeEffect();
+  };
   const canUndo = () => cursorSignal() > 0;
   const canRedo = () => cursorSignal() < stackLenSignal() - 1;
   const undo = () => {
     if (_cursor <= 0) return;
     _cursor--;
-    ignoreNext = true;
-    sourceSet(_stack[_cursor]);
+    const restored = cloneEntry(_stack[_cursor]);
+    _expected = restored;
+    sourceSet(restored);
     syncSignals();
   };
   const redo = () => {
     if (_cursor >= _stack.length - 1) return;
     _cursor++;
-    ignoreNext = true;
-    sourceSet(_stack[_cursor]);
+    const restored = cloneEntry(_stack[_cursor]);
+    _expected = restored;
+    sourceSet(restored);
     syncSignals();
   };
   const clear = () => {
     const currentValue = sourceGet();
-    _stack = [currentValue];
+    _stack = [cloneEntry(currentValue)];
     _cursor = 0;
     syncSignals();
   };
@@ -745,35 +810,91 @@ function createHistory(source, options) {
     canRedo,
     history: () => stackSignal(),
     cursor: () => cursorSignal(),
-    clear
+    clear,
+    destroy
   };
 }
 
 // src/state/persist.ts
+var ENVELOPE_TAG = "$forma:v";
 function persist(source, key, options) {
   const [sourceGet, sourceSet] = source;
   const storage = options?.storage ?? globalThis.localStorage;
   const serialize = options?.serialize ?? JSON.stringify;
   const deserialize = options?.deserialize ?? JSON.parse;
   const validate = options?.validate;
-  try {
-    const stored = storage.getItem(key);
-    if (stored !== null) {
-      const value = deserialize(stored);
-      if (!validate || validate(value)) {
-        sourceSet(value);
+  const version = options?.version;
+  const migrate = options?.migrate;
+  const onError2 = options?.onError;
+  let writing = false;
+  function unwrap(stored) {
+    const parsed = deserialize(stored);
+    if (parsed != null && typeof parsed === "object" && Object.prototype.hasOwnProperty.call(parsed, ENVELOPE_TAG)) {
+      const env = parsed;
+      return { value: env.value, version: Number(env[ENVELOPE_TAG]) };
+    }
+    return { value: parsed, version: 0 };
+  }
+  function hydrate() {
+    let stored;
+    try {
+      stored = storage.getItem(key);
+    } catch (err) {
+      onError2?.(err, "hydrate");
+      return;
+    }
+    if (stored === null) return;
+    try {
+      const { value: raw, version: storedVersion } = unwrap(stored);
+      let value2 = raw;
+      if (version !== void 0 && storedVersion < version) {
+        if (!migrate) return;
+        try {
+          value2 = migrate(raw, storedVersion);
+        } catch (err) {
+          onError2?.(err, "migrate");
+          return;
+        }
+      }
+      if (!validate || validate(value2)) {
+        writing = true;
+        try {
+          sourceSet(value2);
+        } finally {
+          writing = false;
+        }
       }
+    } catch (err) {
+      onError2?.(err, "hydrate");
     }
-  } catch {
   }
-  internalEffect(() => {
-    const value = sourceGet();
+  hydrate();
+  const stopEffect = internalEffect(() => {
+    const value2 = sourceGet();
+    if (writing) return;
     try {
-      const serialized = serialize(value);
+      const serialized = version !== void 0 ? serialize({ [ENVELOPE_TAG]: version, value: value2 }) : serialize(value2);
       storage.setItem(key, serialized);
-    } catch {
+    } catch (err) {
+      onError2?.(err, err?.name === "QuotaExceededError" ? "write" : "serialize");
     }
   });
+  const enableSync = options?.syncTabs ?? (typeof window !== "undefined" && storage === globalThis.localStorage);
+  let onStorage;
+  if (enableSync && typeof window !== "undefined") {
+    onStorage = (e) => {
+      if (e.storageArea !== storage) return;
+      if (e.key !== null && e.key !== key) return;
+      hydrate();
+    };
+    window.addEventListener("storage", onStorage);
+  }
+  return () => {
+    stopEffect();
+    if (onStorage && typeof window !== "undefined") {
+      window.removeEventListener("storage", onStorage);
+    }
+  };
 }
 
 // src/events/bus.ts
@@ -920,20 +1041,20 @@ function toggleClass(el, className, force) {
   return el.classList.toggle(className, force);
 }
 function setStyle(el, styles) {
-  for (const [key, value] of Object.entries(styles)) {
-    if (value !== void 0) {
-      el.style[key] = value;
+  for (const [key, value2] of Object.entries(styles)) {
+    if (value2 !== void 0) {
+      el.style[key] = value2;
     }
   }
 }
 function setAttr(el, attrs) {
-  for (const [name, value] of Object.entries(attrs)) {
-    if (value === false || value === null) {
+  for (const [name, value2] of Object.entries(attrs)) {
+    if (value2 === false || value2 === null) {
       el.removeAttribute(name);
-    } else if (value === true) {
+    } else if (value2 === true) {
       el.setAttribute(name, "");
     } else {
-      el.setAttribute(name, value);
+      el.setAttribute(name, value2);
     }
   }
 }