@0xmonaco/react 1.0.51 → 1.0.53

package/dist/hooks/useUserBalances/useUserBalances.js

@@ -1,21 +1,199 @@
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { useMonacoSDK } from "../useMonaco";
+/**
+ * Page size for the balance read. The endpoint caps it at 100, and asking for
+ * the maximum keeps a full account to one request in practice.
+ */
+const BALANCES_PAGE_SIZE = 100;
+/**
+ * Hard ceiling on pages walked, mirroring the server snapshot's own guard: a
+ * malformed `totalPages` must not drive an unbounded read loop. At the page
+ * size above this covers far more assets than an account can hold.
+ */
+const MAX_BALANCE_PAGES = 20;
+/**
+ * Read every page of the user's balances.
+ *
+ * The endpoint is paginated and defaults to 20 rows, but the WebSocket snapshot
+ * walks the whole set — so a single-page read left any asset past the first
+ * page permanently unreachable, and a snapshot naming one would ask for a
+ * repair read that could never satisfy it.
+ *
+ * Termination is progress-based rather than trusting `totalPages`: a page
+ * shorter than the one requested is the last one, whatever the count claims,
+ * and the ceiling bounds the loop regardless.
+ *
+ * Rows are deduplicated by token, keeping the first occurrence, the same way
+ * `useUserOrders` deduplicates its paginated read. Offset paging is re-derived
+ * against whatever the table looks like when each page runs, so a row that
+ * moves between two reads can be returned twice — and a duplicate here would
+ * become two list entries for one asset, only the first of which any later
+ * update would find.
+ */
+async function readAllBalances(profile) {
+    const all = [];
+    const seen = new Set();
+    for (let page = 1; page <= MAX_BALANCE_PAGES; page++) {
+        const response = await profile.getUserBalances({ page, pageSize: BALANCES_PAGE_SIZE });
+        for (const row of response.balances) {
+            const token = row.token.toLowerCase();
+            if (seen.has(token))
+                continue;
+            seen.add(token);
+            all.push(row);
+        }
+        if (response.balances.length < BALANCES_PAGE_SIZE)
+            break;
+        if (Number.isFinite(response.totalPages) && page >= response.totalPages)
+            break;
+    }
+    return all;
+}
 /**
  * Update an AccountBalance with data from a WebSocket balance event
  */
 export function updateBalanceFromEvent(balance, event) {
-    const totalBalance = totalBalanceFromEvent(balance, event);
-    const totalBalanceRaw = totalBalanceRawFromEvent(balance, event);
+    return updateBalanceFromData(balance, event.data);
+}
+function updateBalanceFromData(balance, data) {
+    const totalBalance = totalBalanceFromData(balance, data);
+    const totalBalanceRaw = totalBalanceRawFromData(balance, data);
     return {
         ...balance,
-        availableBalance: event.data.available,
-        availableBalanceRaw: event.data.availableRaw,
-        lockedBalance: event.data.locked,
-        lockedBalanceRaw: event.data.lockedRaw,
+        availableBalance: data.available,
+        availableBalanceRaw: data.availableRaw,
+        lockedBalance: data.locked,
+        lockedBalanceRaw: data.lockedRaw,
         totalBalance: totalBalance,
         totalBalanceRaw: totalBalanceRaw,
     };
 }
