@abloatai/ablo 0.3.0

package/dist/mutators/RecordingTransaction.js

@@ -0,0 +1,216 @@
+/**
+ * RecordingTransaction — wraps a base `Transaction` and captures inverse ops
+ * for the undo system. Each write is observed BEFORE it runs (to snapshot
+ * pre-state) and AFTER (to capture the forward op for redo).
+ *
+ * The wrapped mutator sees the exact same `Transaction<S>` shape; recording
+ * is invisible. When the mutator returns, the caller reads `getEntry()` and
+ * pushes it into the active `UndoScope`.
+ *
+ * Why snapshots live here (not in the UndoScope):
+ *   - Update inverse requires `prev` field values — must be captured before
+ *     the write lands in the pool.
+ *   - Delete inverse requires the full model data — same reason.
+ *   - Create inverse is simpler (delete by id) but the id must be known
+ *     post-creation (schema generates UUIDs if caller omitted one).
+ */
+import { createTransaction } from './Transaction.js';
+/**
+ * Build a transaction that records inverses + forwards as it runs.
+ * Consumers use this only when they want the invocation to be undoable;
+ * read-only or side-effect-only mutators should use `createTransaction`
+ * directly to avoid the bookkeeping overhead.
+ */
+export function createRecordingTransaction(schema, store, organizationId) {
+    const inverses = [];
+    const forwards = [];
+    const inner = createTransaction(schema, store, organizationId);
+    // Wrap mutations with a Proxy that intercepts each model key's
+    // methods. We keep `inner.read` as-is — reads don't need recording.
+    const mutateProxy = new Proxy({}, {
+        get(_target, prop) {
+            if (typeof prop !== 'string')
+                return undefined;
+            const innerMutate = inner.mutations[prop];
+            if (!innerMutate)
+                return innerMutate;
+            return wrapMutateForKey(prop, innerMutate, store, inverses, forwards);
+        },
+    });
+    return {
+        tx: { mutations: mutateProxy, read: inner.read },
+        getEntry: (label) => {
+            if (inverses.length === 0)
+                return null;
+            // Undo applies inverses in REVERSE order of how the forward writes ran.
+            // Redo applies forwards in the ORIGINAL order.
+            return { label, inverses: [...inverses].reverse(), forwards: [...forwards] };
+        },
+    };
+}
+// ── Per-key wrapper ────────────────────────────────────────────────────────
+function wrapMutateForKey(modelKey, mutate, store, inverses, forwards) {
+    const snapshot = (id) => {
+        const model = store.pool.get(id);
+        if (!model)
+            return null;
+        // Model.toJSON produces a plain object suitable for re-create. We need
+        // ALL fields when generating a delete→create inverse, so toJSON's
+        // wider shape is exactly right.
+        return model.toJSON();
+    };
+    const snapshotFields = (id, fieldNames) => {
+        const model = store.pool.get(id);
+        if (!model)
+            return null;
+        const out = {};
+        // `modifiedProperties` is populated by M1's `observe()` listener the
+        // moment the caller mutates an observable field directly. Thanks to
+        // `Model.propertyChanged`'s first-old-wins policy, `.old` holds the TRUE
+        // pre-session baseline even after many in-place mutations (e.g. a drag
+        // frame loop). That makes it the authoritative source for the undo
+        // inverse when the caller pre-mutates before invoking the mutator.
+        //
+        // Fallback chain for models/fields that weren't pre-mutated (so no
+        // `modifiedProperties` entry exists yet): `getOriginalSnapshot()`
+        // (populated on load/`markAsPersisted`/sync-ack), then the live
+        // observable. The live read is correct only when the caller didn't
+        // touch the field first.
+        const original = model.getOriginalSnapshot();
+        for (const f of fieldNames) {
+            if (f === 'id')
+                continue;
+            const mod = model.modifiedProperties.get(f);
+            if (mod) {
+                out[f] = mod.old;
+            }
+            else if (original && f in original) {
+                out[f] = original[f];
+            }
+            else {
+                out[f] = Reflect.get(model, f);
+            }
+        }
+        return out;
+    };
+    // After a mutator's `base.update` succeeds, drop the `modifiedProperties`
+    // entries we snapshotted from. The next mutator call should see THIS
+    // update's result as its baseline, not the pre-session old value. The
+    // transaction queue already captured its frozen copy synchronously inside
+    // `store.save` (via `captureModelChanges`/`extractPreviousData`), so this
+    // clear is safe for server rollback.
+    const consumeModifiedFields = (id, fieldNames) => {
+        const model = store.pool.get(id);
+        if (!model)
+            return;
+        for (const f of fieldNames) {
+            if (f === 'id')
+                continue;
+            model.modifiedProperties.delete(f);
+        }
+    };
+    return {
+        // Overloaded — single row or array. The recorder dispatches the
+        // matching forward/inverse op shape (`create`/`createMany`,
+        // `update`/`updateMany`, `delete`/`deleteMany`) so the persisted
+        // undo entry is symmetric with what was originally invoked.
+        create: (async (data) => {
+            if (Array.isArray(data)) {
+                const created = await mutate.create(data);
+                const withIds = created.map((m, i) => ({
+                    ...data[i],
+                    id: m.id,
+                }));
+                const ids = created.map((m) => m.id);
+                forwards.push({ kind: 'createMany', modelKey, data: withIds });
+                inverses.push({ kind: 'deleteMany', modelKey, ids });
+                return created;
+            }
+            const created = await mutate.create(data);
+            const id = created.id;
+            forwards.push({
+                kind: 'create',
+                modelKey,
+                data: { ...data, id },
+            });
+            inverses.push({ kind: 'delete', modelKey, id });
+            return created;
+        }),
+        update: (async (patch) => {
+            if (Array.isArray(patch)) {
+                // Snapshot all previous values BEFORE applying — later patches
+                // in the same list would corrupt the inverse state of earlier
+                // ones if we snapshotted lazily.
+                const prevPatches = [];
+                for (const p of patch) {
+                    const fields = Object.keys(p).filter((k) => k !== 'id');
+                    const prev = snapshotFields(p.id, fields);
+                    if (prev)
+                        prevPatches.push({ id: p.id, ...prev });
+                }
+                const updated = await mutate.update(patch);
+                const forwardPatches = patch.map((p) => ({ ...p }));
+                for (const p of forwardPatches) {
+                    consumeModifiedFields(p.id, Object.keys(p).filter((k) => k !== 'id'));
+                }
+                forwards.push({ kind: 'updateMany', modelKey, patches: forwardPatches });
+                if (prevPatches.length > 0) {
+                    inverses.push({ kind: 'updateMany', modelKey, patches: prevPatches });
+                }
+                return updated;
+            }
+            const id = patch.id;
+            const fields = Object.keys(patch).filter((k) => k !== 'id');
+            const prev = snapshotFields(id, fields);
+            const updated = await mutate.update(patch);
+            const patchCopy = {
+                id,
+                ...patch,
+            };
+            consumeModifiedFields(id, fields);
+            forwards.push({ kind: 'update', modelKey, patch: patchCopy });
+            if (prev) {
+                inverses.push({ kind: 'update', modelKey, patch: { id, ...prev } });
+            }
+            return updated;
+        }),
+        delete: (async (idOrIds) => {
+            if (Array.isArray(idOrIds)) {
+                const prevs = idOrIds
+                    .map((id) => snapshot(id))
+                    .filter((d) => d !== null);
+                await mutate.delete(idOrIds);
+                forwards.push({ kind: 'deleteMany', modelKey, ids: [...idOrIds] });
+                if (prevs.length > 0) {
+                    inverses.push({ kind: 'createMany', modelKey, data: prevs });
+                }
+                return;
+            }
+            const prev = snapshot(idOrIds);
+            await mutate.delete(idOrIds);
+            forwards.push({ kind: 'delete', modelKey, id: idOrIds });
+            if (prev) {
+                inverses.push({ kind: 'create', modelKey, data: prev });
+            }
+        }),
+        archive: async (id) => {
+            await mutate.archive(id);
+            forwards.push({
+                kind: 'update',
+                modelKey,
+                patch: { id, archivedAt: new Date() },
+            });
+            // Inverse of archive is unarchive, modeled here as a "restore" update.
+            inverses.push({ kind: 'update', modelKey, patch: { id, archivedAt: null } });
+        },
+        unarchive: async (id) => {
+            await mutate.unarchive(id);
+            forwards.push({ kind: 'update', modelKey, patch: { id, archivedAt: null } });
+            inverses.push({
+                kind: 'update',
+                modelKey,
+                patch: { id, archivedAt: new Date() },
+            });
+        },
+    };
+}

