@korajs/svelte 0.5.0 → 0.6.0

package/dist/index.cjs

@@ -20,13 +20,50 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  applyPresence: () => applyPresence,
+  createCollaboratorsStore: () => createCollaboratorsStore,
+  createMutation: () => createMutation,
+  createQueryStore: () => createQueryStore,
+  createRichTextBinding: () => createRichTextBinding,
+  createSyncStatusStore: () => createSyncStatusStore,
+  getApp: () => getApp,
+  getCollection: () => getCollection,
   getKoraApp: () => getKoraApp,
-  setKoraAppContext: () => setKoraAppContext
+  getKoraContext: () => getKoraContext,
+  initKoraProvider: () => initKoraProvider,
+  setKoraAppContext: () => setKoraAppContext,
+  setKoraContext: () => setKoraContext,
+  useApp: () => useApp,
+  useCollaborators: () => useCollaborators,
+  useCollection: () => useCollection,
+  useMutation: () => useMutation,
+  usePresence: () => usePresence,
+  useQuery: () => useQuery,
+  useRichText: () => useRichText,
+  useSyncStatus: () => useSyncStatus
 });
 module.exports = __toCommonJS(index_exports);
+
+// src/context.ts
 var import_core = require("@korajs/core");
+var import_store = require("@korajs/store");
 var import_svelte = require("svelte");
+var koraContextKey = /* @__PURE__ */ Symbol("korajs-context");
 var koraAppContextKey = /* @__PURE__ */ Symbol("korajs-app");
+function setKoraContext(value) {
+  (0, import_svelte.setContext)(koraContextKey, value);
+}
+function getKoraContext() {
+  const context = (0, import_svelte.getContext)(koraContextKey);
+  if (!context) {
+    throw new import_core.KoraError(
+      "Kora context missing. Wrap your app with <KoraProvider app={kora}> or <KoraStoreProvider store={store}>.",
+      "KORA_NOT_PROVIDED",
+      { fix: "Wrap your app with <KoraProvider app={kora}> or <KoraStoreProvider store={store}>." }
+    );
+  }
+  return context;
+}
 function setKoraAppContext(koraApp) {
   (0, import_svelte.setContext)(koraAppContextKey, koraApp);
 }
@@ -34,18 +71,278 @@ function getKoraApp() {
   const app = (0, import_svelte.getContext)(koraAppContextKey);
   if (!app) {
     throw new import_core.KoraError(
-      "getKoraApp() requires setKoraAppContext(koraApp) on an ancestor component.",
-      "KORA_NOT_PROVIDED",
-      {
-        fix: "In +layout.svelte: setKoraAppContext(kora); await kora.ready before queries."
-      }
+      "getKoraApp() requires setKoraAppContext(koraApp) on an ancestor.",
+      "KORA_NOT_PROVIDED"
     );
   }
   return app;
 }
