@diagrammo/dgmo 0.4.2 → 0.4.3

package/docs/ai-integration.md

@@ -122,4 +122,4 @@ dgmo --chart-types --json         # List all chart types
 
 Run `dgmo --chart-types` for the full list, or see `docs/language-reference.md`.
 
-29 types: bar, line, area, pie, doughnut, radar, polar-area, bar-stacked, scatter, sankey, chord, function, heatmap, funnel, slope, wordcloud, arc, timeline, venn, quadrant, sequence, flowchart, class, er, org, kanban, c4, initiative-status.
+32 types: bar, line, area, pie, doughnut, radar, polar-area, bar-stacked, scatter, sankey, chord, function, heatmap, funnel, slope, wordcloud, arc, timeline, venn, quadrant, sequence, flowchart, state, class, er, org, kanban, c4, initiative-status, sitemap, infra.

package/docs/language-reference.md

@@ -203,6 +203,8 @@ Options: `columns` (required).
 
 ### sankey
 
+**Arrow syntax:**
+
 ```
 chart: sankey
 title: Resource Flow
@@ -213,7 +215,43 @@ Processing -> Output X: 350
 Processing -> Output Y: 150
 ```
 
-Data: `Source -> Target: value`
+**Indentation syntax:**
+
+```
+chart: sankey
+title: Resource Flow
+
+Source A
+  Processing: 300
+Source B
+  Processing: 200
+Processing
+  Output X: 350
+  Output Y: 150
+```
+
+Both syntaxes can be mixed in the same diagram.
+
+**Node colors** — `(color)` after a node name:
+
+```
+Revenue (green)
+  Costs (red): 600
+  Profit (blue): 400
+
+// or with arrows
+Revenue (green) -> Costs (red): 600
+```
+
+**Link colors** — `(color)` after the value:
+
+```
+Revenue
+  Costs: 600 (orange)
+
+// or with arrows
+Revenue -> Costs: 600 (orange)
+```
 
 ### chord
 
@@ -425,11 +463,47 @@ API -200 OK-> User
 - `note on Participant: text` — anchored
 - Multi-line: indent continuation lines under `note:`
 
-**Sections**: `== Section Title ==` or `== Section Title(color) ==`
+**Sections**: `== Section Title ==`
+
+**Groups**: `[Group Name]` or `[Group Name | key: value]` — visual grouping box around participants
+
+**Options**: `activations: off`, `collapse-notes: no`, `active-tag: GroupName`
+
+**Tag groups** — define color-coded metadata dimensions for interactive recoloring:
+
+```
+tag: Concern alias c
+  Caching(blue)
+  Auth(green)
+  BusinessLogic(purple) default
+```
 
-**Groups**: `## Group Name` — visual grouping box around messages
+- `tag: Name` declares a tag group; `alias x` adds a shorthand
+- Each entry: `Value(color)` — named color for that value
+- `default` on an entry applies it to untagged elements when the group is active
 
-**Options**: `activations: off`, `collapse-notes: no`
+**Pipe metadata** — attach tag values to participants, messages, and groups:
+
+```
+API is a service | concern: Caching, team: Platform
+User -login-> API | concern: Auth
+[Backend | concern: BusinessLogic]
+  OrderAPI
+  DB
+```
+
+- `| key: value` after participant declarations, message lines, or group headers
+- Multiple tags: `| key1: val1, key2: val2`
+- Aliases work: `| c: Caching` (if `alias c` was declared)
+
+**Tag resolution priority** (when a tag group is active):
+1. Explicit metadata on the participant
+2. Group propagation (participant inherits from its group)
+3. Receiver inheritance (all incoming tagged messages agree on same value)
+4. `default` entry value
+5. Neutral (no color)
+
+**Legend** — rendered automatically above participants when tag groups exist. The active group expands to show colored entry dots. Click a group pill to activate it (in the desktop app).
 
 ### flowchart
 
@@ -463,6 +537,55 @@ title: Decision Process
 
 Colors on nodes: `[Process(blue)]`
 
