@graphty/graphty-element 2.6.1 → 3.0.0

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

@@ -0,0 +1,169 @@
+/**
+ * @file The run ops: `algo.run`, `algo.legacy` and `algo.remove`.
+ *
+ * `algo.run` takes a slot on the queue under `algorithm-run`, computes, and then, in one
+ * synchronous commit tail, writes the finished run into the `runs` slice together with the style
+ * layers it paints: its first-completion layers, and the suggested layers it was asked to apply.
+ * So a run, its result, its layers and its legend are one step, and undoing it keeps the result
+ * in history instead of recomputing it. A run cancelled before it commits, whether by undo, by
+ * the queue or by its own `cancel()`, writes nothing.
+ *
+ * `algo.remove` takes a run out of the `runs` slice and removes the layers bound to it, in one
+ * draft, so one undo brings both back.
+ *
+ * `algo.legacy` runs a plugin algorithm that declares no catalogue descriptor, and so has no run:
+ * it writes onto node and edge records and `graphResults` as it goes, and may call the graph's
+ * own doors. It is one step all the same. The plugin is handed a facade of the graph whose doors
+ * dispatch into the command's own group ({@link legacyFacade}), and while it runs the records it
+ * reads are copy-on-write views ({@link LegacyWrites}) whose written paths become one attribute
+ * write when it finishes. See design/undo/undo-design.md sections 4.5 and 4.9.
+ *
+ * What a run computes, and which handle a consumer holds for it, is the runs API's work: it
+ * registers the {@link RunService} these ops call. See design/undo/undo-design.md sections 4.7,
+ * 4.8 and 6.3.
+ */
+import type { RunId } from "../../catalog/types";
+import type { AlgorithmRunCommand } from "../planning";
+import type { Dispatcher, DispatchFunction, UndoableContext, UndoableDefinition } from "../project/Dispatcher";
+import { type Draft } from "../project/draft";
+import type { RowUpdate } from "../types";
+/** `algo.remove`: take a finished run, and every layer bound to it, out of the project. */
+export interface AlgoRemoveCommand {
+    readonly op: "algo.remove";
+    /** The run. */
+    readonly runId: RunId;
+}
+/**
+ * `algo.legacy`: run a plugin algorithm that declares no catalogue descriptor, addressed the 1.10
+ * way, as one step with everything it writes.
+ */
+export interface AlgoLegacyCommand {
+    readonly op: "algo.legacy";
+    /** The registry namespace. */
+    readonly namespace: string;
+    /** The registry type. */
+    readonly type: string;
+    /** What the plugin is constructed with. */
+    readonly options?: Readonly<Record<string, unknown>>;
+    /** Also apply the layers its finished runs suggest, in the same step. */
+    readonly applySuggestedStyles?: boolean;
+}
+/** How a renderer carries out `algo.legacy`: it constructs the plugin, which needs a `Graph`. */
+export interface LegacyService {
+    /**
+     * Construct the plugin with a facade of the graph, run it, and write what it wrote.
+     * @param command - The command.
+     * @param ctx - The command's context; `ctx.inline` is what the facade dispatches through.
+     * @returns Settles once everything it wrote is in the command's draft.
+     */
+    run(command: AlgoLegacyCommand, ctx: UndoableContext): Promise<void>;
+}
+/** How a session carries out the run ops; registered by its runs API. */
+export interface RunService {
+    /**
+     * Compute a run, then write it and the layers it paints through the command's draft.
+     * @param command - The run.
+     * @param ctx - The command's context: its draft, its signal and its slot.
+     * @returns Settles once the run is written; rejects when it failed or was cancelled first.
+     */
+    run(command: AlgorithmRunCommand, ctx: UndoableContext): Promise<unknown>;
+    /**
+     * Remove a run and the layers bound to it through `draft`, and stop it if it is still going.
+     * @param command - The removal.
+     * @param draft - The command's draft.
+     * @returns What went with it.
+     */
+    remove(command: AlgoRemoveCommand, draft: Draft): unknown;
+}
+/** The run ops' definitions. */
+export declare const ALGO_DEFINITIONS: readonly [UndoableDefinition<AlgorithmRunCommand>, UndoableDefinition<AlgoLegacyCommand>, UndoableDefinition<AlgoRemoveCommand>];
+/** What a record belongs to: a node, an edge, or the graph's own values. */
+type WriteTarget = "node" | "edge" | "graph";
+/**
+ * The copy-on-write records of one `algo.legacy` command: reads pass through to the record the
+ * graph holds, and the first write under a top-level key copies that key's subtree with
+ * `structuredClone` and writes the copy. The record itself is never touched, so a write that is
+ * never committed (the command failed or was undone while the plugin ran) changes nothing.
+ *
+ * One view per record, cached for the command's duration, so a record read twice allocates once.
+ */
+export declare class LegacyWrites {
+    #private;
+    readonly owner: object;
+    readonly owns: (element: object) => boolean;
+    /**
+     * Open no scope yet: {@link openLegacyScope} does.
+     * @param owner - What the scope is looked up by: the session's dispatcher.
+     * @param owns - Whether a node or edge render object is one of this graph's.
+     */
+    constructor(owner: object, owns: (element: object) => boolean);
+    /**
+     * The copy-on-write view of one record.
+     * @param target - Node, edge, or the graph's values.
+     * @param id - The node or edge id; ignored for the graph.
+     * @param record - The record the graph holds.
+     * @returns The view.
+     */
+    view(target: WriteTarget, id: string | number, record: object): object;
+    /**
+     * The copy-on-write view of the graph's values, the same object each time.
+     * @param values - The graph's values as the graph holds them.
+     * @returns The view, by name.
+     */
+    graph(values: ReadonlyMap<string, unknown>): Record<string, unknown>;
+    /**
+     * Whether the command has ended.
+     * @returns True once {@link LegacyWrites.close} ran.
+     */
+    get closed(): boolean;
+    /**
+     * End the command: a view kept past it throws on the next write, and a copied subtree handed
+     * out while it ran is frozen, so a write to that throws too.
+     */
+    close(): void;
+    /**
+     * What was written, as the rows and graph values a draft takes.
+     * @returns The written top-level keys of each record, and of the graph's values.
+     */
+    writes(): {
+        readonly nodes: RowUpdate<string | number>[];
+        readonly edges: RowUpdate<string | number>[];
+        readonly graph: Readonly<Record<string, unknown>> | null;
+    };
+}
+/**
+ * The scope open for a dispatcher.
+ * @param owner - The dispatcher.
+ * @returns The scope, or undefined when no `algo.legacy` of its graph is running.
+ */
+export declare function legacyScopeOf(owner: Dispatcher | null): LegacyWrites | undefined;
+/** A prototype whose `data` getter is swapped while a scope is open. */
+interface DataPrototype {
+    readonly prototype: object;
+    readonly target: "node" | "edge";
+}
+/**
+ * Open a copy-on-write scope: until it is closed, reading `data` on a node or edge of this graph
+ * hands back a copy-on-write view. The getters are swapped on the prototypes, not branched on
+ * every read, and put back when the last scope closes.
+ * @param scope - The scope.
+ * @param prototypes - The render object prototypes whose `data` getter reads a record.
+ * @returns Closes it.
+ */
+export declare function openLegacyScope(scope: LegacyWrites, prototypes: readonly DataPrototype[]): () => void;
+/**
+ * A group-tagged facade of `root`: the same members, but every call made through it, and through
+ * every object it hands back, runs with the dispatcher routed to `inline`, so a door reached
+ * through it dispatches into the running command's own group instead of a step of its own. The
+ * routing lasts for the synchronous part of each call only, which is where every door dispatches,
+ * so a dispatch made anywhere else while the plugin runs is still a step of its own.
+ *
+ * Calls are made on the real objects, with any facade among the arguments unwrapped, so private
+ * fields and identity checks see the originals.
+ * @param root - The graph.
+ * @param dispatcher - Its session's dispatcher.
+ * @param inline - Dispatches into the running command's group.
+ * @returns The facade.
+ */
+export declare function legacyFacade<T extends object>(root: T, dispatcher: Dispatcher, inline: DispatchFunction): T;
+export {};

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

