@graphty/graphty-element 2.6.1 → 3.0.0

package/dist/src/session/runs/Run.d.ts

@@ -25,6 +25,7 @@
  */
 import type { AlgorithmKey, FieldDescriptor, ResultShape, RunId } from "../../catalog/types";
 import { GraphtyError } from "../../errors";
+import type { RunEntry } from "../project/state";
 import type { ResultSummary, RunResult } from "../results/types";
 import type { HeldCaptures } from "../sets/captures";
 import { type StyleSuggestion } from "../styles/derive";
@@ -62,8 +63,19 @@ export interface RunQueueContext {
     /** The queue's operation id, which is not the run id. */
     readonly id: string;
 }
-/** A run's work, as the queue takes it. */
-export type RunBody = (context: RunQueueContext) => Promise<void>;
+/**
+ * Write a finished run into project state: its entry in the `runs` slice and the layers it
+ * paints, in the step of the command that ran it. Throws to refuse, before anything is written.
+ * @param run - The run, finished and not yet settled: its record reads "succeeded".
+ * @returns Settles once the step is recorded and drawn, which is when the run's promise resolves.
+ */
+type RunCommit = (run: ManagedRun) => Promise<void>;
+/**
+ * A run's work, as the queue takes it.
+ * @param context - What the queue hands the operation.
+ * @param commit - For a run that is project state, how it writes itself when it finishes.
+ */
+export type RunBody = (context: RunQueueContext, commit?: RunCommit) => Promise<void>;
 /** A handle on work that has been handed to the queue. */
 export interface RunTicket {
     /** Stop the work, whether it has started or is still waiting its turn. */
@@ -227,6 +239,15 @@ export interface RunSurroundings {
      * @param phase - Which moment.
      */
     notify?(phase: RunPhase): void;
+    /**
+     * The entry the `runs` slice holds for this run, for a run that is project state.
+     *
+     * Present, the run's result and record are read from the entry whenever no execution of it
+     * is under way, so an undo or a redo that swaps the entry changes what the same handle
+     * reports. Absent (a batch, a style edit), the handle reports its own last execution.
+     * @returns The entry, or undefined when the slice holds none.
+     */
+    entry?(): RunEntry | undefined;
     /**
      * Mint the token that identifies one execution of this run (design/sets 5.2): a session nonce
      * plus a session-wide counter. Called once when the work starts. Optional for the same reason
@@ -292,6 +313,10 @@ export declare class ManagedRun<T = RunResult> implements Run<T> {
     private detachSignal;
     private queueSink;
     private settledFlag;
+    /** Whether the latest execution wrote the run into project state. */
+    private committed;
+    /** How many executions this handle has started. */
+    private generationValue;
     /** Why a cancel is being honoured, when the run publishes what it has instead of rejecting. */
     private cancelReason;
     /**
@@ -325,6 +350,22 @@ export declare class ManagedRun<T = RunResult> implements Run<T> {
      * @returns The status.
      */
     get status(): RunStatus;
+    /**
+     * How many executions this run has started: its own first, and one per re-run.
+     * @returns The count.
+     */
+    get generation(): number;
+    /**
+     * Whether an execution is waiting or working.
+     * @returns True while queued or running.
+     */
+    private get live();
+    /**
+     * The record the `runs` slice holds for this run, when that is what the handle reports: the
+     * run is project state, nothing is executing, and the latest execution was recorded.
+     * @returns The held record, or undefined.
+     */
+    private heldRecord;
     /**
      * How far along the run is.
      * @returns The progress.
@@ -383,18 +424,34 @@ export declare class ManagedRun<T = RunResult> implements Run<T> {
      * @returns The result, or undefined until the run succeeds.
      */
     get result(): T | undefined;
+    /**
+     * The result the latest execution produced, before it is recorded: what a commit writes.
+     * @returns The result, or undefined when the execution produced none.
+     */
+    get computed(): T | undefined;
     /**
      * The execution token of the current result: undefined until a result exists, and for a run
      * whose surroundings mint none. Internal: not on the published `Run` interface.
      * @returns The token.
      */
     get resultExecution(): string | undefined;
+    /**
+     * The token of the execution that produced {@link ManagedRun.computed}, before it is recorded:
+     * what a commit writes with it.
+     * @returns The token.
+     */
+    get computedExecution(): string | undefined;
     /**
      * The members of earlier executions' items that live references hold, by execution and item
      * key. Internal: not on the published `Run` interface.
      * @returns The captures.
      */
     get held(): HeldCaptures;
+    /**
+     * The captures the latest execution holds, before it is recorded: what a commit writes.
+     * @returns The captures.
+     */
+    get computedHeld(): HeldCaptures;
     /**
      * Why the run failed.
      * @returns The error, or undefined when it did not.
@@ -436,6 +493,13 @@ export declare class ManagedRun<T = RunResult> implements Run<T> {
      * @returns This run, restarted.
      */
     rerun(): Run<T>;
+    /**
+     * Keep the run's promise from settling until other work done on its behalf has: a step that
+     * applies the layers of a run that did not need computing again. The promise settles as it
+     * would have, whatever that work does.
+     * @param work - The work.
+     */
+    settleAfter(work: PromiseLike<unknown>): void;
     /**
      * Run the same result again with other parameters or another seed, keeping its id, so every
      * style layer and reference bound to the result repaints from the new values. Work still
@@ -460,6 +524,7 @@ export declare class ManagedRun<T = RunResult> implements Run<T> {
     /**
      * The work, as the queue runs it.
      * @param context - What the queue hands the operation.
+     * @param commit - For a run that is project state, how it writes itself once it finishes.
      */
     private body;
     /**
@@ -478,6 +543,13 @@ export declare class ManagedRun<T = RunResult> implements Run<T> {
      * @param timeBox - The time box's signal, so an expired box becomes a partial result.
      */
     private succeed;
+    /**
+     * Take in what the work produced: the result, its caveats and fields, and the final status.
+     * The promise is left for whoever settles it.
+     * @param outcome - What the work produced.
+     * @param timeBox - The time box's signal, so an expired box becomes a partial result.
+     */
+    private finishWork;
     /**
      * Record a piece of work that threw.
      * @param error - What it threw.
@@ -540,6 +612,10 @@ export declare class ManagedRun<T = RunResult> implements Run<T> {
      * @param action - Resolve or reject.
      */
     private settle;
-    /** Put the run back the way it was before it ran, keeping its id and its definition. */
-    private resetForRerun;
+    /**
+     * Open a new execution under the same id. What the last one produced -- its result, fields,
+     * caveats and timings -- stays readable until this one finishes: a re-run keeps what it had.
+     */
+    private beginExecution;
 }
+export {};

package/dist/src/session/runs/RunsApi.d.ts

@@ -18,12 +18,13 @@
  * structural view of `OperationQueueManager` narrow enough that the session never imports the
  * renderer's manager to talk to it.
  */
-import { type AlgorithmDescriptor, type LayerId, type RunId, type Scope, type ScopeInput, type SetId } from "../../catalog/types";
+import { type AlgorithmDescriptor, type AlgorithmKey, type LayerId, type RunId, type Scope, type ScopeInput, type SetId } from "../../catalog/types";
+import { Dispatcher, type DispatchFunction } from "../project/Dispatcher";
 import type { HeldCaptures } from "../sets/captures";
-import type { AutoApplyPolicy } from "../styles/autoApply";
+import { type AutoApplyPolicy } from "../styles/autoApply";
 import { type RunExecutor, type RunQueueContext } from "./Run";
 import { type LiveKeyword } from "./runId";
-import { type Caveats, type EngineVersions, type ResolvedScope, type RunChange, type RunsApi, type RunScopeFacts } from "./types";
+import { type Caveats, type EngineVersions, type ResolvedScope, type Run, type RunChange, type RunsApi, type RunScopeFacts, type StartOptions } from "./types";
 /**
  * The element's operation queue, as a run needs it.
  *
@@ -89,10 +90,11 @@ interface RunLayerBindings {
      */
     bindings(runId: RunId): readonly LayerId[];
     /**
-     * Remove layers, because the run they read is going away.
+     * Remove layers, because the run they read is going away. Used only by a runs API whose
+     * dispatcher has no style stack registered; a session removes them in the removal's own step.
      * @param layerIds - The layers to remove.
      */
-    remove(layerIds: readonly LayerId[]): void;
+    remove?(layerIds: readonly LayerId[]): void;
 }
 /** Everything the runs API is built from. */
 export interface RunsApiOptions {
@@ -163,6 +165,11 @@ export interface RunsApiOptions {
      * @param change - The run's record, and which moment it reached.
      */
     readonly onChange?: (change: RunChange) => void;
+    /**
+     * The dispatcher whose `runs` slice holds the finished runs and whose history records them.
+     * A session hands in its own; absent, the runs API keeps a private one over its queue.
+     */
+    readonly dispatcher?: Dispatcher;
     /** Called once per execution token minted, which is what advances the session input tick. */
     readonly onExecution?: () => void;
     /** Called when a run is removed, and with it its result (design/sets 11). */
@@ -176,7 +183,7 @@ export interface RunsApiOptions {
      */
     readonly captureHeld?: (run: RunId, prior: HeldCaptures) => HeldCaptures;
 }
-/** The runs API, plus the two things a session needs and a consumer never calls. */
+/** The runs API, plus the things a session needs and a consumer never calls. */
 export interface SessionRunsApi extends RunsApi {
     /**
      * Whether the element minted this run's id rather than the author naming it with `as:`.
@@ -189,6 +196,16 @@ export interface SessionRunsApi extends RunsApi {
      * @returns True when the element derived the id.
      */
     isDerivedId(id: RunId): boolean;
+    /**
+     * Start one algorithm through a dispatch of the caller's: a transaction's, so the run joins
+     * its step, or the one a command hands its deferred members.
+     * @param dispatch - Where the run's command is dispatched.
+     * @param algorithm - Which algorithm to run.
+     * @param params - Its parameters.
+     * @param options - The scope, the seed, the id and the rest.
+     * @returns The run.
+     */
+    startVia(dispatch: DispatchFunction, algorithm: AlgorithmKey, params?: Readonly<Record<string, unknown>>, options?: StartOptions): Run;
     /**
      * What a run keeps of earlier executions' items that live references hold (design/sets 5.2).
      * @param id - The run id.

package/dist/src/session/runs/types.d.ts

@@ -46,8 +46,11 @@ export declare function isRunId(value: unknown): value is RunId;
  * "canceled" and "failed" are separate because a consumer treats them differently: a cancel is
  * something a person did and needs no apology, a failure is something the consumer has to
  * report. A time-boxed run that stopped early is neither -- it SUCCEEDS with `partial` set.
+ *
+ * "removed" is a finished run that undo has taken out of the project, or that `runs.remove`
+ * took away: its handle reports no result until a redo brings the run back.
  */
-export declare const RUN_STATUSES: readonly ["queued", "running", "succeeded", "failed", "canceled"];
+export declare const RUN_STATUSES: readonly ["queued", "running", "succeeded", "failed", "canceled", "removed"];
 /** Where a run is in its life. */
 export type RunStatus = (typeof RUN_STATUSES)[number];
 /** The statuses a run never leaves once it reaches them. */
@@ -65,14 +68,15 @@ export declare function isRunStatus(value: unknown): value is RunStatus;
  */
 export declare function isTerminalRunStatus(status: RunStatus): boolean;
 /**
- * The four moments a watcher is told about.
+ * The moments a watcher is told about: the four of a run's own life, and the two of history.
  *
  * Coarser than {@link RunStatus} on purpose: a status bar draws the same thing for a run that
  * failed and one that was cancelled -- it stops showing progress and reads the record -- so the
  * distinction belongs in the record the notification carries rather than in the notification's
- * own name.
+ * own name. "removed" and "restored" are an undo, a redo or a restore taking a finished run out
+ * of the project and putting it back; nothing was computed for either.
  */
-export declare const RUN_PHASES: readonly ["queued", "start", "progress", "end"];
+export declare const RUN_PHASES: readonly ["queued", "start", "progress", "end", "removed", "restored"];
 /** Which moment in a run's life a notification is about. */
 export type RunPhase = (typeof RUN_PHASES)[number];
 /**
@@ -87,6 +91,13 @@ export interface RunChange {
     readonly run: RunRecord;
     /** Which moment this is. */
     readonly phase: RunPhase;
+    /** What moved it: a command for the run's own life, or an undo, a redo or a restore. */
+    readonly cause: "command" | "undo" | "redo" | "restore" | "rollback";
+    /**
+     * How many times this run id has been executed, so a watcher keyed on the id can tell an old
+     * execution's `end` from a new one's.
+     */
+    readonly generation: number;
 }
 /**
  * How far a run has got.
@@ -315,6 +326,11 @@ export interface StartOptions extends RunOptions {
     readonly exact?: boolean;
     /** Ask for the approximate method at a chosen sample size. */
     readonly sample?: number;
+    /**
+     * Also apply the layers the run suggests, on top of the stack, in the same step as the run,
+     * so one undo takes the run and those layers away together.
+     */
+    readonly applySuggestedStyles?: boolean;
 }
 /**
  * What a run paints when it first completes.
@@ -487,7 +503,9 @@ export interface Run<T = RunResult> extends PromiseLike<T> {
     /** What qualifies the numbers. */
     readonly caveats: Caveats;
     /**
-     * The result, once there is one. Awaiting the run is the other way to get it.
+     * The result, once there is one. Awaiting the run is the other way to get it. Undefined
+     * again once undo has taken the run out of the project (`status` "removed"); a redo brings the
+     * same result object back.
      *
      * Spelled `?: T | undefined` rather than `?: T` because the implementation answers with a
      * getter, and under a consumer's `exactOptionalPropertyTypes` a getter that can return
@@ -513,7 +531,8 @@ export interface Run<T = RunResult> extends PromiseLike<T> {
      *
      * The new run keeps the SAME id, so every style layer, legend and saved reference bound to
      * it survives. That is what "re-run from a layer" needs, and it is why a binding never
-     * dangles after a re-run.
+     * dangles after a re-run. The last result stays readable until the new one is recorded, and
+     * undoing the re-run puts the previous result back without computing it again.
      * @returns The run, which is this one restarted rather than a second entry.
      */
     rerun(): Run<T>;

package/dist/src/session/scope/ElementMask.d.ts

@@ -235,6 +235,20 @@ export declare class ElementMask<TId> {
      * @returns A fresh `Uint8Array` of length {@link ElementMask.count}.
      */
     bytes(): U8;
+    /**
+     * Replace the whole membership with bytes {@link ElementMask.bytes} handed out earlier: one
+     * per row, and the row count becomes their length. The revision moves, as it does for a
+     * remap, because the membership was rewritten wholesale.
+     * @param bytes - One byte per row, `1` for a member.
+     */
+    load(bytes: U8): void;
+    /**
+     * A copy of this mask that refuses every write: the same rows, members and revision, so a
+     * reader keyed on `version` still sees the same number, but nothing done to the copy can
+     * reach this mask.
+     * @returns The copy.
+     */
+    readOnlyCopy(): ElementMask<TId>;
     /**
      * The membership as a packed bitmap in graph-format's mask layout (ceil(length / 32) words,
      * LSB-first): one pass of byte reads. A row at or past the live count is not a member.

package/dist/src/session/scope/ScopeApi.d.ts

@@ -32,31 +32,12 @@ import { type Capture } from "../sets/captures";
 import { type ComponentLabels, type Resolution, type ResolveContext } from "../sets/resolve";
 import type { SetsApi } from "../sets/types";
 import type { FilterSources, FilterValueSource, ScopeLeaf } from "../visibility/filter";
-import type { ElementMask, MaskIdSpace } from "./ElementMask";
+import type { ElementMask } from "./ElementMask";
+import { edgeSpaceOf, nodeSpaceOf } from "./spaces";
 export type { ComponentLabels } from "../sets/resolve";
 /** How many edges {@link ScopeApi.count} looks at when it is allowed to answer approximately. */
 export declare const DEFAULT_SCOPE_SAMPLE = 10000;
-/**
- * One snapshot's node identity space, for a mask over its nodes.
- * @param snapshot - The snapshot to read.
- * @returns The space, which is the snapshot's own id map.
- */
-export declare function nodeSpaceOf(snapshot: GraphSnapshot): MaskIdSpace<NodeId>;
-/**
- * One snapshot's edge identity space, for a mask over its edges.
- *
- * It READS the element-assigned counter the store stamped into every edge's `graphty.edgeId`
- * column rather than minting an id out of the endpoints, and that is the whole difference. A
- * minted pair string could not name two edges between one pair -- so under parallel edges only the
- * last of a repeated pair was addressable at all -- and it collided for any node id containing a
- * colon.
- *
- * The reverse lookup is `snapshot.edgeIndexOf`, a lazily built index graph-format already owns
- * over the same column, so there is no hand-built map here to fall out of step with it.
- * @param snapshot - The snapshot to read.
- * @returns The space.
- */
-export declare function edgeSpaceOf(snapshot: GraphSnapshot): MaskIdSpace<EdgeId>;
+export { edgeSpaceOf, nodeSpaceOf };
 /** The visible data scope: what filters and the time window have left showing. */
 export interface ScopeVisibilitySource {
     /**

package/dist/src/session/scope/spaces.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @file A snapshot's node and edge identity spaces, for masks over its rows. Kept apart from the
+ * scope resolver so a reader of ids (the simple tier's graph view, the style selector source) does
+ * not load the resolver and, through its sets, the session's dispatcher.
+ */
+import { type GraphSnapshot } from "@graphty/graph-format";
+import type { EdgeId, NodeId } from "../../catalog/types";
+import type { MaskIdSpace } from "./ElementMask";
+/**
+ * One snapshot's node identity space, for a mask over its nodes.
+ * @param snapshot - The snapshot to read.
+ * @returns The space, which is the snapshot's own id map.
+ */
+export declare function nodeSpaceOf(snapshot: GraphSnapshot): MaskIdSpace<NodeId>;
+/**
+ * One snapshot's edge identity space, for a mask over its edges.
+ *
+ * It READS the element-assigned counter the store stamped into every edge's `graphty.edgeId`
+ * column rather than minting an id out of the endpoints, and that is the whole difference. A
+ * minted pair string could not name two edges between one pair -- so under parallel edges only the
+ * last of a repeated pair was addressable at all -- and it collided for any node id containing a
+ * colon.
+ *
+ * The reverse lookup is `snapshot.edgeIndexOf`, a lazily built index graph-format already owns
+ * over the same column, so there is no hand-built map here to fall out of step with it.
+ * @param snapshot - The snapshot to read.
+ * @returns The space.
+ */
+export declare function edgeSpaceOf(snapshot: GraphSnapshot): MaskIdSpace<EdgeId>;

package/dist/src/session/sealed.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @file A set a consumer cannot write to, for every set the session hands out.
+ */
+/**
+ * A set that cannot be written to.
+ *
+ * `Object.freeze` alone does NOT stop `Set.prototype.add`: a frozen set that silently accepts an
+ * `add()` would hand a consumer a mutation the session never saw -- project state changed with no
+ * step, or a cached answer changed for every later reader. So the three mutators are replaced on
+ * the instance before it is frozen, and a caller that reaches for one is told rather than ignored.
+ * @param values - What to put in it.
+ * @param hint - What to call instead, said in the error.
+ * @returns The sealed set.
+ */
+export declare function sealedSet<T>(values: Iterable<T>, hint: string): ReadonlySet<T>;
+/**
+ * A read-only view of a map: every read, and no writer, not even through a cast. For a map the
+ * element keeps and hands out, where a writer would change what it holds behind every step.
+ * @param map - The map, which its owner goes on writing.
+ * @returns The view.
+ */
+export declare function readonlyMapView<K, V>(map: ReadonlyMap<K, V>): ReadonlyMap<K, V>;

package/dist/src/session/selection/SelectionApi.d.ts

@@ -47,11 +47,12 @@ export declare const SET_OPS: readonly SelectionOp[];
 /**
  * Who asked for a selection change.
  *
- * A consumer reacts differently to the three: a change a person made with the mouse should move
- * the camera and open the inspector, and the identical change made by a script replaying a
- * saved document should do neither.
+ * A consumer reacts differently to each: a change a person made with the mouse should move the
+ * camera and open the inspector, and the identical change made by a script replaying a saved
+ * document should do neither. `history` is an undo, a redo or a restore selecting the elements
+ * it changed.
  */
-export type SelectionCause = "user" | "api" | "command";
+export type SelectionCause = "user" | "api" | "command" | "history";
 /** What one mutation changed. */
 export interface SelectionDelta {
     /**
@@ -224,6 +225,15 @@ export interface SelectionOwner extends SelectionApi {
      * @returns What changed.
      */
     applyNow(target: SelectionTarget, op?: SelectionOp, cause?: SelectionCause): SelectionDelta;
+    /**
+     * Change the selection at the next read instead of now, so a change made while the graph has
+     * edits not yet frozen does not freeze it: how an undo selects what it changed without paying
+     * for a rebuild nobody asked for. A later call replaces one still waiting.
+     * @param target - What to select.
+     * @param op - What to do with it.
+     * @param cause - Who asked.
+     */
+    applyAtNextRead(target: SelectionTarget, op: SelectionOp, cause: SelectionCause): void;
     /**
      * The node mask itself, for the scope resolver's `selection` source.
      * @returns The live mask, which the caller must not mutate.

package/dist/src/session/sets/SetsApi.d.ts

@@ -2,15 +2,18 @@
  * @file The synchronous doors of `session.sets`: the reads that only look at records and the
  * writes that resolve nothing (design/sets/sets-design.md sections 13.2, 13.3, 15.2).
  *
- * Each write door does the one thing a pure `prepare` cannot: it reaches the graph to turn a
- * session edge id into the edge's stable identity, and it mints the id and the order. Then, in one
- * store write group, it prepares one operation and writes the result. A no-op writes nothing and
- * emits nothing.
+ * Each write door dispatches one `set.*` command through the session's dispatcher, so every write
+ * is one undoable step (design/sets/undo-integration.md section 2). A create's door mints the id
+ * and the order first, and says what the set was created from. The command's body, which this
+ * module hands the dispatcher as its set service, does the one thing a pure `prepare` cannot -- it
+ * reaches the graph to turn a session edge id into the edge's stable identity -- then prepares the
+ * operation and refuses a rule the doors cannot keep. A no-op writes nothing and records nothing.
  *
  * Built by the session and published on it as `session.sets`.
  */
 import { type GraphSnapshot } from "@graphty/graph-format";
 import type { EdgeId, EdgeMember, RuleTree, RunId, Scope, SetCreatedFrom, SetDefinitionInput, SetId } from "../../catalog/types";
+import type { Dispatcher } from "../project/Dispatcher";
 import type { SessionAttributes } from "../types";
 import { type Materialiser } from "./algebra";
 import { type DependencySources } from "./dependencies";
@@ -20,6 +23,11 @@ import { SetsStore } from "./store";
 import type { SetsApi, SetUser } from "./types";
 /** What the doors read from the rest of the session. */
 interface SetsDependencies {
+    /**
+     * The dispatcher whose `sets` slice holds the records and whose history records every write.
+     * A session hands in its own; absent, the sets keep a dispatcher of their own.
+     */
+    readonly dispatcher?: Dispatcher;
     /**
      * A session edge's stable identity.
      * @param id - The session edge id.
@@ -103,7 +111,7 @@ export declare function setsStoreOf(api: SetsApi): SetsStore;
 /**
  * Build the synchronous doors over a store.
  * @param dependencies - Where session edge ids are looked up.
- * @param store - The slice; a fresh one when absent.
+ * @param store - The kept sets; over the dispatcher handed in, or one of their own, when absent.
  * @returns The doors.
  */
 export declare function createSetsApi(dependencies: SetsDependencies, store?: SetsStore): SetsApi;