# Interfaces A–S

Import these from `@grafloria/engine`.

## Interfaces

### `ASTNode`

Base AST Node

```ts
interface ASTNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `string` |  |  |
| `location?` | `SourceLocation` |  |  |

### `ASTPosition`

```ts
interface Position
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `line` | `number` |  |  |
| `column` | `number` |  |  |
| `index` | `number` |  |  |

### `BlockGridSpec`

The grid a container carries for the architecture layout (`metadata.grid`).

```ts
interface BlockGridSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns?` | `number` |  |  |
| `cells` | `Array<{ id?: string; span: number }>` |  |  |

### `ClassDefNode`

Also has every member of `ASTNode`, listed on its own entry.

Class definition: classDef className fill:#f9f

```ts
interface ClassDefNode extends ASTNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'ClassDef'` |  |  |
| `className` | `string` |  |  |
| `properties` | `StyleProperties` |  |  |

### `ConflictInfo`

```ts
interface ConflictInfo
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `timestamp` | `Date` |  | Timestamp of conflict |
| `sources` | `[SyncDirection, SyncDirection]` |  | Conflicting edit sources |
| `resolution` | `'last-write-wins' \| 'user-choice' \| 'merge'` |  | Resolution strategy used |
| `resolved` | `boolean` |  | Was conflict resolved |

### `DiagramAnalysis`

```ts
interface DiagramAnalysis
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `diagramType` | `DiagramType` |  | Suggested diagram type |
| `direction` | `Direction` |  | Suggested direction |
| `nodeOrder` | `string[]` |  | Node ID to order mapping (for sequential output) |
| `nodeGroups` | `Map<string, string[]>` |  | Grouped nodes (for subgraphs) |
| `nodeMetadata` | `Map<string, { shape: string; hasCustomStyle: boolean; }>` |  | Node metadata |
| `linkMetadata` | `Map<string, { hasLabel: boolean; hasCustomStyle: boolean; }>` |  | Link metadata |
| `stats` | `{ nodeCount: number; linkCount: number; maxDepth: number; hasCycles: boolean; }` |  | Overall statistics |

### `DiagramCharacteristics`

```ts
interface DiagramCharacteristics
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `nodeCount` | `number` |  |  |
| `linkCount` | `number` |  |  |
| `hasCycles` | `boolean` |  |  |
| `maxDepth` | `number` |  |  |
| `averageDegree` | `number` |  |  |
| `maxDegree` | `number` |  |  |
| `isTree` | `boolean` |  |  |
| `isDAG` | `boolean` |  |  |
| `direction?` | `Direction` |  |  |
| `diagramType?` | `string` |  |  |

### `DiagramNode`

Also has every member of `ASTNode`, listed on its own entry.

Root diagram node

```ts
interface DiagramNode extends ASTNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'Diagram'` |  |  |
| `diagramType` | `DiagramType` |  |  |
| `direction?` | `Direction` |  |  |
| `statements` | `StatementNode[]` |  |  |

### `DSLOptions`

```ts
interface DSLOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `autoLayout?` | `boolean` |  | Auto-apply layout after parsing |
| `transformOptions?` | `TransformOptions` |  | Transformation options |
| `debug?` | `boolean` |  | Enable debug logging |

### `EdgeDefinitionNode`

Also has every member of `ASTNode`, listed on its own entry.

Edge/Link definition: A --> B

```ts
interface EdgeDefinitionNode extends ASTNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'EdgeDefinition'` |  |  |
| `source` | `string` |  |  |
| `target` | `string` |  |  |
| `linkType` | `LinkType` |  |  |
| `label?` | `string` |  |  |
| `style?` | `StyleProperties` |  |  |
| `sourceShape?` | `NodeShape` |  | Source node shape if specified inline (e.g., A[Label] --> B) |
| `sourceLabel?` | `string` |  | Source node label if specified inline (e.g., A[Label] --> B) |
| `targetShape?` | `NodeShape` |  | Target node shape if specified inline (e.g., A --> B[Label]) |
| `targetLabel?` | `string` |  | Target node label if specified inline (e.g., A --> B[Label]) |

### `ErSpec`

```ts
interface ErSpec
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `entities` | `ErSpecEntity[]` |  |  |
| `relationships` | `ErSpecRelationship[]` |  |  |

### `FormatterOptions`

DSL Formatter - Formats DSL text for readability

Provides clean, consistent formatting for generated DSL text:
- Proper indentation
- Line wrapping
- Comment alignment
- Whitespace normalization

```ts
interface FormatterOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `indent?` | `string` |  | Indentation string (default: 2 spaces) |
| `maxLineLength?` | `number` |  | Maximum line length before wrapping |
| `preserveBlankLines?` | `boolean` |  | Preserve blank lines |
| `blankLineBeforeComments?` | `boolean` |  | Add blank line before comments |
| `alignComments?` | `boolean` |  | Align comments to column |

### `GeneratorOptions`

