@zerolith/state 0.0.0-stage → 1.1.0

package/dist/stored.js

@@ -0,0 +1,130 @@
+/**
+ * A signal kept in the browser's storage under a key, as JSON, and in step
+ * across tabs through the `storage` event.
+ */
+import { diagnostic, effect, hasOwner, onDispose, report, signal } from "zerolith";
+/** The storage kinds reported unavailable on this page, each once. */
+const unavailable = new Set();
+/** How many stored signals are live for each key of each storage, so a second one for a key is reported. */
+const live = new Map();
+/** The storage of a kind, or undefined where the page has none or refuses it, which is reported once per kind with the first key asked for. */
+function storageOf(kind, key) {
+    try {
+        const store = kind === "session" ? globalThis.sessionStorage : globalThis.localStorage;
+        store.getItem("");
+        return store;
+    }
+    catch {
+        if (!unavailable.has(kind)) {
+            unavailable.add(kind);
+            report(diagnostic("state_storage_unavailable", "warning", { storage: kind, key }));
+        }
+        return undefined;
+    }
+}
+/** The value kept as `raw` under `key`, or `initial` where nothing is kept or what is kept does not parse, which is reported. */
+function parse(raw, key, initial) {
+    if (raw === null) {
+        return initial;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        report(diagnostic("state_storage_unreadable", "warning", { key }));
+        return initial;
+    }
+}
+/** The JSON for `next`, or undefined for a value JSON cannot hold: a BigInt or a cycle, which throws, and a function or a symbol, which it leaves out. */
+function toJson(next) {
+    try {
+        return JSON.stringify(next);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * A writable signal kept in storage under `key` as JSON: read back on
+ * creation, written on every set, and set again when another tab writes
+ * the key, so every tab shows the same value. A missing value takes
+ * `initial` quietly; one that does not parse takes `initial` and reports
+ * `state_storage_unreadable`. Setting `undefined` removes the key, so it
+ * reads back as `initial`; a value JSON cannot hold, such as a BigInt,
+ * stays in memory and reports `state_value_not_json`. Where the page has
+ * no storage, as on the server, the signal is a plain one and
+ * `state_storage_unavailable` is reported once, as it is for each write
+ * the storage refuses. Create each key once and share the signal: two
+ * stored signals for one key in the same tab do not hear each other,
+ * since the storage event tells other tabs alone, and the second reports
+ * `state_key_duplicate`. The write and the listener for other tabs are
+ * disposed with the enclosing owner when there is one, after which the
+ * signal keeps its value in memory alone; created in plain code, they
+ * live for the page.
+ */
+export function stored(key, initial, options = {}) {
+    const kind = options.storage ?? "local";
+    const store = storageOf(kind, key);
+    const value = signal(store === undefined ? initial : parse(store.getItem(key), key, initial), options.equals === undefined ? undefined : { equals: options.equals });
+    if (store === undefined) {
+        return value;
+    }
+    const id = `${kind}:${key}`;
+    const count = (live.get(id) ?? 0) + 1;
+    live.set(id, count);
+    if (count > 1) {
+        report(diagnostic("state_key_duplicate", "warning", { storage: kind, key }));
+    }
+    let first = true;
+    let echo = false;
+    effect(() => {
+        const next = value.get();
+        if (first || echo) {
+            first = false;
+            return;
+        }
+        const json = toJson(next);
+        if (json === undefined && next !== undefined) {
+            report(diagnostic("state_value_not_json", "warning", { key }));
+            return;
+        }
+        try {
+            if (json === undefined) {
+                store.removeItem(key);
+            }
+            else {
+                store.setItem(key, json);
+            }
+        }
+        catch {
+            report(diagnostic("state_storage_unavailable", "warning", { storage: kind, key }));
+        }
+    });
+    const onStorage = (event) => {
+        if (event.storageArea !== store || (event.key !== null && event.key !== key)) {
+            return;
+        }
+        echo = true;
+        try {
+            value.set(parse(event.newValue, key, initial));
+        }
+        finally {
+            echo = false;
+        }
+    };
+    addEventListener("storage", onStorage);
+    if (hasOwner()) {
+        onDispose(() => {
+            removeEventListener("storage", onStorage);
+            const left = (live.get(id) ?? 1) - 1;
+            if (left > 0) {
+                live.set(id, left);
+            }
+            else {
+                live.delete(id);
+            }
+        });
+    }
+    return value;
+}
+//# sourceMappingURL=stored.js.map

package/dist/stored.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stored.js","sourceRoot":"","sources":["../src/stored.ts"],"names":[],"mappings":"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"}

package/dist/timing.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Signals that follow another in their own time: after a quiet spell, or
+ * at most so often.
+ */
+import { type ReadableSignal } from "zerolith";
+/**
+ * A signal that follows `source` once it has been quiet for `ms`
+ * milliseconds, starting at its current value, so a search runs for the
+ * text a reader stopped typing rather than for every keystroke. The
+ * pending change is dropped with the enclosing owner when there is one.
+ */
+export declare function debounced<T>(source: ReadableSignal<T>, ms: number): ReadableSignal<T>;
+/**
+ * A signal that follows `source` at most once per `ms` milliseconds: the
+ * first change in a window shows at once, and the last one in it shows
+ * when the window ends, so a scroll position drives work at a steady rate.
+ * A change still pending is dropped when a newer one shows after the
+ * window, and with the enclosing owner when there is one.
+ */
+export declare function throttled<T>(source: ReadableSignal<T>, ms: number): ReadableSignal<T>;
+//# sourceMappingURL=timing.d.ts.map

package/dist/timing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../src/timing.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,KAAK,cAAc,EAAkD,MAAM,UAAU,CAAC;AAE/F;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAgBrF;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CA4CrF"}

package/dist/timing.js

@@ -0,0 +1,70 @@
+/**
+ * Signals that follow another in their own time: after a quiet spell, or
+ * at most so often.
+ */
+import { effect, hasOwner, onDispose, signal, untracked } from "zerolith";
+/**
+ * A signal that follows `source` once it has been quiet for `ms`
+ * milliseconds, starting at its current value, so a search runs for the
+ * text a reader stopped typing rather than for every keystroke. The
+ * pending change is dropped with the enclosing owner when there is one.
+ */
+export function debounced(source, ms) {
+    const value = signal(untracked(() => source.get()));
+    let first = true;
+    effect(() => {
+        const next = source.get();
+        if (first) {
+            first = false;
+            return undefined;
+        }
+        const timer = setTimeout(() => value.set(next), ms);
+        return () => clearTimeout(timer);
+    });
+    return value;
+}
+/**
+ * A signal that follows `source` at most once per `ms` milliseconds: the
+ * first change in a window shows at once, and the last one in it shows
+ * when the window ends, so a scroll position drives work at a steady rate.
+ * A change still pending is dropped when a newer one shows after the
+ * window, and with the enclosing owner when there is one.
+ */
+export function throttled(source, ms) {
+    const value = signal(untracked(() => source.get()));
+    let last = Number.NEGATIVE_INFINITY;
+    let timer;
+    let pending;
+    let first = true;
+    const clear = () => {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+    };
+    effect(() => {
+        const next = source.get();
+        if (first) {
+            first = false;
+            return;
+        }
+        const now = Date.now();
+        if (now - last >= ms) {
+            clear();
+            last = now;
+            value.set(next);
+            return;
+        }
+        pending = next;
+        timer ??= setTimeout(() => {
+            timer = undefined;
+            last = Date.now();
+            value.set(pending);
+        }, ms - (now - last));
+    });
+    if (hasOwner()) {
+        onDispose(clear);
+    }
+    return value;
+}
+//# sourceMappingURL=timing.js.map

package/dist/timing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.js","sourceRoot":"","sources":["../src/timing.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAuB,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE/F;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAI,MAAyB,EAAE,EAAU;IAE9D,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACpD,IAAI,KAAK,GAAG,IAAI,CAAC;IACjB,MAAM,CAAC,GAAG,EAAE;QAER,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,EAAE,CAAC;QAC1B,IAAI,KAAK,EACT,CAAC;YACG,KAAK,GAAG,KAAK,CAAC;YACd,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;QACpD,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;IACH,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAI,MAAyB,EAAE,EAAU;IAE9D,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACpD,IAAI,IAAI,GAAG,MAAM,CAAC,iBAAiB,CAAC;IACpC,IAAI,KAAgD,CAAC;IACrD,IAAI,OAAU,CAAC;IACf,IAAI,KAAK,GAAG,IAAI,CAAC;IACjB,MAAM,KAAK,GAAG,GAAS,EAAE;QAErB,IAAI,KAAK,KAAK,SAAS,EACvB,CAAC;YACG,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,KAAK,GAAG,SAAS,CAAC;QACtB,CAAC;IACL,CAAC,CAAC;IACF,MAAM,CAAC,GAAG,EAAE;QAER,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,EAAE,CAAC;QAC1B,IAAI,KAAK,EACT,CAAC;YACG,KAAK,GAAG,KAAK,CAAC;YACd,OAAO;QACX,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,GAAG,GAAG,IAAI,IAAI,EAAE,EACpB,CAAC;YACG,KAAK,EAAE,CAAC;YACR,IAAI,GAAG,GAAG,CAAC;YACX,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAChB,OAAO;QACX,CAAC;QACD,OAAO,GAAG,IAAI,CAAC;QACf,KAAK,KAAK,UAAU,CAAC,GAAG,EAAE;YAEtB,KAAK,GAAG,SAAS,CAAC;YAClB,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAClB,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACvB,CAAC,EAAE,EAAE,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;IACH,IAAI,QAAQ,EAAE,EACd,CAAC;QACG,SAAS,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC"}

package/package.json

@@ -1,6 +1,52 @@
 {
-  "name": "@zerolith/state",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@zerolith/state",
+    "version": "1.1.0",
+    "description": "Signals with a memory for zerolith: a signal kept in storage and across tabs, undo and redo, debounced and throttled signals, and a row selector",
+    "license": "Apache-2.0",
+    "author": "molexxxx",
+    "homepage": "https://zerolith.dev/",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/molexxxx/zerolith.git",
+        "directory": "packages/state"
+    },
+    "bugs": {
+        "url": "https://github.com/molexxxx/zerolith/issues"
+    },
+    "keywords": [
+        "zerolith",
+        "signals",
+        "state",
+        "storage",
+        "undo",
+        "debounce"
+    ],
+    "type": "module",
+    "sideEffects": false,
+    "engines": {
+        "node": ">=24.0.0"
+    },
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "development": "./dist/index.js",
+            "default": "./dist/production/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist",
+        "src",
+        "LICENSE",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.build.json && node ../../scripts/production.ts"
+    },
+    "peerDependencies": {
+        "zerolith": "^1.1.0"
+    },
+    "devDependencies": {
+        "zerolith": "^1.1.0"
+    }
+}

