@belonguniverseai/react-sdk 0.1.0

package/dist/stream/belong-data-parts.d.ts

@@ -0,0 +1,207 @@
+import { UIMessage } from 'ai';
+/**
+ * F2 — per-step execution status. Optional: absent means `pending`
+ * (back-compat with plans proposed before F2 and the initial propose). The
+ * pinned plan renders a status icon per step and a "k/N done" header once any
+ * step has a non-pending status.
+ */
+export type PlanStepStatus = "pending" | "in_progress" | "completed" | "failed";
+export type PlanStep = {
+    readonly id: string;
+    readonly title: string;
+    readonly kind: string;
+    readonly status?: PlanStepStatus | undefined;
+};
+export type ApprovalState = "pending" | "approved" | "rejected" | "amend_requested" | "expired";
+export type ToolCallState = "started" | "completed" | "failed";
+export type ChoiceState = "pending" | "resolved" | "expired";
+export type SandboxCommandState = "started" | "output" | "completed" | "failed";
+export type SandboxStream = "stdout" | "stderr";
+export type UiActionState = "requested" | "completed" | "failed";
+export type RunStatusKind = "continuing" | "completed" | "cancelled" | "failed" | "throttled";
+export type ReasoningData = {
+    readonly delta: string;
+};
+export type PlanData = {
+    readonly title: string;
+    readonly summary: string;
+    readonly steps: readonly PlanStep[];
+};
+export type ApprovalRequestData = {
+    readonly approvalId: string;
+    readonly reason: string;
+    readonly state: ApprovalState;
+    /**
+     * Optional tool name for the "Always allow" consent checkbox label.
+     * When absent: "Always allow this action".
+     * When present: "Always allow <toolName>".
+     * Added by the backend in a parallel branch — may be absent on older wire
+     * messages; render the generic label when undefined.
+     */
+    readonly toolName?: string | undefined;
+};
+/**
+ * BEL-93 — a friendly question widget the agent emits instead of dumping a wall
+ * of questions as prose. Discriminated on `mode`:
+ *   - "single": choose exactly one option (radio group)
+ *   - "multi":  choose several options (checkbox list), bounded by
+ *               min/maxChoicesCount when present
+ *   - "open":   free-text answer (textarea)
+ * The user answers in-dock; the SDK posts the answer back through the same
+ * `ui-actions/:uiActionRequestId/result` endpoint the UI-action renderer uses,
+ * so no new backend route is needed. `state` mirrors the approval lifecycle
+ * (see ChoiceState) so a resolved/expired question survives a reload.
+ */
+export type ChoiceOption = {
+    readonly id: string;
+    readonly label: string;
+    readonly description?: string | undefined;
+};
+export type ChoiceRequestData = {
+    readonly mode: "single";
+    readonly uiActionRequestId: string;
+    readonly question: string;
+    readonly options: readonly ChoiceOption[];
+    readonly state: ChoiceState;
+} | {
+    readonly mode: "multi";
+    readonly uiActionRequestId: string;
+    readonly question: string;
+    readonly options: readonly ChoiceOption[];
+    readonly state: ChoiceState;
+    /** Inclusive lower bound on selected options. Absent ⇒ at least one (1). */
+    readonly minChoicesCount?: number | undefined;
+    /** Inclusive upper bound on selected options. Absent ⇒ no maximum. */
+    readonly maxChoicesCount?: number | undefined;
+} | {
+    readonly mode: "open";
+    readonly uiActionRequestId: string;
+    readonly question: string;
+    readonly state: ChoiceState;
+    readonly placeholder?: string | undefined;
+};
+/**
+ * Optional fields declared with explicit `| undefined` so Zod's
+ * `.optional()` output (which produces `T | undefined`) lines up with
+ * `exactOptionalPropertyTypes: true`.
+ */
+/**
+ * BEL-97 — distinguishes an ordinary tool/command failure (a non-zero exit, a
+ * tool that couldn't complete) from one that STOPS the agent run (a denied
+ * permission, an aborting failure). Only `"stop"` warrants the red/destructive
+ * treatment; an ordinary `"error"` gets the amber notice treatment so red is
+ * reserved for "the agent can't continue". Absent → `"error"` (the common,
+ * recoverable case; back-compat with wire messages emitted before BEL-97).
+ */
+export type ToolErrorSeverity = "error" | "stop";
+export type ToolCallData = {
+    readonly toolName: string;
+    readonly state: ToolCallState;
+    readonly input?: Readonly<Record<string, unknown>> | undefined;
+    readonly output?: Readonly<Record<string, unknown>> | null | undefined;
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+        readonly severity?: ToolErrorSeverity | undefined;
+    } | undefined;
+};
+export type SandboxCommandData = {
+    readonly state: SandboxCommandState;
+    readonly stream?: SandboxStream | undefined;
+    readonly delta?: string | undefined;
+    /**
+     * Monotonic event seq of THIS delta (live wire only; absent on folded
+     * history parts). Same-id data parts replace each other in useChat, so the
+     * renderer needs a marker to apply each delta exactly once — object
+     * identity churns on every unrelated stream chunk and is NOT a signal.
+     */
+    readonly seq?: number | undefined;
+    readonly exitCode?: number | undefined;
+};
+export type UiActionData = {
+    readonly uiActionRequestId: string;
+    readonly actionName: string;
+    readonly state: UiActionState;
+    readonly args?: Readonly<Record<string, unknown>> | undefined;
+};
+/**
+ * BEL-79 reactive reconnect: the agent's `reconnect_cli` tool emits this when a
+ * delegated-CLI session lapsed mid-run. The dock re-grants it — silently in Auto
+ * mode, a Reconnect prompt otherwise — while the backend tool blocks for the
+ * fresh grant. Provider + scope say WHAT to reconnect.
+ */
+export type CliReconnectData = {
+    readonly provider: string;
+    readonly scopeExternalId: string;
+};
+export type NavigationData = {
+    readonly routeName: string;
+    readonly params: Readonly<Record<string, string>>;
+};
+export type ArtifactData = {
+    readonly artifactId: string;
+    readonly title: string;
+    readonly mimeType: string;
+};
+export type StatusData = {
+    readonly status: RunStatusKind;
+    readonly message?: string | undefined;
+};
+/**
+ * F3 — per-turn token usage + compaction context. Emitted once per turn at
+ * the end of the stream; the SDK renders the quiet context meter from this.
+ * `historyChars / autoCompactThresholdChars` gives compaction proximity;
+ * `threshold === 0` means no auto-compact is configured — hide the meter.
+ */
+export type UsageData = {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly totalTokens: number;
+    readonly historyChars: number;
+    readonly autoCompactThresholdChars: number;
+};
+/**
+ * Single source of truth for Belong's custom data parts. The record
+ * keys (`reasoning`, `plan`, …) become the part-type suffix:
+ * `BelongDataParts["reasoning"]` is the `data` payload of a
+ * `data-reasoning` part.
+ */
+export type BelongDataParts = {
+    reasoning: ReasoningData;
+    plan: PlanData;
+    "approval-request": ApprovalRequestData;
+    "choice-request": ChoiceRequestData;
+    "tool-call": ToolCallData;
+    "sandbox-command": SandboxCommandData;
+    "ui-action": UiActionData;
+    "cli-reconnect": CliReconnectData;
+    navigation: NavigationData;
+    artifact: ArtifactData;
+    status: StatusData;
+    /** F3 — context/cost meter. Additive; absent on old sessions. */
+    usage: UsageData;
+};
+/**
+ * The concrete `UIMessage` shape the chat surface and transport speak.
+ * Metadata is typed `unknown` and read defensively at use sites (e.g. the
+ * user-bubble skill chip reads `metadata.skill` via a narrowing guard) — keep
+ * it `unknown` so new metadata fields need no type-plumbing changes.
+ */
+export type BelongUIMessage = UIMessage<unknown, BelongDataParts>;
+/**
+ * Wire shape emitted by belong-cloud's SSE adapter. This stays as a
+ * separate union because the server side has not migrated to AI-SDK
+ * chunks yet — the transport translates this into `UIMessageChunk`.
+ */
+export type WireTextPart = {
+    readonly type: "text";
+    readonly id: string;
+    readonly text: string;
+};
+export type WireDataPart<NAME extends keyof BelongDataParts> = {
+    readonly type: `data-${NAME & string}`;
+    readonly id: string;
+    readonly data: BelongDataParts[NAME];
+};
+export type WireStreamPart = WireTextPart | WireDataPart<"reasoning"> | WireDataPart<"plan"> | WireDataPart<"approval-request"> | WireDataPart<"choice-request"> | WireDataPart<"tool-call"> | WireDataPart<"sandbox-command"> | WireDataPart<"ui-action"> | WireDataPart<"cli-reconnect"> | WireDataPart<"navigation"> | WireDataPart<"artifact"> | WireDataPart<"status"> | WireDataPart<"usage">;
+export type WireStreamPartType = WireStreamPart["type"];

