@graphty/graphty-element 2.6.2 → 3.0.0

package/dist/src/session/project/Dispatcher.d.ts

@@ -0,0 +1,905 @@
+/**
+ * @file The one path every change to project state takes.
+ *
+ * A command is looked up by its op, its arguments are copied and frozen, and it joins a group: a
+ * plain dispatch is a group of its own, and a dispatch through a transaction's `tx` joins that
+ * transaction's group. An undoable command writes through the group's draft; an exempt command
+ * gets no draft at all. When a group seals, its patch becomes one step in the history. When it
+ * fails or is cancelled, its writes are reverted through the same `applyBackward` that undo uses,
+ * and nothing is recorded. See design/undo/undo-design.md sections 4 to 6.1.
+ *
+ * Two lanes. An immediate command executes synchronously inside `dispatch`, so a write is visible
+ * to a getter as soon as `dispatch` returns. A queued command takes a slot on the session's queue
+ * (through a {@link Scheduler}) and executes when its turn comes; until it has committed it is
+ * pending work, listed in `pending` and cancellable.
+ *
+ * Op-log keys (node and edge ids, or a whole `graph` or `pins` slice) cannot be handed from one
+ * open group to another the way value keys are, so a group holds the op-log keys it touched until
+ * it seals. A command needing a key an open transaction holds fails at once with
+ * `E_HELD_BY_TRANSACTION`; one needing a key any other open group holds waits for it, and runs
+ * when that group commits or is dropped when it rolls back.
+ *
+ * Every change reaches the screen through the derivation lane (`./derive.ts`), and is published
+ * in one order (design section 9.3): the state changes and a pass is scheduled; `project` and
+ * `history` events fire synchronously; the pass runs; the `derived` events (the per-domain
+ * events) fire; the caller's promise settles last. Undo, redo and restore act at call time, and
+ * one called from inside a listener runs after the current call has returned.
+ */
+import type { OperationCategory } from "../../managers/OperationQueueManager";
+import type { LegacyService, RunService } from "../commands/algo";
+import type { DataService } from "../commands/data";
+import type { LayoutAdvice, LayoutService } from "../commands/layout";
+import type { SetService } from "../commands/sets";
+import type { StyleService } from "../commands/style";
+import type { CameraService } from "../commands/view";
+import type { VisibilityService } from "../commands/visibility";
+import type { ProjectConfig } from "../types";
+import { Arrangement } from "./arrangement";
+import { DerivationLane } from "./derive";
+import { type Draft, type Patch } from "./draft";
+import { GraphOps, TouchedIds } from "./graphOps";
+import { History, type HistoryChangeReason } from "./History";
+import { type ProjectState } from "./state";
+/** The part of a command the dispatcher reads: its op. */
+interface CommandLike {
+    readonly op: string;
+}
+/** A key a command writes: a whole slice (`styles`, `graph`) or one key of one (`graph/n1`). */
+type SliceKey = string;
+/**
+ * The per-session parts a definition's `execute` reaches, such as the style compiler. Each
+ * slice's API sets its own part when it is built.
+ */
+interface CommandServices {
+    data?: DataService;
+    /** The arrangement: where `positions.*` write. Always present. */
+    positions?: Arrangement;
+    runs?: RunService;
+    /** A renderer's: constructs a plugin algorithm that has no descriptor, for `algo.legacy`. */
+    legacy?: LegacyService;
+    styles?: StyleService;
+    visibility?: VisibilityService;
+    sets?: SetService;
+    camera?: CameraService;
+    /** The renderer's layout engine and scene: what `layout.set` and `view.dimension` build. */
+    layout?: LayoutService;
+    /** Which layout suits the graph held now, for an import that asks for one. */
+    layoutAdvice?: LayoutAdvice;
+    /** The project settings in effect, with every unset key at its default. */
+    config?: () => ProjectConfig;
+}
+/** What the queue hands a queued command when its slot comes up. */
+interface SlotContext {
+    /** Where the queue's own progress events are written, when the queue publishes any. */
+    readonly progress?: {
+        setProgress(percent: number): void;
+        setMessage(message: string): void;
+        setPhase(phase: string): void;
+    };
+    /** The queue's id for the slot. */
+    readonly id?: string;
+}
+/** How one dispatch is made, beyond the command itself. */
+interface DispatchOptions {
+    /** Aborting it withdraws the command: off the queue if it waits, stopped if it runs. */
+    readonly signal?: AbortSignal;
+    /** A queued command that starts at once, beside the queue, instead of taking a slot. */
+    readonly beside?: boolean;
+}
+/** Dispatch one command, as a transaction's scope or a deferred member's origin does. */
+export type DispatchFunction = <C extends CommandLike>(command: Dispatchable<C>, options?: DispatchOptions) => Promise<unknown>;
+/** What an undoable command executes with: the state to read, and the draft that writes it. */
+export interface UndoableContext {
+    readonly state: ProjectState;
+    readonly services: CommandServices;
+    /** The group's draft. Read it when writing, after any await: it can change underneath. */
+    readonly draft: Draft;
+    /** Fires when the command is cancelled or made obsolete; a queued command stops on it. */
+    readonly signal: AbortSignal;
+    /** What the queue handed the slot; empty for an immediate command or one started beside it. */
+    readonly slot: SlotContext;
+    /** Settles, never rejecting, once the command has finished and the pass drawing it has run. */
+    readonly done: Promise<void>;
+    /**
+     * Start work on behalf of this command once its group has been recorded, as deferred members
+     * of its step: each merges into the step while it is on top. Registered once per key and
+     * group, so a batch of two adding commands starts it once. Dropped when the group rolls back.
+     * Its arguments: what the work is, so a second registration of it is ignored, and what starts
+     * it through the dispatch it is handed.
+     */
+    readonly after: (key: string, start: (dispatch: DispatchFunction) => void) => void;
+    /**
+     * Dispatch into this command's own group, now, whatever the dispatched command's lane: what
+     * `algo.legacy` hands the plugin it runs, through the graph facade (design section 4.5). The
+     * command writes only keys that are free or this group's own; one another group holds fails.
+     */
+    readonly inline: DispatchFunction;
+}
+/** What an exempt command executes with. No draft, so it cannot write project state. */
+interface ExemptContext {
+    readonly state: ProjectState;
+    readonly services: CommandServices;
+}
+/** Which lane a command runs on. */
+type Lane<C extends CommandLike> = {
+    readonly kind: "immediate";
+} | {
+    readonly kind: "queued";
+    /** The queue category, which decides the queue's obsolescence rules for it. */
+    readonly category: OperationCategory;
+    /** For an op whose commands differ (an add, an update, a removal): each one's category. */
+    categoryOf?(command: C): OperationCategory;
+    /** Two commands with one key collapse into one slot while the first has not started. */
+    coalesce?(command: C): string | null;
+};
+/** What every definition declares, whether or not it is undoable. */
+interface DefinitionBase<C extends CommandLike> {
+    readonly op: C["op"];
+    /**
+     * Takes a before-arrangement when it starts (design section 6.4): it sets coordinates on
+     * purpose, or holds its slot while a layout can move the lane (a chunked import).
+     */
+    readonly moves: boolean;
+    /** For an op only some of whose commands take one (`clear` among the data mutations). */
+    movesWhen?(command: C): boolean;
+    /** The keys it will write, known before it runs. */
+    keys(command: C, state: ProjectState): readonly SliceKey[];
+    readonly lane: Lane<C>;
+    /** Changes what is drawn, so its round trip is checked on a renderer as well. */
+    readonly draws?: boolean;
+    /**
+     * The values of its argument's discriminant (each `style.patch` action, each `data.apply`
+     * kind), each of which needs its own round-trip fixture. Absent when it has none.
+     */
+    readonly variants?: readonly string[];
+    /**
+     * Argument keys kept as the caller's own objects wherever they appear, never copied or
+     * frozen (a style layer's `userData`). Everything else is copied and frozen at dispatch.
+     */
+    readonly byReference?: readonly string[];
+    /**
+     * For a compound op (`batch`): the commands it is made of. It runs as a transaction of
+     * them, one step, and its own `execute` is never called.
+     */
+    members?(command: C): {
+        readonly label: string;
+        readonly steps: readonly CommandLike[];
+    };
+    /** Settling, whether it commits or fails, closes the baseline window (an import). */
+    readonly closesBaseline?: boolean;
+    /**
+     * Carried out only on a renderer, which registers the service it needs: a headless session
+     * refuses it, so its round trip is checked on a renderer only.
+     */
+    readonly renderer?: boolean;
+}
+/** A command that changes project state: one step, labelled. */
+export interface UndoableDefinition<C extends CommandLike> extends DefinitionBase<C> {
+    readonly undo: {
+        readonly kind: "undoable";
+        /** What the step is called in the history ("Changed colour of Hubs"). */
+        label(command: C, state: ProjectState): string;
+        /** Steps with equal keys recorded close together become one step. */
+        coalesce?(command: C): string | null;
+    };
+    /** Compute first, write last. */
+    execute(command: C, ctx: UndoableContext): unknown;
+}
+/** A command that changes nothing a project file saves, and why. */
+export interface ExemptDefinition<C extends CommandLike> extends DefinitionBase<C> {
+    readonly undo: {
+        readonly kind: "exempt";
+        readonly reason: string;
+    };
+    execute(command: C, ctx: ExemptContext): unknown;
+}
+/**
+ * How one op behaves under undo, and what it does. Write a definition against
+ * `UndoableDefinition` or `ExemptDefinition`, so `execute` gets the context of its kind.
+ */
+export type CommandDefinition<C extends CommandLike> = UndoableDefinition<C> | ExemptDefinition<C>;
+/**
+ * A command, or a function from state to one, called at dispatch. The late form is for doors
+ * whose meaning depends on state at that moment; history records the concrete command.
+ */
+type Dispatchable<C extends CommandLike = CommandLike> = C | ((state: ProjectState) => C);
+/** The handle a transaction's callback dispatches through; what it dispatches joins the step. */
+export interface TransactionScope {
+    dispatch<C extends CommandLike>(command: Dispatchable<C>, options?: DispatchOptions): Promise<unknown>;
+    /** Nested transactions flatten into the outermost one: `fn` runs with this same scope. */
+    transaction<T>(label: string, fn: TransactionBody<T>, options?: TransactionOptions): Promise<T>;
+}
+type TransactionBody<T> = (tx: TransactionScope, signal: AbortSignal) => T | Promise<T>;
+interface TransactionOptions {
+    /** Stamped on the recorded step, e.g. `{ via: "assistant" }`. */
+    readonly provenance?: Readonly<Record<string, string>>;
+    /** Declared at construction: while the baseline window is open it commits into the baseline. */
+    readonly setup?: boolean;
+    /**
+     * A batch's transaction: its members are known when it opens and it settles by itself, so a
+     * command needing a key it holds waits for it instead of being refused.
+     */
+    readonly compound?: boolean;
+    /**
+     * Takes its before-arrangement when it opens, not at its first graph write: a node drag, whose
+     * pointer moves write the lane before anything is dispatched (design section 5.3).
+     */
+    readonly moves?: boolean;
+}
+/** What moved live project state. */
+type HistoryCause = "command" | "undo" | "redo" | "restore" | "rollback";
+/** A change to live project state. */
+interface ProjectChange {
+    readonly slices: readonly string[];
+    readonly cause: HistoryCause;
+}
+/** Why the history, or what the next undo will do, changed. */
+type HistoryReason = HistoryChangeReason | "pending";
+/** Where the dispatcher publishes; the session turns these into its events. */
+interface DispatcherEvents {
+    /** `project:changed`: synchronously, as soon as the state has changed. */
+    project?: (change: ProjectChange) => void;
+    /** `history:changed`: synchronously, after `project`. */
+    history?: (reason: HistoryReason) => void;
+    /** After the derivation pass: the per-domain events. One per step an undo or restore passes. */
+    derived?: (change: ProjectChange) => void;
+    /** Every command dispatched, as it arrives, before it runs; the doors test spies here. */
+    dispatched?: (command: CommandLike) => void;
+    /**
+     * After an undo, a redo or a restore that touched node or edge ids: the session selects them
+     * (design section 8). Not called when the steps touched none, or {@link TouchedIds.skip}.
+     */
+    touched?: {
+        /** The most ids worth selecting. */
+        readonly cap: () => number;
+        select(ids: TouchedIds): void;
+    };
+}
+/** One slot a queued command holds on the queue. */
+interface ScheduledSlot {
+    /** Fires when the queue drops or stops the slot, including when `cancel` is called. */
+    readonly signal: AbortSignal;
+    /** Give the slot up: removed when it has not started, aborted when it has. */
+    cancel(): void;
+}
+/** The queue queued commands take their turn on. */
+export interface Scheduler {
+    /**
+     * Take a slot. The slot is held from the start of `onTurn` until the promise it returns
+     * settles. `onTurn` is never called from inside `enqueue`.
+     * @param category - The queue category, for the queue's ordering and obsolescence rules.
+     * @param onTurn - Called when the slot comes up.
+     * @returns The slot.
+     */
+    enqueue(category: OperationCategory, onTurn: (context?: SlotContext) => Promise<void>, description?: string): ScheduledSlot;
+}
+/** The part of the element's `OperationQueueManager` a scheduler needs. */
+interface OperationQueue {
+    queueOperation(category: OperationCategory, execute: (context: SlotContext) => Promise<void>, options?: {
+        description?: string;
+    }): string;
+    getOperationController(operationId: string): AbortController | undefined;
+    cancelOperation(operationId: string): boolean;
+}
+/**
+ * The scheduler over the session's `OperationQueueManager`: a queued command takes its turn
+ * among the loads, layouts and runs already on it, and the queue's obsolescence rules reach it
+ * as a cancellation with reason "obsolete".
+ * @param queue - The queue.
+ * @returns The scheduler.
+ */
+export declare function queueScheduler(queue: OperationQueue): Scheduler;
+/** The part of a session's run queue a scheduler needs. */
+interface RunQueueLike {
+    queueOperation(category: "algorithm-run", execute: (context: SlotContext & {
+        readonly signal: AbortSignal;
+    }) => Promise<void> | void, options?: {
+        description?: string;
+    }): string;
+    cancelOperation(operationId: string): boolean;
+}
+/**
+ * The scheduler over a headless session's run queue, which has no categories and no
+ * obsolescence: a queued command takes its turn among the runs, in the order it was dispatched.
+ * @param queue - The queue.
+ * @returns The scheduler.
+ */
+export declare function runQueueScheduler(queue: RunQueueLike): Scheduler;
+/** Pending undoable work, as the history lists it. Frozen. */
+interface PendingStep {
+    readonly id: string;
+    readonly label: string;
+    /** ISO 8601 of the dispatch. */
+    readonly since: string;
+    readonly runIds: readonly string[];
+}
+/** What the next undo will do. */
+type NextUndo = {
+    readonly kind: "cancel";
+    readonly pending: readonly PendingStep[];
+} | {
+    readonly kind: "undo";
+    readonly step: HistoryStepView;
+} | null;
+/** A recorded step as the history publishes it. */
+type HistoryStepView = History<Patch>["steps"][number];
+/** What an undo, a redo or a restore did. */
+type HistoryOutcome = {
+    readonly kind: "undone" | "redone" | "restored";
+    readonly steps: readonly HistoryStepView[];
+} | {
+    readonly kind: "cancelled";
+    readonly pending: readonly PendingStep[];
+} | {
+    readonly kind: "nothing";
+};
+/** Why pending work stopped without committing. */
+type CancelReason = "undo" | "redo" | "cancel" | "obsolete" | "rollback";
+/**
+ * Why pending work was cancelled, read from the error its signal was aborted with.
+ * @param error - The abort reason.
+ * @returns The reason, or undefined when the error is not a cancellation of the dispatcher's.
+ */
+export declare function cancelReasonOf(error: unknown): CancelReason | undefined;
+interface DispatcherOptions {
+    readonly definitions: readonly CommandDefinition<CommandLike>[];
+    /** The baseline; an empty project when absent. */
+    readonly state?: ProjectState;
+    /** The clock of the coalescing window. */
+    readonly now?: () => number;
+    /** Where changes are published; replaceable later through `events`. */
+    readonly events?: DispatcherEvents;
+    /** The queue of queued commands: the session's, through {@link queueScheduler}. */
+    readonly scheduler?: Scheduler;
+    /**
+     * Open the baseline window (design section 3.3): until the first graph write records or the
+     * first import settles, what commits becomes the baseline instead of a step. A renderer's
+     * session opens it, so what the page declared is not undoable.
+     */
+    readonly baselineWindow?: boolean;
+}
+/** The one mutation path: groups, drafts, rollback, transactions and pending work. */
+export declare class Dispatcher {
+    readonly history: History<Patch>;
+    /** Where every change is derived to the picture; hooks register here. */
+    readonly lane: DerivationLane;
+    /** The listeners; the session sets them. */
+    readonly events: DispatcherEvents;
+    /** What definitions reach besides state; see {@link CommandServices}. */
+    readonly services: CommandServices;
+    /** The graph primitives over this dispatcher's `graph` and `pins` slices. */
+    readonly graph: GraphOps;
+    /** Node coordinates at rest: captures, the `arrangement` and `pins` hooks, rest points. */
+    readonly arrangement: Arrangement;
+    private readonly store;
+    private readonly definitions;
+    private readonly scheduler;
+    private readonly strict;
+    private readonly scopes;
+    /** Pending groups: queued, waiting, running, open transactions and deferred members. */
+    private readonly open;
+    /** Which group holds each op-log key. */
+    private readonly holders;
+    /** The groups holding any key of each op-log slice. */
+    private readonly bySlice;
+    /** Jobs waiting on a key another group holds. */
+    private readonly waiters;
+    private readonly steps;
+    /** Orders dispatches, records, undos and hold acquisitions against each other. */
+    private tick;
+    /** Moves whenever the pending list changes. */
+    private changes;
+    /** Moves whenever a hold is taken, which can change what the next undo does. */
+    private holdChanges;
+    private pendingCache;
+    private nextCache;
+    /** `history` reasons not yet published. */
+    private readonly reasons;
+    /** Above zero while a listener runs: a history call made then waits for a microtask. */
+    private emitting;
+    /** The ids the steps passed by the history call under way touched; null outside one. */
+    private touching;
+    /** What an immediate command threw synchronously, for {@link Dispatcher.dispatchNow}. */
+    private syncFailure;
+    /** Whether commits still become the baseline rather than steps (design section 3.3). */
+    private baselineOpen;
+    /** Where an untagged dispatch goes during a call through a group-tagged facade; see {@link Dispatcher.routed}. */
+    private route;
+    /**
+     * Stamped on every step as it is recorded, under the step's own provenance: the renderer
+     * stamps `xr` while an immersive session is active (design section 5.3).
+     */
+    ambientProvenance: (() => Readonly<Record<string, string>>) | null;
+    /**
+     * Create a dispatcher over a state it alone will write.
+     * @param options - The definitions, the baseline, the clock, the change listener and the queue.
+     */
+    constructor(options: DispatcherOptions);
+    /**
+     * The live project state. Read-only; only commands write it.
+     * @returns The state.
+     */
+    get state(): ProjectState;
+    /**
+     * Undoable work dispatched and not yet committed, oldest first: queued commands, commands
+     * waiting on a key, open transactions and deferred members. The identical array between
+     * changes.
+     * @returns The frozen list.
+     */
+    get pending(): readonly PendingStep[];
+    /**
+     * What the next {@link Dispatcher.undo} will do: cancel pending work, undo a step, or nothing.
+     * @returns The frozen answer, identical between changes.
+     */
+    get nextUndo(): NextUndo;
+    /**
+     * Dispatch one command as its own step. An immediate command executes before this returns; a
+     * queued one when its turn comes.
+     * @param command - The command, or a function from state to one.
+     * @param options - Its signal, and whether a queued command starts beside the queue.
+     * @returns What `execute` returned; rejects with what it threw, after reverting its writes,
+     * or with an `AbortError` when it was cancelled.
+     */
+    dispatch<C extends CommandLike>(command: Dispatchable<C>, options?: DispatchOptions): Promise<unknown>;
+    /**
+     * A dispatch that goes where one made now would -- to the transaction or running command a
+     * routed verb is inside, or to this dispatcher -- for a verb that dispatches after an await,
+     * when the routing, which lasts for the synchronous part of the call only, has ended.
+     * @returns The dispatch.
+     */
+    capturedDispatch(): <C extends CommandLike>(command: Dispatchable<C>) => Promise<unknown>;
+    /**
+     * Whether no group is open: nothing is executing, and no transaction or queued command is
+     * waiting to seal. What a minted id not yet sealed is told apart from one a rollback dropped by.
+     * @returns True when none is.
+     */
+    get idle(): boolean;
+    /**
+     * Whether a call through a group-tagged facade is on the stack, so a door that would take a
+     * turn on the operation queue dispatches at once instead: the queue's slot is the running
+     * command's own, and waiting for it would never end.
+     * @returns True during such a call.
+     */
+    get routing(): boolean;
+    /**
+     * Run `fn` with every untagged dispatch, transaction and immediate dispatch it makes routed
+     * to `via`. Membership is by origin: the routing lasts for the synchronous part of `fn` only,
+     * which is where a door dispatches, so nothing dispatched from anywhere else joins.
+     * @param via - Where the dispatches go: a running command's `inline`.
+     * @param fn - The call.
+     * @returns What `fn` returned.
+     */
+    routed<T>(via: DispatchFunction, fn: () => T): T;
+    /**
+     * Run `fn`, and record every command it dispatches through `tx` as one step once it settles
+     * and every non-run command it dispatched has executed. Runs still going then are deferred
+     * members: each merges into the step when it commits while the step is on top, and records
+     * as its own step otherwise.
+     *
+     * Membership is by origin: a dispatch made any other way while `fn` runs is its own step. If
+     * such a dispatch writes a value key the transaction wrote, it takes the key over, so the
+     * transaction's rollback leaves it alone; if it needs an op-log key the transaction holds, it
+     * fails at once with `E_HELD_BY_TRANSACTION`. If `fn` throws, or the transaction is aborted,
+     * everything it wrote is reverted, its pending members are cancelled, nothing is recorded,
+     * and the error is rethrown; until `fn` settles, and after, `tx` dispatches reject with an
+     * `AbortError`. After a clean settle they reject with `E_TRANSACTION_CLOSED`. A transaction
+     * that wrote nothing records nothing.
+     * @param label - The step's label.
+     * @param fn - The body. `signal` fires when the transaction is aborted.
+     * @param options - The provenance stamped on the step.
+     * @returns What `fn` returned.
+     */
+    transaction<T>(label: string, fn: TransactionBody<T>, options?: TransactionOptions): Promise<T>;
+    /**
+     * Abort an open transaction: revert what it wrote now, cancel its pending members, fire its
+     * signal, and reject it. Its `fn` keeps running until it notices, and every `tx` dispatch
+     * meanwhile rejects.
+     * @param tx - The transaction's scope.
+     */
+    abort(tx: TransactionScope): void;
+    /**
+     * Undo, acting on the first of these that applies (design section 6.1):
+     * 0. an open group holding an op-log key the top step touched, or holding graph keys taken
+     *    since the top step was recorded, is aborted, with its dependents;
+     * 1. otherwise the newest pending work dispatched after the top step, or deferred from it, is
+     *    cancelled, with every later-dispatched pending item that shares a key with it;
+     * 2. otherwise the top step is undone. Pending work dispatched before it keeps running.
+     *
+     * Acts at call time; called from inside a listener, it acts after the current call returns.
+     * @returns What was done, once the picture has caught up.
+     */
+    undo(): Promise<HistoryOutcome>;
+    /**
+     * Redo, by the rules of {@link Dispatcher.undo} checked against the step being redone: only
+     * pending work dispatched after that step was undone is cancelled first.
+     * @returns What was done, once the picture has caught up.
+     */
+    redo(): Promise<HistoryOutcome>;
+    /**
+     * Move to the state just after a step, or to the baseline, as the equivalent sequence of undos
+     * or redos: their cancellation rules apply for each step passed, the state changes all at
+     * once. Back to the baseline (null) cancels all pending work and aborts every open
+     * transaction.
+     * @param id - The step, or null for the baseline.
+     * @returns What was done, once the picture has caught up.
+     */
+    restoreTo(id: string | null): Promise<HistoryOutcome>;
+    /**
+     * Write the baseline: what `write` sets is the state history starts from, recorded as no step
+     * and published as no change. Only before anything has been recorded or is pending.
+     * @param write - Writes through a draft of its own.
+     */
+    seed(write: (draft: Draft) => void): void;
+    /**
+     * Drop every step, cancelling all pending work and aborting every open transaction: the
+     * current state becomes the baseline.
+     */
+    clear(): void;
+    /**
+     * The command of the newest pending work queued under a queued coalesce key, until it
+     * commits: what a door assigned and its getter reads back while the slot waits.
+     * @param key - The queued coalesce key.
+     * @returns The command, or undefined when nothing under that key is pending.
+     */
+    pendingCommand(key: string): CommandLike | undefined;
+    /**
+     * Do one command now, and throw what it throws, for a synchronous door. A queued command
+     * starts beside the queue rather than waiting for a turn, as `skipQueue` always did. Routed
+     * into a transaction, an immediate command that is refused throws here too, having reverted
+     * only its own writes; the transaction goes on.
+     * @param command - The command.
+     * @returns What `execute` returned.
+     */
+    dispatchNow<C extends CommandLike>(command: Dispatchable<C>): unknown;
+    /**
+     * Cancel one pending item, and every later-dispatched pending item that shares a key with it.
+     * @param id - The item's id in `pending`.
+     * @returns Every item cancelled; empty when the id is not pending.
+     */
+    cancel(id: string): readonly PendingStep[];
+    /**
+     * Whether a job's group takes a before-arrangement as it starts: the job's command moves, or
+     * it is a transaction's first graph write.
+     * @param job - The job starting.
+     * @returns True when it does.
+     */
+    private takesBefore;
+    /**
+     * Give a group its before-arrangement: where the lane is now (design section 6.4).
+     * @param group - The group.
+     */
+    private takeBefore;
+    /**
+     * Act now, or after the current call when called from inside a listener, and settle once the
+     * pass that derives the change has run.
+     * @param act - The history call.
+     * @returns Its outcome.
+     */
+    private historyCall;
+    /**
+     * One undo or redo, now.
+     * @param direction - Which.
+     * @returns What was done.
+     */
+    private move;
+    /**
+     * One restore, now.
+     * @param id - The step, or null for the baseline.
+     * @returns What was done.
+     */
+    private restore;
+    /**
+     * A collection for the history call starting, when anyone selects what it touched.
+     * @returns The collection, or null.
+     */
+    private startTouching;
+    /**
+     * Report what a patch the history just applied touched, during a history call.
+     * @param patch - The patch.
+     */
+    private collect;
+    /**
+     * Stop collecting, and hand what the history call touched to the session to select once the
+     * pass that derives the change has run.
+     */
+    private selectTouched;
+    /**
+     * Remember when steps were undone, for the redo rules.
+     * @param direction - How they were passed.
+     * @param steps - The steps.
+     */
+    private markUndone;
+    /**
+     * Publish a change: `project` and the pending `history` reasons now, the `derived` events
+     * once the pass has run.
+     * @param change - What changed, for `project`.
+     * @param derived - The per-domain changes, one per step.
+     */
+    private emit;
+    /**
+     * Queue a `history` reason, published at the next emit or in a microtask, whichever is first.
+     * @param reason - Why.
+     */
+    private note;
+    /** Publish every queued `history` reason, in order. */
+    private flushHistory;
+    /**
+     * Call a listener. A history call it makes waits; what it throws is rethrown unhandled, so
+     * it cannot leave the dispatcher half way through a change.
+     * @param listener - The call.
+     */
+    private notify;
+    /**
+     * The scope a transaction's `fn` dispatches through.
+     * @param group - The transaction's group.
+     * @returns The scope.
+     */
+    private scope;
+    /**
+     * Resolve and freeze one command and send it down its lane, in its own group or in `tx`'s.
+     * @param command - The command, or a function from state to one.
+     * @param tx - The transaction it joins, or null for a group of its own.
+     * @param options - Its signal, and whether a queued command starts beside the queue.
+     * @param origin - For a deferred member, the step it belongs to.
+     * @returns What an exempt command returned, or the undoable command's promise.
+     */
+    private submit;
+    /**
+     * Run a compound command's members as one transaction, or inside the one dispatching it.
+     * Every member is dispatched before any is awaited, so immediate members run now, in order.
+     * @param label - The step's label.
+     * @param steps - The members.
+     * @param tx - The transaction it was dispatched in, or null.
+     * @param setup - Whether it was declared at construction.
+     * @param beside - Whether its queued members start at once, beside the queue, as a
+     *     synchronous door's must.
+     * @returns Settles when every member has.
+     */
+    private compound;
+    /**
+     * Execute one command now in a running job's group, whatever its lane: `UndoableContext.inline`.
+     * It seals nothing and rolls back only its own writes when it fails; the group seals when the
+     * job that dispatched it does.
+     * @param command - The command, or a function from state to one.
+     * @param parent - The running job.
+     * @returns What an exempt command returned, or the command's promise.
+     */
+    private inline;
+    /**
+     * A queued job whose slot is not yet started and whose queued coalesce key is `key`.
+     * @param key - The queued coalesce key.
+     * @param tx - The transaction dispatching, or null.
+     * @returns The job, or undefined.
+     */
+    private queuedWith;
+    /**
+     * A queued job's turn has come: start it, or put it on the wait list off the queue.
+     * @param job - The job.
+     * @param context - What the queue handed the slot.
+     * @returns Settles when the slot can be given up.
+     */
+    private turn;
+    /**
+     * Start a job whose keys are free; make it wait when another group holds one; fail it when a
+     * transaction holds one.
+     * @param job - The job.
+     * @returns Whether it started, failed or waits.
+     */
+    private admit;
+    /**
+     * Execute a job with its keys held. Its result settles through `finish` or `fail`.
+     * @param job - The job.
+     */
+    private start;
+    /**
+     * A job has executed. A transaction member stays in the transaction's draft; any other group
+     * seals. A job cancelled meanwhile is ignored: its late value is discarded.
+     * @param job - The job.
+     * @param value - What `execute` returned.
+     */
+    private finish;
+    /**
+     * A job threw, or could not start. A transaction member reverts its own writes; any other
+     * group rolls back.
+     * @param job - The job.
+     * @param error - Why.
+     */
+    private fail;
+    /**
+     * The queue dropped or stopped a job's slot (reason "obsolete"), or its dispatcher withdrew
+     * it (reason "cancel"). The job's group rolls back, or for a transaction member only the
+     * member's own writes.
+     * @param job - The job.
+     * @param reason - Why.
+     */
+    private obsolete;
+    /**
+     * Wait for every non-run member of a closed transaction, including ones dispatched while
+     * waiting.
+     * @param group - The transaction's group.
+     */
+    private drain;
+    /**
+     * Record a transaction, and give each run still going a group of its own: a deferred member
+     * of the transaction's step.
+     * @param group - The transaction's group.
+     */
+    private sealTransaction;
+    /**
+     * Strict: nothing wrote state around the dispatcher since the last check -- the builder
+     * behind the `graph` slice, and every typed array state still keeps (design section 12.1).
+     */
+    private checkStrict;
+    /**
+     * Record a group's patch as one step, or nothing when it wrote nothing, then release its
+     * holds. A deferred member merges into its transaction's step while that step is on top.
+     * @param group - The group.
+     * @returns The step the patch is in, or null.
+     */
+    private seal;
+    /**
+     * Start the work a sealed group registered with `after`, as deferred members of its step.
+     * @param group - The group, sealed.
+     * @param step - The step it recorded, or null when it recorded none.
+     */
+    private startDeferred;
+    /**
+     * Whether a group's writes become the baseline rather than a step (design section 3.3), and
+     * close the baseline window at the first graph write. What the page declared at construction
+     * is baseline for as long as nothing has been recorded; anything else is while the window is
+     * open and it does not write the graph. The first graph write that is not declared is the
+     * first step.
+     * @param group - The group sealing.
+     * @param slices - The slices it wrote.
+     * @returns True when it records no step.
+     */
+    private intoBaseline;
+    /**
+     * Revert everything a group still holds, and say so when anything live changed.
+     * @param group - The group.
+     */
+    private rollback;
+    /**
+     * Live writes were reverted: derive them in restore mode, and say so.
+     * @param slices - The slices reverted; nothing happens when empty.
+     */
+    private reverted;
+    /**
+     * Cancel a group: stop its members, roll it back, and for a transaction, mark it aborted and
+     * fire its signal.
+     * @param group - The group.
+     * @param reason - What the group's caller rejects with: a plain group's job, or the transaction.
+     * @param why - Why a transaction's members were stopped, for their own rejections.
+     */
+    private cancelGroup;
+    /**
+     * Stop one job: off the queue, off the wait list, its signal fired, its caller rejected. Its
+     * writes are its group's to revert.
+     * @param job - The job.
+     * @param reason - What its caller's promise rejects with.
+     */
+    private stop;
+    /**
+     * A graph-writing job has ended, however it ended. When a pass left its paint to a later one
+     * while this was waiting or running (`paintOwed`) and nothing is waiting now, the lane is told,
+     * so a pass paints what the run wrote -- even when this one wrote nothing.
+     * @param job - The job.
+     */
+    private graphWriteEnded;
+    /**
+     * Set by the renderer's `graph` hook when a pass left its whole-graph repaint to a later one
+     * because a graph write was waiting (`graphWritesWaiting`); cleared once one is scheduled.
+     */
+    paintOwed: boolean;
+    /**
+     * Whether a command that writes the graph is dispatched and not finished. The pass deriving a
+     * graph write leaves the whole-graph repaint to a pass once none is, so a run of queued adds
+     * -- `addEdge` in a loop -- repaints once rather than once per add; the last such command to
+     * end, however it ends, schedules that pass (`paintOwed`).
+     * @returns True while one is.
+     */
+    get graphWritesWaiting(): boolean;
+    /**
+     * Cancel groups, newest first.
+     * @param groups - The groups, in dispatch order.
+     * @param reason - Why.
+     * @returns Their pending views, in dispatch order.
+     */
+    private cancelAll;
+    /**
+     * What an undo or a redo will act on (design section 6.1).
+     * @param direction - Which.
+     * @param target - The step it would pass; by default the one next to the cursor.
+     * @returns The groups to cancel, the step to move over, or null for nothing.
+     */
+    private plan;
+    /**
+     * The step next to the cursor.
+     * @param direction - Which side: the top done step, or the next undone one.
+     * @returns The step, or undefined at the end of the history.
+     */
+    private adjacent;
+    /**
+     * The groups to cancel with `roots`: every later-dispatched pending group sharing a key with
+     * one of them, transitively.
+     * @param roots - The groups being cancelled.
+     * @returns Them and their dependents, in dispatch order.
+     */
+    private cascade;
+    /**
+     * The group holding one of `keys`, other than `self`.
+     * @param keys - Op-log keys.
+     * @param self - The group asking, whose own holds do not block it.
+     * @returns The holder and the key, or null when every key is free.
+     */
+    private blocker;
+    /**
+     * Hold op-log keys for a group until it seals or rolls back.
+     * @param group - The group.
+     * @param keys - The keys.
+     */
+    private acquire;
+    /**
+     * Release a group's holds, and wake what waited on them: on commit it runs, on rollback it is
+     * dropped.
+     * @param group - The group.
+     * @param committed - Whether the group sealed rather than rolled back.
+     */
+    private release;
+    /**
+     * A new group, with its draft open.
+     * @param label - Its label.
+     * @param key - Its history coalesce key.
+     * @param provenance - Stamped on its step.
+     * @param after - The step it is a deferred member of, or null.
+     * @param seq - Its dispatch order.
+     * @param tx - Its transaction state, for a transaction's group.
+     * @param setup - Declared at construction.
+     * @param compound - A batch's transaction.
+     * @returns The group.
+     */
+    private group;
+    /**
+     * A new job, not yet on any lane.
+     * @param command - The concrete command.
+     * @param keys - Its declared keys.
+     * @param definition - Its definition.
+     * @param group - The group it writes into.
+     * @param queuedKey - Its queued coalesce key.
+     * @param inline - Dispatched inline by a running job of its group.
+     * @returns The job.
+     */
+    private job;
+    /**
+     * List a group as pending.
+     * @param group - The group.
+     */
+    private enter;
+    /**
+     * Stop listing a group as pending, and mark it done.
+     * @param group - The group.
+     */
+    private leave;
+    /**
+     * The pending groups in dispatch order.
+     * @returns The groups.
+     */
+    private ordered;
+    /**
+     * A group as `pending` lists it.
+     * @param group - The group.
+     * @returns The frozen view.
+     */
+    private view;
+    /**
+     * Run `settle` once the change being made now has been derived. The lane is asked at the end
+     * of the current synchronous work, when every write of it has been marked.
+     * @param settle - What to run.
+     */
+    private afterPass;
+    /** The pending list changed. */
+    private changed;
+    /** Forget the record times of steps the history no longer has. */
+    private prune;
+}
+export {};