package/dist/mutators/Transaction.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Transaction — Zero-style typed transaction object exposed to custom mutators.
+ *
+ * A mutator function receives `{ tx, args }`. Through `tx.mutations.<modelKey>.*`
+ * it performs writes; through `tx.read.<modelKey>.*` it takes imperative
+ * snapshots of the ObjectPool.
+ *
+ * Semantics:
+ *   - Writes dispatch eagerly via the existing `createMutateActions` / store
+ *     primitives (no buffering, no rollback). Partial state is possible if
+ *     a mutator throws midway. Atomic rollback is a follow-up.
+ *   - Reads are synchronous snapshots via `createReaderActions`. They use the
+ *     FK index fast path where available (O(1) on registered FK fields).
+ *
+ * The mutate surface is intentionally one-row-at-a-time
+ * (`create`/`update`/`delete`). For batches, mutator authors compose
+ * `Promise.all(rows.map((r) => tx.mutations.x.create(r)))` — every push
+ * stages in the same synchronous tick, the await happens once, and the
+ * microtask coalescer in `TransactionQueue` collapses N pushes into one
+ * wire commit. Same shape Zero uses: no `insertMany`, just an array map.
+ */
+import type { Schema } from '../schema/schema.js';
+import type { SyncStoreContract } from '../react/context.js';
+import { type MutateActions } from '../react/useMutate.js';
+import { type ReaderActions, type ReaderFindOptions } from '../react/useReader.js';
+/**
+ * The full transaction surface. `tx.mutations.<key>.*` for writes,
+ * `tx.read.<key>.*` for imperative reads. Re-exports the base read options
+ * type so mutator authors can type `where` payloads without reaching into
+ * the React barrel.
+ *
+ * The name `mutations` (not `mutate`) matches the React hook naming.
+ */
+export interface Transaction<S extends Schema> {
+    mutations: {
+        [K in keyof S['models'] & string]: MutateActions<S, K>;
+    };
+    read: {
+        [K in keyof S['models'] & string]: ReaderActions<S, K>;
+    };
+}
+export type { ReaderFindOptions };
+/**
+ * Build a Transaction for a single mutator invocation. The returned object
+ * lazily instantiates per-model actions on first access so we don't pay for
+ * models the mutator never touches.
+ */
+export declare function createTransaction<S extends Schema>(schema: S, store: SyncStoreContract, organizationId: string): Transaction<S>;

