@abloatai/ablo 0.26.0 → 0.27.0

package/dist/core/openIDBWithTimeout.d.ts

@@ -1,32 +1,33 @@
 /**
- * Wrap `indexedDB.open()` with a timeout + loud `onblocked` surfacing so the
- * request can never silently hang the app.
+ * The error raised when opening an IndexedDB database does not complete in a
+ * bounded time. {@link openIDBWithTimeout} throws it in two situations: another
+ * browser tab is holding an older version of the database open and blocking the
+ * upgrade (`reason: 'blocked'`), or the open request produced no result at all
+ * within the timeout (`reason: 'timeout'`).
  *
- * The native `IDBOpenDBRequest` has a nasty failure mode: if another tab is
- * holding an older schema version, the request fires `onblocked` and then
- * waits forever for that tab to close the DB. Neither `onsuccess` nor
- * `onerror` fires — the promise wrapping it never settles and every caller
- * above sits indefinitely.
- *
- * This helper converts that into a real error after a bounded wait, which
- * flows up through `engine.ready()` → `SyncEngineProvider.handleError()` →
- * the error skeleton with a retry button. A visible error is strictly better
- * than a forever-spinner the user can only escape by closing the tab.
+ * The native open request can otherwise hang indefinitely — when a blocking tab
+ * never closes its connection, neither the success nor the error callback fires,
+ * and any code awaiting the open waits forever. Turning that into a thrown error
+ * lets the surrounding application show a recoverable failure instead of an
+ * unbreakable spinner.
  */
 export declare class IDBOpenTimeoutError extends Error {
     readonly dbName: string;
     readonly reason: 'blocked' | 'timeout';
     /**
-     * Stable, transport-independent code. `toAbloError` preserves a string
-     * `.code`, so this survives the wrap into `AbloError` and reaches the
-     * provider's `onError` intact — letting the app distinguish a wedged-storage
-     * failure (show a recovery screen) from any other bootstrap error without a
-     * brittle message match.
+     * A stable identifier for this failure, independent of the message text. When
+     * this error is wrapped into an {@link AbloError} by `toAbloError`, the string
+     * code is preserved, so error handlers can recognize a wedged-storage failure
+     * and offer a recovery path rather than matching on the message.
      */
     readonly code = "storage_open_timeout";
     constructor(dbName: string, reason: 'blocked' | 'timeout', message: string);
 }
