@korajs/react 1.0.0-beta.12 → 1.0.0-beta.14

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { KoraAppLike as KoraAppLike$1, KoraContextValue as KoraContextValue$1, UseMutationOptions as UseMutationOptions$1, UseMutationResultBase, UseQueryOptions as UseQueryOptions$1, AuthSyncBinding, AuthSyncState } from '@korajs/core/bindings';
+import { KoraAppLike as KoraAppLike$1, KoraContextValue as KoraContextValue$1, UseQueryOptions as UseQueryOptions$1, UseMutationOptions as UseMutationOptions$1, UseMutationResultBase, AuthSyncBinding, AuthSyncState } from '@korajs/core/bindings';
 import { Store, QueryStoreCache, CollectionRecord, QueryBuilder, CollectionAccessor } from '@korajs/store';
 import { SyncEngine, CursorInfo, SyncStatusInfo, AwarenessUser, AwarenessState } from '@korajs/sync';
 import { ReactNode } from 'react';
@@ -6,7 +6,24 @@ import * as Y from 'yjs';
 
 type KoraAppLike = KoraAppLike$1<Store, SyncEngine, QueryStoreCache>;
 type KoraContextValue = KoraContextValue$1<Store, SyncEngine, QueryStoreCache>;
-type UseQueryOptions = UseQueryOptions$1;
+/** Options for {@link useQuery} and {@link useQueryState}. */
+interface UseQueryOptions extends UseQueryOptions$1 {
+    /**
+     * When true (default), `useQuery` throws a failed query to the nearest error
+     * boundary. When false it keeps returning the last good rows; read the error with
+     * `useQueryState`. Ignored by `useQueryState`, which always returns the error.
+     */
+    throwOnError?: boolean;
+}
+/** Result of `useQueryState`. */
+interface UseQueryStateResult<T> {
+    /** The current rows (the last good rows while `error` is set). */
+    data: readonly T[];
+    /** The query's failure, or null. Cleared when results flow again. */
+    error: Error | null;
+    /** False until the first result for the current query arrived (always false on the server). */
+    ready: boolean;
+}
 type UseMutationOptions<TData, TArgs extends unknown[], TContext = void> = UseMutationOptions$1<TData, TArgs, TContext>;
 /**
  * Props for the KoraProvider component.
@@ -37,6 +54,15 @@ interface UseRichTextResult {
     cursors: CursorInfo[];
     setCursor: (anchor: number, head: number) => void;
     clearCursor: () => void;
+    /**
+     * True while local edits are not saved yet (a save pending or refused; see
+     * `error`). The edits stay in the document and the next edit saves them again.
+     */
+    hasUnsavedChanges: boolean;
+    /** Save the document now, for example after a refused save. */
+    retrySave: () => Promise<void>;
+    /** The full document state while edits are unsaved (for a recovery copy), else null. */
+    getUnsavedState: () => Uint8Array | null;
 }
 
 /**
@@ -53,6 +79,13 @@ interface AuthBoundKoraProviderProps {
         close(): Promise<void>;
     };
     signedOut?: ReactNode;
+    /**
+     * Rendered instead of the app while the session is locked (offline longer
+     * than the auth client's `maxOfflineGraceMs`, or the device clock moved
+     * backwards). The app and its local data stay open underneath; nothing is
+     * wiped. Defaults to `signedOut`.
+     */
+    locked?: ReactNode;
     fallback?: ReactNode;
     error?: (context: AuthBoundKoraErrorContext) => ReactNode;
     children?: ReactNode;
@@ -83,7 +116,7 @@ declare function classifyKoraInitializationError(error: unknown): AuthBoundKoraI
  * The previous app is fully closed before a different user's app is created,
  * and no stale provider tree is rendered across that boundary.
  */
