@abloatai/ablo 0.3.0

package/dist/react/useCurrentUserId.js

@@ -0,0 +1,33 @@
+'use client';
+import { useContext } from 'react';
+import { AbloInternalContext } from './internalContext.js';
+import { AbloValidationError } from '../errors.js';
+/**
+ * Returns the app user ID passed to the nearest `<AbloProvider>`, when
+ * the app chose to provide one.
+ *
+ * Hosted Ablo identity is resolved server-side from the API key, session,
+ * or capability token. This hook is only for app-owned fields like
+ * `assigneeId`; it is not required for Ablo sync to connect.
+ *
+ * Use this in leaf components that need the current user ID for
+ * mutation payloads, presence labels, permission checks, etc.
+ * @example
+ * function TaskRow({ id }) {
+ *   const userId = useCurrentUserId();
+ *   const ablo = useAblo();
+ *   if (!userId) return null;
+ *   return <button onClick={() => ablo?.tasks.update(id, { assigneeId: userId })}>
+ *     Assign to me
+ *   </button>;
+ * }
+ */
+export function useCurrentUserId() {
+    const ctx = useContext(AbloInternalContext);
+    if (!ctx) {
+        throw new AbloValidationError('useCurrentUserId: no <AbloProvider> mounted above this component. ' +
+            'Wrap your tree with <AbloProvider ...> from ' +
+            '@ablo/sync-engine/react.', { code: 'no_ablo_provider' });
+    }
+    return ctx.currentUserId;
+}

package/dist/react/useErrorListener.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Register an imperative callback that fires whenever the provider
+ * surfaces an error. Covers engine errors (bootstrap failures,
+ * mutation rejections), WebSocket errors, and uncaught exceptions
+ * inside `postBootstrap` hooks.
+ *
+ * Use this for telemetry (Sentry, Datadog), user-facing toasts, or
+ * any side effect that should NOT trigger a re-render. The listener
+ * is stored in a ref, so re-renders don't thrash the subscription.
+ *
+ * @example
+ * function ErrorToaster() {
+ *   useErrorListener((err) => {
+ *     toast.error(err.message);
+ *     Sentry.captureException(err);
+ *   });
+ *   return null;
+ * }
+ */
+export declare function useErrorListener(listener: (error: Error) => void): void;

package/dist/react/useErrorListener.js

@@ -0,0 +1,39 @@
+'use client';
+import { useContext, useEffect, useRef } from 'react';
+import { AbloInternalContext } from './internalContext.js';
+import { AbloValidationError } from '../errors.js';
+/**
+ * Register an imperative callback that fires whenever the provider
+ * surfaces an error. Covers engine errors (bootstrap failures,
+ * mutation rejections), WebSocket errors, and uncaught exceptions
+ * inside `postBootstrap` hooks.
+ *
+ * Use this for telemetry (Sentry, Datadog), user-facing toasts, or
+ * any side effect that should NOT trigger a re-render. The listener
+ * is stored in a ref, so re-renders don't thrash the subscription.
+ *
+ * @example
+ * function ErrorToaster() {
+ *   useErrorListener((err) => {
+ *     toast.error(err.message);
+ *     Sentry.captureException(err);
+ *   });
+ *   return null;
+ * }
+ */
+export function useErrorListener(listener) {
+    const ctx = useContext(AbloInternalContext);
+    if (!ctx) {
+        throw new AbloValidationError('useErrorListener: no <AbloProvider> mounted above this component. ' +
+            'Wrap your tree with <AbloProvider ...> from @ablo/sync-engine/react.', { code: 'no_ablo_provider' });
+    }
+    // Stash the latest callback in a ref so the effect subscription
+    // stays stable across renders. Matches the `useEventCallback`
+    // pattern: late-bind the listener so callers can pass inline
+    // arrows without thrashing the subscription.
+    const ref = useRef(listener);
+    ref.current = listener;
+    useEffect(() => {
+        return ctx.subscribeError((err) => ref.current(err));
+    }, [ctx]);
+}

package/dist/react/useIntent.d.ts

