@lunora/react 1.0.0-alpha.25 → 1.0.0-alpha.26

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { ReactNode, ReactElement } from 'react';
-import { LunoraClient, OptimisticUpdate, User, FunctionReference, ConnectionStatus, ReturnOf, ArgsOf, MutatorHandle, Preloaded } from '@lunora/client';
-export { type ArgsOf, type FunctionReference, type LunoraClient, type LunoraErrorCode, type MutatorHandle, type MutatorTransaction, type OptimisticLocalStore, type OptimisticUpdate, type Preloaded, type ReturnOf, type User, getErrorCode, getRetryAfterMs, isConflictError, isForbiddenError, isRateLimitedError, isUnauthorizedError } from '@lunora/client';
+import { LunoraClient, OptimisticUpdate, User, FunctionReference, ClientQueryRef, ConnectionStatus, ReturnOf, ArgsOf, MutatorHandle, Preloaded } from '@lunora/client';
+export { type ArgsOf, type ClientQueryRef, type FunctionReference, type LunoraClient, type LunoraErrorCode, type MutatorHandle, type MutatorTransaction, type OptimisticLocalStore, type OptimisticUpdate, type Preloaded, type ReturnOf, type User, createClientQuery, getErrorCode, getRetryAfterMs, isConflictError, isForbiddenError, isRateLimitedError, isUnauthorizedError } from '@lunora/client';
 import { QueryClient } from '@tanstack/react-query';
 export { type L as LunoraQueryOptions, l as lunoraQueryOptions } from "./packem_shared/query-options.d-D4okOpO8.mjs";
 import { PaginationStatus } from '@lunora/client/pagination';
@@ -615,6 +615,31 @@ declare const useAgentToolEvents: (options: UseAgentToolEventsOptions) => UseAge
 * hook with the freshly-resolved user.
 */
 declare const useAuth: () => UseAuthResult;
+type Setter<T> = (value: T) => void;
+/**
+* Subscribe to a local-only {@link ClientQueryRef} and re-render when its
+* value changes. Unlike `useQuery`, this never touches the network — the
+* value lives in a reactive store on the `LunoraClient` instance and is shared
+* across every consumer of the same ref.
+*
+* The initial render reads the store synchronously (via
+* `useSyncExternalStore`), so there is never an "undefined flash" — the value
+* is either the one most recently set or `ref.defaultValue`.
+*
+* Returns a `[value, setter]` tuple, matching the `useState` convention.
+* @example
+* ```tsx
+* import { useClientQuery, createClientQuery } from "@lunora/react";
+*
+* const sidebarOpen = createClientQuery("sidebarOpen", true);
+*
+* function Sidebar() {
+*   const [open, setOpen] = useClientQuery(sidebarOpen);
+*   return <aside data-open={open}>…</aside>;
+* }
+* ```
+*/
+declare const useClientQuery: <T extends unknown>(ref: ClientQueryRef<T>) => [T, Setter<T>];
 /**
 * Reactive view of the client's aggregate live-socket status across all shard
 * connections. Re-renders on every transition (`idle` → `connecting` →
@@ -871,6 +896,12 @@ declare const usePresence: <H extends HeartbeatReference, L extends ListPresentR
 * Returns `undefined` until the first response lands. Pass `"skip"` for
 * `args` to short-circuit the query (no network call, no subscription).
 *
+* When the `LunoraClient` was created with `hydrateOnStart: true` and a
+* `queryCache` adapter, the first **enabled** render waits for the durable
+* read cache to finish loading. If a cached value exists for this query it
+* is fed as `initialData` so the user sees it immediately — no undefined
+* flash before the socket round-trip.
+*
 * Internally this routes through TanStack Query: the queryKey is
 * `["lunora", fn.__lunoraRef, args, shardKey]` (TanStack hashes structurally
 * so an args object built in a different key order still dedupes). The
@@ -1089,4 +1120,4 @@ interface UseVoiceAgentResult {
 * `createSocket`) so the hook is drivable outside a browser.
 */
 declare const useVoiceAgent: (options: UseVoiceAgentOptions) => UseVoiceAgentResult;
