@abloatai/ablo 0.7.0 → 0.9.0

package/dist/mutators/inverseOp.d.ts

@@ -0,0 +1,129 @@
+/**
+ * inverseOp.ts — the reversible-operation model for the undo system,
+ * expressed as Zod schemas.
+ *
+ * Why schemas (not bare TS types):
+ *   - Single source of truth. The `InverseOp` / `UndoEntry` TypeScript types
+ *     are *derived* from these schemas (`z.infer`), so the wire shape and the
+ *     static type can't drift.
+ *   - A real validation boundary. Inverse ops are stored as plain JSON-shaped
+ *     records (model keys + row data) so the undo manager stays schema-agnostic
+ *     — it replays them through a strongly-typed transaction it doesn't own.
+ *     That JSON boundary is exactly where a runtime check belongs, and is the
+ *     seam a future cross-session persistence layer (IndexedDB-backed history)
+ *     would deserialize through. `parseUndoEntry` is that gate.
+ *
+ * The op kinds mirror the mutator surface 1:1 — single (`create`/`update`/
+ * `delete`) and batch (`createMany`/`updateMany`/`deleteMany`) — so a recorded
+ * entry is symmetric with what was originally invoked.
+ */
+import { z } from 'zod';
+/**
+ * A single reversible operation. Discriminated on `kind` so a malformed op
+ * fails fast with a precise path (e.g. `inverses[2].patch.id`) rather than a
+ * vague union mismatch. Model keys/data are strings/records — the manager is
+ * schema-agnostic; the transaction it replays through is schema-typed.
+ */
+export declare const inverseOpSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"create">;
+    modelKey: z.ZodString;
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"update">;
+    modelKey: z.ZodString;
+    patch: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$catchall<z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"delete">;
+    modelKey: z.ZodString;
+    id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"createMany">;
+    modelKey: z.ZodString;
+    data: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"updateMany">;
+    modelKey: z.ZodString;
+    patches: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$catchall<z.ZodUnknown>>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"deleteMany">;
+    modelKey: z.ZodString;
+    ids: z.ZodArray<z.ZodString>;
+}, z.core.$strip>], "kind">;
+/** One undo entry = one mutator invocation's inverses + paired forwards. */
+export declare const undoEntrySchema: z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    inverses: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"create">;
+        modelKey: z.ZodString;
+        data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"update">;
+        modelKey: z.ZodString;
+        patch: z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$catchall<z.ZodUnknown>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"delete">;
+        modelKey: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"createMany">;
+        modelKey: z.ZodString;
+        data: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"updateMany">;
+        modelKey: z.ZodString;
+        patches: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$catchall<z.ZodUnknown>>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"deleteMany">;
+        modelKey: z.ZodString;
+        ids: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>], "kind">>;
+    forwards: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"create">;
+        modelKey: z.ZodString;
+        data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"update">;
+        modelKey: z.ZodString;
+        patch: z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$catchall<z.ZodUnknown>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"delete">;
+        modelKey: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"createMany">;
+        modelKey: z.ZodString;
+        data: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"updateMany">;
+        modelKey: z.ZodString;
+        patches: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$catchall<z.ZodUnknown>>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"deleteMany">;
+        modelKey: z.ZodString;
+        ids: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>], "kind">>;
+}, z.core.$strip>;
+/** A single reversible operation (schema-derived). */
+export type InverseOp = z.infer<typeof inverseOpSchema>;
+/** One undo/redo stack entry (schema-derived). */
+export type UndoEntry = z.infer<typeof undoEntrySchema>;
+/**
+ * Validate an untrusted value as an `UndoEntry`. Use at any boundary where an
+ * entry crosses out of internal construction — deserialization from
+ * persistence, or a defensive check at the recording ingestion point. Throws
+ * `AbloValidationError` (code `undo_entry_invalid`) with the failing Zod path
+ * in `details` so the offending op is obvious.
+ */
+export declare function parseUndoEntry(value: unknown): UndoEntry;

package/dist/mutators/inverseOp.js