+/**
+ * Apply a subscribe-time balances snapshot to the current list.
+ *
+ * The snapshot is the user's COMPLETE balance set, which is what makes this a
+ * different operation from applying a live event rather than a loop over one:
+ *
+ * - A held asset the snapshot omits has no balance left, so it is zeroed rather
+ *   than left showing a figure that is no longer true. The row itself stays —
+ *   a portfolio needs to render "0 WSEI", not to lose the line.
+ * - The snapshot's totals are taken VERBATIM. A snapshot row is built from the
+ *   same accounts-service read that produced the REST row, so its `total`
+ *   already is the REST `totalBalance` with margin collateral included —
+ *   unlike a live event, whose `total` can describe the spot balance alone and
+ *   therefore needs {@link updateBalanceFromEvent}'s margin reconciliation.
+ *   Running a snapshot row through that would add the derived margin component
+ *   a second time.
+ * - A row for an asset the list does not hold cannot be completed here: the
+ *   wire payload carries no `assetId`, `decimals` or wrapped-native flag. That
+ *   case is reported by {@link snapshotHasUnknownAsset} rather than from here,
+ *   so the caller can decide to re-read WITHOUT doing it inside a state
+ *   updater — React invokes an updater during render, and may invoke it more
+ *   than once, so a flag assigned inside one is not readable afterwards.
+ *
+ * Pure, so the caller can use it inside a state updater.
+ */
+export function applyBalanceSnapshot(current, items) {
+    const byToken = new Map(items.map((item) => [item.tokenAddress.toLowerCase(), item]));
+    const balances = current.map((held) => {
+        const item = byToken.get(held.token.toLowerCase());
+        if (!item) {
+            return {
+                ...held,
+                availableBalance: "0",
+                lockedBalance: "0",
+                totalBalance: "0",
+                availableBalanceRaw: "0",
+                lockedBalanceRaw: "0",
+                totalBalanceRaw: "0",
+            };
+        }
+        return {
+            ...held,
+            availableBalance: item.available,
+            lockedBalance: item.locked,
+            totalBalance: item.total,
+            availableBalanceRaw: item.availableRaw,
+            lockedBalanceRaw: item.lockedRaw,
+            totalBalanceRaw: item.totalRaw,
+        };
+    });
+    return { balances, hasUnknownAsset: snapshotHasUnknownAsset(current, items) };
+}
+/**
+ * Whether the snapshot names an asset the current list does not hold.
+ *
+ * Split out of {@link applyBalanceSnapshot} so a caller can ask the question
+ * before entering a state updater: the answer decides whether to fire a REST
+ * re-read, and a side effect must not depend on an updater having run.
+ */
+export function snapshotHasUnknownAsset(current, items) {
+    const heldTokens = new Set(current.map((held) => held.token.toLowerCase()));
+    return items.some((item) => !heldTokens.has(item.tokenAddress.toLowerCase()));
+}
+/**
+ * Merge a background REST read into the current list without disturbing it.
+ *
+ * The repair this serves has one job: learn about an asset the list does not
+ * hold yet, because the WebSocket payload carries no `assetId`, `decimals` or
+ * wrapped-native flag and so cannot introduce one on its own.
+ *
+ * It must not do more than that. The subscription stays live while the request
+ * is in flight, so an event or snapshot can land in between — and replacing the
+ * list with the response would roll those newer values back, including the
+ * authoritative snapshot figures that triggered the read in the first place.
+ * Rows already held therefore keep their live values untouched, and only
+ * genuinely new assets are appended.
+ *
+ * The initial load and the public `refresh()` still replace: the first runs
+ * before the subscription opens, so nothing newer can exist to lose, and the
+ * second is a deliberate "give me the server's answer" action.
+ */
+export function reconcileBalances(current, fetched) {
+    const held = new Set(current.map((row) => row.token.toLowerCase()));
+    const added = fetched.filter((row) => !held.has(row.token.toLowerCase()));
+    return added.length === 0 ? current : [...current, ...added];
+}
+/**
+ * Overlay buffered wire state onto rows a REST read has just supplied metadata
+ * for.
+ *
+ * A frame naming a token the list does not hold yet is dropped by the event
+ * handler — there is no row to apply it to — and the repair read that follows
+ * may have queried the server BEFORE that frame. Appending its result would
+ * then leave the token at a value the stream has already moved past, with no
+ * later frame to correct it because every subsequent frame finds a row and
+ * takes the update path. Buffering the newest wire state for an unheld token
+ * and laying it over the row once metadata arrives is what closes that.
+ *
+ * Only entries newer than the read are applied. One buffered BEFORE the read
+ * started is already reflected in its result, and re-applying it would roll the
+ * row back to that older value.
+ */
+export function applyBufferedBalances(rows, buffered, readSeq) {
+    if (buffered.size === 0)
+        return rows;
+    return rows.map((row) => {
+        const entry = buffered.get(row.token.toLowerCase());
+        if (!entry || entry.seq <= readSeq)
+            return row;
+        if (entry.source === "event") {
+            // A live non-margin frame can carry spot total only. Replaying it as a
+            // snapshot would replace the REST row's margin component instead of
+            // preserving it through the ordinary event reconciliation.
+            return updateBalanceFromData(row, entry.data);
+        }
+        return {
+            ...row,
+            availableBalance: entry.data.available,
+            lockedBalance: entry.data.locked,
+            totalBalance: entry.data.total,
+            availableBalanceRaw: entry.data.availableRaw,
+            lockedBalanceRaw: entry.data.lockedRaw,
+            totalBalanceRaw: entry.data.totalRaw,
+        };
+    });
+}
 function parseDecimal(value) {
     const match = value.trim().match(/^(-?)(\d+)(?:\.(\d+))?$/);
     if (!match)
@@ -60,33 +238,33 @@ function decimalGreaterThanZero(value) {
     const parsed = parseDecimal(value);
     return parsed ? parsed.value > 0n : false;
 }
-function totalBalanceFromEvent(balance, event) {
-    if (event.data.reason === "margin_transfer_in" || event.data.reason === "margin_transfer_out") {
-        return event.data.total;
+function totalBalanceFromData(balance, data) {
+    if (data.reason === "margin_transfer_in" || data.reason === "margin_transfer_out") {
+        return data.total;
     }
-    const eventExtraTotal = decimalDifference(event.data.total, event.data.available, event.data.locked);
+    const eventExtraTotal = decimalDifference(data.total, data.available, data.locked);
     if (eventExtraTotal && decimalGreaterThanZero(eventExtraTotal)) {
-        return event.data.total;
+        return data.total;
     }
     const previousMarginTotal = decimalDifference(balance.totalBalance, balance.availableBalance, balance.lockedBalance);
     if (!previousMarginTotal || !decimalGreaterThanZero(previousMarginTotal)) {
-        return event.data.total;
+        return data.total;
     }
-    return decimalSum(event.data.total, previousMarginTotal) ?? event.data.total;
+    return decimalSum(data.total, previousMarginTotal) ?? data.total;
 }
-function totalBalanceRawFromEvent(balance, event) {
-    if (event.data.reason === "margin_transfer_in" || event.data.reason === "margin_transfer_out") {
-        return event.data.totalRaw;
+function totalBalanceRawFromData(balance, data) {
+    if (data.reason === "margin_transfer_in" || data.reason === "margin_transfer_out") {
+        return data.totalRaw;
     }
-    const eventExtraTotalRaw = decimalDifference(event.data.totalRaw, event.data.availableRaw, event.data.lockedRaw);
+    const eventExtraTotalRaw = decimalDifference(data.totalRaw, data.availableRaw, data.lockedRaw);
     if (eventExtraTotalRaw && decimalGreaterThanZero(eventExtraTotalRaw)) {
-        return event.data.totalRaw;
+        return data.totalRaw;
     }
     const previousMarginTotalRaw = decimalDifference(balance.totalBalanceRaw, balance.availableBalanceRaw, balance.lockedBalanceRaw);
     if (!previousMarginTotalRaw || !decimalGreaterThanZero(previousMarginTotalRaw)) {
-        return event.data.totalRaw;
+        return data.totalRaw;
     }
-    return decimalSum(event.data.totalRaw, previousMarginTotalRaw) ?? event.data.totalRaw;
+    return decimalSum(data.totalRaw, previousMarginTotalRaw) ?? data.totalRaw;
 }
 /**
  * Hook for subscribing to real-time user balance updates via WebSocket (authenticated)
@@ -98,39 +276,193 @@ function totalBalanceRawFromEvent(balance, event) {
 export function useUserBalances() {
     const { sdk } = useMonacoSDK();
     const [balances, setBalances] = useState([]);
+    /**
+     * The latest applied balances, readable synchronously from a WebSocket
+     * callback — which closes over the `balances` of the render that installed
+     * it, and so cannot see anything applied since.
+     *
+     * Written by {@link applyBalances} at the moment a list is applied, not from
+     * inside a state updater, so it never lags the state it mirrors.
+     */
+    const balancesRef = useRef([]);
+    /**
+     * Bumped by effect cleanup. Every REST read captures this when it starts and
+     * declines to write anything if it no longer matches, so a response still in
+     * flight when the SDK changed cannot land in the new client's state — which
+     * on an account switch would mean showing, or appending, the previous user's
+     * balances. Mirrors `useUserOrders`' `readGeneration`.
+     */
+    const readGeneration = useRef(0);
+    /**
+     * Whether a background repair read is already in flight.
+     *
+     * A burst of frames naming a token the list does not hold yet would otherwise
+     * start one request per frame: `balancesRef` cannot learn the token until the
+     * first response lands, so every frame in the burst sees it as unknown.
+     */
+    const repairInFlight = useRef(false);
+    /**
+     * Whether a repair was asked for while one was already in flight.
+     *
+     * Coalescing alone would LOSE those updates rather than merely skip requests.
+     * A frame for a still-unknown token is also dropped by the event handler,
+     * because there is no row to apply it to — so if the in-flight read had
+     * already queried the server before that frame, it appends a value that is
+     * already stale and nothing later repairs it. This trailing flag runs exactly
+     * one more read after the first settles, which necessarily observes state
+     * newer than every frame that set it.
+     */
+    const repairDirty = useRef(false);
+    /**
+     * Newest wire state for tokens the list does not hold yet, with a monotonic
+     * sequence so a read can tell which entries postdate it. Cleared per token
+     * once a read has supplied that token's metadata; entries for tokens a read
+     * did not return stay buffered for the next one.
+     */
+    const bufferedUnheld = useRef(new Map());
+    const bufferSeq = useRef(0);
     const [loading, setLoading] = useState(false);
     const [error, setError] = useState(null);
     const [subscribed, setSubscribed] = useState(false);
     const clearError = useCallback(() => setError(null), []);
-    const fetchBalances = useCallback(async () => {
+    /** Remember a frame for a token the list cannot represent yet. */
+    const bufferUnheld = useCallback((items, source) => {
+        const held = new Set(balancesRef.current.map((row) => row.token.toLowerCase()));
+        for (const item of items) {
+            const token = item.tokenAddress.toLowerCase();
+            if (held.has(token))
+                continue;
+            bufferSeq.current += 1;
+            bufferedUnheld.current.set(token, { data: item, seq: bufferSeq.current, source });
+        }
+    }, []);
+    /**
+     * Apply a new list, reducing against the ref rather than through a functional
+     * state updater.
+     *
+     * The ref is the reducing source of truth and `setBalances` only mirrors it
+     * for rendering. That is what removes every dependence on updater timing:
+     * React invokes a functional updater during render and may invoke it more
+     * than once, so neither a side effect nor a value another statement needs can
+     * live inside one. Reducing here instead is also correct under a burst of
+     * WebSocket frames, where consecutive plain `setBalances(value)` calls would
+     * each have closed over a stale list.
+     */
+    const applyBalances = useCallback((next) => {
+        const applied = typeof next === "function" ? next(balancesRef.current) : next;
+        balancesRef.current = applied;
+        setBalances(applied);
+    }, []);
+    /**
+     * Read the balance list and apply it.
+     *
+     * `replace` is only correct while nothing newer can exist to lose — the
+     * initial load, which runs before the subscription opens, and the public
+     * `refresh()`. A read that runs with the socket live must `reconcile`, or an
+     * event arriving while the request is in flight is overwritten by the older
+     * response.
+     */
+    const loadBalances = useCallback(async (mode) => {
         if (!sdk?.profile)
             return;
-        setLoading(true);
+        const generation = readGeneration.current;
+        // Captured where the read starts: only frames buffered AFTER this point
+        // are newer than what the response will carry.
+        const readSeq = bufferSeq.current;
+        // A read belonging to a previous client must not write ANY of this state
+        // — not the rows, not the error, not the loading flag. Clearing `loading`
+        // from a stale request would mark the hook loaded while the new client's
+        // read is still running, and a stale rejection would leave `error` set
+        // after the new load had already succeeded.
+        const current = () => generation === readGeneration.current;
+        // `loading` describes the INITIAL load, which consumers render a spinner
+        // from. A background repair runs with the list already on screen, so it
+        // must not flash it.
+        if (mode === "replace")
+            setLoading(true);
         try {
-            const response = await sdk.profile.getUserBalances();
-            setBalances(response.balances);
+            const fetched = await readAllBalances(sdk.profile);
+            if (current()) {
+                // Lay any frame that arrived while the read was in flight over the
+                // rows it just supplied metadata for, then forget those tokens: they
+                // are held now, so every later frame reaches them the ordinary way.
+                const repaired = applyBufferedBalances(fetched, bufferedUnheld.current, readSeq);
+                for (const row of fetched)
+                    bufferedUnheld.current.delete(row.token.toLowerCase());
+                applyBalances(mode === "replace" ? repaired : (prev) => reconcileBalances(prev, repaired));
+            }
         }
         catch (err) {
-            setError(err instanceof Error ? err : new Error(String(err)));
+            if (current())
+                setError(err instanceof Error ? err : new Error(String(err)));
         }
         finally {
-            setLoading(false);
+            if (mode === "replace" && current())
+                setLoading(false);
         }
-    }, [sdk?.profile]);
+    }, [sdk?.profile, applyBalances]);
+    const fetchBalances = useCallback(() => loadBalances("replace"), [loadBalances]);
     const refresh = useCallback(async () => {
-        await fetchBalances();
-    }, [fetchBalances]);
+        await loadBalances("replace");
+    }, [loadBalances]);
     useEffect(() => {
         if (!sdk?.ws || !sdk?.profile) {
             setSubscribed(false);
+            // The previous effect's cleanup has already bumped `readGeneration`, so a
+            // read still in flight will now decline to write — including its own
+            // `setLoading(false)`. With no client left to start a replacement read,
+            // nothing else would ever clear the flag and the hook would report
+            // loading forever. Clear it here instead.
+            setLoading(false);
             return;
         }
-        setBalances([]);
+        applyBalances([]);
         setError(null);
         setLoading(true);
         // Fetch initial balances via REST API, then subscribe to WebSocket updates
         let unsubscribe;
         let cancelled = false;
+        /**
+         * Re-read the list to pick up an asset the stream cannot introduce on its
+         * own. Reconciles rather than replaces — this runs with the subscription
+         * live, so the response is already potentially stale by the time it lands
+         * — and coalesces, so a burst of frames for an unheld token costs one read.
+         */
+        const refetch = () => {
+            // Already reading: remember that something asked again, so the trailing
+            // read below picks up whatever those frames carried.
+            if (repairInFlight.current) {
+                repairDirty.current = true;
+                return;
+            }
+            // The coordination refs are shared across effect runs, so a repair
+            // started here must only touch them while it is still the current one. A
+            // read from a previous SDK settling late would otherwise clear
+            // `repairInFlight` out from under the NEW client's in-flight repair, and
+            // every frame after that would launch its own concurrent REST read.
+            // Cleanup resets both refs, so a generation that loses the race simply
+            // does nothing rather than leaving the flag stuck.
+            const generation = readGeneration.current;
+            repairInFlight.current = true;
+            repairDirty.current = false;
+            loadBalances("reconcile")
+                .catch((err) => {
+                if (!cancelled) {
+                    setError(err instanceof Error ? err : new Error(String(err)));
+                }
+            })
+                .finally(() => {
+                if (generation !== readGeneration.current)
+                    return;
+                repairInFlight.current = false;
+                // The dirty flag is cleared by the read this starts, not here:
+                // `refetch` resets it the moment it begins, which is the point at
+                // which every request made so far is subsumed. Clearing it in both
+                // places would read as two rules for one thing.
+                if (repairDirty.current && !cancelled)
+                    refetch();
+            });
+        };
         fetchBalances()
             .then(() => {
             // Bail out if effect was cleaned up before fetch resolved
@@ -139,30 +471,48 @@ export function useUserBalances() {
             // Subscribe to WebSocket balance updates after initial data is loaded
             try {
                 unsubscribe = sdk.ws.balances((event) => {
-                    let needsRefresh = false;
-                    setBalances((prev) => {
+                    // Decided off the ref before the updater, for the same reason the
+                    // snapshot path is: a token the list does not hold yet cannot be
+                    // built from the event alone, and the re-read that repairs it must
+                    // not depend on when React invokes an updater.
+                    const held = balancesRef.current.some((row) => row.token.toLowerCase() === event.data.tokenAddress.toLowerCase());
+                    if (!held && !cancelled) {
+                        // The updater below cannot apply this frame — there is no row
+                        // for it — so hold it until the read supplies one.
+                        bufferUnheld([event.data], "event");
+                        refetch();
+                    }
+                    applyBalances((prev) => {
                         // Find by token address and update (case-insensitive for addresses)
                         const existingIndex = prev.findIndex((b) => b.token.toLowerCase() === event.data.tokenAddress.toLowerCase());
                         const existingBalance = prev[existingIndex];
                         if (existingIndex >= 0 && existingBalance) {
-                            // Update existing balance
                             const updatedBalance = updateBalanceFromEvent(existingBalance, event);
                             const newBalances = [...prev];
                             newBalances[existingIndex] = updatedBalance;
                             return newBalances;
                         }
-                        // New token - flag for refresh outside the updater
-                        needsRefresh = true;
+                        // Not held yet — the re-read above is what adds it.
                         return prev;
                     });
-                    // Refresh outside the state updater to keep it pure
-                    if (needsRefresh && !cancelled) {
-                        fetchBalances().catch((err) => {
-                            if (!cancelled) {
-                                setError(err instanceof Error ? err : new Error(String(err)));
-                            }
-                        });
+                }, 
+                // The subscribe-time snapshot carries the whole balance set, so it
+                // repairs the list without a REST round trip — which is what makes
+                // a reconnect cheap: the resubscribe brings a fresh snapshot, and
+                // balances that moved during the outage are corrected from it.
+                (items) => {
+                    // Decided BEFORE the updater runs, off the ref rather than off an
+                    // updater's `prev`: an asset the list does not hold yet cannot be
+                    // completed from the wire payload alone (it carries no assetId or
+                    // decimals), so it needs a re-read — and a side effect must not
+                    // depend on when React chooses to invoke an updater.
+                    if (snapshotHasUnknownAsset(balancesRef.current, items) && !cancelled) {
+                        // Held before the read is issued, so a frame the read predates
+                        // is not lost when its row finally appears.
+                        bufferUnheld(items, "snapshot");
+                        refetch();
                     }
+                    applyBalances((prev) => applyBalanceSnapshot(prev, items).balances);
                 });
                 setSubscribed(true);
             }
@@ -180,8 +530,13 @@ export function useUserBalances() {
         return () => {
             cancelled = true;
             unsubscribe?.();
+            // Invalidates any read already in flight; see `readGeneration`.
+            readGeneration.current += 1;
+            repairInFlight.current = false;
+            repairDirty.current = false;
+            bufferedUnheld.current = new Map();
             setSubscribed(false);
         };
-    }, [sdk?.ws, sdk?.profile, fetchBalances]);
+    }, [sdk?.ws, sdk?.profile, fetchBalances, loadBalances, applyBalances, bufferUnheld]);
     return { balances, loading, subscribed, error, clearError, refresh };
 }

package/dist/hooks/useUserOrders/useUserOrders.d.ts

@@ -1,15 +1,122 @@
-import type { Order, OrderEvent } from "@0xmonaco/types";
+import type { Order, OrderEvent, OrderSnapshotItem, OrderStatus } from "@0xmonaco/types";
 import type { UseUserOrdersReturn } from "./types";
 export declare function useUserOrders(maxOrders?: number): UseUserOrdersReturn;
 /**
- * Reconcile a REST read against live state, last-writer-wins by `updatedAt`.
+ * Map one `orders` snapshot row onto the REST `Order` model, or `null` when
+ * this SDK version cannot describe it.
+ *
+ * Same decline contract as {@link orderFromEvent}, for the same reason: the
+ * wire values are handed through unvalidated, and relabelling a future order
+ * type or side renders an order as something it is not. `status` joins the
+ * declining set here, unlike on an `OrderPlaced` — that event IS a submitted
+ * order whatever string it carries, whereas a snapshot row's status is the
+ * order's actual resting state and has no honest substitute.
+ *
+ * The row's optionals arrive as explicit `null` (Rust `Option`s serialized
+ * without `skip_serializing_if`), so they are normalized to absent: the REST
+ * model declares them `?:`, and leaking `null` past it would have consumers
+ * branching on a value the model says cannot occur.
+ */
+export declare function orderFromSnapshotItem(item: OrderSnapshotItem): Order | null;
+/**
+ * Apply a subscribe-time `orders` snapshot to the current list.
+ *
+ * The snapshot carries RESTING orders only, so — unlike the balances one — it
+ * is not the whole list this hook shows. Replacing wholesale would erase every
+ * filled or cancelled order the user just placed, so it reconciles through
+ * the same version-first ordering as {@link mergeOrders}, with its cap applied
+ * by age.
+ *
+ * It IS complete for the persisted resting set, so absence identifies rows that
+ * need resolution — but it is not itself a terminal-state tombstone. On a fast
+ * reconnect persistence may lag a newer resting event retained from the prior
+ * connection, while an order that really filled or was cancelled during the
+ * outage is absent for the same reason: it no longer rests. The pure merge
+ * therefore keeps omitted resting rows and reports their ids so the caller can
+ * issue the targeted `getOrder` required by the shared order contract. That
+ * point read is cache-first and returns the state/version that can be ranked.
+ * Terminal rows are kept exactly as before: the snapshot never carried them,
+ * so their absence says nothing.
+ *
+ * A snapshot row is ranked against the order already held on `version`. The
+ * snapshot wins when its version is equal or higher, because it is the final
+ * state for that sequencer step; a lower version loses. A versioned local row
+ * also wins over an unversioned snapshot: the latter cannot be ranked and may
+ * be persisted state lagging the previous connection's live stream. When both
+ * sides are unversioned, the pre-counter fallback keeps the snapshot's original
+ * precedence instead of comparing incompatible timestamps; that also permits a
+ * validly-null `updatedAt`.
+ *
+ * A snapshot row is LAYERED over the order it already knows rather than
+ * replacing it. `OrderSnapshotItem` is not a whole `Order`: it carries no
+ * `postOnly`, `expirationDate`, `positionSide`, `terminalReason` or fee
+ * aggregates. Substituting a winning snapshot row would otherwise erase every
+ * one of those — including `postOnly`, where absence is never evidence of
+ * `false`. Spreading the row over the existing order lets the snapshot own
+ * exactly the fields it describes and leaves the rest standing.
+ *
+ * The fee aggregates are the one part that can then go stale rather than
+ * missing: they accumulate with fills, and a fill this connection never saw
+ * moves them. So a snapshot row that reports MORE filled quantity than the row
+ * it supersedes schedules the debounced REST re-read, which is the only source
+ * for them. A snapshot that changes nothing about the fill state schedules
+ * nothing, so a quiet reconnect still costs no request.
+ *
+ * `hasUndescribableRow` reports rows this version declined, `hasOfflineFill`
+ * rows whose fills this connection never saw, and `missingRestingOrderIds`
+ * names snapshot omissions that need point reads. The first two let the caller
+ * schedule the debounced list re-read; the last must not use a list page because
+ * an old order can fall outside it.
+ *
+ * Pure, and called with the current list read from a ref rather than from
+ * inside a state updater — an updater must stay free of side effects, and its
+ * signals exist precisely to drive those reads.
+ */
+export declare function applyOrderSnapshot(current: Order[], items: OrderSnapshotItem[], limit: number): {
+    orders: Order[];
+    hasUndescribableRow: boolean;
+    hasOfflineFill: boolean;
+    missingRestingOrderIds: string[];
+};
+/**
+ * The statuses the subscribe-time snapshot treats as resting.
+ *
+ * Mirrors the server's own `SNAPSHOT_RESTING_ORDER_STATUSES` — an order in one
+ * of these is still working on the book, so the snapshot carries it and its
+ * absence therefore means it stopped resting. Every other status is terminal
+ * or post-trade, never carried, so absence says nothing about it.
+ *
+ * The two sets must not drift: a status the server started treating as resting
+ * but this one does not would put its orders back in the stale-forever case
+ * this drop exists to fix, and one this set claims but the server does not
+ * would delete rows on an absence that means nothing. Exported so
+ * `useUserOrders.test.ts` can pin it against the Rust constant directly.
+ *
+ * A `Record<..., true>` over a subset of `OrderStatus`, read through
+ * `Object.hasOwn`, for the same reasons as {@link asKnown}: no prototype walk,
+ * and the union's own membership is checked by the compiler.
+ */
+export declare const SNAPSHOT_RESTING_STATUSES: Partial<Record<OrderStatus, true>>;
+/**
+ * Map snapshot rows onto the REST model, reporting whether any was declined.
+ *
+ * Split out of {@link applyOrderSnapshot} because it needs no view of the
+ * current list, which makes the mapping — and the decline rule that governs it
+ * — testable on its own.
+ */
+export declare function snapshotOrderRows(items: OrderSnapshotItem[]): {
+    rows: Order[];
+    hasUndescribableRow: boolean;
+};
+/**
+ * Reconcile a REST read against live state, ranking on `version` first.
  *
  * The resync runs with the subscription open, so `fetched` may already be stale
  * by the time it lands. Three cases:
  *
- * - In both: keep whichever `updatedAt` is later, so a fill that arrived over
- *   the socket mid-request is not rolled back by an older REST row. Ties keep
- *   the live row, which cannot be older than the response.
+ * - In both: when either row has `version`, the versioned side wins; when both
+ *   do, the incoming REST row wins on `>=` because it is that step's final
+ *   state. Only when neither has a version does `updatedAt` arbitrate.
  * - Live only: keep it. Either it was placed over the socket after the read
  *   started, or it is an older row the page no longer reaches — the two are
  *   indistinguishable here, which is why the cap is applied by age below