-export { type AgentChatMessage, type AgentLiveEvent, type AgentProgressEvent, type AgentThreadRecord, type AgentThreadStatus, type AgentTokenDelta, type AgentToolEvent, AuthLoading, type AuthState, Authenticated, CheckoutButton, type CheckoutButtonProps, CustomerPortalButton, type CustomerPortalButtonProps, type FlagContext, type FlagValue, type HeartbeatReference, type ListPresentReference, LunoraProvider, type LunoraProviderProps, type MutationHook, type MutatorHook, type PageItemOf, type PaginatedArgs, type RedirectTarget, type RedirectTrigger, type Subscription, Unauthenticated, type UseAgentApi, type UseAgentChatApi, type UseAgentChatOptions, type UseAgentChatResult, type UseAgentOptions, type UseAgentResult, type UseAgentStateApi, type UseAgentStateOptions, type UseAgentStateResult, type UseAgentToolEventsApi, type UseAgentToolEventsOptions, type UseAgentToolEventsResult, type UseAuthResult, type UseCheckoutResult, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UseMutationCallOptions, type UsePaginatedQueryOptions, type UsePaginatedQueryResult, type UsePresenceOptions, type UsePresenceResult, type UseQueryOptions, type UseRateLimitOptions, type UseRateLimitResult, type UseStreamOptions, type UseStreamResult, type UseStreamStatus, type UseSubscriptionResult, type UseVoiceAgentOptions, type UseVoiceAgentResult, type VoiceAudioFormat, type VoiceReference, type VoiceStatus, hydratePreloaded, useAgent, useAgentChat, useAgentState, useAgentToolEvents, useAuth, useAuthState, useCheckout, useConnectionStatus, useFlag, useFlags, useInfiniteQuery, useLunora, useMutation, useMutator, usePaginatedQuery, usePreloadedQuery, usePresence, useQuery, useRateLimit, useStream, useSubscription, useVoiceAgent };
+export { type AgentChatMessage, type AgentLiveEvent, type AgentProgressEvent, type AgentThreadRecord, type AgentThreadStatus, type AgentTokenDelta, type AgentToolEvent, AuthLoading, type AuthState, Authenticated, CheckoutButton, type CheckoutButtonProps, CustomerPortalButton, type CustomerPortalButtonProps, type FlagContext, type FlagValue, type HeartbeatReference, type ListPresentReference, LunoraProvider, type LunoraProviderProps, type MutationHook, type MutatorHook, type PageItemOf, type PaginatedArgs, type RedirectTarget, type RedirectTrigger, type Subscription, Unauthenticated, type UseAgentApi, type UseAgentChatApi, type UseAgentChatOptions, type UseAgentChatResult, type UseAgentOptions, type UseAgentResult, type UseAgentStateApi, type UseAgentStateOptions, type UseAgentStateResult, type UseAgentToolEventsApi, type UseAgentToolEventsOptions, type UseAgentToolEventsResult, type UseAuthResult, type UseCheckoutResult, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UseMutationCallOptions, type UsePaginatedQueryOptions, type UsePaginatedQueryResult, type UsePresenceOptions, type UsePresenceResult, type UseQueryOptions, type UseRateLimitOptions, type UseRateLimitResult, type UseStreamOptions, type UseStreamResult, type UseStreamStatus, type UseSubscriptionResult, type UseVoiceAgentOptions, type UseVoiceAgentResult, type VoiceAudioFormat, type VoiceReference, type VoiceStatus, hydratePreloaded, useAgent, useAgentChat, useAgentState, useAgentToolEvents, useAuth, useAuthState, useCheckout, useClientQuery, useConnectionStatus, useFlag, useFlags, useInfiniteQuery, useLunora, useMutation, useMutator, usePaginatedQuery, usePreloadedQuery, usePresence, useQuery, useRateLimit, useStream, useSubscription, useVoiceAgent };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { ReactNode, ReactElement } from 'react';
-import { LunoraClient, OptimisticUpdate, User, FunctionReference, ConnectionStatus, ReturnOf, ArgsOf, MutatorHandle, Preloaded } from '@lunora/client';
-export { type ArgsOf, type FunctionReference, type LunoraClient, type LunoraErrorCode, type MutatorHandle, type MutatorTransaction, type OptimisticLocalStore, type OptimisticUpdate, type Preloaded, type ReturnOf, type User, getErrorCode, getRetryAfterMs, isConflictError, isForbiddenError, isRateLimitedError, isUnauthorizedError } from '@lunora/client';
+import { LunoraClient, OptimisticUpdate, User, FunctionReference, ClientQueryRef, ConnectionStatus, ReturnOf, ArgsOf, MutatorHandle, Preloaded } from '@lunora/client';
+export { type ArgsOf, type ClientQueryRef, type FunctionReference, type LunoraClient, type LunoraErrorCode, type MutatorHandle, type MutatorTransaction, type OptimisticLocalStore, type OptimisticUpdate, type Preloaded, type ReturnOf, type User, createClientQuery, getErrorCode, getRetryAfterMs, isConflictError, isForbiddenError, isRateLimitedError, isUnauthorizedError } from '@lunora/client';
 import { QueryClient } from '@tanstack/react-query';
 export { type L as LunoraQueryOptions, l as lunoraQueryOptions } from "./packem_shared/query-options.d-D4okOpO8.js";
 import { PaginationStatus } from '@lunora/client/pagination';