@@ -0,0 +1,45 @@
+/**
+ * @file `config.set`: change project settings, one undoable step per call.
+ *
+ * The project settings are the keys of the `config` slice, one key per leaf, named by its dotted
+ * path: every leaf of the zod `DataConfig` schema under `data.` (the id, label, weight and time
+ * paths, the repeated-edge policy, the position scale, the id coercion, the on-load algorithms and
+ * the direction), whether the on-load algorithms run, the background, the selection style, and
+ * three layout-behaviour keys. The `DataConfig` leaves are read from the schema when this module
+ * loads, so a field added there joins the slice without an edit here.
+ *
+ * The slice holds only what has been set, as the caller gave it; a key that is absent reads as
+ * its default. Setting a key to `undefined` removes it, which returns it to its default.
+ * Everything else a graph is configured with -- the camera distance, the view mode, the
+ * interaction and throughput preferences -- is not saved in a project file, is not a key here,
+ * and `config.set` refuses it. See design/undo/undo-design.md sections 3.1, 3.2 and 10.1.
+ */
+import { z } from "zod/v4";
+import type { UndoableDefinition } from "../project/Dispatcher";
+import type { ProjectConfig, ProjectConfigPatch, SessionDataConfig } from "../types";
+/** `config.set`: write project settings. */
+export interface ConfigSetCommand {
+    readonly op: "config.set";
+    readonly values: ProjectConfigPatch;
+}
+/** Which part of the project settings a key belongs to: the discriminant of `config.set`. */
+type ConfigGroup = "data" | "runAlgorithmsOnLoad" | "background" | "selectionStyle" | "layoutBehavior";
+/** One key of the `config` slice. */
+interface ConfigKey {
+    readonly group: ConfigGroup;
+    /** Validates a value set, and reads a stored value (or `undefined`) as the setting. */
+    readonly schema: z.ZodType;
+}
+/** Every key of the `config` slice, with its group and schema. */
+export declare const CONFIG_KEYS: ReadonlyMap<string, ConfigKey>;
+/**
+ * The project settings a slice holds, with every absent key at its default.
+ * @param slice - The `config` slice.
+ * @param base - The data configuration an absent `data.` key reads from: the element's defaults,
+ *     or what a headless session was built with.
+ * @returns The settings, frozen.
+ */
+export declare function readProjectConfig(slice: ReadonlyMap<string, unknown>, base: SessionDataConfig): ProjectConfig;
+/** The config op's definition. */
+export declare const CONFIG_DEFINITIONS: readonly [UndoableDefinition<ConfigSetCommand>];
+export {};

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