package/dist/stream/chat-upload.d.ts

@@ -0,0 +1,35 @@
+import { FileUIPart } from 'ai';
+/** Normalise to the server's allow-list by extension (browsers report .md/.csv inconsistently). */
+export declare const resolveMimeType: (file: File) => string;
+/** Upload one file to the server, returning its fileId (or null on failure). */
+export declare const uploadOneFile: (apiBaseUrl: string, file: File) => Promise<string | null>;
+/**
+ * Bridge the PromptInput's `file` parts (data-url FileUIParts) to the
+ * upload-first wire: upload each, in order, and return the server fileIds.
+ * Throws on any failure so the composer keeps the draft + attachments for a
+ * retry instead of clearing.
+ */
+export declare const uploadFiles: (apiBaseUrl: string, files: readonly FileUIPart[]) => Promise<readonly string[]>;
+/**
+ * A `FileUIPart` extended with the server-assigned fileId in `providerMetadata`
+ * so the attachment chip can open a preview without re-uploading, even after a
+ * page reload (§41). The field is carried through the AI SDK message history
+ * because `FileUIPart.providerMetadata` is a plain `Record<string, JSONObject>`.
+ */
+export type UploadedFilePart = FileUIPart & {
+    providerMetadata: {
+        belong: {
+            fileId: string;
+        };
+    };
+};
+/**
+ * Like `uploadFiles` but also returns each `FileUIPart` annotated with the
+ * server `fileId` via `providerMetadata.belong.fileId`. The annotated parts
+ * are passed as `files` to `sendMessage` so the optimistic message (and any
+ * replay from history) carries the id the chip needs to open a preview.
+ */
+export declare const uploadFilesWithParts: (apiBaseUrl: string, files: readonly FileUIPart[]) => Promise<{
+    fileIds: readonly string[];
+    parts: readonly UploadedFilePart[];
+}>;