@@ -615,6 +615,31 @@ declare const useAgentToolEvents: (options: UseAgentToolEventsOptions) => UseAge
 * hook with the freshly-resolved user.
 */
 declare const useAuth: () => UseAuthResult;
+type Setter<T> = (value: T) => void;
+/**
+* Subscribe to a local-only {@link ClientQueryRef} and re-render when its
+* value changes. Unlike `useQuery`, this never touches the network — the
+* value lives in a reactive store on the `LunoraClient` instance and is shared
+* across every consumer of the same ref.
+*
+* The initial render reads the store synchronously (via
+* `useSyncExternalStore`), so there is never an "undefined flash" — the value
+* is either the one most recently set or `ref.defaultValue`.
+*
+* Returns a `[value, setter]` tuple, matching the `useState` convention.
+* @example
+* ```tsx
+* import { useClientQuery, createClientQuery } from "@lunora/react";
+*
+* const sidebarOpen = createClientQuery("sidebarOpen", true);
+*
+* function Sidebar() {
+*   const [open, setOpen] = useClientQuery(sidebarOpen);
+*   return <aside data-open={open}>…</aside>;
+* }
+* ```
+*/
+declare const useClientQuery: <T extends unknown>(ref: ClientQueryRef<T>) => [T, Setter<T>];
 /**
 * Reactive view of the client's aggregate live-socket status across all shard
 * connections. Re-renders on every transition (`idle` → `connecting` →
@@ -871,6 +896,12 @@ declare const usePresence: <H extends HeartbeatReference, L extends ListPresentR
 * Returns `undefined` until the first response lands. Pass `"skip"` for
 * `args` to short-circuit the query (no network call, no subscription).
 *
+* When the `LunoraClient` was created with `hydrateOnStart: true` and a
+* `queryCache` adapter, the first **enabled** render waits for the durable
+* read cache to finish loading. If a cached value exists for this query it
+* is fed as `initialData` so the user sees it immediately — no undefined
+* flash before the socket round-trip.
+*
 * Internally this routes through TanStack Query: the queryKey is
 * `["lunora", fn.__lunoraRef, args, shardKey]` (TanStack hashes structurally
 * so an args object built in a different key order still dedupes). The
@@ -1089,4 +1120,4 @@ interface UseVoiceAgentResult {
 * `createSocket`) so the hook is drivable outside a browser.
 */
 declare const useVoiceAgent: (options: UseVoiceAgentOptions) => UseVoiceAgentResult;
