@graphty/graphty-element 2.6.2 → 3.0.1

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

@@ -0,0 +1,113 @@
+/**
+ * @file The kept-set ops: `set.create`, `set.rename`, `set.redefine`, `set.members`, `set.remove`
+ * and `set.restore`. Each is one undoable step on the `sets` slice, keyed `sets/<id>`, on the
+ * immediate lane, so the slice is written before the dispatch returns.
+ *
+ * The bodies are the pure prepare functions of `session/sets/prepare.ts`, reached through the
+ * session's set service, which also refuses a rule the doors cannot keep (a cycle, the live
+ * selection). A prepare that finds nothing to change writes nothing, so no step is recorded.
+ *
+ * `set.create` as a consumer sends it carries a definition and a name only. The element's own
+ * doors mint the id and the order before they dispatch, and say what the set was created from,
+ * so the recorded command carries all three; a redo replays the recorded patch and never mints.
+ * The register of issued ids, the order high-water mark, the tombstones and the edge seeds sit
+ * beside the slice and are never rewound (design/sets/undo-integration.md section 1).
+ *
+ * See design/undo/undo-design.md section 11.3.
+ */
+import type { SetCreatedFrom, SetDefinitionInput, SetId } from "../../catalog/types";
+import type { UndoableDefinition } from "../project/Dispatcher";
+import type { ElementSet, SetMemberDelta } from "../sets/types";
+/** `set.create`: keep a definition as a new set. */
+interface SetCreateCommand {
+    readonly op: "set.create";
+    /** What the set holds: a fixed list, a rule or a path. Edges may be named by session id. */
+    readonly definition: SetDefinitionInput;
+    /** Its name; "Set N" (the smallest free N) when absent. */
+    readonly name?: string;
+}
+/**
+ * `set.create` as the element's own doors dispatch it: the id and the order already minted, and
+ * what the set was created from. A consumer may not send these (design/sets 15.3, decision 2).
+ */
+export interface MintedSetCreateCommand extends SetCreateCommand {
+    readonly id: SetId;
+    readonly order: number;
+    readonly createdFrom: SetCreatedFrom;
+}
+/** `set.rename`: give a set another name. */
+interface SetRenameCommand {
+    readonly op: "set.rename";
+    readonly id: SetId;
+    readonly name: string;
+}
+/** `set.redefine`: change what a set holds, keeping its id, name and order. */
+interface SetRedefineCommand {
+    readonly op: "set.redefine";
+    readonly id: SetId;
+    readonly definition: SetDefinitionInput;
+}
+/** `set.members`: add members to a fixed set, or take them out. */
+interface SetMembersCommand {
+    readonly op: "set.members";
+    readonly id: SetId;
+    readonly add?: SetMemberDelta;
+    readonly remove?: SetMemberDelta;
+}
+/** `set.remove`: forget a set. What names it becomes detached rather than silently empty. */
+interface SetRemoveCommand {
+    readonly op: "set.remove";
+    readonly id: SetId;
+}
+/** `set.restore`: bring a removed set back, with the record it had when it was removed. */
+interface SetRestoreCommand {
+    readonly op: "set.restore";
+    readonly id: SetId;
+}
+/** Every kept-set op. */
+export type SetCommand = SetCreateCommand | SetRenameCommand | SetRedefineCommand | SetMembersCommand | SetRemoveCommand | SetRestoreCommand;
+/**
+ * The session's sets, as the set ops reach them: each call checks one command against the sets
+ * held now and returns what to write, throwing a refusal before anything is written. Built by
+ * `createSetsApi`.
+ */
+export interface SetService {
+    /**
+     * @param command - The create; minted by a door, or a consumer's, which is minted here.
+     * @returns The record to write.
+     */
+    create(command: SetCreateCommand | MintedSetCreateCommand): ElementSet;
+    /**
+     * @param command - The rename.
+     * @returns The record to write, or null when the name is the one it has.
+     */
+    rename(command: SetRenameCommand): ElementSet | null;
+    /**
+     * @param command - The redefinition.
+     * @returns The record to write, or null when the definition is canonically the same.
+     */
+    redefine(command: SetRedefineCommand): ElementSet | null;
+    /**
+     * @param command - The member edit.
+     * @returns The record to write, or null when nothing would change.
+     */
+    members(command: SetMembersCommand): ElementSet | null;
+    /**
+     * @param command - The removal.
+     * @returns The id to delete.
+     */
+    remove(command: SetRemoveCommand): SetId;
+    /**
+     * @param command - The restore.
+     * @returns The record to put back.
+     */
+    restore(command: SetRestoreCommand): ElementSet;
+    /**
+     * Keep a record's id in the issued-id register: called once the step that wrote it is recorded.
+     * @param id - The id.
+     */
+    issue(id: SetId): void;
+}
+/** The kept-set ops' definitions. */
+export declare const SET_DEFINITIONS: readonly [UndoableDefinition<SetCreateCommand>, UndoableDefinition<SetRenameCommand>, UndoableDefinition<SetRedefineCommand>, UndoableDefinition<SetMembersCommand>, UndoableDefinition<SetRemoveCommand>, UndoableDefinition<SetRestoreCommand>];
+export {};

