@abloatai/ablo 0.35.0 → 0.37.0

package/dist/mutators/UndoManager.d.ts

@@ -1,258 +0,0 @@
-/**
- * Keeps a per-scope history of reversible changes so a surface can offer undo
- * and redo. Each mutator invocation records an ordered list of inverse
- * operations; `undo()` pops the most recent group and replays those inverses
- * without recording them, then moves the entry onto the redo stack.
- *
- * History is divided into named scopes, one per surface — a report editor, a
- * ledger grid, and so on — reached through {@link UndoManager.getScope}. Undo in
- * one surface never affects another.
- *
- * Two things to know about its reach. History lives in memory and does not
- * persist across sessions. And if the server rejects a change after it was
- * applied optimistically, the undo stack is not invalidated automatically; call
- * {@link UndoScope.clear} on a sync error if you need strict correctness.
- */
-import type { Schema } from '../transaction/schema/schema.js';
-import type { SyncStoreContract } from '../react/context.js';
-import { type InverseOp, type UndoEntry } from './inverseOp.js';
-import { type UndoConflictPolicy } from './undoApply.js';
-export type { InverseOp, UndoEntry };
-export type { UndoConflictPolicy } from './undoApply.js';
-export interface UndoScopeOptions {
-    /** The maximum number of undo entries to keep. Older entries drop off the
-     *  bottom. Defaults to 100. */
-    maxHistory?: number;
-    /**
-     * How undo and redo treat a field a collaborator changed after your own
-     * change. The default, `skip-stale`, reverts your change only where it still
-     * stands, so undo never overwrites a concurrent edit — undo is per user.
-     * `last-writer-wins` restores the older behavior of overwriting regardless. See
-     * {@link UndoConflictPolicy}.
-     */
-    conflictPolicy?: UndoConflictPolicy;
-    /**
-     * A predicate selecting which models this surface owns. The scope records only
-     * mutations whose resolved schema key passes it, so, for example, a ledger
-     * edit never lands on a report editor's undo stack. Omit it to track every model,
-     * which is fine for a single-surface app but wrong when two surfaces with
-     * independent undo share one store.
-     */
-    tracksModel?: (schemaKey: string) => boolean;
-    /**
-     * When `true`, the scope records undo entries by observing the stream of local
-     * mutations, so every write through the store is captured automatically. When
-     * `false`, the default, the scope records nothing on its own and relies on
-     * explicit {@link UndoScope.record} calls. Use one mode or the other for a given
-     * surface, not both, or shared writes are counted twice.
-     */
-    recordFromStream?: boolean;
-}
-export declare class UndoScope<S extends Schema> {
-    private readonly schema;
-    private readonly store;
-    private readonly organizationId;
-    private undoStack;
-    private redoStack;
-    private readonly maxHistory;
-    private readonly conflictPolicy;
-    /**
-     * Observers notified after each successful {@link UndoScope.record}. They see
-     * forward user actions only: undo and redo move entries between the stacks
-     * without calling `record`, so a listener never observes a reversal. It is a
-     * deliberately generic hook — analytics or audit code can watch the stream of
-     * committed mutations without the scope knowing about it. A listener that throws
-     * is isolated so it cannot break recording.
-     */
-    private readonly recordListeners;
-    /**
-     * Observers notified after any stack change — record, undo, redo, or clear.
-     * Unlike {@link recordListeners}, which fires on forward actions only, this
-     * fires on reversals too, so a React consumer can keep `canUndo` and `canRedo`
-     * current. Because the stream-recording path adds entries without triggering a
-     * render, a component that read `canUndo` on its last render would otherwise go
-     * stale and a keyboard handler gated on it would quietly do nothing.
-     */
-    private readonly changeListeners;
-    /**
-     * The serialization tail. Recording, undo, and redo all chain off this one
-     * promise, so they run strictly in the order they were invoked and never
-     * interleave. This matters for correctness, not just throughput, in two ways.
-     * Ordering: callers often fire writes without awaiting them, so without
-     * serialization an entry would land on the stack when its mutator resolves, and
-     * a fast second write could record before a slow first — replaying undo in the
-     * wrong order. Snapshot integrity: each recording reads and clears a model's
-     * modified-field markers, which form the undo baseline, so two recordings
-     * interleaving on the same model would corrupt each other's before-image.
-     * Serializing the whole scope closes both gaps at once.
-     */
-    private tail;
-    /** Predicate selecting which models this surface records (see options). */
-    private readonly tracksModel?;
-    /** registered-name / alias → schema key, built once from the schema. */
-    private readonly schemaKeyByAlias;
-    /** Unsubscribe from the local-mutation stream. */
-    private readonly unsubscribe;
-    /**
-     * True while undo or redo is replaying operations. A replay writes through the
-     * normal commit path and therefore re-emits on the local-mutation stream; this
-     * flag tells the scope's own listener to ignore those writes so they are not
-     * recorded again.
-     */
-    private replaying;
-    /** Operations collected during the current tick, flushed together as one entry. */
-    private batch;
-    private flushScheduled;
-    /**
-     * An open grouping session. While set, stream operations accumulate here across
-     * ticks instead of flushing each tick, so a multi-tick action — a drag, or a
-     * whole streaming AI response — collapses into a single undo step.
-     * {@link UndoScope.endGroup} flushes it.
-     */
-    private group;
-    /**
-     * Suppression of a replay's asynchronous echo, keyed by `${modelKey}:${id}`.
-     *
-     * The synchronous {@link UndoScope.replaying} flag catches only echoes
-     * delivered inline while operations are applied. In practice the engine does not
-     * emit a replayed write's echo synchronously: the commit is deferred behind a
-     * local-store write, so the echo arrives on the stream after undo or redo has
-     * already reset `replaying` and pushed its entry. That late echo would be
-     * recorded as a new edit — and recording clears the redo stack, so every undo
-     * would quietly destroy its own redo. To prevent that, the row of each operation
-     * about to be replayed is marked here synchronously, before the write, and one
-     * mark is consumed when the matching mutation arrives, whenever that is. Marks
-     * carry a time-to-live so an echo that never arrives — because the write was
-     * skipped while offline — cannot linger and wrongly suppress a much later, real
-     * edit to the same row.
-     */
-    private readonly pendingReplayEchoes;
-    constructor(schema: S, store: SyncStoreContract, organizationId: string, options?: UndoScopeOptions);
-    /**
-     * Opens a grouping session: every stream-recorded operation until
-     * {@link UndoScope.endGroup} collapses into one undo entry. Call it at the start
-     * of a gesture, such as a pointer-down, or at the start of an AI response. A
-     * second call closes the previous group first.
-     */
-    beginGroup(label?: string): void;
-    /** Close the grouping session and record the accumulated ops as one entry. */
-    endGroup(label?: string): void;
-    /** Every `${modelKey}:${id}` a set of ops will touch (all op kinds). */
-    private replayEchoKeys;
-    /**
-     * Arms echo suppression for the rows a replay is about to write. Called
-     * synchronously, before the writes, so the marks exist however long the engine
-     * takes to surface each echo on the stream. See {@link UndoScope.pendingReplayEchoes}.
-     */
-    private markReplayEchoes;
-    /**
-     * If `${schemaKey}:${modelId}` has an armed mark, consume one and report that
-     * this mutation is the scope's own replay echo, so the caller drops it. Expired
-     * marks are pruned along the way, so an echo that never arrives cannot linger.
-     */
-    private consumeReplayEcho;
-    /** Resolve a stream mutation's registered name to its schema key, or null. */
-    private resolveSchemaKey;
-    /**
-     * The stream listener, and the only place stream-recorded entries originate. It
-     * skips replay echoes and out-of-scope models, derives the forward and inverse
-     * operations from the mutation's `data` and `previousData`, and defers the stack
-     * push to a per-tick flush, so a burst of writes — aligning five blocks at once,
-     * say — becomes a single undo step.
-     */
-    private onLocalMutation;
-    private scheduleFlush;
-    /** Coalesce the tick's collected ops into one entry and record it. */
-    private flushBatch;
-    /**
-     * Run `work` after every previously-enqueued scope operation has settled,
-     * in invocation order. The internal `tail` always resolves (failures are
-     * swallowed *for the chain only*) so one rejected mutator can't wedge the
-     * queue; the original settlement is still surfaced to this call's caller.
-     */
-    private enqueue;
-    /**
-     * Runs a recording mutator by itself on the scope's serialization chain, so its
-     * snapshot, write, and {@link UndoScope.record} happen atomically with respect to
-     * undo and redo. This is used by the explicit-record path; the stream-recording
-     * path does not need it, since it derives entries from already-committed
-     * mutations.
-     */
-    runRecorded<T>(work: () => Promise<T>): Promise<T>;
-    /**
-     * Records one entry onto the undo stack and clears the redo stack. It is fed
-     * both by the per-tick flush and grouping paths from the local-mutation stream
-     * and by direct callers using explicit recording. Entries are built internally
-     * and therefore trusted, so the schema check here runs only outside production:
-     * it catches recorder bugs early, rejecting a malformed operation at ingestion
-     * with a clear path rather than letting it fail later during replay, without
-     * paying a validation cost on every user action in production. The real
-     * validation boundary is {@link parseUndoEntry}, applied to entries loaded from
-     * persistence, which is untrusted input.
-     */
-    record(entry: UndoEntry): void;
-    /**
-     * Subscribes to every recorded mutation. The listener fires synchronously at the
-     * end of each {@link UndoScope.record} call, once the entry is on the undo stack,
-     * and the returned function unsubscribes it. The listener receives the full
-     * {@link UndoEntry} — its `forwards` carry the `{ kind, modelKey, data }`
-     * operations — so a consumer can tell what changed without querying again.
-     */
-    onRecord(listener: (entry: UndoEntry) => void): () => void;
-    private emitRecord;
-    /**
-     * Subscribes to any stack change — record, undo, redo, or clear. The React
-     * `useUndoScope` hook uses this to re-render so `canUndo` and `canRedo` stay
-     * current for every consumer, not only the component that invoked undo or redo.
-     * The returned function unsubscribes.
-     */
-    onChange(listener: () => void): () => void;
-    private emitChange;
-    canUndo(): boolean;
-    canRedo(): boolean;
-    /**
-     * Pops the most recent entry, applies its inverse operations, and pushes it onto
-     * the redo stack. Under the default `skip-stale` policy the inverses are first
-     * filtered against the current state — paired with the entry's forwards, which
-     * record what this change set — so a field a collaborator changed afterward is
-     * left untouched, and undo reverts the change only where it still stands.
-     */
-    undo(): Promise<void>;
-    /**
-     * Pops the most recently undone entry, re-applies its forward operations, and
-     * pushes it onto the undo stack. It mirrors {@link UndoScope.undo}: the forwards
-     * are filtered against the current state — paired with the entry's inverses,
-     * which record what undo restored — so redo re-asserts the change only where the
-     * undone value still stands.
-     */
-    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;
-    };
-    /**
-     * Detach from the local-mutation stream and drop listeners. Scopes are
-     * cached for the store's lifetime by `UndoManager`, so this is mainly for
-     * tests and explicit teardown.
-     */
-    dispose(): void;
-}
-/**
- * The registry of named undo scopes. One instance is created per application
- * during engine setup, and each surface finds its scope by name through
- * {@link UndoManager.getScope}.
- */
-export declare class UndoManager<S extends Schema> {
-    private readonly schema;
-    private readonly store;
-    private readonly organizationId;
-    private readonly scopes;
-    /** The options each scope was constructed with, for the mismatch warning below. */
-    private readonly creationOptions;
-    constructor(schema: S, store: SyncStoreContract, organizationId: string);
-    getScope(name: string, options?: UndoScopeOptions): UndoScope<S>;
-    clearAll(): void;
-}