+async function initKoraProvider(app) {
+  await app.ready;
+  const queryStoreCache = typeof app.getQueryStoreCache === "function" ? app.getQueryStoreCache() : new import_store.QueryStoreCache();
+  const value = {
+    store: app.getStore(),
+    syncEngine: app.getSyncEngine(),
+    app,
+    events: app.events ?? null,
+    subscribeSyncStatus: app.sync?.subscribeStatus ?? null,
+    queryStoreCache
+  };
+  setKoraContext(value);
+  setKoraAppContext(app);
+  return value;
+}
+
+// src/stores/query-store.ts
+var import_store2 = require("@korajs/store");
+var import_store3 = require("svelte/store");
+var EMPTY_ARRAY = Object.freeze([]);
+function createQueryStore(query, options) {
+  const { queryStoreCache } = getKoraContext();
+  const enabled = options?.enabled !== false;
+  return (0, import_store3.readable)(EMPTY_ARRAY, (set) => {
+    if (!enabled) {
+      set(EMPTY_ARRAY);
+      return () => {
+      };
+    }
+    (0, import_store2.assertQueryReady)(query);
+    const queryStore = queryStoreCache.getOrCreate(query);
+    const unsubscribe = queryStore.subscribe(() => {
+      set(queryStore.getSnapshot());
+    });
+    set(queryStore.getSnapshot());
+    return () => {
+      unsubscribe();
+      queryStoreCache.release(query);
+    };
+  });
+}
+var useQuery = createQueryStore;
+
+// src/composables/use-mutation.ts
+var import_bindings = require("@korajs/core/bindings");
+function createMutation(mutationFn, options) {
+  const optionsRef = { current: options };
+  optionsRef.current = options;
+  const fnRef = { current: mutationFn };
+  fnRef.current = mutationFn;
+  const controller = (0, import_bindings.createMutationController)({
+    mutationFn: (...args) => fnRef.current(...args),
+    resolveOptions: () => optionsRef.current
+  });
+  const loadingListeners = /* @__PURE__ */ new Set();
+  const errorListeners = /* @__PURE__ */ new Set();
+  controller.subscribe(() => {
+    const snapshot = controller.getSnapshot();
+    for (const listener of loadingListeners) {
+      listener(snapshot.isLoading);
+    }
+    for (const listener of errorListeners) {
+      listener(snapshot.error);
+    }
+  });
+  return {
+    mutate: (...args) => controller.mutate(...args),
+    mutateAsync: (...args) => controller.mutateAsync(...args),
+    subscribeLoading: (fn) => {
+      loadingListeners.add(fn);
+      fn(controller.getSnapshot().isLoading);
+      return () => loadingListeners.delete(fn);
+    },
+    subscribeError: (fn) => {
+      errorListeners.add(fn);
+      fn(controller.getSnapshot().error);
+      return () => errorListeners.delete(fn);
+    },
+    get loading() {
+      return controller.getSnapshot().isLoading;
+    },
+    get isLoading() {
+      return controller.getSnapshot().isLoading;
+    },
+    get error() {
+      return controller.getSnapshot().error;
+    },
+    reset: () => controller.reset()
+  };
+}
+var useMutation = createMutation;
+
+// src/composables/use-sync-status.ts
+var import_sync = require("@korajs/sync");
+var import_store4 = require("svelte/store");
+function createSyncStatusStore() {
+  const { syncEngine, subscribeSyncStatus, events } = getKoraContext();
+  return (0, import_store4.readable)(import_sync.OFFLINE_SYNC_STATUS, (set) => {
+    const controller = (0, import_sync.createSyncStatusController)({
+      syncEngine,
+      subscribeSyncStatus,
+      events: subscribeSyncStatus ? null : events
+    });
+    set(controller.getSnapshot());
+    const unsubscribe = controller.subscribe(() => {
+      set(controller.getSnapshot());
+    });
+    return () => {
+      unsubscribe();
+      controller.destroy();
+    };
+  });
+}
+var useSyncStatus = createSyncStatusStore;
+
+// src/composables/use-app.ts
+function getApp() {
+  const { app } = getKoraContext();
+  if (!app) {
+    throw new Error(
+      "getApp() requires <KoraProvider app={kora}> or <KoraStoreProvider store={store}> with a createApp() instance."
+    );
+  }
+  return app;
+}
+var useApp = getApp;
+
+// src/composables/use-collection.ts
+function getCollection(name) {
+  const { store } = getKoraContext();
+  return store.collection(name);
+}
+var useCollection = getCollection;
+
+// src/composables/use-rich-text.ts
+var import_store5 = require("@korajs/store");
+var import_svelte2 = require("svelte");
+var import_store6 = require("svelte/store");
+function createRichTextBinding(collectionName, recordId, fieldName, options) {
+  const { store, syncEngine } = getKoraContext();
+  const controller = (0, import_store5.createRichTextController)({
+    collection: store.collection(collectionName),
+    collectionName,
+    recordId,
+    fieldName,
+    store,
+    syncEngine: (0, import_store5.asRichTextSyncEngine)(syncEngine),
+    useDocChannel: options?.useDocChannel,
+    user: options?.user
+  });
+  (0, import_svelte2.onDestroy)(() => {
+    controller.destroy();
+  });
+  const resultStore = (0, import_store6.readable)(buildResult(controller), (set) => {
+    const sync = () => {
+      set(buildResult(controller));
+    };
+    sync();
+    return controller.subscribe(sync);
+  });
+  return {
+    get doc() {
+      return controller.doc;
+    },
+    get text() {
+      return controller.text;
+    },
+    undo: () => controller.undo(),
+    redo: () => controller.redo(),
+    get ready() {
+      return (0, import_store6.get)(resultStore).ready;
+    },
+    get error() {
+      return (0, import_store6.get)(resultStore).error;
+    },
+    get canUndo() {
+      return (0, import_store6.get)(resultStore).canUndo;
+    },
+    get canRedo() {
+      return (0, import_store6.get)(resultStore).canRedo;
+    },
+    get cursors() {
+      return (0, import_store6.get)(resultStore).cursors;
+    },
+    setCursor: (anchor, head) => controller.setCursor(anchor, head),
+    clearCursor: () => controller.clearCursor(),
+    subscribe: resultStore.subscribe
+  };
+}
+var useRichText = createRichTextBinding;
+function buildResult(controller) {
+  const snapshot = controller.getSnapshot();
+  return {
+    doc: controller.doc,
+    text: controller.text,
+    undo: () => controller.undo(),
+    redo: () => controller.redo(),
+    ready: snapshot.ready,
+    error: snapshot.error,
+    canUndo: snapshot.canUndo,
+    canRedo: snapshot.canRedo,
+    cursors: [...snapshot.cursors],
+    setCursor: (anchor, head) => controller.setCursor(anchor, head),
+    clearCursor: () => controller.clearCursor()
+  };
+}
+
+// src/composables/use-presence.ts
+function applyPresence(user) {
+  const { syncEngine } = getKoraContext();
+  if (!syncEngine || !user?.name || !user?.color) {
+    return () => {
+    };
+  }
+  const awareness = syncEngine.getAwarenessManager();
+  awareness.setLocalState({
+    user: {
+      name: user.name,
+      color: user.color,
+      avatar: user.avatar
+    }
+  });
+  return () => {
+    awareness.setLocalState(null);
+  };
+}
+var usePresence = applyPresence;
+
+// src/composables/use-collaborators.ts
+var import_sync2 = require("@korajs/sync");
+var import_store7 = require("svelte/store");
+function createCollaboratorsStore() {
+  const { syncEngine } = getKoraContext();
+  return (0, import_store7.readable)([], (set) => {
+    if (!syncEngine) {
+      set([]);
+      return () => {
+      };
+    }
+    const awareness = syncEngine.getAwarenessManager();
+    return (0, import_sync2.subscribeRemoteAwarenessStates)(awareness, set);
+  });
+}
+var useCollaborators = createCollaboratorsStore;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  applyPresence,
+  createCollaboratorsStore,
+  createMutation,
+  createQueryStore,
+  createRichTextBinding,
+  createSyncStatusStore,
+  getApp,
+  getCollection,
   getKoraApp,
