@lunora/react 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import { ReactNode, ReactElement } from 'react';
-import { LunoraClient, OptimisticUpdate, User, ConnectionStatus, ReturnOf, ArgsOf, FunctionReference, Preloaded } from '@lunora/client';
-export type { ArgsOf, FunctionReference, LunoraClient, OptimisticLocalStore, OptimisticUpdate, Preloaded, ReturnOf, User } from '@lunora/client';
+import { LunoraClient, OptimisticUpdate, User, ConnectionStatus, ReturnOf, ArgsOf, FunctionReference, 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 { 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';
@@ -233,6 +233,38 @@ declare const useAuth: () => UseAuthResult;
 * operator can tell a healthy live channel from a silently-dropped socket.
 */
 declare const useConnectionStatus: () => ConnectionStatus;
+/** A targeting context merged on top of the app's default (`defineFlags({ identify })`). */
+type FlagContext = Record<string, unknown>;
+/** The value kinds a flag resolves to — OpenFeature's boolean / number / string / structured (JSON) flags. */
+type FlagValue = boolean | number | string | {
+  [key: string]: unknown;
+} | unknown[] | null;
+/**
+* Subscribe to a single feature flag, live over Lunora's WebSocket.
+*
+* Returns `defaultValue` until the first evaluation lands, then the server's
+* resolved value — re-pushed whenever the provider re-evaluates (e.g. a flag is
+* toggled in Cloudflare Flagship). The flag's kind is inferred from
+* `defaultValue`'s runtime type, so `useFlag("dark", false)` reads a boolean and
+* `useFlag("hero", "control")` a string. `context` supplies a per-call targeting
+* context merged on top of the app's default `identify` targeting key.
+*
+* Evaluation runs through whatever OpenFeature provider the app wired in
+* `lunora/flags.ts`; the read never throws — a provider error resolves the
+* default (the same fail-open contract as server-side `ctx.flags`).
+*/
+declare const useFlag: <T extends FlagValue>(key: string, defaultValue: T, context?: FlagContext) => T;
+/**
+* Subscribe to several feature flags at once, live over Lunora's WebSocket.
+*
+* Pass a record of `key → defaultValue`; each flag's kind is inferred from its
+* default, and the result is the same-shaped record with resolved values (the
+* defaults until each evaluation lands). A single `context` applies to every
+* flag. This is the batched form of {@link useFlag} — one effect manages one
+* subscription per key, so it stays rules-of-hooks-safe even as the flag set
+* changes between renders.
+*/
+declare const useFlags: <T extends Record<string, FlagValue>>(flags: T, context?: FlagContext) => T;
 /** The args a paginated query exposes minus the framework-supplied page cursor. */
 type PaginatedArgs<F> = Omit<ArgsOf<F>, "paginationOpts">;
 /** The element type of the `page` array a paginated query returns. */
@@ -322,6 +354,31 @@ interface MutationHook<F extends FunctionReference> {
 * through TanStack's `onMutate`.
 */
 declare const useMutation: <F extends FunctionReference>(function_: F) => MutationHook<F>;
+interface MutatorHook<TArgs> {
+  /** The latest invocation's error, or `undefined`. */
+  error: Error | undefined;
+  /** `true` when the latest invocation rejected. */
+  isError: boolean;
+  /** Run the mutator; resolves once the write is persisted, rejects on failure. */
+  mutate: (args: TArgs) => Promise<void>;
+  /** `true` while ANY invocation from this hook is in flight (ref-counted, so overlapping calls compose). */
+  pending: boolean;
+  /** Clear the latest `error` back to idle. */
+  reset: () => void;
+}
+/**
+* Ergonomic `{ mutate, pending, error, isError, reset }` wrapper over a bound
+* custom-mutator handle from `@lunora/db`'s `bindMutators`. The optimistic
+* overlay and server-authoritative push are owned by the bound handle (and
+* TanStack DB's optimistic-transaction layer rebases pending overlays on every
+* sync tick) — this hook only surfaces React state for the in-flight/error
+* lifecycle. Reads stay on the existing `useLiveQuery`; no new query hook is
+* needed.
+*
+* `pending` is ref-counted across overlapping invocations of THIS hook instance,
+* so it clears only once every concurrent call has settled.
+*/
+declare const useMutator: <TArgs = Record<string, unknown>>(handle: MutatorHandle<TArgs>) => MutatorHook<TArgs>;
 /**
 * Hydrate a query from a {@link Preloaded} token produced by `preloadQuery`
 * during SSR, then keep it live.
@@ -496,4 +553,4 @@ declare const useStream: <F extends FunctionReference<"stream">>(function_: F, a
 * the server pushes over the WS.
 */
 declare const useSubscription: <F extends FunctionReference>(function_: F, args: ArgsOf<F> | "skip", options?: UseQueryOptions) => UseSubscriptionResult<ReturnOf<F>>;
-export { AuthLoading, type AuthState, Authenticated, CheckoutButton, type CheckoutButtonProps, CustomerPortalButton, type CustomerPortalButtonProps, type HeartbeatReference, type ListPresentReference, LunoraProvider, type LunoraProviderProps, type MutationHook, type PageItemOf, type PaginatedArgs, type RedirectTarget, type RedirectTrigger, type Subscription, Unauthenticated, 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, hydratePreloaded, useAuth, useAuthState, useCheckout, useConnectionStatus, useInfiniteQuery, useLunora, useMutation, usePaginatedQuery, usePreloadedQuery, usePresence, useQuery, useRateLimit, useStream, useSubscription };
+export { 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 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, hydratePreloaded, useAuth, useAuthState, useCheckout, useConnectionStatus, useFlag, useFlags, useInfiniteQuery, useLunora, useMutation, useMutator, usePaginatedQuery, usePreloadedQuery, usePresence, useQuery, useRateLimit, useStream, useSubscription };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { ReactNode, ReactElement } from 'react';
-import { LunoraClient, OptimisticUpdate, User, ConnectionStatus, ReturnOf, ArgsOf, FunctionReference, Preloaded } from '@lunora/client';
-export type { ArgsOf, FunctionReference, LunoraClient, OptimisticLocalStore, OptimisticUpdate, Preloaded, ReturnOf, User } from '@lunora/client';
+import { LunoraClient, OptimisticUpdate, User, ConnectionStatus, ReturnOf, ArgsOf, FunctionReference, 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 { 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';
@@ -233,6 +233,38 @@ declare const useAuth: () => UseAuthResult;
 * operator can tell a healthy live channel from a silently-dropped socket.
 */
 declare const useConnectionStatus: () => ConnectionStatus;
+/** A targeting context merged on top of the app's default (`defineFlags({ identify })`). */
+type FlagContext = Record<string, unknown>;
+/** The value kinds a flag resolves to — OpenFeature's boolean / number / string / structured (JSON) flags. */
+type FlagValue = boolean | number | string | {
+  [key: string]: unknown;
+} | unknown[] | null;
+/**
+* Subscribe to a single feature flag, live over Lunora's WebSocket.
+*
+* Returns `defaultValue` until the first evaluation lands, then the server's
+* resolved value — re-pushed whenever the provider re-evaluates (e.g. a flag is
+* toggled in Cloudflare Flagship). The flag's kind is inferred from
+* `defaultValue`'s runtime type, so `useFlag("dark", false)` reads a boolean and
+* `useFlag("hero", "control")` a string. `context` supplies a per-call targeting
+* context merged on top of the app's default `identify` targeting key.
+*
+* Evaluation runs through whatever OpenFeature provider the app wired in
+* `lunora/flags.ts`; the read never throws — a provider error resolves the
+* default (the same fail-open contract as server-side `ctx.flags`).
+*/
+declare const useFlag: <T extends FlagValue>(key: string, defaultValue: T, context?: FlagContext) => T;
+/**
+* Subscribe to several feature flags at once, live over Lunora's WebSocket.
+*
+* Pass a record of `key → defaultValue`; each flag's kind is inferred from its
+* default, and the result is the same-shaped record with resolved values (the
+* defaults until each evaluation lands). A single `context` applies to every
+* flag. This is the batched form of {@link useFlag} — one effect manages one
+* subscription per key, so it stays rules-of-hooks-safe even as the flag set
+* changes between renders.
+*/
+declare const useFlags: <T extends Record<string, FlagValue>>(flags: T, context?: FlagContext) => T;
 /** The args a paginated query exposes minus the framework-supplied page cursor. */
 type PaginatedArgs<F> = Omit<ArgsOf<F>, "paginationOpts">;
 /** The element type of the `page` array a paginated query returns. */
@@ -322,6 +354,31 @@ interface MutationHook<F extends FunctionReference> {
 * through TanStack's `onMutate`.
 */
 declare const useMutation: <F extends FunctionReference>(function_: F) => MutationHook<F>;
+interface MutatorHook<TArgs> {
+  /** The latest invocation's error, or `undefined`. */
+  error: Error | undefined;
+  /** `true` when the latest invocation rejected. */
+  isError: boolean;
+  /** Run the mutator; resolves once the write is persisted, rejects on failure. */
+  mutate: (args: TArgs) => Promise<void>;
+  /** `true` while ANY invocation from this hook is in flight (ref-counted, so overlapping calls compose). */
+  pending: boolean;
+  /** Clear the latest `error` back to idle. */
+  reset: () => void;
+}
+/**
+* Ergonomic `{ mutate, pending, error, isError, reset }` wrapper over a bound
+* custom-mutator handle from `@lunora/db`'s `bindMutators`. The optimistic
+* overlay and server-authoritative push are owned by the bound handle (and
+* TanStack DB's optimistic-transaction layer rebases pending overlays on every
+* sync tick) — this hook only surfaces React state for the in-flight/error
+* lifecycle. Reads stay on the existing `useLiveQuery`; no new query hook is
+* needed.
+*
+* `pending` is ref-counted across overlapping invocations of THIS hook instance,
+* so it clears only once every concurrent call has settled.
+*/
+declare const useMutator: <TArgs = Record<string, unknown>>(handle: MutatorHandle<TArgs>) => MutatorHook<TArgs>;
 /**
 * Hydrate a query from a {@link Preloaded} token produced by `preloadQuery`
 * during SSR, then keep it live.
@@ -496,4 +553,4 @@ declare const useStream: <F extends FunctionReference<"stream">>(function_: F, a
 * the server pushes over the WS.
 */
 declare const useSubscription: <F extends FunctionReference>(function_: F, args: ArgsOf<F> | "skip", options?: UseQueryOptions) => UseSubscriptionResult<ReturnOf<F>>;
-export { AuthLoading, type AuthState, Authenticated, CheckoutButton, type CheckoutButtonProps, CustomerPortalButton, type CustomerPortalButtonProps, type HeartbeatReference, type ListPresentReference, LunoraProvider, type LunoraProviderProps, type MutationHook, type PageItemOf, type PaginatedArgs, type RedirectTarget, type RedirectTrigger, type Subscription, Unauthenticated, 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, hydratePreloaded, useAuth, useAuthState, useCheckout, useConnectionStatus, useInfiniteQuery, useLunora, useMutation, usePaginatedQuery, usePreloadedQuery, usePresence, useQuery, useRateLimit, useStream, useSubscription };
+export { 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 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, hydratePreloaded, useAuth, useAuthState, useCheckout, useConnectionStatus, useFlag, useFlags, useInfiniteQuery, useLunora, useMutation, useMutator, usePaginatedQuery, usePreloadedQuery, usePresence, useQuery, useRateLimit, useStream, useSubscription };

package/dist/index.mjs

@@ -1,17 +1,20 @@
 'use client';
-export { AuthLoading, Authenticated, Unauthenticated } from './packem_shared/Authenticated-DtKgZT2Z.mjs';
-export { useAuthState } from './packem_shared/useAuthState-BiGhtSCs.mjs';
-export { LunoraProvider, useLunora } from './packem_shared/LunoraProvider-D38Xp16l.mjs';
-export { CheckoutButton, CustomerPortalButton, useCheckout } from './packem_shared/CheckoutButton-CVSry8U1.mjs';
-export { lunoraQueryOptions } from './packem_shared/lunoraQueryOptions-CsuWzjg1.mjs';
-export { default as useAuth } from './packem_shared/useAuth-CNUKtOOp.mjs';
-export { default as useConnectionStatus } from './packem_shared/useConnectionStatus-DRSY9ldm.mjs';
-export { default as useInfiniteQuery } from './packem_shared/useInfiniteQuery-MH0x4l8h.mjs';
-export { useMutation } from './packem_shared/useMutation-CrvMXRsk.mjs';
-export { usePaginatedQuery } from './packem_shared/usePaginatedQuery-D3PTDRGS.mjs';
-export { hydratePreloaded, default as usePreloadedQuery } from './packem_shared/hydratePreloaded-BlFL9FGq.mjs';
-export { usePresence } from './packem_shared/usePresence-D7jLuxj0.mjs';
-export { default as useQuery } from './packem_shared/useQuery-C5S0W-7K.mjs';
+export { AuthLoading, Authenticated, Unauthenticated } from './packem_shared/AuthLoading-DezUWNB2.mjs';
+export { useAuthState } from './packem_shared/useAuthState-CyF35qZR.mjs';
+export { LunoraProvider, useLunora } from './packem_shared/LunoraProvider-BsuiW4Lk.mjs';
+export { CheckoutButton, CustomerPortalButton, useCheckout } from './packem_shared/CheckoutButton-DUite8jJ.mjs';
+export { lunoraQueryOptions } from './packem_shared/lunoraQueryOptions-C3uwOTMW.mjs';
+export { default as useAuth } from './packem_shared/useAuth-BSutjJaa.mjs';
+export { default as useConnectionStatus } from './packem_shared/useConnectionStatus-PJ7vyCHy.mjs';
+export { useFlag, useFlags } from './packem_shared/useFlag-hhoN_xYA.mjs';
+export { default as useInfiniteQuery } from './packem_shared/useInfiniteQuery-Dy42_srs.mjs';
+export { useMutation } from './packem_shared/useMutation-BeqeIjTr.mjs';
+export { useMutator } from './packem_shared/useMutator-IIrLtDiM.mjs';
+export { usePaginatedQuery } from './packem_shared/usePaginatedQuery-Tx-B3mAP.mjs';
+export { hydratePreloaded, default as usePreloadedQuery } from './packem_shared/hydratePreloaded-Dsf9YuII.mjs';
+export { usePresence } from './packem_shared/usePresence-DC8VIyLB.mjs';
+export { default as useQuery } from './packem_shared/useQuery-_fTR6DCQ.mjs';
 export { useRateLimit } from './packem_shared/useRateLimit-DTEffQEi.mjs';
-export { useStream } from './packem_shared/useStream-BRY9nemd.mjs';
-export { default as useSubscription } from './packem_shared/useSubscription-CHMCjyQg.mjs';
+export { useStream } from './packem_shared/useStream-DFuryaIC.mjs';
+export { default as useSubscription } from './packem_shared/useSubscription-D38Jdyr8.mjs';
+export { getErrorCode, getRetryAfterMs, isConflictError, isForbiddenError, isRateLimitedError, isUnauthorizedError } from '@lunora/client';

package/dist/packem_shared/{Authenticated-DtKgZT2Z.mjs → AuthLoading-DezUWNB2.mjs}

@@ -1,5 +1,5 @@
 'use client';
-import { useAuthState } from './useAuthState-BiGhtSCs.mjs';
+import { useAuthState } from './useAuthState-CyF35qZR.mjs';
 
 const Authenticated = (t0) => {
   const {

package/dist/packem_shared/{CheckoutButton-CVSry8U1.mjs → CheckoutButton-DUite8jJ.mjs}

@@ -3,6 +3,13 @@ import { c } from 'react/compiler-runtime';
 import { useState, useCallback } from 'react';
 import { jsxDEV } from 'react/jsx-dev-runtime';
 
+const safeRedirectHref = (url) => {
+  const parsed = new URL(url, globalThis.location.href);
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new Error(`refusing to redirect to a non-http(s) URL: ${parsed.protocol}`);
+  }
+  return parsed.href;
+};
 const useCheckout = (trigger) => {
   const [pending, setPending] = useState(false);
   const [error, setError] = useState(void 0);
@@ -11,10 +18,7 @@ const useCheckout = (trigger) => {
     setError(void 0);
     try {
       const target = await trigger();
-      const {
-        url
-      } = target;
-      globalThis.location.assign(url);
+      globalThis.location.assign(safeRedirectHref(target.url));
     } catch (error_) {
       const normalized = error_ instanceof Error ? error_ : new Error(String(error_));
       setError(normalized);

package/dist/packem_shared/{LunoraProvider-D38Xp16l.mjs → LunoraProvider-BsuiW4Lk.mjs}

@@ -1,5 +1,6 @@
 'use client';
 import { c } from 'react/compiler-runtime';
+import { LunoraError } from '@lunora/errors';
 import { QueryClientContext, QueryClientProvider, QueryClient } from '@tanstack/react-query';
 import { use, useState, createContext } from 'react';
 import { jsxDEV } from 'react/jsx-dev-runtime';
@@ -37,7 +38,7 @@ const LunoraProvider = (t0) => {
   const [internalClient] = useState(t1);
   const effectiveClient = queryClient ?? parentQueryClient ?? internalClient;
   if (!effectiveClient) {
-    throw new Error("LunoraProvider: failed to resolve a QueryClient");
+    throw new LunoraError("INTERNAL", "LunoraProvider: failed to resolve a QueryClient");
   }
   let t2;
   if ($[3] !== children || $[4] !== client) {
@@ -72,7 +73,7 @@ const LunoraProvider = (t0) => {
 const useLunora = () => {
   const client = use(LunoraContext);
   if (!client) {
-    throw new Error("useLunora must be used inside <LunoraProvider />");
+    throw new LunoraError("INTERNAL", "useLunora must be used inside <LunoraProvider />");
   }
   return client;
 };

package/dist/packem_shared/{cache-CItk3fgN.mjs → cache-BFlsXmup.mjs}

@@ -1,4 +1,4 @@
-import { k as keyHash } from './query-key-C5rufkEE.mjs';
+import { k as keyHash } from './query-key-BmCbgidV.mjs';
 
 class LunoraSubscriptionRegistry {
   constructor(client) {

package/dist/packem_shared/{hydratePreloaded-BlFL9FGq.mjs → hydratePreloaded-Dsf9YuII.mjs}

@@ -1,11 +1,13 @@
 'use client';
+import { c } from 'react/compiler-runtime';
 import { useQueryClient, useQuery } from '@tanstack/react-query';
-import { useMemo, useEffect } from 'react';
-import { g as getSubscriptionRegistry } from './cache-CItk3fgN.mjs';
-import { useLunora } from './LunoraProvider-D38Xp16l.mjs';
-import { l as lunoraQueryKey, s as serializeQueryKey } from './query-key-C5rufkEE.mjs';
+import { useEffect } from 'react';
+import { g as getSubscriptionRegistry } from './cache-BFlsXmup.mjs';
+import { useLunora } from './LunoraProvider-BsuiW4Lk.mjs';
+import { s as serializeQueryKey, l as lunoraQueryKey } from './query-key-BmCbgidV.mjs';
 
 const usePreloadedQuery = function(preloaded) {
+  const $ = c(4);
   const client = useLunora();
   const queryClient = useQueryClient();
   const {
@@ -14,18 +16,13 @@ const usePreloadedQuery = function(preloaded) {
     shardKey,
     value
   } = preloaded;
-  const functionRef = useMemo(() => {
-    return {
-      __lunoraRef: functionPath
-    };
-  }, [functionPath]);
-  const queryKey = useMemo(() => lunoraQueryKey(functionRef, args, shardKey), [functionRef.__lunoraRef, JSON.stringify(args), shardKey]);
+  const functionRef = {
+    __lunoraRef: functionPath
+  };
+  const queryKey = lunoraQueryKey(functionRef, args, shardKey);
   const {
     data
   } = useQuery({
-    // Seed the cache with the server value so the first paint doesn't
-    // re-fetch. TanStack treats `initialData` as fresh — the WS push from
-    // the registry is what supplies subsequent updates.
     initialData: value,
     queryFn: () => client.query(functionRef, args, {
       shardKey
@@ -33,10 +30,21 @@ const usePreloadedQuery = function(preloaded) {
     queryKey,
     staleTime: Number.POSITIVE_INFINITY
   });
+  const t0 = serializeQueryKey(queryKey);
+  let t1;
+  if ($[0] !== client || $[1] !== queryClient || $[2] !== t0) {
+    t1 = [client, queryClient, t0];
+    $[0] = client;
+    $[1] = queryClient;
+    $[2] = t0;
+    $[3] = t1;
+  } else {
+    t1 = $[3];
+  }
   useEffect(() => {
     const registry = getSubscriptionRegistry(client);
     return registry.attach(queryClient, queryKey, functionRef, args, shardKey);
-  }, [client, queryClient, serializeQueryKey(queryKey)]);
+  }, t1);
   return data ?? value;
 };
 const hydratePreloaded = function(preloaded) {

package/dist/packem_shared/{lunoraQueryOptions-CsuWzjg1.mjs → lunoraQueryOptions-C3uwOTMW.mjs}

@@ -1,4 +1,4 @@
-import { l as lunoraQueryKey } from './query-key-C5rufkEE.mjs';
+import { l as lunoraQueryKey } from './query-key-BmCbgidV.mjs';
 
 const lunoraQueryOptions = (client, function_, args, options = {}) => {
   const argsRecord = args ?? {};

package/dist/packem_shared/query-key-BmCbgidV.mjs

@@ -0,0 +1,13 @@
+import { s as stableStringify } from './stable-key-CGp4e2Ux.mjs';
+
+const keyHash = (queryKey) => stableStringify(queryKey);
+const lunoraQueryKey = (function_, args, shardKey) => [
+  "lunora",
+  function_.__lunoraRef,
+  args,
+  // eslint-disable-next-line unicorn/no-null -- this literal is part of the JSON-serialized query key TanStack hashes for dedup; `null` keeps a stable, distinct slot from an absent shardKey across renders.
+  shardKey ?? null
+];
+const serializeQueryKey = (queryKey) => keyHash(queryKey);
+
+export { keyHash as k, lunoraQueryKey as l, serializeQueryKey as s };

package/dist/packem_shared/stable-key-CGp4e2Ux.mjs

@@ -0,0 +1,38 @@
+const compareKeys = (a, b) => {
+  if (a < b) {
+    return -1;
+  }
+  return a > b ? 1 : 0;
+};
+const stableStringify = (value) => {
+  if (value === void 0) {
+    return "null";
+  }
+  if (typeof value === "bigint") {
+    throw new TypeError("stableStringify: cannot use a bigint in a cache key (query/subscription/shape args) — pass it as a string");
+  }
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== null && proto !== Object.prototype) {
+    const name = value.constructor?.name ?? "value";
+    throw new TypeError(`stableStringify: cannot use a ${name} in a cache key (query/subscription/shape args) — only plain objects, arrays, and JSON primitives are supported`);
+  }
+  const record = value;
+  const keys = Object.keys(record).toSorted(compareKeys);
+  const parts = [];
+  for (const key of keys) {
+    const raw = record[key];
+    if (raw === void 0) {
+      continue;
+    }
+    parts.push(`${JSON.stringify(key)}:${stableStringify(raw)}`);
+  }
+  return `{${parts.join(",")}}`;
+};
+
+export { stableStringify as s };

package/dist/packem_shared/{use-paginated-core-CoOfcc-p.mjs → use-paginated-core-CWSzk1J1.mjs}

@@ -2,9 +2,9 @@
 import { initialPages, rebalance, derivePaginationStatus, applyLoadMore } from '@lunora/client/pagination';
 import { useQueryClient } from '@tanstack/react-query';
 import { useRef, useReducer, useState, useEffect, useCallback } from 'react';
-import { g as getSubscriptionRegistry } from './cache-CItk3fgN.mjs';
-import { useLunora } from './LunoraProvider-D38Xp16l.mjs';
-import { s as serializeQueryKey, l as lunoraQueryKey } from './query-key-C5rufkEE.mjs';
+import { g as getSubscriptionRegistry } from './cache-BFlsXmup.mjs';
+import { useLunora } from './LunoraProvider-BsuiW4Lk.mjs';
+import { s as serializeQueryKey, l as lunoraQueryKey } from './query-key-BmCbgidV.mjs';
 
 const useLazyRef = function(create) {
   const reference = useRef(void 0);
@@ -49,12 +49,14 @@ const usePaginatedCore = function(function_, args, options) {
     key: key_0
   }) => serializeQueryKey(key_0)).join("|");
   const desiredRef = useRef({
+    baseArgs,
     entries: [],
     fn: function_,
     shardKey
   });
   useEffect(() => {
     desiredRef.current = {
+      baseArgs,
       entries: pageEntries,
       fn: function_,
       shardKey
@@ -106,12 +108,16 @@ const usePaginatedCore = function(function_, args, options) {
       detaches.set(hash_0, registry.attach(queryClient, entry.key, desired.fn, entry.args, desired.shardKey));
     }
   }, [client, queryClient, pageKeysHash, skipped]);
-  useEffect(() => () => {
-    for (const detach_2 of detachesRef.current.values()) {
-      detach_2();
-    }
-    detachesRef.current.clear();
-  }, []);
+  useEffect(
+    () => () => {
+      for (const detach_2 of detachesRef.current.values()) {
+        detach_2();
+      }
+      detachesRef.current.clear();
+    },
+    // react-doctor-disable-next-line react-doctor/exhaustive-deps -- intentional: unmount-only cleanup. `detachesRef` is a stable ref, so the empty dep array is correct — the teardown must run once on unmount, not every render.
+    []
+  );
   useEffect(() => {
     const cache = queryClient.getQueryCache();
     const unsubscribe = cache.subscribe((event) => {
@@ -140,17 +146,30 @@ const usePaginatedCore = function(function_, args, options) {
     }
   });
   const {
-    nextCursor,
     status
   } = derivePaginationStatus(skipped, pageResults);
-  const nextCursorRef = useRef(void 0);
-  useEffect(() => {
-    nextCursorRef.current = status === "CanLoadMore" ? nextCursor : void 0;
-  });
   const loadMore = useCallback((numberItems) => {
-    const cursor = nextCursorRef.current;
-    setPages((current) => applyLoadMore(current, cursor, numberItems) ?? current);
-  }, []);
+    setPages((current) => {
+      const desired_0 = desiredRef.current;
+      const results = current.map((page_0) => {
+        const pageArgs_0 = {
+          ...desired_0.baseArgs,
+          paginationOpts: {
+            cursor: page_0.lower,
+            endCursor: page_0.upper,
+            numItems: page_0.numItems
+          }
+        };
+        return queryClient.getQueryData(lunoraQueryKey(desired_0.fn, pageArgs_0, desired_0.shardKey));
+      });
+      const {
+        nextCursor,
+        status: liveStatus
+      } = derivePaginationStatus(false, results);
+      const cursor = liveStatus === "CanLoadMore" ? nextCursor : void 0;
+      return applyLoadMore(current, cursor, numberItems) ?? current;
+    });
+  }, [queryClient]);
   return {
     loadMore,
     pageResults,

package/dist/packem_shared/{useAuth-CNUKtOOp.mjs → useAuth-BSutjJaa.mjs}

@@ -1,7 +1,7 @@
 'use client';
 import { c } from 'react/compiler-runtime';
 import { useSyncExternalStore } from 'react';
-import { useLunora } from './LunoraProvider-D38Xp16l.mjs';
+import { useLunora } from './LunoraProvider-BsuiW4Lk.mjs';
 
 const stores = /* @__PURE__ */ new WeakMap();
 const createStore = (client) => {

package/dist/packem_shared/{useAuthState-BiGhtSCs.mjs → useAuthState-CyF35qZR.mjs}

@@ -1,7 +1,7 @@
 'use client';
 import { c } from 'react/compiler-runtime';
 import { useSyncExternalStore } from 'react';
-import useAuth from './useAuth-CNUKtOOp.mjs';
+import useAuth from './useAuth-BSutjJaa.mjs';
 
 const subscribe = () => () => void 0;
 const useAuthState = () => {

package/dist/packem_shared/{useConnectionStatus-DRSY9ldm.mjs → useConnectionStatus-PJ7vyCHy.mjs}

@@ -1,7 +1,7 @@
 'use client';
 import { c } from 'react/compiler-runtime';
 import { useSyncExternalStore } from 'react';
-import { useLunora } from './LunoraProvider-D38Xp16l.mjs';
+import { useLunora } from './LunoraProvider-BsuiW4Lk.mjs';
 
 const useConnectionStatus = () => {
   const $ = c(4);