-declare function AuthBoundKoraProvider({ authClient, createApp, signedOut, fallback, error: renderError, children, }: AuthBoundKoraProviderProps): ReactNode;
+declare function AuthBoundKoraProvider({ authClient, createApp, signedOut, locked, fallback, error: renderError, children, }: AuthBoundKoraProviderProps): ReactNode;
 
 /**
  * React hook that returns the Kora app instance from context.
@@ -110,19 +143,137 @@ declare function useApp<T extends KoraAppLike = KoraAppLike>(): T;
 
 /**
  * React hook for reactive queries against the local Kora store.
+ *
+ * Returns the current rows synchronously (no loading state for local data) and
+ * re-renders only when the result set changes. The array keeps its identity while
+ * the result is unchanged. On the server (`renderToString`, Next.js App Router) and
+ * during hydration it returns `[]`; the rows arrive right after hydration.
+ *
+ * A query that fails (for example a where/orderBy on an unknown field) is thrown to
+ * the nearest React error boundary, so the failure is visible instead of an empty
+ * list. Pass `throwOnError: false`, or use {@link useQueryState}, to handle it inline.
+ *
+ * @param query - A query builder, for example `app.todos.where({ completed: false })`
+ * @param options - `enabled` (default true) and `throwOnError` (default true)
+ * @returns The current result rows
+ *
+ * @example
+ * ```tsx
+ * const todos = useQuery(app.todos.where({ completed: false }).orderBy('createdAt'))
+ * ```
  */
 declare function useQuery<T = CollectionRecord>(query: QueryBuilder<T>, options?: UseQueryOptions): readonly T[];
+/**
+ * Like {@link useQuery}, but returns the error instead of throwing it.
+ *
+ * @param query - A query builder
+ * @param options - `enabled` (default true); `throwOnError` is ignored
+ * @returns `{ data, error, ready }`, the same object until one of them changes.
+ *   `ready` is false until the first result for the current query has arrived.
+ *
+ * @example
+ * ```tsx
+ * const { data: todos, error } = useQueryState(app.todos.where({ completed: false }))
+ * if (error) return <p role="alert">{error.message}</p>
+ * ```
+ */
+declare function useQueryState<T = CollectionRecord>(query: QueryBuilder<T>, options?: UseQueryOptions): UseQueryStateResult<T>;
 
 /**
  * React hook for performing mutations against the local Kora store.
+ *
+ * `mutate`, `mutateAsync` and `reset` keep their identity for the component's lifetime
+ * (safe in effect deps and as memoized props), and the result object only changes when
+ * `isLoading` or `error` does. The latest `mutationFn` and `options` are always used.
+ *
+ * @param mutationFn - The mutation to run, for example `app.todos.insert`
+ * @param options - Optional lifecycle callbacks (`onMutate`, `onSuccess`, `onError`, `onSettled`)
+ * @returns `{ mutate, mutateAsync, isLoading, error, reset }`
+ *
+ * @example
+ * ```tsx
+ * const { mutate: addTodo, isLoading } = useMutation(app.todos.insert)
+ * return <button disabled={isLoading} onClick={() => addTodo({ title: 'New' })}>Add</button>
+ * ```
  */
 declare function useMutation<TData, TArgs extends unknown[], TContext = void>(mutationFn: (...args: TArgs) => Promise<TData>, options?: UseMutationOptions<TData, TArgs, TContext>): UseMutationResult<TData, TArgs>;
 
 /**
  * React hook for monitoring the sync engine's connection status.
+ *
+ * Re-renders only when the status payload changes. The returned object, and its nested
+ * `heldNodes`, `initialSync` and `blockedFailure` values, keep their identity while
+ * unchanged, so they are safe as effect or memo dependencies. Beyond `status` and
+ * `pendingOperations` it reports `heldOperations` / `heldNodes` (writes of another
+ * user waiting on this device), `localDurability` (`'degraded'` when the local
+ * database cannot persist) and `serverProtocolVersion` / `protocolDeprecated`.
+ *
+ * @returns The current {@link SyncStatusInfo}
+ *
+ * @example
+ * ```tsx
+ * const { status, pendingOperations, localDurability } = useSyncStatus()
+ * ```
  */
 declare function useSyncStatus(): SyncStatusInfo;
 