@@ -0,0 +1,178 @@
+/**
+ * @file The data ops, each one undoable step:
+ *
+ * - `data.apply`: one change to the graph's rows or records. The kinds that grow or patch the
+ *   graph, `add-nodes`, `add-edges`, `set-attributes` and `update-rows`, and the removals and
+ *   `clear`: `remove-nodes`, `remove-edges`, `clear`.
+ * - `data.import`: a load through a registered data source, replacing the graph or adding to it.
+ * - `data.expand`: the neighbourhood a double-click fetched, added as one step. The fetched
+ *   records are in the command, so redo never fetches again.
+ *
+ * Each reads its records through ingest (id and endpoint extraction, the repeated-edge policy,
+ * weights) and writes through the graph primitives in its draft, which record the resolved values,
+ * so undo and redo never pass through ingest, a data source or a fetcher again. See
+ * design/undo/undo-design.md sections 3.3, 3.4, 4.7 and 11.1.
+ *
+ * `data.apply` and `data.import` take their turn on the queue, so an add is ordered against the
+ * loads, layouts and runs dispatched before it, and one still waiting is pending work that undo
+ * cancels. A synchronous door starts its `data.apply` beside the queue instead. `data.import`
+ * holds the whole graph while it reads. `data.expand` runs on the immediate lane: the write is
+ * visible as soon as `dispatch` returns.
+ */
+import type { DuplicatePolicy } from "@graphty/graph-format";
+import type { EdgeId, NodeId } from "../../catalog/types";
+import type { UndoableContext, UndoableDefinition } from "../project/Dispatcher";
+import type { Draft } from "../project/draft";
+import type { NodeRecordInput, RowUpdate } from "../types";
+import type { BatchCommand } from "./index";
+/** A record to add; its id, or its endpoints, are read through the configured paths. */
+type RecordInput = NodeRecordInput;
+/** One change `data.apply` makes. */
+export type DataMutation = {
+    readonly kind: "add-nodes";
+    readonly records: readonly RecordInput[];
+    /** The id path for this call, overriding `data.knownFields.nodeIdPath`. */
+    readonly idPath?: string;
+} | {
+    readonly kind: "add-edges";
+    readonly records: readonly RecordInput[];
+    /** The source endpoint path for this call. */
+    readonly source?: string;
+    /** The target endpoint path for this call. */
+    readonly target?: string;
+    /** The repeated-edge policy for this call. */
+    readonly repeated?: DuplicatePolicy;
+} | {
+    /** The same values on many rows: "set type to hub on these nodes". */
+    readonly kind: "set-attributes";
+    readonly target: "node" | "edge";
+    readonly ids: readonly (NodeId | EdgeId)[];
+    readonly values: Readonly<Record<string, unknown>>;
+} | {
+    /** Values of its own for each row. */
+    readonly kind: "update-rows";
+    readonly target: "node" | "edge";
+    readonly rows: readonly RowUpdate<NodeId | EdgeId>[];
+} | {
+    /** Remove nodes, and every edge attached to one. */
+    readonly kind: "remove-nodes";
+    readonly ids: readonly NodeId[];
+} | {
+    /** Remove edges, by the element-assigned edge id. */
+    readonly kind: "remove-edges";
+    readonly ids: readonly EdgeId[];
+} | {
+    /** Remove every node, edge, record and graph-level value. */
+    readonly kind: "clear";
+};
+/** `data.apply`. */
+interface DataApplyCommand {
+    readonly op: "data.apply";
+    readonly mutation: DataMutation;
+}
+/**
+ * Where a load comes from: a registered data source's name and its options. The element's
+ * `dataSource` / `dataSourceConfig` pair may be half assigned, so either may be absent; a source
+ * missing either is recorded and nothing is loaded.
+ */
+export interface ImportSource {
+    readonly type?: string;
+    readonly config?: Readonly<Record<string, unknown>>;
+    /** What the reader calls the data; see `DataSourceInput.name`. */
+    readonly name?: string;
+    /** The file's size in bytes, when a file was read. */
+    readonly size?: number;
+}
+/** `data.import`. */
+export interface DataImportCommand {
+    readonly op: "data.import";
+    readonly source: ImportSource;
+    /** `"replace"` (the default) empties the graph first, in the same step; `"merge"` adds to it. */
+    readonly mode?: "replace" | "merge";
+    /** `"recommended"` also chooses a layout for what was loaded, in the same step. */
+    readonly layout?: "recommended" | "keep";
+    /** Declared at construction: while the baseline window is open it becomes the baseline. */
+    readonly setup?: boolean;
+    /**
+     * Imports with the same key coalesce while the first waits its turn: the element's two
+     * properties assigned one after the other are one load.
+     */
+    readonly coalesce?: string;
+}
+/** `data.expand`: what a double-click on `seed` fetched, captured so redo does not fetch again. */
+interface DataExpandCommand {
+    readonly op: "data.expand";
+    readonly seed: NodeId;
+    readonly nodes: readonly RecordInput[];
+    readonly edges: readonly RecordInput[];
+    /** The expression naming each edge's source, resolved once for the fetched edges. */
+    readonly source?: string;
+    /** The expression naming each edge's target. */
+    readonly target?: string;
+}
+/** Every data op. */
+export type DataCommand = DataApplyCommand | DataImportCommand | DataExpandCommand;
+/** How a session applies a data mutation: its ingest and its store. Set by whoever owns them. */
+export interface DataService {
+    /**
+     * Apply one mutation, writing through the graph primitives in `draft`.
+     * @param mutation - The mutation.
+     * @param draft - The command's draft.
+     * @param after - Starts work once the command's step is recorded, as its deferred members:
+     *     the on-load runs of a command that adds rows.
+     */
+    apply(mutation: DataMutation, draft: Draft, after?: UndoableContext["after"]): void;
+    /**
+     * Carry out one import, writing through the graph primitives in `draft`.
+     * @param command - The import.
+     * @param draft - The command's draft.
+     * @param signal - Fires when the import is cancelled; it stops before the next chunk.
+     * @param after - Starts work once the import's step is recorded, as its deferred members.
+     * @returns Settles once the last chunk is written.
+     */
+    import(command: DataImportCommand, draft: Draft, signal: AbortSignal, after?: UndoableContext["after"]): Promise<void>;
+    /**
+     * Set graph-level values through `draft`: what a plugin algorithm wrote to `graphResults`.
+     * A renderer's only; a headless session runs no plugin.
+     * @param values - The values by name.
+     * @param draft - The command's draft.
+     */
+    values?(values: Readonly<Record<string, unknown>>, draft: Draft): void;
+}
+/** The graph value naming where the graph was last loaded from. */
+export declare const SOURCE_VALUE = "source";
+/**
+ * A source as the graph keeps it: without the inline text or the file, which the loaded rows
+ * already hold and which history must not keep alive.
+ * @param source - The source.
+ * @returns The descriptor.
+ */
+export declare function describeSource(source: ImportSource): ImportSource;
+/** How new edges are read: the endpoint expressions and the repeated-edge policy. */
+interface EdgeReadOptions {
+    readonly source?: string;
+    readonly target?: string;
+    readonly repeated?: DuplicatePolicy;
+}
+/**
+ * The step replacing the graph's edges: remove the edges it holds, add the new ones.
+ * @param held - The ids of the edges it holds, read when the step is about to run.
+ * @param records - The edges it should hold afterwards.
+ * @param options - Endpoint expressions and the repeated-edge policy for the new edges.
+ * @param setup - Declared at construction.
+ * @returns The command.
+ */
+export declare function replaceEdgesCommand(held: readonly EdgeId[], records: readonly RecordInput[], options?: EdgeReadOptions, setup?: boolean): BatchCommand;
+/**
+ * The step replacing the graph's nodes: remove the nodes it holds that the new records do not
+ * name, with their edges, and add the new ones. A node named again keeps its row and its edges.
+ * @param held - The ids of the nodes it holds, read when the step is about to run.
+ * @param records - The nodes it should hold afterwards.
+ * @param idPath - Where a record's id is, `data.knownFields.nodeIdPath`.
+ * @param setup - Declared at construction.
+ * @returns The command.
+ */
+export declare function replaceNodesCommand(held: readonly NodeId[], records: readonly RecordInput[], idPath: string, setup?: boolean): BatchCommand;
+/** The data ops' definitions. */
+export declare const DATA_DEFINITIONS: readonly [UndoableDefinition<DataApplyCommand>, UndoableDefinition<DataImportCommand>, UndoableDefinition<DataExpandCommand>];
+export {};

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

