tempest-react-sdk 0.48.0 → 0.49.0

package/dist/tempest-react-sdk.d.ts

@@ -806,6 +806,12 @@ export declare type AppBarTone = "surface" | "primary" | "transparent";
  * @example
  * const visible = applyFilters(orders, filters);
  *
+ * Each filter's values are normalised once, before the scan, rather than inside
+ * the per-row predicate: the arity, the `between` ordering and the value array
+ * depend only on the filter, so deriving them per row multiplied that work by
+ * the row count. `empty`/`notEmpty` ignore their values entirely, which is why
+ * the prepared shape does not need to distinguish them.
+ *
  * @param items - The full list.
  * @param filters - Applied filters; incomplete ones are ignored.
  * @returns A new array with the rows that satisfy every complete filter.
@@ -1504,6 +1510,15 @@ export declare interface BarcodeScanResult {
  * numbers on purpose: a width scaled by the total leaves every bar short in a
  * long list, which is when the chart is needed most.
  *
+ * Colors come from {@link useChartColors}, the same resolver every chart in the
+ * SDK uses, so a theme that declares fewer series than the eight
+ * `--tempest-chart-*` slots cycles within its own palette. Reading the tokens
+ * through CSS `var()` could not do that: the count lives in
+ * `--tempest-chart-count`, which CSS cannot use as a modulus, so a six-color
+ * brand palette got the SDK's leftover defaults in rows seven and eight — the
+ * exact regression that token exists to prevent. `palette.ts` imports nothing,
+ * so this pulls no chart library into the slice.
+ *
  * @example
  * <BarList
  *     items={[{ label: "Free", value: 128 }, { label: "Pro", value: 32 }]}
@@ -1571,6 +1586,9 @@ export declare type BarListSort = "desc" | "asc" | "none";
  * `atob` and losing the last byte — is the classic broken-WebAuthn bug, which is
  * why the SDK owns it instead of leaving it to each app.
  *
+ * This is the WebAuthn-facing name for {@link base64ToBytes}; the codec itself is
+ * shared, so the padding rule has one implementation rather than three.
+ *
  * @param value - Base64url text, with or without `=` padding.
  * @returns The decoded bytes.
  */
@@ -1870,6 +1888,9 @@ export declare type ButtonVariant = "primary" | "secondary" | "danger" | "succes
 /**
  * Encode bytes as an unpadded base64url string.
  *
+ * Normalises `ArrayBuffer` to a view — which is what the WebAuthn response
+ * fields hand over — and delegates the encoding to {@link bytesToBase64}.
+ *
  * @param value - Bytes to encode, as a view or a raw buffer.
  * @returns Base64url text, safe to put in JSON and in a URL.
  */
@@ -2607,33 +2628,17 @@ export declare function compareValues(a: unknown, b: unknown): number;
 /**
  * Typed `localStorage` wrapper that gzips what it writes.
  *
- * Mirrors {@link storage} so the two are interchangeable at the call site; the
- * difference is only in how the value is encoded.
+ * {@link createJsonStorage} with {@link compressedStorageCodec}, so it is the
+ * same implementation as {@link storage} and genuinely interchangeable with it —
+ * `get`, `set` and `remove`, differing only in how the value is encoded. It used
+ * to be a hand-written copy that had no `remove`, which made that promise false
+ * for anybody who took the docstring at its word.
+ *
+ * When compression itself fails the value is written as plain JSON rather than
+ * dropped: a slightly larger record still loads, an absent one does not. Only a
+ * storage-level failure — quota, blocked storage — loses the write.
  */
-export declare const compressedStorage: {
-    /**
-     * Read and decompress a key.
-     *
-     * @typeParam T - The expected value shape.
-     * @param key - Storage key.
-     * @param fallback - Returned when the key is absent, unreadable, or corrupt.
-     * @returns The stored value, or `fallback`.
-     */
-    get<T>(key: string, fallback: T): T;
-    /**
-     * Compress and write a key.
-     *
-     * When compression itself fails the value is written as plain JSON rather
-     * than dropped: a slightly larger record still loads, an absent one does
-     * not. Only a storage-level failure — quota, blocked storage — loses the
-     * write.
-     *
-     * @typeParam T - The value being stored.
-     * @param key - Storage key.
-     * @param value - Any JSON-serializable value.
-     */
-    set<T>(key: string, value: T): void;
-};
+export declare const compressedStorage: JsonStorage;
 
 /**
  * Codec pair for {@link useLocalStorage}, so a compressed key gets the hook's
@@ -2642,10 +2647,7 @@ export declare const compressedStorage: {
  * @example
  * const [save, setSave] = useLocalStorage("save", EMPTY_SAVE, compressedStorageCodec);
  */
-export declare const compressedStorageCodec: {
-    serialize: typeof compressToString;
-    deserialize: typeof decompressFromString;
-};
+export declare const compressedStorageCodec: StorageCodec;
 
 /**
  * Serialize a value to a gzipped, base64 string carrying the format marker.
@@ -3060,6 +3062,10 @@ export declare interface CreateGrowthBookFeatureFlagsAdapterOptions {
  * });
  * i18n.t("greet", { name: "Mau" });          // "Olá, Mau"
  * i18n.plural("alos", 3);                     // "3 Alôs"
+ *
+ * @example
+ * // A key the catalog does not define, with text to show instead of the key.
+ * i18n.t("cart.empty", undefined, { default: "Seu carrinho está vazio" });
  */
 export declare function createI18n(options: CreateI18nOptions): I18n;
 
@@ -3120,6 +3126,34 @@ export declare function createInMemoryFlags(options?: InMemoryFlagsOptions): Fea
     set: (key: string, value: FlagValue) => void;
 };
 
