@voltro/client 0.24.0 → 0.26.0

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { ClipboardEvent as ClipboardEvent_2 } from 'react';
 import { Context } from 'react';
 import { DragEvent as DragEvent_2 } from 'react';
 import { Effect } from 'effect';
+import { EventDescriptor as EventDescriptor_2 } from '@voltro/protocol';
 import { Fiber } from 'effect';
 import { ManagedRuntime } from 'effect';
 import { ReactNode } from 'react';
@@ -650,6 +651,27 @@ declare type EventMap<E extends ReadonlyArray<EventDescriptor<string, unknown>>>
     [D in E[number] as D['name']]: D extends EventDescriptor<string, infer A> ? A : never;
 };
 
+export declare interface EventMiss {
+    /** How many deliveries were lost. */
+    readonly count: number;
+    readonly reason: EventMissReason;
+}
+
+/** Why a subscriber lost deliveries. Both are PROVEN counts, never guesses. */
+export declare type EventMissReason = 'buffer' | 'resume';
+
+export declare interface EventState {
+    /** `idle` = not subscribed (null key or `skip`); `connecting` = attaching;
+     *  `live` = the server confirmed the subscription is attached. */
+    readonly status: EventStatus;
+    /** Total deliveries PROVEN lost on this subscription since it mounted. */
+    readonly missed: number;
+    /** The most recent loss, with its cause. */
+    readonly lastMiss: EventMiss | undefined;
+}
+
+export declare type EventStatus = 'idle' | 'connecting' | 'live';
+
 export declare interface EventValidation {
     readonly valid: boolean;
     /** `path` → message, empty when valid. */
@@ -746,6 +768,30 @@ export declare const getMutationNotifier: () => MutationNotifier | undefined;
 /** Read the current feed. Newest-first; up to MAX_MUTATIONS entries. */
 export declare const getMutations: () => ReadonlyArray<MutationEvent>;
 
+/**
+ * Is this the loading baseline rather than a resolved api?
+ *
+ * The stub is deliberately *usable* — that is what lets a provider-less render
+ * proceed instead of crashing — so nothing about its shape says "not ready".
+ * Reads go through `LoadingSubscriptionCache`, whose `subscribe` is a
+ * non-fetching no-op, and that covers every hook that reads through the cache.
+ *
+ * A hook that instead forks its own fiber on `handle.runtime` has no such
+ * backstop, and gets a worse failure than a crash: `useEvent` retries a dropped
+ * subscription forever by design, so forking against the stub's client proxy —
+ * which throws on any call — is an unbounded retry loop, not a one-off error.
+ * Such a hook must gate on this instead.
+ *
+ * It asks about the CAPABILITY, not about object identity, and that is
+ * load-bearing rather than stylistic. `handle === ssrStubHandle` is the obvious
+ * spelling and it is wrong here: a host that loads a bundled copy of this
+ * package alongside this one — `@voltro/web`'s dist does exactly that — has its
+ * own `ssrStubHandle`, so the comparison answers "resolved" for a stub and the
+ * caller forks into the crash anyway. Asking whether the runtime can fork is
+ * true of every real runtime and false of every stub, in any number of copies.
+ */
+export declare const isUnresolvedApi: (handle: ApiHandle) => boolean;
+
 declare type Listener = () => void;
 
 /**
@@ -2205,6 +2251,39 @@ export declare const useDebounced: <T>(value: T, ms?: number) => T;
  */
 export declare const useDerived: <S extends Record<string, unknown>, T>(sources: S, reducer: (sources: S) => T) => T;
 
+/**
+ * Subscribe to a declared event.
+ *
+ * ```tsx
+ * useEvent(gameStarted, arenaId ? { arenaId } : null, (payload) => {
+ *   scene.switchTo('running', payload.gameId)
+ * })
+ * ```
+ *
+ * `payload` is typed from the descriptor — a wrong field name is a `tsc` error
+ * at this call site, and the `key` must structurally match the descriptor's key
+ * schema, so a typo cannot produce a subscription that silently never fires.
+ */
+export declare function useEvent<Name extends string, Key extends Schema.Schema.Any, Payload extends Schema.Schema.Any>(descriptor: EventDescriptor_2<Name, Key, Payload>, key: Schema.Schema.Type<Key> | null, handler: (payload: Schema.Schema.Type<Payload>) => void, options?: UseEventOptions): EventState;
+
+export declare interface UseEventOptions {
+    /**
+     * Called when the server can PROVE deliveries were lost — a serial gap while
+     * you were slow to read, or a reconnect older than the server's buffer.
+     *
+     * This is the callback an app builds recovery on: refetch the authoritative
+     * state, re-run the scene, resync the display. It exists because silence is
+     * the one outcome nothing can be built on — a screen cannot tell "nothing
+     * happened" from "I missed the signal", and every comparable product answers
+     * that question by dropping quietly.
+     */
+    readonly onMissed?: (miss: EventMiss) => void;
+    /** Suspend the subscription without unmounting. Same meaning as
+     *  `useSubscription`'s `skip`; a `null` key does the same thing. */
+    readonly skip?: boolean;
+    readonly apiName?: string;
+}
+
 export declare const useFormBinding: <Input extends Record<string, unknown> = Record<string, unknown>, Output = unknown>(apiName: string, mutationTag: string, options: UseFormBindingOptions<Input>) => FormBinding<Input, Output>;
 
 export declare interface UseFormBindingOptions<Input> {