@@ -0,0 +1,74 @@
+/**
+ * inverseOp.ts — the reversible-operation model for the undo system,
+ * expressed as Zod schemas.
+ *
+ * Why schemas (not bare TS types):
+ *   - Single source of truth. The `InverseOp` / `UndoEntry` TypeScript types
+ *     are *derived* from these schemas (`z.infer`), so the wire shape and the
+ *     static type can't drift.
+ *   - A real validation boundary. Inverse ops are stored as plain JSON-shaped
+ *     records (model keys + row data) so the undo manager stays schema-agnostic
+ *     — it replays them through a strongly-typed transaction it doesn't own.
+ *     That JSON boundary is exactly where a runtime check belongs, and is the
+ *     seam a future cross-session persistence layer (IndexedDB-backed history)
+ *     would deserialize through. `parseUndoEntry` is that gate.
+ *
+ * The op kinds mirror the mutator surface 1:1 — single (`create`/`update`/
+ * `delete`) and batch (`createMany`/`updateMany`/`deleteMany`) — so a recorded
+ * entry is symmetric with what was originally invoked.
+ */
+import { z } from 'zod';
+import { AbloValidationError } from '../errors.js';
+/** A row payload — JSON-shaped record used by create/createMany inverses. */
+const rowDataSchema = z.record(z.string(), z.unknown());
+/**
+ * An update patch: an `id` plus the changed fields. Modeled as an object with
+ * a required `id` and an open `catchall`, so `z.infer` yields
+ * `{ id: string } & { [k: string]: unknown }` — the exact shape the recorder
+ * builds and the replayer consumes.
+ */
+const patchSchema = z.object({ id: z.string() }).catchall(z.unknown());
+/**
+ * A single reversible operation. Discriminated on `kind` so a malformed op
+ * fails fast with a precise path (e.g. `inverses[2].patch.id`) rather than a
+ * vague union mismatch. Model keys/data are strings/records — the manager is
+ * schema-agnostic; the transaction it replays through is schema-typed.
+ */
+export const inverseOpSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('create'), modelKey: z.string(), data: rowDataSchema }),
+    z.object({ kind: z.literal('update'), modelKey: z.string(), patch: patchSchema }),
+    z.object({ kind: z.literal('delete'), modelKey: z.string(), id: z.string() }),
+    z.object({ kind: z.literal('createMany'), modelKey: z.string(), data: z.array(rowDataSchema) }),
+    z.object({ kind: z.literal('updateMany'), modelKey: z.string(), patches: z.array(patchSchema) }),
+    z.object({ kind: z.literal('deleteMany'), modelKey: z.string(), ids: z.array(z.string()) }),
+]);
+/** One undo entry = one mutator invocation's inverses + paired forwards. */
+export const undoEntrySchema = z.object({
+    /** Optional label for diagnostics / UI ("Move layer", "Delete slide", etc). */
+    label: z.string().optional(),
+    /** Applied (in array order) to reverse the invocation. */
+    inverses: z.array(inverseOpSchema),
+    /**
+     * Paired forward ops, captured at record time so redo can replay them
+     * without re-running the user's mutator (which may have non-idempotent
+     * side effects like generating new IDs).
+     */
+    forwards: z.array(inverseOpSchema),
+});
+/**
+ * Validate an untrusted value as an `UndoEntry`. Use at any boundary where an
+ * entry crosses out of internal construction — deserialization from
+ * persistence, or a defensive check at the recording ingestion point. Throws
+ * `AbloValidationError` (code `undo_entry_invalid`) with the failing Zod path
+ * in `details` so the offending op is obvious.
+ */
+export function parseUndoEntry(value) {
+    const result = undoEntrySchema.safeParse(value);
+    if (!result.success) {
+        throw new AbloValidationError('Undo entry failed inverse-op schema validation.', {
+            code: 'undo_entry_invalid',
+            details: { issues: result.error.issues },
+        });
+    }
+    return result.data;
+}

package/dist/mutators/readerActions.d.ts

@@ -4,7 +4,7 @@ import type { SyncStoreContract } from '../react/context.js';
  * React-free imperative reads over a store: one-off `retrieve`/`list`/`count`
  * snapshots that do NOT subscribe to changes. Used by the transaction system
  * and `BaseSyncedStore`. For reactive reads in components use