+/**
+ * Build a typed `localStorage` wrapper around a codec.
+ *
+ * One implementation behind every store the SDK ships, so they cannot drift in
+ * surface. {@link storage} and {@link compressedStorage} are both this function —
+ * before it, the compressed one was a hand-written copy of the same guards and
+ * had no `remove`, while its own docstring promised the two were interchangeable
+ * at the call site. They were not, and the promise failed exactly where somebody
+ * followed it.
+ *
+ * @example
+ * const session = createJsonStorage();
+ * session.set("draft", { title: "Sem título" });
+ *
+ * @example
+ * const packed = createJsonStorage(compressedStorageCodec);
+ *
+ * @param codec - Encoder pair. Defaults to plain JSON.
+ * @returns A store with `get` / `set` / `remove`.
+ *
+ * @tempest-limits empty-catch — every method is best-effort by contract:
+ * `localStorage` throws on quota exhaustion, in Safari private mode, and when a
+ * cross-origin frame has storage blocked. A caller persisting a preference has no
+ * recovery to run and no user-facing message to show, so the write is dropped and
+ * the app keeps the value in memory for the session.
+ */
+export declare function createJsonStorage(codec?: StorageCodec): JsonStorage;
+
 /**
  * Build a [[FeatureFlagsAdapter]] backed by a LaunchDarkly JS client. Apps
  * initialise the client themselves (`LDClient.initialize(envKey, ctx)`) and
@@ -3630,34 +3664,6 @@ export declare interface CreateSentryTelemetryAdapterOptions {
     breadcrumbCategory?: string;
 }
 
-/**
- * A pool of preallocated `<audio>` elements for short sound effects.
- *
- * `new Audio(src)` on every play allocates an element and re-enters the network
- * stack for a file the browser already has, which is the wrong shape for a
- * sound that fires dozens of times a minute — a UI blip, a hit, a pickup. The
- * pool allocates once per source and replays.
- *
- * This is deliberately not {@link createAudioPlayer}: that handle tracks a
- * single "current" clip with loop, sink routing and lifecycle callbacks, which
- * is what background music needs. Effects are the opposite case — many
- * sources, all short, fire-and-forget, and the only thing that matters is that
- * firing one is cheap.
- *
- * A blocked `play()` is swallowed. Browsers reject playback until the user has
- * interacted with the page, and a sound effect is by definition not worth
- * interrupting anything over; call {@link SfxPool.preload} after the first
- * interaction if you want the pool warm.
- *
- * @param options - Master volume, base URL, voices per source and pool size.
- * @returns The pool handle.
- *
- * @example
- * const sfx = createSfxPool({ volume: 0.6, baseUrl: import.meta.env.BASE_URL });
- * sfx.preload(["sfx/select.mp3", "sfx/back.mp3"]);
- *
- * <button onClick={() => sfx.play("sfx/select.mp3")}>Confirmar</button>
- */
 export declare function createSfxPool(options?: SfxPoolOptions): SfxPool;
 
 /**
@@ -4159,6 +4165,64 @@ export declare interface DataProviderOptions {
  */
 export declare function DataTable<T>({ data, columns, pageSize, searchable, searchKeys, initialSort, rowKey, emptyMessage, onCellChange, editLabels, totalItems, page: controlledPage, onPageChange, manualSort, onSortChange, manualSearch, onSearchChange, loading, className, ...rest }: DataTableProps<T>): JSX.Element;
 