```ts
interface GeneratorOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `includeComments?` | `boolean` |  | Include comments in output |
| `includeStyles?` | `boolean` |  | Include style definitions |
| `format?` | `boolean` |  | Format output (uses DSLFormatter) |
| `preserveIds?` | `boolean` |  | Preserve node IDs from diagram |
| `includeSubgraphs?` | `boolean` |  | Generate subgraphs |
| `positions?` | `boolean` |  | Write `%%grafloria:at id x,y WxH` for every node and zone (see ExportTextOptions.positions). |

### `IntegratedSyncOptions`

```ts
interface IntegratedSyncOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `syncOptions?` | `SyncOptions` |  | Bidirectional sync options |
| `layoutOptions?` | `LayoutApplicatorOptions` |  | Layout applicator options |
| `autoLayoutOnTextChange?` | `boolean` |  | Enable auto-layout on text changes |
| `debug?` | `boolean` |  | Enable debug logging |

### `LayoutApplicationResult`

```ts
interface LayoutApplicationResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `success` | `boolean` |  | Was layout applied successfully |
| `presetId?` | `string` |  | Layout preset that was applied |
| `confidence?` | `number` |  | Confidence of the layout selection |
| `reasoning?` | `string` |  | Reasoning for layout choice |
| `applyTime?` | `number` |  | Time taken to apply layout (ms) |
| `error?` | `string` |  | Error if layout failed |

### `LayoutApplicatorOptions`

```ts
interface LayoutApplicatorOptions
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `minConfidence?` | `number` |  | Minimum confidence threshold to auto-apply (0-1) |
| `debug?` | `boolean` |  | Enable debug logging |
| `customLayouts?` | `Map<string, LayoutConfiguration>` |  | Custom layout configurations |

### `LayoutSuggestion`

```ts
interface LayoutSuggestion
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `presetId` | `string` |  | Recommended layout preset ID |
| `confidence` | `number` |  | Confidence score (0-1) |
| `reasoning` | `string` |  | Reasoning for this suggestion |
| `alternatives?` | `string[]` |  | Alternative suggestions |

### `MermaidArchEdge`

```ts
interface MermaidArchEdge
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `from` | `string` |  |  |
| `fromSide` | `ArchSide` |  |  |
| `to` | `string` |  |  |
| `toSide` | `ArchSide` |  |  |
| `arrowFrom` | `boolean` |  |  |
| `arrowTo` | `boolean` |  |  |
| `label?` | `string` |  |  |
| `fromGroup?` | `boolean` |  | `{group}`: the line joins the GROUP the service is in, at its edge. |
| `toGroup?` | `boolean` |  |  |

### `MermaidArchGroup`

```ts
interface MermaidArchGroup
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `icon?` | `string` |  |  |
| `title?` | `string` |  |  |
| `parent?` | `string` |  |  |

### `MermaidArchitectureModel`

```ts
interface MermaidArchitectureModel
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `groups` | `MermaidArchGroup[]` |  |  |
| `services` | `MermaidArchService[]` |  |  |
| `junctions` | `MermaidArchJunction[]` |  |  |
| `edges` | `MermaidArchEdge[]` |  |  |

### `MermaidArchJunction`

```ts
interface MermaidArchJunction
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `parent?` | `string` |  |  |

### `MermaidBlockModel`

```ts
interface MermaidBlockModel
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `columns?` | `number` |  | Blocks to a row; undefined = `auto` (one row). |
| `cells` | `BlockCell[]` |  |  |
| `passthrough` | `string[]` |  | Lines the flowchart grammar reads as they are: edges, style, classDef, class, linkStyle, %%grafloria. |

### `MermaidClassDef`