- * `useAblo((ablo) => ablo.<model>.retrieve(id) / .list(opts))`.
+ * `useAblo((ablo) => ablo.<model>.retrieve({ id }) / .list(opts))`.
  */
 export interface ReaderFindOptions<T> {
     /** Equality filter — uses FK index when the field is registered. */

package/dist/mutators/undoApply.d.ts

@@ -0,0 +1,42 @@
+/**
+ * undoApply.ts — conflict-aware resolution of undo/redo ops (per-user undo).
+ *
+ * The undo stack is already per-client (only local mutator invocations call
+ * `UndoScope.record`; a collaborator's edits arrive as inbound sync deltas and
+ * never land here). What this module adds is the second half of "undo per
+ * user": when replaying a recorded op, only touch a field whose CURRENT value
+ * still equals what THIS op established — so undo reverts your own change only
+ * where it still stands, and never clobbers a field a collaborator changed
+ * after you (the Yjs/CRDT "selective undo" principle, adapted to our
+ * field-level last-writer-wins model).
+ *
+ * `resolveOps(apply, paired, store, policy)`:
+ *   - `apply`  — the ops we're about to replay (inverses on undo, forwards on redo).
+ *   - `paired` — their counterparts, carrying the value this op established
+ *     (forwards on undo = "what I set"; inverses on redo = "what undo restored").
+ *   - For `update`/`updateMany` ops it drops fields whose live value no longer
+ *     matches the established value. `create`/`delete` families are structural
+ *     and applied unconditionally (undoing your create removes the row you
+ *     added; undoing your delete restores it).
+ *
+ * With no collaborator, the live value always equals what you set, so nothing
+ * is dropped — single-user undo is byte-for-byte unchanged.
+ */
+import type { SyncStoreContract } from '../react/context.js';
+import type { InverseOp } from './inverseOp.js';
+/**
+ * How undo/redo handles a field a collaborator changed after your op:
+ *   - `skip-stale` (default): leave it — your change is already superseded, so
+ *     reverting it would clobber theirs. This is the per-user guarantee.
+ *   - `last-writer-wins`: apply the op verbatim (legacy behavior). Your undo
+ *     overwrites their change.
+ */
+export type UndoConflictPolicy = 'skip-stale' | 'last-writer-wins';
+export declare const DEFAULT_UNDO_CONFLICT_POLICY: UndoConflictPolicy;
+/** Structural equality for JSON-shaped values (scalars, arrays, plain objects). */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/**
+ * Filter the ops to apply so they don't clobber concurrent collaborator edits.
+ * See the module docblock. `last-writer-wins` returns the ops unchanged.
+ */
+export declare function resolveOps(apply: InverseOp[], paired: InverseOp[], store: SyncStoreContract, policy: UndoConflictPolicy): InverseOp[];

package/dist/mutators/undoApply.js

@@ -0,0 +1,143 @@
+/**
+ * undoApply.ts — conflict-aware resolution of undo/redo ops (per-user undo).
+ *
+ * The undo stack is already per-client (only local mutator invocations call
+ * `UndoScope.record`; a collaborator's edits arrive as inbound sync deltas and
+ * never land here). What this module adds is the second half of "undo per
+ * user": when replaying a recorded op, only touch a field whose CURRENT value
+ * still equals what THIS op established — so undo reverts your own change only
+ * where it still stands, and never clobbers a field a collaborator changed
+ * after you (the Yjs/CRDT "selective undo" principle, adapted to our
+ * field-level last-writer-wins model).
+ *
+ * `resolveOps(apply, paired, store, policy)`:
+ *   - `apply`  — the ops we're about to replay (inverses on undo, forwards on redo).
+ *   - `paired` — their counterparts, carrying the value this op established
+ *     (forwards on undo = "what I set"; inverses on redo = "what undo restored").
+ *   - For `update`/`updateMany` ops it drops fields whose live value no longer
+ *     matches the established value. `create`/`delete` families are structural
+ *     and applied unconditionally (undoing your create removes the row you
+ *     added; undoing your delete restores it).
+ *
+ * With no collaborator, the live value always equals what you set, so nothing
+ * is dropped — single-user undo is byte-for-byte unchanged.
+ */
+export const DEFAULT_UNDO_CONFLICT_POLICY = 'skip-stale';
+/** Structural equality for JSON-shaped values (scalars, arrays, plain objects). */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') {
+        return false;
+    }
+    const aArr = Array.isArray(a);
+    if (aArr !== Array.isArray(b))
+        return false;
+    if (aArr) {
+        const av = a;
+        const bv = b;
+        if (av.length !== bv.length)
+            return false;
+        for (let i = 0; i < av.length; i++) {
+            if (!deepEqual(av[i], bv[i]))
+                return false;
+        }
+        return true;
+    }
+    const ao = a;
+    const bo = b;
+    const ak = Object.keys(ao);
+    const bk = Object.keys(bo);
+    if (ak.length !== bk.length)
+        return false;
+    for (const k of ak) {
+        if (!Object.prototype.hasOwnProperty.call(bo, k))
+            return false;
+        if (!deepEqual(ao[k], bo[k]))
+            return false;
+    }
+    return true;
+}
+/**
+ * Map `id → { field: establishedValue }` from the paired ops. Only update-family
+ * ops carry per-field values worth comparing.
+ */
+function buildEstablished(paired) {
+    const map = new Map();
+    for (const op of paired) {
+        if (op.kind === 'update') {
+            map.set(op.patch.id, op.patch);
+        }
+        else if (op.kind === 'updateMany') {
+            for (const p of op.patches)
+                map.set(p.id, p);
+        }
+    }
+    return map;
+}
+/** Read the live value of a field from the store's pool, or `undefined`. */
+function readCurrentField(store, id, field) {
+    const model = store.pool.get(id);
+    if (!model)
+        return undefined;
+    const json = model.toJSON?.();
+    return json ? json[field] : undefined;
+}
+/**
+ * Keep only the fields whose live value still equals what this op established
+ * (`established[field]`). Returns `null` if nothing survives (the whole op is a
+ * no-op — every field was superseded by a collaborator).
+ */
+function filterStalePatch(store, patch, established) {
+    const out = { id: patch.id };
+    let kept = 0;
+    for (const field of Object.keys(patch)) {
+        if (field === 'id')
+            continue;
+        if (established && field in established) {
+            // Apply only if the field still holds the value WE established — i.e. no
+            // collaborator overwrote it since. Otherwise skip (don't clobber them).
+            if (deepEqual(readCurrentField(store, patch.id, field), established[field])) {
+                out[field] = patch[field];
+                kept++;
+            }
+        }
+        else {
+            // No paired value to compare against. The recorder always pairs fields,
+            // so this is theoretical; apply to preserve undo functionality.
+            out[field] = patch[field];
+            kept++;
+        }
+    }
+    return kept > 0 ? out : null;
+}
+/**
+ * Filter the ops to apply so they don't clobber concurrent collaborator edits.
+ * See the module docblock. `last-writer-wins` returns the ops unchanged.
+ */
+export function resolveOps(apply, paired, store, policy) {
+    if (policy === 'last-writer-wins')
+        return apply;
+    const established = buildEstablished(paired);
+    const out = [];
+    for (const op of apply) {
+        if (op.kind === 'update') {
+            const filtered = filterStalePatch(store, op.patch, established.get(op.patch.id));
+            if (filtered)
+                out.push({ kind: 'update', modelKey: op.modelKey, patch: filtered });
+        }
+        else if (op.kind === 'updateMany') {
+            const patches = op.patches
+                .map((p) => filterStalePatch(store, p, established.get(p.id)))
+                .filter((p) => p !== null);
+            if (patches.length > 0) {
+                out.push({ kind: 'updateMany', modelKey: op.modelKey, patches });
+            }
+        }
+        else {
+            // create / createMany / delete / deleteMany — structural, applied as-is.
+            out.push(op);
+        }
+    }
+    return out;
+}