+/** Everything a table needs regardless of who owns paging, sorting and searching. */
+export declare interface DataTableBaseProps<T> extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * The rows to work with.
+     *
+     * By default this is the **full** dataset and sorting, searching and paging
+     * all happen in memory. Pass `totalItems` and it becomes the current page as
+     * the server returned it, with those three delegated to the caller.
+     */
+    data: T[];
+    /** Column definitions. */
+    columns: DataTableColumn<T>[];
+    /** Rows per page. Default 10. */
+    pageSize?: number;
+    /** Render a search input above the table. Default false. */
+    searchable?: boolean;
+    /**
+     * Keys to match the search term against. When omitted, every column whose
+     * value is a string or number is searched.
+     */
+    searchKeys?: (keyof T)[];
+    /** Initial sort applied before any header interaction. */
+    initialSort?: DataTableSort<T>;
+    /** Stable key extractor for rows. Defaults to the row index. */
+    rowKey?: (row: T, index: number) => string | number;
+    /** Content shown when no rows match. */
+    emptyMessage?: ReactNode;
+    /**
+     * Persist an accepted cell edit. Return a promise: while it is pending the cell
+     * already shows the new value, and a rejection rolls that back and surfaces the
+     * error in the cell. Without this prop no column is editable.
+     */
+    onCellChange?: (change: DataTableCellChange<T>) => void | Promise<void>;
+    /** Override the PT-BR copy of the editing affordances. */
+    editLabels?: Partial<DataTableEditLabels>;
+    /**
+     * Searching is the caller's job: typing reports through `onSearchChange` and
+     * the rows are left as they arrived.
+     *
+     * Implied by `totalItems`. Filtering the current page would hide the rows
+     * that do not match *on this page* and show nothing for a term that only
+     * matches on page three — an empty table that looks like "no results".
+     */
+    manualSearch?: boolean;
+    /** Called with the current search term (debouncing, if any, is the caller's). */
+    onSearchChange?: (term: string) => void;
+    /**
+     * A fetch is in flight.
+     *
+     * With rows already on screen they stay put, dimmed and `aria-busy`, so the
+     * page does not jump under the cursor between pages. With no rows yet it
+     * renders placeholder lines at full height, which is a different statement
+     * from `emptyMessage`: "loading" and "there is nothing" are not the same
+     * screen.
+     */
+    loading?: boolean;
+}
+
 /** One accepted cell edit, handed to `onCellChange`. */
 export declare interface DataTableCellChange<T> {
     /** The row as it was before the edit. */
@@ -4236,40 +4300,24 @@ export declare interface DataTableEditLabels {
 /** Input types an editable column can use. */
 export declare type DataTableEditorType = "text" | "number" | "date" | "email" | "tel" | "url";
 
-export declare interface DataTableProps<T> extends HTMLAttributes<HTMLDivElement> {
-    /**
-     * The rows to work with.
-     *
-     * By default this is the **full** dataset and sorting, searching and paging
-     * all happen in memory. Pass `totalItems` and it becomes the current page as
-     * the server returned it, with those three delegated to the caller.
-     */
-    data: T[];
-    /** Column definitions. */
-    columns: DataTableColumn<T>[];
-    /** Rows per page. Default 10. */
-    pageSize?: number;
-    /** Render a search input above the table. Default false. */
-    searchable?: boolean;
-    /**
-     * Keys to match the search term against. When omitted, every column whose
-     * value is a string or number is searched.
-     */
-    searchKeys?: (keyof T)[];
-    /** Initial sort applied before any header interaction. */
-    initialSort?: DataTableSort<T>;
-    /** Stable key extractor for rows. Defaults to the row index. */
-    rowKey?: (row: T, index: number) => string | number;
-    /** Content shown when no rows match. */
-    emptyMessage?: ReactNode;
-    /**
-     * Persist an accepted cell edit. Return a promise: while it is pending the cell
-     * already shows the new value, and a rejection rolls that back and surfaces the
-     * error in the cell. Without this prop no column is editable.
-     */
-    onCellChange?: (change: DataTableCellChange<T>) => void | Promise<void>;
-    /** Override the PT-BR copy of the editing affordances. */
-    editLabels?: Partial<DataTableEditLabels>;
+/**
+ * Paging, as one of the three shapes that actually work.
+ *
+ * These used to be three optional props, so the compiler accepted
+ * `totalItems` with no `page` — a table whose pager moves an internal page while
+ * `data` keeps showing page one. Every prop was optional on its own, so the only
+ * place left to catch it was a `console.warn` in dev, in the browser, with the
+ * component mounted. As a union the same mistake is a build error at the call
+ * site, for free, everywhere.
+ */
+export declare type DataTablePagingProps = {
+    /** Not server mode. */
+    totalItems?: never;
+    /** The table owns the page. */
+    page?: never;
+    /** Nothing to report to. */
+    onPageChange?: never;
+} | {
     /**
      * Total row count across every page — the `total` of a paginated envelope.
      *
@@ -4279,49 +4327,64 @@ export declare interface DataTableProps<T> extends HTMLAttributes<HTMLDivElement
      * (see `manualSort` / `manualSearch`, which are implied here). Pair it with
      * `page` and `onPageChange`.
      */
-    totalItems?: number;
+    totalItems?: never;
     /** Current page, 1-based. Controlled — required in server mode. */
-    page?: number;
+    page: number;
     /** Called with the next page. Required whenever `page` is controlled. */
-    onPageChange?: (page: number) => void;
-    /**
-     * Sorting is the caller's job: clicking a header reports through
-     * `onSortChange` and the rows are left in the order they arrived.
-     *
-     * Implied by `totalItems`, because sorting the page in memory would sort
-     * *that page only* while the header claims the whole table is ordered.
-     */
-    manualSort?: boolean;
-    /** Called with the next sort state — `null` when the header cycles back to unsorted. */
-    onSortChange?: (sort: DataTableSort<T> | null) => void;
-    /**
-     * Searching is the caller's job: typing reports through `onSearchChange` and
-     * the rows are left as they arrived.
-     *
-     * Implied by `totalItems`. Filtering the current page would hide the rows
-     * that do not match *on this page* and show nothing for a term that only
-     * matches on page three — an empty table that looks like "no results".
-     */
-    manualSearch?: boolean;
-    /** Called with the current search term (debouncing, if any, is the caller's). */
-    onSearchChange?: (term: string) => void;
+    onPageChange: (page: number) => void;
+} | {
     /**
-     * A fetch is in flight.
+     * Total row count across every page — the `total` of a paginated envelope.
      *
-     * With rows already on screen they stay put, dimmed and `aria-busy`, so the
-     * page does not jump under the cursor between pages. With no rows yet it
-     * renders placeholder lines at full height, which is a different statement
-     * from `emptyMessage`: "loading" and "there is nothing" are not the same
-     * screen.
+     * Passing it switches the table to **server mode**: `data` is read as the
+     * current page, the page count comes from this number instead of
+     * `data.length`, and sorting and searching are delegated to the caller
+     * (see `manualSort` / `manualSearch`, which are implied here). `page` and
+     * `onPageChange` come with it — the type says so, because a server-mode
+     * table without them silently shows page one forever.
      */
-    loading?: boolean;
-}
+    totalItems: number;
+    /** Current page, 1-based. Controlled, and required in server mode. */
+    page: number;
+    /** Called with the next page. */
+    onPageChange: (page: number) => void;
+};
+
+/**
+ * The table's props: the shared half, plus one valid paging shape and one valid
+ * sorting shape.
+ */
+export declare type DataTableProps<T> = DataTableBaseProps<T> & DataTablePagingProps & DataTableSortProps<T>;
 
 export declare interface DataTableSort<T> {
     key: keyof T;
     direction: SortDirection;
 }
 
+/**
+ * Sorting: delegated, and therefore reported, or neither.
+ *
+ * `manualSort` without `onSortChange` renders a header that moves its arrow and
+ * changes nothing else — the arrow is a lie the compiler can now catch.
+ */
+export declare type DataTableSortProps<T> = {
+    /** The table sorts the rows it has. */
+    manualSort?: false;
+    /** Called with the next sort state — `null` when the header cycles back to unsorted. */
+    onSortChange?: (sort: DataTableSort<T> | null) => void;
+} | {
+    /**
+     * Sorting is the caller's job: clicking a header reports through
+     * `onSortChange` and the rows are left in the order they arrived.
+     *
+     * Implied by `totalItems`, because sorting the page in memory would sort
+     * *that page only* while the header claims the whole table is ordered.
+     */
+    manualSort: true;
+    /** Where the click goes. Required, since nothing else acts on it. */
+    onSortChange: (sort: DataTableSort<T> | null) => void;
+};
+
 /**
  * Thin wrapper around the native `<input type="date">` (or `datetime-local`,
  * `time`, `month`). For richer pickers, pair with `react-datepicker` directly
@@ -5215,15 +5278,55 @@ export declare function filtersFromSearchParams(params: URLSearchParams, fields:
  *   will not answer an `empty` filter, while {@link applyFilters} treats blank
  *   text as empty.
  *
+ * The defaults are that dialect, not a universal truth. A backend that names its
+ * substring column something other than `name`, or that spells its operators
+ * differently, passes `options` — the alternative was an encoder whose special
+ * cases were a wall for anyone not on the Tempest stack.
+ *
  * @example
  * const params = filtersToQueryParams(filters);
  * params.set("page", String(page));
  * const data = await api.get(`/orders?${params}`);
  *
+ * @example
+ * // A backend whose searchable column is `razao_social` and that spells `ne`
+ * // the Django way.
+ * const params = filtersToQueryParams(filters, {
+ *     substringColumns: ["razao_social"],
+ *     operatorSuffix: { ne: "__exclude" },
+ * });
+ *
  * @param filters - Applied filters; incomplete ones are ignored.
+ * @param options - Dialect overrides. Defaults to the `tempest-fastapi-sdk` one.
  * @returns Params ready to append to a request URL.
  */
-export declare function filtersToQueryParams(filters: readonly Filter[]): URLSearchParams;
+export declare function filtersToQueryParams(filters: readonly Filter[], options?: FiltersToQueryParamsOptions): URLSearchParams;
+
+/** Overrides for the backend dialect {@link filtersToQueryParams} encodes into. */
+export declare interface FiltersToQueryParamsOptions {
+    /**
+     * Columns whose `eq` is emitted as `<column>__iexact` rather than as the bare
+     * column name. Default `["name"]`, which is what `build_filter_condition`
+     * special-cases.
+     *
+     * Pass the columns **your** backend treats that way — `nome`, `titulo`,
+     * `razao_social` — or `[]` when it treats none of them specially and a bare
+     * `eq` should stay bare.
+     */
+    substringColumns?: readonly string[];
+    /**
+     * Operator suffixes, merged over the `tempest-fastapi-sdk` dialect, so an
+     * override names only the operators that differ.
+     *
+     * @example
+     * // A DRF-style backend
+     * filtersToQueryParams(filters, {
+     *     substringColumns: [],
+     *     operatorSuffix: { contains: "__icontains", ne: "__exclude" },
+     * });
+     */
+    operatorSuffix?: Partial<Record<FilterOperator, string>>;
+}
 
 /**
  * Serialize filters into URL search params.
@@ -5914,14 +6017,16 @@ export declare interface I18n {
     fallbackLocale: string | null;
     /**
      * Translate `key`, interpolating `{name}` placeholders from `params`.
-     * Falls back to the configured fallback locale, then to the key itself.
+     * Falls back to the configured fallback locale, then to `options.default`,
+     * then to the key itself.
      */
-    t: (key: string, params?: InterpolationValues) => string;
+    t: (key: string, params?: InterpolationValues, options?: TranslateOptions) => string;
     /**
      * Plural-aware translation. Tries `${key}_one` for `count === 1` and
      * `${key}_other` otherwise, with `{count}` available for interpolation.
+     * Falls back to `options.default`, then to the key itself.
      */
-    plural: (key: string, count: number, params?: InterpolationValues) => string;
+    plural: (key: string, count: number, params?: InterpolationValues, options?: TranslateOptions) => string;
     /** Format a number using `Intl.NumberFormat` on the active locale. */
     formatNumber: (value: number, options?: Intl.NumberFormatOptions) => string;
     /** Format a Date using `Intl.DateTimeFormat` on the active locale. */
@@ -6563,6 +6668,31 @@ export declare function isPlatformAuthenticatorAvailable(): Promise<boolean>;
  */
 export declare function isPushSupported(): boolean;
 
+/**
+ * Whether an HTTP status describes a condition a replay can plausibly fix.
+ *
+ * The single owner of that decision. It used to be spelled out in three places —
+ * the client's own policy, the react-query default and the bare `retry()` helper
+ * — and they had already drifted: the query default was missing `425`, so the
+ * same `425 Too Early` was replayed through `createApiClient({ retry: true })`
+ * and not replayed through `useQuery`. Same app, same error, two behaviours, and
+ * no test caught it because each file asserted against its own copy.
+ *
+ * Deliberately about the status and nothing else. Whether a *non*-API error is
+ * worth replaying, and whether the request's method may be replayed at all, are
+ * the caller's calls: {@link createApiClient} refuses a non-idempotent method,
+ * while a bare `retry()` has no method to inspect.
+ *
+ * @example
+ * await api.get("/report", {
+ *     retry: { shouldRetry: (error) => isApiError(error) && isRetriableStatus(error.status) },
+ * });
+ *
+ * @param status - The HTTP status, where `0` means the request never landed.
+ * @returns Whether a retry is worth attempting.
+ */
+export declare function isRetriableStatus(status: number): boolean;
+
 /** Whether `getDisplayMedia` is reachable at all. */
 export declare function isScreenCaptureSupported(): boolean;
 
@@ -6599,6 +6729,33 @@ export declare function isValidLongitude(value: number): boolean;
 /** Whether `MediaRecorder` exists and can produce at least one video container. */
 export declare function isVideoRecordingSupported(): boolean;
 
+/** The surface every store built by {@link createJsonStorage} exposes. */
+export declare interface JsonStorage {
+    /**
+     * Read and decode a key.
+     *
+     * @typeParam T - The expected value shape.
+     * @param key - Storage key.
+     * @param fallback - Returned when the key is absent, unreadable, or corrupt.
+     * @returns The stored value, or `fallback`.
+     */
+    get<T>(key: string, fallback: T): T;
+    /**
+     * Encode and write a key.
+     *
+     * @typeParam T - The value being stored.
+     * @param key - Storage key.
+     * @param value - Any value the codec can represent.
+     */
+    set<T>(key: string, value: T): void;
+    /**
+     * Delete a key.
+     *
+     * @param key - Storage key.
+     */
+    remove(key: string): void;
+}
+
 /**
  * Kanban board: columns of cards, reorderable within a column and movable across
  * columns, by pointer **or** keyboard.
@@ -9703,7 +9860,12 @@ export declare interface RetryOptions {
     respectRetryAfter?: boolean;
     /**
      * Return false to stop retrying for a specific error.
-     * Default: retry on any thrown error.
+     *
+     * Default: replay anything that is not a recognisable API error — a
+     * transport failure has no status to judge — and, for one that is, only the
+     * statuses {@link isRetriableStatus} accepts. A `403` on an admin-only
+     * endpoint and a `404` for a deleted record are the server's final answer;
+     * repeating them spends the caller's time to show the same error twice.
      */
     shouldRetry?: (error: unknown, attempt: number) => boolean;
     /** Called before each retry with the upcoming delay. */
@@ -10221,6 +10383,11 @@ export declare interface ShareResult {
  * of another round trip. A network failure or a 5xx is a different thing: it may
  * well succeed on the next try, so those keep the previous behaviour.
  *
+ * The status list is {@link isRetriableStatus}, shared with the client's own
+ * policy. It used to be a second copy here, and the copy was missing `425` — so
+ * a `425 Too Early` was replayed by `createApiClient({ retry: true })` and not
+ * by a query, for the same error in the same app.
+ *
  * @example
  * new QueryClient({ defaultOptions: { queries: { retry: shouldRetryQuery } } });
  *
@@ -10810,20 +10977,18 @@ export declare interface StepperProps {
 export declare function stopAudio(): void;
 
 /**
- * Typed wrapper around `localStorage` that JSON-encodes values and
- * silently handles environments where storage is unavailable (SSR, private mode).
- *
- * @tempest-limits empty-catch — every method here is best-effort by contract:
- * `localStorage` throws on quota exhaustion, in Safari private mode, and when a
- * cross-origin frame has storage blocked. A caller persisting a preference has no
- * recovery to run and no user-facing message to show, so the write is dropped and
- * the app keeps the value in memory for the session.
+ * Typed wrapper around `localStorage` that JSON-encodes values and silently
+ * handles environments where storage is unavailable (SSR, private mode).
  */
-export declare const storage: {
-    get<T>(key: string, fallback: T): T;
-    set<T>(key: string, value: T): void;
-    remove(key: string): void;
-};
+export declare const storage: JsonStorage;
+
+/** How a {@link createJsonStorage} store turns values into text and back. */
+export declare interface StorageCodec {
+    /** Encode a value for storage. */
+    serialize: <T>(value: T) => string;
+    /** Decode a stored string. */
+    deserialize: <T>(raw: string) => T;
+}
 
 /** Raw usage/quota reading from the Storage API, in bytes. */
 declare interface StorageEstimate_2 {
@@ -10863,6 +11028,16 @@ export declare interface SyncRunSummary {
     succeeded: number;
     /** Entries that failed and stay queued for the next run. */
     failed: number;
+    /**
+     * Entries left untried because an earlier entry for the **same record**
+     * failed this run.
+     *
+     * They stay queued and are attempted next run, in order. Counted apart from
+     * `failed` because they were never sent: reporting them as failures would
+     * blame the server for a decision this engine made, and folding them in would
+     * make `succeeded + failed` stop accounting for the queue.
+     */
+    deferred: number;
     /** Total wall-clock milliseconds the run took. */
     durationMs: number;
     /** `true` when the run was skipped because the device was offline. */
@@ -11768,6 +11943,23 @@ export declare interface TransferProps extends Omit<HTMLAttributes<HTMLDivElemen
 /** Which pane an operation is about. */
 export declare type TransferSide = "source" | "target";
 
+/** Per-call options for {@link I18n.t} and {@link I18n.plural}. */
+export declare interface TranslateOptions {
+    /**
+     * Text to use when the catalog defines neither the key nor its fallback.
+     *
+     * Without this, a miss returns the key, and a caller that wants its own text
+     * instead has to *detect* the miss — which from the outside means comparing
+     * the result against the key it just passed in. That heuristic is wrong for a
+     * catalog that legitimately maps a key to itself, and it is what every
+     * translatable string the SDK ships would otherwise have to copy.
+     *
+     * Interpolated like any other message, so a default carries `{placeholders}`
+     * too and is not second-class.
+     */
+    default?: string;
+}
+
 /**
  * Estimated travel between two coordinates. Mirrors the `TravelEstimate`
  * schema from `tempest-fastapi-sdk` (`geo/schemas.py`), snake_case preserved so
@@ -12426,7 +12618,8 @@ export declare interface UseClipboardResult {
  * which a counter held in state cannot do.
  *
  * The interval stops once it reaches zero instead of ticking forever behind a
- * clamp.
+ * clamp — `useInterval` pauses on a `null` delay, so reaching zero is what tears
+ * the timer down.
  *
  * @param durationMs - Length of the window.
  * @param startedAt - Epoch ms the window opened (`Date.now()` when it started).
@@ -12886,6 +13079,17 @@ export declare interface UseKeyboardShortcutOptions {
  * want to *call* — it hands back a callable with a stable identity, rather than
  * making every call site reach through `.current`.
  *
+ * **List the returned ref in your effect's dependencies.** It is a stable object,
+ * so the effect never re-runs because of it, but `react-hooks/exhaustive-deps`
+ * cannot prove that for a custom hook the way it does for a bare `useRef`.
+ * Listing it lets the rule verify the array instead of taking an omission on
+ * trust.
+ *
+ * **Not for holding the previous value.** The write happens during render, so
+ * `.current` is already the current value by the time any effect reads it. A hook
+ * that wants the value from the *previous* commit — `usePrevious` — needs the
+ * effect-based write, and swapping it for this would make it return the present.
+ *
  * @typeParam T - The tracked value.
  * @param value - The value to track. Written on every render.
  * @returns A stable ref whose `current` holds the latest `value`.
@@ -14098,7 +14302,9 @@ export declare interface UseSetResult<T> {
  * `volume` is tracked separately: changing it calls `setVolume` on the existing
  * pool rather than rebuilding it, which would throw away every clip the user
  * has already downloaded — exactly the cost the pool exists to avoid.
- * `baseUrl`, `voices` and `maxSources` are read once, at creation.
+ * `baseUrl`, `voices` and `maxSources` are read once, at creation. The options
+ * object is forwarded whole rather than rebuilt field by field, so a field added
+ * to {@link SfxPoolOptions} does not silently stop reaching the pool.
  *
  * @param options - Passed through to {@link createSfxPool}.
  * @returns A stable pool handle.
@@ -14316,12 +14522,15 @@ export declare interface UseSpeechRecognitionResult {
  * `callback` argument. Use to break dependency cycles in effects without
  * triggering re-runs when the callback identity changes.
  *
- * The assignment happens **during render** on purpose. Moving it into an effect
- * would satisfy the React Compiler rules but open a one-commit staleness window:
- * an effect declared before this hook's own effect, in the same commit, would call
- * the previous render's callback. This is a primitive other hooks build on, so a
- * subtle staleness here is worse than the rule violation. Prefer React's
+ * Built on {@link useLatestRef}, which owns the render-time assignment and the
+ * reason it is not an effect: an effect would satisfy the React Compiler rules
+ * but open a one-commit staleness window. What this adds is the callable with a
+ * stable identity, so callers do not reach through `.current`. Prefer React's
  * `useEffectEvent` once it ships as stable.
+ *
+ * The ref is listed as a dependency because it is one — a stable object across
+ * renders, so the returned identity never changes. Listing it is what lets the
+ * exhaustive-deps rule verify that instead of taking an empty array on trust.
  */
 export declare function useStableCallback<TArgs extends unknown[], TReturn>(callback: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
 
@@ -14472,6 +14681,11 @@ export declare function useTranslate(): I18nContextValue["t"];
  * Always give the reader a way out: an animation that cannot be skipped is a
  * tax on anyone re-reading or moving fast, which is what `skip` is for.
  *
+ * How far the reveal got is derived rather than stored: a `speedMs` of `0` reads
+ * as "all of it" without a state write, and `useInterval` pausing on a `null`
+ * delay is what stops the timer at the end. Both used to need an effect that
+ * cleared its own interval from inside a state updater.
+ *
  * @param text - The full string to reveal. Nullish is treated as empty.
  * @param speedMs - Delay between characters. `0` or less renders instantly,
  *   which is the hook-safe way to honour `prefers-reduced-motion`.