+### state
+
+Minimal example:
+
+```
+[*] -> Idle -> Active -> [*]
+```
+
+Full example:
+
+```
+chart: state
+title: Order Lifecycle
+direction: LR
+
+## Processing(blue)
+  Validating -valid-> Approved
+  Validating -invalid-> Rejected(red)
+
+[*] -> Pending -submit-> Validating
+Approved -ship-> Shipped -> [*]
+Rejected -> [*]
+Shipped -return-> Pending
+```
+
+**States**: bare text — `Idle`, `Active`, `Processing`. Optional color suffix: `Active(green)`.
+
+**Pseudostates**: `[*]` — rendered as a filled circle. Use for start and end points.
+
+**Transitions**: `->`, `-label->`, `-(color)->`, `-label(color)->`.
+
+**Chains**: `A -> B -> C` on a single line creates two transitions.
+
+**Indentation**: indented lines use the parent as implicit source:
+
+```
+Idle
+  -start-> Running
+  -configure-> Configuring
+```
+
+is equivalent to `Idle -start-> Running` and `Idle -configure-> Configuring`.
+
+**Groups**: `## GroupName` or `## GroupName(color)` — groups subsequent indented states visually.
+
+**Self-loops**: `Running -retry-> Running` — a state transitioning to itself.
+
+**Options**: `direction` (`TB` or `LR`), `title`, `color: off` (monochrome mode).
+
 ### class
 
 Minimal example:
@@ -528,12 +651,11 @@ Minimal example:
 users
   id: int [pk]
   name: varchar
+  1-* posts
 
 posts
   id: int [pk]
   user_id: int [fk]
-
-users 1--* posts : writes
 ```
 
 Full example:
@@ -546,6 +668,8 @@ users
   id: int [pk]
   email: varchar [unique]
   name: varchar
+  1-writes-* posts
+  ?-moderates-* categories
 
 posts
   id: int [pk]
@@ -557,20 +681,23 @@ posts
 categories
   id: int [pk]
   name: varchar [unique]
-
-users 1--* posts : writes
-categories 1--* posts : contains
-users ?--* categories : moderates
+  1-* posts
 ```
 
 **Columns**: `name: type [constraints]`. Constraints: `pk`, `fk`, `unique`, `nullable`. Multiple: `[fk, nullable]`.
 
-**Relationships** (symbolic cardinality):
-- `1--1` — one-to-one
-- `1--*` — one-to-many
-- `?--1` — zero-or-one to one
-- `?--*` — zero-or-more
-- Optional label: `table1 1--* table2 : description`
+**Relationships** — indented under the source table (preferred):
+- `1-* target` — one-to-many
+- `1-1 target` — one-to-one
+- `?-1 target` — zero-or-one to one
+- `?-* target` — zero-or-more
+- Labeled: `1-writes-* target` (label between dashes)
+
+Columns and relationships can be mixed under the same table. The parser distinguishes them by the leading cardinality character (`1`, `*`, `?`).
+
+**Flat relationships** — at indent 0 (also supported):
+- `table1 1--* table2` — one-to-many
+- `table1 1--* table2 : label` — with label
 
 ### c4
 
@@ -766,11 +893,203 @@ DBLayer | done
 
 **Groups**: `[Group Name]` for visual grouping.
 