package/dist/mutators/Transaction.js

@@ -0,0 +1,64 @@
+/**
+ * Transaction — Zero-style typed transaction object exposed to custom mutators.
+ *
+ * A mutator function receives `{ tx, args }`. Through `tx.mutations.<modelKey>.*`
+ * it performs writes; through `tx.read.<modelKey>.*` it takes imperative
+ * snapshots of the ObjectPool.
+ *
+ * Semantics:
+ *   - Writes dispatch eagerly via the existing `createMutateActions` / store
+ *     primitives (no buffering, no rollback). Partial state is possible if
+ *     a mutator throws midway. Atomic rollback is a follow-up.
+ *   - Reads are synchronous snapshots via `createReaderActions`. They use the
+ *     FK index fast path where available (O(1) on registered FK fields).
+ *
+ * The mutate surface is intentionally one-row-at-a-time
+ * (`create`/`update`/`delete`). For batches, mutator authors compose
+ * `Promise.all(rows.map((r) => tx.mutations.x.create(r)))` — every push
+ * stages in the same synchronous tick, the await happens once, and the
+ * microtask coalescer in `TransactionQueue` collapses N pushes into one
+ * wire commit. Same shape Zero uses: no `insertMany`, just an array map.
+ */
+import { createMutateActions } from '../react/useMutate.js';
+import { createReaderActions } from '../react/useReader.js';
+import { AbloValidationError } from '../errors.js';
+/**
+ * Build a Transaction for a single mutator invocation. The returned object
+ * lazily instantiates per-model actions on first access so we don't pay for
+ * models the mutator never touches.
+ */
+export function createTransaction(schema, store, organizationId) {
+    const mutateCache = new Map();
+    const readCache = new Map();
+    const mutations = new Proxy({}, {
+        get(_target, prop) {
+            if (typeof prop !== 'string')
+                return undefined;
+            const cached = mutateCache.get(prop);
+            if (cached)
+                return cached;
+            if (!(prop in schema.models)) {
+                throw new AbloValidationError(`Transaction.mutations: unknown model key "${prop}". Known keys: ${Object.keys(schema.models).join(', ')}`, { code: 'transaction_mutate_unknown_model' });
+            }
+            const actions = createMutateActions(schema, prop, store, organizationId);
+            mutateCache.set(prop, actions);
+            return actions;
+        },
+    });
+    const read = new Proxy({}, {
+        get(_target, prop) {
+            if (typeof prop !== 'string')
+                return undefined;
+            const cached = readCache.get(prop);
+            if (cached)
+                return cached;
+            if (!(prop in schema.models)) {
+                throw new AbloValidationError(`Transaction.read: unknown model key "${prop}". Known keys: ${Object.keys(schema.models).join(', ')}`, { code: 'transaction_read_unknown_model' });
+            }
+            const actions = createReaderActions(schema, prop, store);
+            readCache.set(prop, actions);
+            return actions;
+        },
+    });
+    return { mutations, read };
+}