@@ -0,0 +1,29 @@
+import type { ResolveIntents } from '../types/global.js';
+/**
+ * Named-intent invoker, typed via `ResolveIntents[IntentName]`.
+ *
+ * The consumer declares their intent vocabulary in the global:
+ *
+ * ```ts
+ * declare global {
+ *   interface AbloSync {
+ *     Intents: {
+ *       editLayer: { slideId: string; layerId: string };
+ *       generateWithAI: { entityId: string; tool: string };
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * Then `useIntent('editLayer')` returns a function whose sole argument
+ * is the `editLayer` claim shape — no runtime checks, purely compile-
+ * time narrowing.
+ *
+ * The SDK doesn't own what happens next: the `beginIntent` function on
+ * the React context (supplied via `SyncProvider`) is where the intent
+ * claim turns into a network effect. A Node-backed consumer wires it
+ * through `SyncAgent.beginIntent`; a browser-backed consumer may
+ * broadcast it through their own WebSocket. This hook is pure sugar
+ * that adds the typed name + claim narrowing.
+ */
+export declare function useIntent<Name extends keyof ResolveIntents & string>(intentName: Name): (claim: ResolveIntents[Name]) => unknown;

package/dist/react/useIntent.js

@@ -0,0 +1,42 @@
+'use client';
+import { useCallback } from 'react';
+import { useSyncContext } from './context.js';
+import { AbloValidationError } from '../errors.js';
+/**
+ * Named-intent invoker, typed via `ResolveIntents[IntentName]`.
+ *
+ * The consumer declares their intent vocabulary in the global:
+ *
+ * ```ts
+ * declare global {
+ *   interface AbloSync {
+ *     Intents: {
+ *       editLayer: { slideId: string; layerId: string };
+ *       generateWithAI: { entityId: string; tool: string };
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * Then `useIntent('editLayer')` returns a function whose sole argument
+ * is the `editLayer` claim shape — no runtime checks, purely compile-
+ * time narrowing.
+ *
+ * The SDK doesn't own what happens next: the `beginIntent` function on
+ * the React context (supplied via `SyncProvider`) is where the intent
+ * claim turns into a network effect. A Node-backed consumer wires it
+ * through `SyncAgent.beginIntent`; a browser-backed consumer may
+ * broadcast it through their own WebSocket. This hook is pure sugar
+ * that adds the typed name + claim narrowing.
+ */
+export function useIntent(intentName) {
+    const { beginIntent } = useSyncContext();
+    return useCallback((claim) => {
+        if (!beginIntent) {
+            throw new AbloValidationError(`useIntent: no \`beginIntent\` wired into SyncProvider. Pass ` +
+                `a \`beginIntent\` prop (typically bound to your transport) ` +
+                `to enable intent invocations.`, { code: 'intent_not_wired' });
+        }
+        return beginIntent(intentName, claim);
+    }, [beginIntent, intentName]);
+}

package/dist/react/useMutate.d.ts