package/dist/stream/plan-panel-store.d.ts

@@ -0,0 +1,11 @@
+/** Default panel width when none persisted. */
+export declare const DEFAULT_PLAN_PANEL_WIDTH_PX = 420;
+export type PlanPanelState = {
+    readonly open: boolean;
+    readonly widthPx: number;
+};
+export declare const peekPlanPanelState: () => PlanPanelState;
+export declare const subscribePlanPanelState: (listener: () => void) => (() => void);
+export declare const setPlanPanelOpen: (open: boolean) => void;
+export declare const togglePlanPanelOpen: () => void;
+export declare const setPlanPanelWidth: (widthPx: number) => void;

package/dist/stream/plan-progress-store.d.ts

@@ -0,0 +1,4 @@
+import { PlanProgress } from './plan-progress.ts';
+export declare const publishPlanProgress: (progress: PlanProgress | null) => void;
+export declare const peekPlanProgress: () => PlanProgress | null;
+export declare const subscribePlanProgress: (listener: () => void) => (() => void);

package/dist/stream/plan-progress.d.ts

@@ -0,0 +1,25 @@
+import { PlanData, PlanStep, PlanStepStatus } from './belong-data-parts.ts';
+export type PlanProgress = {
+    readonly total: number;
+    /** Steps with status `completed` (failed steps are terminal but not "done"). */
+    readonly completed: number;
+    /** The first `in_progress` step, or null between steps / when idle. */
+    readonly current: PlanStep | null;
+    /** The first `failed` step, or null. */
+    readonly failed: PlanStep | null;
+    readonly executing: boolean;
+    readonly finished: boolean;
+};
+/** A step's effective status: absent or unknown wire values read as pending. */
+export declare const effectiveStepStatus: (step: PlanStep) => PlanStepStatus;
+/**
+ * One-line executing/finished label shared by PlanView (pill) and PlanCue
+ * (cue line):
+ *  - while a step is in progress: "Step k of N — <current title>"
+ *  - all steps terminal:           "k of N done"
+ *
+ * Callers are responsible for guarding the idle case (no executing/finished)
+ * before calling this helper.
+ */
+export declare const planStepLabel: (progress: PlanProgress) => string;
+export declare const planProgress: (plan: PlanData | null) => PlanProgress | null;