package/dist/mutators/UndoManager.d.ts

@@ -0,0 +1,114 @@
+/**
+ * UndoManager — per-scope history of reversible mutations.
+ *
+ * Each mutator invocation records an ordered list of inverse operations.
+ * On `undo()` we pop the last group and apply the inverses as a non-recorded
+ * transaction (so the inverse itself doesn't push to the redo stack; we do
+ * that explicitly below).
+ *
+ * Scopes: every consumer (deck editor, spreadsheet, etc.) gets a named scope
+ * via `getScope(name)`. Cmd+Z in one surface never affects another.
+ *
+ * V1 limitations:
+ *   - No persistence across sessions (in-memory stack).
+ *   - No collaborative awareness — undoing after a teammate edited the same
+ *     row produces a "last writer wins" outcome, not a true merge.
+ *   - Server-side mutation rejection after optimistic apply does NOT
+ *     automatically invalidate the undo stack. Consumers should `clear()`
+ *     the scope on sync error if they want strict correctness.
+ */
+import type { Schema } from '../schema/schema.js';
+import type { SyncStoreContract } from '../react/context.js';
+/**
+ * A single reversible operation. The runtime captures these during a
+ * recorded transaction and replays them (in reverse order) on undo.
+ * Model keys and data shapes are stored as strings/records so the manager
+ * is schema-agnostic — the transaction it replays through is schema-typed.
+ */
+export type InverseOp = {
+    kind: 'create';
+    modelKey: string;
+    data: Record<string, unknown>;
+} | {
+    kind: 'update';
+    modelKey: string;
+    patch: {
+        id: string;
+    } & Record<string, unknown>;
+} | {
+    kind: 'delete';
+    modelKey: string;
+    id: string;
+} | {
+    kind: 'createMany';
+    modelKey: string;
+    data: Record<string, unknown>[];
+} | {
+    kind: 'updateMany';
+    modelKey: string;
+    patches: Array<{
+        id: string;
+    } & Record<string, unknown>>;
+} | {
+    kind: 'deleteMany';
+    modelKey: string;
+    ids: string[];
+};
+/** One undo entry = one mutator invocation's set of inverses, in reverse order. */
+export interface UndoEntry {
+    /** Optional label for diagnostics / UI ("Move layer", "Delete slide", etc). */
+    label?: string;
+    inverses: InverseOp[];
+    /**
+     * 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: InverseOp[];
+}
+export interface UndoScopeOptions {
+    /** Max number of undo entries. Older entries drop off the bottom. Default: 100. */
+    maxHistory?: number;
+}
+/**
+ * A single undo stack for one surface. Access via `UndoManager.getScope(name)`.
+ * Consumers call `record(entry)` after each mutator; `undo()` / `redo()` to
+ * traverse the stacks.
+ */
+export declare class UndoScope<S extends Schema> {
+    private readonly schema;
+    private readonly store;
+    private readonly organizationId;
+    private undoStack;
+    private redoStack;
+    private readonly maxHistory;
+    constructor(schema: S, store: SyncStoreContract, organizationId: string, options?: UndoScopeOptions);
+    /** Internal: record a mutator's inverses. Clears the redo stack. */
+    record(entry: UndoEntry): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /** Pop the last mutator and apply its inverses. Pushes to redo. */
+    undo(): Promise<void>;
+    /** Pop the last undone entry and re-apply the forward ops. Pushes to undo. */
+    redo(): Promise<void>;
+    /** Drop all history. Use after bootstrap / sync group change / sync error. */
+    clear(): void;
+    /** Introspection — for debug panels / e2e tests. */
+    size(): {
+        undo: number;
+        redo: number;
+    };
+}
+/**
+ * Central registry of named undo scopes. One per-app instance, created once
+ * during engine setup. Mutator invocations find their scope by name.
+ */
+export declare class UndoManager<S extends Schema> {
+    private readonly schema;
+    private readonly store;
+    private readonly organizationId;
+    private readonly scopes;
+    constructor(schema: S, store: SyncStoreContract, organizationId: string);
+    getScope(name: string, options?: UndoScopeOptions): UndoScope<S>;
+    clearAll(): void;
+}