-  setKoraAppContext
+  getKoraContext,
+  initKoraProvider,
+  setKoraAppContext,
+  setKoraContext,
+  useApp,
+  useCollaborators,
+  useCollection,
+  useMutation,
+  usePresence,
+  useQuery,
+  useRichText,
+  useSyncStatus
 });
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { KoraError } from '@korajs/core'\nimport { getContext, setContext } from 'svelte'\nimport type { KoraAppHandle } from './types'\n\nexport type { KoraAppHandle } from './types'\n\nconst koraAppContextKey = Symbol('korajs-app')\n\n/**\n * Set the Kora app in Svelte context (call from a root layout or `+layout.svelte`).\n */\nexport function setKoraAppContext(koraApp: KoraAppHandle): void {\n\tsetContext(koraAppContextKey, koraApp)\n}\n\n/**\n * Read the Kora app from Svelte context in child components.\n */\nexport function getKoraApp(): KoraAppHandle {\n\tconst app = getContext<KoraAppHandle | undefined>(koraAppContextKey)\n\tif (!app) {\n\t\tthrow new KoraError(\n\t\t\t'getKoraApp() requires setKoraAppContext(koraApp) on an ancestor component.',\n\t\t\t'KORA_NOT_PROVIDED',\n\t\t\t{\n\t\t\t\tfix: 'In +layout.svelte: setKoraAppContext(kora); await kora.ready before queries.',\n\t\t\t},\n\t\t)\n\t}\n\treturn app\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,kBAA0B;AAC1B,oBAAuC;AAKvC,IAAM,oBAAoB,uBAAO,YAAY;AAKtC,SAAS,kBAAkB,SAA8B;AAC/D,gCAAW,mBAAmB,OAAO;AACtC;AAKO,SAAS,aAA4B;AAC3C,QAAM,UAAM,0BAAsC,iBAAiB;AACnE,MAAI,CAAC,KAAK;AACT,UAAM,IAAI;AAAA,MACT;AAAA,MACA;AAAA,MACA;AAAA,QACC,KAAK;AAAA,MACN;AAAA,IACD;AAAA,EACD;AACA,SAAO;AACR;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/context.ts","../src/stores/query-store.ts","../src/composables/use-mutation.ts","../src/composables/use-sync-status.ts","../src/composables/use-app.ts","../src/composables/use-collection.ts","../src/composables/use-rich-text.ts","../src/composables/use-presence.ts","../src/composables/use-collaborators.ts"],"sourcesContent":["export type {\n\tKoraAppHandle,\n\tKoraAppLike,\n\tKoraContextValue,\n\tUseMutationOptions,\n\tUseMutationResult,\n\tUseQueryOptions,\n\tUseRichTextResult,\n} from './types'\n\nexport {\n\tgetKoraApp,\n\tgetKoraContext,\n\tinitKoraProvider,\n\tsetKoraAppContext,\n\tsetKoraContext,\n} from './context'\n\nexport { createQueryStore, useQuery } from './stores/query-store'\nexport { createMutation, useMutation } from './composables/use-mutation'\nexport { createSyncStatusStore, useSyncStatus } from './composables/use-sync-status'\nexport { getApp, useApp } from './composables/use-app'\nexport { getCollection, useCollection } from './composables/use-collection'\nexport { createRichTextBinding, useRichText } from './composables/use-rich-text'\nexport type { UseRichTextOptions } from './composables/use-rich-text'\nexport { applyPresence, usePresence } from './composables/use-presence'\nexport { createCollaboratorsStore, useCollaborators } from './composables/use-collaborators'\n","import { KoraError } from '@korajs/core'\nimport { QueryStoreCache } from '@korajs/store'\nimport { getContext, setContext } from 'svelte'\nimport type { KoraAppLike, KoraContextValue } from './types'\n\nconst koraContextKey = Symbol('korajs-context')\nconst koraAppContextKey = Symbol('korajs-app')\n\nexport function setKoraContext(value: KoraContextValue): void {\n\tsetContext(koraContextKey, value)\n}\n\nexport function getKoraContext(): KoraContextValue {\n\tconst context = getContext<KoraContextValue | undefined>(koraContextKey)\n\tif (!context) {\n\t\tthrow new KoraError(\n\t\t\t'Kora context missing. Wrap your app with <KoraProvider app={kora}> or <KoraStoreProvider store={store}>.',\n\t\t\t'KORA_NOT_PROVIDED',\n\t\t\t{ fix: 'Wrap your app with <KoraProvider app={kora}> or <KoraStoreProvider store={store}>.' },\n\t\t)\n\t}\n\treturn context\n}\n\n/** @deprecated Use {@link setKoraContext} via {@link KoraProvider} or {@link KoraStoreProvider}. */\nexport function setKoraAppContext(koraApp: KoraAppLike): void {\n\tsetContext(koraAppContextKey, koraApp)\n}\n\n/** @deprecated Use {@link getKoraContext} and {@link getApp}. */\nexport function getKoraApp(): KoraAppLike {\n\tconst app = getContext<KoraAppLike | undefined>(koraAppContextKey)\n\tif (!app) {\n\t\tthrow new KoraError(\n\t\t\t'getKoraApp() requires setKoraAppContext(koraApp) on an ancestor.',\n\t\t\t'KORA_NOT_PROVIDED',\n\t\t)\n\t}\n\treturn app\n}\n\n/**\n * Initialize Kora provider context after `app.ready`.\n *\n * @deprecated Prefer {@link KoraProvider} or {@link KoraStoreProvider} in root layout.\n */\nexport async function initKoraProvider(app: KoraAppLike): Promise<KoraContextValue> {\n\tawait app.ready\n\tconst queryStoreCache =\n\t\ttypeof app.getQueryStoreCache === 'function'\n\t\t\t? app.getQueryStoreCache()\n\t\t\t: new QueryStoreCache()\n\tconst value: KoraContextValue = {\n\t\tstore: app.getStore(),\n\t\tsyncEngine: app.getSyncEngine(),\n\t\tapp,\n\t\tevents: app.events ?? null,\n\t\tsubscribeSyncStatus: app.sync?.subscribeStatus ?? null,\n\t\tqueryStoreCache,\n\t}\n\tsetKoraContext(value)\n\tsetKoraAppContext(app)\n\treturn value\n}\n","import type { CollectionRecord, QueryBuilder } from '@korajs/store'\nimport { assertQueryReady } from '@korajs/store'\nimport { readable, type Readable } from 'svelte/store'\nimport { getKoraContext } from '../context'\nimport type { UseQueryOptions } from '../types'\n\nconst EMPTY_ARRAY: readonly unknown[] = Object.freeze([])\n\n/**\n * Create a Svelte readable store for a static Kora query.\n *\n * For reactive filter changes, use {@link KoraQuery} which re-subscribes when the\n * query descriptor changes.\n */\nexport function createQueryStore<T = CollectionRecord>(\n\tquery: QueryBuilder<T>,\n\toptions?: UseQueryOptions,\n): Readable<readonly T[]> {\n\tconst { queryStoreCache } = getKoraContext()\n\tconst enabled = options?.enabled !== false\n\n\treturn readable<readonly T[]>(EMPTY_ARRAY as readonly T[], (set) => {\n\t\tif (!enabled) {\n\t\t\tset(EMPTY_ARRAY as readonly T[])\n\t\t\treturn () => {}\n\t\t}\n\n\t\tassertQueryReady(query as QueryBuilder<unknown>)\n\t\tconst queryStore = queryStoreCache.getOrCreate(query)\n\t\tconst unsubscribe = queryStore.subscribe(() => {\n\t\t\tset(queryStore.getSnapshot())\n\t\t})\n\t\tset(queryStore.getSnapshot())\n\n\t\treturn () => {\n\t\t\tunsubscribe()\n\t\t\tqueryStoreCache.release(query as QueryBuilder<unknown>)\n\t\t}\n\t})\n}\n\n/** Alias for {@link createQueryStore}. */\nexport const useQuery = createQueryStore\n","import { createMutationController } from '@korajs/core/bindings'\nimport type { UseMutationOptions, UseMutationResult } from '../types'\n\n/**\n * Create a mutation controller with optimistic update hooks.\n */\nexport function createMutation<TData, TArgs extends unknown[], TContext = void>(\n\tmutationFn: (...args: TArgs) => Promise<TData>,\n\toptions?: UseMutationOptions<TData, TArgs, TContext>,\n): UseMutationResult<TData, TArgs> {\n\tconst optionsRef = { current: options }\n\toptionsRef.current = options\n\n\tconst fnRef = { current: mutationFn }\n\tfnRef.current = mutationFn\n\n\tconst controller = createMutationController<TData, TArgs, TContext>({\n\t\tmutationFn: (...args) => fnRef.current(...args),\n\t\tresolveOptions: () => optionsRef.current,\n\t})\n\n\tconst loadingListeners = new Set<(value: boolean) => void>()\n\tconst errorListeners = new Set<(value: Error | null) => void>()\n\n\tcontroller.subscribe(() => {\n\t\tconst snapshot = controller.getSnapshot()\n\t\tfor (const listener of loadingListeners) {\n\t\t\tlistener(snapshot.isLoading)\n\t\t}\n\t\tfor (const listener of errorListeners) {\n\t\t\tlistener(snapshot.error)\n\t\t}\n\t})\n\n\treturn {\n\t\tmutate: (...args: TArgs) => controller.mutate(...args),\n\t\tmutateAsync: (...args: TArgs) => controller.mutateAsync(...args),\n\t\tsubscribeLoading: (fn) => {\n\t\t\tloadingListeners.add(fn)\n\t\t\tfn(controller.getSnapshot().isLoading)\n\t\t\treturn () => loadingListeners.delete(fn)\n\t\t},\n\t\tsubscribeError: (fn) => {\n\t\t\terrorListeners.add(fn)\n\t\t\tfn(controller.getSnapshot().error)\n\t\t\treturn () => errorListeners.delete(fn)\n\t\t},\n\t\tget loading() {\n\t\t\treturn controller.getSnapshot().isLoading\n\t\t},\n\t\tget isLoading() {\n\t\t\treturn controller.getSnapshot().isLoading\n\t\t},\n\t\tget error() {\n\t\t\treturn controller.getSnapshot().error\n\t\t},\n\t\treset: () => controller.reset(),\n\t}\n}\n\n/** Alias for {@link createMutation}. */\nexport const useMutation = createMutation\n","import { OFFLINE_SYNC_STATUS, createSyncStatusController } from '@korajs/sync'\nimport type { SyncStatusInfo } from '@korajs/sync'\nimport { readable, type Readable } from 'svelte/store'\nimport { getKoraContext } from '../context'\n\n/**\n * Readable store of sync engine status.\n */\nexport function createSyncStatusStore(): Readable<SyncStatusInfo> {\n\tconst { syncEngine, subscribeSyncStatus, events } = getKoraContext()\n\n\treturn readable<SyncStatusInfo>(OFFLINE_SYNC_STATUS, (set) => {\n\t\tconst controller = createSyncStatusController({\n\t\t\tsyncEngine,\n\t\t\tsubscribeSyncStatus,\n\t\t\tevents: subscribeSyncStatus ? null : events,\n\t\t})\n\t\tset(controller.getSnapshot())\n\t\tconst unsubscribe = controller.subscribe(() => {\n\t\t\tset(controller.getSnapshot())\n\t\t})\n\t\treturn () => {\n\t\t\tunsubscribe()\n\t\t\tcontroller.destroy()\n\t\t}\n\t})\n}\n\n/** Alias for {@link createSyncStatusStore}. */\nexport const useSyncStatus = createSyncStatusStore\n","import { getKoraContext } from '../context'\nimport type { KoraAppLike } from '../types'\n\nexport function getApp<T extends KoraAppLike = KoraAppLike>(): T {\n\tconst { app } = getKoraContext()\n\tif (!app) {\n\t\tthrow new Error(\n\t\t\t'getApp() requires <KoraProvider app={kora}> or <KoraStoreProvider store={store}> with a createApp() instance.',\n\t\t)\n\t}\n\treturn app as T\n}\n\n/** Alias for {@link getApp}. */\nexport const useApp = getApp\n","import type { CollectionAccessor } from '@korajs/store'\nimport { getKoraContext } from '../context'\n\nexport function getCollection(name: string): CollectionAccessor {\n\tconst { store } = getKoraContext()\n\treturn store.collection(name)\n}\n\n/** Alias for {@link getCollection}. */\nexport const useCollection = getCollection\n","import { asRichTextSyncEngine, createRichTextController } from '@korajs/store'\nimport type { AwarenessUser } from '@korajs/sync'\nimport { onDestroy } from 'svelte'\nimport { get, readable, type Readable } from 'svelte/store'\nimport { getKoraContext } from '../context'\nimport type { UseRichTextResult } from '../types'\n\nexport interface UseRichTextOptions {\n\tuser?: AwarenessUser\n\tuseDocChannel?: boolean\n}\n\n/**\n * Binds a richtext field to a shared Yjs document for editor integration.\n *\n * Must be called during component initialization. For reactive target changes,\n * use {@link KoraRichText} instead.\n */\nexport function createRichTextBinding(\n\tcollectionName: string,\n\trecordId: string,\n\tfieldName: string,\n\toptions?: UseRichTextOptions,\n): UseRichTextResult & { subscribe: Readable<UseRichTextResult>['subscribe'] } {\n\tconst { store, syncEngine } = getKoraContext()\n\n\tconst controller = createRichTextController({\n\t\tcollection: store.collection(collectionName),\n\t\tcollectionName,\n\t\trecordId,\n\t\tfieldName,\n\t\tstore,\n\t\tsyncEngine: asRichTextSyncEngine(syncEngine),\n\t\tuseDocChannel: options?.useDocChannel,\n\t\tuser: options?.user,\n\t})\n\n\tonDestroy(() => {\n\t\tcontroller.destroy()\n\t})\n\n\tconst resultStore = readable<UseRichTextResult>(buildResult(controller), (set) => {\n\t\tconst sync = (): void => {\n\t\t\tset(buildResult(controller))\n\t\t}\n\t\tsync()\n\t\treturn controller.subscribe(sync)\n\t})\n\n\treturn {\n\t\tget doc() {\n\t\t\treturn controller.doc\n\t\t},\n\t\tget text() {\n\t\t\treturn controller.text\n\t\t},\n\t\tundo: () => controller.undo(),\n\t\tredo: () => controller.redo(),\n\t\tget ready() {\n\t\t\treturn get(resultStore).ready\n\t\t},\n\t\tget error() {\n\t\t\treturn get(resultStore).error\n\t\t},\n\t\tget canUndo() {\n\t\t\treturn get(resultStore).canUndo\n\t\t},\n\t\tget canRedo() {\n\t\t\treturn get(resultStore).canRedo\n\t\t},\n\t\tget cursors() {\n\t\t\treturn get(resultStore).cursors\n\t\t},\n\t\tsetCursor: (anchor: number, head: number) => controller.setCursor(anchor, head),\n\t\tclearCursor: () => controller.clearCursor(),\n\t\tsubscribe: resultStore.subscribe,\n\t}\n}\n\n/** @alias createRichTextBinding */\nexport const useRichText = createRichTextBinding\n\nfunction buildResult(\n\tcontroller: ReturnType<typeof createRichTextController>,\n): UseRichTextResult {\n\tconst snapshot = controller.getSnapshot()\n\treturn {\n\t\tdoc: controller.doc,\n\t\ttext: controller.text,\n\t\tundo: () => controller.undo(),\n\t\tredo: () => controller.redo(),\n\t\tready: snapshot.ready,\n\t\terror: snapshot.error,\n\t\tcanUndo: snapshot.canUndo,\n\t\tcanRedo: snapshot.canRedo,\n\t\tcursors: [...snapshot.cursors],\n\t\tsetCursor: (anchor, head) => controller.setCursor(anchor, head),\n\t\tclearCursor: () => controller.clearCursor(),\n\t}\n}\n","import { getKoraContext } from '../context'\n\n/**\n * Applies local collaborative presence. Returns a cleanup function.\n *\n * In Svelte components, call from an effect:\n * `$effect(() => applyPresence(user))`\n */\nexport function applyPresence(\n\tuser: { name: string; color: string; avatar?: string } | null,\n): () => void {\n\tconst { syncEngine } = getKoraContext()\n\tif (!syncEngine || !user?.name || !user?.color) {\n\t\treturn () => {}\n\t}\n\n\tconst awareness = syncEngine.getAwarenessManager()\n\tawareness.setLocalState({\n\t\tuser: {\n\t\t\tname: user.name,\n\t\t\tcolor: user.color,\n\t\t\tavatar: user.avatar,\n\t\t},\n\t})\n\n\treturn () => {\n\t\tawareness.setLocalState(null)\n\t}\n}\n\n/** Alias for {@link applyPresence} — use inside `$effect()` in `.svelte` files. */\nexport const usePresence = applyPresence\n","import type { AwarenessState } from '@korajs/sync'\nimport { subscribeRemoteAwarenessStates } from '@korajs/sync'\nimport { readable, type Readable } from 'svelte/store'\nimport { getKoraContext } from '../context'\n\n/**\n * Readable store of remote collaborators' awareness states.\n */\nexport function createCollaboratorsStore(): Readable<AwarenessState[]> {\n\tconst { syncEngine } = getKoraContext()\n\n\treturn readable<AwarenessState[]>([], (set) => {\n\t\tif (!syncEngine) {\n\t\t\tset([])\n\t\t\treturn () => {}\n\t\t}\n\n\t\tconst awareness = syncEngine.getAwarenessManager()\n\t\treturn subscribeRemoteAwarenessStates(awareness, set)\n\t})\n}\n\n/** Alias for {@link createCollaboratorsStore}. */\nexport const useCollaborators = createCollaboratorsStore\n"],"mappings":"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","names":["import_store","import_store","import_store","import_svelte","import_sync","import_store"]}

package/dist/index.d.cts

@@ -1,25 +1,116 @@
-import { KoraEventEmitter } from '@korajs/core';
-import { Store } from '@korajs/store';
+import { KoraAppLike as KoraAppLike$1, KoraContextValue as KoraContextValue$1, UseMutationOptions as UseMutationOptions$1, UseMutationResultBase, UseQueryOptions as UseQueryOptions$1 } from '@korajs/core/bindings';
+import { Store, QueryStoreCache, CollectionRecord, QueryBuilder, CollectionAccessor } from '@korajs/store';
+import { SyncEngine, CursorInfo, SyncStatusInfo, AwarenessUser, AwarenessState } from '@korajs/sync';
+import * as Y from 'yjs';
+import { Readable } from 'svelte/store';
+
+type KoraAppLike = KoraAppLike$1<Store, SyncEngine, QueryStoreCache>;
+type KoraContextValue = KoraContextValue$1<Store, SyncEngine, QueryStoreCache>;
+type UseQueryOptions = UseQueryOptions$1;
+type UseMutationOptions<TData, TArgs extends unknown[], TContext = void> = UseMutationOptions$1<TData, TArgs, TContext>;
+interface UseMutationResult<TData, TArgs extends unknown[]> extends UseMutationResultBase<TData, TArgs> {
+    subscribeLoading: (fn: (value: boolean) => void) => () => void;
+    subscribeError: (fn: (value: Error | null) => void) => () => void;
+    readonly loading: boolean;
+    readonly isLoading: boolean;
+    readonly error: Error | null;
+}
+/** @deprecated Use {@link KoraAppLike}. */
+type KoraAppHandle = KoraAppLike;
+interface UseRichTextResult {
+    doc: Y.Doc;
+    text: Y.Text;
+    undo: () => void;
+    redo: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    ready: boolean;
+    error: Error | null;
+    cursors: CursorInfo[];
+    setCursor: (anchor: number, head: number) => void;
+    clearCursor: () => void;
+}
+
+declare function setKoraContext(value: KoraContextValue): void;
+declare function getKoraContext(): KoraContextValue;
+/** @deprecated Use {@link setKoraContext} via {@link KoraProvider} or {@link KoraStoreProvider}. */
+declare function setKoraAppContext(koraApp: KoraAppLike): void;
+/** @deprecated Use {@link getKoraContext} and {@link getApp}. */
+declare function getKoraApp(): KoraAppLike;
+/**
+ * Initialize Kora provider context after `app.ready`.
+ *
+ * @deprecated Prefer {@link KoraProvider} or {@link KoraStoreProvider} in root layout.
+ */
+declare function initKoraProvider(app: KoraAppLike): Promise<KoraContextValue>;
+
+/**
+ * Create a Svelte readable store for a static Kora query.
+ *
+ * For reactive filter changes, use {@link KoraQuery} which re-subscribes when the
+ * query descriptor changes.
+ */
+declare function createQueryStore<T = CollectionRecord>(query: QueryBuilder<T>, options?: UseQueryOptions): Readable<readonly T[]>;
+/** Alias for {@link createQueryStore}. */
+declare const useQuery: typeof createQueryStore;
 
 /**
- * Minimal app handle type for Svelte context (matches `createApp()` from korajs).
+ * Create a mutation controller with optimistic update hooks.
  */
-interface KoraAppHandle {
-    readonly ready: Promise<void>;
-    readonly events: KoraEventEmitter;
-    readonly sync: unknown;
-    close(): Promise<void>;
-    getStore(): Store;
-    [collection: string]: unknown;
+declare function createMutation<TData, TArgs extends unknown[], TContext = void>(mutationFn: (...args: TArgs) => Promise<TData>, options?: UseMutationOptions<TData, TArgs, TContext>): UseMutationResult<TData, TArgs>;
+/** Alias for {@link createMutation}. */
+declare const useMutation: typeof createMutation;
+
+/**
+ * Readable store of sync engine status.
+ */
+declare function createSyncStatusStore(): Readable<SyncStatusInfo>;
+/** Alias for {@link createSyncStatusStore}. */
+declare const useSyncStatus: typeof createSyncStatusStore;
+
+declare function getApp<T extends KoraAppLike = KoraAppLike>(): T;
+/** Alias for {@link getApp}. */
+declare const useApp: typeof getApp;
+
+declare function getCollection(name: string): CollectionAccessor;
+/** Alias for {@link getCollection}. */
+declare const useCollection: typeof getCollection;
+
+interface UseRichTextOptions {
+    user?: AwarenessUser;
+    useDocChannel?: boolean;
 }
+/**
+ * Binds a richtext field to a shared Yjs document for editor integration.
+ *
+ * Must be called during component initialization. For reactive target changes,
+ * use {@link KoraRichText} instead.
+ */
+declare function createRichTextBinding(collectionName: string, recordId: string, fieldName: string, options?: UseRichTextOptions): UseRichTextResult & {
+    subscribe: Readable<UseRichTextResult>['subscribe'];
+};
+/** @alias createRichTextBinding */
+declare const useRichText: typeof createRichTextBinding;
 
 /**
- * Set the Kora app in Svelte context (call from a root layout or `+layout.svelte`).
+ * Applies local collaborative presence. Returns a cleanup function.
+ *
+ * In Svelte components, call from an effect:
+ * `$effect(() => applyPresence(user))`
  */
-declare function setKoraAppContext(koraApp: KoraAppHandle): void;
+declare function applyPresence(user: {
+    name: string;
+    color: string;
+    avatar?: string;
+} | null): () => void;
+/** Alias for {@link applyPresence} — use inside `$effect()` in `.svelte` files. */
+declare const usePresence: typeof applyPresence;
+
 /**
- * Read the Kora app from Svelte context in child components.
+ * Readable store of remote collaborators' awareness states.
  */
-declare function getKoraApp(): KoraAppHandle;
+declare function createCollaboratorsStore(): Readable<AwarenessState[]>;
+/** Alias for {@link createCollaboratorsStore}. */
+declare const useCollaborators: typeof createCollaboratorsStore;
 
-export { type KoraAppHandle, getKoraApp, setKoraAppContext };
+export { type KoraAppHandle, type KoraAppLike, type KoraContextValue, type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseRichTextOptions, type UseRichTextResult, applyPresence, createCollaboratorsStore, createMutation, createQueryStore, createRichTextBinding, createSyncStatusStore, getApp, getCollection, getKoraApp, getKoraContext, initKoraProvider, setKoraAppContext, setKoraContext, useApp, useCollaborators, useCollection, useMutation, usePresence, useQuery, useRichText, useSyncStatus };

package/dist/index.d.ts

@@ -1,25 +1,116 @@
-import { KoraEventEmitter } from '@korajs/core';
-import { Store } from '@korajs/store';
+import { KoraAppLike as KoraAppLike$1, KoraContextValue as KoraContextValue$1, UseMutationOptions as UseMutationOptions$1, UseMutationResultBase, UseQueryOptions as UseQueryOptions$1 } from '@korajs/core/bindings';
+import { Store, QueryStoreCache, CollectionRecord, QueryBuilder, CollectionAccessor } from '@korajs/store';
+import { SyncEngine, CursorInfo, SyncStatusInfo, AwarenessUser, AwarenessState } from '@korajs/sync';
+import * as Y from 'yjs';
+import { Readable } from 'svelte/store';
+
+type KoraAppLike = KoraAppLike$1<Store, SyncEngine, QueryStoreCache>;
+type KoraContextValue = KoraContextValue$1<Store, SyncEngine, QueryStoreCache>;
+type UseQueryOptions = UseQueryOptions$1;
+type UseMutationOptions<TData, TArgs extends unknown[], TContext = void> = UseMutationOptions$1<TData, TArgs, TContext>;
+interface UseMutationResult<TData, TArgs extends unknown[]> extends UseMutationResultBase<TData, TArgs> {
+    subscribeLoading: (fn: (value: boolean) => void) => () => void;
+    subscribeError: (fn: (value: Error | null) => void) => () => void;
+    readonly loading: boolean;
+    readonly isLoading: boolean;
+    readonly error: Error | null;
+}
+/** @deprecated Use {@link KoraAppLike}. */
+type KoraAppHandle = KoraAppLike;
+interface UseRichTextResult {
+    doc: Y.Doc;
+    text: Y.Text;
+    undo: () => void;
+    redo: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    ready: boolean;
+    error: Error | null;
+    cursors: CursorInfo[];
+    setCursor: (anchor: number, head: number) => void;
+    clearCursor: () => void;
+}
+
+declare function setKoraContext(value: KoraContextValue): void;
+declare function getKoraContext(): KoraContextValue;
+/** @deprecated Use {@link setKoraContext} via {@link KoraProvider} or {@link KoraStoreProvider}. */
+declare function setKoraAppContext(koraApp: KoraAppLike): void;
+/** @deprecated Use {@link getKoraContext} and {@link getApp}. */
+declare function getKoraApp(): KoraAppLike;
+/**
+ * Initialize Kora provider context after `app.ready`.
+ *
+ * @deprecated Prefer {@link KoraProvider} or {@link KoraStoreProvider} in root layout.
+ */
+declare function initKoraProvider(app: KoraAppLike): Promise<KoraContextValue>;
+
+/**
+ * Create a Svelte readable store for a static Kora query.
+ *
+ * For reactive filter changes, use {@link KoraQuery} which re-subscribes when the
+ * query descriptor changes.
+ */
+declare function createQueryStore<T = CollectionRecord>(query: QueryBuilder<T>, options?: UseQueryOptions): Readable<readonly T[]>;
+/** Alias for {@link createQueryStore}. */
+declare const useQuery: typeof createQueryStore;
 
 /**
- * Minimal app handle type for Svelte context (matches `createApp()` from korajs).
+ * Create a mutation controller with optimistic update hooks.
  */
-interface KoraAppHandle {
-    readonly ready: Promise<void>;
-    readonly events: KoraEventEmitter;
-    readonly sync: unknown;
-    close(): Promise<void>;
-    getStore(): Store;
-    [collection: string]: unknown;
+declare function createMutation<TData, TArgs extends unknown[], TContext = void>(mutationFn: (...args: TArgs) => Promise<TData>, options?: UseMutationOptions<TData, TArgs, TContext>): UseMutationResult<TData, TArgs>;
+/** Alias for {@link createMutation}. */
+declare const useMutation: typeof createMutation;
+
+/**
+ * Readable store of sync engine status.
+ */
+declare function createSyncStatusStore(): Readable<SyncStatusInfo>;
+/** Alias for {@link createSyncStatusStore}. */
+declare const useSyncStatus: typeof createSyncStatusStore;
+
+declare function getApp<T extends KoraAppLike = KoraAppLike>(): T;
+/** Alias for {@link getApp}. */
+declare const useApp: typeof getApp;
+
+declare function getCollection(name: string): CollectionAccessor;
+/** Alias for {@link getCollection}. */
+declare const useCollection: typeof getCollection;
+
+interface UseRichTextOptions {
+    user?: AwarenessUser;
+    useDocChannel?: boolean;
 }
+/**
+ * Binds a richtext field to a shared Yjs document for editor integration.
+ *
+ * Must be called during component initialization. For reactive target changes,
+ * use {@link KoraRichText} instead.
+ */
+declare function createRichTextBinding(collectionName: string, recordId: string, fieldName: string, options?: UseRichTextOptions): UseRichTextResult & {
+    subscribe: Readable<UseRichTextResult>['subscribe'];
+};
+/** @alias createRichTextBinding */
+declare const useRichText: typeof createRichTextBinding;
 
 /**
- * Set the Kora app in Svelte context (call from a root layout or `+layout.svelte`).
+ * Applies local collaborative presence. Returns a cleanup function.
+ *
+ * In Svelte components, call from an effect:
+ * `$effect(() => applyPresence(user))`
  */
-declare function setKoraAppContext(koraApp: KoraAppHandle): void;
+declare function applyPresence(user: {
+    name: string;
+    color: string;
+    avatar?: string;
+} | null): () => void;
+/** Alias for {@link applyPresence} — use inside `$effect()` in `.svelte` files. */
+declare const usePresence: typeof applyPresence;
+
 /**
- * Read the Kora app from Svelte context in child components.
+ * Readable store of remote collaborators' awareness states.
  */
-declare function getKoraApp(): KoraAppHandle;
+declare function createCollaboratorsStore(): Readable<AwarenessState[]>;
+/** Alias for {@link createCollaboratorsStore}. */
+declare const useCollaborators: typeof createCollaboratorsStore;
 
-export { type KoraAppHandle, getKoraApp, setKoraAppContext };
+export { type KoraAppHandle, type KoraAppLike, type KoraContextValue, type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseRichTextOptions, type UseRichTextResult, applyPresence, createCollaboratorsStore, createMutation, createQueryStore, createRichTextBinding, createSyncStatusStore, getApp, getCollection, getKoraApp, getKoraContext, initKoraProvider, setKoraAppContext, setKoraContext, useApp, useCollaborators, useCollection, useMutation, usePresence, useQuery, useRichText, useSyncStatus };