@joewinke/jatui 0.22.0 → 0.24.0

package/dist/components/batch/QuotaMeter.svelte

@@ -0,0 +1,78 @@
+<script lang="ts">
+	/**
+	 * QuotaMeter (jatui-m4uz3.7) — "312 / 500 generations · resets in 4h 10m".
+	 *
+	 * Purely presentational: the host owns the ledger and passes `used`/`limit`.
+	 * Bar tints warning at `warnAt` and error at 100%.
+	 */
+	import { formatElapsed } from './batchQueue';
+
+	interface Props {
+		used: number;
+		limit: number;
+		/** When the quota window resets — Date, ISO string, or epoch ms. */
+		resetsAt?: Date | string | number | null;
+		label?: string;
+		/** Unit noun shown after the numbers ("credits", "videos"). */
+		unit?: string;
+		/** Fraction (0..1) at which the bar turns warning. Default 0.8. */
+		warnAt?: number;
+		size?: 'xs' | 'sm' | 'md';
+		class?: string;
+	}
+
+	let {
+		used,
+		limit,
+		resetsAt = null,
+		label = 'Quota',
+		unit = '',
+		warnAt = 0.8,
+		size = 'sm',
+		class: className = ''
+	}: Props = $props();
+
+	const ratio = $derived(limit > 0 ? used / limit : 1);
+	const remaining = $derived(Math.max(0, limit - used));
+	const tone = $derived(ratio >= 1 ? 'progress-error' : ratio >= warnAt ? 'progress-warning' : 'progress-primary');
+	const textTone = $derived(ratio >= 1 ? 'text-error' : ratio >= warnAt ? 'text-warning' : 'text-base-content/60');
+
+	// Re-render the countdown once a minute; no ticking when there's no reset.
+	let now = $state(Date.now());
+	$effect(() => {
+		if (resetsAt == null) return;
+		const t = setInterval(() => (now = Date.now()), 60_000);
+		return () => clearInterval(t);
+	});
+
+	const resetLabel = $derived.by(() => {
+		if (resetsAt == null) return '';
+		const at = new Date(resetsAt).getTime();
+		if (!Number.isFinite(at)) return '';
+		const ms = at - now;
+		return ms <= 0 ? 'resets now' : `resets in ${formatElapsed(ms)}`;
+	});
+
+	const fmt = (n: number) => n.toLocaleString();
+	const sizeClass = { xs: 'h-1', sm: 'h-1.5', md: 'h-2.5' };
+</script>
+
+<div class="flex min-w-40 flex-col gap-1 {className}">
+	<div class="flex items-baseline justify-between gap-3 text-xs">
+		<span class="font-medium">{label}</span>
+		<span class="tabular-nums {textTone}">
+			{fmt(used)} / {fmt(limit)}{unit ? ` ${unit}` : ''}
+		</span>
+	</div>
+	<progress
+		class="progress w-full {tone} {sizeClass[size]}"
+		value={Math.min(used, limit)}
+		max={limit > 0 ? limit : 1}
+		aria-label="{label}: {fmt(used)} of {fmt(limit)}{unit ? ` ${unit}` : ''} used, {fmt(remaining)} left{resetLabel
+			? `, ${resetLabel}`
+			: ''}"
+	></progress>
+	{#if resetLabel}
+		<span class="text-base-content/50 text-2xs">{resetLabel}</span>
+	{/if}
+</div>

package/dist/components/batch/QuotaMeter.svelte.d.ts

@@ -0,0 +1,16 @@
+interface Props {
+    used: number;
+    limit: number;
+    /** When the quota window resets — Date, ISO string, or epoch ms. */
+    resetsAt?: Date | string | number | null;
+    label?: string;
+    /** Unit noun shown after the numbers ("credits", "videos"). */
+    unit?: string;
+    /** Fraction (0..1) at which the bar turns warning. Default 0.8. */
+    warnAt?: number;
+    size?: 'xs' | 'sm' | 'md';
+    class?: string;
+}
+declare const QuotaMeter: import("svelte").Component<Props, {}, "">;
+type QuotaMeter = ReturnType<typeof QuotaMeter>;
+export default QuotaMeter;

package/dist/components/batch/batchQueue.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Pure queue logic behind `BatchJobTable` (jatui-m4uz3.7).
+ *
+ * No DOM, no runes — the component owns the reactive `jobs` array and calls
+ * these to decide what to dispatch, reorder, and summarize. Kept separate so
+ * the scheduling rules are unit-testable under plain node:test.
+ */
+export type JobStatus = 'queued' | 'running' | 'done' | 'failed' | 'skipped' | 'cancelled';
+export interface JobRow<T> {
+    id: string;
+    /** Host payload — whatever the runner needs (prompt, file, params…). */
+    data: T;
+    status: JobStatus;
+    /** 0..1 while running, when the runner reports it. */
+    progress?: number;
+    /** Epoch ms of the current/last attempt's start. */
+    startedAt?: number;
+    /** Epoch ms of the current/last attempt's end. */
+    finishedAt?: number;
+    /** Number of attempts started so far. */
+    attempts: number;
+    error?: string;
+    result?: unknown;
+}
+export interface DispatchLimits {
+    /** Max jobs running at once. */
+    concurrencyLimit: number;
+    /** Max jobs to START in this run (e.g. a quota budget). `null`/undefined = unlimited. */
+    processLimit?: number | null;
+    /** Jobs already started in this run. */
+    startedThisRun: number;
+}
+/** Wrap host payloads as fresh queued rows. `idOf` defaults to a sequential id. */
+export declare function toJobRows<T>(items: T[], idOf?: (item: T, index: number) => string): JobRow<T>[];
+/** Ids of the queued jobs to start now, in table order, honoring both limits. */
+export declare function nextJobsToStart<T>(jobs: JobRow<T>[], limits: DispatchLimits): string[];
+/** True when the process limit (not the queue) is what stops further dispatch. */
+export declare function isProcessLimitReached<T>(jobs: JobRow<T>[], limits: DispatchLimits): boolean;
+/** Move a job `delta` places (−1 up, +1 down). Returns a new array; out-of-range is a no-op. */
+export declare function moveJob<T>(jobs: JobRow<T>[], id: string, delta: number): JobRow<T>[];
+export interface BatchSummary {
+    total: number;
+    queued: number;
+    running: number;
+    done: number;
+    failed: number;
+    skipped: number;
+    cancelled: number;
+    /** done + failed + skipped + cancelled. */
+    settled: number;
+    /** 0..1 — settled share of the batch, counting running jobs' partial progress. */
+    fraction: number;
+}
+export declare function summarizeJobs<T>(jobs: JobRow<T>[]): BatchSummary;
+/** "45s", "3m 07s", "1h 02m". Negative/NaN → "0s". */
+export declare function formatElapsed(ms: number): string;

package/dist/components/batch/batchQueue.js

@@ -0,0 +1,81 @@
+/**
+ * Pure queue logic behind `BatchJobTable` (jatui-m4uz3.7).
+ *
+ * No DOM, no runes — the component owns the reactive `jobs` array and calls
+ * these to decide what to dispatch, reorder, and summarize. Kept separate so
+ * the scheduling rules are unit-testable under plain node:test.
+ */
+/** Wrap host payloads as fresh queued rows. `idOf` defaults to a sequential id. */
+export function toJobRows(items, idOf) {
+    return items.map((data, i) => ({
+        id: idOf ? idOf(data, i) : `job-${i + 1}`,
+        data,
+        status: 'queued',
+        attempts: 0
+    }));
+}
+/** Ids of the queued jobs to start now, in table order, honoring both limits. */
+export function nextJobsToStart(jobs, limits) {
+    const running = jobs.filter((j) => j.status === 'running').length;
+    let slots = Math.max(0, Math.floor(limits.concurrencyLimit) - running);
+    if (limits.processLimit != null) {
+        slots = Math.min(slots, Math.max(0, limits.processLimit - limits.startedThisRun));
+    }
+    if (slots === 0)
+        return [];
+    return jobs
+        .filter((j) => j.status === 'queued')
+        .slice(0, slots)
+        .map((j) => j.id);
+}
+/** True when the process limit (not the queue) is what stops further dispatch. */
+export function isProcessLimitReached(jobs, limits) {
+    return (limits.processLimit != null &&
+        limits.startedThisRun >= limits.processLimit &&
+        jobs.some((j) => j.status === 'queued'));
+}
+/** Move a job `delta` places (−1 up, +1 down). Returns a new array; out-of-range is a no-op. */
+export function moveJob(jobs, id, delta) {
+    const from = jobs.findIndex((j) => j.id === id);
+    const to = from + delta;
+    if (from < 0 || to < 0 || to >= jobs.length || delta === 0)
+        return jobs;
+    const next = jobs.slice();
+    const [row] = next.splice(from, 1);
+    next.splice(to, 0, row);
+    return next;
+}
+export function summarizeJobs(jobs) {
+    const s = {
+        total: jobs.length,
+        queued: 0,
+        running: 0,
+        done: 0,
+        failed: 0,
+        skipped: 0,
+        cancelled: 0,
+        settled: 0,
+        fraction: 0
+    };
+    let partial = 0;
+    for (const j of jobs) {
+        s[j.status]++;
+        if (j.status === 'running')
+            partial += Math.min(1, Math.max(0, j.progress ?? 0));
+    }
+    s.settled = s.done + s.failed + s.skipped + s.cancelled;
+    s.fraction = s.total === 0 ? 0 : (s.settled + partial) / s.total;
+    return s;
+}
+/** "45s", "3m 07s", "1h 02m". Negative/NaN → "0s". */
+export function formatElapsed(ms) {
+    const total = Number.isFinite(ms) && ms > 0 ? Math.round(ms / 1000) : 0;
+    const h = Math.floor(total / 3600);
+    const m = Math.floor((total % 3600) / 60);
+    const s = total % 60;
+    if (h > 0)
+        return `${h}h ${String(m).padStart(2, '0')}m`;
+    if (m > 0)
+        return `${m}m ${String(s).padStart(2, '0')}s`;
+    return `${s}s`;
+}

package/dist/components/batch/elapsedEstimate.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Rolling-average ETA math (jatui-m4uz3.7). Pure — the `useElapsedEstimate`
+ * rune in `useElapsedEstimate.svelte.ts` wraps it with reactive state.
+ */
+export interface EtaInput {
+    /** Durations (ms) of finished jobs, oldest first. */
+    durations: number[];
+    /** Jobs still waiting to start. */
+    queued: number;
+    /** Elapsed ms of each currently running job. */
+    runningElapsed: number[];
+    /** Parallel workers. */
+    concurrency: number;
+    /** How many recent durations to average. Default 10. */
+    window?: number;
+}
+/** Mean of the last `window` durations, or null with no samples. */
+export declare function rollingAverage(durations: number[], window?: number): number | null;
+/**
+ * Estimated ms until the batch drains, or null until one job has finished.
+ * Running jobs contribute what's left of an average job (never negative);
+ * queued jobs a full average; total work is spread over the workers.
+ */
+export declare function estimateRemainingMs(input: EtaInput): number | null;

package/dist/components/batch/elapsedEstimate.js

@@ -0,0 +1,25 @@
+/**
+ * Rolling-average ETA math (jatui-m4uz3.7). Pure — the `useElapsedEstimate`
+ * rune in `useElapsedEstimate.svelte.ts` wraps it with reactive state.
+ */
+/** Mean of the last `window` durations, or null with no samples. */
+export function rollingAverage(durations, window = 10) {
+    const recent = durations.slice(-Math.max(1, window)).filter((d) => Number.isFinite(d) && d >= 0);
+    if (recent.length === 0)
+        return null;
+    return recent.reduce((a, b) => a + b, 0) / recent.length;
+}
+/**
+ * Estimated ms until the batch drains, or null until one job has finished.
+ * Running jobs contribute what's left of an average job (never negative);
+ * queued jobs a full average; total work is spread over the workers.
+ */
+export function estimateRemainingMs(input) {
+    const avg = rollingAverage(input.durations, input.window);
+    if (avg == null)
+        return null;
+    const running = input.runningElapsed.reduce((sum, e) => sum + Math.max(0, avg - e), 0);
+    const work = running + Math.max(0, input.queued) * avg;
+    const lanes = Math.max(1, Math.min(Math.floor(input.concurrency) || 1, input.queued + input.runningElapsed.length || 1));
+    return work / lanes;
+}

package/dist/components/batch/pollOperation.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Promise poller for long-running remote operations (jatui-m4uz3.7) — the
+ * "submit, then poll /status until done" loop every generation API needs.
+ *
+ *   const video = await pollOperation(
+ *     async ({ signal }) => {
+ *       const op = await fetch(`/api/ops/${id}`, { signal }).then((r) => r.json());
+ *       return op.done ? { done: true, value: op.result } : { done: false, progress: op.pct / 100 };
+ *     },
+ *     { intervalMs: 2000, timeoutMs: 600_000, signal, onProgress: (p) => reportProgress(p) }
+ *   );
+ *
+ * Rejects with `PollTimeoutError` on timeout, the signal's reason on abort,
+ * and whatever `check` throws (a thrown check is a failed operation, not a
+ * retry — wrap it yourself if transient errors should be swallowed).
+ */
+export type PollStep<T> = {
+    done: true;
+    value: T;
+} | {
+    done: false;
+    progress?: number;
+};
+export interface PollContext {
+    /** 1-based attempt number. */
+    attempt: number;
+    signal: AbortSignal;
+}
+export interface PollOptions {
+    /** Delay between checks. Default 2000. */
+    intervalMs?: number;
+    /** Give up after this many ms in total. Default: never. */
+    timeoutMs?: number;
+    /** Multiply the interval by this after each check (capped by maxIntervalMs). Default 1. */
+    backoff?: number;
+    maxIntervalMs?: number;
+    signal?: AbortSignal;
+    /** Fires after every not-done check. `progress` is whatever the check reported. */
+    onProgress?: (progress: number | undefined, attempt: number) => void;
+}
+export declare class PollTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+export declare function pollOperation<T>(check: (ctx: PollContext) => Promise<PollStep<T>> | PollStep<T>, opts?: PollOptions): Promise<T>;

package/dist/components/batch/pollOperation.js

@@ -0,0 +1,80 @@
+/**
+ * Promise poller for long-running remote operations (jatui-m4uz3.7) — the
+ * "submit, then poll /status until done" loop every generation API needs.
+ *
+ *   const video = await pollOperation(
+ *     async ({ signal }) => {
+ *       const op = await fetch(`/api/ops/${id}`, { signal }).then((r) => r.json());
+ *       return op.done ? { done: true, value: op.result } : { done: false, progress: op.pct / 100 };
+ *     },
+ *     { intervalMs: 2000, timeoutMs: 600_000, signal, onProgress: (p) => reportProgress(p) }
+ *   );
+ *
+ * Rejects with `PollTimeoutError` on timeout, the signal's reason on abort,
+ * and whatever `check` throws (a thrown check is a failed operation, not a
+ * retry — wrap it yourself if transient errors should be swallowed).
+ */
+export class PollTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`Operation did not finish within ${timeoutMs}ms`);
+        this.timeoutMs = timeoutMs;
+        this.name = 'PollTimeoutError';
+    }
+}
+function abortReason(signal) {
+    return signal.reason ?? new DOMException('Polling aborted', 'AbortError');
+}
+export function pollOperation(check, opts = {}) {
+    const { intervalMs = 2000, timeoutMs, backoff = 1, maxIntervalMs = Infinity, onProgress } = opts;
+    const outer = opts.signal;
+    // Internal controller: aborts in-flight checks on timeout or outer abort.
+    const ctrl = new AbortController();
+    return new Promise((resolve, reject) => {
+        let timer;
+        let deadline;
+        let settled = false;
+        const finish = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            clearTimeout(deadline);
+            outer?.removeEventListener('abort', onAbort);
+            fn();
+        };
+        const onAbort = () => {
+            const reason = abortReason(outer);
+            ctrl.abort(reason);
+            finish(() => reject(reason));
+        };
+        if (outer?.aborted)
+            return onAbort();
+        outer?.addEventListener('abort', onAbort, { once: true });
+        if (timeoutMs != null) {
+            deadline = setTimeout(() => {
+                const err = new PollTimeoutError(timeoutMs);
+                ctrl.abort(err);
+                finish(() => reject(err));
+            }, timeoutMs);
+        }
+        let delay = intervalMs;
+        const tick = async (attempt) => {
+            let step;
+            try {
+                step = await check({ attempt, signal: ctrl.signal });
+            }
+            catch (err) {
+                return finish(() => reject(err));
+            }
+            if (settled)
+                return;
+            if (step.done)
+                return finish(() => resolve(step.value));
+            onProgress?.(step.progress, attempt);
+            timer = setTimeout(() => tick(attempt + 1), delay);
+            delay = Math.min(maxIntervalMs, delay * backoff);
+        };
+        tick(1);
+    });
+}