+/**
+ * The collections an app exposes, read from its `collections` namespace. Purely
+ * structural, so it follows whatever accessor types `createApp` infers from the schema.
+ */
+type AppCollections<TApp> = TApp extends {
+    collections: infer C;
+} ? C : never;
+/** The collection names of an app, as string literals. */
+type AppCollectionName<TApp> = Extract<keyof AppCollections<TApp>, string>;
+/** The record type of a collection accessor, inferred from what its queries return. */
+type AccessorRecord<TAccessor> = TAccessor extends {
+    where(...args: never[]): QueryBuilder<infer R>;
+} ? R : CollectionRecord;
+/** The record type of collection `N` of an app. */
+type AppRecord<TApp, N extends AppCollectionName<TApp>> = AccessorRecord<AppCollections<TApp>[N]>;
+/**
+ * Hooks bound to one app type, returned by {@link createKoraHooks}.
+ */
+interface KoraHooks<TApp> {
+    /** The app from the nearest `<KoraProvider app={app}>`, typed as `TApp`. */
+    useApp: () => TApp;
+    /**
+     * The typed accessor of one collection: `insert`, `update` and `where` are checked
+     * against the schema. The accessor keeps its identity across renders.
+     */
+    useCollection: <N extends AppCollectionName<TApp>>(name: N) => AppCollections<TApp>[N];
+    /** {@link useQuery}: rows are typed from the query builder. */
+    useQuery: typeof useQuery;
+    /** {@link useQueryState}: rows are typed from the query builder. */
+    useQueryState: typeof useQueryState;
+    /** {@link useMutation}. */
+    useMutation: typeof useMutation;
+    /** {@link useSyncStatus}. */
+    useSyncStatus: typeof useSyncStatus;
+}
+/**
+ * Creates React hooks typed for one app, so components get schema-checked
+ * collection names, inserts, updates and rows without passing generics around.
+ * Call it once next to `createApp` and import the hooks from there. Nothing runs at
+ * call time; the hooks read the app from `<KoraProvider app={app}>`.
+ *
+ * @returns {@link KoraHooks} for `TApp`
+ *
+ * @example
+ * ```typescript
+ * // kora.ts
+ * export const app = createApp({ schema })
+ * export const { useCollection, useQuery, useMutation } = createKoraHooks<typeof app>()
+ *
+ * // TodoList.tsx
+ * const todos = useCollection('todos')          // 'todoz' is a type error
+ * const rows = useQuery(todos.where({ completed: false }))
+ * const { mutate: add } = useMutation(todos.insert)
+ * ```
+ */
+declare function createKoraHooks<TApp extends KoraAppLike>(): KoraHooks<TApp>;
+
 /**
  * React hook that returns a CollectionAccessor for the given collection name.
  * Convenience hook for accessing a collection without going through the store directly.
@@ -161,8 +312,11 @@ declare function usePresence(user: {
 /**
  * Returns all currently connected collaborators' awareness states.
  *
- * Excludes the local user — only returns remote peers.
+ * Excludes the local user — only returns remote peers. Safe under server rendering
+ * (`renderToString`, Next.js App Router): the server and the hydration pass see `[]`.
+ *
+ * @returns The remote peers' awareness states; the same array until they change
  */
 declare function useCollaborators(): AwarenessState[];
 
-export { type AuthBoundKoraErrorContext, type AuthBoundKoraInitializationError, AuthBoundKoraProvider, type AuthBoundKoraProviderProps, type AuthBoundKoraSession, type KoraAppLike, type KoraContextValue, KoraProvider, type KoraProviderProps, type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseRichTextOptions, type UseRichTextResult, classifyKoraInitializationError, useApp, useCollaborators, useCollection, useMutation, usePresence, useQuery, useRichText, useSyncStatus };
+export { type AccessorRecord, type AppCollectionName, type AppCollections, type AppRecord, type AuthBoundKoraErrorContext, type AuthBoundKoraInitializationError, AuthBoundKoraProvider, type AuthBoundKoraProviderProps, type AuthBoundKoraSession, type KoraAppLike, type KoraContextValue, type KoraHooks, KoraProvider, type KoraProviderProps, type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseQueryStateResult, type UseRichTextOptions, type UseRichTextResult, classifyKoraInitializationError, createKoraHooks, useApp, useCollaborators, useCollection, useMutation, usePresence, useQuery, useQueryState, useRichText, useSyncStatus };

