@rethunk/react-load-hooks 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rethunk.Tech, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+<h1 align="center">react-load-hooks</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<div align="center">
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![npm](https://img.shields.io/npm/v/@rethunk/react-load-hooks.svg)](https://www.npmjs.com/package/@rethunk/react-load-hooks)
+[![TypeScript](https://img.shields.io/badge/TypeScript-typed-3178C6?logo=typescript&logoColor=white)](tsconfig.json)
+
+</div>
+
+---
+
+React hooks for async loads that never land out of order, plus the small state hooks an app builds screens from. Package `@rethunk/react-load-hooks`. First consumer: Mortar.
+
+Only the newest load lands: a slower, older answer or error never overwrites a newer one, and an
+unmounted component hears nothing.
+
+```tsx
+const { data, loading, error, reload } = useLoaded(() => fetchRepos(owner), [owner], [])
+```
+
+## Quick start
+
+```bash
+bun add @rethunk/react-load-hooks
+```
+
+A worked example and the contracts: [HUMANS.md](HUMANS.md).
+
+## Features
+
+- `useLoaded` and `useDebouncedLoad` fetch on dependency changes and drop superseded answers.
+- `loader` is the same logic without React, for a store or a class.
+- `useStoredState` persists UI state in `localStorage`.
+- `useWidth` tracks an element's width before paint; `useDebouncedValue` settles a fast-changing value.
+- `useNowValue` and `useSecondValue` share one timer per period and re-render only on a changed answer.
+
+## Documentation
+
+| Doc | Audience |
+| --- | --- |
+| [HUMANS.md](HUMANS.md) | Running and using the package |
+| [AGENTS.md](AGENTS.md) | Internals, invariants, and why |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Process — commits, tests, docs |
+| [SECURITY.md](SECURITY.md) | Vulnerability disclosure |
+| [CHANGELOG.md](CHANGELOG.md) | Release notes |
+
+## License
+
+MIT — see [LICENSE](LICENSE). © 2026 Rethunk.Tech, LLC.

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { type LoadSink, loader } from './loader.ts';
+export { useDebouncedLoad } from './useDebouncedLoad.ts';
+export { useDebouncedValue } from './useDebouncedValue.ts';
+export { useLoaded } from './useLoaded.ts';
+export { useNowValue, useSecondValue } from './useNow.ts';
+export { readStored, useStoredState, writeStored } from './useStoredState.ts';
+export { useWidth } from './useWidth.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACzD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAC7E,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { loader } from './loader.js';
+export { useDebouncedLoad } from './useDebouncedLoad.js';
+export { useDebouncedValue } from './useDebouncedValue.js';
+export { useLoaded } from './useLoaded.js';
+export { useNowValue, useSecondValue } from './useNow.js';
+export { readStored, useStoredState, writeStored } from './useStoredState.js';
+export { useWidth } from './useWidth.js';

package/dist/loader.d.ts

@@ -0,0 +1,23 @@
+import type { DependencyList } from 'react';
+export interface LoadSink<T> {
+    value: (value: T) => void;
+    error: (error: unknown) => void;
+    loading: (on: boolean) => void;
+    /** Shows the hook's initial value again. */
+    reset: () => void;
+}
+/**
+ * useLoaded's and useDebouncedLoad's logic without React. Only the newest load lands: a later load, new deps or stop
+ * drops the answer, error and end of every one before it. New deps reset the value unless keepAcrossKeys, and a null
+ * load always does. `defer` starts a load, now or later, and returns what cancels the start.
+ */
+export declare function loader<T>(sink: LoadSink<T>, { keepAcrossKeys, defer, }?: {
+    keepAcrossKeys?: boolean;
+    defer?: (go: () => void) => () => void;
+}): {
+    deps(deps: DependencyList, load: (() => Promise<T>) | null): void;
+    /** Runs a load at once with the same deps, keeping the value shown until it answers; resolves when it has. */
+    run(load: (() => Promise<T>) | null): Promise<void>;
+    stop(): void;
+};
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAK3C,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAA;IACzB,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IAC/B,OAAO,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,IAAI,CAAA;IAC9B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAOD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EACtB,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EACjB,EACE,cAAsB,EACtB,KAAW,GACZ,GAAE;IAAE,cAAc,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAA;CAAO;IAuC1E,IAAI,OAAO,cAAc,QAAQ,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;IAoB1D,8GAA8G;IAC9G,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAOnD,IAAI;EAKP"}

package/dist/loader.js

@@ -0,0 +1,79 @@
+const sameDeps = (a, b) => a !== null && a.length === b.length && b.every((dep, i) => Object.is(dep, a[i]));
+const now = (go) => {
+    go();
+    return () => undefined;
+};
+/**
+ * useLoaded's and useDebouncedLoad's logic without React. Only the newest load lands: a later load, new deps or stop
+ * drops the answer, error and end of every one before it. New deps reset the value unless keepAcrossKeys, and a null
+ * load always does. `defer` starts a load, now or later, and returns what cancels the start.
+ */
+export function loader(sink, { keepAcrossKeys = false, defer = now, } = {}) {
+    let generation = 0;
+    let seen = null;
+    let cancel = () => undefined;
+    const drop = () => {
+        generation += 1;
+        cancel();
+    };
+    const start = (load) => {
+        generation += 1;
+        const mine = generation;
+        const current = () => generation === mine;
+        sink.loading(true);
+        return load()
+            .then((value) => {
+            if (current()) {
+                sink.value(value);
+            }
+        }, (error) => {
+            if (current()) {
+                sink.error(error);
+            }
+        })
+            .finally(() => {
+            if (current()) {
+                sink.loading(false);
+            }
+        });
+    };
+    const skip = () => {
+        drop();
+        sink.reset();
+        sink.loading(false);
+    };
+    return {
+        deps(deps, load) {
+            if (sameDeps(seen, deps)) {
+                return;
+            }
+            const fresh = seen !== null;
+            seen = deps;
+            if (load === null) {
+                skip();
+                return;
+            }
+            drop();
+            if (fresh && !keepAcrossKeys) {
+                sink.reset();
+            }
+            sink.loading(true);
+            // start settles through the sink, so only a throwing sink handler reaches this catch.
+            cancel = defer(() => {
+                start(load).catch(sink.error);
+            });
+        },
+        /** Runs a load at once with the same deps, keeping the value shown until it answers; resolves when it has. */
+        run(load) {
+            if (load === null) {
+                skip();
+                return Promise.resolve();
+            }
+            return start(load);
+        },
+        stop() {
+            drop();
+            seen = null;
+        },
+    };
+}

package/dist/useDebouncedLoad.d.ts

@@ -0,0 +1,18 @@
+import { type DependencyList } from 'react';
+/**
+ * useLoaded for input that changes on every key: `load` runs `delayMs` (read afresh each time a load is scheduled)
+ * after `deps` last changed, and `data` keeps the last answer meanwhile. Only the newest run lands, so `onError` hears
+ * only the newest failure. A null `load` resets `data` to `initial`. `run` starts another load at once, such as the
+ * next page, under the same rule.
+ */
+export declare function useDebouncedLoad<T>(load: (() => Promise<T>) | null, deps: DependencyList, { initial, delayMs, onError, }: {
+    initial: T;
+    delayMs: number;
+    onError?: (error: unknown) => void;
+}): {
+    data: T;
+    loading: boolean;
+    error: unknown;
+    run: (next: () => Promise<T>) => Promise<void>;
+};
+//# sourceMappingURL=useDebouncedLoad.d.ts.map

package/dist/useDebouncedLoad.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDebouncedLoad.d.ts","sourceRoot":"","sources":["../src/useDebouncedLoad.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAA+B,MAAM,OAAO,CAAA;AAGxE;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,IAAI,EAAE,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,EAC/B,IAAI,EAAE,cAAc,EACpB,EACE,OAAO,EACP,OAAO,EACP,OAAO,GACR,EAAE;IAAE,OAAO,EAAE,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CAAE;;;;gBAwCxD,MAAM,OAAO,CAAC,CAAC,CAAC;EAE/B"}

package/dist/useDebouncedLoad.js

@@ -0,0 +1,45 @@
+import { useEffect, useRef, useState } from 'react';
+import { loader } from './loader.js';
+/**
+ * useLoaded for input that changes on every key: `load` runs `delayMs` (read afresh each time a load is scheduled)
+ * after `deps` last changed, and `data` keeps the last answer meanwhile. Only the newest run lands, so `onError` hears
+ * only the newest failure. A null `load` resets `data` to `initial`. `run` starts another load at once, such as the
+ * next page, under the same rule.
+ */
+export function useDebouncedLoad(load, deps, { initial, delayMs, onError, }) {
+    const [data, setData] = useState(initial);
+    const [loading, setLoading] = useState(load !== null);
+    const [error, setError] = useState(null);
+    const latest = useRef({ initial, onError, delayMs });
+    latest.current = { initial, onError, delayMs };
+    const [runs] = useState(() => loader({
+        value: (value) => {
+            setData(() => value);
+            setError(null);
+        },
+        error: (e) => {
+            setError(e);
+            latest.current.onError?.(e);
+        },
+        loading: setLoading,
+        reset: () => setData(() => latest.current.initial),
+    }, {
+        keepAcrossKeys: true,
+        defer: (go) => {
+            const timer = globalThis.setTimeout(go, latest.current.delayMs);
+            return () => globalThis.clearTimeout(timer);
+        },
+    }));
+    // Runs after every render and acts only when the caller's deps changed: an effect cannot take a caller-supplied
+    // dependency list.
+    useEffect(() => {
+        runs.deps(deps, load);
+    });
+    useEffect(() => () => runs.stop(), [runs]);
+    return {
+        data,
+        loading,
+        error,
+        run: (next) => runs.run(next),
+    };
+}

package/dist/useDebouncedValue.d.ts

@@ -0,0 +1,3 @@
+/** `value` once it has held still for `ms`; the first render returns it at once. */
+export declare function useDebouncedValue<T>(value: T, ms: number): T;
+//# sourceMappingURL=useDebouncedValue.d.ts.map

package/dist/useDebouncedValue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDebouncedValue.d.ts","sourceRoot":"","sources":["../src/useDebouncedValue.ts"],"names":[],"mappings":"AAEA,oFAAoF;AACpF,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,CAAC,CAO5D"}

package/dist/useDebouncedValue.js

@@ -0,0 +1,10 @@
+import { useEffect, useState } from 'react';
+/** `value` once it has held still for `ms`; the first render returns it at once. */
+export function useDebouncedValue(value, ms) {
+    const [settled, setSettled] = useState(value);
+    useEffect(() => {
+        const timer = setTimeout(() => setSettled(value), ms);
+        return () => clearTimeout(timer);
+    }, [value, ms]);
+    return settled;
+}

package/dist/useLoaded.d.ts

@@ -0,0 +1,15 @@
+import { type DependencyList } from 'react';
+/**
+ * Runs `load` whenever `deps` change (never while `load` is null) and drops the answer of any run that has been
+ * superseded or unmounted. New deps and a null load reset `data` to `initial`; a failed load keeps the last good `data`
+ * and sets `error`. `reload` runs it again with the same deps and keeps the old value until the answer arrives;
+ * `setData` edits the loaded value in place.
+ */
+export declare function useLoaded<T>(load: (() => Promise<T>) | null, deps: DependencyList, initial: T, onError?: (error: unknown) => void): {
+    data: T;
+    setData: import("react").Dispatch<import("react").SetStateAction<T>>;
+    loading: boolean;
+    error: unknown;
+    reload: () => Promise<void>;
+};
+//# sourceMappingURL=useLoaded.d.ts.map

package/dist/useLoaded.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLoaded.d.ts","sourceRoot":"","sources":["../src/useLoaded.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAA4C,MAAM,OAAO,CAAA;AAGrF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,IAAI,EAAE,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,EAC/B,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,CAAC,EACV,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI;;;;;;EA+BnC"}

package/dist/useLoaded.js

@@ -0,0 +1,37 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { loader } from './loader.js';
+/**
+ * Runs `load` whenever `deps` change (never while `load` is null) and drops the answer of any run that has been
+ * superseded or unmounted. New deps and a null load reset `data` to `initial`; a failed load keeps the last good `data`
+ * and sets `error`. `reload` runs it again with the same deps and keeps the old value until the answer arrives;
+ * `setData` edits the loaded value in place.
+ */
+export function useLoaded(load, deps, initial, onError) {
+    const [data, setData] = useState(initial);
+    const [loading, setLoading] = useState(load !== null);
+    const [error, setError] = useState(null);
+    const latest = useRef({ load, initial, onError });
+    latest.current = { load, initial, onError };
+    const [runs] = useState(() => loader({
+        value: (value) => setData(() => value),
+        error: (e) => {
+            setError(e);
+            latest.current.onError?.(e);
+        },
+        loading: (on) => {
+            setLoading(on);
+            if (on) {
+                setError(null);
+            }
+        },
+        reset: () => setData(() => latest.current.initial),
+    }));
+    // Runs after every render and starts a load only when the caller's deps changed: an effect cannot take a
+    // caller-supplied dependency list.
+    useEffect(() => {
+        runs.deps(deps, load);
+    });
+    useEffect(() => () => runs.stop(), [runs]);
+    const reload = useCallback(() => runs.run(latest.current.load), [runs]);
+    return { data, setData, loading, error, reload };
+}

package/dist/useNow.d.ts

@@ -0,0 +1,6 @@
+/** compute's answer from the minute clock; the component re-renders only when the answer changes, so compute returns a
+ * primitive (a label rather than the time). */
+export declare function useNowValue<T extends string | number | boolean>(compute: (now: number) => T): T;
+/** useNowValue on a clock that ticks every second while `on`; compute should return a constant while off. */
+export declare function useSecondValue<T extends string | number | boolean>(compute: (now: number) => T, on: boolean): T;
+//# sourceMappingURL=useNow.d.ts.map

package/dist/useNow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useNow.d.ts","sourceRoot":"","sources":["../src/useNow.ts"],"names":[],"mappings":"AAiDA;+CAC+C;AAC/C,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,GAAG,CAAC,CAE/F;AAED,6GAA6G;AAC7G,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,OAAO,EAChE,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,CAAC,EAC3B,EAAE,EAAE,OAAO,GACV,CAAC,CAEH"}

package/dist/useNow.js

@@ -0,0 +1,46 @@
+import { useSyncExternalStore } from 'react';
+const second = 1000;
+const minute = 60_000;
+// One shared timer per period, running only while some component watches it.
+function tickingClock(period) {
+    const listeners = new Set();
+    let now = Date.now();
+    let timer;
+    function tick() {
+        now = Date.now();
+        for (const listener of listeners) {
+            listener();
+        }
+    }
+    function subscribe(listener) {
+        listeners.add(listener);
+        if (listeners.size === 1) {
+            // The clock stood still while nobody watched it.
+            now = Date.now();
+            timer = setInterval(tick, period);
+        }
+        return () => {
+            listeners.delete(listener);
+            if (listeners.size === 0 && timer !== undefined) {
+                clearInterval(timer);
+                timer = undefined;
+            }
+        };
+    }
+    return { subscribe, read: () => (listeners.size === 0 ? Date.now() : now) };
+}
+const minuteClock = tickingClock(minute);
+const secondClock = tickingClock(second);
+const unwatched = () => () => undefined;
+function useClockValue(clock, compute, on) {
+    return useSyncExternalStore(on ? clock.subscribe : unwatched, () => compute(clock.read()));
+}
+/** compute's answer from the minute clock; the component re-renders only when the answer changes, so compute returns a
+ * primitive (a label rather than the time). */
+export function useNowValue(compute) {
+    return useClockValue(minuteClock, compute, true);
+}
+/** useNowValue on a clock that ticks every second while `on`; compute should return a constant while off. */
+export function useSecondValue(compute, on) {
+    return useClockValue(secondClock, compute, on);
+}

package/dist/useStoredState.d.ts

@@ -0,0 +1,6 @@
+declare function read<T>(key: string, fallback: T, valid: (value: unknown) => value is T): T;
+declare function write(key: string, value: unknown): void;
+/** State that survives a restart in localStorage. A stored value that fails `valid` is ignored. */
+export declare function useStoredState<T>(key: string, fallback: T, valid: (value: unknown) => value is T): [T, (value: T) => void];
+export { read as readStored, write as writeStored };
+//# sourceMappingURL=useStoredState.d.ts.map

package/dist/useStoredState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStoredState.d.ts","sourceRoot":"","sources":["../src/useStoredState.ts"],"names":[],"mappings":"AAEA,iBAAS,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,GAAG,CAAC,CAWnF;AAWD,iBAAS,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,QAMzC;AAED,mGAAmG;AACnG,wBAAgB,cAAc,CAAC,CAAC,EAC9B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,CAAC,EACX,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,GACpC,CAAC,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC,CAczB;AAED,OAAO,EAAE,IAAI,IAAI,UAAU,EAAE,KAAK,IAAI,WAAW,EAAE,CAAA"}

package/dist/useStoredState.js

@@ -0,0 +1,48 @@
+import { useState } from 'react';
+function read(key, fallback, valid) {
+    try {
+        const raw = localStorage.getItem(key);
+        if (raw === null) {
+            return fallback;
+        }
+        const parsed = parseOrRaw(raw);
+        return valid(parsed) ? parsed : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+// Other code may have written a bare string, which is not JSON.
+function parseOrRaw(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+function write(key, value) {
+    try {
+        localStorage.setItem(key, JSON.stringify(value));
+    }
+    catch {
+        // Storage can be blocked or full; the choice then lasts until the app closes.
+    }
+}
+/** State that survives a restart in localStorage. A stored value that fails `valid` is ignored. */
+export function useStoredState(key, fallback, valid) {
+    const [stored, setStored] = useState(() => ({ key, value: read(key, fallback, valid) }));
+    let value = stored.value;
+    if (stored.key !== key) {
+        value = read(key, fallback, valid);
+        setStored({ key, value });
+    }
+    return [
+        value,
+        (next) => {
+            setStored({ key, value: next });
+            write(key, next);
+        },
+    ];
+}
+export { read as readStored, write as writeStored };

package/dist/useWidth.d.ts

@@ -0,0 +1,5 @@
+import { type RefObject } from 'react';
+/** The client width of the element the ref is put on, kept current as it resizes; 0 until measured. */
+declare function useWidth<T extends HTMLElement>(): [RefObject<T | null>, number];
+export { useWidth };
+//# sourceMappingURL=useWidth.d.ts.map

package/dist/useWidth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useWidth.d.ts","sourceRoot":"","sources":["../src/useWidth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAqC,MAAM,OAAO,CAAA;AAGzE,uGAAuG;AACvG,iBAAS,QAAQ,CAAC,CAAC,SAAS,WAAW,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,MAAM,CAAC,CAiBxE;AAED,OAAO,EAAE,QAAQ,EAAE,CAAA"}

package/dist/useWidth.js

@@ -0,0 +1,22 @@
+import { useLayoutEffect, useRef, useState } from 'react';
+import { flushSync } from 'react-dom';
+/** The client width of the element the ref is put on, kept current as it resizes; 0 until measured. */
+function useWidth() {
+    const ref = useRef(null);
+    const [width, setWidth] = useState(0);
+    // Measured before paint, so the first frame is laid out for the real width rather than 0.
+    useLayoutEffect(() => {
+        const el = ref.current;
+        if (!el) {
+            return;
+        }
+        // Rendered before the browser paints the resize: a default-priority update would paint one frame laid out for the
+        // old width, with whatever columns or scrollbar that width implies.
+        const ro = new ResizeObserver(() => flushSync(() => setWidth(el.clientWidth)));
+        ro.observe(el);
+        setWidth(el.clientWidth);
+        return () => ro.disconnect();
+    }, []);
+    return [ref, width];
+}
+export { useWidth };

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@rethunk/react-load-hooks",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "React hooks for async loads that never land out of order, plus the small state hooks an app builds screens from.",
+  "license": "MIT",
+  "author": "Rethunk.Tech, LLC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Rethunk-Tech/react-load-hooks.git"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "packageManager": "bun@1.4.4",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "lint": "biome check --error-on-warnings .",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "bun test",
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "pack:check": "bun scripts/check-pack.ts"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.4",
+    "@happy-dom/global-registrator": "^21.0.4",
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/react": "^16.3.3",
+    "@types/bun": "^1.4.4",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "typescript": "^7.0.2"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export { type LoadSink, loader } from './loader.ts'
+export { useDebouncedLoad } from './useDebouncedLoad.ts'
+export { useDebouncedValue } from './useDebouncedValue.ts'
+export { useLoaded } from './useLoaded.ts'
+export { useNowValue, useSecondValue } from './useNow.ts'
+export { readStored, useStoredState, writeStored } from './useStoredState.ts'
+export { useWidth } from './useWidth.ts'

package/src/loader.test.ts

@@ -0,0 +1,78 @@
+import { expect, test } from 'bun:test'
+import { loader } from './loader.ts'
+
+const flush = () => new Promise<void>((resolve) => setTimeout(resolve, 0))
+
+function harness(keepAcrossKeys: boolean) {
+  const log: string[] = []
+  const pending: (() => void)[] = []
+  const runs = loader<string>(
+    {
+      value: (v) => log.push(`value ${v}`),
+      error: (e) => log.push(`error ${String(e)}`),
+      loading: (on) => log.push(on ? 'loading' : 'idle'),
+      reset: () => log.push('reset'),
+    },
+    {
+      keepAcrossKeys,
+      // A deferred start waits in `pending` until the test runs it; cancelling empties its slot.
+      defer: (go) => {
+        const i = pending.push(go) - 1
+        return () => {
+          pending[i] = () => undefined
+        }
+      },
+    },
+  )
+  return { log, pending, runs }
+}
+
+// The branches useLoaded and useDebouncedLoad share: a superseded answer and error are dropped, new deps reset or keep
+// the value, a null load resets, a start cancelled by new deps never runs, and stop drops what is in flight.
+test('only the newest load lands', async () => {
+  for (const keep of [false, true]) {
+    const { log, pending, runs } = harness(keep)
+    const a = Promise.withResolvers<string>()
+    const b = Promise.withResolvers<string>()
+    runs.deps(['a'], () => a.promise)
+    runs.deps(['a'], () => b.promise)
+    expect(pending).toHaveLength(1)
+    pending[0]?.()
+    runs.deps(['b'], () => b.promise)
+    pending[1]?.()
+    b.resolve('b')
+    a.reject(new Error('a failed'))
+    await flush()
+    expect(log).toEqual([
+      'loading',
+      'loading',
+      ...(keep ? [] : ['reset']),
+      'loading',
+      'loading',
+      'value b',
+      'idle',
+    ])
+
+    log.length = 0
+    const c = Promise.withResolvers<string>()
+    const older = runs.run(() => c.promise)
+    const newest = runs.run(() => Promise.reject(new Error('newest')))
+    c.resolve('c')
+    await Promise.all([older, newest])
+    expect(log).toEqual(['loading', 'loading', 'error Error: newest', 'idle'])
+
+    log.length = 0
+    runs.deps(['c'], () => c.promise)
+    runs.deps(['d'], null)
+    pending.at(-1)?.()
+    await flush()
+    expect(log).toEqual([...(keep ? [] : ['reset']), 'loading', 'reset', 'idle'])
+
+    log.length = 0
+    await runs.run(null)
+    const late = runs.run(() => Promise.resolve('late'))
+    runs.stop()
+    await late
+    expect(log).toEqual(['reset', 'idle', 'loading'])
+  }
+})

package/src/loader.ts

@@ -0,0 +1,101 @@
+import type { DependencyList } from 'react'
+
+const sameDeps = (a: DependencyList | null, b: DependencyList) =>
+  a !== null && a.length === b.length && b.every((dep, i) => Object.is(dep, a[i]))
+
+export interface LoadSink<T> {
+  value: (value: T) => void
+  error: (error: unknown) => void
+  loading: (on: boolean) => void
+  /** Shows the hook's initial value again. */
+  reset: () => void
+}
+
+const now = (go: () => void) => {
+  go()
+  return () => undefined
+}
+
+/**
+ * useLoaded's and useDebouncedLoad's logic without React. Only the newest load lands: a later load, new deps or stop
+ * drops the answer, error and end of every one before it. New deps reset the value unless keepAcrossKeys, and a null
+ * load always does. `defer` starts a load, now or later, and returns what cancels the start.
+ */
+export function loader<T>(
+  sink: LoadSink<T>,
+  {
+    keepAcrossKeys = false,
+    defer = now,
+  }: { keepAcrossKeys?: boolean; defer?: (go: () => void) => () => void } = {},
+) {
+  let generation = 0
+  let seen: DependencyList | null = null
+  let cancel: () => void = () => undefined
+  const drop = () => {
+    generation += 1
+    cancel()
+  }
+  const start = (load: () => Promise<T>): Promise<void> => {
+    generation += 1
+    const mine = generation
+    const current = () => generation === mine
+    sink.loading(true)
+    return load()
+      .then(
+        (value) => {
+          if (current()) {
+            sink.value(value)
+          }
+        },
+        (error: unknown) => {
+          if (current()) {
+            sink.error(error)
+          }
+        },
+      )
+      .finally(() => {
+        if (current()) {
+          sink.loading(false)
+        }
+      })
+  }
+  const skip = () => {
+    drop()
+    sink.reset()
+    sink.loading(false)
+  }
+  return {
+    deps(deps: DependencyList, load: (() => Promise<T>) | null) {
+      if (sameDeps(seen, deps)) {
+        return
+      }
+      const fresh = seen !== null
+      seen = deps
+      if (load === null) {
+        skip()
+        return
+      }
+      drop()
+      if (fresh && !keepAcrossKeys) {
+        sink.reset()
+      }
+      sink.loading(true)
+      // start settles through the sink, so only a throwing sink handler reaches this catch.
+      cancel = defer(() => {
+        start(load).catch(sink.error)
+      })
+    },
+    /** Runs a load at once with the same deps, keeping the value shown until it answers; resolves when it has. */
+    run(load: (() => Promise<T>) | null): Promise<void> {
+      if (load === null) {
+        skip()
+        return Promise.resolve()
+      }
+      return start(load)
+    },
+    stop() {
+      drop()
+      seen = null
+    },
+  }
+}

package/src/useDebouncedLoad.test.ts

@@ -0,0 +1,26 @@
+import { afterAll, expect, test } from 'bun:test'
+
+const testing = await import('@testing-library/react')
+const { useDebouncedLoad } = await import('./useDebouncedLoad.ts')
+
+afterAll(() => {
+  testing.cleanup()
+})
+
+const sleep = (ms: number) => testing.act(async () => new Promise<void>((r) => setTimeout(r, ms)))
+
+test('a delayMs that changes between renders applies to the next scheduled load', async () => {
+  const view = testing.renderHook(
+    ({ key, delayMs }) =>
+      useDebouncedLoad(() => Promise.resolve(key), [key], { initial: '', delayMs }),
+    { initialProps: { key: 'a', delayMs: 1 } },
+  )
+  await sleep(20)
+  expect(view.result.current.data).toBe('a')
+
+  view.rerender({ key: 'b', delayMs: 150 })
+  await sleep(40)
+  expect(view.result.current.data).toBe('a')
+  await sleep(200)
+  expect(view.result.current.data).toBe('b')
+})

package/src/useDebouncedLoad.ts

@@ -0,0 +1,59 @@
+import { type DependencyList, useEffect, useRef, useState } from 'react'
+import { loader } from './loader.ts'
+
+/**
+ * useLoaded for input that changes on every key: `load` runs `delayMs` (read afresh each time a load is scheduled)
+ * after `deps` last changed, and `data` keeps the last answer meanwhile. Only the newest run lands, so `onError` hears
+ * only the newest failure. A null `load` resets `data` to `initial`. `run` starts another load at once, such as the
+ * next page, under the same rule.
+ */
+export function useDebouncedLoad<T>(
+  load: (() => Promise<T>) | null,
+  deps: DependencyList,
+  {
+    initial,
+    delayMs,
+    onError,
+  }: { initial: T; delayMs: number; onError?: (error: unknown) => void },
+) {
+  const [data, setData] = useState(initial)
+  const [loading, setLoading] = useState(load !== null)
+  const [error, setError] = useState<unknown>(null)
+  const latest = useRef({ initial, onError, delayMs })
+  latest.current = { initial, onError, delayMs }
+  const [runs] = useState(() =>
+    loader<T>(
+      {
+        value: (value) => {
+          setData(() => value)
+          setError(null)
+        },
+        error: (e) => {
+          setError(e)
+          latest.current.onError?.(e)
+        },
+        loading: setLoading,
+        reset: () => setData(() => latest.current.initial),
+      },
+      {
+        keepAcrossKeys: true,
+        defer: (go) => {
+          const timer = globalThis.setTimeout(go, latest.current.delayMs)
+          return () => globalThis.clearTimeout(timer)
+        },
+      },
+    ),
+  )
+  // Runs after every render and acts only when the caller's deps changed: an effect cannot take a caller-supplied
+  // dependency list.
+  useEffect(() => {
+    runs.deps(deps, load)
+  })
+  useEffect(() => () => runs.stop(), [runs])
+  return {
+    data,
+    loading,
+    error,
+    run: (next: () => Promise<T>) => runs.run(next),
+  }
+}

package/src/useDebouncedValue.ts

@@ -0,0 +1,11 @@
+import { useEffect, useState } from 'react'
+
+/** `value` once it has held still for `ms`; the first render returns it at once. */
+export function useDebouncedValue<T>(value: T, ms: number): T {
+  const [settled, setSettled] = useState(value)
+  useEffect(() => {
+    const timer = setTimeout(() => setSettled(value), ms)
+    return () => clearTimeout(timer)
+  }, [value, ms])
+  return settled
+}

package/src/useLoaded.test.tsx

@@ -0,0 +1,125 @@
+import { afterAll, expect, test } from 'bun:test'
+
+const testing = await import('@testing-library/react')
+const { useLoaded } = await import('./useLoaded.ts')
+
+afterAll(() => {
+  testing.cleanup()
+})
+
+// Flushes pending promises inside act, so the state update they make renders before the test reads it.
+const settle = () => testing.act(async () => new Promise<void>((resolve) => setTimeout(resolve, 0)))
+
+function deferred<T>() {
+  let resolve: (v: T) => void = () => undefined
+  let reject: (e: unknown) => void = () => undefined
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  return { promise, resolve, reject }
+}
+
+test('loads, then reloads with the same deps', async () => {
+  let n = 0
+  const next = () => {
+    n += 1
+    return Promise.resolve(n)
+  }
+  const { result } = testing.renderHook(() => useLoaded(next, [], 0))
+  expect(result.current.loading).toBe(true)
+  await settle()
+  expect(result.current.data).toBe(1)
+  expect(result.current.loading).toBe(false)
+  await testing.act(() => result.current.reload())
+  await settle()
+  expect(result.current.data).toBe(2)
+})
+
+test('a run superseded by new deps is dropped', async () => {
+  const first = deferred<string>()
+  const second = deferred<string>()
+  const { result, rerender } = testing.renderHook(
+    ({ key }) => useLoaded(() => (key === 'a' ? first.promise : second.promise), [key], ''),
+    { initialProps: { key: 'a' } },
+  )
+  rerender({ key: 'b' })
+  second.resolve('b')
+  await settle()
+  expect(result.current.data).toBe('b')
+  first.resolve('a')
+  await testing.act(() => first.promise)
+  expect(result.current.data).toBe('b')
+})
+
+test('an answer after unmount is ignored and errors reach onError once', async () => {
+  const late = deferred<string>()
+  const seen: unknown[] = []
+  const gone = testing.renderHook(() =>
+    useLoaded(
+      () => late.promise,
+      [],
+      '',
+      (e) => seen.push(e),
+    ),
+  )
+  gone.unmount()
+  late.reject(new Error('late'))
+  await late.promise.catch(() => undefined)
+  expect(seen).toEqual([])
+
+  const boom = new Error('boom')
+  const { result } = testing.renderHook(() =>
+    useLoaded(
+      () => Promise.reject(boom),
+      [],
+      'fallback',
+      (e) => seen.push(e),
+    ),
+  )
+  await settle()
+  expect(result.current.error).toBe(boom)
+  expect(result.current.data).toBe('fallback')
+  expect(result.current.loading).toBe(false)
+  expect(seen).toEqual([boom])
+})
+
+test('new deps clear the old answer until the new one arrives', async () => {
+  const second = deferred<string>()
+  const { result, rerender } = testing.renderHook(
+    ({ key }) => useLoaded(() => (key === 'a' ? Promise.resolve('a') : second.promise), [key], ''),
+    { initialProps: { key: 'a' } },
+  )
+  await settle()
+  expect(result.current.data).toBe('a')
+  rerender({ key: 'b' })
+  await settle()
+  expect(result.current.data).toBe('')
+  second.resolve('b')
+  await settle()
+  expect(result.current.data).toBe('b')
+})
+
+test('a null loader never runs', () => {
+  const { result } = testing.renderHook(() => useLoaded<number>(null, [], 7))
+  expect(result.current).toMatchObject({ data: 7, loading: false })
+})
+
+test('a failed reload keeps the last good data', async () => {
+  let fail: boolean
+  fail = false
+  const { result } = testing.renderHook(() =>
+    useLoaded(
+      () => (fail ? Promise.reject(new Error('offline')) : Promise.resolve('good')),
+      [],
+      '',
+    ),
+  )
+  await settle()
+  expect(result.current.data).toBe('good')
+  fail = true
+  await testing.act(() => result.current.reload())
+  await settle()
+  expect(result.current.data).toBe('good')
+  expect(result.current.error).toBeInstanceOf(Error)
+})

package/src/useLoaded.ts

@@ -0,0 +1,45 @@
+import { type DependencyList, useCallback, useEffect, useRef, useState } from 'react'
+import { loader } from './loader.ts'
+
+/**
+ * Runs `load` whenever `deps` change (never while `load` is null) and drops the answer of any run that has been
+ * superseded or unmounted. New deps and a null load reset `data` to `initial`; a failed load keeps the last good `data`
+ * and sets `error`. `reload` runs it again with the same deps and keeps the old value until the answer arrives;
+ * `setData` edits the loaded value in place.
+ */
+export function useLoaded<T>(
+  load: (() => Promise<T>) | null,
+  deps: DependencyList,
+  initial: T,
+  onError?: (error: unknown) => void,
+) {
+  const [data, setData] = useState(initial)
+  const [loading, setLoading] = useState(load !== null)
+  const [error, setError] = useState<unknown>(null)
+  const latest = useRef({ load, initial, onError })
+  latest.current = { load, initial, onError }
+  const [runs] = useState(() =>
+    loader<T>({
+      value: (value) => setData(() => value),
+      error: (e) => {
+        setError(e)
+        latest.current.onError?.(e)
+      },
+      loading: (on) => {
+        setLoading(on)
+        if (on) {
+          setError(null)
+        }
+      },
+      reset: () => setData(() => latest.current.initial),
+    }),
+  )
+  // Runs after every render and starts a load only when the caller's deps changed: an effect cannot take a
+  // caller-supplied dependency list.
+  useEffect(() => {
+    runs.deps(deps, load)
+  })
+  useEffect(() => () => runs.stop(), [runs])
+  const reload = useCallback(() => runs.run(latest.current.load), [runs])
+  return { data, setData, loading, error, reload }
+}

package/src/useNow.test.ts

@@ -0,0 +1,58 @@
+import { afterAll, afterEach, beforeEach, expect, jest, setSystemTime, test } from 'bun:test'
+
+const testing = await import('@testing-library/react')
+const { useNowValue, useSecondValue } = await import('./useNow.ts')
+
+beforeEach(() => {
+  jest.useFakeTimers()
+  setSystemTime(new Date('2026-01-01T00:00:00Z'))
+})
+afterEach(() => {
+  testing.cleanup()
+  jest.useRealTimers()
+  setSystemTime()
+})
+afterAll(() => {
+  testing.cleanup()
+})
+
+test('a watcher re-renders only when its answer changes, and the clock stops with the last one', () => {
+  let renders = 0
+  const view = testing.renderHook(() => {
+    renders += 1
+    return useSecondValue((now) => Math.floor(now / 10_000), true)
+  })
+  const first = view.result.current
+  const afterMount = renders
+
+  testing.act(() => {
+    setSystemTime(new Date('2026-01-01T00:00:03Z'))
+    jest.advanceTimersByTime(3000)
+  })
+  expect(view.result.current).toBe(first)
+  expect(renders).toBe(afterMount)
+
+  testing.act(() => {
+    setSystemTime(new Date('2026-01-01T00:00:10Z'))
+    jest.advanceTimersByTime(7000)
+  })
+  expect(view.result.current).toBe(first + 1)
+
+  view.unmount()
+  expect(jest.getTimerCount()).toBe(0)
+})
+
+test('the minute clock ticks once for every watcher and is idle when none is left', () => {
+  const a = testing.renderHook(() => useNowValue((now) => Math.floor(now / 60_000)))
+  const b = testing.renderHook(() => useNowValue((now) => Math.floor(now / 60_000)))
+  expect(jest.getTimerCount()).toBe(1)
+  a.unmount()
+  expect(jest.getTimerCount()).toBe(1)
+  b.unmount()
+  expect(jest.getTimerCount()).toBe(0)
+})
+
+test('a clock switched off never ticks', () => {
+  testing.renderHook(() => useSecondValue(() => 'off', false))
+  expect(jest.getTimerCount()).toBe(0)
+})

package/src/useNow.ts

@@ -0,0 +1,62 @@
+import { useSyncExternalStore } from 'react'
+
+const second = 1000
+const minute = 60_000
+
+// One shared timer per period, running only while some component watches it.
+function tickingClock(period: number) {
+  const listeners = new Set<() => void>()
+  let now = Date.now()
+  let timer: ReturnType<typeof setInterval> | undefined
+
+  function tick() {
+    now = Date.now()
+    for (const listener of listeners) {
+      listener()
+    }
+  }
+
+  function subscribe(listener: () => void) {
+    listeners.add(listener)
+    if (listeners.size === 1) {
+      // The clock stood still while nobody watched it.
+      now = Date.now()
+      timer = setInterval(tick, period)
+    }
+    return () => {
+      listeners.delete(listener)
+      if (listeners.size === 0 && timer !== undefined) {
+        clearInterval(timer)
+        timer = undefined
+      }
+    }
+  }
+
+  return { subscribe, read: () => (listeners.size === 0 ? Date.now() : now) }
+}
+
+const minuteClock = tickingClock(minute)
+const secondClock = tickingClock(second)
+const unwatched = () => () => undefined
+
+function useClockValue<T extends string | number | boolean>(
+  clock: ReturnType<typeof tickingClock>,
+  compute: (now: number) => T,
+  on: boolean,
+): T {
+  return useSyncExternalStore(on ? clock.subscribe : unwatched, () => compute(clock.read()))
+}
+
+/** compute's answer from the minute clock; the component re-renders only when the answer changes, so compute returns a
+ * primitive (a label rather than the time). */
+export function useNowValue<T extends string | number | boolean>(compute: (now: number) => T): T {
+  return useClockValue(minuteClock, compute, true)
+}
+
+/** useNowValue on a clock that ticks every second while `on`; compute should return a constant while off. */
+export function useSecondValue<T extends string | number | boolean>(
+  compute: (now: number) => T,
+  on: boolean,
+): T {
+  return useClockValue(secondClock, compute, on)
+}

package/src/useStoredState.test.ts

@@ -0,0 +1,43 @@
+import { afterAll, expect, test } from 'bun:test'
+
+const testing = await import('@testing-library/react')
+const { readStored, useStoredState, writeStored } = await import('./useStoredState.ts')
+
+afterAll(() => {
+  testing.cleanup()
+})
+
+const isText = (v: unknown): v is string => typeof v === 'string'
+
+test('a stored string reads back whether it was written as JSON or bare', () => {
+  localStorage.setItem('stored-test.json', JSON.stringify('run-1'))
+  localStorage.setItem('stored-test.bare', 'run-2')
+  expect(readStored('stored-test.json', '', isText)).toBe('run-1')
+  expect(readStored('stored-test.bare', '', isText)).toBe('run-2')
+  expect(readStored('stored-test.missing', 'none', isText)).toBe('none')
+  localStorage.removeItem('stored-test.json')
+  localStorage.removeItem('stored-test.bare')
+})
+
+test('the value follows the key when the key changes', () => {
+  localStorage.setItem('stored-test.a', JSON.stringify('one'))
+  localStorage.setItem('stored-test.b', JSON.stringify('two'))
+  const view = testing.renderHook(({ key }) => useStoredState(key, '', isText), {
+    initialProps: { key: 'stored-test.a' },
+  })
+  expect(view.result.current[0]).toBe('one')
+  view.rerender({ key: 'stored-test.b' })
+  expect(view.result.current[0]).toBe('two')
+  testing.act(() => view.result.current[1]('three'))
+  expect(localStorage.getItem('stored-test.b')).toBe('"three"')
+  expect(localStorage.getItem('stored-test.a')).toBe('"one"')
+  localStorage.removeItem('stored-test.a')
+  localStorage.removeItem('stored-test.b')
+})
+
+test('the caller key reaches localStorage verbatim, with no prefix', () => {
+  writeStored('stored-test.verbatim', { a: 1 })
+  expect(localStorage.getItem('stored-test.verbatim')).toBe(JSON.stringify({ a: 1 }))
+  expect(localStorage.length).toBe(1)
+  localStorage.removeItem('stored-test.verbatim')
+})

package/src/useStoredState.ts

@@ -0,0 +1,54 @@
+import { useState } from 'react'
+
+function read<T>(key: string, fallback: T, valid: (value: unknown) => value is T): T {
+  try {
+    const raw = localStorage.getItem(key)
+    if (raw === null) {
+      return fallback
+    }
+    const parsed = parseOrRaw(raw)
+    return valid(parsed) ? parsed : fallback
+  } catch {
+    return fallback
+  }
+}
+
+// Other code may have written a bare string, which is not JSON.
+function parseOrRaw(raw: string): unknown {
+  try {
+    return JSON.parse(raw)
+  } catch {
+    return raw
+  }
+}
+
+function write(key: string, value: unknown) {
+  try {
+    localStorage.setItem(key, JSON.stringify(value))
+  } catch {
+    // Storage can be blocked or full; the choice then lasts until the app closes.
+  }
+}
+
+/** State that survives a restart in localStorage. A stored value that fails `valid` is ignored. */
+export function useStoredState<T>(
+  key: string,
+  fallback: T,
+  valid: (value: unknown) => value is T,
+): [T, (value: T) => void] {
+  const [stored, setStored] = useState(() => ({ key, value: read(key, fallback, valid) }))
+  let value = stored.value
+  if (stored.key !== key) {
+    value = read(key, fallback, valid)
+    setStored({ key, value })
+  }
+  return [
+    value,
+    (next) => {
+      setStored({ key, value: next })
+      write(key, next)
+    },
+  ]
+}
+
+export { read as readStored, write as writeStored }

package/src/useWidth.ts

@@ -0,0 +1,24 @@
+import { type RefObject, useLayoutEffect, useRef, useState } from 'react'
+import { flushSync } from 'react-dom'
+
+/** The client width of the element the ref is put on, kept current as it resizes; 0 until measured. */
+function useWidth<T extends HTMLElement>(): [RefObject<T | null>, number] {
+  const ref = useRef<T | null>(null)
+  const [width, setWidth] = useState(0)
+  // Measured before paint, so the first frame is laid out for the real width rather than 0.
+  useLayoutEffect(() => {
+    const el = ref.current
+    if (!el) {
+      return
+    }
+    // Rendered before the browser paints the resize: a default-priority update would paint one frame laid out for the
+    // old width, with whatever columns or scrollbar that width implies.
+    const ro = new ResizeObserver(() => flushSync(() => setWidth(el.clientWidth)))
+    ro.observe(el)
+    setWidth(el.clientWidth)
+    return () => ro.disconnect()
+  }, [])
+  return [ref, width]
+}
+
+export { useWidth }