package/dist/components/batch/useElapsedEstimate.d.ts

@@ -0,0 +1,10 @@
+export interface ElapsedEstimate {
+    readonly averageMs: number | null;
+    readonly samples: number;
+    record(durationMs: number): void;
+    reset(): void;
+    remainingMs(queued: number, runningElapsed: number[], concurrency: number): number | null;
+}
+export declare function useElapsedEstimate(opts?: {
+    window?: number;
+}): ElapsedEstimate;

package/dist/components/batch/useElapsedEstimate.js

@@ -0,0 +1,38 @@
+/* useElapsedEstimate.svelte.js generated by Svelte v5.53.11 */
+import * as $ from 'svelte/internal/client';
+import { estimateRemainingMs, rollingAverage } from './elapsedEstimate';
+
+export function useElapsedEstimate(opts = {}) {
+	const window = opts.window ?? 10;
+	let durations = $.state($.proxy([]));
+	const averageMs = $.derived(() => rollingAverage($.get(durations), window));
+
+	return {
+		get averageMs() {
+			return $.get(averageMs);
+		},
+
+		get samples() {
+			return $.get(durations).length;
+		},
+
+		record(durationMs) {
+			// Only the window matters — keep the array bounded.
+			$.set(durations, [...$.get(durations), durationMs].slice(-window), true);
+		},
+
+		reset() {
+			$.set(durations, [], true);
+		},
+
+		remainingMs(queued, runningElapsed, concurrency) {
+			return estimateRemainingMs({
+				durations: $.get(durations),
+				queued,
+				runningElapsed,
+				concurrency,
+				window
+			});
+		}
+	};
+}