@@ -0,0 +1,83 @@
+import type { Schema, InferModel, InferCreate } from '../schema/schema.js';
+import type { ResolveSchema } from '../types/global.js';
+import type { SyncStoreContract } from './context.js';
+type GlobalMutateKey = ResolveSchema extends {
+    models: infer M;
+} ? keyof M & string : string;
+type GlobalMutateActions<K extends string> = ResolveSchema extends Schema ? K extends keyof ResolveSchema['models'] & string ? MutateActions<ResolveSchema, K> : MutateActions<Schema, string> : MutateActions<Schema, string>;
+/**
+ * Compatibility mutation hook. Returns CRUD methods for a single model type.
+ *
+ * Prefer `useAblo()` and call `ablo.<model>.create/update/delete` inside
+ * callbacks for new integrations. This hook remains for older string-keyed code.
+ *
+ * @example
+ * import { schema } from '@ablo/schema';
+ * import { useMutate } from '@ablo/sync-engine/react';
+ *
+ * const tasks = useMutate(schema, 'tasks');
+ *
+ * // Create — fields are type-checked against the schema's Zod shape
+ * await tasks.create({ title: 'Fix bug', status: 'todo', projectId });
+ *
+ * // Update — id + partial changes, no need to hold a model instance
+ * await tasks.update({ id: task.id, status: 'done', completedAt: new Date() });
+ *
+ * // Delete / archive / unarchive — by id
+ * await tasks.delete(task.id);
+ * await tasks.archive(task.id);
+ *
+ * Mirrors the Zero pattern: `zero.mutate.task.update({ id, status: 'done' })`.
+ */
+/**
+ * `create` / `update` / `delete` are overloaded: pass one row or an
+ * array. Drizzle and Prisma use the same shape (`db.insert(table).values(rowOrRows)`).
+ * Avoids the `*Many` suffix while keeping the semantics: every entry in
+ * an array call lands in the same synchronous tick (Promise.all under
+ * the hood), so the microtask coalescer in `TransactionQueue` collapses
+ * N pushes into one wire commit with one `batchIndex` — structurally
+ * identical to Zero's mutator-boundary commit.
+ */
+type UpdatePatch<S extends Schema, K extends keyof S['models'] & string> = {
+    id: string;
+} & Partial<InferModel<S, K>>;
+export interface MutateActions<S extends Schema, K extends keyof S['models'] & string> {
+    /**
+     * Create one entity, or an array of entities in a single tick. ID,
+     * createdAt, updatedAt, organizationId default automatically per row.
+     */
+    create(data: InferCreate<S, K>): Promise<InferModel<S, K>>;
+    create(data: InferCreate<S, K>[]): Promise<InferModel<S, K>[]>;
+    /**
+     * Update one row, or an array of rows in a single tick. Each patch is
+     * `{ id, ...changes }` — missing ids throw. Schema-generated models
+     * are MobX-observable, so direct assignment fires reactivity.
+     */
+    update(patch: UpdatePatch<S, K>): Promise<InferModel<S, K>>;
+    update(patches: UpdatePatch<S, K>[]): Promise<InferModel<S, K>[]>;
+    /**
+     * Delete one row by id, or an array of ids in a single tick. Missing
+     * ids are silently ignored.
+     */
+    delete(id: string): Promise<void>;
+    delete(ids: string[]): Promise<void>;
+    /** Soft-archive by ID. */
+    archive: (id: string) => Promise<void>;
+    /** Restore an archived entity by ID. */
+    unarchive: (id: string) => Promise<void>;
+}
+/**
+ * Pure factory — testable without React. The hook just wraps this in
+ * useMemo with the React context.
+ */
+export declare function createMutateActions<S extends Schema, K extends keyof S['models'] & string>(schema: S, modelKey: K, store: SyncStoreContract, organizationId: string): MutateActions<S, K>;
+/** @deprecated Prefer `useAblo()` plus `ablo.<model>.create/update/delete`. */
+export declare function useMutate<S extends Schema, K extends keyof S['models'] & string>(schema: S, modelKey: K): MutateActions<S, K>;
+/** Typed CRUD via the `AbloSync` global augmentation. The schema is
+ * resolved from the `SyncProvider`'s context — consumer doesn't pass it
+ * at the call site.
+ *
+ * @deprecated Prefer `useAblo()` plus `ablo.<model>.create/update/delete`.
+ */
+export declare function useMutate<K extends GlobalMutateKey>(modelKey: K): GlobalMutateActions<K>;
+export {};

package/dist/react/useMutate.js