@@ -0,0 +1,93 @@
+/**
+ * @file The door list: every public member of graphty-element that could change it, and what
+ * each one does about undo.
+ *
+ * A door is a public method, accessor or field. Each is classified as one of:
+ *
+ * - `readOnly`: it changes nothing;
+ * - `exempt`, with the reason: it changes something no project file saves (the camera, the
+ *   selection, work in flight, a machine preference);
+ * - `dispatches`: it dispatches the command in its row, and nothing else;
+ * - `partial`: it dispatches, but one call of it is not yet one step, until the issue it names
+ *   is fixed;
+ * - `knownGap`: it changes project state without the dispatcher, until the issue it names is
+ *   fixed. With an `op` it will dispatch that op; without one it is a public escape (a writable
+ *   field, a live array) that the issue narrows.
+ *
+ * The roots are the element, `Graph`, `Node`, `Edge`, the session and each of its parts, the
+ * `Run` handle, the style layer, every manager, and every type a public member of one of them
+ * hands back that has methods. `test/session/history/door-surface.test.ts` walks the declared
+ * types of the roots with the TypeScript compiler and fails on any public member this list does
+ * not classify, and on any handle type that is not a root, so nothing public can ship without a
+ * decision about undo. `test/session/history/doors.test.ts` (the session's rows) and
+ * `test/browser/doors.test.ts` (the renderer's rows) call every row that dispatches or will
+ * dispatch, with a spy on the dispatcher, and hold the rule: no `knownGap` or `partial` row may
+ * remain, and a `knownGap` door must dispatch nothing. A row of either kind names the GitHub
+ * issue that tracks it, so a gap that has to land for a while is still on record.
+ *
+ * No entry point exports this module.
+ */
+/** How the doors tests call a door. */
+export type DoorCall = {
+    readonly kind: "call";
+    /** The arguments, or a function building them where they cannot be plain data. */
+    readonly args: readonly unknown[] | (() => readonly unknown[]);
+    /**
+     * For a door that does nothing in the doors test's default state: sets up the state it
+     * acts on before the spy is attached, and returns what puts it back afterwards.
+     */
+    readonly around?: (target: object) => Promise<() => Promise<unknown>>;
+} | {
+    readonly kind: "set";
+    readonly value: unknown;
+};
+/** What one door does about undo. */
+export type Door = {
+    readonly kind: "readOnly";
+} | {
+    readonly kind: "exempt";
+    readonly reason: string;
+} | {
+    readonly kind: "dispatches";
+    readonly op: string;
+    readonly call: DoorCall;
+    /** The commands the call must dispatch, in order. */
+    readonly expect: readonly unknown[];
+} | {
+    readonly kind: "partial";
+    /** The GitHub issue tracking it. */
+    readonly issue: number;
+    readonly reason: string;
+    readonly op: string;
+    readonly call: DoorCall;
+    readonly expect: readonly unknown[];
+} | {
+    readonly kind: "knownGap";
+    /** The GitHub issue tracking it. */
+    readonly issue: number;
+    /** The op it will dispatch once ported; absent for an escape the issue narrows. */
+    readonly op?: string;
+    /** How to call it; present exactly when `op` is. */
+    readonly call?: DoorCall;
+};
+/** A type whose public members are doors. */
+export interface DoorRoot {
+    /** The declared name of the class or interface. */
+    readonly name: string;
+    /** The file declaring it, relative to the package root. */
+    readonly file: string;
+    /** Which doors test calls its rows: the Node one on a session, or the browser one on a `Graph`. */
+    readonly half: "session" | "renderer";
+    /** One row per public member. */
+    readonly doors?: Readonly<Record<string, Door>>;
+    /** For a type every member of which has the same answer: that answer. */
+    readonly whole?: Door;
+}
+/** Every root, and the door of every public member. */
+export declare const DOOR_ROOTS: readonly DoorRoot[];
+/**
+ * The ops a gesture the element handles itself dispatches, with no public member of its own: the
+ * gesture is the door. Each names where it is handled; the browser test of that gesture checks
+ * that it dispatches the op.
+ */
+export declare const GESTURE_DOORS: Readonly<Record<string, string>>;

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

