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

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/coalescer.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Runs one slow task per key at a time: an ask made while one runs waits for it and then runs once more, however many
+ * ask meanwhile, so a result is never older than its ask but identical slow calls do not pile up.
+ */
+export declare function coalescer(): (key: string, run: () => Promise<void>) => Promise<void>;
+//# sourceMappingURL=coalescer.d.ts.map

package/dist/coalescer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coalescer.d.ts","sourceRoot":"","sources":["../src/coalescer.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,wBAAgB,SAAS,UAaV,MAAM,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,KAAG,OAAO,CAAC,IAAI,CAAC,CAQ9D"}

package/dist/coalescer.js

@@ -0,0 +1,27 @@
+const ignore = () => undefined;
+/**
+ * Runs one slow task per key at a time: an ask made while one runs waits for it and then runs once more, however many
+ * ask meanwhile, so a result is never older than its ask but identical slow calls do not pile up.
+ */
+export function coalescer() {
+    const running = new Map();
+    const start = (key, run) => {
+        const p = run();
+        const slot = { settled: Promise.resolve(), next: null };
+        slot.settled = p.then(ignore, ignore).then(() => {
+            if (running.get(key) === slot) {
+                running.delete(key);
+            }
+        });
+        running.set(key, slot);
+        return p;
+    };
+    return (key, run) => {
+        const slot = running.get(key);
+        if (!slot) {
+            return start(key, run);
+        }
+        slot.next ??= slot.settled.then(() => start(key, run));
+        return slot.next;
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { coalescer } from './coalescer.ts';
+export { type LoadSink, loader } from './loader.ts';
+export { useDebouncedLoad } from './useDebouncedLoad.ts';
+export { useDebouncedValue } from './useDebouncedValue.ts';
+export { type LoadedOptions, 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,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,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,KAAK,aAAa,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC9D,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,8 @@
+export { coalescer } from './coalescer.js';
+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,21 @@
+import { type DependencyList } from 'react';
+export interface LoadedOptions {
+    onError?: (error: unknown) => void;
+    /** Keep `data` across new deps until the new answer lands. */
+    keepAcrossKeys?: boolean;
+}
+/**
+ * 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. The fourth argument is `onError` or `{ onError, keepAcrossKeys }`. With `keepAcrossKeys`, new deps keep `data` until the new answer lands
+ * (a null load still resets it).
+ */
+export declare function useLoaded<T>(load: (() => Promise<T>) | null, deps: DependencyList, initial: T, options?: ((error: unknown) => void) | LoadedOptions): {
+    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,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IAClC,8DAA8D;IAC9D,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED;;;;;;GAMG;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,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,aAAa;;;;;;EAoCrD"}

package/dist/useLoaded.js

@@ -0,0 +1,39 @@
+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. The fourth argument is `onError` or `{ onError, keepAcrossKeys }`. With `keepAcrossKeys`, new deps keep `data` until the new answer lands
+ * (a null load still resets it).
+ */
+export function useLoaded(load, deps, initial, options) {
+    const { onError, keepAcrossKeys = false } = typeof options === 'function' ? { onError: options } : (options ?? {});
+    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),
+    }, { keepAcrossKeys }));
+    // 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.1",
+  "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/coalescer.ts

@@ -0,0 +1,34 @@
+interface Slot {
+  settled: Promise<void>
+  // The follow-up run asked for while this one runs, shared by every later asker.
+  next: Promise<void> | null
+}
+
+const ignore = () => undefined
+
+/**
+ * Runs one slow task per key at a time: an ask made while one runs waits for it and then runs once more, however many
+ * ask meanwhile, so a result is never older than its ask but identical slow calls do not pile up.
+ */
+export function coalescer() {
+  const running = new Map<string, Slot>()
+  const start = (key: string, run: () => Promise<void>): Promise<void> => {
+    const p = run()
+    const slot: Slot = { settled: Promise.resolve(), next: null }
+    slot.settled = p.then(ignore, ignore).then(() => {
+      if (running.get(key) === slot) {
+        running.delete(key)
+      }
+    })
+    running.set(key, slot)
+    return p
+  }
+  return (key: string, run: () => Promise<void>): Promise<void> => {
+    const slot = running.get(key)
+    if (!slot) {
+      return start(key, run)
+    }
+    slot.next ??= slot.settled.then(() => start(key, run))
+    return slot.next
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export { coalescer } from './coalescer.ts'
+export { type LoadSink, loader } from './loader.ts'
+export { useDebouncedLoad } from './useDebouncedLoad.ts'
+export { useDebouncedValue } from './useDebouncedValue.ts'
+export { type LoadedOptions, 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.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.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.ts

@@ -0,0 +1,57 @@
+import { type DependencyList, useCallback, useEffect, useRef, useState } from 'react'
+import { loader } from './loader.ts'
+
+export interface LoadedOptions {
+  onError?: (error: unknown) => void
+  /** Keep `data` across new deps until the new answer lands. */
+  keepAcrossKeys?: boolean
+}
+
+/**
+ * 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. The fourth argument is `onError` or `{ onError, keepAcrossKeys }`. With `keepAcrossKeys`, new deps keep `data` until the new answer lands
+ * (a null load still resets it).
+ */
+export function useLoaded<T>(
+  load: (() => Promise<T>) | null,
+  deps: DependencyList,
+  initial: T,
+  options?: ((error: unknown) => void) | LoadedOptions,
+) {
+  const { onError, keepAcrossKeys = false } =
+    typeof options === 'function' ? { onError: options } : (options ?? {})
+  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),
+      },
+      { keepAcrossKeys },
+    ),
+  )
+  // 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.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.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 }