package/dist/src/session/commands/style.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @file The style ops: `style.patch`, `style.encode` and `style.template`. Every edit to the
+ * style stack is one of them, and each is one undoable step.
+ *
+ * All three run on the immediate lane: the new stack is written when the command is dispatched,
+ * so `styles.list()` shows it as soon as the verb returns, and the repaint follows on the
+ * derivation lane. The stack is one frozen array of compiled layers (the `styles` slice), so a
+ * step keeps the stack before and after by reference, and undo puts the identical, already
+ * compiled layers back. See design/undo/undo-design.md sections 3.4, 5.2 and 11.3.
+ *
+ * What an edit does to the stack is worked out by the session's style compiler (the
+ * {@link StyleService} its styles API registers), because compiling a layer needs the session's
+ * columns and scales. This module says how each op behaves under undo.
+ */
+import type { Channel, LayerId, LayerSpec, RunId, StyleDocument } from "../../catalog/types";
+import type { UndoableDefinition } from "../project/Dispatcher";
+import type { Draft } from "../project/draft";
+import type { EncodingSpec } from "../styles/EncodingSpec";
+import type { ExplainTarget } from "../styles/explain";
+import type { LayerPosition } from "../styles/Layer";
+import type { HighlightSpec } from "../styles/StylesApi";
+/** `style.patch`: one change to the stack, said the way the styles verb that made it says it. */
+export type StylePatchCommand = {
+    readonly op: "style.patch";
+    readonly action: "add";
+    readonly spec: LayerSpec;
+    /** Which neighbour to sit next to; the top of the stack when absent. */
+    readonly at?: LayerPosition;
+} | {
+    readonly op: "style.patch";
+    readonly action: "update";
+    readonly id: LayerId;
+    /** Applied over the layer's specification one key deep; `undefined` clears a key. */
+    readonly patch: Partial<LayerSpec>;
+} | {
+    readonly op: "style.patch";
+    readonly action: "remove";
+    readonly id: LayerId;
+} | {
+    readonly op: "style.patch";
+    readonly action: "move";
+    readonly id: LayerId;
+    /** The layer to sit immediately below, or null for the top of the stack. */
+    readonly before: LayerId | null;
+} | {
+    readonly op: "style.patch";
+    readonly action: "removeBySource";
+    /** The layers the sweep matched when it was dispatched. */
+    readonly ids: readonly LayerId[];
+} | {
+    readonly op: "style.patch";
+    readonly action: "highlight";
+    readonly spec: Omit<HighlightSpec, "run"> & {
+        readonly run: RunId;
+    };
+} | {
+    readonly op: "style.patch";
+    readonly action: "resolveToStatic";
+    readonly id: LayerId;
+    readonly channel: Channel;
+    readonly at?: ExplainTarget;
+};
+/** `style.encode`: paint a run's measurement onto a channel. */
+export interface StyleEncodeCommand {
+    readonly op: "style.encode";
+    readonly spec: Omit<EncodingSpec, "run"> & {
+        readonly run: RunId;
+    };
+}
+/** `style.template`: add the layers of a style document. */
+interface StyleTemplateCommand {
+    readonly op: "style.template";
+    readonly document: StyleDocument;
+    /** Recorded as the template on every layer that names no source of its own. */
+    readonly templateId?: string;
+}
+/** Every style op. */
+export type StyleCommand = StylePatchCommand | StyleEncodeCommand | StyleTemplateCommand;
+/** The session's style compiler, as the style ops reach it. */
+export interface StyleService {
+    /**
+     * Work out the stack a command produces and write it through the draft. Throws a
+     * `GraphtyError` to refuse, before anything is written.
+     * @param command - The command.
+     * @param draft - The draft of the command's step.
+     * @returns What the verb resolves with.
+     */
+    execute(command: StyleCommand, draft: Draft): unknown;
+}
+/** The style ops' definitions. */
+export declare const STYLE_DEFINITIONS: readonly [UndoableDefinition<StylePatchCommand>, UndoableDefinition<StyleEncodeCommand>, UndoableDefinition<StyleTemplateCommand>];
+export {};