package/dist/index.js

@@ -123,6 +123,7 @@ function AuthBoundKoraProvider({
   authClient,
   createApp,
   signedOut = null,
+  locked,
   fallback = null,
   error: renderError,
   children
@@ -216,6 +217,7 @@ function AuthBoundKoraProvider({
     );
   }
   if (state.state === "signed-out" || state.state === "anonymous") return signedOut;
+  if (state.state === "authenticated" && state.locked) return locked ?? signedOut;
   if (!app) return fallback;
   return createElement2(KoraProvider, { app, fallback }, children);
 }
@@ -232,17 +234,24 @@ function useApp() {
 }
 
 // src/hooks/use-query.ts
-import { assertQueryReady } from "@korajs/store";
-import { useCallback, useEffect as useEffect3, useRef as useRef3, useState as useState3, useSyncExternalStore } from "react";
+import { assertQueryReady, queryKey } from "@korajs/store";
+import { useCallback, useEffect as useEffect3, useMemo as useMemo2, useRef as useRef3, useState as useState3, useSyncExternalStore } from "react";
 var EMPTY_ARRAY = Object.freeze([]);
 var noopSubscribe = (_onStoreChange) => {
   return () => {
   };
 };
-function useQuery(query, options) {
+var getServerSnapshot = () => EMPTY_ARRAY;
+var getNoError = () => null;
+function readQueryError(queryStore) {
+  if (!queryStore) return null;
+  const channel = queryStore;
+  return typeof channel.getError === "function" ? channel.getError() : null;
+}
+function useQuerySubscription(query, options) {
   const { queryStoreCache } = useKoraContext();
   const enabled = options?.enabled !== false;
-  const descriptorKey = JSON.stringify(query.getDescriptor());
+  const descriptorKey = queryKey(query.getDescriptor());
   const queryRef = useRef3(query);
   queryRef.current = query;
   const lastSnapshotRef = useRef3(EMPTY_ARRAY);
@@ -260,122 +269,204 @@ function useQuery(query, options) {
       queryStoreCache.release(currentQuery);
     };
   }, [descriptorKey, enabled, queryStoreCache]);
+  const subscribe = enabled && queryStore ? queryStore.subscribe : noopSubscribe;
   const getSnapshot = useCallback(() => {
     if (!enabled) {
       lastSnapshotRef.current = EMPTY_ARRAY;
       return lastSnapshotRef.current;
     }
-    if (!queryStore) {
-      return lastSnapshotRef.current;
-    }
-    if (!queryStore.hasSnapshot()) {
+    if (!queryStore || !queryStore.hasSnapshot()) {
       return lastSnapshotRef.current;
     }
     const snapshot = queryStore.getSnapshot();
     lastSnapshotRef.current = snapshot;
     return snapshot;
   }, [enabled, queryStore]);
-  return useSyncExternalStore(queryStore ? queryStore.subscribe : noopSubscribe, getSnapshot);
+  const getError = useCallback(
+    () => enabled ? readQueryError(queryStore) : null,
+    [enabled, queryStore]
+  );
+  const data = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+  const error = useSyncExternalStore(subscribe, getError, getNoError);
+  const ready = enabled && queryStore !== null && queryStore.hasSnapshot();
+  return { data, error, ready };
+}
+function useQuery(query, options) {
+  const { data, error } = useQuerySubscription(query, options);
+  if (error && options?.throwOnError !== false) {
+    throw error;
+  }
+  return data;
 }
+function useQueryState(query, options) {
+  const { data, error, ready } = useQuerySubscription(query, options);
+  return useMemo2(() => ({ data, error, ready }), [data, error, ready]);
+}
+
+// src/hooks/create-kora-hooks.ts
+import { useMemo as useMemo4 } from "react";
 
 // src/hooks/use-mutation.ts
 import { createMutationController } from "@korajs/core/bindings";
-import { useRef as useRef5, useSyncExternalStore as useSyncExternalStore2 } from "react";
+import { useCallback as useCallback2, useMemo as useMemo3, useRef as useRef5, useSyncExternalStore as useSyncExternalStore2 } from "react";
 
 // src/hooks/use-controller.ts
 import { useEffect as useEffect4, useReducer, useRef as useRef4 } from "react";
+var ORPHAN_REAP_MS = 1e3;
 function useController(create, destroy, deps) {
-  const controllerRef = useRef4(null);
+  const entryRef = useRef4(null);
   const createRef = useRef4(create);
   createRef.current = create;
-  const [, forceRender] = useReducer((count) => count + 1, 0);
-  const getController = useRef4(() => {
-    if (controllerRef.current === null) {
-      controllerRef.current = createRef.current();
+  const destroyRef = useRef4(destroy);
+  destroyRef.current = destroy;
+  const [version, bumpVersion] = useReducer((count) => count + 1, 0);
+  const handle = useRef4({
+    get: () => {
+      const current = entryRef.current;
+      if (current !== null && !current.reaped) {
+        return current.controller;
+      }
+      const entry = {
+        controller: createRef.current(),
+        claimed: false,
+        reaped: false
+      };
+      entryRef.current = entry;
+      setTimeout(() => {
+        if (!entry.claimed && !entry.reaped) {
+          entry.reaped = true;
+          destroyRef.current(entry.controller);
+        }
+      }, ORPHAN_REAP_MS);
+      return entry.controller;
+    },
+    peek: () => {
+      const current = entryRef.current;
+      return current?.claimed && !current.reaped ? current.controller : null;
     }
-    return controllerRef.current;
   }).current;
   useEffect4(() => {
-    if (controllerRef.current === null) {
-      controllerRef.current = createRef.current();
-      forceRender();
+    const current = entryRef.current;
+    if (current !== null && !current.reaped && !current.claimed) {
+      current.claimed = true;
+    } else if (current === null || current.reaped) {
+      entryRef.current = { controller: createRef.current(), claimed: true, reaped: false };
+      bumpVersion();
     }
     return () => {
-      const controller = controllerRef.current;
-      controllerRef.current = null;
-      if (controller !== null) {
-        destroy(controller);
+      const entry = entryRef.current;
+      entryRef.current = null;
+      if (entry !== null && !entry.reaped) {
+        entry.reaped = true;
+        destroyRef.current(entry.controller);
       }
     };
   }, deps);
-  return getController;
+  return { get: handle.get, peek: handle.peek, version };
 }
 
 // src/hooks/use-mutation.ts
+var IDLE = Object.freeze({ isLoading: false, error: null });
+var getServerSnapshot2 = () => IDLE;
 function useMutation(mutationFn, options) {
   const fnRef = useRef5(mutationFn);
   fnRef.current = mutationFn;
   const optionsRef = useRef5(options);
   optionsRef.current = options;
-  const getController = useController(
+  const controller = useController(
     () => createMutationController({
       mutationFn: (...args) => fnRef.current(...args),
       resolveOptions: () => optionsRef.current
     }),
-    (controller) => controller.destroy(),
+    (instance) => instance.destroy(),
     []
   );
-  const state = useSyncExternalStore2(
+  const getController = controller.get;
+  const subscribe = useCallback2(
     (onStoreChange) => getController().subscribe(onStoreChange),
-    () => getController().getSnapshot(),
-    () => getController().getSnapshot()
+    [getController, controller.version]
+  );
+  const getSnapshot = useCallback2(() => getController().getSnapshot(), [getController]);
+  const state = useSyncExternalStore2(subscribe, getSnapshot, getServerSnapshot2);
+  const mutate = useCallback2((...args) => getController().mutate(...args), [getController]);
+  const mutateAsync = useCallback2(
+    (...args) => getController().mutateAsync(...args),
+    [getController]
+  );
+  const reset = useCallback2(() => getController().reset(), [getController]);
+  return useMemo3(
+    () => ({ mutate, mutateAsync, isLoading: state.isLoading, error: state.error, reset }),
+    [mutate, mutateAsync, reset, state.isLoading, state.error]
   );
-  return {
-    mutate: (...args) => getController().mutate(...args),
-    mutateAsync: (...args) => getController().mutateAsync(...args),
-    isLoading: state.isLoading,
-    error: state.error,
-    reset: () => getController().reset()
-  };
 }
 
 // src/hooks/use-sync-status.ts
-import { createSyncStatusController } from "@korajs/sync";
-import { useSyncExternalStore as useSyncExternalStore3 } from "react";
+import { OFFLINE_SYNC_STATUS, createSyncStatusController } from "@korajs/sync";
+import { useCallback as useCallback3, useSyncExternalStore as useSyncExternalStore3 } from "react";
+var getServerSnapshot3 = () => OFFLINE_SYNC_STATUS;
 function useSyncStatus() {
   const { syncEngine, subscribeSyncStatus, events } = useKoraContext();
-  const getController = useController(
+  const controller = useController(
     () => createSyncStatusController({
       syncEngine,
       subscribeSyncStatus,
       events: subscribeSyncStatus ? null : events
     }),
-    (controller) => controller.destroy(),
+    (instance) => instance.destroy(),
     [syncEngine, subscribeSyncStatus, events]
   );
-  return useSyncExternalStore3(
+  const getController = controller.get;
+  const subscribe = useCallback3(
     (onStoreChange) => getController().subscribe(onStoreChange),
-    () => getController().getSnapshot(),
-    () => getController().getSnapshot()
+    [getController, controller.version]
   );
+  const peek = controller.peek;
+  const getSnapshot = useCallback3(
+    () => peek()?.getSnapshot() ?? OFFLINE_SYNC_STATUS,
+    [peek]
+  );
+  return useSyncExternalStore3(subscribe, getSnapshot, getServerSnapshot3);
+}
+
+// src/hooks/create-kora-hooks.ts
+function createKoraHooks() {
+  function useTypedApp() {
+    return useApp();
+  }
+  function useTypedCollection(name) {
+    const { app, store } = useKoraContext();
+    return useMemo4(() => {
+      const collections = app?.collections;
+      const accessor = collections && name in collections ? collections[name] : store.collection(name);
+      return accessor;
+    }, [app, store, name]);
+  }
+  return {
+    useApp: useTypedApp,
+    useCollection: useTypedCollection,
+    useQuery,
+    useQueryState,
+    useMutation,
+    useSyncStatus
+  };
 }
 
 // src/hooks/use-collection.ts
-import { useMemo as useMemo2 } from "react";
+import { useMemo as useMemo5 } from "react";
 function useCollection(name) {
   const { store } = useKoraContext();
-  return useMemo2(() => {
+  return useMemo5(() => {
     return store.collection(name);
   }, [store, name]);
 }
 
 // src/hooks/use-rich-text.ts
 import { asRichTextSyncEngine, createRichTextController } from "@korajs/store";
-import { useCallback as useCallback2, useEffect as useEffect5, useMemo as useMemo3, useSyncExternalStore as useSyncExternalStore4 } from "react";
+import { useCallback as useCallback4, useEffect as useEffect5, useMemo as useMemo6, useSyncExternalStore as useSyncExternalStore4 } from "react";
 function useRichText(collectionName, recordId, fieldName, options) {
   const { store, syncEngine } = useKoraContext();
-  const collection = useMemo3(() => store.collection(collectionName), [store, collectionName]);
-  const getController = useController(
+  const collection = useMemo6(() => store.collection(collectionName), [store, collectionName]);
+  const controller = useController(
     () => createRichTextController({
       collection,
       collectionName,
@@ -386,29 +477,35 @@ function useRichText(collectionName, recordId, fieldName, options) {
       useDocChannel: options?.useDocChannel,
       user: options?.user
     }),
-    (controller) => controller.destroy(),
+    (instance) => instance.destroy(),
     [collection, collectionName, fieldName, options?.useDocChannel, recordId, store, syncEngine]
   );
+  const getController = controller.get;
   useEffect5(() => {
     getController().setUser(options?.user);
-  }, [getController, options?.user]);
-  const snapshot = useSyncExternalStore4(
+  }, [getController, options?.user, controller.version]);
+  const subscribe = useCallback4(
     (onStoreChange) => getController().subscribe(onStoreChange),
-    () => getController().getSnapshot(),
-    () => getController().getSnapshot()
+    [getController, controller.version]
   );
-  const undo = useCallback2(() => {
+  const getSnapshot = useCallback4(() => getController().getSnapshot(), [getController]);
+  const snapshot = useSyncExternalStore4(subscribe, getSnapshot, getSnapshot);
+  const undo = useCallback4(() => {
     getController().undo();
   }, [getController]);
-  const redo = useCallback2(() => {
+  const redo = useCallback4(() => {
     getController().redo();
   }, [getController]);
-  const setCursor = useCallback2(
+  const setCursor = useCallback4(
     (anchor, head) => getController().setCursor(anchor, head),
     [getController]
   );
-  const clearCursor = useCallback2(() => getController().clearCursor(), [getController]);
-  return buildResult(getController(), snapshot, undo, redo, setCursor, clearCursor);
+  const clearCursor = useCallback4(() => getController().clearCursor(), [getController]);
+  const live = getController();
+  return useMemo6(
+    () => buildResult(live, snapshot, undo, redo, setCursor, clearCursor),
+    [live, snapshot, undo, redo, setCursor, clearCursor, controller.version]
+  );
 }
 function buildResult(controller, snapshot, undo, redo, setCursor, clearCursor) {
   return {
@@ -422,7 +519,10 @@ function buildResult(controller, snapshot, undo, redo, setCursor, clearCursor) {
     error: snapshot.error,
     cursors: [...snapshot.cursors],
     setCursor,
-    clearCursor
+    clearCursor,
+    hasUnsavedChanges: snapshot.hasUnsavedChanges,
+    retrySave: () => controller.retrySave(),
+    getUnsavedState: () => controller.getUnsavedState()
   };
 }
 
@@ -447,12 +547,13 @@ function usePresence(user) {
 
 // src/hooks/use-collaborators.ts
 import { subscribeRemoteAwarenessStates } from "@korajs/sync";
-import { useCallback as useCallback3, useEffect as useEffect7, useRef as useRef6, useSyncExternalStore as useSyncExternalStore5 } from "react";
+import { useCallback as useCallback5, useEffect as useEffect7, useRef as useRef6, useSyncExternalStore as useSyncExternalStore5 } from "react";
 var EMPTY_ARRAY2 = [];
+var getServerSnapshot4 = () => EMPTY_ARRAY2;
 function useCollaborators() {
   const { syncEngine } = useKoraContext();
   const snapshotRef = useRef6(EMPTY_ARRAY2);
-  const subscribe = useCallback3(
+  const subscribe = useCallback5(
     (onStoreChange) => {
       if (!syncEngine) {
         snapshotRef.current = EMPTY_ARRAY2;
@@ -460,6 +561,7 @@ function useCollaborators() {
         };
       }
       const awareness = syncEngine.getAwarenessManager();
+      snapshotRef.current = EMPTY_ARRAY2;
       return subscribeRemoteAwarenessStates(awareness, (states) => {
         snapshotRef.current = states;
         onStoreChange();
@@ -467,24 +569,26 @@ function useCollaborators() {
     },
     [syncEngine]
   );
-  const getSnapshot = useCallback3(() => snapshotRef.current, []);
+  const getSnapshot = useCallback5(() => snapshotRef.current, []);
   useEffect7(() => {
     if (!syncEngine) {
       snapshotRef.current = EMPTY_ARRAY2;
     }
   }, [syncEngine]);
-  return useSyncExternalStore5(subscribe, getSnapshot);
+  return useSyncExternalStore5(subscribe, getSnapshot, getServerSnapshot4);
 }
 export {
   AuthBoundKoraProvider,
   KoraProvider,
   classifyKoraInitializationError,
+  createKoraHooks,
   useApp,
   useCollaborators,
   useCollection,
   useMutation,
   usePresence,
   useQuery,
+  useQueryState,
   useRichText,
   useSyncStatus
 };