@reactra/resource 0.1.0-alpha.0

package/dist/index.js

@@ -0,0 +1,956 @@
+// @reactra/resource — useResource hook + ResourceCache + ErrorBoundary
+//
+// Owner: reactra-resource-spec.md (Spec 1.0 / Discussion v4 — v1 promotion)
+//
+// Surface — see Resource v1:
+//   useResource<Deps, T>(deps, fn, opts?): ResourceHandle<T>    (§2)
+//   useMutation(fn, opts?)                                       (§7 — Stage D)
+//   ResourceCache (singleton + interface), createLRUCache         (§6 — Stage A1)
+//   configureResources({ cache?, cacheMaxEntries? })              (§9 — Stage A1)
+//   ResourceOptions, ResourceHandle<T>
+//   ErrorBoundary — class component that compiled `await(r) error(e) { }`
+//     blocks wrap around `<Suspense>` per Resource v1 §4 emission contract.
+//
+// Stages landed in this file: A1 — ResourceCache singleton + cache-hit branch
+// (settled) + configureResources + RES010/011. A2 — in-flight dedup: useResource
+// writes an in-flight tombstone (`value === undefined && error === undefined`)
+// to the cache before firing `fn`; concurrent mounts on the same
+// `(resourceName, depsKey)` adopt the shared promise + controller instead of
+// firing their own; on rejection the tombstone is `cache.delete`d (matching
+// A1's "do not cache rejections" rule). B — stale-while-revalidate: on a
+// settled cache hit past `cache.ttlMs`, return the stale value this render
+// (zero flicker, no suspense) AND fire a background refetch that writes an
+// SWR tombstone (stale value + in-flight promise + fresh writtenAt) so
+// concurrent mounts get a non-suspending hit and don't fire another refresh;
+// on refresh failure the entry is rewritten with `writtenAt: now` to back off
+// for `ttlMs`. SWR is opt-in via `cache: { ttlMs, staleWhileRevalidate: true }`.
+// C — retry + backoff + jitter (RES012): `opts.retry: N | { count, baseMs?,
+// jitter? }` wraps `fn` in `__fireWithRetry` (exponential backoff
+// `baseMs * 2^attempt` with optional ±20% jitter). AbortError never retries;
+// on exhaustion RES012 logs and the last error surfaces to setState +
+// cache.delete tombstone (A2 path) unchanged. SWR refresh inherits retries.
+// D — `useMutation(fn, opts?)` for non-idempotent side effects + cross-mount
+// `cache.invalidate` notification: useResource now subscribes to its cache key
+// via `useSyncExternalStore` (StrictMode-safe sub/unsub for free); re-renders
+// driven by `setNotifyTick` inside the subscribe callback. `ResourceEntry`
+// gains `cacheCoupled` (set true on adoption + after a successful write-back);
+// render-body `cacheBust = cacheCoupled && cached === undefined` triggers
+// re-fire on cross-mount invalidate. `useMutation` exposes
+// `mutate`/`reset`/`data`/`error`/`isPending` + RES013 (overlap without
+// `concurrent: true`) + RES014 (invalidate name unknown to cache).
+// E — `warmResource(name, deps, fn, signal)` exported helper that
+// `StoreRegistry.warm`-emitted companions call per-resource to pre-fill the
+// cache ahead of navigation. Best-effort: silent on failure (RES015 not
+// minted). Writes an in-flight tombstone for dedup + propagates caller signal
+// to fn via a two-layer AbortController. In-flight adoption in useResource
+// now swallows AbortError so a cancelled warm doesn't flash error UI.
+// Streaming/SSR (F → v2/Phase 4) pending.
+import React, { useCallback, useRef, useState, useSyncExternalStore } from "react";
+import { createLRUCache } from "./cache.js";
+export { createLRUCache } from "./cache.js";
+/**
+ * True outside a CONFIRMED production build — gates dev-only diagnostics.
+ *
+ * Reference the `process.env.NODE_ENV` LITERAL (not `globalThis.process`):
+ * bundlers (Vite/webpack) statically replace it at build time, and a browser
+ * bundle has no runtime `process`. The prior `globalThis.process` form returned
+ * `true` whenever `process` was absent — i.e. in BOTH browser dev and browser
+ * prod — so RES012 still logged in a production browser build (the very thing the
+ * gate was added to stop). The try/catch covers a bundler that leaves the literal
+ * un-replaced (no `process` global): treat unknown as dev so the diagnostic isn't
+ * silently swallowed. Node/bun read it at runtime.
+ */
+const __isDevEnv = () => {
+    try {
+        return process.env.NODE_ENV !== "production";
+    }
+    catch {
+        return true;
+    }
+};
+// ---------------------------------------------------------------------------
+// ResourceCache singleton + configureResources (Resource v1 §6/§9, Stage A1)
+// ---------------------------------------------------------------------------
+let __currentCache = createLRUCache(50);
+let __firstMountFired = false;
+/** Internal accessor — the active singleton. Not part of the public API. */
+export const __getResourceCache = () => __currentCache;
+/** Test-only: reset the singleton + first-mount guard between test cases. */
+export const __resetResourceConfigForTest = () => {
+    __currentCache = createLRUCache(50);
+    __firstMountFired = false;
+};
+/**
+ * Configure the resource layer at app boot (Resource v1 §9). Pass a custom
+ * `cache` implementation (must satisfy `ResourceCache`) or just override the
+ * built-in LRU's max-entries with `cacheMaxEntries`. **Must run before the
+ * first `useResource` mount** — calling it after throws RES010 (the cache
+ * implementation is already in use; the swap is rejected).
+ *
+ * Calling it more than once before the first mount overwrites silently (last
+ * call wins — typically only configures once at app boot). Calling it never
+ * is fine — the built-in LRU runs with `maxEntries: 50` and no TTL.
+ */
+export const configureResources = (opts = {}) => {
+    if (__firstMountFired) {
+        throw new Error(`[reactra:resource] RES010: configureResources called after the first useResource mount. ` +
+            `The cache implementation is already in use; the swap is rejected. ` +
+            `Call configureResources at app boot, before configureRouter and the first render. ` +
+            `(Resource v1 §9.)`);
+    }
+    if (opts.cache !== undefined) {
+        __currentCache = opts.cache;
+    }
+    else if (opts.cacheMaxEntries !== undefined) {
+        __currentCache = createLRUCache(opts.cacheMaxEntries);
+    }
+};
+// The policy helpers below read only T/S-independent fields (resourceName/cache/
+// retry), never `select`. `ResourceOptions<any, any>` lets any instantiation pass:
+// a bare `ResourceOptions<unknown, unknown>` would reject `ResourceOptions<T, S>`
+// because `select: (data: T) => S` is CONTRAVARIANT in T (a fn taking T is not a fn
+// taking unknown). `any` here is justified — these helpers never touch `select`.
+/** Cache is enabled for this call iff a resourceName is present AND `opts.cache` is truthy. */
+const cacheEnabled = (opts) => opts.resourceName !== undefined &&
+    (opts.cache === true || (typeof opts.cache === "object" && opts.cache !== null));
+/** Extract `opts.cache` as an object form, or null if `true`/`false`/absent. */
+const cacheOptsObject = (opts) => typeof opts.cache === "object" && opts.cache !== null ? opts.cache : null;
+/**
+ * Stage B — TTL-based staleness check. Returns `true` iff `cache.ttlMs` is
+ * set AND `Date.now() - entry.writtenAt` exceeds it. No TTL = never stale
+ * (entries live until eviction). Exported under `__` so the test suite can
+ * exercise the predicate without standing up a render.
+ */
+export const __isCacheEntryStale = (entry, opts, now = Date.now()) => {
+    const co = cacheOptsObject(opts);
+    if (co?.ttlMs === undefined)
+        return false;
+    return now - entry.writtenAt > co.ttlMs;
+};
+/**
+ * Stage B — staleWhileRevalidate opt-in check. Returns `true` iff
+ * `opts.cache` is an object form AND `staleWhileRevalidate: true`. Bare
+ * `cache: true` is treated as "cache but no SWR" — explicit opt-in required.
+ */
+export const __shouldRevalidate = (opts) => cacheOptsObject(opts)?.staleWhileRevalidate === true;
+const RETRY_BASE_MS_DEFAULT = 250;
+const RETRY_JITTER_DEFAULT = true;
+/**
+ * Stage C — normalize `opts.retry` to a `__RetryConfig` or `null`. `retry: N`
+ * (number) becomes `{ count: N, baseMs: 250, jitter: true }`. `retry: { count }`
+ * fills in the same defaults for unset fields. `retry: 0` or absent returns
+ * null (consumer fires `fn` once with zero retry overhead).
+ */
+export const __normalizeRetry = (opts) => {
+    const r = opts.retry;
+    if (r === undefined)
+        return null;
+    if (typeof r === "number") {
+        if (r <= 0)
+            return null;
+        return { count: r, baseMs: RETRY_BASE_MS_DEFAULT, jitter: RETRY_JITTER_DEFAULT };
+    }
+    if (r.count <= 0)
+        return null;
+    return {
+        count: r.count,
+        baseMs: r.baseMs ?? RETRY_BASE_MS_DEFAULT,
+        jitter: r.jitter ?? RETRY_JITTER_DEFAULT,
+    };
+};
+/**
+ * Stage C — exponential backoff with optional ±20% jitter. Delay for attempt
+ * `n` (0-indexed) is `baseMs * 2^n`, optionally multiplied by a uniform
+ * `[0.8, 1.2)` jitter factor. `random` is injectable so tests can pin both
+ * extremes (`() => 0` → 0.8x; `() => 1` → 1.2x).
+ */
+export const __computeRetryDelay = (attempt, config, random = Math.random) => {
+    const expMs = config.baseMs * 2 ** attempt;
+    if (!config.jitter)
+        return expMs;
+    // [0.8, 1.2): symmetric ±20% around the exponential delay.
+    return expMs * (0.8 + random() * 0.4);
+};
+/**
+ * Stage C — abortable `setTimeout` as a Promise. Resolves after `ms`; rejects
+ * with a DOMException("Aborted", "AbortError") if `signal` aborts before the
+ * timer fires (the timer is cleared). If the signal is already aborted at
+ * call time, rejects synchronously on the next microtask.
+ */
+export const __delay = (ms, signal) => new Promise((resolve, reject) => {
+    if (signal.aborted) {
+        reject(new DOMException("Aborted", "AbortError"));
+        return;
+    }
+    const t = setTimeout(() => {
+        signal.removeEventListener("abort", onAbort);
+        resolve();
+    }, ms);
+    const onAbort = () => {
+        clearTimeout(t);
+        reject(new DOMException("Aborted", "AbortError"));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+});
+/**
+ * Stage C — fire `fn(deps, { signal })` up to `config.count + 1` times (one
+ * initial + `count` retries), with exponential backoff + jitter between
+ * attempts. On `AbortError` from `fn` OR signal abort during the backoff
+ * delay, the loop short-circuits and the abort propagates. On exhaustion,
+ * logs RES012 (dev-gated — prod stays silent since the error already surfaces
+ * via `r.error` + ErrorBoundary + the rejected promise) and re-throws the last
+ * error UNCONDITIONALLY. The hook's existing `.then` chain handles
+ * `setState({ error })` + cache.delete tombstone removal unchanged.
+ */
+export const __fireWithRetry = async (deps, signal, config, fn, random = Math.random) => {
+    let lastErr;
+    // `attempt` 0 is the initial call; 1..count are the retries.
+    for (let attempt = 0; attempt <= config.count; attempt++) {
+        if (signal.aborted) {
+            throw new DOMException("Aborted", "AbortError");
+        }
+        try {
+            return await fn(deps, { signal });
+        }
+        catch (err) {
+            lastErr = err;
+            // Aborts never retry — propagate immediately. This covers both the
+            // consumer-driven abort (deps change, refetch) and any in-fn explicit
+            // cancellation.
+            if (err instanceof DOMException && err.name === "AbortError")
+                throw err;
+            if (attempt >= config.count)
+                break;
+            // RES012-precursor — silent per-attempt retry. The surfaced log lives
+            // at exhaustion (below) so a transient flake doesn't spam the console.
+            const delayMs = __computeRetryDelay(attempt, config, random);
+            await __delay(delayMs, signal);
+        }
+    }
+    // Exhausted. Log RES012 once (dev-gated — the error already surfaces via
+    // `r.error` + ErrorBoundary + the rejected promise, so prod console stays
+    // silent) and re-throw the last error so the existing `.then` chain surfaces
+    // it to setState + cache.delete the in-flight tombstone (A2's on-rejection
+    // path). The throw is UNCONDITIONAL — only the log is gated.
+    if (__isDevEnv()) {
+        console.error(`[reactra:resource] RES012: retry exhausted after ${config.count + 1} attempts — last error follows`, lastErr);
+    }
+    throw lastErr;
+};
+// Stable reference id for object-typed deps. Per Resource v0 §3 deps
+// equality is `Object.is`, so two fresh object literals are different
+// references and must trigger a refetch. We assign each object a unique
+// id via a WeakMap so depsKey changes whenever the reference changes.
+let __refCounter = 0;
+const __refIds = new WeakMap();
+const refId = (obj) => {
+    let id = __refIds.get(obj);
+    if (id === undefined) {
+        id = `ref:${++__refCounter}`;
+        __refIds.set(obj, id);
+    }
+    return id;
+};
+const scalarKey = (x) => {
+    if (x === null)
+        return "null";
+    if (x === undefined)
+        return "undef";
+    if (typeof x === "object")
+        return refId(x);
+    if (typeof x === "function")
+        return refId(x);
+    return `${typeof x}:${String(x)}`;
+};
+/**
+ * Stable string key for a `deps` value. Arrays are unwrapped element-wise so
+ * `[1, 2]` keys identically to another `[1, 2]`; scalar refs are compared by
+ * `Object.is`-equivalent identity. Exported for tests.
+ */
+export const depsToKey = (deps) => {
+    if (Array.isArray(deps))
+        return `[${deps.map(scalarKey).join(",")}]`;
+    return scalarKey(deps);
+};
+// Per-call record cached in a ref. Survives StrictMode's fake-unmount
+// because refs live outside React's render-output reconciliation — the
+// same depsKey on the fake-remount finds this entry intact and reuses
+// its (unaborted) promise. See the comment block on `useResource` for
+// the full rationale.
+// Stage D — `useSyncExternalStore` snapshot stays a constant so the
+// subscription-driven re-renders go through the explicit `setNotifyTick`
+// call inside the subscribe callback (single source of truth). Hoisted to
+// module scope so the reference is identity-stable across renders —
+// uSES treats a changing snapshot fn closure as a change signal.
+const USES_NOOP_SNAPSHOT = () => null;
+/**
+ * The Reactra resource hook. Compiler-emitted from `resource r(deps) => fn(deps)`.
+ *
+ * Behaviour per Resource v0 §2 + §3:
+ *   - `deps === null`  → skip the call. `data/error: undefined`, `isPending: false`,
+ *                        `promise: Promise.resolve(undefined)`.
+ *   - `deps === undefined` → same as `null` but emits a RES004 warning. The
+ *                        explicit skip sentinel is `null`.
+ *   - Otherwise `fn(deps, { signal })` runs immediately. `data` updates on
+ *     resolution; `error` updates on rejection (preserving last good `data`).
+ *   - Deps change (shallow `Object.is`) aborts the in-flight call and re-fires.
+ *   - `refetch()` aborts the current call and re-fires with the same deps.
+ *   - Late resolutions are dropped via a generation counter.
+ *
+ * The returned `promise` is always non-null and is fed to `React.use()` inside
+ * compiled `await(r) { }` blocks so React 19's Suspense can drive the boundary.
+ *
+ * ## StrictMode-safety (the reason this hook is ref-cached, not useMemo'd)
+ *
+ * Earlier drafts used `useMemo` for the promise and a `useEffect(() => () =>
+ * abort())` cleanup. That breaks under React.StrictMode in dev. StrictMode
+ * double-invokes render → mount → cleanup → mount on first mount to surface
+ * impurity. The first mount's `useEffect` cleanup aborts the controller while
+ * the SAME promise object is still referenced by the rendered tree; on the
+ * fake-remount, `React.use(promise)` sees a rejected (AbortError) promise and
+ * the surrounding ErrorBoundary fires for what should be a normal load.
+ * Removing the cleanup-side abort alone doesn't fix it — the top-of-useMemo
+ * abort + StrictMode's deliberate memo-discard still leave a rejected promise
+ * visible to React.use either way (useMemo is a cache *hint*, not a guarantee).
+ *
+ * The fix: cache the entry in a `useRef`. Refs are mutable cells that survive
+ * StrictMode's fake-unmount unchanged because they live outside React's
+ * render-output reconciliation. On the fake-remount, the same `depsKey` finds
+ * the existing entry and reuses its unaborted promise. Abort happens ONLY at
+ * the top of the cache-miss branch (genuine deps change or first call), never
+ * from an effect cleanup. Late resolutions are still dropped by the
+ * `genRef === myGen` guard inside the .then handlers, which covers the cases
+ * the cleanup-abort used to: deps-change, refetch, and the rarer "still
+ * in-flight at real unmount" case (setState on an unmounted component is a
+ * silent no-op in React 18+; no error, no warning, just a dropped state
+ * update). The minor cost is that a fetch in flight at real unmount keeps
+ * running until the network call completes — but its resolution is dropped,
+ * so no setState-on-unmounted and no observable bug. Worth it for StrictMode.
+ *
+ * Mutating refs during render is the standard React 19 pattern for cache-like
+ * state; React docs explicitly bless it when (a) the operation is idempotent
+ * for a given input (same depsKey → same entry) and (b) the mutation doesn't
+ * affect the rendered output during *this* render. Both hold here.
+ */
+export const useResource = (deps, fn, opts = {}) => {
+    // First-mount latch (Resource v1 §9): configureResources called after this
+    // throws RES010 — the cache impl is in use and the swap is rejected.
+    __firstMountFired = true;
+    // Bumped by refetch() to force a cache-miss even when deps didn't change.
+    // Kept separate from genRef so React can observe it via state.
+    const [refetchTick, setRefetchTick] = useState(0);
+    // The resolved snapshot. `resolvedKey` is the depsKey of whichever promise
+    // resolved into this state — used to derive isPending below.
+    // State holds the SELECTED value `S` (= raw `T` when no `select`). Storing the
+    // slice — not the raw data — is what enables the re-render bail-out: an
+    // unselected-field change recomputes the same slice, the guarded setState
+    // returns the same state, and React skips the re-render.
+    const [state, setState] = useState({ data: undefined, error: undefined, resolvedKey: null });
+    // Project raw → selected. Identity when no `select` (so no-select resources keep
+    // today's exact behaviour byte-for-byte).
+    const applySel = (raw) => raw === undefined ? undefined : opts.select ? opts.select(raw) : raw;
+    // Commit a successful raw value as the selected slice. WITH `select`, guard on
+    // `Object.is` so an unchanged slice bails the re-render (the feature). WITHOUT
+    // `select`, keep today's always-allocate write (no behaviour change).
+    const commitData = (raw) => {
+        if (opts.select) {
+            const sel = applySel(raw);
+            setState((s) => s.resolvedKey === depsKey && Object.is(s.data, sel) && s.error === undefined
+                ? s
+                : { data: sel, error: undefined, resolvedKey: depsKey });
+        }
+        else {
+            setState({ data: raw, error: undefined, resolvedKey: depsKey });
+        }
+    };
+    // Ref-cached entry. Survives StrictMode fake-unmount unchanged.
+    const entryRef = useRef(null);
+    // Monotonic generation. Bumped only on a new factory invocation (NOT on
+    // unmount cleanup — there is no cleanup). Used by the .then handlers to
+    // drop late resolutions from aborted calls so they don't overwrite state
+    // from the current call.
+    const genRef = useRef(0);
+    const depsKey = `${depsToKey(deps)}:${refetchTick}`;
+    // ResourceCache key (Resource v1 §6): purely deps-derived, sans refetchTick —
+    // entries cross refetch boundaries (refetch invalidates the cache entry, see
+    // refetch callback). Distinct from the local `depsKey` which DOES include the
+    // tick so the local entryRef misses on refetch.
+    const cacheKey = depsToKey(deps);
+    const useCache = cacheEnabled(opts) && deps !== null && deps !== undefined;
+    // Stage D — subscribe to cache notifications for our key so a cross-mount
+    // `useMutation.invalidate(name)` or external `cache.delete/clear` triggers
+    // a re-render here. We use `useSyncExternalStore` purely for StrictMode-
+    // safe subscribe/unsubscribe lifecycle (uSES guarantees a single live
+    // subscription per mount across StrictMode's fake-unmount/remount, which
+    // we cannot get from a render-body subscribe without a `useEffect`). Its
+    // returned snapshot is intentionally a constant (`null`) — re-renders are
+    // driven by `notifyTick` inside the subscribe callback, NOT by uSES's
+    // snapshot diffing, so we don't get spurious renders from uSES itself.
+    const [, setNotifyTick] = useState(0);
+    const subscribeResource = useCache ? opts.resourceName : undefined;
+    const subscribeKey = useCache ? cacheKey : "";
+    const subscribeFn = useCallback((uSESChange) => {
+        if (subscribeResource === undefined)
+            return () => { };
+        return __currentCache.subscribe(subscribeResource, subscribeKey, () => {
+            // Drive an actual re-render — uSES's snapshot is a no-op constant.
+            setNotifyTick((t) => t + 1);
+            uSESChange();
+        });
+    }, [subscribeResource, subscribeKey]);
+    useSyncExternalStore(subscribeFn, USES_NOOP_SNAPSHOT, USES_NOOP_SNAPSHOT);
+    // `renderCached` holds a cache-hit entry for THIS render so the returned
+    // handle can read from it synchronously (zero Suspense flash, no flicker
+    // through `data: undefined` on first render).
+    let renderCached;
+    // Pre-read the cache once so both the cache-miss branch and the Stage D
+    // cacheBust check see the same snapshot.
+    const rawCached = useCache && opts.resourceName !== undefined
+        ? __currentCache.get(opts.resourceName, cacheKey)
+        : undefined;
+    // Hard-expiry (`cache(ttl: D)` — a ttl WITHOUT `staleWhileRevalidate`): an entry
+    // past its `ttlMs` is treated as a MISS so the next read refetches instead of
+    // serving stale forever. `swr` is the opposite (serve stale + revalidate), so it
+    // is excluded here and keeps its settled hit. No ttl, or swr → unchanged.
+    const cached = rawCached !== undefined &&
+        cacheOptsObject(opts)?.ttlMs !== undefined &&
+        !__shouldRevalidate(opts) &&
+        __isCacheEntryStale(rawCached, opts)
+        ? undefined
+        : rawCached;
+    // Stage D — cross-mount cache-bust. If our local entry was cache-coupled
+    // (adopted from the cache OR write-backed after a fresh fire) and the cache
+    // entry has since been evicted (invalidate / delete / clear), we re-fire
+    // even though `depsKey` didn't change. Without this, a `useMutation`
+    // invalidate would only refresh the firing mount; sibling mounts holding
+    // adopted entries would keep showing stale data until their own deps changed.
+    const cacheBust = entryRef.current !== null &&
+        entryRef.current.cacheCoupled &&
+        useCache &&
+        opts.resourceName !== undefined &&
+        cached === undefined;
+    // Cache-miss branch: first call, or deps genuinely changed, or Stage D
+    // cache-bust. This is the ONLY abort site — no useEffect cleanup, no
+    // top-of-useMemo abort. The same depsKey on a subsequent render (including
+    // StrictMode's fake-remount) takes the cache-hit path and returns the
+    // existing promise.
+    let entry = entryRef.current;
+    if (entry === null || entry.depsKey !== depsKey || cacheBust) {
+        // Cancel the prior in-flight (if any). On first call this is a no-op.
+        entry?.controller?.abort();
+        const myGen = ++genRef.current;
+        if (deps === undefined) {
+            console.warn("[reactra:resource] RES004: deps is undefined — use null to explicitly skip");
+        }
+        // Resource v1 §3 + §6 — Stage A1 cache-hit branch. Before firing `fn`,
+        // consult `ResourceCache` for `(resourceName, cacheKey)` (pre-read above
+        // so the cacheBust check sees the same snapshot). On hit, take the cached
+        // entry's already-resolved promise (no Suspense flash) and sync the local
+        // state via microtask so future renders are stable.
+        if (cached !== undefined) {
+            // Stage A2 — distinguish a SETTLED hit (resolved value, or settled-error
+            // we may cache in a future stage) from an IN-FLIGHT hit (both undefined —
+            // a prior mount is still fetching). Settled keeps the A1 zero-flicker
+            // synth; in-flight adopts the shared promise + controller so this mount
+            // dedups onto the same fetch instead of firing its own.
+            const cachedSettled = cached.value !== undefined || cached.error !== undefined;
+            entry = {
+                depsKey,
+                gen: myGen,
+                controller: null, // cache owns the controller (two-layer ownership, §3)
+                promise: cached.promise,
+                cacheCoupled: true, // adopted from cache → re-fire on invalidate
+            };
+            if (cachedSettled) {
+                renderCached = cached;
+                const cachedValue = cached.value;
+                const cachedError = cached.error;
+                const cachedSel = applySel(cachedValue);
+                queueMicrotask(() => {
+                    if (myGen !== genRef.current)
+                        return;
+                    setState((s) => s.resolvedKey === depsKey && Object.is(s.data, cachedSel) && s.error === cachedError
+                        ? s
+                        : { data: cachedSel, error: cachedError, resolvedKey: depsKey });
+                });
+                // Stage B — stale-while-revalidate. If `cache.ttlMs` is set and the
+                // cached entry is past it, AND `cache.staleWhileRevalidate: true`,
+                // return the stale value this render (renderCached + microtask
+                // setState above) AND fire a background refetch. The refetch
+                // writes an SWR tombstone holding the STALE value + the in-flight
+                // promise + a FRESH writtenAt so a concurrent mount (a) gets a
+                // non-suspending settled hit, and (b) doesn't fire ANOTHER refresh
+                // (the fresh stamp signals "refresh in flight"). On success, the
+                // tombstone is superseded with the resolved value (same controller →
+                // idempotent supersede, no abort). On failure, the entry is REWRITTEN
+                // with `writtenAt: now` so the next attempt waits a full `ttlMs`
+                // (back-off; the consumer keeps showing the valid stale value).
+                // SWR failures do NOT setState({error}) — the consumer asked for
+                // stale-over-error semantics. C (retry) and onError live in a later stage.
+                if (__isCacheEntryStale(cached, opts) &&
+                    __shouldRevalidate(opts) &&
+                    opts.resourceName !== undefined &&
+                    deps !== null &&
+                    deps !== undefined) {
+                    const swrController = new AbortController();
+                    const swrResourceName = opts.resourceName;
+                    const swrCacheKey = cacheKey;
+                    const swrStaleValue = cached.value;
+                    // Stage C — SWR refresh also benefits from retries. Same normalization
+                    // path; null = bare call, zero overhead.
+                    const swrRetryConfig = __normalizeRetry(opts);
+                    const swrRawPromise = swrRetryConfig === null
+                        ? fn(deps, { signal: swrController.signal })
+                        : __fireWithRetry(deps, swrController.signal, swrRetryConfig, fn);
+                    // Tombstone: stale value + in-flight promise + fresh writtenAt.
+                    try {
+                        __currentCache.set(swrResourceName, swrCacheKey, {
+                            value: swrStaleValue,
+                            error: undefined,
+                            promise: swrRawPromise,
+                            controller: swrController,
+                            writtenAt: Date.now(),
+                        });
+                    }
+                    catch (err) {
+                        console.warn(`[reactra:resource] RES011: cache write failed for "${swrResourceName}" — falling back to no-cache for this entry`, err);
+                    }
+                    void swrRawPromise.then((value) => {
+                        if (myGen === genRef.current) {
+                            commitData(value);
+                        }
+                        try {
+                            __currentCache.set(swrResourceName, swrCacheKey, {
+                                value: value,
+                                error: undefined,
+                                promise: Promise.resolve(value),
+                                controller: swrController,
+                                writtenAt: Date.now(),
+                            });
+                        }
+                        catch (err) {
+                            console.warn(`[reactra:resource] RES011: cache write failed for "${swrResourceName}" — falling back to no-cache for this entry`, err);
+                        }
+                    }, (err) => {
+                        // SWR back-off: rewrite the stale entry with a fresh writtenAt so
+                        // the next render past ttlMs retries. The consumer is NOT
+                        // notified of the refresh error — stale-over-error is the SWR
+                        // contract; the stale data keeps showing.
+                        try {
+                            __currentCache.set(swrResourceName, swrCacheKey, {
+                                value: swrStaleValue,
+                                error: undefined,
+                                promise: Promise.resolve(swrStaleValue),
+                                controller: swrController,
+                                writtenAt: Date.now(),
+                            });
+                        }
+                        catch {
+                            /* swallow — cache impl rejected the rewrite */
+                        }
+                        // Dev-only diagnostic so a flaky API isn't completely silent.
+                        if (__isDevEnv()) {
+                            console.warn(`[reactra:resource] SWR refresh failed for "${swrResourceName}" — keeping stale data`, err);
+                        }
+                    });
+                }
+            }
+            else {
+                // In-flight adoption: attach a follow-on to the shared promise so THIS
+                // mount learns when it lands. `setState` is gated on `myGen` so a
+                // deps-change supersede silently drops the stale handler. The firing
+                // mount's own `.then` updates ITS state separately; both can race
+                // freely (idempotent `setState` shape).
+                void cached.promise.then((value) => {
+                    if (myGen !== genRef.current)
+                        return;
+                    commitData(value);
+                }, (err) => {
+                    if (myGen !== genRef.current)
+                        return;
+                    // Stage E — an AbortError from an adopted in-flight (typically a
+                    // cancelled `warmResource`, Resource v1 §8) is NOT surfaced to
+                    // the consumer. Stage D's `cacheBust = cacheCoupled && cached ===
+                    // undefined` re-fires fresh on the next render (warmResource's
+                    // failure path delete's the tombstone). Surfacing the abort would
+                    // flash an error in the UI for what is internally a benign
+                    // prefetch-cancelled-by-real-navigation race.
+                    if (err instanceof DOMException && err.name === "AbortError")
+                        return;
+                    setState((s) => ({ data: s.data, error: err, resolvedKey: depsKey }));
+                });
+            }
+        }
+        else if (deps === null || deps === undefined) {
+            entry = {
+                depsKey,
+                gen: myGen,
+                controller: null,
+                promise: Promise.resolve(undefined),
+                cacheCoupled: false, // no cache participation when skipping
+            };
+            // Clear any prior data/error on non-null→null transition (Resource v0
+            // §3 row 4). Microtask so we don't setState during render.
+            queueMicrotask(() => {
+                if (myGen !== genRef.current)
+                    return;
+                setState((s) => s.data === undefined && s.error === undefined && s.resolvedKey === depsKey
+                    ? s
+                    : { data: undefined, error: undefined, resolvedKey: depsKey });
+            });
+        }
+        else {
+            const controller = new AbortController();
+            // Capture name/key at fire time so the on-success cache write uses the
+            // values that fired this fetch, not the values from a later render.
+            const resourceName = opts.resourceName;
+            const writingCacheKey = cacheKey;
+            const writingToCache = useCache && resourceName !== undefined;
+            // Stage C — wrap `fn` in the retry loop when `opts.retry` is configured.
+            // `__normalizeRetry` returns null for `retry: 0`/absent, in which case
+            // the bare `fn` call is used (zero overhead, matching A1 behaviour).
+            const retryConfig = __normalizeRetry(opts);
+            const rawPromise = retryConfig === null
+                ? fn(deps, { signal: controller.signal })
+                : __fireWithRetry(deps, controller.signal, retryConfig, fn);
+            // Stage A2 — claim the cache key with an IN-FLIGHT tombstone before the
+            // `.then` chain. Concurrent mounts that render before this fetch lands
+            // will see `value === undefined && error === undefined` and adopt this
+            // promise + controller (cache-hit / in-flight branch above) instead of
+            // firing their own `fn`. Same-controller supersede is idempotent, so the
+            // on-success cache.set below does NOT abort this fetch.
+            if (writingToCache) {
+                try {
+                    __currentCache.set(resourceName, writingCacheKey, {
+                        value: undefined,
+                        error: undefined,
+                        promise: rawPromise,
+                        controller,
+                        writtenAt: Date.now(),
+                    });
+                }
+                catch (err) {
+                    // RES011 graceful degrade — no dedup for this fetch, but the fire
+                    // continues. (May log again on the success path's write; acceptable
+                    // for A2 — a once-per-key suppression is a future refinement.)
+                    console.warn(`[reactra:resource] RES011: cache write failed for "${resourceName}" — falling back to no-cache for this entry`, err);
+                }
+            }
+            const promise = rawPromise.then((value) => {
+                if (myGen === genRef.current) {
+                    commitData(value);
+                }
+                // Stage A1: cache only successful resolutions (errors retry on next
+                // mount, matching v0). Wrap quota/serialization failures in RES011.
+                if (writingToCache) {
+                    try {
+                        __currentCache.set(resourceName, writingCacheKey, {
+                            value,
+                            error: undefined,
+                            promise: Promise.resolve(value),
+                            controller,
+                            writtenAt: Date.now(),
+                        });
+                        // Stage D — write-back succeeded → this consumer's local entry
+                        // is now coupled to a shared cache entry. A subsequent
+                        // cross-mount invalidate that wipes the cache will bust the
+                        // local entry via the render-body cacheBust check.
+                        if (newEntry.gen === myGen)
+                            newEntry.cacheCoupled = true;
+                    }
+                    catch (err) {
+                        console.warn(`[reactra:resource] RES011: cache write failed for "${resourceName}" — falling back to no-cache for this entry`, err);
+                    }
+                }
+                return value;
+            }, (err) => {
+                if (myGen === genRef.current) {
+                    // Preserve last good data per Resource v0 §2 "data and error are
+                    // mutually exclusive in steady state".
+                    setState((s) => ({ data: s.data, error: err, resolvedKey: depsKey }));
+                }
+                // Stage A2 — withdraw the in-flight tombstone. Future mounts re-fire
+                // (matching A1's "do not cache rejections" rule, extended). The
+                // cache.delete may itself reject for a custom impl; swallow — the
+                // entry is logically already gone.
+                if (writingToCache) {
+                    try {
+                        __currentCache.delete(resourceName, writingCacheKey);
+                    }
+                    catch {
+                        /* swallow — entry already gone or impl rejected */
+                    }
+                }
+                throw err;
+            });
+            // `newEntry` is captured by the .then handler above so a successful
+            // write-back can flip `cacheCoupled` true (Stage D — couples the local
+            // entry to the shared cache for cross-mount bust detection).
+            const newEntry = {
+                depsKey,
+                gen: myGen,
+                controller,
+                promise,
+                cacheCoupled: false,
+            };
+            entry = newEntry;
+        }
+        entryRef.current = entry;
+    }
+    // Resource v1 §3 refetch row: invalidate the resource's cache entries so the
+    // re-fired fn re-populates. A1 uses `invalidate(name)` (the spec's public
+    // surface) which nukes every entry for the resource — over-invalidation is
+    // acceptable here; a future stage may add a per-key signature for surgical
+    // refetch. The refetchTick bump then causes a local-cache miss and refires.
+    const refetchResourceName = opts.resourceName;
+    const refetchCacheActive = useCache && refetchResourceName !== undefined;
+    const refetch = useCallback(() => {
+        if (refetchCacheActive && refetchResourceName !== undefined) {
+            __currentCache.invalidate(refetchResourceName);
+        }
+        setRefetchTick((t) => t + 1);
+    }, [refetchResourceName, refetchCacheActive]);
+    // Stage A1: on a cache HIT this render, synthesize the handle from the
+    // cached entry directly. Local `state` is updated by the microtask above and
+    // takes over from the second render on; without this synth the first cache-
+    // hit render would briefly show `data: undefined` while React queues the
+    // microtask, producing a flicker the cache exists to avoid.
+    if (renderCached !== undefined) {
+        return {
+            data: applySel(renderCached.value),
+            error: renderCached.error,
+            isPending: false,
+            refetch,
+            promise: entry.promise,
+        };
+    }
+    return {
+        data: state.data,
+        error: state.error,
+        // Derived: pending iff the most recent resolution doesn't match the
+        // currently rendered deps. Null/undefined deps are never pending.
+        isPending: deps === null || deps === undefined ? false : state.resolvedKey !== depsKey,
+        refetch,
+        promise: entry.promise,
+    };
+};
+/**
+ * Props for the ErrorBoundary emitted by `await(r) error(e) { … }` blocks.
+ * `fallback` is a render-fn (not an element) so the boundary can pass the
+ * caught error to the user's `error(e) { JSX }` body verbatim.
+ */
+// ---------------------------------------------------------------------------
+// Resource v1 §8 — `warmResource` (Stage E)
+// ---------------------------------------------------------------------------
+/**
+ * Resource v1 §8.1 — the runtime helper a compiler-emitted `warm(inputs,
+ * signal)` companion calls per-resource. Best-effort cache pre-fill; never
+ * throws. The returned promise resolves when the entry settles (success or
+ * any failure, including AbortError).
+ *
+ * Behaviour:
+ *   - If `(name, depsToKey(deps))` already has a cache entry (settled OR
+ *     in-flight), resolve immediately. Stage E treats any present entry as
+ *     "fresh enough" — consumers with SWR drive their own refresh from the
+ *     render path; warm doesn't aggressively refresh.
+ *   - Otherwise: write an in-flight tombstone (Stage A2 shape) keyed under
+ *     a fresh `AbortController` so concurrent warm + consumer mounts dedup.
+ *     Forward `callerSignal.abort` to the cache controller, propagating
+ *     cancel-on-real-navigation through to `fn(deps, { signal })`.
+ *   - On `fn` success: supersede the tombstone with the resolved entry
+ *     (same controller → idempotent supersede per §6).
+ *   - On `fn` failure (including AbortError): `cache.delete(name, depsKey)`
+ *     withdraws the tombstone. Any consumer mid-adopt sees the
+ *     `cacheBust = cacheCoupled && cached === undefined` check (Stage D)
+ *     and re-fires fresh on its next render. Failures are silently
+ *     resolved by the returned promise — RES015 was deliberately not
+ *     minted (§5; failed warms are debug-only).
+ */
+export const warmResource = async (name, deps, fn, callerSignal) => {
+    // Short-circuit on a pre-aborted signal — don't even write a tombstone.
+    if (callerSignal.aborted)
+        return;
+    const depsKey = depsToKey(deps);
+    // Cache-hit short-circuit. A1's settled entries OR A2's in-flight
+    // tombstones both qualify — present-in-cache means "someone else is
+    // (or has) handled this fetch", warm has nothing to add.
+    if (__currentCache.get(name, depsKey) !== undefined)
+        return;
+    const cacheCtrl = new AbortController();
+    // Two-layer signal composition: caller abort → cache controller abort →
+    // signal to fn. We own cacheCtrl; we listen for callerSignal so the cache
+    // entry's controller stays under our control (cache internals call .abort()
+    // on it freely without us having to expose / share the caller's signal).
+    const onCallerAbort = () => cacheCtrl.abort();
+    callerSignal.addEventListener("abort", onCallerAbort, { once: true });
+    let settledPromiseResolve;
+    const settledPromise = new Promise((resolve) => {
+        settledPromiseResolve = resolve;
+    });
+    // Wrap fn in its own .then chain so we can route success / failure into
+    // the cache without affecting the returned best-effort promise's shape.
+    const rawPromise = fn(deps, { signal: cacheCtrl.signal });
+    void rawPromise.then((value) => {
+        callerSignal.removeEventListener("abort", onCallerAbort);
+        try {
+            __currentCache.set(name, depsKey, {
+                value,
+                error: undefined,
+                promise: Promise.resolve(value),
+                controller: cacheCtrl,
+                writtenAt: Date.now(),
+            });
+        }
+        catch {
+            // Best-effort — swallow cache impl rejections silently. The whole
+            // warm path is "make consumer mounts faster if possible".
+        }
+        settledPromiseResolve?.();
+    }, () => {
+        // Failure path (network error OR AbortError from caller cancel).
+        // Withdraw the tombstone so a future consumer mount fires fresh
+        // (matches A2's on-rejection rule; aligns with Stage D's cacheBust
+        // for any consumer that adopted the tombstone before it failed).
+        callerSignal.removeEventListener("abort", onCallerAbort);
+        try {
+            __currentCache.delete(name, depsKey);
+        }
+        catch {
+            /* swallow */
+        }
+        settledPromiseResolve?.();
+    });
+    // Tombstone write goes AFTER attaching .then handlers but is still
+    // synchronous — concurrent renders + warm calls see it on their next
+    // microtask. RES011 path on the cache impl rejection: swallow (warm is
+    // best-effort; nothing else degrades).
+    try {
+        __currentCache.set(name, depsKey, {
+            value: undefined,
+            error: undefined,
+            promise: rawPromise,
+            controller: cacheCtrl,
+            writtenAt: Date.now(),
+        });
+    }
+    catch {
+        /* swallow */
+    }
+    return settledPromise;
+};
+/**
+ * Resource v1 §7 — `useMutation(fn, opts?)`. A user-called hook for
+ * non-idempotent side effects (POST, PATCH, DELETE, …) that may need to
+ * invalidate cached resources on success. Lives in `@reactra/resource`; NOT
+ * emitted by the compiler from any DSL keyword (architect Q6 — `mutation` is
+ * deliberately not added to the 25-keyword surface in v1).
+ *
+ * Behaviour:
+ *   - `mutate(args)` immediately calls `fn(args, { signal })` and returns the
+ *     promise. `isPending` toggles `true → false` on settle (success OR error).
+ *   - On success: writes `data`, clears `error`, then runs
+ *     `__currentCache.invalidate(opts.invalidate)` if `invalidate` is set. The
+ *     returned promise resolves AFTER invalidation is initiated.
+ *   - On rejection: writes `error`, retains the previous `data`. Retries (if
+ *     `opts.retry`) drain before the rejection lands. A final failure does NOT
+ *     invalidate.
+ *   - `reset()` aborts the in-flight call, clears `data` + `error`, toggles
+ *     `isPending` false. Reference is stable across renders.
+ *   - **RES013** throws if `mutate()` is called while `isPending` is true and
+ *     `concurrent !== true`. Set `concurrent: true` to opt in to overlap.
+ *   - **RES014** warns if `opts.invalidate` lists a name not yet known to the
+ *     cache (likely a typo). The mutation still completes.
+ *
+ * StrictMode: no `useEffect`. The in-flight controller lives in a `useRef`
+ * and is aborted by `reset()` or replaced on the next `mutate()` call.
+ */
+export const useMutation = (fn, opts = {}) => {
+    __firstMountFired = true;
+    const [state, setState] = useState({ data: undefined, error: undefined, isPending: false });
+    // The LIVE in-flight controller. Only the most recent `mutate()` call is
+    // tracked here — older overlapping calls (concurrent mode) run to completion
+    // but won't update handle state. Comparing `inFlightRef.current === myCtrl`
+    // inside the .then/.catch handlers is the supersede check.
+    const inFlightRef = useRef(null);
+    // Hold the latest opts so `mutate` doesn't need `opts` in its dep array
+    // (which would break the consumer pattern of passing a fresh object
+    // literal every render). reset is stable; mutate may re-create.
+    const optsRef = useRef(opts);
+    optsRef.current = opts;
+    const fnRef = useRef(fn);
+    fnRef.current = fn;
+    const reset = useCallback(() => {
+        if (inFlightRef.current !== null) {
+            inFlightRef.current.abort();
+            inFlightRef.current = null;
+        }
+        setState({ data: undefined, error: undefined, isPending: false });
+    }, []);
+    const mutate = useCallback(async (args) => {
+        const currentOpts = optsRef.current;
+        const currentFn = fnRef.current;
+        if (inFlightRef.current !== null && currentOpts.concurrent !== true) {
+            // RES013 — overlap without explicit opt-in. Throw synchronously so
+            // the calling code's `try { await mutate(args) } catch` sees it.
+            throw new Error("[reactra:resource] RES013: useMutation.mutate() called while previous call is in-flight; pass { concurrent: true } to allow overlap");
+        }
+        const controller = new AbortController();
+        inFlightRef.current = controller;
+        const myCtrl = controller;
+        setState((s) => ({ ...s, isPending: true }));
+        const retryConfig = __normalizeRetry({ retry: currentOpts.retry });
+        try {
+            const result = retryConfig === null
+                ? await currentFn(args, { signal: controller.signal })
+                : await __fireWithRetry(
+                // Mutation args have no null/undefined-as-skip semantics (that
+                // is useResource's domain), so widening to NonNullable<Args>
+                // is safe even if the consumer's Args generic admits null.
+                args, controller.signal, retryConfig, currentFn);
+            // Supersede check — only the LATEST in-flight updates handle state.
+            // Older overlapping calls still resolve their own promise (the caller
+            // gets the return value) but don't disturb data/error/isPending.
+            if (inFlightRef.current === myCtrl) {
+                inFlightRef.current = null;
+                setState({ data: result, error: undefined, isPending: false });
+                // §7 — invalidate fires AFTER setState (the promise resolves after
+                // invalidation is initiated). RES014 (the unknown-name backstop behind
+                // the compile-time `.reactra/resource-names.d.ts` net) now lives in
+                // `cache.invalidate` itself, so BOTH this path and the command-emitted
+                // `__getResourceCache().invalidate(...)` get the same warning.
+                const inv = currentOpts.invalidate;
+                if (inv !== undefined && inv.length > 0) {
+                    __currentCache.invalidate(inv);
+                }
+            }
+            return result;
+        }
+        catch (err) {
+            if (inFlightRef.current === myCtrl) {
+                inFlightRef.current = null;
+                setState((s) => ({ data: s.data, error: err, isPending: false }));
+            }
+            throw err;
+        }
+    }, []);
+    return { mutate, isPending: state.isPending, data: state.data, error: state.error, reset };
+};
+/**
+ * React class component used by compiled `await(r) error(e) { … }` blocks.
+ * Phase-1 surface: catches render-time errors below the boundary, then
+ * renders `fallback(error)`. No reset API yet — a fresh boundary is created
+ * on every parent re-render that re-emits a new JSX subtree.
+ *
+ * Resource v0 §4: errors thrown inside `fn` reject the promise; React.use()
+ * re-throws on subsequent render; this boundary catches the re-throw.
+ */
+export class ErrorBoundary extends React.Component {
+    state = { error: null };
+    static getDerivedStateFromError = (error) => ({ error });
+    render() {
+        if (this.state.error != null)
+            return this.props.fallback(this.state.error);
+        return this.props.children;
+    }
+}
+//# sourceMappingURL=index.js.map