package/dist/src/session/commands/view.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @file The saved-view ops: `view.save` keeps camera states under names, `view.remove` forgets
+ * them, and `view.camera` moves the camera.
+ *
+ * Saved views are the `views` slice of project state, so saving and removing them are undoable
+ * steps on the immediate lane. Where the camera is looking is view state, not saved in a project
+ * file, so `view.camera` is exempt: it changes no slice, and a renderer carries it out. See
+ * design/undo/undo-design.md sections 3.1, 3.2, 10.5 and 11.4.
+ */
+import type { CameraState, Vec3 } from "../../camera/types";
+import type { ExemptDefinition, UndoableDefinition } from "../project/Dispatcher";
+/** One view to save: a name and the camera state it holds. */
+interface SavedView {
+    readonly name: string;
+    readonly camera: CameraState;
+}
+/** `view.save`: keep camera states under names, replacing any view already under one. */
+interface ViewSaveCommand {
+    readonly op: "view.save";
+    readonly views: readonly SavedView[];
+}
+/** `view.remove`: forget saved views. */
+interface ViewRemoveCommand {
+    readonly op: "view.remove";
+    readonly names: readonly string[];
+}
+/** `view.camera`: move the camera to a named view, or to a position and target. */
+interface ViewCameraCommand {
+    readonly op: "view.camera";
+    /** A camera view or a saved view, by name. Wins over `position` and `target`. */
+    readonly preset?: string;
+    readonly position?: Vec3;
+    readonly target?: Vec3;
+    /** Animate the move instead of jumping. */
+    readonly animate?: boolean;
+}
+/** Every view op. */
+export type ViewCommand = ViewSaveCommand | ViewRemoveCommand | ViewCameraCommand;
+/** The renderer's camera, as `view.camera` reaches it. */
+export interface CameraService {
+    /**
+     * Move the camera.
+     * @param command - Where to.
+     * @returns Settles once the camera has arrived.
+     */
+    move(command: ViewCameraCommand): Promise<void>;
+}
+/**
+ * Refuse a view name a camera view already answers to, or no name at all.
+ * @param name - The name being claimed.
+ * @throws A `GraphtyError` with `E_PROTECTED` for a camera view's name, `E_BAD_COMMAND` for an
+ *     empty one.
+ */
+export declare function assertViewName(name: string): void;
+/** The view ops' definitions. */
+export declare const VIEW_DEFINITIONS: readonly [UndoableDefinition<ViewSaveCommand>, UndoableDefinition<ViewRemoveCommand>, ExemptDefinition<ViewCameraCommand>];
+export {};