package/dist/mutators/UndoManager.js

@@ -0,0 +1,143 @@
+/**
+ * UndoManager — per-scope history of reversible mutations.
+ *
+ * Each mutator invocation records an ordered list of inverse operations.
+ * On `undo()` we pop the last group and apply the inverses as a non-recorded
+ * transaction (so the inverse itself doesn't push to the redo stack; we do
+ * that explicitly below).
+ *
+ * Scopes: every consumer (deck editor, spreadsheet, etc.) gets a named scope
+ * via `getScope(name)`. Cmd+Z in one surface never affects another.
+ *
+ * V1 limitations:
+ *   - No persistence across sessions (in-memory stack).
+ *   - No collaborative awareness — undoing after a teammate edited the same
+ *     row produces a "last writer wins" outcome, not a true merge.
+ *   - Server-side mutation rejection after optimistic apply does NOT
+ *     automatically invalidate the undo stack. Consumers should `clear()`
+ *     the scope on sync error if they want strict correctness.
+ */
+import { createTransaction } from './Transaction.js';
+/**
+ * A single undo stack for one surface. Access via `UndoManager.getScope(name)`.
+ * Consumers call `record(entry)` after each mutator; `undo()` / `redo()` to
+ * traverse the stacks.
+ */
+export class UndoScope {
+    schema;
+    store;
+    organizationId;
+    undoStack = [];
+    redoStack = [];
+    maxHistory;
+    constructor(schema, store, organizationId, options = {}) {
+        this.schema = schema;
+        this.store = store;
+        this.organizationId = organizationId;
+        this.maxHistory = options.maxHistory ?? 100;
+    }
+    /** Internal: record a mutator's inverses. Clears the redo stack. */
+    record(entry) {
+        this.undoStack.push(entry);
+        if (this.undoStack.length > this.maxHistory)
+            this.undoStack.shift();
+        this.redoStack = [];
+    }
+    canUndo() {
+        return this.undoStack.length > 0;
+    }
+    canRedo() {
+        return this.redoStack.length > 0;
+    }
+    /** Pop the last mutator and apply its inverses. Pushes to redo. */
+    async undo() {
+        const entry = this.undoStack.pop();
+        if (!entry)
+            return;
+        const tx = createTransaction(this.schema, this.store, this.organizationId);
+        await applyOps(tx, entry.inverses);
+        this.redoStack.push(entry);
+        if (this.redoStack.length > this.maxHistory)
+            this.redoStack.shift();
+    }
+    /** Pop the last undone entry and re-apply the forward ops. Pushes to undo. */
+    async redo() {
+        const entry = this.redoStack.pop();
+        if (!entry)
+            return;
+        const tx = createTransaction(this.schema, this.store, this.organizationId);
+        await applyOps(tx, entry.forwards);
+        this.undoStack.push(entry);
+        if (this.undoStack.length > this.maxHistory)
+            this.undoStack.shift();
+    }
+    /** Drop all history. Use after bootstrap / sync group change / sync error. */
+    clear() {
+        this.undoStack = [];
+        this.redoStack = [];
+    }
+    /** Introspection — for debug panels / e2e tests. */
+    size() {
+        return { undo: this.undoStack.length, redo: this.redoStack.length };
+    }
+}
+// ── Manager ────────────────────────────────────────────────────────────────
+/**
+ * Central registry of named undo scopes. One per-app instance, created once
+ * during engine setup. Mutator invocations find their scope by name.
+ */
+export class UndoManager {
+    schema;
+    store;
+    organizationId;
+    scopes = new Map();
+    constructor(schema, store, organizationId) {
+        this.schema = schema;
+        this.store = store;
+        this.organizationId = organizationId;
+    }
+    getScope(name, options) {
+        let scope = this.scopes.get(name);
+        if (!scope) {
+            scope = new UndoScope(this.schema, this.store, this.organizationId, options);
+            this.scopes.set(name, scope);
+        }
+        return scope;
+    }
+    clearAll() {
+        for (const scope of this.scopes.values())
+            scope.clear();
+    }
+}
+// ── Internal helpers ───────────────────────────────────────────────────────
+/**
+ * Replay a list of InverseOps through a Transaction. Used by both undo
+ * (replaying captured inverses) and redo (replaying the captured forwards).
+ * Every op is awaited sequentially to preserve ordering guarantees.
+ */
+async function applyOps(tx, ops) {
+    const mutateAny = tx.mutations;
+    for (const op of ops) {
+        const m = mutateAny[op.modelKey];
+        switch (op.kind) {
+            case 'create':
+                await m.create(op.data);
+                break;
+            case 'update':
+                await m.update(op.patch);
+                break;
+            case 'delete':
+                await m.delete(op.id);
+                break;
+            case 'createMany':
+                await m.create(op.data);
+                break;
+            case 'updateMany':
+                await m.update(op.patches);
+                break;
+            case 'deleteMany':
+                await m.delete(op.ids);
+                break;
+        }
+    }
+}