-export { type AgentChatMessage, type AgentLiveEvent, type AgentProgressEvent, type AgentThreadRecord, type AgentThreadStatus, type AgentTokenDelta, type AgentToolEvent, AuthLoading, type AuthState, Authenticated, CheckoutButton, type CheckoutButtonProps, CustomerPortalButton, type CustomerPortalButtonProps, type FlagContext, type FlagValue, type HeartbeatReference, type ListPresentReference, LunoraProvider, type LunoraProviderProps, type MutationHook, type MutatorHook, type PageItemOf, type PaginatedArgs, type RedirectTarget, type RedirectTrigger, type Subscription, Unauthenticated, type UseAgentApi, type UseAgentChatApi, type UseAgentChatOptions, type UseAgentChatResult, type UseAgentOptions, type UseAgentResult, type UseAgentStateApi, type UseAgentStateOptions, type UseAgentStateResult, type UseAgentToolEventsApi, type UseAgentToolEventsOptions, type UseAgentToolEventsResult, type UseAuthResult, type UseCheckoutResult, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UseMutationCallOptions, type UsePaginatedQueryOptions, type UsePaginatedQueryResult, type UsePresenceOptions, type UsePresenceResult, type UseQueryOptions, type UseRateLimitOptions, type UseRateLimitResult, type UseStreamOptions, type UseStreamResult, type UseStreamStatus, type UseSubscriptionResult, type UseVoiceAgentOptions, type UseVoiceAgentResult, type VoiceAudioFormat, type VoiceReference, type VoiceStatus, hydratePreloaded, useAgent, useAgentChat, useAgentState, useAgentToolEvents, useAuth, useAuthState, useCheckout, useConnectionStatus, useFlag, useFlags, useInfiniteQuery, useLunora, useMutation, useMutator, usePaginatedQuery, usePreloadedQuery, usePresence, useQuery, useRateLimit, useStream, useSubscription, useVoiceAgent };
+export { type AgentChatMessage, type AgentLiveEvent, type AgentProgressEvent, type AgentThreadRecord, type AgentThreadStatus, type AgentTokenDelta, type AgentToolEvent, AuthLoading, type AuthState, Authenticated, CheckoutButton, type CheckoutButtonProps, CustomerPortalButton, type CustomerPortalButtonProps, type FlagContext, type FlagValue, type HeartbeatReference, type ListPresentReference, LunoraProvider, type LunoraProviderProps, type MutationHook, type MutatorHook, type PageItemOf, type PaginatedArgs, type RedirectTarget, type RedirectTrigger, type Subscription, Unauthenticated, type UseAgentApi, type UseAgentChatApi, type UseAgentChatOptions, type UseAgentChatResult, type UseAgentOptions, type UseAgentResult, type UseAgentStateApi, type UseAgentStateOptions, type UseAgentStateResult, type UseAgentToolEventsApi, type UseAgentToolEventsOptions, type UseAgentToolEventsResult, type UseAuthResult, type UseCheckoutResult, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UseMutationCallOptions, type UsePaginatedQueryOptions, type UsePaginatedQueryResult, type UsePresenceOptions, type UsePresenceResult, type UseQueryOptions, type UseRateLimitOptions, type UseRateLimitResult, type UseStreamOptions, type UseStreamResult, type UseStreamStatus, type UseSubscriptionResult, type UseVoiceAgentOptions, type UseVoiceAgentResult, type VoiceAudioFormat, type VoiceReference, type VoiceStatus, hydratePreloaded, useAgent, useAgentChat, useAgentState, useAgentToolEvents, useAuth, useAuthState, useCheckout, useClientQuery, useConnectionStatus, useFlag, useFlags, useInfiniteQuery, useLunora, useMutation, useMutator, usePaginatedQuery, usePreloadedQuery, usePresence, useQuery, useRateLimit, useStream, useSubscription, useVoiceAgent };