package/dist/src/session/commands/visibility.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @file The visibility ops: `visibility.set` (the filter), `visibility.window` (the time window)
+ * and `visibility.context` (whether hidden nodes are drawn faintly). Each is one undoable step.
+ *
+ * All three run on the immediate lane: the value is written to the `visibility` slice when the
+ * command is dispatched, and the masks are evaluated on the derivation lane against whatever the
+ * slice holds when the pass runs, so a filter superseded before then is never evaluated. The
+ * masks are not state; they are derived from these three values and the graph. See
+ * design/undo/undo-design.md sections 3.4, 9.2 and 11.3.
+ */
+import type { UndoableDefinition } from "../project/Dispatcher";
+import { type RuleTree, type TimeWindow } from "../visibility/filter";
+/** `visibility.set`: apply a filter, or clear it with null. */
+interface VisibilitySetCommand {
+    readonly op: "visibility.set";
+    readonly filter: RuleTree | null;
+}
+/** `visibility.window`: apply a time window, or clear it with null. */
+interface VisibilityWindowCommand {
+    readonly op: "visibility.window";
+    readonly window: TimeWindow | null;
+}
+/** `visibility.context`: draw hidden nodes faintly, or not at all. */
+interface VisibilityContextCommand {
+    readonly op: "visibility.context";
+    readonly show: boolean;
+}
+/** Every visibility op. */
+export type VisibilityCommand = VisibilitySetCommand | VisibilityWindowCommand | VisibilityContextCommand;
+/** The session's visibility model, as the visibility ops reach it. */
+export interface VisibilityService {
+    /**
+     * Refuse a filter or a window the session could not evaluate, before anything is written.
+     * @param filter - The filter, or null.
+     * @param window - The window, or null.
+     */
+    check(filter: RuleTree | null, window: TimeWindow | null): void;
+}
+/** The visibility ops' definitions. */
+export declare const VISIBILITY_DEFINITIONS: readonly [UndoableDefinition<VisibilitySetCommand>, UndoableDefinition<VisibilityWindowCommand>, UndoableDefinition<VisibilityContextCommand>];
+export {};

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

@@ -7,10 +7,27 @@
  * replaced only when the graph actually changes. The first reader after a change pays; everyone
  * else in the same revision reads a field.
  */
+import "../data/index";
 import { type DerivedGraph, type GraphSnapshot, type NodeId } from "@graphty/graph-format";
 import type { AttributeDescriptor, EdgeId } from "../catalog/types";
+import type { GraphStore } from "../data/GraphStore";
 import type { ImportReport } from "../data/report";