package/dist/query/client.d.ts

@@ -3,7 +3,7 @@
  *
  * Thin wrapper over fetch() that:
  *   - POSTs a QueryBatch as JSON
- *   - Handles auth via `credentials: 'include'` (session cookie)
+ *   - Sends the bearer credential via withAuthHeaders (Authorization header)
  *   - Throws on non-2xx responses
  *   - Parses the response into a typed QueryBatchResult
  *
@@ -12,6 +12,7 @@
  * without duplicating the fetch boilerplate.
  */
 import type { QueryBatch, QueryBatchResult } from './types.js';
+import { type AuthTokenGetter } from '../auth/credentialSource.js';
 export interface PostQueryOptions {
     /**
      * Full base URL of the sync server including the `/api` prefix.
@@ -22,14 +23,14 @@ export interface PostQueryOptions {
     /** Timeout in ms for the fetch request. Default: 30000. */
     fetchTimeout?: number;
     /**
-     * Bearer credential — a restricted (`rk_`) API key — attached as
-     * `Authorization: Bearer <token>`. Required for Node consumers
-     * (agent-worker, server-side tests) that have no session cookie to
-     * ride. Browser consumers can omit this and fall back to
-     * `credentials: 'include'`. When both are present the server prefers
-     * the Bearer header (see `apiKeyProvider` in
-     * `apps/sync-server/src/auth`), so passing the token in browser code
-     * is harmless. (Field name predates the Biscuit→opaque-key migration.)
+     * Live bearer credential getter. Preferred over `capabilityToken` because it
+     * is read per request, so token refreshes propagate without reconstructing
+     * query helpers.
+     */
+    getAuthToken?: AuthTokenGetter;
+    /**
+     * Compatibility fallback for callers that have only a copied token string.
+     * New SDK internals should pass `getAuthToken`.
      */
     capabilityToken?: string;
 }