package/dist/index.mjs

@@ -9,6 +9,7 @@ export { useAgentChat } from './packem_shared/useAgentChat-WPm5iHgR.mjs';
 export { useAgentState } from './packem_shared/useAgentState-Cikdlomg.mjs';
 export { useAgentToolEvents } from './packem_shared/useAgentToolEvents-BM7ERo00.mjs';
 export { default as useAuth } from './packem_shared/useAuth-BSutjJaa.mjs';
+export { default as useClientQuery } from './packem_shared/useClientQuery-CN1sC3cP.mjs';
 export { default as useConnectionStatus } from './packem_shared/useConnectionStatus-PJ7vyCHy.mjs';
 export { useFlag, useFlags } from './packem_shared/useFlag-C2Pkghli.mjs';
 export { default as useInfiniteQuery } from './packem_shared/useInfiniteQuery-BeaehE9f.mjs';
@@ -17,9 +18,9 @@ export { useMutator } from './packem_shared/useMutator-IIrLtDiM.mjs';
 export { usePaginatedQuery } from './packem_shared/usePaginatedQuery-_6ETVUmf.mjs';
 export { hydratePreloaded, default as usePreloadedQuery } from './packem_shared/hydratePreloaded-uMDH_xA9.mjs';
 export { usePresence } from './packem_shared/usePresence-Rnx1Fznc.mjs';
-export { default as useQuery } from './packem_shared/useQuery-D3_ZxMYs.mjs';
+export { default as useQuery } from './packem_shared/useQuery-C-hDzP-t.mjs';
 export { useRateLimit } from './packem_shared/useRateLimit-DTEffQEi.mjs';
 export { useStream } from './packem_shared/useStream-CGC26afa.mjs';
 export { default as useSubscription } from './packem_shared/useSubscription-D38Jdyr8.mjs';
 export { useVoiceAgent } from './packem_shared/useVoiceAgent-sC5_ADB8.mjs';
-export { getErrorCode, getRetryAfterMs, isConflictError, isForbiddenError, isRateLimitedError, isUnauthorizedError } from '@lunora/client';
+export { createClientQuery, getErrorCode, getRetryAfterMs, isConflictError, isForbiddenError, isRateLimitedError, isUnauthorizedError } from '@lunora/client';

package/dist/packem_shared/useClientQuery-CN1sC3cP.mjs

@@ -0,0 +1,56 @@
+'use client';
+import { c } from 'react/compiler-runtime';
+import { useSyncExternalStore } from 'react';
+import { useLunora } from './LunoraProvider-BsuiW4Lk.mjs';
+
+const useClientQuery = (ref) => {
+  const $ = c(11);
+  const client = useLunora();
+  let t0;
+  let t1;
+  let t2;
+  if ($[0] !== client || $[1] !== ref) {
+    t0 = (onStoreChange) => {
+      const unsubscribe = client.subscribeClientQuery(ref, () => {
+        onStoreChange();
+      });
+      return unsubscribe;
+    };
+    t1 = () => client.getClientQuery(ref);
+    t2 = () => client.getClientQuery(ref);
+    $[0] = client;
+    $[1] = ref;
+    $[2] = t0;
+    $[3] = t1;
+    $[4] = t2;
+  } else {
+    t0 = $[2];
+    t1 = $[3];
+    t2 = $[4];
+  }
+  const value = useSyncExternalStore(t0, t1, t2);
+  let t3;
+  if ($[5] !== client || $[6] !== ref) {
+    t3 = (next) => {
+      client.setClientQuery(ref, next);
+    };
+    $[5] = client;
+    $[6] = ref;
+    $[7] = t3;
+  } else {
+    t3 = $[7];
+  }
+  const setter = t3;
+  let t4;
+  if ($[8] !== setter || $[9] !== value) {
+    t4 = [value, setter];
+    $[8] = setter;
+    $[9] = value;
+    $[10] = t4;
+  } else {
+    t4 = $[10];
+  }
+  return t4;
+};
+
+export { useClientQuery as default };