+### sitemap
+
+Minimal example:
+
+```
+chart: sitemap
+
+Home
+  -about-> About
+  -blog-> Blog
+
+[Content]
+  About
+  Blog
+    -read-> Post
+  Post
+```
+
+Full example:
+
+```
+chart: sitemap
+title: SaaS Platform
+direction: TB
+
+tag: Auth
+  Public(green)
+  Required(blue)
+  Admin(red)
+
+tag: Type
+  Landing(purple)
+  Form(orange)
+  Content(cyan)
+
+Home
+  Auth: Public
+  Type: Landing
+  -pricing-> Pricing
+  -login-> Login
+  -docs-> Docs
+
+[Marketing]
+  Pricing
+    Auth: Public
+    Type: Content
+    -sign up-> Register
+
+  Docs
+    Auth: Public
+    Type: Content
+
+[Auth]
+  Login
+    Auth: Public
+    Type: Form
+    -success-> Dashboard
+    -forgot-> Reset Password
+
+  Register
+    Auth: Public
+    Type: Form
+    -success-> Dashboard
+
+  Reset Password
+    Auth: Public
+    Type: Form
+    -submitted-> Login
+
+[App]
+  Dashboard
+    Auth: Required
+    Type: Landing
+    -projects-> Projects
+    -settings-> Settings
+
+  Projects
+    Auth: Required
+    Type: Content
+
+  Settings
+    Auth: Required
+    Type: Form
+    -saved-> Dashboard
+```
+
+**Pages**: Plain labels at any indent level become page nodes.
+
+**Groups**: `[Group Name]` wraps indented children in a container.
+
+**Arrows**: `-label-> Target`, `-(color)-> Target`, `-label(color)-> Target` — cross-link between any pages.
+
+**Metadata**: `Key: Value` lines attach to the parent page (displayed as card rows).
+
+**Tag groups**: `tag: Name` with colored entries — same syntax as org charts.
+
+**Direction**: `direction: TB` (top-to-bottom, default) or `direction: LR` (left-to-right).
+
+**Collapsible groups**: Groups can be collapsed/expanded in the app — arrows to hidden pages re-terminate at the group boundary.
+
+### infra
+
+Minimal example:
+
+```
+chart: infra
+
+edge
+  rps: 1000
+  -> CDN
+
+CDN
+  cache-hit: 80%
+  -> API
+
+API
+  instances: 2
+  max-rps: 400
+  latency-ms: 30
+```
+
+Full example:
+
+```
+chart: infra
+title: Production Traffic Flow
+direction: LR
+
+tag: Team alias t
+  Backend(blue)
+  Platform(teal)
+
+edge
+  rps: 10000
+  -> CloudFront
+
+CloudFront | t: Platform
+  cache-hit: 80%
+  -> CloudArmor
+
+CloudArmor | t: Platform
+  firewall-block: 5%
+  -> ALB
+
+ALB | t: Platform
+  -/api-> [API Pods] | split: 60%
+  -/purchase-> [Commerce Pods] | split: 30%
+  -/static-> StaticServer | split: 10%
+
+[API Pods]
+  APIServer | t: Backend
+    instances: 3
+    max-rps: 500
+    latency-ms: 45
+    cb-error-threshold: 50%
+
+[Commerce Pods]
+  PurchaseMS
+    instances: 1-8
+    max-rps: 300
+    latency-ms: 120
+
+StaticServer | t: Platform
+  latency-ms: 5
+```
+
+**Entry point**: The `edge` block declares the external traffic source with `rps:` (requests per second). All downstream rps are computed automatically.
+
+**Components**: Bare labels at indent 0 define infrastructure components. Properties are indented below:
+- `cache-hit: N%` — percentage of traffic served from cache (reduces downstream flow)
+- `firewall-block: N%` — percentage of traffic blocked (reduces downstream flow)
+- `ratelimit-rps: N` — maximum rps allowed through (excess dropped)
+- `max-rps: N` — maximum rps capacity per instance
+- `instances: N` or `instances: N-M` — fixed or auto-scaling instance count
+- `latency-ms: N` — per-request latency in milliseconds
+- `cb-error-threshold: N%` — circuit breaker opens when overload exceeds this ratio
+- `cb-latency-threshold-ms: N` — circuit breaker opens when cumulative latency exceeds this
+
+**Connections**: `-> Target` (unlabeled), `-label-> Target` (labeled). Pipe metadata for splits: `-> Target | split: N%`.
+
+**Branching**: Multiple outbound connections with `split: N%` metadata. Splits must sum to 100%. Undeclared splits are evenly distributed from the remaining percentage.
+
+**Groups**: `[Group Name]` with indented children — rendered as dashed-border containers. Edges targeting a group route to all children.
+
+**Roles**: Inferred automatically from behavior properties — no type declarations needed. Components with `cache-hit` get a Cache role, `firewall-block` gets Firewall, etc. Roles appear as colored dots on nodes and in the legend.
+
+**Overload**: When computed rps exceeds `max-rps × instances`, the node turns red. Dynamic scaling (`instances: 1-8`) auto-scales within the range before overloading.
+
+**Direction**: `direction: LR` (left-to-right, default) or `direction: TB` (top-to-bottom).
+
+**Tag groups**: Same syntax as org/kanban/sitemap — `tag: Name alias x` with colored entries.
+
 ---
 
 ## Tag Groups
 