package/dist/components/bulkActionBarKeys.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pure hotkey resolution for `BulkActionBar` (jatui-is2ow.6) — ported from
+ * the IDE's fork (`ide/src/lib/components/BulkActionBar.svelte`, audit
+ * jat-1alfp row 15).
+ *
+ * The IDE fork keeps key handling in the host page; here it lives in the
+ * component, but the DECIDING logic is this pure function so it can be
+ * unit-tested without a DOM. The component's keydown handler calls
+ * `matchBulkHotkey(event, actions)` and invokes the returned action's
+ * `onSelect`.
+ *
+ * Rules (mirroring the shortcut registry's sharp edges):
+ *  - single printable keys only (`event.key.length === 1`) — an action
+ *    declaring a multi-char `key` is never matched;
+ *  - matched case-insensitively (`'C'` on the action fires on `'c'`);
+ *  - ignored while the focus is in a text entry target (`isTypingTarget`);
+ *  - ignored for modifier combos (Ctrl/⌘/Alt) and already-handled events.
+ */
+/** The subset of `BulkAction` the resolver needs. */
+export interface BulkHotkeyAction {
+    /** Single-key binding (e.g. 'c'). Multi-char values never match. */
+    key?: string;
+    /** Click handler — fired by the component when the hotkey matches. */
+    onSelect: () => void;
+}
+/** Minimal structural subset of `KeyboardEvent` — real events satisfy it. */
+export interface BulkHotkeyEvent {
+    key: string;
+    target: EventTarget | null;
+    defaultPrevented?: boolean;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    altKey?: boolean;
+}
+/**
+ * Resolve a keydown to the bulk action whose single-key binding matches,
+ * or return null when the event must not fire a hotkey (typing target,
+ * modifier combo, defaultPrevented, non-printable key, no match).
+ */
+export declare function matchBulkHotkey(event: BulkHotkeyEvent, actions: readonly BulkHotkeyAction[]): BulkHotkeyAction | null;

package/dist/components/bulkActionBarKeys.js

@@ -0,0 +1,38 @@
+/**
+ * Pure hotkey resolution for `BulkActionBar` (jatui-is2ow.6) — ported from
+ * the IDE's fork (`ide/src/lib/components/BulkActionBar.svelte`, audit
+ * jat-1alfp row 15).
+ *
+ * The IDE fork keeps key handling in the host page; here it lives in the
+ * component, but the DECIDING logic is this pure function so it can be
+ * unit-tested without a DOM. The component's keydown handler calls
+ * `matchBulkHotkey(event, actions)` and invokes the returned action's
+ * `onSelect`.
+ *
+ * Rules (mirroring the shortcut registry's sharp edges):
+ *  - single printable keys only (`event.key.length === 1`) — an action
+ *    declaring a multi-char `key` is never matched;
+ *  - matched case-insensitively (`'C'` on the action fires on `'c'`);
+ *  - ignored while the focus is in a text entry target (`isTypingTarget`);
+ *  - ignored for modifier combos (Ctrl/⌘/Alt) and already-handled events.
+ */
+import { isTypingTarget } from '../utils/keyboardShortcutRegistry';
+/**
+ * Resolve a keydown to the bulk action whose single-key binding matches,
+ * or return null when the event must not fire a hotkey (typing target,
+ * modifier combo, defaultPrevented, non-printable key, no match).
+ */
+export function matchBulkHotkey(event, actions) {
+    if (event.defaultPrevented)
+        return null;
+    if (event.ctrlKey || event.metaKey || event.altKey)
+        return null;
+    if (isTypingTarget(event.target))
+        return null;
+    // Single printable keys only — 'Escape', 'ArrowDown', 'Enter' etc. are
+    // navigation keys owned by listNav and must never trigger a bulk action.
+    if (!event.key || event.key.length !== 1)
+        return null;
+    const wanted = event.key.toLowerCase();
+    return (actions.find((a) => a.key && a.key.length === 1 && a.key.toLowerCase() === wanted) ?? null);
+}

package/dist/components/infiniteGridLoader.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Cursor-paged loader behind InfiniteGrid / InfiniteSearchGrid (jatui-m4uz3.4).
+ *
+ * Ported from chimaro's InfiniteMediaGrid/InfiniteSearchGrid, where the paging
+ * machinery was welded to Supabase + media types. This is the machinery alone,
+ * DOM-free and framework-free so it can be unit-tested under node:test:
+ *
+ *   - ONE request in flight per generation (the fast-scroll double-fire guard —
+ *     an IntersectionObserver can call back twice before `loading` flips).
+ *   - `reset()` bumps a generation and aborts the in-flight request. A response
+ *     that lands for an older generation is DROPPED, so a slow page for query
+ *     "ca" can never be appended under the results for "cat" (the cursor race).
+ *   - Items are de-duplicated by key across pages (offset paging over a list
+ *     that grew between requests re-sends rows).
+ *   - Empty and exhausted are distinct states: `empty` = done with zero items,
+ *     `exhausted` = done with some. A page that returns no items AND repeats the
+ *     cursor it was given is treated as the end, never as "try again".
+ *   - A failed page parks in `error`; nothing auto-retries (the observer would
+ *     hammer a dead endpoint). `retry()` re-requests the same cursor.
+ */
+export interface InfinitePage<T, C> {
+    items: T[];
+    /** Cursor for the next page; `null` (or undefined) means there is no next page. */
+    nextCursor?: C | null;
+    /** Optional total row count, surfaced in the end-of-list footer. */
+    total?: number;
+}
+export interface InfiniteLoadContext {
+    /** Aborted when the grid resets (query/filter change) or unmounts. */
+    signal: AbortSignal;
+}
+export type InfiniteLoadFn<T, C> = (cursor: C | null, ctx: InfiniteLoadContext) => Promise<InfinitePage<T, C>>;
+export type InfiniteStatus = 'idle' | 'loading' | 'error' | 'done';
+export interface InfiniteLoaderState<T, C> {
+    items: T[];
+    status: InfiniteStatus;
+    /** Cursor the NEXT load will send (`null` before the first page). */
+    cursor: C | null;
+    /** True once at least one page has settled for the current generation. */
+    initialized: boolean;
+    /** status 'done' with zero items. */
+    empty: boolean;
+    /** status 'done' with at least one item. */
+    exhausted: boolean;
+    error: unknown;
+    total: number | undefined;
+    /** Bumps on every reset; stale responses carry an older value and are dropped. */
+    generation: number;
+    /** Items appended by the most recent page (for a live-region announcement). */
+    lastPageCount: number;
+}
+export interface InfiniteLoaderOptions<T, C> {
+    load: InfiniteLoadFn<T, C>;
+    getKey?: (item: T) => unknown;
+    onChange?: (state: InfiniteLoaderState<T, C>) => void;
+}
+export interface InfiniteLoader<T, C> {
+    readonly state: InfiniteLoaderState<T, C>;
+    /** Fetch the next page. No-op while loading, done, or errored. Resolves when settled. */
+    loadNext(): Promise<void>;
+    /** Re-request the page that failed. No-op unless status is 'error'. */
+    retry(): Promise<void>;
+    /** Drop everything, abort in flight, start a new generation (does not fetch). */
+    reset(): void;
+    /** Swap the fetcher (e.g. a new query closure) — call reset() after. */
+    setLoad(load: InfiniteLoadFn<T, C>): void;
+    /** Abort in flight and stop emitting. */
+    destroy(): void;
+}
+export declare function createInfiniteLoader<T, C = unknown>(opts: InfiniteLoaderOptions<T, C>): InfiniteLoader<T, C>;