@@ -0,0 +1,20 @@
+/**
+ * @file The definition of every op in the vocabulary: how it behaves under undo, which keys it
+ * writes, which lane it runs on, and what it does. The dispatcher is built from this list, and
+ * `COMMANDS` in `commands.ts` publishes the undo half of it; the vocabulary test checks that the
+ * two agree op for op. See design/undo/undo-design.md sections 4.1 and 10.5.
+ */
+import type { SessionCommand } from "../planning";
+import type { CommandDefinition } from "../project/Dispatcher";
+/** `batch`: commands that are one step, as data. A serialisable transaction. */
+export interface BatchCommand {
+    readonly op: "batch";
+    /** The commands, dispatched in order; each takes its own lane. */
+    readonly steps: readonly SessionCommand[];
+    /** What the step is called; the first member's name by default. */
+    readonly label?: string;
+    /** Declared at construction: while the baseline window is open it becomes the baseline. */
+    readonly setup?: boolean;
+}
+/** Every op's definition, one per op. */
+export declare const DEFINITIONS: readonly CommandDefinition<SessionCommand>[];

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

@@ -0,0 +1,104 @@
+/**
+ * @file The layout ops: which layout draws the graph and in how many dimensions, and the two
+ * exempt controls beside them.
+ *
+ * - `layout.set`: choose the layout (a catalogue id, the engine that draws it, its options, and
+ *   optionally what it runs over). One undoable step.
+ * - `layout.scope`: change what layouts run over, keeping the layout. One undoable step, written
+ *   at once so a layout still waiting for its turn carries it; the `layout` hook restarts the
+ *   running layout over it. Never refused for a scope that resolves to nothing.
+ * - `view.dimension`: draw in 2D or 3D. One undoable step. The dimension lives in the `layout`
+ *   slice and nowhere else: the merged `Styles.config` computes `graph.viewMode` and `graph.twoD`
+ *   from it, and the renderer's `layout` hook writes `scene.metadata.twoD` from it.
+ * - `layout.transport`: play or pause the layout. Exempt: coordinates while a layout moves are
+ *   in-flight computation, and where it comes to rest is sealed into the top step.
+ * - `view.immersive`: enter or leave VR or AR. Exempt: a device session, not the document.
+ *
+ * `layout.set` and `view.dimension` are slot-holding writers (design/undo/undo-design.md section
+ * 4.7): they take the arrangement they began from, write the slice, then have the renderer build
+ * the engine and spend its pre-steps inside their slot. Cancelled or made obsolete while the
+ * pre-steps run, they publish nothing, and the rollback puts the previous layout and the previous
+ * coordinates back. See design sections 3.2, 4.7, 6.4 and 11.4.
+ */
+import type { LayoutId, Scope } from "../../catalog/types";
+import type { ExemptDefinition, UndoableDefinition } from "../project/Dispatcher";
+import type { LayoutChoice } from "../project/state";
+/** `layout.set`: choose the layout that draws the graph. */
+export interface LayoutSetCommand {
+    readonly op: "layout.set";
+    /** The catalogue id, such as `"force"`. A registered engine name is read as the id it serves. */
+    readonly id: LayoutId;
+    /** The engine that draws it, such as `"d3"`; the catalogue's default engine for `id` when absent. */
+    readonly engine?: string;
+    /** The engine's options. */
+    readonly options?: Readonly<Record<string, unknown>>;
+    /**
+     * What it runs over, canonical: absent keeps the scope the slice holds, `"graph"` clears it.
+     * A scope named here is refused when the engine cannot hold nodes still or nothing is in it.
+     */
+    readonly scope?: Scope;
+    /** Choices with the same key coalesce while the first waits its turn (the element's property pair). */
+    readonly coalesce?: string;
+    /** Declared at construction: while the baseline window is open it becomes the baseline. */
+    readonly setup?: boolean;
+}
+/** `layout.scope`: change what layouts run over; `"graph"` for the whole graph. */
+interface LayoutScopeCommand {
+    readonly op: "layout.scope";
+    /** The scope, canonical. */
+    readonly scope: Scope;
+}
+/** `view.dimension`: draw the graph in two or three dimensions. */
+interface ViewDimensionCommand {
+    readonly op: "view.dimension";
+    readonly dimension: "2d" | "3d";
+    /** Declared at construction: while the baseline window is open it becomes the baseline. */
+    readonly setup?: boolean;
+}
+/** `layout.transport`: let the layout move, or hold it still. */
+interface LayoutTransportCommand {
+    readonly op: "layout.transport";
+    readonly action: "play" | "pause";
+}
+/** `view.immersive`: enter VR or AR, or leave it with `null`. */
+interface ViewImmersiveCommand {
+    readonly op: "view.immersive";
+    readonly mode: "vr" | "ar" | null;
+}
+/** Every layout op. */
+export type LayoutCommand = LayoutSetCommand | LayoutScopeCommand | ViewDimensionCommand | LayoutTransportCommand | ViewImmersiveCommand;
+/** The renderer's layout, as the layout ops reach it. A session that draws nothing has none. */
+export interface LayoutService {
+    /**
+     * Build or reconfigure the engine for a choice just written, and spend its pre-steps, inside
+     * the command's slot: the `layout` hook, run inline.
+     * @param choice - The choice, as the slice now holds it.
+     * @param signal - Fires when the command is cancelled or made obsolete; the pre-steps then
+     *     stop without publishing anything.
+     * @param explicitScope - Whether the command named the scope, the only case in which a scope
+     *     the engine cannot hold, or that holds nothing, is refused.
+     * @returns Settles once the pre-steps have landed.
+     */
+    apply(choice: LayoutChoice, signal: AbortSignal, explicitScope: boolean): Promise<void>;
+    /**
+     * Play or pause the layout.
+     * @param action - Which.
+     */
+    transport(action: "play" | "pause"): void;
+    /**
+     * Enter or leave an immersive session.
+     * @param mode - VR, AR, or null to leave.
+     * @returns Settles once the device session has started or ended; rejects when it cannot.
+     */
+    immersive(mode: "vr" | "ar" | null): Promise<void>;
+}
+/** Which layout suits the graph the session holds now: what `data.import` with a recommended layout asks. */
+export type LayoutAdvice = () => {
+    readonly id: LayoutId;
+    readonly engine: string;
+} | undefined;
+/** The layout a graph is drawn with before one is chosen: the element's own default. */
+export declare const DEFAULT_LAYOUT: LayoutChoice;
+/** The layout ops' definitions. */
+export declare const LAYOUT_DEFINITIONS: readonly [UndoableDefinition<LayoutSetCommand>, UndoableDefinition<LayoutScopeCommand>, UndoableDefinition<ViewDimensionCommand>, ExemptDefinition<LayoutTransportCommand>, ExemptDefinition<ViewImmersiveCommand>];
+export {};

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