@@ -0,0 +1,122 @@
+'use client';
+import { useMemo } from 'react';
+import { Model, modelAsRow } from '../Model.js';
+import { AbloValidationError } from '../errors.js';
+import { useSyncContext } from './context.js';
+/**
+ * Pure factory — testable without React. The hook just wraps this in
+ * useMemo with the React context.
+ */
+export function createMutateActions(schema, modelKey, store, organizationId) {
+    const modelDef = schema.models[modelKey];
+    const typename = modelDef?.typename ?? modelKey;
+    // Materialise one input row into a Model and stage a save. The default
+    // fields land here once so create-of-one and create-of-array share the
+    // same defaulting logic.
+    const buildModelForCreate = (data, now) => {
+        const record = data;
+        const fullData = {
+            ...record,
+            __typename: typename,
+            id: record.id ?? Model.generateId(),
+            organizationId: record.organizationId ?? organizationId,
+            createdAt: record.createdAt ?? now,
+            updatedAt: record.updatedAt ?? now,
+        };
+        const model = store.pool.createFromData(fullData);
+        if (!model) {
+            throw new AbloValidationError(`useMutate: failed to create ${typename} — no constructor in registry`, { code: 'mutate_create_unknown_model' });
+        }
+        return model;
+    };
+    // Apply a patch onto an existing pool model. Returns the model.
+    const applyPatch = (patch, now) => {
+        const { id, ...changes } = patch;
+        const model = store.pool.get(id);
+        if (!model) {
+            throw new AbloValidationError(`useMutate: ${typename} with id "${id}" not found in pool`, { code: 'mutate_update_entity_not_found' });
+        }
+        // Schema-derived patch keys are validated at the call-site type
+        // signature (`UpdatePatch<S, K>`); writes here are dynamic-class
+        // field assignments. `Reflect.set` is the typed bridge — Model
+        // doesn't carry an index signature for arbitrary string keys, but
+        // the dynamic field installation in `createDynamicModelClass`
+        // guarantees these keys resolve at runtime.
+        for (const [fieldName, value] of Object.entries(changes)) {
+            Reflect.set(model, fieldName, value);
+        }
+        Reflect.set(model, 'updatedAt', now);
+        return model;
+    };
+    return {
+        // Overloaded — runtime check on `Array.isArray` decides shape. Both
+        // branches stage via `Promise.all` so the microtask coalescer in
+        // `TransactionQueue` collapses N pushes into one wire commit.
+        create: (async (data) => {
+            const now = new Date();
+            if (Array.isArray(data)) {
+                if (data.length === 0)
+                    return [];
+                const models = data.map((d) => buildModelForCreate(d, now));
+                await Promise.all(models.map((m) => store.save(m)));
+                return models.map((m) => modelAsRow(m));
+            }
+            const model = buildModelForCreate(data, now);
+            await store.save(model);
+            return modelAsRow(model);
+        }),
+        update: (async (patch) => {
+            const now = new Date();
+            if (Array.isArray(patch)) {
+                if (patch.length === 0)
+                    return [];
+                const models = patch.map((p) => applyPatch(p, now));
+                await Promise.all(models.map((m) => store.save(m)));
+                return models.map((m) => modelAsRow(m));
+            }
+            const model = applyPatch(patch, now);
+            await store.save(model);
+            return modelAsRow(model);
+        }),
+        delete: (async (idOrIds) => {
+            if (Array.isArray(idOrIds)) {
+                if (idOrIds.length === 0)
+                    return;
+                const models = [];
+                for (const id of idOrIds) {
+                    const m = store.pool.get(id);
+                    if (m)
+                        models.push(m);
+                }
+                await Promise.all(models.map((m) => store.delete(m)));
+                return;
+            }
+            const model = store.pool.get(idOrIds);
+            if (!model)
+                return;
+            await store.delete(model);
+        }),
+        archive: async (id) => {
+            const model = store.pool.get(id);
+            if (!model)
+                return;
+            await store.archive(model);
+        },
+        unarchive: async (id) => {
+            const model = store.pool.get(id);
+            if (!model)
+                return;
+            await store.unarchive(model);
+        },
+    };
+}
+export function useMutate(schemaOrKey, maybeKey) {
+    const { store, organizationId, schema: ctxSchema } = useSyncContext();
+    const resolvedSchema = typeof schemaOrKey === 'string' ? ctxSchema : schemaOrKey;
+    const resolvedKey = typeof schemaOrKey === 'string' ? schemaOrKey : maybeKey;
+    if (!resolvedSchema) {
+        throw new AbloValidationError('useMutate: no schema available. Pass the schema as the first arg ' +
+            'or wire SyncProvider with a `schema` prop when using the zero-arg overload.', { code: 'mutate_schema_missing' });
+    }
+    return useMemo(() => createMutateActions(resolvedSchema, resolvedKey, store, organizationId), [store, organizationId, resolvedSchema, resolvedKey]);
+}