package/dist/mutators/defineMutators.d.ts

@@ -0,0 +1,55 @@
+/**
+ * defineMutators — Zero-style custom mutator declaration.
+ *
+ * Consumers declare a tree of named mutators grouped by model key. Each
+ * mutator is a plain async function that receives `{ tx, args }`. The body
+ * composes any number of `tx.mutate.*` / `tx.read.*` calls to implement a
+ * named operation (e.g. `slides.createWithLayers`).
+ *
+ * This file is pure type scaffolding + a pass-through factory. The runtime
+ * dispatcher lives in `./Transaction` (the `tx` object) and
+ * `../react/useMutators` (the React-side invoker builder). Keeping those
+ * concerns separate makes the types trivially inferable at the call site:
+ * `defineMutators(schema, { ... })` returns the literal object the consumer
+ * wrote, so `typeof mutators` carries every mutator's exact `args`/result
+ * signature into `useMutators`.
+ */
+import type { Schema } from '../schema/schema.js';
+import type { Transaction } from './Transaction.js';
+/**
+ * Signature of a single custom mutator. The host injects `tx`; the consumer
+ * controls `args` (whatever shape they want) and the resolved return value.
+ *
+ * We bound `TArgs`/`TResult` with `unknown` rather than `any` so consumers
+ * opt into the inference they need — the `MutatorDefs` record relaxes to
+ * `unknown` to let heterogeneous mutator trees unify without `any`.
+ */
+export type MutatorFn<S extends Schema, TArgs, TResult = void> = (options: {
+    tx: Transaction<S>;
+    args: TArgs;
+}) => Promise<TResult>;
+/**
+ * The shape `defineMutators` accepts: an optional record per model key whose
+ * values are named mutator functions.
+ *
+ * We intentionally use `unknown` in the bounds rather than `any` to preserve
+ * type-safety at the public API boundary. When a consumer writes their
+ * mutators inline, TypeScript infers the concrete `TArgs`/`TResult` for each
+ * function — the `unknown` here is just a ceiling, not what the consumer
+ * ends up seeing.
+ */
+export type MutatorDefs<S extends Schema> = {
+    [K in keyof S['models']]?: {
+        [mutatorName: string]: MutatorFn<S, never, unknown>;
+    };
+};
+/**
+ * Identity function that forwards the mutators object while constraining its
+ * shape against the schema. The `S` generic pins model keys; the `M` generic
+ * is `const`-inferred so each mutator's literal signature survives.
+ *
+ * Pattern mirrors Zero's own `defineMutators` / `createBuilder` — there is
+ * no runtime work to do here, it's purely a location for type inference to
+ * anchor.
+ */
+export declare function defineMutators<S extends Schema, const M extends MutatorDefs<S>>(_schema: S, mutators: M): M;

