@diagrammo/dgmo 0.4.1 → 0.4.3

package/dist/index.d.ts

@@ -39,6 +39,7 @@ declare function render(content: string, options?: {
     c4Level?: 'context' | 'containers' | 'components' | 'deployment';
     c4System?: string;
     c4Container?: string;
+    scenario?: string;
 }): Promise<string>;
 
 /**
@@ -263,6 +264,7 @@ interface ParsedSankeyLink {
     source: string;
     target: string;
     value: number;
+    color?: string;
     lineNumber: number;
 }
 interface ParsedFunction {
@@ -309,6 +311,7 @@ interface ParsedEChart {
     sizelabel?: string;
     showLabels?: boolean;
     categoryColors?: Record<string, string>;
+    nodeColors?: Record<string, string>;
     diagnostics: DgmoError[];
     error: string | null;
 }
@@ -548,8 +551,25 @@ declare function renderD3ForExport(content: string, theme: 'light' | 'dark' | 't
     c4Level?: 'context' | 'containers' | 'components' | 'deployment';
     c4System?: string;
     c4Container?: string;
+    scenario?: string;
 }): Promise<string>;
 
+/** A single entry inside a tag group: `Value(color)` */
+interface TagEntry {
+    value: string;
+    color: string;
+    lineNumber: number;
+}
+/** A tag group block: heading + entries */
+interface TagGroup {
+    name: string;
+    alias?: string;
+    entries: TagEntry[];
+    /** Value of the entry marked `default` (nodes without metadata get this) */
+    defaultValue?: string;
+    lineNumber: number;
+}
+
 /**
  * Participant types that can be declared via "Name is a type" syntax.
  */
@@ -568,6 +588,8 @@ interface SequenceParticipant {
     lineNumber: number;
     /** Explicit layout position override (0-based from left, negative from right) */
     position?: number;
+    /** Pipe-delimited tag metadata (e.g. `| role: Gateway`) */
+    metadata?: Record<string, string>;
 }
 /**
  * A message between two participants.
@@ -578,6 +600,8 @@ interface SequenceMessage {
     label: string;
     lineNumber: number;
     async?: boolean;
+    /** Pipe-delimited tag metadata (e.g. `| c: Caching`) */
+    metadata?: Record<string, string>;
 }
 /**
  * A conditional or loop block in the sequence diagram.
@@ -601,7 +625,6 @@ interface SequenceBlock {
 interface SequenceSection {
     kind: 'section';
     label: string;
-    color?: string;
     lineNumber: number;
 }
 /**
@@ -623,9 +646,10 @@ declare function isSequenceNote(el: SequenceElement): el is SequenceNote;
  */
 interface SequenceGroup {
     name: string;
-    color?: string;
     participantIds: string[];
     lineNumber: number;
+    /** Pipe-delimited tag metadata (e.g. `[Backend | t: Product]`) */
+    metadata?: Record<string, string>;
 }
 /**
  * Parsed result from a .dgmo sequence diagram.
@@ -638,6 +662,7 @@ interface ParsedSequenceDgmo {
     elements: SequenceElement[];
     groups: SequenceGroup[];
     sections: SequenceSection[];
+    tagGroups: TagGroup[];
     options: Record<string, string>;
     diagnostics: DgmoError[];
     error: string | null;
@@ -704,7 +729,7 @@ declare function buildMermaidQuadrant(parsed: ParsedQuadrant, options?: {
     mutedTextColor?: string;
 }): string;
 
-type GraphShape = 'terminal' | 'process' | 'decision' | 'io' | 'subroutine' | 'document';
+type GraphShape = 'terminal' | 'process' | 'decision' | 'io' | 'subroutine' | 'document' | 'state' | 'pseudostate';
 type GraphDirection = 'TB' | 'LR';
 interface GraphNode {
     id: string;
@@ -730,7 +755,7 @@ interface GraphGroup {
 }
 
 interface ParsedGraph {
-    type: 'flowchart';
+    type: 'flowchart' | 'state';
     title?: string;
     titleLineNumber?: number;
     direction: GraphDirection;
@@ -750,6 +775,61 @@ declare function parseFlowchart(content: string, palette?: PaletteColors): Parse
  */
 declare function looksLikeFlowchart(content: string): boolean;
 