package/dist/stream/plan-store.d.ts

@@ -0,0 +1,16 @@
+import { PlanData } from './belong-data-parts.ts';
+import { PlanProgress } from './plan-progress.ts';
+export type PlanState = {
+    readonly plan: PlanData;
+    readonly planKey: string;
+    readonly streaming: boolean;
+    readonly progress: PlanProgress | null;
+    /** The user has already approved/rejected THIS plan (handlers no-op). */
+    readonly decided: boolean;
+    readonly onRun: () => void;
+    readonly onReject: () => void;
+    readonly onFailedHelp: () => void;
+};
+export declare const publishPlanState: (next: PlanState | null) => void;
+export declare const peekPlanState: () => PlanState | null;
+export declare const subscribePlanState: (listener: () => void) => (() => void);

package/dist/stream/preview-panel-store.d.ts

@@ -0,0 +1,50 @@
+/**
+ * In-process store for the artifact PREVIEW panel — its open state, the target
+ * being previewed, the docked width, and the fullscreen toggle.
+ *
+ * A published artifact (chat `data-artifact` card) and a workspace file (the
+ * documents tab's file tree) both open the SAME left-docked preview surface;
+ * the two call sites live across the BelongDock ↔ kept-alive-ChatRoute / routed
+ * documents boundary, so a shared module store (read via `useSyncExternalStore`)
+ * is the single toggle both write — no prop-drilling. Modelled on
+ * `plan-panel-store.ts`.
+ *
+ * Persistence: only the user's size + fullscreen PREFERENCES persist (so the
+ * panel reopens at the same size). `open`/`target` are deliberately ephemeral —
+ * they reset to closed on load, so a stale artifact from a prior conversation
+ * never auto-reopens (a preview is a user-initiated drill-in, not run state).
+ */
+/** Default docked width when none persisted. Wider than the plan panel — an
+ *  interactive HTML deliverable reads better with room. Fullscreen covers more. */
+export declare const DEFAULT_PREVIEW_PANEL_WIDTH_PX = 480;
+/**
+ * What the panel is previewing. A published artifact is fetched by id; a
+ * workspace file by its workspace-relative path. Both resolve to an auth'd
+ * bytes URL in `PreviewPanel`.
+ */
+export type PreviewTarget = {
+    readonly kind: "artifact";
+    readonly artifactId: string;
+    readonly title: string;
+    readonly mimeType: string;
+} | {
+    readonly kind: "workspace";
+    readonly path: string;
+    readonly title: string;
+    readonly mimeType: string;
+};
+export type PreviewPanelState = {
+    readonly open: boolean;
+    readonly widthPx: number;
+    readonly fullscreen: boolean;
+    readonly target: PreviewTarget | null;
+};
+export declare const peekPreviewPanelState: () => PreviewPanelState;
+export declare const subscribePreviewPanelState: (listener: () => void) => (() => void);
+/** Open the panel on a target (or swap the target while already open). */
+export declare const openPreview: (target: PreviewTarget) => void;
+/** Close the panel; the size/fullscreen preferences are kept. */
+export declare const closePreview: () => void;
+export declare const setPreviewWidth: (widthPx: number) => void;
+export declare const setPreviewFullscreen: (fullscreen: boolean) => void;
+export declare const togglePreviewFullscreen: () => void;

package/dist/stream/sandbox-output.d.ts

@@ -0,0 +1,32 @@
+import { SandboxCommandData, ToolCallData } from './belong-data-parts.ts';
+/** The shell tools across runtimes; both carry `input.command` + `output.exitCode`. */
+export declare const SHELL_TOOL_NAMES: ReadonlySet<string>;
+export declare const isShellToolName: (toolName: string) => boolean;
+/**
+ * BEL-97 — how a finished shell command's outcome should be coloured.
+ *
+ *   - `"none"`   — still running, or completed cleanly (exit 0 / no exit code).
+ *   - `"notice"` — an ORDINARY failure (non-zero exit, or a tool error with no
+ *                  stop-severity). Amber, NOT red: the agent kept going.
+ *   - `"stop"`   — an agent-execution-STOPPING failure (a denied permission, an
+ *                  aborting error: `error.severity === "stop"`). Red.
+ *
+ * One source of truth shared by `TerminalTask` (its status badge) and the
+ * consolidated terminal group (its aggregate failure badge).
+ */
+export type TerminalSeverity = "none" | "notice" | "stop";
+export declare const terminalCommandSeverity: (command: ToolCallData) => TerminalSeverity;
+/** Apply-once dedupe key for a sandbox delta (folded history parts → "folded"). */
+export declare const sandboxDeltaKey: (data: SandboxCommandData) => string;
+/** Sort order for merging deltas: the folded full-text part precedes any live seq. */
+export declare const sandboxDeltaOrder: (data: SandboxCommandData) => number;
+/**
+ * Accumulate a sandbox part's streamed deltas into one string across
+ * re-renders, applying each delta exactly once by {@link sandboxDeltaKey}.
+ *
+ * Deliberately `useLayoutEffect` (not `useEffect`): it runs synchronously after
+ * DOM mutations, so the flushSync-based test harness observes the accumulated
+ * text within the same render flush. In production it's equally correct — it
+ * runs before paint, so streamed output never renders a frame late.
+ */
+export declare const useSandboxOutputText: (output: SandboxCommandData | null) => string;