package/dist/packem_shared/{useQuery-D3_ZxMYs.mjs → useQuery-C-hDzP-t.mjs}

@@ -1,13 +1,13 @@
 'use client';
 import { c } from 'react/compiler-runtime';
 import { useQueryClient, useQuery as useQuery$1 } from '@tanstack/react-query';
-import { useEffect } from 'react';
+import { useState, useEffect } from 'react';
 import { g as getSubscriptionRegistry } from './cache-D1O_xfAe.mjs';
 import { useLunora } from './LunoraProvider-BsuiW4Lk.mjs';
 import { s as serializeQueryKey, l as lunoraQueryKey } from './query-key-BmCbgidV.mjs';
 
 const useQuery = (function_, args, t0) => {
-  const $ = c(5);
+  const $ = c(9);
   const options = t0 === void 0 ? {} : t0;
   const client = useLunora();
   const queryClient = useQueryClient();
@@ -17,27 +17,50 @@ const useQuery = (function_, args, t0) => {
   const skipped = args === "skip";
   const argsRecord = skipped ? {} : args;
   const queryKey = lunoraQueryKey(function_, argsRecord, shardKey);
+  const [hydrated, setHydrated] = useState(client.isReady);
+  let t1;
+  let t2;
+  if ($[0] !== client || $[1] !== hydrated) {
+    t1 = () => {
+      if (!hydrated) {
+        client.whenReady().then(() => {
+          setHydrated(true);
+        });
+      }
+    };
+    t2 = [client, hydrated];
+    $[0] = client;
+    $[1] = hydrated;
+    $[2] = t1;
+    $[3] = t2;
+  } else {
+    t1 = $[2];
+    t2 = $[3];
+  }
+  useEffect(t1, t2);
+  const cachedData = skipped ? void 0 : client.peekHydratedQuery(function_.__lunoraRef, argsRecord, shardKey);
   const {
     data
   } = useQuery$1({
-    enabled: !skipped,
+    enabled: !skipped && hydrated,
+    initialData: cachedData,
     queryFn: () => client.query(function_, argsRecord, {
       shardKey
     }),
     queryKey,
     staleTime: Number.POSITIVE_INFINITY
   });
-  const t1 = serializeQueryKey(queryKey);
-  let t2;
-  if ($[0] !== client || $[1] !== queryClient || $[2] !== skipped || $[3] !== t1) {
-    t2 = [client, queryClient, t1, skipped];
-    $[0] = client;
-    $[1] = queryClient;
-    $[2] = skipped;
-    $[3] = t1;
-    $[4] = t2;
+  const t3 = serializeQueryKey(queryKey);
+  let t4;
+  if ($[4] !== client || $[5] !== queryClient || $[6] !== skipped || $[7] !== t3) {
+    t4 = [client, queryClient, t3, skipped];
+    $[4] = client;
+    $[5] = queryClient;
+    $[6] = skipped;
+    $[7] = t3;
+    $[8] = t4;
   } else {
-    t2 = $[4];
+    t4 = $[8];
   }
   useEffect(() => {
     if (skipped) {
@@ -45,7 +68,7 @@ const useQuery = (function_, args, t0) => {
     }
     const registry = getSubscriptionRegistry(client);
     return registry.attach(queryClient, queryKey, function_, argsRecord, shardKey);
-  }, t2);
+  }, t4);
   return skipped ? void 0 : data;
 };
 function _temp() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/react",
-  "version": "1.0.0-alpha.25",
+  "version": "1.0.0-alpha.26",
   "description": "React hooks for Lunora: useQuery, useMutation, useSubscription, and useAuth",
   "keywords": [
     "cloudflare",
@@ -49,7 +49,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/client": "1.0.0-alpha.21",
+    "@lunora/client": "1.0.0-alpha.22",
     "@lunora/errors": "1.0.0-alpha.4",
     "@lunora/ratelimit": "1.0.0-alpha.7"
   },