@voltro/client 0.27.0 → 0.29.0

package/dist/index.d.ts

@@ -175,6 +175,13 @@ export declare interface ApiHandle {
     readonly errorBus: RpcErrorBus;
 }
 
+/**
+ * Apply preload seeds from the hydration payload, BEFORE the first client
+ * render. Idempotent (a Map upsert) so a re-hydration or a repeated key is
+ * harmless — last write wins, matching the store-seed rule.
+ */
+export declare const applyPreloadSeeds: (seeds: ReadonlyArray<PreloadSeed> | undefined) => void;
+
 /**
  * Apply seeds from the hydration payload, BEFORE the first client render.
  *
@@ -820,6 +827,8 @@ export declare class LoadingSubscriptionCache extends SubscriptionCache {
     };
 }
 
+export declare const makePreloadSeedBag: () => PreloadSeedBag;
+
 export declare const makeStoreSeedBag: () => StoreSeedBag;
 
 /** Exported for tests: the inspect URL this hook fetches. */
@@ -1000,6 +1009,27 @@ export declare interface PersistOptions<S> {
     readonly migrate?: (stored: unknown) => Partial<S> | undefined;
 }
 
+/** Options `usePreloadedSubscription` accepts. It OWNS `initialSnapshot` (the
+ *  preload payload supplies it), so callers pass only `skip` — `fallback` and
+ *  `initialSnapshot` are its own concern. */
+export declare type PreloadedSubscriptionOptions = Pick<SubscriptionOptions<never>, 'skip'>;
+
+/** One preloaded subscription snapshot, as it travels in the hydration payload. */
+export declare interface PreloadSeed {
+    /** The api mount name the subscription reads from (first arg of `useSubscription`). */
+    readonly api: string;
+    /** `stableKey([rpcTag, input])` — identical to the SubscriptionCache's own key,
+     *  so the seed and the live subscription address the same entry. */
+    readonly key: string;
+    /** The server-fetched snapshot value. */
+    readonly value: unknown;
+}
+
+/** Collects preload seeds for ONE request. The server creates one per render. */
+export declare interface PreloadSeedBag {
+    readonly seeds: PreloadSeed[];
+}
+
 /** Structural mirror of @voltro/runtime's PreviewDiff (client stays decoupled). */
 export declare interface PreviewDiff {
     readonly rows: ReadonlyArray<PreviewRowDiff>;
@@ -1089,6 +1119,17 @@ export declare interface QueryFiltersState<Row> {
     readonly error: unknown | undefined;
 }
 
+/**
+ * The preloaded snapshot for `(api, rpcTag, input)`, or `undefined` when none was
+ * seeded. On the SERVER it reads the current request's bag directly, so the SSR
+ * markup and the client hydration render see the SAME value (no hydration
+ * flicker); on the CLIENT it reads the hydration-applied registry.
+ *
+ * A seed value is never `undefined` (it round-trips through JSON, so the worst
+ * case is `null`), which is why `undefined` unambiguously means "not seeded".
+ */
+export declare const readPreloadedSnapshot: (api: string, rpcTag: string, input: Readonly<Record<string, unknown>>) => unknown;
+
 export declare interface RecordState<R> {
     readonly record: R | undefined;
     readonly loading: boolean;
@@ -1112,6 +1153,9 @@ export declare const reportClientError: (error: unknown, context?: Record<string
  *  module-global flags + any pending grace-period timer). */
 export declare const _resetFrameworkRuntimesWarning: () => void;
 
+/** Drop all applied client-side seeds. Tests only. */
+export declare const resetPreloadSeeds: () => void;
+
 /** Test helper: forget every defined store. NEVER call this in app code. */
 export declare const resetStoreRegistryForTests: () => void;
 
@@ -1282,6 +1326,14 @@ export declare const schemaToColumns: (schema: Schema.Schema.Any) => ReadonlyArr
  */
 export declare const schemaToFields: (schema: Schema.Schema.Any) => ReadonlyArray<FieldDescriptor>;
 
+/**
+ * Seed a subscription's first value for THIS request's hydration. Call it on the
+ * server during a render — a loader, a layout loader — with the value a
+ * `ctx.query` already fetched, and `usePreloadedSubscription(api, rpcTag, input)`
+ * shows it at the first paint without any serialization step of your own.
+ */
+export declare const seedPreloadedSubscription: (api: string, rpcTag: string, input: Readonly<Record<string, unknown>>, value: unknown) => void;
+
 /**
  * Seed a store for THIS request's hydration. Call it anywhere on the server
  * during a render — a loader, a layout loader — and the value reaches the
@@ -1351,6 +1403,12 @@ export declare type SequenceResult<Ctx> = {
  *  at boot, next to your toast provider. */
 export declare const setMutationNotifier: (notifier: MutationNotifier | undefined) => void;
 
+/**
+ * Install the request-scoped bag resolver. Server-side only; pass `null` to
+ * uninstall (tests). `@voltro/web/ssr` registers it, backed by its own ALS.
+ */
+export declare const setPreloadSeedResolver: (resolver: (() => PreloadSeedBag | null) | null) => void;
+
 /**
  * Install the request-scoped bag resolver. Server-side only; pass `null` to
  * uninstall (tests).
@@ -2134,13 +2192,6 @@ export declare interface UploadResult {
 
 export declare type UploadStatus = 'idle' | 'uploading' | 'success' | 'error';
 
-/**
- * Invoke a server `defineAction` procedure by tag. Unlike `useMutation`,
- * an action has no optimistic / cache surface — it's a unary call whose
- * effects (sends, captures, side-effecting writes the framework must NOT
- * preview locally) only become visible when the server pushes a delta on
- * an independent subscription.
- */
 export declare const useAction: <Input = unknown, Output = unknown>(apiName: string, rpcTag: string) => ActionState<Input, Output>;
 
 export declare const useAgent: (apiName: string, rpcTag: string) => AgentControls;
@@ -2332,6 +2383,19 @@ export declare interface UseOutboxOptions {
 /** The current subject's scopes (defaults to none if no provider). */
 export declare const usePermissions: () => PermissionState_2;
 
+/**
+ * Subscribe to a streaming rpc, seeding the first value from the SSR preload
+ * payload when one exists.
+ *
+ * @param apiName  The api mount name (as in `useSubscription`).
+ * @param rpcTag   The rpc tag (e.g. `'projects.list'`).
+ * @param input    The rpc payload; part of the preload lookup key AND the
+ *                 subscription's cache key (identical `stableKey`).
+ * @param options  `{ skip }` — defers the subscription. `initialSnapshot`
+ *                 comes from the preload payload, not from here.
+ */
+export declare function usePreloadedSubscription<T = unknown>(apiName: string, rpcTag: string, input?: Readonly<Record<string, unknown>>, options?: PreloadedSubscriptionOptions): SubscriptionState<T> | SubscriptionIdle;
+
 export declare const usePreview: <Input = Record<string, unknown>>(apiName: string, previewTag: string) => PreviewState<Input>;
 
 export declare const useProvenance: (apiName: string, table: string, id: string, column?: string) => ProvenanceState;