```ts
interface MermaidClassDef
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `name` | `string` |  | Display name — `class Foo["Bar"]` label, else the id (generics included). |
| `stereotype?` | `string` |  | `<<interface>>` / `<<abstract>>` / `<<enum>>` / … |
| `generic?` | `string` |  | `class Square~Shape~` generic parameter. |
| `attributes` | `MermaidClassMember[]` |  |  |
| `methods` | `MermaidClassMember[]` |  |  |
| `cssClasses` | `string[]` |  | `:::css` style classes applied to the node. |

### `MermaidClassMember`

```ts
interface MermaidClassMember
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `raw` | `string` |  | The member exactly as written (minus the visibility marker's whitespace). |
| `visibility?` | `UmlVisibility` |  |  |
| `name` | `string` |  |  |
| `isMethod` | `boolean` |  |  |
| `classifier?` | `'$' \| '*'` |  | `$` (static) / `*` (abstract) classifier suffixes Mermaid supports. |

### `MermaidClassModel`

```ts
interface MermaidClassModel
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `classes` | `MermaidClassDef[]` |  |  |
| `relationships` | `MermaidClassRelationship[]` |  |  |
| `direction?` | `string` |  |  |
| `notes` | `Array<{ for?: string; text: string }>` |  | `note "text"` / `note for X "text"` — kept so export does not drop them. |

### `MermaidClassRelationship`

```ts
interface MermaidClassRelationship
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `from` | `string` |  | Left operand, exactly as written. |
| `to` | `string` |  | Right operand, exactly as written. |
| `operator` | `UmlOperator` |  |  |
| `label?` | `string` |  |  |
| `multiplicity?` | `[string, string]` |  | Multiplicity as written: [left-of-operator, right-of-operator]. |

### `MermaidErAttribute`

```ts
interface MermaidErAttribute
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `string` |  |  |
| `name` | `string` |  |  |
| `keys` | `string[]` |  | PK / FK / UK, in source order. |
| `comment?` | `string` |  |  |

### `MermaidErEntity`

```ts
interface MermaidErEntity
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | The identifier used in relationships. |
| `name` | `string` |  | Display name — the `ENTITY["alias"]` alias when given, else the id. |
| `attributes` | `MermaidErAttribute[]` |  |  |

### `MermaidErModel`

```ts
interface MermaidErModel
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `entities` | `MermaidErEntity[]` |  |  |
| `relationships` | `MermaidErRelationship[]` |  |  |
| `direction?` | `string` |  |  |

### `MermaidErRelationship`

```ts
interface MermaidErRelationship
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `from` | `string` |  | Left-hand entity id, exactly as written. |
| `to` | `string` |  | Right-hand entity id, exactly as written. |
| `left` | `ErLeftToken` |  |  |
| `right` | `ErRightToken` |  |  |
| `identifying` | `boolean` |  | `--` (identifying: the child cannot exist without the parent) vs `..` (non-identifying). Mermaid renders the latter dashed. |
| `label` | `string` |  |  |

### `MermaidStateModel`

```ts
interface MermaidStateModel
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `states` | `MermaidStateNode[]` |  |  |
| `transitions` | `MermaidStateTransition[]` |  |  |
| `direction?` | `string` |  |  |
| `notes` | `Array<{ position: string; target: string; text: string }>` |  |  |

### `MermaidStateNode`

```ts
interface MermaidStateNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `label` | `string` |  |  |
| `kind` | `StateKind` |  |  |
| `parent?` | `string` |  | Composite parent id, when nested. For a region's children, the REGION id. |
| `composite?` | `boolean` |  | True when this state has its own `{ … }` body. |
| `concurrent?` | `boolean` |  | Composite whose body is split by `--` into concurrent regions. |
| `region?` | `boolean` |  | A synthetic orthogonal region of a `concurrent` composite. Not a state the author wrote — it exists so each region owns its own children and `[*]`, and it is re-emitted as a `--` separator, never as a nested state. |
| `direction?` | `string` |  | `direction` declared INSIDE this composite. Mermaid scopes it to the composite; hoisting it onto the diagram re-exported it at top level and silently re-oriented the WHOLE diagram. |
| `cssClass?` | `string` |  | The `:::cssClass` style hook, captured by NAME. Not applied and not re-emitted (state-level styling is an open gap), but it has to be parsed: `[*] --> A:::hot` used to read as a state `A` LABELLED `::hot`, and export then wrote `[*] --> A : ::hot` — a transition label the author never typed. |

### `MermaidStateTransition`

```ts
interface MermaidStateTransition
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `from` | `string` |  |  |
| `to` | `string` |  |  |
| `label?` | `string` |  |  |

### `NodeDefinitionNode`

Also has every member of `ASTNode`, listed on its own entry.

Node definition: A[Label]

```ts
interface NodeDefinitionNode extends ASTNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'NodeDefinition'` |  |  |
| `id` | `string` |  |  |
| `label?` | `string` |  |  |
| `shape` | `NodeShape` |  |  |
| `style?` | `StyleProperties` |  |  |

### `ParseResult`

```ts
interface ParseResult
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `diagram` | `DiagramModel` |  | Generated diagram model |
| `ast` | `DiagramNode` |  | Abstract syntax tree |
| `tokens` | `Token[]` |  | Tokens from lexical analysis |
| `layoutSuggestion?` | `LayoutSuggestion` |  | Layout suggestion |
| `stats` | `{ nodeCount: number; linkCount: number; parseTime: number; }` |  | Parse statistics |

### `SourceLocation`

Source location in the original text

```ts
interface SourceLocation
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `start` | `Position` |  |  |
| `end` | `Position` |  |  |

### `StyleNode`

Also has every member of `ASTNode`, listed on its own entry.

Style definition: style A fill:#f9f,stroke:#333

```ts
interface StyleNode extends ASTNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'Style'` |  |  |
| `targetId` | `string` |  |  |
| `properties` | `StyleProperties` |  |  |

### `StyleProperties`

Style properties

```ts
interface StyleProperties
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `fill?` | `string` |  |  |
| `stroke?` | `string` |  |  |
| `strokeWidth?` | `number` |  |  |
| `strokeDasharray?` | `string` |  |  |
| `color?` | `string` |  |  |

### `SubgraphNode`

Also has every member of `ASTNode`, listed on its own entry.

Subgraph definition

```ts
interface SubgraphNode extends ASTNode
```

**Properties**

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `type` | `'Subgraph'` |  |  |
| `id?` | `string` |  |  |
| `label?` | `string` |  |  |
| `direction?` | `Direction` |  |  |
| `statements` | `StatementNode[]` |  |  |