package/dist/query/client.js

@@ -3,7 +3,7 @@
  *
  * Thin wrapper over fetch() that:
  *   - POSTs a QueryBatch as JSON
- *   - Handles auth via `credentials: 'include'` (session cookie)
+ *   - Sends the bearer credential via withAuthHeaders (Authorization header)
  *   - Throws on non-2xx responses
  *   - Parses the response into a typed QueryBatchResult
  *
@@ -12,6 +12,8 @@
  * without duplicating the fetch boilerplate.
  */
 import { z } from 'zod';
+import { translateHttpError } from '../errors.js';
+import { withAuthHeaders } from '../auth/credentialSource.js';
 // ── Response validation ─────────────────────────────────────────────────
 //
 // Each result slot is an array of rows (or an object for bundled
@@ -48,26 +50,32 @@ export async function postQuery(options, batch) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeout);
     try {
-        const headers = { 'Content-Type': 'application/json' };
-        if (options.capabilityToken) {
-            headers.Authorization = `Bearer ${options.capabilityToken}`;
-        }
+        const headers = withAuthHeaders(options.getAuthToken, { 'Content-Type': 'application/json' }, options.capabilityToken);
         const response = await fetch(url, {
             method: 'POST',
             headers,
-            credentials: 'include',
             body: JSON.stringify(batch),
             signal: controller.signal,
         });
         if (!response.ok) {
-            // Direct console.error is INTENTIONAL — operators alert on the
-            // `[postQuery.error]` prefix in browser console. Routing through
-            // an injected logger here would require a coordinated change to
-            // the alerting pipeline. Tracked as future work; the dual-channel
-            // alternative (logger + observability.captureException) is the
-            // production target. Never throw — fire-and-forget callers would
-            // kill Next.js router on unhandled rejection.
-            console.error(`[postQuery.error] ${response.status} ${response.statusText} for ${batch.queries.map((q) => q.model).join(',')}`);
+            // Build the typed AbloError for this HTTP failure (same code→class
+            // map the throwing paths use) so the log is tagged + carries a
+            // registry `code` (e.g. AbloAuthenticationError/session_expired on a
+            // 401) instead of a bare status. We deliberately DON'T throw —
+            // fire-and-forget callers would kill the Next.js router on an
+            // unhandled rejection — and still return empty slots, but the failure
+            // is now legible as an Ablo error. Direct console.error is
+            // INTENTIONAL: operators alert on the `[postQuery.error]` prefix.
+            let body = null;
+            try {
+                body = await response.clone().json();
+            }
+            catch {
+                // non-JSON error page — translateHttpError falls back to status text
+            }
+            const err = translateHttpError(response.status, body);
+            console.error(`[postQuery.error] ${err.type} ${err.code ?? response.status} for ` +
+                `${batch.queries.map((q) => q.model).join(',')}: ${err.message}`);
             return { results: batch.queries.map(() => []) };
         }
         const raw = await response.json();

package/dist/react/AbloProvider.d.ts

@@ -1,10 +1,6 @@
 import { type ReactNode } from 'react';
-import type { Schema, SchemaRecord } from '../schema/schema.js';
+import type { SchemaRecord } from '../schema/schema.js';
 import { Ablo } from '../client/Ablo.js';
-import type { AbloPersistence } from '../client/persistence.js';
-import type { SyncEngineConfig, MutationExecutor, MutationDispatcher, SessionErrorDetector, OnlineStatusProvider, SyncLogger, SyncObservabilityProvider } from '../config/index.js';
-import type { UseMutatorsOptions } from './useMutators.js';
-import type { MutatorDefs } from '../mutators/defineMutators.js';
 import type { ActiveIntent, Peer } from '../types/streams.js';
 import type { EngineParticipant, ParticipantScope, ParticipantStatus } from '../sync/participants.js';
 import { type SyncStoreContract } from './context.js';
@@ -49,115 +45,41 @@ import { type SyncStoreContract } from './context.js';
  */
 export interface AbloProviderProps<R extends SchemaRecord = SchemaRecord> {
     /**
-     * Schema from `defineSchema()`. Determines the typed hook surface.
-     * This is the only prop most apps pass — start here.
-     */
-    schema: Schema<R>;
-    /**
-     * WebSocket URL of the sync server (`wss://...` or `ws://...`).
-     * Hosted apps omit this.
+     * A prebuilt {@link Ablo} client — **the only way to configure the engine.**
+     * Construct it yourself with `Ablo({ schema, apiKey, ... })` and pass the
+     * instance: the CLIENT owns auth, the credential lifecycle, transport, and
+     * connection; this provider is the thin REACTIVE binding over it (context,
+     * the bootstrap gate, error/​session forwarding). Mirrors Stripe
+     * `<Elements stripe={...}>` and a Supabase client passed into a context.
+     *
+     * Memoize it (build it once, e.g. with `useMemo` or module scope) — a new
+     * instance each render re-keys the bootstrap gate and tears down the socket.
      */
-    url?: string;
+    client: Ablo<R>;
     /**
-     * Optional app user id for app-owned fields. Ablo resolves sync
-     * participant identity from auth; this is not required to connect.
+     * The app user id, surfaced via `useCurrentUserId()` for app-owned fields.
+     * Purely informational for the React tree — sync identity is resolved by the
+     * client from its auth, not from this. Optional.
      */
     userId?: string;
-    /** Team IDs the user belongs to. Expanded into sync groups. */
-    teamIds?: string[];
-    /**
-     * API key for engine bootstrap auth. Used by the bootstrap fetch
-     * path; falls back to `credentials: 'include'` (session cookie)
-     * when unset. Browser apps typically omit this and rely on
-     * same-origin session cookies.
-     */
-    apiKey?: string;
-    /** Optional Zero-style custom mutators. */
-    mutators?: MutatorDefs<Schema<R>>;
-    /** Options forwarded to the internal `useMutators` call (e.g., `undoScope`). */
-    mutatorOptions?: UseMutatorsOptions<Schema<R>>;
     /**
-     * Block browser tab close when there are unsynced local writes.
-     * Triggers the standard `beforeunload` "Leave site?" prompt.
-     * Browsers ignore custom messages — do not pass one. Consumers
-     * who want telemetry should read
-     * `useSyncStatus().hasUnsyncedChanges` directly.
+     * Block tab close while there are unsynced local writes (the standard
+     * `beforeunload` prompt). Browsers ignore custom messages — don't pass one.
      */
     preventUnsavedChanges?: boolean;
     /**
-     * Milliseconds to tolerate connection loss before `useSyncStatus()`
-     * flips to `disconnected`. Defaults to 5000. Set to 0 to
-     * disable the grace period (immediate transition).
-     *
-     * v0.3.0 scope: reserved for future wiring. Current transition is
-     * driven by the engine's built-in state machine.
-     */
-    lostConnectionTimeout?: number;
-    /**
-     * Fired when the server rejects the session. The provider has
-     * ALREADY called `engine.purge()` (disposed + wiped IndexedDB) by
-     * the time this runs — the callback is for app-level side effects
-     * (e.g., redirect to sign-in, clear analytics identity).
+     * Fired when the server rejects the session. The provider has ALREADY called
+     * `client.purge()` (disposed + wiped IndexedDB) by the time this runs — use it
+     * for app side effects (redirect to sign-in, clear analytics identity).
      */
     onSessionExpired?: () => void | Promise<void>;
     /**
-     * Fired on any error the provider surfaces: engine errors,
-     * WebSocket errors, uncaught `postBootstrap` exceptions. Use for
-     * Sentry / Datadog. Consumers who only want errors inside React
-     * can use the `useErrorListener()` hook instead.
+     * Fired on any error the provider surfaces (engine/WebSocket/bootstrap). For
+     * Sentry/Datadog. React-only consumers can use `useErrorListener()` instead.
      */
     onError?: (error: Error) => void;
-    observability?: SyncObservabilityProvider;
-    logger?: SyncLogger;
-    mutationExecutor?: MutationExecutor;
-    mutationDispatcher?: MutationDispatcher;
-    sessionErrorDetector?: SessionErrorDetector;
-    onlineStatus?: OnlineStatusProvider;
-    configOverrides?: SyncEngineConfig;
-    /**
-     * Raw sync-group strings for the initial connection. Prefer {@link scope} —
-     * the model form (`{ decks: deckId }`) that the engine resolves through the
-     * schema's `scope`, so you never hand-write a `deck:<id>` string. Both merge.
-     */
-    syncGroups?: string[];
-    /**
-     * Model-form connection scope: `{ decks: deckId, documents: documentId }` or
-     * entity refs. Resolved through the schema's per-model `scope` into group
-     * strings (so typename `SlideDeck` → `deck:<id>`), unioned with {@link syncGroups}.
-     * Memoize the object if it's derived, to avoid rotating the engine each render.
-     */
-    scope?: ParticipantScope;
-    bootstrapBaseUrl?: string;
-    maxPoolSize?: number;
-    /**
-     * Local persistence mode for the underlying `Ablo` client. Defaults
-     * to `volatile` — pass `'indexeddb'` to opt back into offline-queue +
-     * reload-surviving cache in a browser. See `AbloOptions.persistence`
-     * for the full semantics.
-     */
-    persistence?: AbloPersistence;
-    /**
-     * How aggressively this provider pulls baseline state at startup.
-     *
-     *  - `'full'` (default): pull every delta in the configured sync
-     *    groups before the engine reports ready — a local replica of the
-     *    org's tenant plane. Right for collaborative editors and any page
-     *    that reads a lot of shared state.
-     *  - `'none'`: open the connection and process live deltas only — no
-     *    baseline fetch. Reads round-trip via `ablo.<model>.retrieve(...)`
-     *    and subscriptions populate the pool lazily. Right for read-light
-     *    pages (a mostly-static dashboard, a settings screen) that don't
-     *    want to download the whole org to render.
-     *
-     * Note: `'none'` still opens the realtime connection — it skips the
-     * baseline pull, not the socket. A fully connection-free mode for
-     * pages that do zero multiplayer is a separate follow-up (the socket
-     * open lives inside `engine.ready()`, so deferring it needs
-     * engine-level lazy-connect support, not just a provider prop).
-     *
-     * Mirrors `AbloOptions.bootstrapMode`. Changing it rotates the engine.
-     */
-    bootstrapMode?: 'full' | 'none';
+    /** @internal placeholder so the old WS-URL prop shape doesn't silently leak in. */
+    url?: never;
     /**
      * Rendered in place of `children` during the *first* bootstrap pass —
      * while the engine is actively transitioning from `initial` →