package/dist/react/useMutationFailureListener.d.ts

@@ -0,0 +1,26 @@
+import type { Transaction } from '../transactions/TransactionQueue.js';
+export interface MutationFailurePayload {
+    transaction: Transaction;
+    error: Error;
+    permanent?: boolean;
+}
+/**
+ * Register a side-effect listener for mutation failures. Fires whenever
+ * the underlying transaction queue rolls back an optimistic write —
+ * permanent rejections (validation, FK, auth) and exhausted-retry
+ * rollbacks (connection lost mid-burst).
+ *
+ * Use this to mount a single `<MutationFailureBoundary>` near the app
+ * shell that turns silent pool rollbacks into toasts / banners. The
+ * listener is stored in a ref so re-renders don't thrash the
+ * subscription — matches `useErrorListener`.
+ *
+ * @example
+ * function MutationFailureBoundary() {
+ *   useMutationFailureListener(({ transaction, error }) => {
+ *     toast.error(`Couldn't save ${transaction.modelName}: ${error.message}`);
+ *   });
+ *   return null;
+ * }
+ */
+export declare function useMutationFailureListener(listener: (payload: MutationFailurePayload) => void): void;

package/dist/react/useMutationFailureListener.js

@@ -0,0 +1,38 @@
+'use client';
+import { useContext, useEffect, useRef } from 'react';
+import { AbloInternalContext } from './internalContext.js';
+import { AbloValidationError } from '../errors.js';
+/**
+ * Register a side-effect listener for mutation failures. Fires whenever
+ * the underlying transaction queue rolls back an optimistic write —
+ * permanent rejections (validation, FK, auth) and exhausted-retry
+ * rollbacks (connection lost mid-burst).
+ *
+ * Use this to mount a single `<MutationFailureBoundary>` near the app
+ * shell that turns silent pool rollbacks into toasts / banners. The
+ * listener is stored in a ref so re-renders don't thrash the
+ * subscription — matches `useErrorListener`.
+ *
+ * @example
+ * function MutationFailureBoundary() {
+ *   useMutationFailureListener(({ transaction, error }) => {
+ *     toast.error(`Couldn't save ${transaction.modelName}: ${error.message}`);
+ *   });
+ *   return null;
+ * }
+ */
+export function useMutationFailureListener(listener) {
+    const ctx = useContext(AbloInternalContext);
+    if (!ctx) {
+        throw new AbloValidationError('useMutationFailureListener: no <AbloProvider> mounted above this component. ' +
+            'Wrap your tree with <AbloProvider ...> from @ablo/sync-engine/react.', { code: 'no_ablo_provider' });
+    }
+    const ref = useRef(listener);
+    ref.current = listener;
+    useEffect(() => {
+        const engine = ctx.engine;
+        if (!engine)
+            return;
+        return engine.onMutationFailure((payload) => ref.current(payload));
+    }, [ctx, ctx.engine]);
+}

package/dist/react/useMutators.d.ts