-/** True for the wedged-IndexedDB failure, after it has been wrapped anywhere. */
+/**
+ * Returns true when a caught value is the storage-open-timeout failure. It
+ * detects the failure by its stable `code`, so it still matches after the error
+ * has been wrapped into an {@link AbloError} or another error type.
+ */
 export declare function isStorageOpenTimeout(err: unknown): boolean;
 export interface OpenIDBOptions {
     /** Called inside `onupgradeneeded` — mirrors `IDBOpenDBRequest.onupgradeneeded`. */
@@ -34,30 +35,31 @@ export interface OpenIDBOptions {
     /** Max milliseconds to wait for the open request to resolve. Default 10_000. */
     timeoutMs?: number;
     /**
-     * Called when another context (a new tab, a fresh deploy, or our own
-     * `deleteIDBWithTimeout` self-heal) fires `versionchange` on this connection.
-     * By default the connection is `close()`d immediately — the W3C/MDN-mandated
-     * behavior that lets the other context's upgrade/delete proceed instead of
-     * blocking forever. Provide this to ALSO react (e.g. prompt a reload) AFTER
-     * the close. Throwing here is swallowed.
+     * Called when another context — a new tab, a page reload after a deploy, or
+     * this package's own {@link deleteIDBWithTimeout} recovery — needs to upgrade
+     * or delete the database and fires a `versionchange` event on this connection.
+     * The connection is always closed first, which is what lets the other
+     * context's upgrade or delete proceed instead of blocking on this one. Provide
+     * this callback to react after that close, for example to prompt the user to
+     * reload. Any error it throws is ignored.
      */
     onVersionChange?: () => void;
 }
 export declare function openIDBWithTimeout(name: string, version: number | undefined, options?: OpenIDBOptions): Promise<IDBDatabase>;
 /**
- * Bounded `indexedDB.deleteDatabase()` — the delete counterpart of
- * `openIDBWithTimeout`. Used by the meta-DB self-heal: when opening
- * `ablo_databases` times out (a wedged backing store), we attempt to delete it
- * and re-create from scratch. The registry it holds is rebuildable from the
- * server on the next bootstrap, so dropping it is safe.
+ * Deletes an IndexedDB database within a bounded time — the delete counterpart
+ * to {@link openIDBWithTimeout}. It is used to recover from a wedged backing
+ * store: when opening a database times out, the caller can delete it and start
+ * fresh, which is safe for any database whose contents can be rebuilt on the
+ * next load.
  *
- * Like `open`, `deleteDatabase` can hang indefinitely: if another live
- * connection holds the DB it fires `onblocked` and waits, and on a truly stuck
- * store it fires *no* event at all. Both become a bounded rejection here so the
- * caller can fall through to surfacing a real error instead of spinning.
+ * Like an open request, a native delete can hang indefinitely — it fires a
+ * blocked event and waits when another connection still holds the database, and
+ * on a truly stuck store it fires no event at all. Both cases become a bounded,
+ * resolved result here, so the caller never spins.
  *
- * Resolves `true` on a clean delete, `false` if it was blocked or timed out
- * (caller decides whether to retry the open regardless — a no-op delete still
- * leaves us no worse off).
+ * Resolves to `true` on a clean delete and `false` when the delete was blocked
+ * or timed out. Either way the caller can decide whether to retry the open; a
+ * delete that did nothing leaves the store no worse off.
  */
 export declare function deleteIDBWithTimeout(name: string, timeoutMs?: number): Promise<boolean>;

package/dist/core/openIDBWithTimeout.js

@@ -1,27 +1,24 @@
 /**
- * Wrap `indexedDB.open()` with a timeout + loud `onblocked` surfacing so the
- * request can never silently hang the app.
+ * The error raised when opening an IndexedDB database does not complete in a
+ * bounded time. {@link openIDBWithTimeout} throws it in two situations: another
+ * browser tab is holding an older version of the database open and blocking the
+ * upgrade (`reason: 'blocked'`), or the open request produced no result at all
+ * within the timeout (`reason: 'timeout'`).
  *
- * The native `IDBOpenDBRequest` has a nasty failure mode: if another tab is
- * holding an older schema version, the request fires `onblocked` and then
- * waits forever for that tab to close the DB. Neither `onsuccess` nor
- * `onerror` fires — the promise wrapping it never settles and every caller
- * above sits indefinitely.
- *
- * This helper converts that into a real error after a bounded wait, which
- * flows up through `engine.ready()` → `SyncEngineProvider.handleError()` →
- * the error skeleton with a retry button. A visible error is strictly better
- * than a forever-spinner the user can only escape by closing the tab.
+ * The native open request can otherwise hang indefinitely — when a blocking tab
+ * never closes its connection, neither the success nor the error callback fires,
+ * and any code awaiting the open waits forever. Turning that into a thrown error
+ * lets the surrounding application show a recoverable failure instead of an
+ * unbreakable spinner.
  */
 export class IDBOpenTimeoutError extends Error {
     dbName;
     reason;
     /**
-     * Stable, transport-independent code. `toAbloError` preserves a string
-     * `.code`, so this survives the wrap into `AbloError` and reaches the
-     * provider's `onError` intact — letting the app distinguish a wedged-storage
-     * failure (show a recovery screen) from any other bootstrap error without a
-     * brittle message match.
+     * A stable identifier for this failure, independent of the message text. When
+     * this error is wrapped into an {@link AbloError} by `toAbloError`, the string
+     * code is preserved, so error handlers can recognize a wedged-storage failure
+     * and offer a recovery path rather than matching on the message.
      */
     code = 'storage_open_timeout';
     constructor(dbName, reason, message) {
@@ -31,7 +28,11 @@ export class IDBOpenTimeoutError extends Error {
         this.name = 'IDBOpenTimeoutError';
     }
 }
-/** True for the wedged-IndexedDB failure, after it has been wrapped anywhere. */
+/**
+ * Returns true when a caught value is the storage-open-timeout failure. It
+ * detects the failure by its stable `code`, so it still matches after the error
+ * has been wrapped into an {@link AbloError} or another error type.
+ */
 export function isStorageOpenTimeout(err) {
     return (typeof err === 'object' &&
         err !== null &&
@@ -57,13 +58,12 @@ export function openIDBWithTimeout(name, version, options = {}) {
             };
         }
         request.onsuccess = () => {
-            // If we ALREADY timed out (or blocked) and rejected, this is a late
+            // If we already timed out or were blocked and rejected, this is a late
             // success: the native open eventually completed after we gave up. The
-            // resulting connection is orphaned — nobody up the stack holds it, so
-            // nobody will `.close()` it. A leaked open connection holds an IndexedDB
-            // lock that wedges every subsequent open/delete of this DB name (the
-            // exact "ablo_databases open/delete hangs forever with no event" failure
-            // mode). Close it here so a timed-out attempt can't poison the store.
+            // resulting connection is orphaned — nothing up the stack holds it, so
+            // nothing will close it. A leaked open connection holds an IndexedDB lock
+            // that wedges every later open or delete of this database name, so close
+            // it here to keep a timed-out attempt from poisoning the store.
             if (settled) {
                 try {
                     request.result.close();
@@ -74,13 +74,12 @@ export function openIDBWithTimeout(name, version, options = {}) {
                 return;
             }
             const db = request.result;
-            // MANDATORY resilience handler (W3C IndexedDB / MDN): close this
-            // connection the instant any other context wants to upgrade or delete the
-            // DB. Without it, an open connection that ignores `versionchange` blocks
-            // the other context's request indefinitely — the root cause of a wedged
-            // `ablo_databases` that survives reloads (an interrupted transaction's
-            // connection never closes, so every later open/delete hangs with no
-            // event). Auto-closing here makes the store self-releasing.
+            // Required resilience handler per the IndexedDB specification: close this
+            // connection as soon as any other context wants to upgrade or delete the
+            // database. Without it, a connection that ignores `versionchange` blocks
+            // the other context's request indefinitely — a common cause of a database
+            // that stays wedged across reloads. Closing here makes the store release
+            // itself.
             db.onversionchange = () => {
                 try {
                     db.close();
@@ -120,20 +119,20 @@ export function openIDBWithTimeout(name, version, options = {}) {
     });
 }
 /**
- * Bounded `indexedDB.deleteDatabase()` — the delete counterpart of
- * `openIDBWithTimeout`. Used by the meta-DB self-heal: when opening
- * `ablo_databases` times out (a wedged backing store), we attempt to delete it
- * and re-create from scratch. The registry it holds is rebuildable from the
- * server on the next bootstrap, so dropping it is safe.
+ * Deletes an IndexedDB database within a bounded time — the delete counterpart
+ * to {@link openIDBWithTimeout}. It is used to recover from a wedged backing
+ * store: when opening a database times out, the caller can delete it and start
+ * fresh, which is safe for any database whose contents can be rebuilt on the
+ * next load.
  *
- * Like `open`, `deleteDatabase` can hang indefinitely: if another live
- * connection holds the DB it fires `onblocked` and waits, and on a truly stuck
- * store it fires *no* event at all. Both become a bounded rejection here so the
- * caller can fall through to surfacing a real error instead of spinning.
+ * Like an open request, a native delete can hang indefinitely — it fires a
+ * blocked event and waits when another connection still holds the database, and
+ * on a truly stuck store it fires no event at all. Both cases become a bounded,
+ * resolved result here, so the caller never spins.
  *
- * Resolves `true` on a clean delete, `false` if it was blocked or timed out
- * (caller decides whether to retry the open regardless — a no-op delete still
- * leaves us no worse off).
+ * Resolves to `true` on a clean delete and `false` when the delete was blocked
+ * or timed out. Either way the caller can decide whether to retry the open; a
+ * delete that did nothing leaves the store no worse off.
  */
 export function deleteIDBWithTimeout(name, timeoutMs = 5_000) {
     return new Promise((resolve) => {

package/dist/core/queryUtils.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Small, self-contained helpers for sorting, filtering, and binary insertion.
+ * The incrementally-updated views that implement {@link IncrementalView} rely on
+ * these for their ordering and matching, so keeping the rules in one place
+ * ensures every view sorts and filters identically. The functions here work on
+ * plain arrays and values — they hold no reference to models, pools, or the
+ * reactivity system.
+ */
+/**
+ * The interface a live view implements to receive incremental updates: one call
+ * when an entity is added, one when it changes, and one when it is removed. A
+ * view registry holds its views under this non-generic base type so it can keep
+ * views over different entity shapes in a single collection and notify them
+ * uniformly. Because a generic `View<T>` is invariant in `T`, this shared base
+ * is what lets the registry store and dispatch to them without unsafe casts.
+ */
+export interface IncrementalView {
+    handleAdded(entity: Record<string, unknown>): void;
+    handleUpdated(entity: Record<string, unknown>): void;
+    handleRemoved(id: string): void;
+}
+/**
+ * Compares two values for sorting, tolerating `null` and `undefined`, which
+ * always sort last regardless of direction. `dir` is 1 for ascending or -1 for
+ * descending. Returns -1, 0, or 1.
+ */
+export declare function compareValues(a: unknown, b: unknown, dir: 1 | -1): number;
+/**
+ * Finds, by binary search, the index at which `item` should be inserted to keep
+ * an array ordered. The array must already be sorted by `sortKey` in direction
+ * `dir`, using the same rule as {@link compareValues}. Returns that insertion
+ * index.
+ */
+export declare function binaryInsertionIndex<T>(arr: ArrayLike<T>, item: T, sortKey: string, dir: 1 | -1): number;
+/**
+ * Returns true when an entity satisfies a declarative `where` filter: every key
+ * present in `where` must equal the entity's value for that key. A key whose
+ * filter value is `undefined` is skipped, so a partially-filled filter matches
+ * on only its defined keys.
+ */
+export declare function matchesWhere<T extends Record<string, unknown>>(entity: T, where: Partial<T>): boolean;
+/**
+ * Find the index of an entity by id in an array. Returns -1 if not found.
+ */
+export declare function findIndexById<T extends Record<string, unknown>>(arr: ArrayLike<T>, id: string): number;

package/dist/core/queryUtils.js

@@ -0,0 +1,69 @@
+/**
+ * Small, self-contained helpers for sorting, filtering, and binary insertion.
+ * The incrementally-updated views that implement {@link IncrementalView} rely on
+ * these for their ordering and matching, so keeping the rules in one place
+ * ensures every view sorts and filters identically. The functions here work on
+ * plain arrays and values — they hold no reference to models, pools, or the
+ * reactivity system.
+ */
+/**
+ * Compares two values for sorting, tolerating `null` and `undefined`, which
+ * always sort last regardless of direction. `dir` is 1 for ascending or -1 for
+ * descending. Returns -1, 0, or 1.
+ */
+export function compareValues(a, b, dir) {
+    if (a === b)
+        return 0;
+    if (a == null)
+        return 1;
+    if (b == null)
+        return -1;
+    return (a < b ? -1 : 1) * dir;
+}
+/**
+ * Finds, by binary search, the index at which `item` should be inserted to keep
+ * an array ordered. The array must already be sorted by `sortKey` in direction
+ * `dir`, using the same rule as {@link compareValues}. Returns that insertion
+ * index.
+ */
+export function binaryInsertionIndex(arr, item, sortKey, dir) {
+    let lo = 0;
+    let hi = arr.length;
+    const itemVal = item[sortKey];
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        const midVal = arr[mid][sortKey];
+        if (compareValues(midVal, itemVal, dir) <= 0) {
+            lo = mid + 1;
+        }
+        else {
+            hi = mid;
+        }
+    }
+    return lo;
+}
+/**
+ * Returns true when an entity satisfies a declarative `where` filter: every key
+ * present in `where` must equal the entity's value for that key. A key whose
+ * filter value is `undefined` is skipped, so a partially-filled filter matches
+ * on only its defined keys.
+ */
+export function matchesWhere(entity, where) {
+    for (const [key, value] of Object.entries(where)) {
+        if (value === undefined)
+            continue;
+        if (entity[key] !== value)
+            return false;
+    }
+    return true;
+}
+/**
+ * Find the index of an entity by id in an array. Returns -1 if not found.
+ */
+export function findIndexById(arr, id) {
+    for (let i = 0; i < arr.length; i++) {
+        if (arr[i]?.id === id)
+            return i;
+    }
+    return -1;
+}

package/dist/core/storeContract.d.ts

@@ -1,24 +1,25 @@
 /**
- * storeContract — the framework-neutral store contract.
+ * The framework-neutral store contract. {@link SyncStoreContract} is the minimal
+ * store interface the SDK's hooks and mutators are written against, and
+ * {@link BaseSyncedStore} is the concrete class that implements it. Framework
+ * integrations, such as the React bindings, re-export these types, so a hook can
+ * accept any store that satisfies the contract without depending on a particular
+ * UI framework.
  *
- * `SyncStoreContract` is the minimal store interface the SDK's hooks and
- * mutators program against; `BaseSyncedStore` is the concrete engine class
- * that implements it. The contract used to live in `react/context.ts`, which
- * meant the CORE store layer imported its own contract from the React
- * adapter (a module that runtime-imports 'react') — an L2-core →
- * react-integration inversion and a module cycle. It now lives here, in a
- * dependency-free core leaf: `react/context.ts` re-exports these types so
- * React consumers are unchanged, and the core layer never touches 'react'.
- *
- * Everything in this module is type-only — no runtime imports, no runtime
- * exports beyond erased interfaces.
+ * This module is type-only: it has no runtime imports and contributes nothing to
+ * the runtime bundle beyond the erased interface declarations.
  */
 import type { Model } from '../Model.js';
 import type { ModelScope } from '../types/index.js';
 import type { QueryView, QueryViewOptions } from './QueryView.js';
 import type { ViewRegistry } from './ViewRegistry.js';
 import type { ParticipantScope } from '../sync/participants.js';
-/** Sync status for UI binding */
+/**
+ * A snapshot of the client's synchronization state, shaped for binding to UI.
+ * {@link SyncStoreContract.syncStatus} exposes a reactive instance of this, and
+ * the `useSyncStatus()` hook reads its fields to render connection and progress
+ * indicators.
+ */
 export interface SyncStatus {
     state: 'idle' | 'syncing' | 'error' | 'offline' | 'reconnecting';
     progress: number;
@@ -30,39 +31,41 @@ export interface SyncStatus {
     offlineSince?: Date;
 }
 /**
- * A single LOCAL mutation as observed off the commit stream — the substrate
- * the undo system records from. One is emitted per local create/update/
- * delete/archive (remote/collaborator deltas never appear here: they apply
- * through a separate pool path that doesn't queue mutations). `previousData`
- * holds the pre-edit field values (captured from the model's
- * `modifiedProperties` first-old-wins baseline), so an inverse op is fully
- * derivable from the event alone — no separate snapshot pass.
- *
- * This mirrors how Yjs's `UndoManager` derives reverse-ops by observing the
- * doc and Liveblocks' `room.history` records room ops: undo listens to the
- * one place all local writes converge, rather than wrapping the write call.
+ * A single locally-originated mutation, observed as it flows through the commit
+ * stream. The undo system records these to build its inverse operations: one is
+ * emitted per local create, update, delete, or archive. Changes arriving from
+ * other participants do not appear here — they apply through a separate path
+ * that does not queue mutations. Because `previousData` captures the field
+ * values as they were before the edit, each event carries everything needed to
+ * derive its inverse, with no separate snapshot step. A store exposes this
+ * stream through {@link SyncStoreContract.subscribeLocalMutations}.
  */
 export interface LocalMutation {
     type: 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
-    /** Registered model name (e.g. `'SlideLayer'`); resolved to a schema key by the recorder. */
+    /** The registered name of the mutated model, for example `'SlideLayer'`. */
     modelName: string;
     modelId: string;
-    /** New field values (create/update). */
+    /** The new field values, for a create or an update. */
     data?: Record<string, unknown> | null;
-    /** Pre-edit field values (update → inverse patch; delete → full re-create row). */
+    /** The field values as they were before the edit. For an update these form
+     *  the inverse patch; for a delete they hold the full row needed to recreate
+     *  it. */
     previousData?: Record<string, unknown> | null;
 }
 /**
- * Minimal store interface that the SDK hooks need.
- * Consumers provide their concrete store (e.g., SyncedStore) that implements this.
+ * The minimal store interface the SDK's hooks and mutators depend on. Provide a
+ * concrete store that implements it — {@link BaseSyncedStore} is the built-in
+ * implementation — and the hooks work against your store without knowing its
+ * exact type. Optional members exist so lightweight test doubles can implement
+ * only the parts they exercise.
  */
 export interface SyncStoreContract {
     /**
-     * Subscribe to the LOCAL mutation stream (optimistic, pre-ack) for undo
-     * recording. Optional so minimal test doubles can omit it — when absent,
-     * undo scopes simply record nothing. The concrete store
-     * (`BaseSyncedStore`) wires this to the TransactionQueue's
-     * `transaction:created` event. Returns an unsubscribe function.
+     * Subscribes to the stream of local mutations for undo recording, delivering
+     * each optimistic write before it is acknowledged by the server. See
+     * {@link LocalMutation}. Returns a function that removes the subscription.
+     * This is optional: when a store does not implement it, undo scopes simply
+     * record nothing.
      */
     subscribeLocalMutations?(handler: (mutation: LocalMutation) => void): () => void;
     retrieve(modelClass: abstract new (...args: never[]) => Model, id: string): Model | undefined;
@@ -77,17 +80,15 @@ export interface SyncStoreContract {
         data: Model[];
     };
     /**
-     * Save (create or update) one entity. Calling `save` in a tight loop
-     * produces a single wire commit with one `batchIndex`: the SyncClient
-     * debounces IDB persistence and the server push to one microtask, and
-     * TransactionQueue coalesces every transaction staged in the tick into
-     * one batch. There is intentionally no `saveMany` — Zero, Replicache,
-     * and the rest of the local-first lineage all expose one-row writes
-     * and rely on the implicit tick boundary.
+     * Saves one entity, creating it if new or updating it if it already exists.
+     * Calling `save` repeatedly within the same tick is efficient: the writes are
+     * coalesced and persisted, then sent to the server, as a single commit. There
+     * is deliberately no bulk method — issue one `save` per row and let the tick
+     * boundary batch them.
      *
-     * `skipValidation` exists for trusted bulk paths (AI sandbox layer
-     * generation, PPTX import, hydration) where the producer has already
-     * type-checked and per-row Zod is a measurable cost.
+     * Pass `skipValidation` on trusted, high-volume paths — bulk import or
+     * hydration, where the data has already been validated — to skip the per-row
+     * schema check, which is a measurable cost at that volume.
      */
     save(model: Model, options?: {
         skipValidation?: boolean;
@@ -95,7 +96,8 @@ export interface SyncStoreContract {
     delete(model: Model): Promise<void>;
     archive(model: Model): Promise<void>;
     unarchive(model: Model): Promise<void>;
-    /** The ObjectPool — for entity/collection lookups by ID or typename. */
+    /** The in-memory object pool: look up individual entities or collections by
+     *  id or model name, create views, and resolve foreign-key relationships. */
     pool: {
         get(id: string): Model | undefined;
         getByTypeName(typename: string, scope?: ModelScope): Model[];
@@ -106,10 +108,11 @@ export interface SyncStoreContract {
         viewRegistry: ViewRegistry;
     };
     /**
-     * Reactive sync-status getters. Powered by MobX `computed` inside
-     * `BaseSyncedStore`, so they're safe to read in `observer` components
-     * and inside `reaction(() => store.isReady, ...)`. Consumers that
-     * don't want to touch MobX should prefer the `useSyncStatus()` hook.
+     * Reactive getters for the current sync state. In the built-in store these
+     * are backed by observable computeds, so reading them inside a reactive
+     * context — an observer component or a reaction — re-runs that context when
+     * the state changes. Code that prefers not to work with the reactivity system
+     * directly can read the same values through the `useSyncStatus()` hook.
      */
     readonly isReady: boolean;
     readonly isSyncing: boolean;
@@ -118,14 +121,13 @@ export interface SyncStoreContract {
     readonly isError: boolean;
     readonly hasUnsyncedChanges: boolean;
     /**
-     * Area-of-interest (dynamic read subscription). `enterScope`/`leaveScope`
-     * move the connection's read interest as the user navigates (open/close a
-     * deck, sheet, doc); `pinScope`/`unpinScope` express prominence (an active
-     * claim keeps a group subscribed). Each resolves the scope through the same
-     * resolver the claim path uses, so read interest and write claims agree on
-     * the sync-group string. Optional so minimal test doubles can omit them;
-     * no-ops before the socket exists. The concrete store (`BaseSyncedStore`)
-     * forwards to its `AreaOfInterestManager`.
+     * Manages the connection's area of interest — the dynamic set of data it
+     * subscribes to. Call `enterScope` and `leaveScope` to move that interest as
+     * the user navigates between documents, and `pinScope` and `unpinScope` to
+     * keep a scope subscribed while it stays important, such as while a claim is
+     * held. Every scope resolves through the same resolver the claim path uses, so
+     * read subscriptions and write claims always agree on which group they refer
+     * to. These are optional and do nothing until the connection is open.
      */
     enterScope?(scope: ParticipantScope, opts?: {
         hydrate?: boolean;
@@ -134,10 +136,10 @@ export interface SyncStoreContract {
     pinScope?(scope: ParticipantScope): Promise<void>;
     unpinScope?(scope: ParticipantScope): Promise<void>;
     /**
-     * Raw MobX-observable `SyncStatus` record. `useSyncStatus()` reads
-     * `state`, `progress`, `pendingChanges`, `isSessionError`, `error`
-     * from this to build its tagged union. Exposed on the contract so
-     * consumer-facing hooks and test doubles can manipulate it directly.
+     * The full reactive {@link SyncStatus} record. The `useSyncStatus()` hook
+     * reads its fields — `state`, `progress`, `pendingChanges`, `isSessionError`,
+     * and `error` — to present the current sync state. It is part of the contract
+     * so hooks and test doubles can read or set it directly.
      */
     readonly syncStatus: SyncStatus;
 }

package/dist/core/storeContract.js

@@ -1,16 +1,12 @@
 /**
- * storeContract — the framework-neutral store contract.
+ * The framework-neutral store contract. {@link SyncStoreContract} is the minimal
+ * store interface the SDK's hooks and mutators are written against, and
+ * {@link BaseSyncedStore} is the concrete class that implements it. Framework
+ * integrations, such as the React bindings, re-export these types, so a hook can
+ * accept any store that satisfies the contract without depending on a particular
+ * UI framework.
  *
- * `SyncStoreContract` is the minimal store interface the SDK's hooks and
- * mutators program against; `BaseSyncedStore` is the concrete engine class
- * that implements it. The contract used to live in `react/context.ts`, which
- * meant the CORE store layer imported its own contract from the React
- * adapter (a module that runtime-imports 'react') — an L2-core →
- * react-integration inversion and a module cycle. It now lives here, in a
- * dependency-free core leaf: `react/context.ts` re-exports these types so
- * React consumers are unchanged, and the core layer never touches 'react'.
- *
- * Everything in this module is type-only — no runtime imports, no runtime
- * exports beyond erased interfaces.
+ * This module is type-only: it has no runtime imports and contributes nothing to
+ * the runtime bundle beyond the erased interface declarations.
  */
 export {};

package/dist/environment.d.ts

@@ -1,12 +1,40 @@
 import { z } from 'zod';
+/**
+ * The two environments an Ablo project runs in: `production` for live data and
+ * `sandbox` for isolated test data. Every credential and every stored row
+ * belongs to exactly one of them.
+ */
 export declare const ENVIRONMENTS: readonly ["production", "sandbox"];
+/**
+ * How an environment is spelled inside an API-key prefix: a `live` key acts on
+ * the production environment and a `test` key acts on the sandbox. Convert
+ * between this spelling and {@link Environment} with
+ * {@link environmentFromKeyPrefix} and {@link environmentToKeyPrefix}.
+ */
 export type KeyPrefixEnvironment = 'live' | 'test';
+/** A Zod schema that validates a value as one of the {@link ENVIRONMENTS}. */
 export declare const environmentSchema: z.ZodEnum<{
     production: "production";
     sandbox: "sandbox";
 }>;
+/** One of the {@link ENVIRONMENTS} — either `'production'` or `'sandbox'`. */
 export type Environment = z.infer<typeof environmentSchema>;
+/**
+ * Coerces an untrusted value into a valid {@link Environment}, returning
+ * `fallback` (which defaults to `'production'`) when the value is not a
+ * recognized environment. Use it when reading an environment from configuration
+ * or off the wire.
+ */
 export declare function normalizeEnvironment(value: unknown, fallback?: Environment): Environment;
+/**
+ * Maps an API-key prefix spelling to its {@link Environment}: a `'test'` key
+ * operates on the sandbox, and anything else on production.
+ */
 export declare function environmentFromKeyPrefix(value: KeyPrefixEnvironment): Environment;
+/**
+ * Maps an {@link Environment} to the spelling used in an API-key prefix: the
+ * sandbox is `'test'` and production is `'live'`.
+ */
 export declare function environmentToKeyPrefix(value: Environment): KeyPrefixEnvironment;
+/** Returns true when the given environment is the sandbox. */
 export declare function isSandboxEnvironment(value: Environment): boolean;