@pixerate/editor 0.52.0 → 0.54.0

package/dist/diagram/index.d.cts

@@ -0,0 +1,787 @@
+import { M as MetaCarrier, a as MermaidDocument, E as EditOp, D as DiagramFamily, b as DiagramAdapter, S as SupportTier, P as Preamble, c as DiagramMeta, d as EdgePattern, A as ArrowHead, G as GraphEdge, e as Point, f as DiagramGraph } from '../types-BULrFyuQ.cjs';
+export { g as AdapterParseContext, h as DIRECTIONS, i as Diagnostic, j as Direction, k as GraphGroup, l as GraphNode } from '../types-BULrFyuQ.cjs';
+import { H as HistoryManager } from '../HistoryManager-DeQQMBCj.cjs';
+import { A as AgentToolProvider } from '../registry-DIpIaCkH.cjs';
+import { g as PresenceStore, e as PresenceClock, d as PresenceActorInfo } from '../presence-Cb6WhcrQ.cjs';
+export { P as PRESENCE_COLORS, a as PerformanceQueue, c as PresenceActor, f as PresenceState, h as createInstantPresenceClock, r as realPresenceClock } from '../presence-Cb6WhcrQ.cjs';
+import '../types-DsiXGmjo.cjs';
+import '../schema-Di0CS6Pe.cjs';
+
+interface ParseOptions {
+    /** Force where metadata is written. Defaults per family. */
+    metaCarrier?: MetaCarrier;
+}
+/** Detects the diagram family of a Mermaid source without fully parsing it. */
+declare function detectFamily(source: string): DiagramFamily;
+/**
+ * Parses Mermaid text into a {@link MermaidDocument}.
+ *
+ * Never throws: unknown or malformed input yields a `render-only` document
+ * with diagnostics, so hosts can always show the source editor.
+ */
+declare function parseMermaid(source: string, options?: ParseOptions): MermaidDocument;
+/** Serialises a document back to Mermaid text. */
+declare function serializeMermaid(doc: MermaidDocument): string;
+/**
+ * Applies an edit and returns a new document whose `source` is the updated
+ * text. Documents are immutable; keep the returned value.
+ */
+declare function applyEdit(doc: MermaidDocument, op: EditOp): MermaidDocument;
+/** Applies several edits in order. */
+declare function applyEdits(doc: MermaidDocument, ops: EditOp[]): MermaidDocument;
+
+/** Registers (or replaces) the adapter for a family. */
+declare function registerDiagramAdapter(adapter: DiagramAdapter<unknown>): void;
+declare function getDiagramAdapter(family: DiagramFamily): DiagramAdapter<unknown>;
+/** `editable` for flowchart, state, class and ER diagrams; `render-only` otherwise. */
+declare function supportTierOf(family: DiagramFamily): SupportTier;
+
+interface SplitSource {
+    eol: "\n" | "\r\n";
+    preamble: Preamble;
+    /** Header line without EOL; empty string if none was found. */
+    header: string;
+    /** 0-based index of the header line in the original line array. */
+    headerIndex: number;
+    bodyLines: string[];
+    trailing: string;
+}
+/** Detects the diagram family of a header line (or whole source). */
+declare function detectFamilyFromHeader(header: string): DiagramFamily;
+/**
+ * Splits a Mermaid source into preamble, header, body and trailing whitespace.
+ *
+ * The preamble is everything before the header: an optional YAML frontmatter
+ * block (which must start on the first line), directives, comments and blank
+ * lines. All of it is kept verbatim.
+ */
+declare function splitSource(source: string): SplitSource;
+/**
+ * Splits a single line into `;`-separated statements, ignoring separators
+ * inside quotes or brackets. Mermaid allows `A --> B; B --> C` on one line.
+ */
+declare function splitStatements(line: string): string[];
+
+/** A Mermaid diagram found in some text by {@link findMermaidSources}. */
+interface FoundMermaid {
+    /** The diagram's Mermaid text, without any surrounding code fence. */
+    source: string;
+    /** Its family (never `"unknown"`). */
+    family: DiagramFamily;
+    /** The frontmatter `title`, else the Markdown heading above its code fence. */
+    title?: string;
+}
+/**
+ * Finds the Mermaid diagrams in a piece of text: a `.mmd` file, a Markdown
+ * document with ```` ```mermaid ```` blocks (GitHub, Notion and most AI
+ * chats write them like this), or a diagram pasted with or without its fence.
+ *
+ * Fenced blocks are used when there are any: those marked `mermaid` / `mmd`,
+ * and unmarked ones whose first line is a Mermaid header. Otherwise the whole
+ * text is one diagram if it starts with one. Unmarked text must spell the
+ * keyword as Mermaid does (`timeline`, not `Timeline`). Text that holds no
+ * diagram of a known family returns `[]`.
+ */
+declare function findMermaidSources(text: string): FoundMermaid[];
+
+/** Prefix of the metadata comment line. */
+declare const META_COMMENT_PREFIX = "%% @pixerate ";
+/** Frontmatter key used when comments are not safe for a family. */
+declare const META_FRONTMATTER_KEY = "pixerate";
+declare function emptyMeta(): DiagramMeta;
+declare function mergeMeta(a: DiagramMeta, b: DiagramMeta): DiagramMeta;
+/** True when there is nothing worth writing. */
+declare function isMetaEmpty(meta: DiagramMeta): boolean;
+/** Compact, deterministic JSON so diffs stay small. Positions are rounded. */
+declare function serializeMeta(meta: DiagramMeta): string;
+
+/**
+ * Statement-level model of a flowchart body. Every line of the source maps
+ * to exactly one statement (multi-line `@{ … }` blocks and `;`-joined
+ * statements are normalised during tokenisation). Statements remember their
+ * raw text and are re-emitted verbatim unless marked `dirty`.
+ *
+ * @module
+ */
+interface NodeRef {
+    id: string;
+    /** Shape when declared on this occurrence (bracket or data syntax). */
+    shape?: string;
+    /** How the shape was expressed: classic brackets or `@{ … }`. */
+    form?: "bracket" | "data";
+    label?: string;
+    labelQuoted?: boolean;
+    /** Parsed `@{ … }` entries (shape/label removed). Values keep their raw text. */
+    data?: Record<string, string>;
+    classes: string[];
+}
+interface LinkRef {
+    id?: string;
+    pattern: EdgePattern;
+    arrowStart: ArrowHead;
+    arrowEnd: ArrowHead;
+    length: number;
+    label?: string;
+    labelStyle?: "inline" | "pipe";
+}
+interface Chain {
+    /** `groups[i]` are the nodes joined by `&`; `links[i]` connects group i → i+1. */
+    groups: NodeRef[][];
+    links: LinkRef[];
+}
+type FlowStatement = {
+    kind: "raw";
+    raw: string;
+} | {
+    kind: "chain";
+    raw: string;
+    indent: string;
+    chain: Chain;
+    dirty?: boolean;
+} | {
+    kind: "subgraph";
+    raw: string;
+    indent: string;
+    id: string;
+    title?: string;
+    /** `subgraph id [title]` vs `subgraph "title"` */
+    titleForm: "bracket" | "bare" | "none";
+    dirty?: boolean;
+} | {
+    kind: "end";
+    raw: string;
+    indent: string;
+} | {
+    kind: "direction";
+    raw: string;
+    indent: string;
+    direction: string;
+    dirty?: boolean;
+} | {
+    kind: "classDef";
+    raw: string;
+    indent: string;
+    names: string[];
+    styles: string[];
+    dirty?: boolean;
+} | {
+    kind: "class";
+    raw: string;
+    indent: string;
+    ids: string[];
+    className: string;
+    dirty?: boolean;
+} | {
+    kind: "style";
+    raw: string;
+    indent: string;
+    id: string;
+    styles: string[];
+    dirty?: boolean;
+} | {
+    kind: "linkStyle";
+    raw: string;
+    indent: string;
+    targets: number[] | "default";
+    styles: string[];
+    dirty?: boolean;
+} | {
+    kind: "click";
+    raw: string;
+    indent: string;
+    id: string;
+    rest: string;
+    dirty?: boolean;
+};
+/**
+ * Parses a chain statement (`A[x] --> B & C -- t --> D:::k`).
+ * Returns `null` if the text is not a chain.
+ */
+declare function parseChain(text: string): Chain | null;
+/** Classifies a single logical statement line. */
+declare function parseStatement(line: string): FlowStatement;
+declare function formatNode(node: NodeRef): string;
+declare function formatChain(chain: Chain): string;
+
+/** Body model of a flowchart document. */
+interface FlowchartBody {
+    statements: FlowStatement[];
+}
+type FlowchartDocument = MermaidDocument<FlowchartBody>;
+
+type Doc = MermaidDocument<FlowchartBody>;
+/** Full parse of a flowchart source, used after edits. */
+declare function parseFlowchartSource(source: string, carrier?: Doc["metaCarrier"]): Doc;
+
+/**
+ * Flowchart shape vocabulary.
+ *
+ * Mermaid has two ways to express a shape: classic bracket syntax (`A[text]`)
+ * and the `@{ shape: … }` data syntax introduced in v11. the diagram module normalises
+ * both to the *short name* used by the data syntax (`rect`, `diam`, `cyl`…),
+ * which is also what Mermaid's `getData()` reports for data-syntax nodes.
+ *
+ * @module
+ */
+interface BracketForm {
+    open: string;
+    close: string;
+}
+interface ShapeDef {
+    /** Canonical short name (what `@{ shape: … }` expects). */
+    name: string;
+    /** Human-readable name for UIs. */
+    title: string;
+    /** Alternative names accepted by Mermaid's data syntax. */
+    aliases: string[];
+    /** Classic bracket syntax when one exists. */
+    bracket?: BracketForm;
+    /** Broad visual category, handy for toolbars. */
+    category: "basic" | "process" | "data" | "control" | "misc";
+}
+declare const FLOWCHART_SHAPES: ShapeDef[];
+/** Resolves any accepted shape name/alias (or Mermaid `getData()` id) to its definition. */
+declare function resolveShape(name: string | undefined): ShapeDef | undefined;
+/** Canonical short name for any alias; unknown names pass through unchanged. */
+declare function canonicalShape(name: string | undefined): string;
+
+/**
+ * Flowchart link syntax.
+ *
+ * Grammar (informal):
+ *
+ *     link      := [edgeId '@'] (plainLink | textLink) [ '|' label '|' ]
+ *     plainLink := [head] body [head]
+ *     textLink  := [head] open ws label ws close [head]
+ *     body      := '--'+ | '=='+ | '-' '.'+ '-' | '~~~'+
+ *     head      := '>' | 'x' | 'o' | '<' (start only)
+ *
+ * @module
+ */
+interface ParsedLink {
+    /** User-defined edge id (`A e1@--> B`). */
+    id?: string;
+    pattern: EdgePattern;
+    arrowStart: ArrowHead;
+    arrowEnd: ArrowHead;
+    length: number;
+    label?: string;
+    /** How the label was written, so regeneration keeps the author's style. */
+    labelStyle?: "inline" | "pipe";
+    /** Characters consumed from the input. */
+    consumed: number;
+    raw: string;
+}
+/**
+ * Attempts to parse a link at the start of `input`. Returns `null` when the
+ * input does not begin with a link.
+ */
+declare function parseLink(input: string): ParsedLink | null;
+declare function quoteLabelIfNeeded(label: string): string;
+interface LinkSpec {
+    id?: string;
+    pattern: EdgePattern;
+    arrowStart: ArrowHead;
+    arrowEnd: ArrowHead;
+    length: number;
+    label?: string;
+    labelStyle?: "inline" | "pipe";
+}
+/** Serialises a link back to Mermaid syntax. */
+declare function formatLink(spec: LinkSpec): string;
+
+declare const flowchartAdapter: DiagramAdapter<FlowchartBody>;
+
+/**
+ * A small engine for "one statement per line" Mermaid grammars
+ * (stateDiagram, classDiagram, erDiagram). A grammar classifies each logical
+ * line into a typed statement; the engine builds the graph, applies edits and
+ * re-emits untouched statements verbatim.
+ *
+ * @module
+ */
+interface NodeDecl {
+    id: string;
+    label?: string;
+    shape?: string;
+    classes: string[];
+    /** Family-specific data (members, attributes, descriptions…). */
+    data?: Record<string, unknown>;
+}
+type LineStatement = {
+    kind: "raw";
+    raw: string;
+    indent: string;
+} | {
+    kind: "node";
+    raw: string;
+    indent: string;
+    decl: NodeDecl;
+    /** Multi-line body `{ … }` kept verbatim. */ body?: string[];
+    dirty?: boolean;
+} | {
+    kind: "edge";
+    raw: string;
+    indent: string;
+    source: NodeDecl;
+    target: NodeDecl;
+    label?: string;
+    arrowStart: ArrowHead;
+    arrowEnd: ArrowHead;
+    pattern: GraphEdge["pattern"];
+    /** Family-specific data (cardinalities…). */
+    data?: Record<string, unknown>;
+    dirty?: boolean;
+} | {
+    kind: "groupOpen";
+    raw: string;
+    indent: string;
+    id: string;
+    label?: string;
+    dirty?: boolean;
+} | {
+    kind: "groupClose";
+    raw: string;
+    indent: string;
+} | {
+    kind: "direction";
+    raw: string;
+    indent: string;
+    direction: string;
+    dirty?: boolean;
+} | {
+    kind: "classDef";
+    raw: string;
+    indent: string;
+    names: string[];
+    styles: string[];
+    dirty?: boolean;
+} | {
+    kind: "class";
+    raw: string;
+    indent: string;
+    ids: string[];
+    className: string;
+    dirty?: boolean;
+} | {
+    kind: "style";
+    raw: string;
+    indent: string;
+    id: string;
+    styles: string[];
+    dirty?: boolean;
+};
+interface EdgeSpec {
+    label?: string;
+    arrowStart: ArrowHead;
+    arrowEnd: ArrowHead;
+    pattern: GraphEdge["pattern"];
+    data?: Record<string, unknown>;
+}
+interface LineGrammar {
+    family: DiagramFamily;
+    defaultShape: string;
+    /** Groups logical statements from physical lines (brace blocks, `end note`, …). */
+    joinLines(lines: string[]): string[];
+    parseLine(line: string): LineStatement;
+    formatStatement(stmt: LineStatement): string;
+    /** Builds a node statement for a new node. */
+    nodeStatement(decl: NodeDecl, indent: string): LineStatement;
+    /** Builds an edge statement. */
+    edgeStatement(source: string, target: string, spec: EdgeSpec, indent: string): LineStatement;
+    /** Builds the open/close statements of a group. */
+    groupStatements(id: string, label: string | undefined, indent: string): {
+        open: LineStatement;
+        close: LineStatement;
+    };
+    /** Reads the header direction. */
+    headerDirection(header: string, statements: LineStatement[]): string;
+    /** Optional: pseudo-node ids such as `[*]` that need special graph handling. */
+    resolveEndpoint?(id: string, groupStack: string[], role: "source" | "target"): {
+        id: string;
+        shape: string;
+        label: string;
+        synthetic: true;
+    } | null;
+    /** Default edge spec when the UI connects two nodes. */
+    defaultEdge: EdgeSpec;
+    /** Whether `setDirection` writes a `direction` statement (true) or the header. */
+    directionAsStatement: boolean;
+    /** False when the family has no grouping construct (ER). Group ops become no-ops. */
+    supportsGroups?: boolean;
+}
+interface LineBody {
+    statements: LineStatement[];
+}
+type LineDocument = MermaidDocument<LineBody>;
+/** Creates a full adapter from a grammar. */
+declare function createLineAdapter(grammar: LineGrammar): DiagramAdapter<LineBody>;
+
+declare const STATE_SHAPES: readonly [{
+    readonly name: "rect";
+    readonly title: "State";
+}, {
+    readonly name: "fork";
+    readonly title: "Fork";
+}, {
+    readonly name: "join";
+    readonly title: "Join";
+}, {
+    readonly name: "choice";
+    readonly title: "Choice";
+}];
+declare const stateGrammar: LineGrammar;
+
+/** Relation syntax → arrow heads. Order matters: longer tokens first. */
+interface ClassRelation {
+    token: string;
+    arrowStart: ArrowHead;
+    arrowEnd: ArrowHead;
+    pattern: EdgePattern;
+    title: string;
+}
+declare const CLASS_RELATIONS: ClassRelation[];
+declare function relationFor(arrowStart: ArrowHead, arrowEnd: ArrowHead, pattern: EdgePattern): ClassRelation;
+interface ClassMember {
+    raw: string;
+    visibility?: "+" | "-" | "#" | "~";
+    kind: "attribute" | "method";
+}
+declare function parseMembers(bodyLines: string[]): ClassMember[];
+declare const classGrammar: LineGrammar;
+
+declare const ER_CARDINALITIES: {
+    token: string;
+    head: ArrowHead;
+    side: "left" | "right";
+    title: string;
+}[];
+interface ErAttribute {
+    raw: string;
+    type: string;
+    name: string;
+    keys: string[];
+    comment?: string;
+}
+declare function parseAttributes(bodyLines: string[]): ErAttribute[];
+declare const erGrammar: LineGrammar;
+declare const ER_PATTERNS: {
+    pattern: EdgePattern;
+    title: string;
+}[];
+
+/** Body of a render-only document: the raw body lines. */
+interface PassthroughBody {
+    lines: string[];
+}
+/**
+ * Adapter for families the diagram module cannot edit on a canvas. The text is preserved
+ * verbatim; only `replaceSource`, `setTitle` and metadata edits apply.
+ */
+declare function createPassthroughAdapter(family: DiagramFamily, tier?: SupportTier): DiagramAdapter<PassthroughBody>;
+
+/** Families that can be edited on the canvas; every other family is kept as text. */
+declare const EDITABLE_DIAGRAM_FAMILIES: readonly ["flowchart", "state", "class", "er"];
+/** The shapes a node of `family` can take (`setNodeShape`), as canonical names. */
+declare function diagramShapes(family: DiagramFamily): string[];
+/** Whether the family has groups (subgraphs, composite states, namespaces). ER diagrams do not. */
+declare function diagramSupportsGroups(family: DiagramFamily): boolean;
+/**
+ * Checks an edit against the document before it is applied. Returns a sentence saying
+ * what is wrong and how to fix it, or `null` when the edit is valid. Ids are checked
+ * against nodes, groups and edges; shapes against {@link diagramShapes}.
+ */
+declare function validateDiagramEdit(doc: MermaidDocument, op: EditOp): string | null;
+interface DiagramControllerOptions {
+    /** Starting Mermaid source (default: an empty `flowchart TD`). */
+    source?: string;
+    /** History to record into, e.g. one shared with the rest of the app (default: a new one). */
+    history?: HistoryManager;
+    /** Refuse edits (read tools still work). */
+    readOnly?: boolean;
+    /** Called after the source changes (edit, undo, redo, load). */
+    onChange?: (source: string, document: MermaidDocument) => void;
+}
+/** A snapshot of the controller. The same object is returned until something changes. */
+interface DiagramState {
+    document: MermaidDocument;
+    /** The Mermaid text, always in step with `document`. */
+    source: string;
+    family: DiagramFamily;
+    /** True for flowchart, state, class and ER diagrams that are not read-only. */
+    editable: boolean;
+    readOnly: boolean;
+    /** Selected node, group or edge ids. */
+    selection: readonly string[];
+    /** The problem with the last rejected edit, if any. */
+    issue: string | null;
+    canUndo: boolean;
+    canRedo: boolean;
+    undoLabel: string;
+    redoLabel: string;
+    /** Bumped on every change. */
+    revision: number;
+}
+type DiagramActionResult = {
+    ok: true;
+    document: MermaidDocument;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Headless state for a Mermaid diagram editor: the parsed document, a selection and
+ * undoable statement-level edits. Every `apply` is one undo step and only rewrites the
+ * statements it touches, so untouched text (comments, directives, formatting) survives.
+ * Canvas positions go into the `%% @pixerate {…}` comment. Drags merge into one undo
+ * step between `beginGesture` and `endGesture`. `getState()` returns the same object
+ * until something changes, so it works with `useSyncExternalStore` and Svelte runes.
+ */
+declare class DiagramController {
+    readonly history: HistoryManager;
+    private doc;
+    private selection;
+    private issue;
+    private readOnly;
+    private revision;
+    private applying;
+    private gestureKey;
+    private gestureCount;
+    private readonly onChange?;
+    private readonly listeners;
+    private unsubscribeHistory?;
+    private state;
+    constructor(options?: DiagramControllerOptions);
+    private connect;
+    /** Stops listening to the history (subscribing again reconnects). */
+    destroy(): void;
+    /** The current snapshot (stable until the next change). */
+    getState: () => DiagramState;
+    /** Calls `listener` after every change. Returns an unsubscribe function. */
+    subscribe: (listener: (state: DiagramState) => void) => (() => void);
+    /** The current document (immutable; edit through the controller). */
+    getDocument(): MermaidDocument;
+    getSource(): string;
+    private computeState;
+    private notify;
+    private setDocument;
+    private commit;
+    private reject;
+    /**
+     * Applies edits as one undo step. All-or-nothing: every edit is checked against the
+     * document as it stands after the edits before it, and nothing changes when one fails.
+     */
+    apply(ops: EditOp | EditOp[], label?: string): DiagramActionResult;
+    /**
+     * Replaces the whole source. `clearHistory` drops the undo stack (opening a file);
+     * otherwise the replacement is one undo step.
+     */
+    load(source: string, options?: {
+        clearHistory?: boolean;
+    }): DiagramActionResult;
+    setReadOnly(readOnly: boolean): void;
+    /** Selects node, group or edge ids (unknown ids are dropped). */
+    select(ids: readonly string[]): void;
+    /** Edits until `endGesture` (e.g. the moves of one drag) fold into one undo step. */
+    beginGesture(key: string): void;
+    endGesture(): void;
+    undo(): boolean;
+    redo(): boolean;
+    /** A node id not used by any node or group: `prefix` followed by the next free number. */
+    nextId(prefix?: string): string;
+}
+
+/** Where things are drawn on the canvas (absolute top-left and size), e.g. `mermaidToCanvas(...).layout`. */
+interface DiagramPlacement {
+    positions: Readonly<Record<string, Point>>;
+    sizes: Readonly<Record<string, {
+        width: number;
+        height: number;
+    }>>;
+}
+type DiagramPerformanceStep = {
+    type: 'move';
+    to: {
+        x: number;
+        y: number;
+    };
+    ms: number;
+} | {
+    type: 'say';
+    text: string;
+    ms: number;
+} | {
+    type: 'type';
+    text: string;
+    ms: number;
+} | {
+    type: 'press';
+} | {
+    type: 'release';
+}
+/** Drag a node (and the cursor) so its top-left ends at `to`; the node follows live. */
+ | {
+    type: 'drag';
+    id: string;
+    to: {
+        x: number;
+        y: number;
+    };
+    position: Point;
+    ms: number;
+} | {
+    type: 'commit';
+};
+/**
+ * Plans how an agent acts out one edit on the canvas: where the cursor goes, what it
+ * clicks, drags or types, and when the edit commits. Pure: the same document, placement
+ * and edit give the same steps. `next` is the edit that follows in the same call (a new
+ * node is placed beside the node an edge will connect it from).
+ */
+declare function planDiagramEdit(doc: MermaidDocument, place: DiagramPlacement, op: EditOp, speed?: number, next?: EditOp): DiagramPerformanceStep[];
+interface DiagramDirectorOptions {
+    /** Where nodes are drawn now, e.g. `() => mermaidToCanvas(controller.getDocument()).layout`. */
+    placement: () => DiagramPlacement;
+    clock?: PresenceClock;
+    /** 1 = natural speed; 2 = twice as fast. */
+    speed?: number;
+    /** Hide each actor's cursor this long after its last call (ms, default 1500; 0 keeps it). */
+    linger?: number;
+    /** Most frames when a whole-diagram write is drawn statement by statement (default 40). */
+    maxDraftFrames?: number;
+}
+type DiagramPerformanceResult = {
+    ok: true;
+    document: MermaidDocument;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Acts out agent edits on a Mermaid diagram: each actor's cursor moves to the node or edge,
+ * clicks, drags, connects and types, the edit lands, and everything one call changes is one
+ * undo step, while the user keeps editing. Calls queue per actor. A batch is checked against
+ * the diagram before the cursor moves; if the diagram changed underneath and an edit no
+ * longer applies, the call's earlier edits are rolled back and the call fails with a sentence.
+ * A whole-diagram write (`playSource`) is drawn statement by statement.
+ */
+declare class DiagramDirector {
+    private readonly controller;
+    private readonly options;
+    readonly presence: PresenceStore;
+    private readonly clock;
+    private readonly queue;
+    constructor(controller: DiagramController, presence: PresenceStore, options: DiagramDirectorOptions);
+    /** Acts out `ops` in order for `actor` as one undo step. */
+    perform(actor: PresenceActorInfo, ops: readonly EditOp[], label?: string): Promise<DiagramPerformanceResult>;
+    /**
+     * Replaces the diagram with `source`, drawing it statement by statement when it extends
+     * what is there (Ursula's draft playback): each frame lands, the cursor points at what
+     * appeared, and the whole write is one undo step. Otherwise it lands at once.
+     */
+    playSource(actor: PresenceActorInfo, source: string, label?: string): Promise<DiagramPerformanceResult>;
+    /** Stores the drawn position of every node and group that has none yet. */
+    private pin;
+    /** Runs one step; returns a problem sentence when the edit can no longer be applied. */
+    private act;
+}
+/** Reads a document for planning without a controller (tests, previews). */
+declare function planDiagramEdits(source: string, place: DiagramPlacement, ops: readonly EditOp[], speed?: number): DiagramPerformanceStep[][];
+
+interface DiagramToolProviderOptions {
+    /** Provider id (unique per registry). Default `diagram`. */
+    id?: string;
+    /** Always prefix tool names with `<namespace>__`. */
+    namespace?: string;
+    /**
+     * The diagram cannot be edited: write tools are hidden and `get_diagram` says why. A
+     * string is the reason ("The report is locked"). The controller's own `readOnly` counts too.
+     */
+    readOnly?: boolean | string | (() => boolean | string);
+    /**
+     * Where the canvas shows each node now (absolute top-left), e.g. `() => canvas.layout.positions`.
+     * When given, a move pins every node that has no stored position yet, so moving one
+     * node of an auto-laid diagram does not shift the others.
+     */
+    getPositions?: () => Readonly<Record<string, Point>>;
+    /**
+     * Acts out every write with a visible cursor (see `DiagramDirector`): it moves to the node,
+     * clicks, drags, connects and types, and a whole-diagram load is drawn statement by
+     * statement. Each call is still one undo step. Without it, edits apply at once.
+     */
+    director?: DiagramDirector;
+    /** Who the cursor belongs to (default `{ id: 'agent', name: 'Agent' }`). */
+    actor?: PresenceActorInfo;
+}
+/** What an agent needs to know about a document: ids, labels, shapes, structure. */
+declare function describeDiagram(doc: MermaidDocument): {
+    diagnostics?: {
+        line?: number | undefined;
+        severity: "info" | "error" | "warning";
+        message: string;
+    }[] | undefined;
+    nodes: {
+        synthetic?: boolean | undefined;
+        styles?: string[] | undefined;
+        classes?: string[] | undefined;
+        parentId?: string | undefined;
+        id: string;
+        label: string;
+        shape: string;
+    }[];
+    edges: {
+        pattern: EdgePattern;
+        arrowEnd: ArrowHead;
+        label?: string | undefined;
+        id: string;
+        source: string;
+        target: string;
+    }[];
+    groups: {
+        direction?: string | undefined;
+        parentId?: string | undefined;
+        id: string;
+        label: string;
+    }[];
+    shapes: string[];
+    positions: {
+        [k: string]: {
+            x: number;
+            y: number;
+        };
+    };
+    title?: string | undefined;
+    family: DiagramFamily;
+    editable: boolean;
+    direction: string;
+};
+/**
+ * Agent tools for a Mermaid diagram (`DiagramController`), for a `ToolRegistry`: one
+ * tool per operation with strict schemas. Reads (`get_diagram`, `export_diagram_mermaid`,
+ * `find_mermaid_diagrams`) are always there; writes are hidden while the diagram is
+ * read-only. Every write is checked against the current diagram first (unknown ids,
+ * taken ids, shapes the family does not have), applies as one undo step, and returns
+ * what it created or changed. Untouched Mermaid statements are kept byte for byte.
+ */
+declare function createDiagramToolProvider(controller: DiagramController, options?: DiagramToolProviderOptions): AgentToolProvider;
+
+interface DraftOptions {
+    /** Most frames to play; longer drafts are sampled evenly (default 40). */
+    maxFrames?: number;
+}
+/**
+ * Splits writing `target` over `current` into frames that grow the diagram
+ * statement by statement, so a whole-diagram write can be played as the
+ * diagram being drawn. Each frame is a valid prefix of `target` (it parses
+ * as the same family without diagnostics) that shows something new; the last
+ * frame is `target` itself.
+ *
+ * Returns null when `target` does not extend `current` (some existing line
+ * changes), when the family changes, or when there is nothing to grow: the
+ * write is then committed in one step.
+ */
+declare function draftFrames(current: string, target: string, options?: DraftOptions): string[] | null;
+/** Ids of nodes and groups in `after` that are new or changed since `before`. */
+declare function changedItems(before: DiagramGraph, after: DiagramGraph): string[];
+
+export { ArrowHead, CLASS_RELATIONS, type Chain, type ClassMember, type ClassRelation, type DiagramActionResult, DiagramAdapter, DiagramController, type DiagramControllerOptions, DiagramDirector, type DiagramDirectorOptions, DiagramFamily, DiagramGraph, DiagramMeta, type DiagramPerformanceResult, type DiagramPerformanceStep, type DiagramPlacement, type DiagramState, type DiagramToolProviderOptions, type DraftOptions, EDITABLE_DIAGRAM_FAMILIES, ER_CARDINALITIES, ER_PATTERNS, EdgePattern, type EdgeSpec, EditOp, type ErAttribute, FLOWCHART_SHAPES, type FlowStatement, type FlowchartBody, type FlowchartDocument, type FoundMermaid, GraphEdge, type LineBody, type LineDocument, type LineGrammar, type LineStatement, type LinkRef, type LinkSpec, META_COMMENT_PREFIX, META_FRONTMATTER_KEY, MermaidDocument, MetaCarrier, type NodeDecl, type NodeRef, type ParseOptions, type PassthroughBody, Point, Preamble, PresenceActorInfo, PresenceClock, PresenceStore, STATE_SHAPES, type ShapeDef, type SplitSource, SupportTier, applyEdit, applyEdits, canonicalShape, changedItems, classGrammar, createDiagramToolProvider, createLineAdapter, createPassthroughAdapter, describeDiagram, detectFamily, detectFamilyFromHeader, diagramShapes, diagramSupportsGroups, draftFrames, emptyMeta, erGrammar, findMermaidSources, flowchartAdapter, formatChain, formatLink, formatNode, getDiagramAdapter, isMetaEmpty, mergeMeta, parseAttributes, parseChain, parseFlowchartSource, parseLink, parseMembers, parseMermaid, parseStatement, planDiagramEdit, planDiagramEdits, quoteLabelIfNeeded, registerDiagramAdapter, relationFor, resolveShape, serializeMermaid, serializeMeta, splitSource, splitStatements, stateGrammar, supportTierOf, validateDiagramEdit };