@@ -0,0 +1,56 @@
+import type { Schema } from '../schema/schema.js';
+import type { MutatorDefs } from '../mutators/defineMutators.js';
+import type { UndoScope } from '../mutators/UndoManager.js';
+import type { ResolveSchema } from '../types/global.js';
+/**
+ * useMutators — turn a `defineMutators` tree into callable invokers.
+ *
+ * The returned object mirrors the mutator tree one-to-one, but each leaf is
+ * now a `(args) => Promise<TResult>` function. Internally each invocation:
+ *   1. Builds a fresh `Transaction` bound to the current store/org context.
+ *   2. Calls the user's mutator with `{ tx, args }`.
+ *   3. Returns the mutator's resolved value.
+ *
+ * V1 error handling: if the mutator throws, we `console.error` + rethrow.
+ * Any writes that already dispatched stay in place (no rollback). That
+ * matches the existing behaviour of batch helpers like `saveManyOptimized`
+ * and keeps the contract honest — consumers can layer their own try/catch
+ * + compensating writes until V2 adds atomicity.
+ */
+/**
+ * Map a `MutatorFn` onto its invoker form — strip `tx`, keep `args`/return.
+ *
+ * Uses nested `infer O` so the `args`/`result` types are extracted from the
+ * function signature without binding the `tx` parameter to a specific
+ * `Transaction<S>` variance. Function parameters are contravariant, so a
+ * match against `MutatorFn<Schema>` would reject mutators declared against
+ * a narrower schema (e.g. `Transaction<typeof appSchema>`). The two-step
+ * inference sidesteps that without resorting to `any`/`unknown` placeholders.
+ */
+export type InvokerFor<F> = F extends (options: infer O) => Promise<infer R> ? O extends {
+    args: infer A;
+} ? (args: A) => Promise<R> : never : never;
+/**
+ * The hook's return shape: same tree as the input `MutatorDefs`, every leaf
+ * rewritten to its invoker form.
+ */
+export type MutatorInvokers<M> = {
+    [K in keyof M]: {
+        [N in keyof M[K]]: InvokerFor<M[K][N]>;
+    };
+};
+/**
+ * Options passed to `useMutators`. When `undoScope` is set, every mutator
+ * invocation is wrapped in a `RecordingTransaction` and its inverses are
+ * pushed to the scope as one undo entry.
+ */
+export interface UseMutatorsOptions<S extends Schema> {
+    /** Target undo scope for recording inverses. Omit to disable recording. */
+    undoScope?: UndoScope<S>;
+}
+/** Mutator invokers (explicit schema arg). */
+export declare function useMutators<S extends Schema, M extends MutatorDefs<S>>(schema: S, mutators: M, options?: UseMutatorsOptions<S>): MutatorInvokers<M>;
+/** Mutator invokers via the `AbloSync` global augmentation. Schema comes
+ * from the `SyncProvider`'s context; the mutator tree is typed against
+ * `ResolveSchema` at the call site. */
+export declare function useMutators<M extends ResolveSchema extends Schema ? MutatorDefs<ResolveSchema> : MutatorDefs<Schema>>(mutators: M, options?: UseMutatorsOptions<ResolveSchema extends Schema ? ResolveSchema : Schema>): MutatorInvokers<M>;

package/dist/react/useMutators.js

@@ -0,0 +1,66 @@
+'use client';
+import { useMemo } from 'react';
+import { createTransaction } from '../mutators/Transaction.js';
+import { createRecordingTransaction } from '../mutators/RecordingTransaction.js';
+import { useSyncContext } from './context.js';
+import { AbloValidationError } from '../errors.js';
+import { getContext } from '../context.js';
+export function useMutators(schemaOrMutators, mutatorsOrOptions, maybeOptions) {
+    const { store, organizationId, schema: ctxSchema } = useSyncContext();
+    // Disambiguate: explicit-schema path has the schema object in first slot;
+    // the global-resolved path has the mutator tree there. A schema object
+    // has a `.models` property; a mutator tree doesn't.
+    const isExplicit = typeof schemaOrMutators === 'object' &&
+        schemaOrMutators !== null &&
+        'models' in schemaOrMutators;
+    const schema = isExplicit ? schemaOrMutators : ctxSchema;
+    const mutators = (isExplicit ? mutatorsOrOptions : schemaOrMutators);
+    const options = (isExplicit ? maybeOptions : mutatorsOrOptions);
+    if (!schema) {
+        throw new AbloValidationError('useMutators: no schema available. Pass the schema as the first arg ' +
+            'or wire SyncProvider with a `schema` prop when using the zero-arg overload.', { code: 'mutators_schema_missing' });
+    }
+    const { undoScope } = options ?? {};
+    return useMemo(() => {
+        const out = {};
+        for (const modelKey of Object.keys(mutators)) {
+            const group = mutators[modelKey];
+            if (!group)
+                continue;
+            const invokers = {};
+            for (const mutatorName of Object.keys(group)) {
+                const fn = group[mutatorName];
+                const label = `${String(modelKey)}.${mutatorName}`;
+                invokers[mutatorName] = async (args) => {
+                    // Recording path: wrap the transaction so each write snapshots its
+                    // inverse. On success, push the captured entry to the scope.
+                    if (undoScope) {
+                        const recording = createRecordingTransaction(schema, store, organizationId);
+                        try {
+                            const result = await fn({ tx: recording.tx, args });
+                            const entry = recording.getEntry(label);
+                            if (entry)
+                                undoScope.record(entry);
+                            return result;
+                        }
+                        catch (err) {
+                            getContext().logger.error(`[useMutators] mutator "${label}" threw`, { error: err });
+                            throw err;
+                        }
+                    }
+                    // Non-recording path — plain transaction, identical to pre-undo V1.
+                    const tx = createTransaction(schema, store, organizationId);
+                    try {
+                        return await fn({ tx, args });
+                    }
+                    catch (err) {
+                        getContext().logger.error(`[useMutators] mutator "${label}" threw`, { error: err });
+                        throw err;
+                    }
+                };
+            }
+            out[modelKey] = invokers;
+        }
+        return out;
+    }, [schema, mutators, store, organizationId, undoScope]);
+}