-Define reusable metadata categories for org charts, kanban boards, and C4 diagrams:
+Define reusable metadata categories for org charts, kanban boards, C4 diagrams, sitemaps, and infra charts:
 
 ```
 tag: Priority

package/docs/migration-sequence-color-to-tags.md

@@ -0,0 +1,98 @@
+# Migration Guide: Sequence Diagram Colors → Tags
+
+This guide covers migrating from inline `(color)` syntax to the tag system for sequence diagrams.
+
+## Why migrate?
+
+Inline `(color)` on sequence elements is static — every viewer sees the same fixed colors. Tags provide:
+
+- **Interactive recoloring** — click legend pills to switch between different color dimensions (e.g., "by team" vs "by concern")
+- **Multiple dimensions** — one diagram can carry team ownership, protocol type, and concern metadata simultaneously
+- **Receiver inheritance** — participants auto-inherit color from incoming tagged messages
+- **Legend** — auto-generated legend bar with clickable pills and colored entry dots
+
+## Before / After
+
+### Participants
+
+Before (static color):
+```
+API(blue)
+DB(green)
+```
+
+After (tag-driven):
+```
+tag: Role
+  Gateway(blue)
+  Storage(green)
+
+API is a service | role: Gateway
+DB is a database | role: Storage
+```
+
+### Messages
+
+Before (no color mechanism existed for messages):
+```
+User -login-> API
+```
+
+After (tag metadata on messages):
+```
+tag: Concern
+  Auth(green)
+
+User -login-> API | concern: Auth
+```
+
+### Groups
+
+Before (static color):
+```
+[Backend(teal)]
+  API
+  DB
+```
+
+After (tag-driven):
+```
+tag: Team
+  Product(teal)
+
+[Backend | team: Product]
+  API
+  DB
+```
+
+### Sections
+
+Sections (`== Title ==`) do not carry tag metadata. Continue using inline colors if needed:
+```
+== Authentication(green) ==
+```
+
+## Quick reference
+
+| Syntax | Purpose |
+|--------|---------|
+| `tag: Name alias x` | Declare a tag group with optional alias |
+| `Value(color)` | Tag entry with named color |
+| `Value(color) default` | Default entry for untagged elements |
+| `\| key: value` | Pipe metadata on participants, messages, groups |
+| `\| k1: v1, k2: v2` | Multiple tag values |
+| `active-tag: Name` | Activate a group for CLI/export rendering |
+
+## Activation
+
+In the desktop app, click legend pills to switch active tag groups interactively.
+
+For CLI or static export, add `active-tag: GroupName` to the diagram header:
+```
+chart: sequence
+active-tag: Concern
+
+tag: Concern alias c
+  Caching(blue)
+  Auth(green)
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "type": "module",

package/src/c4/renderer.ts

@@ -6,6 +6,7 @@ import * as d3Selection from 'd3-selection';
 import * as d3Shape from 'd3-shape';
 import { FONT_FAMILY } from '../fonts';
 import type { PaletteColors } from '../palettes';
+import { mix } from '../palettes/color-utils';
 import { renderInlineText } from '../utils/inline-markdown';
 import type { ParsedC4 } from './types';
 import type { C4Shape } from './types';
@@ -73,26 +74,6 @@ const LEGEND_CAPSULE_PAD = 4;
 // Color helpers
 // ============================================================
 