package/dist/mutators/defineMutators.js

@@ -0,0 +1,28 @@
+/**
+ * defineMutators — Zero-style custom mutator declaration.
+ *
+ * Consumers declare a tree of named mutators grouped by model key. Each
+ * mutator is a plain async function that receives `{ tx, args }`. The body
+ * composes any number of `tx.mutate.*` / `tx.read.*` calls to implement a
+ * named operation (e.g. `slides.createWithLayers`).
+ *
+ * This file is pure type scaffolding + a pass-through factory. The runtime
+ * dispatcher lives in `./Transaction` (the `tx` object) and
+ * `../react/useMutators` (the React-side invoker builder). Keeping those
+ * concerns separate makes the types trivially inferable at the call site:
+ * `defineMutators(schema, { ... })` returns the literal object the consumer
+ * wrote, so `typeof mutators` carries every mutator's exact `args`/result
+ * signature into `useMutators`.
+ */
+/**
+ * Identity function that forwards the mutators object while constraining its
+ * shape against the schema. The `S` generic pins model keys; the `M` generic
+ * is `const`-inferred so each mutator's literal signature survives.
+ *
+ * Pattern mirrors Zero's own `defineMutators` / `createBuilder` — there is
+ * no runtime work to do here, it's purely a location for type inference to
+ * anchor.
+ */
+export function defineMutators(_schema, mutators) {
+    return mutators;
+}