@@ -0,0 +1,30 @@
+/**
+ * @file The positions ops, each one undoable step on the immediate lane:
+ *
+ * - `positions.set`: place nodes at coordinates. It records the rows it wrote as a row patch, or,
+ *   over more than a third of the rows, a capture; calls made one after another within the
+ *   coalescing window are one step.
+ * - `positions.pin`: pin nodes where they are, or release them. The pinned ids are the `pins`
+ *   slice; the lane's pin bytes and the layout engine follow it.
+ *
+ * See design/undo/undo-design.md sections 6.4 and 10.5.
+ */
+import type { NodeId } from "../../catalog/types";
+import type { UndoableDefinition } from "../project/Dispatcher";
+import type { PositionEntry } from "../types";
+/** `positions.set`: place nodes at coordinates. */
+interface PositionsSetCommand {
+    readonly op: "positions.set";
+    readonly entries: readonly PositionEntry[];
+}
+/** `positions.pin`: pin nodes, or release them. */
+interface PositionsPinCommand {
+    readonly op: "positions.pin";
+    readonly ids: readonly NodeId[];
+    readonly pinned: boolean;
+}
+/** Every positions op. */
+export type PositionsCommand = PositionsSetCommand | PositionsPinCommand;
+/** The positions ops' definitions. */
+export declare const POSITIONS_DEFINITIONS: readonly [UndoableDefinition<PositionsSetCommand>, UndoableDefinition<PositionsPinCommand>];
+export {};