-function mix(a: string, b: string, pct: number): string {
-  const parse = (h: string) => {
-    const r = h.replace('#', '');
-    const f = r.length === 3 ? r[0] + r[0] + r[1] + r[1] + r[2] + r[2] : r;
-    return [
-      parseInt(f.substring(0, 2), 16),
-      parseInt(f.substring(2, 4), 16),
-      parseInt(f.substring(4, 6), 16),
-    ];
-  };
-  const [ar, ag, ab] = parse(a),
-    [br, bg, bb] = parse(b),
-    t = pct / 100;
-  const c = (x: number, y: number) =>
-    Math.round(x * t + y * (1 - t))
-      .toString(16)
-      .padStart(2, '0');
-  return `#${c(ar, br)}${c(ag, bg)}${c(ab, bb)}`;
-}
-
 function typeColor(
   type: 'person' | 'system' | 'container' | 'component',
   palette: PaletteColors,

package/src/class/renderer.ts

@@ -6,6 +6,7 @@ import * as d3Selection from 'd3-selection';
 import * as d3Shape from 'd3-shape';
 import { FONT_FAMILY } from '../fonts';
 import type { PaletteColors } from '../palettes';
+import { mix } from '../palettes/color-utils';
 import type { ParsedClassDiagram, ClassModifier, RelationshipType } from './types';
 import type { ClassLayoutResult, ClassLayoutNode, ClassLayoutEdge } from './layout';
 import { parseClassDiagram } from './parser';
@@ -30,17 +31,6 @@ const MEMBER_PADDING_X = 10;
 // Color helpers
 // ============================================================
 
-function mix(a: string, b: string, pct: number): string {
-  const parse = (h: string) => {
-    const r = h.replace('#', '');
-    const f = r.length === 3 ? r[0]+r[0]+r[1]+r[1]+r[2]+r[2] : r;
-    return [parseInt(f.substring(0,2),16), parseInt(f.substring(2,4),16), parseInt(f.substring(4,6),16)];
-  };
-  const [ar,ag,ab] = parse(a), [br,bg,bb] = parse(b), t = pct/100;
-  const c = (x: number, y: number) => Math.round(x*t + y*(1-t)).toString(16).padStart(2,'0');
-  return `#${c(ar,br)}${c(ag,bg)}${c(ab,bb)}`;
-}
-
 function modifierColor(modifier: ClassModifier | undefined, palette: PaletteColors, colorOff?: boolean): string {
   if (colorOff) return palette.textMuted;
   switch (modifier) {

package/src/cli.ts

@@ -54,6 +54,7 @@ const CHART_TYPE_DESCRIPTIONS: Record<string, string> = {
   kanban: 'Kanban board — task/workflow columns',
   c4: 'C4 diagram — system architecture (context, container, component, deployment)',
   'initiative-status': 'Initiative status — project roadmap with dependency tracking',
+  infra: 'Infra chart — infrastructure traffic flow with rps computation',
 };
 
 function printHelp(): void {
@@ -101,6 +102,8 @@ function parseArgs(argv: string[]): {
   c4Level: 'context' | 'containers' | 'components' | 'deployment';
   c4System: string | undefined;
   c4Container: string | undefined;
+  scenario: string | undefined;
+  listScenarios: boolean;
 } {
   const result = {
     input: undefined as string | undefined,
@@ -116,6 +119,8 @@ function parseArgs(argv: string[]): {
     c4Level: 'context' as 'context' | 'containers' | 'components' | 'deployment',
     c4System: undefined as string | undefined,
     c4Container: undefined as string | undefined,
+    scenario: undefined as string | undefined,
+    listScenarios: false,
   };
 
   const args = argv.slice(2); // skip node + script
@@ -169,6 +174,12 @@ function parseArgs(argv: string[]): {
     } else if (arg === '--c4-container') {
       result.c4Container = args[++i];
       i++;
+    } else if (arg === '--scenario') {
+      result.scenario = args[++i];
+      i++;
+    } else if (arg === '--list-scenarios') {
+      result.listScenarios = true;
+      i++;
     } else if (arg === '--no-branding') {
       result.noBranding = true;
       i++;
@@ -429,6 +440,34 @@ async function main(): Promise<void> {
     }
   }
 
+  // List scenarios (infra diagrams)
+  if (opts.listScenarios) {
+    const { parseInfra } = await import('./infra/parser');
+    const infraParsed = parseInfra(content);
+    if (infraParsed.scenarios.length === 0) {
+      console.log('(no scenarios defined)');
+    } else {
+      for (const s of infraParsed.scenarios) {
+        console.log(s.name);
+      }
+    }
+    return;
+  }
+
+  // Validate --scenario name against defined scenarios
+  if (opts.scenario) {
+    const { parseInfra } = await import('./infra/parser');
+    const infraParsed = parseInfra(content);
+    const match = infraParsed.scenarios.find((s) => s.name.toLowerCase() === opts.scenario!.toLowerCase());
+    if (!match) {
+      const available = infraParsed.scenarios.map((s) => s.name);
+      const msg = available.length > 0
+        ? `Error: Unknown scenario "${opts.scenario}". Available: ${available.join(', ')}`
+        : `Error: Unknown scenario "${opts.scenario}". No scenarios defined in this file.`;
+      exitWithJsonError(msg);
+    }
+  }
+
   // Validate C4 options
   if (opts.c4Level === 'containers' && !opts.c4System) {
     exitWithJsonError('Error: --c4-system is required when --c4-level is containers');
@@ -449,6 +488,7 @@ async function main(): Promise<void> {
     c4Level: opts.c4Level,
     c4System: opts.c4System,
     c4Container: opts.c4Container,
+    scenario: opts.scenario,
   });
 
   if (!svg) {