package/dist/stream/select-latest-plan.d.ts

@@ -0,0 +1,17 @@
+import { BelongUIMessage, PlanData } from './belong-data-parts.ts';
+export type LatestPlanEntry = {
+    readonly plan: PlanData;
+    /** Id of the (assistant) message carrying the plan part. */
+    readonly messageId: string;
+    /** Stable identity for "this proposal" — survives re-renders and reloads. */
+    readonly key: string;
+};
+export declare const selectLatestPlanEntry: (messages: readonly BelongUIMessage[]) => LatestPlanEntry | null;
+export declare const selectLatestPlan: (messages: readonly BelongUIMessage[]) => PlanData | null;
+/**
+ * True when the user has already answered the latest proposal: a message with
+ * role "user" appears AFTER the assistant message carrying the plan. Derived
+ * from message order (not in-memory flags) so it survives a reload — history
+ * restores the decision turn (§12 local reasoning, §41 no visual drift).
+ */
+export declare const isPlanDecided: (messages: readonly BelongUIMessage[], planEntry: LatestPlanEntry) => boolean;

package/dist/stream/select-session-usage.d.ts

@@ -0,0 +1,23 @@
+import { BelongUIMessage } from './belong-data-parts.ts';
+export type SessionUsageSummary = {
+    /** Sum of all per-turn input tokens. */
+    readonly totalInputTokens: number;
+    /** Sum of all per-turn output tokens. */
+    readonly totalOutputTokens: number;
+    /** Sum of all per-turn combined tokens. */
+    readonly totalTokens: number;
+    /** How many turns have reported usage. */
+    readonly turns: number;
+    /**
+     * Character count of the compactable history at the time of the most
+     * recent `data-usage` part (last-wins). Used for proximity:
+     *   `pct = min(100, round(historyChars / autoCompactThresholdChars * 100))`.
+     */
+    readonly historyChars: number;
+    /**
+     * Auto-compact threshold in chars (last-wins). 0 means auto-compact is
+     * not configured — the meter must be hidden when this is 0.
+     */
+    readonly autoCompactThresholdChars: number;
+};
+export declare const selectSessionUsage: (messages: readonly BelongUIMessage[]) => SessionUsageSummary | null;

package/dist/stream/session-title.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Derive a human-readable session title from the first user message.
+ *
+ * Sessions are created lazily by the transport on the first message
+ * (`#createSession`), so that message text is the only signal available at
+ * creation time. Seeding the title from it gives the Chats switcher
+ * distinguishable rows instead of a list of identical "Untitled chat"
+ * entries. Pure + deterministic, so it unit-tests without a DOM.
+ *
+ *   - collapse runs of whitespace/newlines to single spaces
+ *   - trim
+ *   - truncate to MAX_TITLE_CHARS, appending an ellipsis when cut
+ *   - empty input → null (the caller omits `title`; the server stores null)
+ */
+export declare const deriveSessionTitle: (text: string) => string | null;