package/src/history.ts

@@ -0,0 +1,105 @@
+/**
+ * Undo and redo for a signal, from explicit checkpoints, as an editor
+ * keeps them.
+ */
+import { type ReadableSignal, type Signal, batch, signal, untracked } from "zerolith";
+
+/** Options for `history`. */
+export interface HistoryOptions
+{
+    /** How many checkpoints are kept; the oldest goes when one more is saved. Defaults to 50, which a value that is not a finite number keeps. */
+    limit?: number;
+}
+
+/** The undo and redo of one signal. */
+export interface History<T>
+{
+    /** Saves the signal's current value as the point `undo()` goes back to, and drops what `redo()` could have brought back. */
+    checkpoint(): void;
+    /** Sets the signal back to the last checkpoint, keeping the current value for `redo()`; false when there is no checkpoint. */
+    undo(): boolean;
+    /** Sets the signal forward to the value the last `undo()` left; false when there is none. */
+    redo(): boolean;
+    /** True while `undo()` has somewhere to go, for a button to follow. */
+    readonly canUndo: ReadableSignal<boolean>;
+    /** True while `redo()` has somewhere to go. */
+    readonly canRedo: ReadableSignal<boolean>;
+    /** Forgets every checkpoint and every value `redo()` could bring back; the signal keeps its value. */
+    dispose(): void;
+    /** The signal the history is of. */
+    readonly source: Signal<T>;
+}
+
+/**
+ * Undo and redo for `source` from explicit checkpoints: call
+ * `checkpoint()` before a change worth undoing, as an editor does before
+ * each edit, and `undo()` sets the signal back to it while `redo()` brings
+ * the undone value back. A new checkpoint after an undo starts a new
+ * branch, as in most editors, so what was undone is gone. `limit`
+ * checkpoints are kept, 50 by default. Each move writes the signal and
+ * both flags in one batch, so an effect over them runs once.
+ */
+export function history<T>(source: Signal<T>, options: HistoryOptions = {}): History<T>
+{
+    const limit = Number.isFinite(options.limit) ? Math.max(1, Math.floor(options.limit as number)) : 50;
+    const past: T[] = [];
+    const future: T[] = [];
+    const canUndo = signal(false);
+    const canRedo = signal(false);
+    const update = (): void =>
+    {
+        canUndo.set(past.length > 0);
+        canRedo.set(future.length > 0);
+    };
+    return {
+        source,
+        canUndo,
+        canRedo,
+        checkpoint(): void
+        {
+            past.push(untracked(() => source.get()));
+            if (past.length > limit)
+            {
+                past.shift();
+            }
+            future.length = 0;
+            batch(update);
+        },
+        undo(): boolean
+        {
+            if (past.length === 0)
+            {
+                return false;
+            }
+            const previous = past.pop() as T;
+            future.push(untracked(() => source.get()));
+            batch(() =>
+            {
+                source.set(previous);
+                update();
+            });
+            return true;
+        },
+        redo(): boolean
+        {
+            if (future.length === 0)
+            {
+                return false;
+            }
+            const next = future.pop() as T;
+            past.push(untracked(() => source.get()));
+            batch(() =>
+            {
+                source.set(next);
+                update();
+            });
+            return true;
+        },
+        dispose(): void
+        {
+            past.length = 0;
+            future.length = 0;
+            batch(update);
+        }
+    };
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @zerolith/state: signals with a memory, over the core alone. A signal
+ * kept in storage and in step across tabs, undo and redo for a signal,
+ * signals that follow another after a quiet spell or at most so often, and
+ * a selector that tells each row whether it is the selected one. The public
+ * surface is assembled here.
+ */
+export type { StoredOptions } from "./stored.js";
+export { stored } from "./stored.js";
+
+export type { History, HistoryOptions } from "./history.js";
+export { history } from "./history.js";
+
+export { debounced, throttled } from "./timing.js";
+
+export { selector } from "./selector.js";

package/src/selector.ts

@@ -0,0 +1,57 @@
+/**
+ * A selector over a signal: one boolean signal per key, true for the key
+ * the source holds, so a selection among many rows updates two rows
+ * rather than every row's own comparison.
+ */
+import { type ReadableSignal, type Signal, effect, signal, untracked } from "zerolith";
+
+/** True when `Map` would treat `a` and `b` as one key. */
+function same(a: unknown, b: unknown): boolean
+{
+    return a === b || (a !== a && b !== b);
+}
+
+/**
+ * A per-key view of `source`: `selected(key)` is a signal that is true
+ * while `source` holds `key`, and a change of `source` updates the two
+ * keys concerned alone, so a list of a thousand rows that each bind
+ * `selected(row.id)` runs two bindings on a selection, not a thousand
+ * comparisons. Keys are compared as `Map` keys are. A key's signal is
+ * shared by everyone who asks for it, and the selector keeps no hold of
+ * its own: the signal lives while a view reads it and goes with the row
+ * that did.
+ */
+export function selector<T>(source: ReadableSignal<T>): (key: T) => ReadableSignal<boolean>
+{
+    const flags = new Map<T, WeakRef<Signal<boolean>>>();
+    const gone = new FinalizationRegistry<T>((key) =>
+    {
+        if (flags.get(key)?.deref() === undefined)
+        {
+            flags.delete(key);
+        }
+    });
+    let current = untracked(() => source.get());
+    effect(() =>
+    {
+        const next = source.get();
+        if (same(next, current))
+        {
+            return;
+        }
+        flags.get(current)?.deref()?.set(false);
+        flags.get(next)?.deref()?.set(true);
+        current = next;
+    });
+    return (key) =>
+    {
+        let flag = flags.get(key)?.deref();
+        if (flag === undefined)
+        {
+            flag = signal(same(key, current));
+            flags.set(key, new WeakRef(flag));
+            gone.register(flag, key);
+        }
+        return flag;
+    };
+}

package/src/stored.ts

@@ -0,0 +1,173 @@
+/**
+ * A signal kept in the browser's storage under a key, as JSON, and in step
+ * across tabs through the `storage` event.
+ */
+import { type Signal, diagnostic, effect, hasOwner, onDispose, report, signal } from "zerolith";
+
+/** Options for `stored`. */
+export interface StoredOptions<T>
+{
+    /** Which storage keeps the value: `localStorage`, shared across tabs and kept across sessions, or `sessionStorage`, this tab's alone. Defaults to local. */
+    storage?: "local" | "session";
+    /** When two values count as the same, so a set of an equal value changes nothing; the signal's own option. */
+    equals?: (previous: T, next: T) => boolean;
+}
+
+/** The storage kinds reported unavailable on this page, each once. */
+const unavailable = new Set<string>();
+
+/** How many stored signals are live for each key of each storage, so a second one for a key is reported. */
+const live = new Map<string, number>();
+
+/** The storage of a kind, or undefined where the page has none or refuses it, which is reported once per kind with the first key asked for. */
+function storageOf(kind: "local" | "session", key: string): Storage | undefined
+{
+    try
+    {
+        const store = kind === "session" ? globalThis.sessionStorage : globalThis.localStorage;
+        store.getItem("");
+        return store;
+    }
+    catch
+    {
+        if (!unavailable.has(kind))
+        {
+            unavailable.add(kind);
+            report(diagnostic("state_storage_unavailable", "warning", { storage: kind, key }));
+        }
+        return undefined;
+    }
+}
+
+/** The value kept as `raw` under `key`, or `initial` where nothing is kept or what is kept does not parse, which is reported. */
+function parse<T>(raw: string | null, key: string, initial: T): T
+{
+    if (raw === null)
+    {
+        return initial;
+    }
+    try
+    {
+        return JSON.parse(raw) as T;
+    }
+    catch
+    {
+        report(diagnostic("state_storage_unreadable", "warning", { key }));
+        return initial;
+    }
+}
+
+/** The JSON for `next`, or undefined for a value JSON cannot hold: a BigInt or a cycle, which throws, and a function or a symbol, which it leaves out. */
+function toJson(next: unknown): string | undefined
+{
+    try
+    {
+        return JSON.stringify(next);
+    }
+    catch
+    {
+        return undefined;
+    }
+}
+
+/**
+ * A writable signal kept in storage under `key` as JSON: read back on
+ * creation, written on every set, and set again when another tab writes
+ * the key, so every tab shows the same value. A missing value takes
+ * `initial` quietly; one that does not parse takes `initial` and reports
+ * `state_storage_unreadable`. Setting `undefined` removes the key, so it
+ * reads back as `initial`; a value JSON cannot hold, such as a BigInt,
+ * stays in memory and reports `state_value_not_json`. Where the page has
+ * no storage, as on the server, the signal is a plain one and
+ * `state_storage_unavailable` is reported once, as it is for each write
+ * the storage refuses. Create each key once and share the signal: two
+ * stored signals for one key in the same tab do not hear each other,
+ * since the storage event tells other tabs alone, and the second reports
+ * `state_key_duplicate`. The write and the listener for other tabs are
+ * disposed with the enclosing owner when there is one, after which the
+ * signal keeps its value in memory alone; created in plain code, they
+ * live for the page.
+ */
+export function stored<T>(key: string, initial: T, options: StoredOptions<T> = {}): Signal<T>
+{
+    const kind = options.storage ?? "local";
+    const store = storageOf(kind, key);
+    const value = signal<T>(store === undefined ? initial : parse(store.getItem(key), key, initial), options.equals === undefined ? undefined : { equals: options.equals });
+    if (store === undefined)
+    {
+        return value;
+    }
+    const id = `${kind}:${key}`;
+    const count = (live.get(id) ?? 0) + 1;
+    live.set(id, count);
+    if (count > 1)
+    {
+        report(diagnostic("state_key_duplicate", "warning", { storage: kind, key }));
+    }
+    let first = true;
+    let echo = false;
+    effect(() =>
+    {
+        const next = value.get();
+        if (first || echo)
+        {
+            first = false;
+            return;
+        }
+        const json = toJson(next);
+        if (json === undefined && next !== undefined)
+        {
+            report(diagnostic("state_value_not_json", "warning", { key }));
+            return;
+        }
+        try
+        {
+            if (json === undefined)
+            {
+                store.removeItem(key);
+            }
+            else
+            {
+                store.setItem(key, json);
+            }
+        }
+        catch
+        {
+            report(diagnostic("state_storage_unavailable", "warning", { storage: kind, key }));
+        }
+    });
+    const onStorage = (event: StorageEvent): void =>
+    {
+        if (event.storageArea !== store || (event.key !== null && event.key !== key))
+        {
+            return;
+        }
+        echo = true;
+        try
+        {
+            value.set(parse(event.newValue, key, initial));
+        }
+        finally
+        {
+            echo = false;
+        }
+    };
+    addEventListener("storage", onStorage);
+    if (hasOwner())
+    {
+        onDispose(() =>
+        {
+            removeEventListener("storage", onStorage);
+            const left = (live.get(id) ?? 1) - 1;
+            if (left > 0)
+            {
+                live.set(id, left);
+            }
+            else
+            {
+                live.delete(id);
+            }
+        });
+    }
+    return value;
+}