-import type { EdgeRecord, GraphStatistics, NodeRecord, SessionDataApi, SessionDataConfig, SessionGraphStore, SessionRecordSource } from "./types";
+import { type DataImportCommand, type DataMutation, type DataService } from "./commands/data";
+import type { Dispatcher } from "./project/Dispatcher";
+import type { GraphSlice } from "./project/state";
+import type { DataSourceDescriptor, DataSourceInput, EdgeRecord, EdgeRecordInput, GraphStatistics, ImportOptions, NodeRecord, NodeRecordInput, RowUpdate, SessionAttributes, SessionDataApi, SessionDataConfig, SessionGraphStore, SessionRecordSource } from "./types";
+/** What the data surface writes through, and where it reads what the graph holds beside rows. */
+interface DataWrites {
+    /** Dispatch `data.apply`. */
+    dispatch(mutation: DataMutation): Promise<unknown>;
+    /**
+     * Where a `data.import` made now would go -- the session, or the transaction a routed verb
+     * runs in -- held for a verb that dispatches it after an await.
+     */
+    importer(): (command: DataImportCommand) => Promise<unknown>;
+    /** The `graph` slice now. */
+    slice(): GraphSlice;
+}
 /**
  * The session's view of the graph data.
  *
@@ -20,9 +37,13 @@ import type { EdgeRecord, GraphStatistics, NodeRecord, SessionDataApi, SessionDa
  * no longer exists.
  */
 export declare class SessionData implements SessionDataApi {
+    /** The store, read-only: its snapshot is a consumer's, and its coordinates cannot be written. */
     readonly store: SessionGraphStore;
+    /** The store itself, which the session's own readers read. */
+    private readonly graphStore;
     private readonly records;
     private readonly readConfig;
+    private readonly writes;
     private derived;
     private disposed;
     /**
@@ -32,11 +53,62 @@ export declare class SessionData implements SessionDataApi {
      *     element holds none
      * @param readConfig - reads the data configuration, live: the element replaces that object
      *     when a style template is applied, so it is read on demand rather than captured
+     * @param writes - the dispatcher to write through, and the slice beside the rows
+     */
+    constructor(store: SessionGraphStore, records: SessionRecordSource | null, readConfig: () => SessionDataConfig, writes: DataWrites);
+    /**
+     * Add node records, as one undoable step.
+     * @param records - the records; each id is read through `data.knownFields.nodeIdPath`
+     * @returns settles once they are in the graph and drawn
+     */
+    addNodes(records: readonly NodeRecordInput[]): Promise<void>;
+    /**
+     * Add edge records, as one undoable step.
+     * @param records - the records; endpoints are read through the configured edge id paths
+     * @returns settles once they are in the graph and drawn
+     */
+    addEdges(records: readonly EdgeRecordInput[]): Promise<void>;
+    /**
+     * Change attributes of existing nodes, as one undoable step.
+     * @param rows - the new values per node
+     * @returns settles once the change is drawn
+     */
+    updateNodes(rows: readonly RowUpdate<NodeId>[]): Promise<void>;
+    /**
+     * Change attributes of existing edges, as one undoable step.
+     * @param rows - the new values per edge id
+     * @returns settles once the change is drawn
+     */
+    updateEdges(rows: readonly RowUpdate<EdgeId>[]): Promise<void>;
+    /**
+     * Remove nodes, and every edge attached to one, as one undoable step.
+     * @param ids - the node ids; one the graph does not hold is skipped
+     * @returns settles once they are gone from the graph and the picture
+     */
+    removeNodes(ids: readonly NodeId[]): Promise<void>;
+    /**
+     * Remove edges, as one undoable step.
+     * @param ids - the element-assigned edge ids; one the graph does not hold is skipped
+     * @returns settles once they are gone from the graph and the picture
+     */
+    removeEdges(ids: readonly EdgeId[]): Promise<void>;
+    /**
+     * Remove every node, edge, record and graph-level value, as one undoable step.
+     * @returns settles once the graph and the picture are empty
+     */
+    clear(): Promise<void>;
+    /**
+     * Load a file, a URL or inline text through a registered data source, as one undoable step.
+     * @param source - The data source's name and its options.
+     * @param options - Whether to replace the graph (the default) or add to it.
+     * @returns Settles once the last chunk is in the graph; rejects, recording nothing, when the
+     *     load fails.
      */
-    constructor(store: SessionGraphStore, records: SessionRecordSource | null, readConfig: () => SessionDataConfig);
+    import(source: DataSourceInput, options?: ImportOptions): Promise<void>;
     /**
-     * The current snapshot, freezing first when records have arrived since the last freeze.
-     * @returns the immutable snapshot
+     * The current snapshot, freezing first when records have arrived since the last freeze, with
+     * copies of its coordinate and pin columns.
+     * @returns the sealed snapshot
      * @throws A `GraphtyError` with `E_DISPOSED` when the session has been disposed.
      */
     snapshot(): GraphSnapshot;
@@ -47,6 +119,11 @@ export declare class SessionData implements SessionDataApi {
      * @throws A `GraphtyError` with `E_DISPOSED` when the session has been disposed.
      */
     undirected(snapshot?: GraphSnapshot): DerivedGraph;
+    /**
+     * The store's own snapshot, for the readers here that never hand it out.
+     * @returns the resident snapshot
+     */
+    private current;
     /**
      * One node, by id.
      * @param id - the node id, compared without coercion
@@ -61,6 +138,24 @@ export declare class SessionData implements SessionDataApi {
      * @throws A `GraphtyError` with `E_DISPOSED` when the session has been disposed.
      */
     edge(id: EdgeId): EdgeRecord | undefined;
+    /**
+     * Every node, in the graph's order.
+     * @returns the records, deep-frozen
+     * @throws A `GraphtyError` with `E_DISPOSED` when the session has been disposed.
+     */
+    nodes(): readonly NodeRecord[];
+    /**
+     * Every edge, in the graph's order.
+     * @returns the records, deep-frozen
+     * @throws A `GraphtyError` with `E_DISPOSED` when the session has been disposed.
+     */
+    edges(): readonly EdgeRecord[];
+    /**
+     * Where the graph was loaded from, as the `graph` slice keeps it, so undo and redo move it.
+     * @returns the source, or null when no import loaded the graph
+     * @throws A `GraphtyError` with `E_DISPOSED` when the session has been disposed.
+     */
+    source(): DataSourceDescriptor | null;
     /**
      * What the last load did.
      * @returns the report, or null when nothing has been loaded into this graph
@@ -110,3 +205,35 @@ export declare class SessionData implements SessionDataApi {
      */
     private requireLive;
 }
+/**
+ * Where a session reads the attributes a record carries: the `graph` slice, which every write
+ * through the graph primitives fills, and then a host's own source for rows it wrote some other way.
+ *
+ * An edge's record is handed back without the keys the last import read its endpoints from, when
+ * those are plain keys, so a consumer deriving columns from the keys does not show `src` beside the
+ * canonical `source`.
+ * @param slice - Reads the `graph` slice.
+ * @param snapshot - Reads the current snapshot, to name an edge row by its id.
+ * @param lastImport - Reads the last import report.
+ * @param fallback - The host's own source, if it has one.
+ * @returns The source.
+ */
+export declare function sliceRecords(slice: () => GraphSlice, snapshot: () => GraphSnapshot, lastImport: () => ImportReport | null, fallback: SessionRecordSource | null): SessionRecordSource;
+/**
+ * The graph's records in row order: what the element's `nodeData` and `edgeData` read. A node
+ * record whose id the graph could not store, and so has no row, follows the rows.
+ * @param slice - The `graph` slice.
+ * @param snapshot - The snapshot of the same graph.
+ * @param target - Nodes or edges.
+ * @returns The records, frozen.
+ */
+export declare function recordsInRowOrder(slice: GraphSlice, snapshot: GraphSnapshot, target: "node" | "edge"): readonly SessionAttributes[];
+/**
+ * The data service of a session that owns its store: ingest over that store, with nothing to draw.
+ * @param store - The store.
+ * @param dispatcher - The session's dispatcher.
+ * @param readConfig - Reads the data configuration.
+ * @returns The service.
+ */
+export declare function headlessDataService(store: GraphStore, dispatcher: Dispatcher, readConfig: () => SessionDataConfig): DataService;
+export {};

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

@@ -16,5 +16,5 @@ export type { DefaultableLimits } from "./limits";
 export { DEFAULT_LIMITS } from "./limits";
 export type { AlgorithmRunCommand, Plan, PlanBlock, PlanEffect, SessionCommand } from "./planning";
 export { isAlgorithmRunCommand } from "./planning";
-export type { ComponentStatistics, CreateGraphSessionOptions, EdgeRecord, ElementSession, GraphSession, GraphStatistics, NodeRecord, SessionAttributes, SessionCatalogApi, SessionConfig, SessionDataApi, SessionDataConfig, SessionEventMap, SessionGraphStore, SessionRecordSource, SessionRunsOptions, SessionStatus, StyleProblem, } from "./types";
+export type { CommandOutcome, CommandOutcomeMap, ComponentStatistics, CreateGraphSessionOptions, DataSourceDescriptor, DataSourceInput, EdgeRecord, EdgeRecordInput, ElementSession, GraphSession, GraphStatistics, HistoryCause, HistoryOutcome, HistoryStep, HistoryStepId, ImportOptions, NodeRecord, NodeRecordInput, PendingId, PendingStep, PositionEntry, ProjectConfig, ProjectConfigPatch, ProjectSlice, ReadonlyElementPositions, RowUpdate, SessionAttributes, SessionCatalogApi, SessionConfig, SessionDataApi, SessionDataConfig, SessionEventMap, SessionGraphStore, SessionHistory, SessionLayout, SessionPositions, SessionRunsOptions, SessionStatus, SessionViews, StyleProblem, TransactionOptions, TransactionScope, } from "./types";
 export { COMPONENT_SIZE_CAP } from "./types";

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

@@ -17,18 +17,26 @@
  */
 import type { AlgorithmDescriptor, AlgorithmKey, FieldDescriptor, RunId, Scope, SetId } from "../catalog/types";
 import type { GraphtyErrorCode } from "../errors";
+import type { AlgoLegacyCommand, AlgoRemoveCommand } from "./commands/algo";
+import type { ConfigSetCommand } from "./commands/config";
+import type { DataCommand } from "./commands/data";
+import type { BatchCommand } from "./commands/index";
+import type { LayoutCommand } from "./commands/layout";
+import type { PositionsCommand } from "./commands/positions";
+import type { SetCommand } from "./commands/sets";
+import type { StyleCommand } from "./commands/style";
+import type { ViewCommand } from "./commands/view";
+import type { VisibilityCommand } from "./commands/visibility";
 import { type CostEstimate, type CostGateLimits, type CostMeasurement, type MachineCalibration, type ScopeCandidate } from "./cost";
 import type { Caveats, ResolvedScope } from "./runs";
 import type { GraphStatistics } from "./types";
 /**
  * Start one algorithm, as data.
  *
- * Every verb on a session is meant to be expressible as one of these, so that "do this" and
- * "record that you did this" are the same artifact -- what a recipe replays, what a journal
- * stores, what an agent's tool call carries. One verb is expressible today, and the union below
- * has one member rather than a placeholder: a command that does not exist is discovered by
- * autocomplete finding nothing, which costs a consumer one keystroke, where a stub that compiles
- * and then throws costs them an afternoon.
+ * Every verb on a session is expressible as a command, so that "do this" and "record that you
+ * did this" are the same artifact -- what `session.execute` runs, what a transaction groups into
+ * one undoable step, and what an agent's tool call carries. This is the one that starts a run;
+ * {@link SessionCommand} is the union of all of them.
  */
 export interface AlgorithmRunCommand {
     /** Which verb this is. */
@@ -47,9 +55,18 @@ export interface AlgorithmRunCommand {
     readonly exact?: boolean;
     /** The id to give the run. Required for anything that will be saved. */
     readonly as?: RunId;
+    /**
+     * Also apply the layers the run suggests, on top of the stack, in the same step as the run:
+     * one undo takes the run and those layers away together.
+     */
+    readonly applySuggestedStyles?: boolean;
 }
-/** Everything a session can be asked to do, as data. */
-export type SessionCommand = AlgorithmRunCommand;
+/**
+ * Everything a session can be asked to do, as data: the union of every op in the vocabulary
+ * (`COMMANDS` in `@graphty/graphty-element/commands`). It widens as ops are added, so a `switch`
+ * over `op` should keep a default branch.
+ */
+export type SessionCommand = AlgorithmRunCommand | AlgoLegacyCommand | AlgoRemoveCommand | DataCommand | StyleCommand | VisibilityCommand | SetCommand | ViewCommand | ConfigSetCommand | PositionsCommand | LayoutCommand | BatchCommand;
 /**
  * Tell whether a value is the command that starts an algorithm.
  * @param value - The value to test.