@kekonic/diagrams-core 1.0.0-rc.4

package/dist/index.d.mts

@@ -0,0 +1,967 @@
+//#region src/types/geometry.d.ts
+/** Core geometry and shared primitives — no AST types here. */
+type Point = {
+  x: number;
+  y: number;
+};
+type Vec2 = {
+  x: number;
+  y: number;
+};
+type Rect = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+type BoxPadding = {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+};
+type SourceRange = {
+  start: {
+    line: number;
+    column: number;
+    offset: number;
+  };
+  end: {
+    line: number;
+    column: number;
+    offset: number;
+  };
+};
+type Diagnostic = {
+  severity: "error" | "warning" | "info";
+  code: string;
+  message: string;
+  range: SourceRange;
+  hint?: string;
+};
+declare function rectCenter(r: Rect): Point;
+declare function rectRight(r: Rect): number;
+declare function rectBottom(r: Rect): number;
+declare function rectsOverlap(a: Rect, b: Rect, gap?: number): boolean;
+declare function expandRect(r: Rect, pad: number): Rect;
+declare function manhattan(a: Point, b: Point): number;
+//#endregion
+//#region src/types/shapes.d.ts
+/**
+ * Shared shape id vocabulary — leaf types used by kinds, compile, and geometry.
+ * Geometry implementations live in @kekonic/diagrams-geometry; this module
+ * only names the ids so core can validate without depending on renderers.
+ */
+declare const BUILTIN_SHAPE_IDS: readonly ["rectangle", "rounded", "pill", "circle", "ellipse", "diamond", "hexagon", "triangle", "parallelogram", "trapezoid", "document", "folded-document", "cylinder", "cloud", "person", "queue", "stream", "table", "boundary"];
+type BuiltinShapeId = (typeof BUILTIN_SHAPE_IDS)[number];
+/**
+ * Open shape id — built-ins plus custom registry ids.
+ * Prefer this over a closed union so `registerShape()` can extend the set.
+ */
+type ShapeId = BuiltinShapeId | (string & {});
+declare function normalizeShapeId(shape: string | undefined | null): string;
+declare function isKnownShapeId(shape: string | undefined | null): boolean;
+declare function listBuiltinShapeIds(): readonly string[];
+//#endregion
+//#region src/types/branch.d.ts
+/** Compiled / derived branch outcome for edges (layout + theme share this). */
+type BranchKind = "yes" | "no" | "neutral";
+/**
+ * Classify an edge label into a yes/no/neutral branch cue.
+ * Only clear affirmative/negative tokens — use `branch: yes|no` for outcome wording.
+ */
+declare function classifyBranch(label?: string): BranchKind;
+declare function normalizeBranch(value: unknown): BranchKind | undefined;
+//#endregion
+//#region src/types/cardinality.d.ts
+/**
+ * Relationship endpoint multiplicity for ERD edges.
+ * Drawn as crow's-foot / IE-style markers instead of plain arrowheads.
+ */
+type Cardinality = "one" | "zeroOrOne" | "oneOrMany" | "zeroOrMany";
+type EdgeCardinality = {
+  /** Multiplicity at the source (from) end. */from: Cardinality; /** Multiplicity at the target (to) end. */
+  to: Cardinality;
+};
+/**
+ * Parse cardinality from a property or label.
+ *
+ * Forms:
+ * - `"1:N"` / `"1:0..N"` / `"0..1:N"` (from:to)
+ * - Mermaid-ish `"||--o{"` / `"}o--||"`
+ * - Single side `"N"` (applied to target; source defaults to `one`)
+ */
+declare function parseCardinality(raw: unknown): EdgeCardinality | undefined;
+/**
+ * True when a label only encodes cardinality (crow's-foot already conveys it).
+ * Shared by finalize (label placement) and SVG (hide duplicate text).
+ */
+declare function isPureCardinalityLabel(label: string | undefined): boolean;
+declare function cardinalityLabel(c: EdgeCardinality): string;
+/** Default IE cardinality for a FK from parent → child. */
+declare function fkCardinality(fkNotNull: boolean | undefined): EdgeCardinality;
+//#endregion
+//#region src/types/table.d.ts
+/** Column key roles for ERD-style table nodes. */
+type TableColumnKey = "pk" | "fk" | "uk";
+type TableColumnRef = {
+  /** Referenced table / entity node id. */table: string; /** Referenced column name (usually a PK). */
+  column: string;
+};
+type TableColumn = {
+  /** Column / attribute name. */name: string; /** SQL-ish or conceptual type (e.g. uuid, text, timestamptz). */
+  type?: string; /** Primary / foreign / unique key markers (order preserved). */
+  keys: TableColumnKey[]; /** NOT NULL */
+  notNull?: boolean; /** FK target — e.g. from `"customer_id FK uuid -> customers.id"`. */
+  references?: TableColumnRef; /** Optional short note shown muted after the type. */
+  note?: string;
+};
+/**
+ * Parse a compact column spec string into a structured column.
+ *
+ * Accepted forms (whitespace-separated):
+ * - `"id PK uuid"`
+ * - `"email text UK NN"`
+ * - `"customer_id : uuid FK"`
+ * - `"customer_id FK uuid -> customers.id"`
+ * - `"status text NN // order lifecycle"` (note after //)
+ *
+ * Flags: PK, FK, UK/UNIQUE, NN/NOT NULL/NOTNULL (case-insensitive).
+ */
+declare function parseTableColumnSpec(raw: string): TableColumn | null;
+declare function parseTableColumns(raw: unknown): TableColumn[];
+declare function findColumnIndex(columns: TableColumn[] | undefined, name: string): number;
+/**
+ * Format a structured column as a highlightable line:
+ * `customer_id: uuid FK NN -> customers.id // buyer`
+ */
+declare function formatTableColumnLine(col: TableColumn): string;
+//#endregion
+//#region src/types/sequence.d.ts
+/** Diagram surface — flow/state use ELK; sequence uses the time-axis layout engine. */
+type DiagramKind = "flow" | "state" | "sequence";
+type SequenceMessageKind = "sync" | "async" | "return" | "create" | "destroy" | "failure" | "found" | "lost";
+/**
+ * Combined-fragment operators (canonical long names).
+ * Parser also accepts Mermaid-style aliases: alt, opt, par, group.
+ */
+type SequenceFragmentOperator = "alternate" | "optional" | "loop" | "parallel" | "critical" | "break" | "section";
+/** Map authored keyword (including aliases) → canonical operator. */
+declare const SEQUENCE_FRAGMENT_ALIASES: Record<string, SequenceFragmentOperator>;
+/** Title-case label painted on the fragment frame (newcomer-friendly). */
+declare function sequenceFragmentDisplayName(operator: SequenceFragmentOperator): string;
+declare function normalizeSequenceFragmentOperator(word: string): SequenceFragmentOperator | undefined;
+type SequenceNotePlacement = "over" | "left" | "right";
+type SequenceMessage = {
+  id: string;
+  order: number;
+  from: string | null;
+  to: string | null;
+  kind: SequenceMessageKind;
+  label?: string;
+  labelAuthored?: boolean; /** Pair return messages back to the call that opened them (when known). */
+  replyTo?: string;
+  sourceRange?: SourceRange;
+};
+type SequenceActivation = {
+  id: string;
+  participantId: string;
+  startOrder: number;
+  endOrder: number;
+  sourceRange?: SourceRange;
+};
+type SequenceFragmentOperand = {
+  label?: string;
+  styleRefs: string[]; /** Inclusive message-order span covered by this operand. */
+  startOrder: number;
+  endOrder: number;
+  children: SequenceFragment[];
+};
+type SequenceFragment = {
+  id: string;
+  operator: SequenceFragmentOperator;
+  label?: string; /** `is danger` / authored fragment styles. */
+  styleRefs: string[]; /** Inline CSS vars from `style … for fragment` resolution inputs (compile-time bag). */
+  unresolvedVars: Record<string, string>;
+  startOrder: number;
+  endOrder: number;
+  operands: SequenceFragmentOperand[];
+  sourceRange?: SourceRange;
+};
+type SequenceNote = {
+  id: string;
+  order: number;
+  placement: SequenceNotePlacement;
+  participantIds: string[];
+  text: string;
+  sourceRange?: SourceRange;
+};
+type SequenceDivider = {
+  id: string;
+  order: number;
+  label?: string;
+  sourceRange?: SourceRange;
+};
+/**
+ * Sequence-specific IR compiled beside GraphModel.
+ * Ordering, activations, and fragments live here — not on unordered GraphEdge alone.
+ */
+type SequenceIR = {
+  autonumber: boolean;
+  messages: SequenceMessage[];
+  activations: SequenceActivation[];
+  fragments: SequenceFragment[];
+  notes: SequenceNote[];
+  dividers: SequenceDivider[]; /** Participant ids in declaration order (X axis). */
+  participantOrder: string[];
+};
+//#endregion
+//#region src/parser/edge-ops.d.ts
+/** Edge operators — longest first so `<->` / `<..` / `<~` / `-->` win over shorter prefixes. */
+declare const EDGE_OPS: readonly ["<->", "<..", "<~", "<=", "<-", "x-", "=>", "~>", "..>", "-->", "-x", "->", "--"];
+type EdgeOperator = (typeof EDGE_OPS)[number];
+/** Escape for TextMate / Shiki character classes (e.g. `.` in `..>`). */
+declare function edgeOpsPattern(): string;
+//#endregion
+//#region src/parser/ast.d.ts
+type PropertyValue = string | number | boolean | string[];
+type PropertyMap = Record<string, PropertyValue>;
+type KDiagramAst = {
+  type: "Document";
+  version?: number;
+  body: TopLevelNode[];
+  diagnostics: Diagnostic[];
+};
+type TopLevelNode = DiagramAst | SequenceAst;
+type DiagramAst = {
+  type: "Diagram";
+  diagramKind: "flow" | "state"; /** Optional quoted title after `diagram` — used for SVG/a11y and presentation chrome. */
+  name?: string;
+  statements: StatementAst[];
+  range: SourceRange;
+};
+/** Classical UML sequence diagram — time-axis layout, not ELK layered flow. */
+type SequenceAst = {
+  type: "Sequence";
+  name?: string;
+  statements: SequenceStatementAst[];
+  range: SourceRange;
+};
+type StatementAst = NodeAst | EdgeAst | GroupAst | StyleAst | StyleRefAst | GroupMemberAst | DirectiveAst | LayoutBlockAst | EdgePolicyBlockAst | RenderBlockAst | PresentationBlockAst | AnimationBlockAst;
+type SequenceStatementAst = NodeAst | EdgeAst | StyleAst | StyleRefAst | DirectiveAst | LayoutBlockAst | EdgePolicyBlockAst | RenderBlockAst | PresentationBlockAst | AnimationBlockAst | SequenceActivateAst | SequenceDeactivateAst | SequenceCreateAst | SequenceDestroyAst | SequenceNoteAst | SequenceDividerAst | SequenceAutonumberAst | SequenceFragmentAst;
+type SequenceActivateAst = {
+  type: "SequenceActivate";
+  participantId: string;
+  range: SourceRange;
+};
+type SequenceDeactivateAst = {
+  type: "SequenceDeactivate";
+  participantId: string;
+  range: SourceRange;
+};
+type SequenceCreateAst = {
+  type: "SequenceCreate";
+  node: NodeAst;
+  range: SourceRange;
+};
+type SequenceDestroyAst = {
+  type: "SequenceDestroy";
+  participantId: string;
+  range: SourceRange;
+};
+type SequenceNoteAst = {
+  type: "SequenceNote";
+  placement: "over" | "left" | "right";
+  participantIds: string[];
+  text: string;
+  range: SourceRange;
+};
+type SequenceDividerAst = {
+  type: "SequenceDivider";
+  label?: string;
+  range: SourceRange;
+};
+type SequenceAutonumberAst = {
+  type: "SequenceAutonumber";
+  range: SourceRange;
+};
+type SequenceFragmentAst = {
+  type: "SequenceFragment";
+  operator: SequenceFragmentOperator;
+  label?: string; /** Semantic / authored styles (`is danger`, `is timeoutBand`). */
+  styleRefs: string[];
+  operands: SequenceFragmentOperandAst[];
+  range: SourceRange;
+};
+type SequenceFragmentOperandAst = {
+  /** `else` / `and` label, or primary fragment label. */label?: string; /** Per-operand styles (`else "timeout" is danger`). */
+  styleRefs: string[];
+  statements: SequenceStatementAst[];
+  range: SourceRange;
+};
+type AnimationTargetAst = {
+  type: "all";
+} | {
+  type: "node";
+  id: string;
+} | {
+  type: "edge";
+  from: string;
+  to: string;
+};
+type AnimationCueAst = {
+  type: "dim";
+  targets: AnimationTargetAst[];
+  range: SourceRange;
+} | {
+  type: "activate";
+  targets: AnimationTargetAst[];
+  range: SourceRange;
+} | {
+  type: "pulse";
+  targets: AnimationTargetAst[];
+  durationMs?: number;
+  range: SourceRange;
+} | {
+  type: "flow";
+  path: string[];
+  durationMs?: number;
+  range: SourceRange;
+} | {
+  type: "wait";
+  durationMs: number;
+  range: SourceRange;
+} | {
+  type: "loop";
+  range: SourceRange;
+} | {
+  type: "parallel";
+  cues: AnimationCueAst[];
+  range: SourceRange;
+};
+type AnimationBlockAst = {
+  type: "AnimationBlock";
+  name: string;
+  cues: AnimationCueAst[];
+  range: SourceRange;
+};
+type NodeAst = {
+  type: "Node";
+  id: string;
+  kind: string;
+  label?: string;
+  properties: PropertyMap; /** From inline `is styleName` on the declaration (before or after `{ … }`). */
+  styleRefs: string[];
+  range: SourceRange;
+};
+type EdgeAst = {
+  type: "Edge";
+  from: string;
+  to: string; /** Optional column on the source table (ERD: `customers.id -> …`). */
+  fromColumn?: string; /** Optional column on the target table (ERD: `… -> orders.customer_id`). */
+  toColumn?: string;
+  op: EdgeOperator;
+  label?: string;
+  properties: PropertyMap;
+  styleRefs: string[];
+  range: SourceRange;
+};
+type GroupAst = {
+  type: "Group";
+  id?: string;
+  label?: string;
+  groupKind: "group" | "boundary" | "zone" | "swimlane";
+  statements: StatementAst[];
+  properties: PropertyMap;
+  range: SourceRange;
+};
+type StyleAst = {
+  type: "Style";
+  name: string;
+  target: "node" | "edge" | "fragment";
+  properties: PropertyMap;
+  range: SourceRange;
+};
+type StyleRefAst = {
+  type: "StyleRef";
+  targetIds: string[];
+  styleName: string;
+  range: SourceRange;
+};
+type GroupMemberAst = {
+  type: "GroupMember";
+  nodeIds: string[];
+  range: SourceRange;
+};
+type DirectiveAst = {
+  type: "Directive";
+  name: string; /** Scalar or identifier list (e.g. `columns: [edge, core, data]`). */
+  value?: string | number | boolean | string[];
+  range: SourceRange;
+};
+type LayoutBlockAst = {
+  type: "LayoutBlock";
+  properties: PropertyMap;
+  range: SourceRange;
+};
+type EdgePolicyBlockAst = {
+  type: "EdgePolicyBlock";
+  properties: PropertyMap;
+  range: SourceRange;
+};
+type RenderBlockAst = {
+  type: "RenderBlock";
+  properties: PropertyMap;
+  range: SourceRange;
+};
+type PresentationBlockAst = {
+  type: "PresentationBlock";
+  properties: PropertyMap;
+  range: SourceRange;
+};
+//#endregion
+//#region src/animation/types.d.ts
+/** Compiled animation targeting graph nodes/edges by id. */
+type AnimationTarget = {
+  type: "all";
+} | {
+  type: "node";
+  id: string;
+} | {
+  type: "edge";
+  from: string;
+  to: string;
+};
+type AnimationCue = {
+  op: "dim";
+  targets: AnimationTarget[];
+} | {
+  op: "activate";
+  targets: AnimationTarget[];
+} | {
+  op: "pulse";
+  targets: AnimationTarget[];
+  durationMs: number;
+} | {
+  op: "flow";
+  path: string[];
+  durationMs: number; /** Prefer this edge when from→to is ambiguous (sequence, single hop). */
+  edgeId?: string;
+  /**
+   * Per-hop edge ids aligned with `path` (`path.length - 1` entries).
+   * When present, index `i` is the edge for hop `path[i] → path[i+1]`.
+   */
+  edgeIds?: string[];
+} | {
+  op: "wait";
+  durationMs: number;
+} /** Sibling cues that share one clock — duration is max(child durations). */ | {
+  op: "parallel";
+  cues: AnimationCue[];
+};
+type AnimationDefinition = {
+  /** Stable slug (from authored name, or `"auto"` for inferred). */id: string; /** Display name for the picker. */
+  name: string;
+  loop: boolean;
+  cues: AnimationCue[];
+  /**
+   * `authored` — explicit cues.
+   * `auto` — empty opt-in block; player fills cues via `inferAutoAnimation`.
+   */
+  source: "auto" | "authored";
+};
+//#endregion
+//#region src/types/presentation.d.ts
+/** Padding — uniform number or per-side box. */
+type PaddingSpec = number | {
+  top?: number;
+  right?: number;
+  bottom?: number;
+  left?: number;
+};
+/** Only as-authored — no silent case transforms. */
+type LabelCasePolicy = "as-authored";
+type TitleSpec = false | true | "auto" | {
+  text?: string;
+  subtitle?: string;
+  align?: "start" | "center";
+};
+/**
+ * Opt-in presentation chrome. Omitted options yield embeddable, transparent SVG.
+ * There are no presets — set fields explicitly when you want title, accents, etc.
+ */
+type PresentationOptions = {
+  title?: TitleSpec; /** Outer inset around the full rendered canvas (including chrome). */
+  padding?: PaddingSpec; /** Gap between chrome elements (title block) and diagram content. */
+  contentPadding?: PaddingSpec;
+  labelCase?: LabelCasePolicy;
+  /**
+   * When true, stamp built-in kind eyebrows (Service, Gateway, …) under every node.
+   * Prefer per-node `subtitle: "…"` for authored captions. Default false.
+   */
+  showKindSubtitles?: boolean;
+  /**
+   * When true, paint small dots where edges meet node silhouettes.
+   * Dot fill matches the edge stroke. Default false.
+   */
+  showEndpoints?: boolean; /** Tint group bands for review readability. */
+  groupAccent?: boolean; /** Keep edge labels inside the diagram bounds (default true). */
+  clampLabels?: boolean;
+};
+type ResolvedPadding = {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+};
+type ResolvedTitle = false | {
+  text: string;
+  subtitle?: string;
+  align: "start" | "center";
+};
+/** Fully resolved presentation — no undefined fields. */
+type ResolvedPresentation = {
+  title: ResolvedTitle;
+  padding: ResolvedPadding;
+  contentPadding: ResolvedPadding;
+  labelCase: LabelCasePolicy;
+  showKindSubtitles: boolean;
+  showEndpoints: boolean;
+  groupAccent: boolean;
+  clampLabels: boolean;
+};
+/** Props removed from the presentation DSL — emit a diagnostic instead of ignoring. */
+declare const REMOVED_PRESENTATION_PROPS: readonly ["preset", "background", "grid", "frame", "legend", "nodeGradient", "groupHeaders"];
+type RemovedPresentationProp = (typeof REMOVED_PRESENTATION_PROPS)[number];
+declare function normalizePadding(spec: PaddingSpec | undefined, fallback?: number): ResolvedPadding;
+/** Merge explicit options onto chromeless defaults. */
+declare function resolvePresentation(options: PresentationOptions | undefined, graphTitle?: string): ResolvedPresentation;
+/** Parse a DSL property map into PresentationOptions. */
+declare function presentationFromProperties(props: Record<string, unknown>): PresentationOptions;
+/**
+ * Pick the case policy for a concrete label.
+ * Quoted / authored labels are never rewritten.
+ */
+declare function displayLabelCase(_labelAuthored: boolean | undefined, _policy: LabelCasePolicy): LabelCasePolicy;
+declare function formatLabelText(text: string, _policy: LabelCasePolicy): string;
+/** Shallow-merge presentation layers (later wins). */
+declare function mergePresentationOptions(...layers: (PresentationOptions | undefined)[]): PresentationOptions | undefined;
+//#endregion
+//#region src/types/graph.d.ts
+type EdgeKind = "sync" | "async" | "eventual" | "dependency" | "failure" | "association";
+/** Where arrowheads attach after layout (path always runs from → to). */
+type EdgeArrows = "end" | "start" | "both" | "none";
+type GroupKind = "group" | "boundary" | "zone" | "swimlane";
+type Direction = "LR" | "RL" | "TD" | "BT";
+/** Whole-diagram spacing preset. Local `gap` / `padding` prefer px numbers. */
+type Density = "compact" | "normal" | "spacious";
+type RouteMode = "straight" | "bezier" | "orthogonal" | "rounded" | "metro";
+type CrossingMode = "none" | "gaps" | "jumps" | "smart";
+type BuiltinThemeMode = "dark" | "light";
+/** Built-in themes or names passed to `registerTheme()`. */
+type ThemeMode = BuiltinThemeMode | (string & {});
+type StyleDefinition = {
+  name: string; /** Defaults to node when omitted (authored `style name { }` / builtins). */
+  target?: "node" | "edge" | "fragment";
+  properties: Record<string, string>;
+};
+type GraphNode = {
+  id: string;
+  label: string;
+  /**
+   * True when `label` came from a quoted string literal in source.
+   * False when the label was derived from the bare id.
+   * Authored labels must render verbatim (aside from XML/SVG escaping).
+   */
+  labelAuthored?: boolean;
+  kind: string; /** Geometry id from the shared shape library (normalized at compile). */
+  shape?: ShapeId;
+  icon?: string; /** Paint policy for icons: brand (embedded fills, default) or theme (currentColor). */
+  iconPaint?: "theme" | "brand";
+  /**
+   * Icon-only ink (CSS color). Compiles to `--icon-color` and themes the glyph
+   * without changing the node shell stroke/fill.
+   */
+  iconColor?: string;
+  depth?: number;
+  minWidth?: number;
+  maxWidth?: number; /** Presentation scale for measure + label size (1 = default). */
+  scale?: number;
+  groupId?: string;
+  styleRefs: string[];
+  unresolvedVars?: Record<string, string>;
+  note?: string;
+  /**
+   * When true, show the built-in kind eyebrow (e.g. "Service") for this node.
+   * Prefer authored `subtitle` text when you want a custom line.
+   */
+  showSubtitle?: boolean; /** Optional author-provided subtitle under the title (not the kind name). */
+  subtitle?: string; /** C4 / architecture technology tag (e.g. "Spring Boot", "[Java]"). */
+  technology?: string; /** Longer body text under the title (C4 description). */
+  description?: string; /** ERD columns — when present on a `table` kind, shape becomes an entity card. */
+  columns?: TableColumn[];
+  sourceRange?: SourceRange;
+};
+type GraphEdge = {
+  id: string;
+  from: string;
+  to: string;
+  label?: string;
+  /**
+   * True when `label` came from a quoted string literal in source.
+   * Edge labels are only present when authored; keep the flag for render policy.
+   */
+  labelAuthored?: boolean;
+  kind: EdgeKind;
+  /**
+   * Arrowhead placement on the routed path (`from` → `to`).
+   * Reverse DSL ops (`<-`, …) swap endpoints at compile so arrows stay `"end"`.
+   * Bidirectional `<->` compiles to `"both"`.
+   */
+  arrows?: EdgeArrows;
+  styleRefs: string[]; /** Optional icon shown beside the edge label (same id vocabulary as nodes). */
+  icon?: string; /** Paint policy for edge icons: brand (embedded fills) or theme (currentColor). */
+  iconPaint?: "theme" | "brand"; /** Icon-only ink (CSS color) for the edge label glyph. */
+  iconColor?: string;
+  priority?: "low" | "normal" | "high";
+  /**
+   * Prefer the label near the start, middle, or end of the routed path.
+   * Auto placement still avoids nodes/crossings; this biases the scorer.
+   */
+  labelPosition?: "start" | "middle" | "end"; /** Yes/no/neutral branch cue — explicit DSL or compiled from label. */
+  branch?: BranchKind; /** ERD relationship multiplicity (crow's-foot markers). */
+  cardinality?: EdgeCardinality; /** Source column name for ERD column-anchored edges. */
+  fromColumn?: string; /** Target column name for ERD column-anchored edges. */
+  toColumn?: string;
+  /**
+   * Identifying relationship (solid) vs non-identifying (dashed).
+   * Column-anchored FK edges default to `false` (non-identifying).
+   * Plain table edges without column anchors stay solid unless set explicitly.
+   */
+  identifying?: boolean; /** Sequence message order (0-based) when diagramKind is sequence. */
+  sequenceOrder?: number; /** Sequence message kind when diagramKind is sequence. */
+  sequenceKind?: SequenceMessageKind;
+  sourceRange?: SourceRange;
+};
+type RegionArrange = "stack" | "row" | "grid";
+type RegionAlign = "stretch" | "start" | "center" | "end";
+type CellArrange = "flow" | "pack" | "stack";
+/** Track spec: count, or named tracks for column/row assignment. */
+type TrackSpec = number | string[];
+/** Declaration-order member of a group (node or nested group/zone). */
+type GroupMemberRef = {
+  kind: "node";
+  id: string;
+} | {
+  kind: "group";
+  id: string;
+};
+type GraphGroup = {
+  id: string;
+  label: string;
+  /**
+   * True when `label` came from a quoted string literal in source.
+   * False when the label was derived from the bare group id.
+   */
+  labelAuthored?: boolean;
+  kind: GroupKind;
+  parentId?: string;
+  nodeIds: string[];
+  childGroupIds: string[];
+  /**
+   * Source order of direct members (nodes + child groups).
+   * Used by region arrange so interleaved nodes stay on the track.
+   */
+  members?: GroupMemberRef[];
+  styleRefs: string[];
+  paddingHint?: string;
+  /**
+   * When false, skip border/fill/label (layout-only plane).
+   * Default true — dashed group chrome.
+   */
+  chrome?: boolean; /** Optional glyph beside the group label (same id vocabulary as nodes). */
+  icon?: string; /** Paint policy for group icons: brand (default for logos) or theme. */
+  iconPaint?: "theme" | "brand"; /** Tint the group glyph without changing the group rim. */
+  iconColor?: string;
+  /**
+   * How this group places its child groups/zones.
+   * `stack` / `row` / `grid` = region tracks; omit = ELK ownership.
+   */
+  arrange?: RegionArrange; /** Cross-axis alignment of child regions (default stretch). */
+  align?: RegionAlign; /** Gap between child regions (`compact` | `normal` | `spacious` or px). */
+  gap?: string | number; /** Grid column tracks (count or names). */
+  columns?: TrackSpec; /** Grid row tracks (count or names). */
+  rows?: TrackSpec; /** This region's column (1-based index or track name). */
+  column?: number | string; /** This region's row (1-based index or track name). */
+  row?: number | string; /** Span along the main axis (stack/row) or shorthand for colSpan. */
+  span?: number;
+  colSpan?: number;
+  rowSpan?: number; /** How nodes inside this region are laid out (default flow = ELK). */
+  cellArrange?: CellArrange;
+};
+type GraphModel = {
+  id: string;
+  title?: string; /** Flow (ELK) vs sequence (time-axis). Default `"flow"` when omitted. */
+  diagramKind?: DiagramKind; /** Present when `diagramKind === "sequence"`. */
+  sequence?: SequenceIR;
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+  groups: GraphGroup[];
+  styles: StyleDefinition[]; /** Authored `animation` blocks compiled onto the graph (auto is inferred separately). */
+  animations?: AnimationDefinition[];
+  diagnostics: Diagnostic[];
+};
+type LayoutOptions = {
+  direction?: Direction;
+  density?: Density;
+  spacingScale?: number;
+  algorithmVersion?: "elk-layered-v1";
+  groupGap?: number;
+  /**
+   * Nested group handling for ELK.
+   * - `compound` / `auto` → INCLUDE_CHILDREN (default)
+   * - `flat` → SEPARATE_CHILDREN
+   * - `swimlane` → INCLUDE_CHILDREN (DSL group kind still distinct)
+   */
+  groupLayout?: "auto" | "flat" | "compound" | "swimlane";
+  /**
+   * How layered layout places nodes along each rank.
+   * - `straight` — prefer aligned/straight edges (ELK Brandes–Köpf)
+   * - `balanced` — more even packing (ELK network simplex; default)
+   * - `basic` — fastest / simplest placement (often cleaner for ERDs)
+   *
+   * The compiler also accepts common short aliases (`brandes`, `network`, `simple`)
+   * and ELK strategy spellings (`BRANDES_KOEPF`, …) and maps them to these values.
+   */
+  nodePlacement?: "straight" | "balanced" | "basic"; /** Prefer source order when ranking/ordering. */
+  considerModelOrder?: boolean; /** Edge–node clearance override (defaults from density). */
+  edgeNodeSpacing?: number; /** Parallel-edge clearance override. */
+  edgeEdgeSpacing?: number; /** Clearance between edge labels and other edges/nodes. */
+  edgeLabelSpacing?: number;
+  /**
+   * Arrange ungrouped nodes and top-level groups/zones into tracks (stack / row / grid).
+   * Per-group `arrange` wins when set on a parent.
+   */
+  arrange?: RegionArrange; /** Cross-axis alignment for diagram-level arrange (default stretch). */
+  align?: RegionAlign; /** Gap between top-level regions when `arrange` is set. */
+  gap?: string | number; /** Grid columns when diagram `arrange: grid`. */
+  columns?: TrackSpec; /** Grid rows when diagram `arrange: grid`. */
+  rows?: TrackSpec;
+};
+type RoutingOptions = {
+  /** Paint style for edge polylines (geometry always comes from ELK orthogonal). */route?: RouteMode;
+  crossings?: CrossingMode;
+  cornerRadius?: number; /** DSL-accepted; ignored by ELK (orthogonal routes are independent). */
+  parallel?: "separate" | "shared";
+  arrowheads?: boolean;
+  algorithmVersion?: string;
+};
+type RenderOptions = {
+  theme?: ThemeMode;
+  snapshotTheme?: boolean; /** Additive presentation chrome — default chromeless transparent SVG. */
+  presentation?: PresentationOptions;
+  debug?: DebugOptions; /** Opt-in drop shadows / glow. Default off. */
+  shadows?: boolean;
+  /**
+   * Opt-in corner radius on rectangular node shells (rounded/rectangle/pill,
+   * ERD tables, groups, edge labels). Default off — sharp corners.
+   */
+  roundedCorners?: boolean;
+};
+type DebugOptions = {
+  /** Draw circles at ELK edge attachment points (source + target). */showPorts?: boolean;
+  showBounds?: boolean;
+  showKindLabels?: boolean;
+};
+type CompileOptions = Record<string, never>;
+type InteractiveRenderOptions = RenderOptions & {
+  layout?: LayoutOptions;
+  edges?: RoutingOptions;
+};
+type RenderStats = {
+  parseMs: number;
+  compileMs: number;
+  measureMs: number;
+  layoutMs: number;
+  routeMs: number;
+  renderMs: number;
+  totalMs: number;
+  nodeCount: number;
+  edgeCount: number;
+  layoutAlgorithm: string;
+  routerAlgorithm: string;
+};
+type CompileResult = {
+  graph: GraphModel;
+  layoutHints: LayoutOptions;
+  routingHints: RoutingOptions;
+  renderHints: RenderOptions;
+  diagnostics: Diagnostic[];
+};
+type ParseResult = {
+  ast: KDiagramAst;
+  diagnostics: Diagnostic[];
+};
+type RenderResult = {
+  ok: boolean;
+  svg?: string;
+  ast?: KDiagramAst;
+  graph?: GraphModel;
+  layout?: unknown;
+  routing?: unknown;
+  diagnostics: Diagnostic[];
+  stats: RenderStats;
+};
+type AnimationListItem = {
+  id: string;
+  name: string;
+  source: "auto" | "authored";
+};
+type AnimationPlayerState = {
+  id: string | null;
+  playing: boolean;
+  timeMs: number;
+  durationMs: number;
+  loop: boolean; /** Playback rate in [0.5, 2]. */
+  speed: number;
+};
+type AnimationController = {
+  list(): AnimationListItem[];
+  play(id?: string): void;
+  pause(): void;
+  stop(): void;
+  seek(ms: number): void;
+  step(delta: -1 | 1): void;
+  setLoop(on: boolean): void; /** Clamp playback rate to [0.5, 2]. */
+  setSpeed(rate: number): void;
+  subscribe(listener: (state: AnimationPlayerState) => void): () => void;
+  getState(): AnimationPlayerState;
+};
+type RenderController = {
+  update(source: string, options?: Partial<InteractiveRenderOptions>): Promise<RenderResult>;
+  setTheme(theme: ThemeMode): Promise<RenderResult>; /** Resolves after the initial paint (and first fit). */
+  ready(): Promise<RenderResult>;
+  fit(): void;
+  zoomIn(): void;
+  zoomOut(): void; /** Reset pan/zoom to the fitted natural view (not a model/view switch). */
+  resetView(): void; /** Diagram animation player (auto path or authored `animation` blocks). */
+  animations: AnimationController;
+  destroy(): void;
+};
+declare function mergeOptions<T extends Record<string, unknown>>(defaults: T, ...layers: (Partial<T> | undefined)[]): T;
+//#endregion
+//#region src/animation/infer-auto-animation.d.ts
+type AutoWalkStep = {
+  kind: "chapter";
+} | {
+  kind: "enter";
+  nodeId: string;
+} | {
+  kind: "enter-many";
+  nodeIds: string[];
+} | {
+  kind: "edge";
+  from: string;
+  to: string;
+} | {
+  kind: "parallel-edges";
+  edges: Array<{
+    from: string;
+    to: string;
+  }>;
+};
+/**
+ * Infer Automatic animation.
+ *
+ * - **Exclusive** fan-out (choice nodes / yes·no branches) → one chapter per alternative.
+ * - **Parallel** fan-out (everything else) → `parallel` flow cues in a single story.
+ */
+declare function inferAutoAnimation(graph: GraphModel): AnimationDefinition | null;
+/**
+ * Chaptered walk: exclusive alternatives restart as chapters; concurrent
+ * fan-out becomes parallel edge steps within a chapter.
+ */
+declare function planAutoWalk(graph: GraphModel): AutoWalkStep[];
+/**
+ * Exclusive alternatives as node sequences (parallel siblings linearized in
+ * wavefront order). Prefer {@link planAutoWalk} for playback structure.
+ */
+declare function enumerateAutoPaths(graph: GraphModel): string[][];
+/** First-visit node order across Automatic chapters. */
+declare function traceDeclarationPath(graph: GraphModel): string[];
+//#endregion
+//#region src/animation/bind-sequence-flow-edge-ids.d.ts
+type FlowEdgeRefs = {
+  edgeId?: string;
+  edgeIds?: string[];
+};
+/**
+ * Resolve the concrete edge/message id for hop `i` of a flow cue.
+ * `edgeIds` is authoritative and index-aligned with hops; lone `edgeId` only
+ * covers hop 0 (single-hop convenience / auto-anim).
+ */
+declare function flowHopEdgeId(hopIndex: number, refs: FlowEdgeRefs): string | undefined;
+/** Attach concrete sequence message ids to authored `flow` cues (in place-safe copy). */
+declare function bindSequenceFlowEdgeIds(graph: GraphModel, cues: AnimationCue[]): AnimationCue[];
+//#endregion
+//#region src/animation/index.d.ts
+/** Slugify an authored animation name into a stable id. */
+declare function animationIdFromName(name: string): string;
+//#endregion
+//#region src/parser/parser.d.ts
+declare function parse(source: string): KDiagramAst;
+//#endregion
+//#region src/parser/lexer.d.ts
+/** Soft keywords — statement intros; lexer emits them as identifiers. */
+declare const STATEMENT_KEYWORDS: Set<string>;
+//#endregion
+//#region src/compiler/compile.d.ts
+declare function compile(ast: KDiagramAst, diagramIndex?: number): CompileResult;
+//#endregion
+//#region src/compiler/kinds.d.ts
+/**
+ * Capabilities communicate layout/render behavior beyond the visible shape.
+ * Example: ERD column cards need row anchors even when themed like a cylinder.
+ */
+type NodeCapability = "erd-table" | "symbolic" | "icon-only" | "card" | "annotation" | "boundary" | "messaging" | "datastore" | "sequence-lifeline";
+type NodeKindCategory = "general" | "flowchart" | "architecture" | "infrastructure" | "messaging" | "modeling" | "state" | "git" /** Bare geometry ids usable as kinds: `n: diamond "X"`. */ | "shape";
+type NodeKindDefaults = {
+  shape: ShapeId; /** Default icon when the author omits `icon:` (suppressed with `icon: none`). */
+  icon?: string; /** Presentation subtitle (C4 / architecture eyebrow). */
+  subtitle: string;
+  classNames: string[];
+  cssVars: Record<string, string>;
+  defaultMinWidth: number;
+  defaultMaxWidth: number;
+  defaultDepth: number;
+  category: NodeKindCategory;
+  capabilities: NodeCapability[];
+};
+declare function getKindDefaults(kind: string): {
+  defaults: NodeKindDefaults;
+  isBuiltin: boolean;
+};
+declare function isBuiltinKind(kind: string): boolean;
+/**
+ * True when `kind` names a built-in shape (or alias): `diamond`, `hex`, `cloud`, …
+ * Semantic kinds that share a shape id (`cloud`, `document`, `person`, `queue`) count —
+ * they are usable as both meaning and geometry. ERD `table` is excluded.
+ */
+declare function isGeometryKind(kind: string): boolean;
+declare function kindHasCapability(kind: string, capability: NodeCapability): boolean;
+/** Human-readable kind subtitle for presentation chrome. */
+declare function kindSubtitle(kind: string): string;
+declare function listKindsByCategory(category: NodeKindCategory): string[];
+/**
+ * Shape ids usable directly as kinds (excludes ERD `table`, which stays semantic-only).
+ * Includes semantic synonyms that share a shape id (`cloud`, `document`, `person`, `queue`).
+ */
+declare function listGeometryKinds(): string[];
+declare const BUILTIN_KIND_LIST: string[];
+declare const BUILTIN_KIND_CATALOG: Readonly<Record<string, NodeKindDefaults>>;
+//#endregion
+//#region src/format/print.d.ts
+declare function formatSource(source: string): string;
+//#endregion
+export { type AnimationBlockAst, type AnimationController, type AnimationCue, type AnimationCueAst, type AnimationDefinition, type AnimationListItem, type AnimationPlayerState, type AnimationTarget, type AnimationTargetAst, type AutoWalkStep, BUILTIN_KIND_CATALOG, BUILTIN_KIND_LIST, BUILTIN_SHAPE_IDS, type BoxPadding, type BranchKind, type BuiltinShapeId, type BuiltinThemeMode, type Cardinality, type CellArrange, type CompileOptions, type CompileResult, type CrossingMode, type DebugOptions, type Density, type Diagnostic, type DiagramAst, type DiagramKind, type Direction, type DirectiveAst, EDGE_OPS, type EdgeArrows, type EdgeAst, type EdgeCardinality, type EdgeKind, type EdgeOperator, type EdgePolicyBlockAst, type FlowEdgeRefs, type GraphEdge, type GraphGroup, type GraphModel, type GraphNode, type GroupAst, type GroupKind, type GroupMemberAst, type GroupMemberRef, type InteractiveRenderOptions, type KDiagramAst, type LabelCasePolicy, type LayoutBlockAst, type LayoutOptions, type NodeAst, type NodeCapability, type NodeKindCategory, type NodeKindDefaults, type PaddingSpec, type ParseResult, type Point, type PresentationBlockAst, type PresentationOptions, type PropertyMap, type PropertyValue, REMOVED_PRESENTATION_PROPS, type Rect, type RegionAlign, type RegionArrange, type RemovedPresentationProp, type RenderBlockAst, type RenderController, type RenderOptions, type RenderResult, type RenderStats, type ResolvedPadding, type ResolvedPresentation, type ResolvedTitle, type RouteMode, type RoutingOptions, SEQUENCE_FRAGMENT_ALIASES, STATEMENT_KEYWORDS, type SequenceActivateAst, type SequenceActivation, type SequenceAst, type SequenceAutonumberAst, type SequenceCreateAst, type SequenceDeactivateAst, type SequenceDestroyAst, type SequenceDivider, type SequenceDividerAst, type SequenceFragment, type SequenceFragmentAst, type SequenceFragmentOperand, type SequenceFragmentOperandAst, type SequenceFragmentOperator, type SequenceIR, type SequenceMessage, type SequenceMessageKind, type SequenceNote, type SequenceNoteAst, type SequenceNotePlacement, type SequenceStatementAst, type ShapeId, type SourceRange, type StatementAst, type StyleAst, type StyleDefinition, type StyleRefAst, type TableColumn, type TableColumnKey, type TableColumnRef, type ThemeMode, type TitleSpec, type TopLevelNode, type TrackSpec, type Vec2, animationIdFromName, bindSequenceFlowEdgeIds, cardinalityLabel, classifyBranch, compile, displayLabelCase, edgeOpsPattern, enumerateAutoPaths, expandRect, findColumnIndex, fkCardinality, flowHopEdgeId, formatLabelText, formatSource, formatTableColumnLine, getKindDefaults, inferAutoAnimation, isBuiltinKind, isGeometryKind, isKnownShapeId, isPureCardinalityLabel, kindHasCapability, kindSubtitle, listBuiltinShapeIds, listGeometryKinds, listKindsByCategory, manhattan, mergeOptions, mergePresentationOptions, normalizeBranch, type normalizePadding, normalizeSequenceFragmentOperator, normalizeShapeId, parse, parseCardinality, parseTableColumnSpec, parseTableColumns, planAutoWalk, presentationFromProperties, rectBottom, rectCenter, rectRight, rectsOverlap, resolvePresentation, sequenceFragmentDisplayName, traceDeclarationPath };
+//# sourceMappingURL=index.d.mts.map