package/dist/stream/stream-state-store.d.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod';
+declare const streamStateSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    /**
+     * Active run id, or null once the run reached a terminal state. The session
+     * pointer outlives the run: it survives on terminal so a reload can still
+     * restore this conversation's history — only the run cursor is dropped so we
+     * never reconnect to a finished run.
+     */
+    runId: z.ZodNullable<z.ZodString>;
+    /** `<seq>-0` SSE cursor, or null when no event has been seen yet. */
+    lastEventId: z.ZodNullable<z.ZodString>;
+    /**
+     * Epoch ms of the last cursor write. Resume is only attempted for
+     * recently-touched runs (see {@link readResumableStreamState}). State
+     * written by an older SDK build has no `updatedAt`, fails this schema, and
+     * is treated as absent — which is exactly the "start fresh" behavior we
+     * want for stale leftovers from a previous visit.
+     */
+    updatedAt: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    updatedAt: number;
+    sessionId: string;
+    runId: string | null;
+    lastEventId: string | null;
+}, {
+    updatedAt: number;
+    sessionId: string;
+    runId: string | null;
+    lastEventId: string | null;
+}>;
+export type PersistedStreamState = z.infer<typeof streamStateSchema>;
+export declare const readStreamState: () => PersistedStreamState | null;
+export declare const writeStreamState: (state: Omit<PersistedStreamState, "updatedAt">) => void;
+export declare const clearStreamState: () => void;
+/**
+ * Like {@link readStreamState}, but only returns state fresh enough that its
+ * run is worth reconnecting to. Returns null for stale state WITHOUT clearing
+ * it: the persisted `sessionId` is still needed for conversation continuity
+ * and history restore on reload — only the *run* is too old to resume. A new
+ * message overwrites the cursor via {@link writeStreamState}.
+ */
+export declare const readResumableStreamState: () => PersistedStreamState | null;
+/**
+ * Persist the chosen session as the active stream session (sessions menu
+ * switch / new). Passing a session id points the next ChatRoute mount at that
+ * conversation with NO live run cursor (`runId`/`lastEventId` null) — so it
+ * restores from history rather than resuming a stale run. Passing null clears
+ * the pointer entirely, so a fresh `belong-chat-<id>` is generated (New chat).
+ */
+export declare const setActiveSessionId: (sessionId: string | null) => void;
+/**
+ * Subscribe to active-session-pointer changes. Pairs with
+ * {@link peekActiveSessionId} for `useSyncExternalStore`. Returns an
+ * unsubscribe fn. Fires on every {@link writeStreamState} /
+ * {@link clearStreamState} — including the transport's `#persist()` when it
+ * creates a brand-new session, which is how the dock learns the new id and
+ * lights up the right row in the switcher.
+ */
+export declare const subscribeStreamState: (listener: () => void) => (() => void);
+/**
+ * The currently-pinned session id, or null when none. Returns a primitive so
+ * the `useSyncExternalStore` snapshot identity is stable across reads (no
+ * memo cache needed).
+ */
+export declare const peekActiveSessionId: () => string | null;
+export {};

package/dist/stream/tool-io.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Read a typed field from a loosely-typed tool input/output record. Tool
+ * `input` / `output` payloads cross the AI-SDK boundary as
+ * `Record<string, unknown>`, so we narrow per field at the read site (§4).
+ */
+export declare const readString: (rec: Readonly<Record<string, unknown>> | null | undefined, key: string) => string | null;
+export declare const readNumber: (rec: Readonly<Record<string, unknown>> | null | undefined, key: string) => number | null;

package/dist/test/render.d.ts

@@ -0,0 +1,23 @@
+import { ReactElement } from 'react';
+export type RenderResult = {
+    readonly container: HTMLElement;
+    readonly rerender: (ui: ReactElement) => void;
+    readonly unmount: () => void;
+};
+export declare function renderComponent(ui: ReactElement): RenderResult;
+/** Unmount every still-mounted tree — call from an afterEach. */
+export declare function cleanupAll(): void;
+/** Click an element and flush the resulting React updates synchronously. */
+export declare function click(el: Element): void;
+/** Set an input/textarea value and fire React's onChange, flushed. */
+export declare function setValue(el: HTMLInputElement | HTMLTextAreaElement, value: string): void;
+/**
+ * Poll `predicate`, yielding the event loop between attempts (`stepMs`), until
+ * it holds or `timeoutMs` elapses. The repo's render harness serves React's
+ * prod build (no `React.act`), so async state — react-query settling, a $post
+ * resolving — is observed by polling rather than awaiting `act`.
+ */
+export declare function waitFor(predicate: () => boolean, { timeoutMs, stepMs }?: {
+    timeoutMs?: number;
+    stepMs?: number;
+}): Promise<void>;

package/dist/test-setup.d.ts

@@ -0,0 +1 @@
+export {};