+declare function parseState(content: string, palette?: PaletteColors): ParsedGraph;
+/**
+ * Detect if content looks like a state diagram (without explicit `chart: state` header).
+ * Only matches if `[*]` token is present — too ambiguous to infer from bare names alone.
+ */
+declare function looksLikeState(content: string): boolean;
+
+interface LayoutNode {
+    id: string;
+    label: string;
+    shape: GraphShape;
+    color?: string;
+    group?: string;
+    lineNumber: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface LayoutEdge {
+    source: string;
+    target: string;
+    points: {
+        x: number;
+        y: number;
+    }[];
+    label?: string;
+    color?: string;
+    lineNumber: number;
+}
+interface LayoutGroup {
+    id: string;
+    label: string;
+    color?: string;
+    lineNumber: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface LayoutResult {
+    nodes: LayoutNode[];
+    edges: LayoutEdge[];
+    groups: LayoutGroup[];
+    width: number;
+    height: number;
+}
+declare function layoutGraph(graph: ParsedGraph): LayoutResult;
+
+declare function renderState(container: HTMLDivElement, graph: ParsedGraph, layout: LayoutResult, palette: PaletteColors, isDark: boolean, onClickItem?: (lineNumber: number) => void, exportDims?: {
+    width?: number;
+    height?: number;
+}): void;
+declare function renderStateForExport(content: string, theme: 'light' | 'dark' | 'transparent', palette: PaletteColors): string;
+
 type ClassModifier = 'abstract' | 'interface' | 'enum';
 type MemberVisibility = 'public' | 'private' | 'protected';
 type RelationshipType = 'extends' | 'implements' | 'composes' | 'aggregates' | 'depends' | 'associates';
@@ -911,22 +991,6 @@ declare function renderERDiagram(container: HTMLDivElement, parsed: ParsedERDiag
 }): void;
 declare function renderERDiagramForExport(content: string, theme: 'light' | 'dark' | 'transparent', palette: PaletteColors): string;
 
-/** A single entry inside a tag group: `Value(color)` */
-interface TagEntry {
-    value: string;
-    color: string;
-    lineNumber: number;
-}
-/** A tag group block: heading + entries */
-interface TagGroup {
-    name: string;
-    alias?: string;
-    entries: TagEntry[];
-    /** Value of the entry marked `default` (nodes without metadata get this) */
-    defaultValue?: string;
-    lineNumber: number;
-}
-
 interface InlineSpan {
     text: string;
     bold?: boolean;
@@ -1025,7 +1089,7 @@ interface OrgLayoutResult {
     width: number;
     height: number;
 }
-declare function layoutOrg(parsed: ParsedOrg, hiddenCounts?: Map<string, number>, activeTagGroup?: string | null, hiddenAttributes?: Set<string>): OrgLayoutResult;
+declare function layoutOrg(parsed: ParsedOrg, hiddenCounts?: Map<string, number>, activeTagGroup?: string | null, hiddenAttributes?: Set<string>, expandAllLegend?: boolean): OrgLayoutResult;
 
 declare function renderOrg(container: HTMLDivElement, parsed: ParsedOrg, layout: OrgLayoutResult, palette: PaletteColors, isDark: boolean, onClickItem?: (lineNumber: number) => void, exportDims?: {
     width?: number;
@@ -1354,48 +1418,68 @@ declare function renderInitiativeStatus(container: HTMLDivElement, parsed: Parse
 }): void;
 declare function renderInitiativeStatusForExport(content: string, theme: 'light' | 'dark' | 'transparent', palette: PaletteColors): string;
 
-interface CollapsedOrgResult {
-    /** ParsedOrg with collapsed subtrees pruned (deep-cloned, never mutates original) */
-    parsed: ParsedOrg;
-    /** nodeId → count of hidden descendants */
-    hiddenCounts: Map<string, number>;
+interface SitemapNode {
+    id: string;
+    label: string;
+    metadata: Record<string, string>;
+    children: SitemapNode[];
+    parentId: string | null;
+    /** True for [Group Name] container nodes */
+    isContainer: boolean;
+    lineNumber: number;
+    color?: string;
 }
-declare function collapseOrgTree(original: ParsedOrg, collapsedIds: Set<string>): CollapsedOrgResult;
-
-/**
- * Async or sync file reader. Receives an absolute path, returns content.
- * Throwing means "file not found".
- */
-type ReadFileFn = (path: string) => string | Promise<string>;
-interface ResolveImportsResult {
-    content: string;
+interface SitemapEdge {
+    sourceId: string;
+    targetId: string;
+    label?: string;
+    color?: string;
+    lineNumber: number;
+}
+type SitemapDirection = 'TB' | 'LR';
+interface ParsedSitemap {
+    title: string | null;
+    titleLineNumber: number | null;
+    direction: SitemapDirection;
+    /** Top-level nodes (roots of the hierarchy) */
+    roots: SitemapNode[];
+    /** All cross-link edges */
+    edges: SitemapEdge[];
+    tagGroups: TagGroup[];
+    options: Record<string, string>;
     diagnostics: DgmoError[];
+    error: string | null;
 }
+
 /**
- * Pre-processes org chart content, resolving `tags:` and `import:` directives.
- *
- * @param content   - Raw .dgmo file content
- * @param filePath  - Absolute path of the file (for relative path resolution)
- * @param readFileFn - Function to read files (sync or async)
- * @returns Merged content with all imports resolved + diagnostics
+ * Returns true if content looks like a sitemap diagram.
+ * Heuristic: has `->` arrows AND `[Group]` containers but does NOT have
+ * flowchart shape delimiters ((...), <...>, /.../) adjacent to arrows.
  */
-declare function resolveOrgImports(content: string, filePath: string, readFileFn: ReadFileFn): Promise<ResolveImportsResult>;
+declare function looksLikeSitemap(content: string): boolean;
+declare function parseSitemap(content: string, palette?: PaletteColors): ParsedSitemap;
 
-interface LayoutNode {
+interface SitemapLayoutNode {
     id: string;
     label: string;
-    shape: GraphShape;
-    color?: string;
-    group?: string;
+    metadata: Record<string, string>;
+    /** Original (unfiltered) metadata for tag-based coloring and hover dimming */
+    tagMetadata: Record<string, string>;
+    isContainer: boolean;
     lineNumber: number;
+    color?: string;
     x: number;
     y: number;
     width: number;
     height: number;
+    /** Count of hidden descendants when collapsed */
+    hiddenCount?: number;
+    /** True if node has children (expanded or collapsed) — drives toggle UI */
+    hasChildren?: boolean;
 }
-interface LayoutEdge {
-    source: string;
-    target: string;
+interface SitemapLayoutEdge {
+    sourceId: string;
+    targetId: string;
     points: {
         x: number;
         y: number;
@@ -1404,23 +1488,377 @@ interface LayoutEdge {
     color?: string;
     lineNumber: number;
 }
-interface LayoutGroup {
+interface SitemapContainerBounds {
+    nodeId: string;
+    label: string;
+    lineNumber: number;
+    color?: string;
+    metadata: Record<string, string>;
+    /** Original (unfiltered) metadata for tag-based coloring and hover dimming */
+    tagMetadata: Record<string, string>;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    labelHeight: number;
+    /** Count of hidden descendants when collapsed */
+    hiddenCount?: number;
+    /** True if container has children (expanded or collapsed) */
+    hasChildren?: boolean;
+}
+interface SitemapLegendEntry {
+    value: string;
+    color: string;
+}
+interface SitemapLegendGroup {
+    name: string;
+    alias?: string;
+    entries: SitemapLegendEntry[];
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    minifiedWidth: number;
+    minifiedHeight: number;
+}
+interface SitemapLayoutResult {
+    nodes: SitemapLayoutNode[];
+    edges: SitemapLayoutEdge[];
+    containers: SitemapContainerBounds[];
+    legend: SitemapLegendGroup[];
+    width: number;
+    height: number;
+}
+declare function layoutSitemap(parsed: ParsedSitemap, hiddenCounts?: Map<string, number>, activeTagGroup?: string | null, hiddenAttributes?: Set<string>, expandAllLegend?: boolean): SitemapLayoutResult;
+
+declare function renderSitemap(container: HTMLDivElement, parsed: ParsedSitemap, layout: SitemapLayoutResult, palette: PaletteColors, isDark: boolean, onClickItem?: (lineNumber: number) => void, exportDims?: {
+    width?: number;
+    height?: number;
+}, activeTagGroup?: string | null, hiddenAttributes?: Set<string>): void;
+declare function renderSitemapForExport(content: string, theme: 'light' | 'dark' | 'transparent', palette?: PaletteColors): Promise<string>;
+
+interface CollapsedSitemapResult {
+    /** ParsedSitemap with collapsed subtrees pruned (deep-cloned, never mutates original) */
+    parsed: ParsedSitemap;
+    /** nodeId → count of hidden descendants */
+    hiddenCounts: Map<string, number>;
+}
+declare function collapseSitemapTree(original: ParsedSitemap, collapsedIds: Set<string>): CollapsedSitemapResult;
+
+/** Namespaced behavior property keys recognized by the parser. */
+type InfraBehaviorKey = 'cache-hit' | 'firewall-block' | 'ratelimit-rps' | 'latency-ms' | 'uptime' | 'instances' | 'max-rps' | 'cb-error-threshold' | 'cb-latency-threshold-ms' | 'concurrency' | 'duration-ms' | 'cold-start-ms' | 'buffer' | 'drain-rate' | 'retention-hours' | 'partitions';
+/** All recognized property keys (behavior + structural). */
+declare const INFRA_BEHAVIOR_KEYS: Set<string>;
+interface InfraProperty {
+    key: string;
+    value: string | number;
+    lineNumber: number;
+}
+interface InfraNode {
     id: string;
     label: string;
+    properties: InfraProperty[];
+    groupId: string | null;
+    tags: Record<string, string>;
+    isEdge: boolean;
+    lineNumber: number;
+}
+interface InfraEdge {
+    sourceId: string;
+    targetId: string;
+    label: string;
+    split: number | null;
+    lineNumber: number;
+}
+interface InfraGroup {
+    id: string;
+    label: string;
+    /** Number of instances (or auto-scaling range "N-M") of this group as a unit. */
+    instances?: number | string;
+    /** Whether this group should be collapsed by default in the source. */
+    collapsed?: boolean;
+    lineNumber: number;
+}
+interface InfraTagValue {
+    name: string;
     color?: string;
+}
+interface InfraTagGroup {
+    name: string;
+    alias: string | null;
+    values: InfraTagValue[];
+    /** Value of the entry marked `default` (nodes without this tag get it automatically). */
+    defaultValue?: string;
+    lineNumber: number;
+}
+interface InfraScenario {
+    name: string;
+    /** Node property overrides: nodeId -> { key: value } */
+    overrides: Record<string, Record<string, string | number>>;
+    lineNumber: number;
+}
+interface ParsedInfra {
+    type: 'infra';
+    title: string | null;
+    titleLineNumber: number | null;
+    direction: 'LR' | 'TB';
+    nodes: InfraNode[];
+    edges: InfraEdge[];
+    groups: InfraGroup[];
+    tagGroups: InfraTagGroup[];
+    scenarios: InfraScenario[];
+    options: Record<string, string>;
+    diagnostics: DgmoError[];
+    error: string | null;
+}
+interface InfraComputeParams {
+    rps?: number;
+    instanceOverrides?: Record<string, number>;
+    scenario?: InfraScenario | null;
+    /** Per-node property overrides: nodeId -> { propertyKey: numericValue }.
+     *  Applied after scenario overrides. Lets sliders adjust cache-hit, etc. */
+    propertyOverrides?: Record<string, Record<string, number>>;
+    /** Set of group IDs that should be treated as collapsed (virtual nodes). */
+    collapsedGroups?: Set<string>;
+}
+type InfraCbState = 'closed' | 'open' | 'half-open';
+interface ComputedInfraNode {
+    id: string;
+    label: string;
+    groupId: string | null;
+    isEdge: boolean;
+    computedRps: number;
+    overloaded: boolean;
+    /** True when inbound RPS exceeds the node's ratelimit-rps and traffic is being shed. */
+    rateLimited: boolean;
+    /** Cumulative latency from edge to this node (ms). */
+    computedLatencyMs: number;
+    /** Latency percentiles from this node through all downstream paths (ms). */
+    computedLatencyPercentiles: InfraLatencyPercentiles;
+    /** Component uptime (product of uptimes along path, 0-1). */
+    computedUptime: number;
+    /** Local availability at this node (0-1), factoring in uptime, overload shed, and rate-limit reject. */
+    computedAvailability: number;
+    /** Availability percentiles through all downstream paths from this node (0-1 fractions). */
+    computedAvailabilityPercentiles: InfraAvailabilityPercentiles;
+    /** Circuit breaker state. */
+    computedCbState: InfraCbState;
+    /** Computed instance count for auto-scaling (min-max) ranges. */
+    computedInstances: number;
+    /** For serverless nodes: estimated concurrent invocations (Little's Law: RPS × duration_ms / 1000). */
+    computedConcurrentInvocations: number;
+    /** For collapsed group virtual nodes: worst health state of any child.
+     *  'overloaded' > 'warning' > 'normal'. Undefined for regular nodes. */
+    childHealthState?: 'normal' | 'warning' | 'overloaded';
+    /** Queue metrics — only present when buffer property exists. */
+    queueMetrics?: {
+        /** Messages per second filling the buffer (inbound - drain-rate, clamped to 0). */
+        fillRate: number;
+        /** Seconds until buffer overflow at sustained fill rate. Infinity if not filling. */
+        timeToOverflow: number;
+        /** Queue wait time in ms (pending_messages / drain_rate * 1000). */
+        waitTimeMs: number;
+    };
+    properties: InfraProperty[];
+    tags: Record<string, string>;
+    lineNumber: number;
+}
+interface ComputedInfraEdge {
+    sourceId: string;
+    targetId: string;
+    label: string;
+    computedRps: number;
+    split: number;
+    lineNumber: number;
+}
+interface InfraDiagnostic {
+    type: 'SPLIT_SUM' | 'CYCLE' | 'OVERLOAD' | 'RATE_LIMITED' | 'ORPHAN' | 'SYNTAX' | 'UPTIME';
+    line: number;
+    message: string;
+}
+interface InfraLatencyPercentiles {
+    p50: number;
+    p90: number;
+    p99: number;
+}
+interface InfraAvailabilityPercentiles {
+    p50: number;
+    p90: number;
+    p99: number;
+}
+interface ComputedInfraModel {
+    nodes: ComputedInfraNode[];
+    edges: ComputedInfraEdge[];
+    groups: InfraGroup[];
+    tagGroups: InfraTagGroup[];
+    title: string | null;
+    direction: 'LR' | 'TB';
+    /** Diagram-level options (e.g., default-latency-ms, default-uptime). */
+    options: Record<string, string>;
+    /** Latency percentiles at the edge entry point (weighted by traffic probability). */
+    edgeLatency: InfraLatencyPercentiles;
+    /** System uptime at edge (weighted average across all paths). */
+    systemUptime: number;
+    /** System availability at edge (weighted average of compound availability across all paths). */
+    systemAvailability: number;
+    diagnostics: InfraDiagnostic[];
+}
+
+declare function parseInfra(content: string): ParsedInfra;
+
+declare function computeInfra(parsed: ParsedInfra, params?: InfraComputeParams): ComputedInfraModel;
+
+declare function validateInfra(parsed: ParsedInfra): InfraDiagnostic[];
+/**
+ * Validate computed model (post-computation warnings).
+ * Call after computeInfra() to get uptime/SLA warnings.
+ */
+declare function validateComputed(computed: ComputedInfraModel): InfraDiagnostic[];
+
+interface InfraRole {
+    name: string;
+    color: string;
+}
+/**
+ * Infer roles from a component's properties.
+ * A component can have multiple roles (e.g., Cache + Rate Limiter).
+ */
+declare function inferRoles(properties: InfraProperty[]): InfraRole[];
+/**
+ * Collect all unique roles present in the diagram (for legend).
+ */
+declare function collectDiagramRoles(allProperties: InfraProperty[][]): InfraRole[];
+
+interface InfraLayoutNode {
+    id: string;
+    label: string;
     x: number;
     y: number;
     width: number;
     height: number;
+    computedRps: number;
+    overloaded: boolean;
+    rateLimited: boolean;
+    isEdge: boolean;
+    groupId: string | null;
+    computedLatencyMs: number;
+    computedLatencyPercentiles: ComputedInfraNode['computedLatencyPercentiles'];
+    computedUptime: number;
+    computedAvailability: number;
+    computedAvailabilityPercentiles: ComputedInfraNode['computedAvailabilityPercentiles'];
+    computedInstances: number;
+    computedConcurrentInvocations: number;
+    computedCbState: ComputedInfraNode['computedCbState'];
+    childHealthState?: ComputedInfraNode['childHealthState'];
+    properties: ComputedInfraNode['properties'];
+    queueMetrics?: ComputedInfraNode['queueMetrics'];
+    tags: Record<string, string>;
+    lineNumber: number;
 }
-interface LayoutResult {
-    nodes: LayoutNode[];
-    edges: LayoutEdge[];
-    groups: LayoutGroup[];
+interface InfraLayoutEdge {
+    sourceId: string;
+    targetId: string;
+    label: string;
+    computedRps: number;
+    split: number;
+    points: {
+        x: number;
+        y: number;
+    }[];
+    lineNumber: number;
+}
+interface InfraLayoutGroup {
+    id: string;
+    label: string;
+    x: number;
+    y: number;
     width: number;
     height: number;
+    instances?: number | string;
+    lineNumber: number;
 }
-declare function layoutGraph(graph: ParsedGraph): LayoutResult;
+interface InfraLayoutResult {
+    nodes: InfraLayoutNode[];
+    edges: InfraLayoutEdge[];
+    groups: InfraLayoutGroup[];
+    /** Diagram-level options (e.g., default-latency-ms, default-uptime). */
+    options: Record<string, string>;
+    width: number;
+    height: number;
+}
+declare function layoutInfra(computed: ComputedInfraModel, selectedNodeId?: string | null): InfraLayoutResult;
+
+interface InfraLegendEntry {
+    value: string;
+    color: string;
+    /** For role: kebab-case role name. For tag: lowercase tag value. */
+    key: string;
+}
+interface InfraLegendGroup {
+    name: string;
+    type: 'role' | 'tag';
+    /** For tag groups: the key used in data-tag-* attributes (alias or name). */
+    tagKey?: string;
+    entries: InfraLegendEntry[];
+    width: number;
+    minifiedWidth: number;
+}
+/** Build legend groups from roles + tags. */
+declare function computeInfraLegendGroups(nodes: InfraLayoutNode[], tagGroups: InfraTagGroup[], palette: PaletteColors): InfraLegendGroup[];
+interface InfraPlaybackState {
+    expanded: boolean;
+    paused: boolean;
+    speed: number;
+    speedOptions: readonly number[];
+}
+declare function renderInfra(container: HTMLDivElement, layout: InfraLayoutResult, palette: PaletteColors, isDark: boolean, title: string | null, titleLineNumber: number | null, tagGroups?: InfraTagGroup[], activeGroup?: string | null, animate?: boolean, playback?: InfraPlaybackState | null, selectedNodeId?: string | null, exportMode?: boolean): void;
+declare function parseAndLayoutInfra(content: string): {
+    parsed: ParsedInfra;
+    computed: null;
+    layout: null;
+} | {
+    parsed: ParsedInfra;
+    computed: ComputedInfraModel;
+    layout: InfraLayoutResult;
+};
+
+interface CollapsedOrgResult {
+    /** ParsedOrg with collapsed subtrees pruned (deep-cloned, never mutates original) */
+    parsed: ParsedOrg;
+    /** nodeId → count of hidden descendants */
+    hiddenCounts: Map<string, number>;
+}
+declare function collapseOrgTree(original: ParsedOrg, collapsedIds: Set<string>): CollapsedOrgResult;
+
+/**
+ * Async or sync file reader. Receives an absolute path, returns content.
+ * Throwing means "file not found".
+ */
+type ReadFileFn = (path: string) => string | Promise<string>;
+/** Tracks the original source file and line for an imported line. */
+interface ImportSource {
+    /** Absolute path of the file this line originates from */
+    filePath: string;
+    /** 1-based line number in the original (pre-resolution) source file */
+    sourceLine: number;
+}
+interface ResolveImportsResult {
+    content: string;
+    diagnostics: DgmoError[];
+    /** resolvedLine (1-based index) → originalLine (1-based) or null for inserted lines */
+    lineMap: (number | null)[];
+    /** resolvedLine (1-based index) → import source info or null for non-imported lines */
+    importSourceMap: (ImportSource | null)[];
+}
+/**
+ * Pre-processes org chart content, resolving `tags:` and `import:` directives.
+ *
+ * @param content   - Raw .dgmo file content
+ * @param filePath  - Absolute path of the file (for relative path resolution)
+ * @param readFileFn - Function to read files (sync or async)
+ * @returns Merged content with all imports resolved + diagnostics
+ */
+declare function resolveOrgImports(content: string, filePath: string, readFileFn: ReadFileFn): Promise<ResolveImportsResult>;
 
 declare function renderFlowchart(container: HTMLDivElement, graph: ParsedGraph, layout: LayoutResult, palette: PaletteColors, isDark: boolean, onClickItem?: (lineNumber: number) => void, exportDims?: {
     width?: number;
@@ -1436,6 +1874,7 @@ interface SequenceRenderOptions {
     collapsedSections?: Set<number>;
     expandedNoteLines?: Set<number>;
     exportWidth?: number;
+    activeTagGroup?: string | null;
 }
 /**
  * Group messages by the top-level section that precedes them.
@@ -1476,9 +1915,14 @@ declare function computeActivations(steps: RenderStep[]): Activation[];
 declare function applyPositionOverrides(participants: SequenceParticipant[]): SequenceParticipant[];
 /**
  * Reorder participants so that members of the same group are adjacent.
- * Groups appear in declaration order, followed by ungrouped participants.
+ * Groups are positioned at the point where their first member would naturally
+ * appear based on message order (first-occurrence positioning). This prevents
+ * groups declared at the top of the file from being placed before participants
+ * that appear in messages earlier.
+ *
+ * Explicit `position` overrides are handled separately by `applyPositionOverrides`.
  */
-declare function applyGroupOrdering(participants: SequenceParticipant[], groups: SequenceGroup[]): SequenceParticipant[];
+declare function applyGroupOrdering(participants: SequenceParticipant[], groups: SequenceGroup[], messages?: SequenceMessage[]): SequenceParticipant[];
 /**
  * Render a sequence diagram into the given container element.
  */
@@ -1567,4 +2011,4 @@ declare function decodeDiagramUrl(hash: string): DecodedDiagramUrl;
  */
 declare function injectBranding(svgHtml: string, mutedColor: string): string;
 
-export { type Activation, type ArcLink, type ArcNodeGroup, type C4ArrowType, type C4DeploymentNode, type C4Element, type C4ElementType, type C4Group, type C4LayoutBoundary, type C4LayoutEdge, type C4LayoutNode, type C4LayoutResult, type C4LegendEntry, type C4LegendGroup, type C4Relationship, type C4Shape, type C4TagEntry, type C4TagGroup, type ChartDataPoint, type ChartType, type ClassLayoutEdge, type ClassLayoutNode, type ClassLayoutResult, type ClassMember, type ClassModifier, type ClassNode, type ClassRelationship, type CollapsedOrgResult, type ContextRelationship, type D3ChartType, type D3ExportDimensions, DGMO_CHART_TYPE_MAP, type DecodedDiagramUrl, type DgmoError, type DgmoFramework, type DgmoSeverity, type DiagramViewState, type EChartsChartType, type ERCardinality, type ERColumn, type ERConstraint, type ERLayoutEdge, type ERLayoutNode, type ERLayoutResult, type ERRelationship, type ERTable, type ElseIfBranch, type EncodeDiagramUrlOptions, type EncodeDiagramUrlResult, type GraphDirection, type GraphEdge, type GraphGroup, type GraphNode, type GraphShape, type ISEdge, type ISGroup, type ISLayoutEdge, type ISLayoutGroup, type ISLayoutNode, type ISLayoutResult, type ISNode, type InitiativeStatus, type InlineSpan, type KanbanCard, type KanbanColumn, type KanbanTagEntry, type KanbanTagGroup, type LayoutEdge, type LayoutGroup, type LayoutNode, type LayoutResult, type MemberVisibility, type OrgContainerBounds, type OrgLayoutEdge, type OrgLayoutNode, type OrgLayoutResult, type OrgNode, type OrgTagEntry, type OrgTagGroup, type PaletteColors, type PaletteConfig, type ParsedC4, type ParsedChart, type ParsedClassDiagram, type ParsedD3, type ParsedEChart, type ParsedERDiagram, type ParsedGraph, type ParsedInitiativeStatus, type ParsedKanban, type ParsedOrg, type ParsedQuadrant, type ParsedSequenceDgmo, type ParticipantType, RULE_COUNT, type ReadFileFn, type RelationshipType, type RenderStep, type ResolveImportsResult, STANDARD_CHART_TYPES, type SectionMessageGroup, type SequenceBlock, type SequenceElement, type SequenceGroup, type SequenceMessage, type SequenceNote, type SequenceParticipant, type SequenceRenderOptions, type SequenceSection, type TagEntry, type TagGroup, addDurationToDate, applyGroupOrdering, applyPositionOverrides, boldPalette, buildEChartsOption, buildEChartsOptionFromChart, buildMermaidQuadrant, buildMermaidThemeVars, buildNoteMessageMap, buildRenderSequence, buildThemeCSS, catppuccinPalette, collapseOrgTree, colorNames, computeActivations, computeCardArchive, computeCardMove, computeTimeTicks, contrastText, decodeDiagramUrl, encodeDiagramUrl, formatDateLabel, formatDgmoError, getAvailablePalettes, getDgmoFramework, getPalette, getSeriesColors, groupMessagesBySection, gruvboxPalette, hexToHSL, hexToHSLString, hslToHex, inferParticipantType, injectBranding, isArchiveColumn, isSequenceBlock, isSequenceNote, isValidHex, layoutC4Components, layoutC4Containers, layoutC4Context, layoutC4Deployment, layoutClassDiagram, layoutERDiagram, layoutGraph, layoutInitiativeStatus, layoutOrg, looksLikeClassDiagram, looksLikeERDiagram, looksLikeFlowchart, looksLikeInitiativeStatus, looksLikeSequence, makeDgmoError, mute, nord, nordPalette, oneDarkPalette, orderArcNodes, parseC4, parseChart, parseClassDiagram, parseD3, parseDgmo, parseDgmoChartType, parseEChart, parseERDiagram, parseFlowchart, parseInitiativeStatus, parseInlineMarkdown, parseKanban, parseOrg, parseQuadrant, parseSequenceDgmo, parseTimelineDate, registerPalette, render, renderArcDiagram, renderC4ComponentsForExport, renderC4Containers, renderC4ContainersForExport, renderC4Context, renderC4ContextForExport, renderC4Deployment, renderC4DeploymentForExport, renderClassDiagram, renderClassDiagramForExport, renderD3ForExport, renderEChartsForExport, renderERDiagram, renderERDiagramForExport, renderFlowchart, renderFlowchartForExport, renderInitiativeStatus, renderInitiativeStatusForExport, renderKanban, renderKanbanForExport, renderOrg, renderOrgForExport, renderQuadrant, renderSequenceDiagram, renderSlopeChart, renderTimeline, renderVenn, renderWordCloud, resolveColor, resolveOrgImports, rollUpContextRelationships, rosePinePalette, seriesColors, shade, solarizedPalette, tint, tokyoNightPalette, truncateBareUrl };
+export { type Activation, type ArcLink, type ArcNodeGroup, type C4ArrowType, type C4DeploymentNode, type C4Element, type C4ElementType, type C4Group, type C4LayoutBoundary, type C4LayoutEdge, type C4LayoutNode, type C4LayoutResult, type C4LegendEntry, type C4LegendGroup, type C4Relationship, type C4Shape, type C4TagEntry, type C4TagGroup, type ChartDataPoint, type ChartType, type ClassLayoutEdge, type ClassLayoutNode, type ClassLayoutResult, type ClassMember, type ClassModifier, type ClassNode, type ClassRelationship, type CollapsedOrgResult, type CollapsedSitemapResult, type ComputedInfraEdge, type ComputedInfraModel, type ComputedInfraNode, type ContextRelationship, type D3ChartType, type D3ExportDimensions, DGMO_CHART_TYPE_MAP, type DecodedDiagramUrl, type DgmoError, type DgmoFramework, type DgmoSeverity, type DiagramViewState, type EChartsChartType, type ERCardinality, type ERColumn, type ERConstraint, type ERLayoutEdge, type ERLayoutNode, type ERLayoutResult, type ERRelationship, type ERTable, type ElseIfBranch, type EncodeDiagramUrlOptions, type EncodeDiagramUrlResult, type GraphDirection, type GraphEdge, type GraphGroup, type GraphNode, type GraphShape, INFRA_BEHAVIOR_KEYS, type ISEdge, type ISGroup, type ISLayoutEdge, type ISLayoutGroup, type ISLayoutNode, type ISLayoutResult, type ISNode, type ImportSource, type InfraAvailabilityPercentiles, type InfraBehaviorKey, type InfraCbState, type InfraComputeParams, type InfraDiagnostic, type InfraEdge, type InfraGroup, type InfraLatencyPercentiles, type InfraLayoutEdge, type InfraLayoutGroup, type InfraLayoutNode, type InfraLayoutResult, type InfraLegendGroup, type InfraNode, type InfraPlaybackState, type InfraProperty, type InfraRole, type InfraScenario, type InfraTagGroup, type InitiativeStatus, type InlineSpan, type KanbanCard, type KanbanColumn, type KanbanTagEntry, type KanbanTagGroup, type LayoutEdge, type LayoutGroup, type LayoutNode, type LayoutResult, type MemberVisibility, type OrgContainerBounds, type OrgLayoutEdge, type OrgLayoutNode, type OrgLayoutResult, type OrgNode, type OrgTagEntry, type OrgTagGroup, type PaletteColors, type PaletteConfig, type ParsedC4, type ParsedChart, type ParsedClassDiagram, type ParsedD3, type ParsedEChart, type ParsedERDiagram, type ParsedGraph, type ParsedInfra, type ParsedInitiativeStatus, type ParsedKanban, type ParsedOrg, type ParsedQuadrant, type ParsedSequenceDgmo, type ParsedSitemap, type ParticipantType, RULE_COUNT, type ReadFileFn, type RelationshipType, type RenderStep, type ResolveImportsResult, STANDARD_CHART_TYPES, type SectionMessageGroup, type SequenceBlock, type SequenceElement, type SequenceGroup, type SequenceMessage, type SequenceNote, type SequenceParticipant, type SequenceRenderOptions, type SequenceSection, type SitemapContainerBounds, type SitemapDirection, type SitemapEdge, type SitemapLayoutEdge, type SitemapLayoutNode, type SitemapLayoutResult, type SitemapLegendEntry, type SitemapLegendGroup, type SitemapNode, type TagEntry, type TagGroup, addDurationToDate, applyGroupOrdering, applyPositionOverrides, boldPalette, buildEChartsOption, buildEChartsOptionFromChart, buildMermaidQuadrant, buildMermaidThemeVars, buildNoteMessageMap, buildRenderSequence, buildThemeCSS, catppuccinPalette, collapseOrgTree, collapseSitemapTree, collectDiagramRoles, colorNames, computeActivations, computeCardArchive, computeCardMove, computeInfra, computeInfraLegendGroups, computeTimeTicks, contrastText, decodeDiagramUrl, encodeDiagramUrl, formatDateLabel, formatDgmoError, getAvailablePalettes, getDgmoFramework, getPalette, getSeriesColors, groupMessagesBySection, gruvboxPalette, hexToHSL, hexToHSLString, hslToHex, inferParticipantType, inferRoles, injectBranding, isArchiveColumn, isSequenceBlock, isSequenceNote, isValidHex, layoutC4Components, layoutC4Containers, layoutC4Context, layoutC4Deployment, layoutClassDiagram, layoutERDiagram, layoutGraph, layoutInfra, layoutInitiativeStatus, layoutOrg, layoutSitemap, looksLikeClassDiagram, looksLikeERDiagram, looksLikeFlowchart, looksLikeInitiativeStatus, looksLikeSequence, looksLikeSitemap, looksLikeState, makeDgmoError, mute, nord, nordPalette, oneDarkPalette, orderArcNodes, parseAndLayoutInfra, parseC4, parseChart, parseClassDiagram, parseD3, parseDgmo, parseDgmoChartType, parseEChart, parseERDiagram, parseFlowchart, parseInfra, parseInitiativeStatus, parseInlineMarkdown, parseKanban, parseOrg, parseQuadrant, parseSequenceDgmo, parseSitemap, parseState, parseTimelineDate, registerPalette, render, renderArcDiagram, renderC4ComponentsForExport, renderC4Containers, renderC4ContainersForExport, renderC4Context, renderC4ContextForExport, renderC4Deployment, renderC4DeploymentForExport, renderClassDiagram, renderClassDiagramForExport, renderD3ForExport, renderEChartsForExport, renderERDiagram, renderERDiagramForExport, renderFlowchart, renderFlowchartForExport, renderInfra, renderInitiativeStatus, renderInitiativeStatusForExport, renderKanban, renderKanbanForExport, renderOrg, renderOrgForExport, renderQuadrant, renderSequenceDiagram, renderSitemap, renderSitemapForExport, renderSlopeChart, renderState, renderStateForExport, renderTimeline, renderVenn, renderWordCloud, resolveColor, resolveOrgImports, rollUpContextRelationships, rosePinePalette, seriesColors, shade, solarizedPalette, tint, tokyoNightPalette, truncateBareUrl, validateComputed, validateInfra };