package/dist/react/usePresence.d.ts

@@ -0,0 +1,32 @@
+import type { ResolvePresence } from '../types/global.js';
+/**
+ * Read the consumer-supplied presence state with `ResolvePresence`d
+ * typing — the shape the consumer declared in
+ * `declare global { interface AbloSync { Presence: ... } }`.
+ *
+ * The SDK doesn't own a presence wire format. Consumers plug whatever
+ * backs their cursors, status, or activity (a MobX store, a custom
+ * WebSocket channel, `SyncAgent` in Node, a Zustand slice) via the
+ * `presence` prop on `SyncProvider`. This hook returns it typed.
+ *
+ * ```ts
+ * // apps/your-app/src/ablo-sync.d.ts
+ * declare global {
+ *   interface AbloSync {
+ *     Presence: { cursor: { x: number; y: number } | null; status: 'away' | 'online' };
+ *   }
+ * }
+ *
+ * // consumer's <SyncProvider> wiring
+ * <SyncProvider store={store} organizationId={orgId} presence={presenceStore}>
+ *
+ * // any component
+ * const presence = usePresence();
+ * presence?.cursor?.x; // fully typed
+ * ```
+ *
+ * Returns `undefined` when no provider-level presence source is wired —
+ * consumers can narrow with a guard or configure a default in their
+ * provider.
+ */
+export declare function usePresence(): ResolvePresence | undefined;

package/dist/react/usePresence.js

@@ -0,0 +1,41 @@
+'use client';
+import { useSyncContext } from './context.js';
+/**
+ * Read the consumer-supplied presence state with `ResolvePresence`d
+ * typing — the shape the consumer declared in
+ * `declare global { interface AbloSync { Presence: ... } }`.
+ *
+ * The SDK doesn't own a presence wire format. Consumers plug whatever
+ * backs their cursors, status, or activity (a MobX store, a custom
+ * WebSocket channel, `SyncAgent` in Node, a Zustand slice) via the
+ * `presence` prop on `SyncProvider`. This hook returns it typed.
+ *
+ * ```ts
+ * // apps/your-app/src/ablo-sync.d.ts
+ * declare global {
+ *   interface AbloSync {
+ *     Presence: { cursor: { x: number; y: number } | null; status: 'away' | 'online' };
+ *   }
+ * }
+ *
+ * // consumer's <SyncProvider> wiring
+ * <SyncProvider store={store} organizationId={orgId} presence={presenceStore}>
+ *
+ * // any component
+ * const presence = usePresence();
+ * presence?.cursor?.x; // fully typed
+ * ```
+ *
+ * Returns `undefined` when no provider-level presence source is wired —
+ * consumers can narrow with a guard or configure a default in their
+ * provider.
+ */
+export function usePresence() {
+    const ctx = useSyncContext();
+    // The runtime value is whatever the consumer passed to `SyncProvider`.
+    // The type assertion reflects the consumer's declared global, which
+    // the hook can't verify at runtime — but the consumer controls both
+    // ends (the global declaration and the provider prop) so this is a
+    // single-source-of-truth contract, not blind trust.
+    return ctx.presence;
+}