@diagrammo/dgmo 0.8.19 → 0.8.21

package/docs/guide/chart-mindmap.md

@@ -0,0 +1,198 @@
+# Mind Map
+
+```dgmo
+mindmap Product Strategy
+
+Research
+  User Interviews
+    Surveys | description: Quarterly NPS survey
+    Focus Groups
+  Competitor Analysis
+    Feature Matrix
+    Pricing Review
+Development
+  MVP Features
+    Auth System
+      description: Handle login, signup, OAuth flows
+    Dashboard
+  Nice-to-haves | collapsed: true
+    Dark Mode
+    Export PDF
+Go-to-Market
+  Launch Plan
+    Blog Post
+    Demo Video | description: 2-min product walkthrough
+```
+
+## Overview
+
+Mind maps visualize hierarchical information radiating from a central concept. Each branch represents a subtopic, with deeper nesting for finer detail. Mind maps are useful for brainstorming, project planning, knowledge organization, and breaking down complex topics.
+
+**Interactive features:** Click nodes to navigate to their source line. Collapse and expand subtrees by clicking nodes with children. Toggle tag group coloring and depth-based coloring via the legend controls.
+
+## Syntax
+
+```
+mindmap Title
+
+Node
+  Child Node
+    Grandchild
+  Another Child
+```
+
+The first line declares the chart type. The title becomes the root node. Indentation establishes the parent-child hierarchy.
+
+## Nodes
+
+Every non-blank, non-directive line is a node. Nesting is set by indentation:
+
+```
+mindmap Root
+  Level 1a
+    Level 2a
+    Level 2b
+  Level 1b
+```
+
+### Node Colors
+
+Add a color suffix in parentheses:
+
+```
+Important Topic(red)
+  Sub-topic(blue)
+```
+
+### Descriptions
+
+Nodes can have descriptions shown as secondary text. Two forms:
+
+```
+// Pipe form (single line)
+Surveys | description: Quarterly NPS survey
+
+// Indented form (before children)
+Auth System
+  description: Handle login, signup, and OAuth flows
+  Login Page
+```
+
+### Collapse Default
+
+Set a node's default collapsed state with pipe metadata:
+
+```
+Nice-to-haves | collapsed: true
+  Dark Mode
+  Export PDF
+```
+
+Collapsed nodes show a drill-bar indicating hidden children. Click to expand.
+
+## Multi-Root
+
+Omit the title to create multiple independent root trees:
+
+```
+mindmap
+
+Q1 Goals
+  Ship MVP
+  Hire designers
+Q2 Goals
+  Launch marketing
+  Expand team
+```
+
+The diagram title is inferred from the first root's label.
+
+## Pipe Metadata
+
+Attach metadata after `|` with comma-separated `key: value` pairs:
+
+```
+Node | priority: High, status: Done
+```
+
+Tag values, descriptions, and `collapsed` are all set via pipe metadata.
+
+## Tag Groups
+
+Tag groups define color-coded categories. They appear before content and follow the standard tag syntax:
+
+```
+mindmap Root
+
+tag Priority p
+  High(red)
+  Medium(yellow)
+  Low(green)
+
+  Task A | p: High
+  Task B | p: Low
+```
+
+- The alias (`p`) provides a shorthand for metadata keys
+- The active tag group colors nodes by their tag value
+- Click a tag group name in the legend to activate or deactivate it
+
+## Options
+
+| Option | Effect |
+|--------|--------|
+| `active-tag GroupName` | Set the default active tag group |
+| `hide-descriptions` | Hide description text on all nodes |
+
+Options are placed on their own line before content:
+
+```
+mindmap Root
+
+tag Priority p
+  High(red)
+  Low(green)
+
+active-tag Priority
+hide-descriptions
+
+  Task A | p: High
+```
+
+## Complete Example
+
+```dgmo
+mindmap Product Strategy(blue)
+
+tag Priority p
+  High(red)
+  Medium(yellow)
+  Low(green)
+
+tag Department d
+  Engineering(blue)
+  Design(purple)
+  Marketing(orange)
+
+active-tag Priority
+
+Research | d: Marketing
+  User Interviews | p: High
+    Surveys | description: Quarterly NPS survey
+    Focus Groups
+  Competitor Analysis | d: Engineering
+    Feature Matrix
+    Pricing Review
+Development | p: High, d: Engineering
+  MVP Features
+    Auth System
+      description: Handle login, signup, OAuth flows
+    Dashboard
+  Nice-to-haves | p: Low, collapsed: true
+    Dark Mode
+    Export PDF
+Go-to-Market | d: Marketing
+  Launch Plan
+    Blog Post
+    Demo Video | description: 2-min product walkthrough
+```

package/docs/guide/chart-sequence.md

@@ -103,7 +103,29 @@ PaymentGW is a networking aka "Payment Gateway"
 OrderDB position -1
 ```
 
-Position `0` is leftmost, `-1` is rightmost. Unpositioned participants appear in first-mention order.
+## Participant Ordering
+
+Participants are laid out left-to-right based on **first appearance in messages** — the first participant mentioned gets the leftmost column.
+
+**Position values:**
+- `0` = leftmost, `1` = second from left, etc.
+- `-1` = rightmost, `-2` = second from right
+- If two participants target the same slot, the later one shifts to the nearest free position
+
+**Groups affect ordering:** members of the same group always stay adjacent (see [Groups](#groups) below). The group is placed where its first member would naturally appear.
+
+**Priority (highest wins):**
+1. Explicit `position N`
+2. Group adjacency
+3. First appearance in messages
+
+```
+// Example: force the database to the far right
+sequence
+User -placeOrder-> OrderService
+OrderService -save-> OrderDB
+OrderDB position -1
+```
 
 ## Messages
 

package/docs/guide/chart-wireframe.md

@@ -0,0 +1,100 @@
+# Wireframe
+
+```dgmo
+wireframe Login Page
+
+[Header]
+  Acme App
+  nav
+    Home | active
+    About
+    Pricing
+
+[Main]
+  # Sign In
+
+  Email  [user@example.com]
+  Password  [****] | password
+
+  <x> Remember me
+
+  (Sign In)
+  (Forgot Password?) | ghost
+
+  ---
+
+  New here? (Create Account) | ghost
+```
+
+## Overview
+
+Wireframe diagrams use **visual-mnemonic syntax** where bracket characters communicate the element type. The source text reads as a wireframe even before rendering.
+
+## Elements
+
+| Syntax | Element |
+|--------|---------|
+| `[text]` (no children) | Text input |
+| `[Name]` (with children) | Group / region |
+| `(Label)` | Button |
+| `{A \| B \| C}` | Dropdown |
+| `<x>` / `< >` | Checkbox |
+| `(*) Label` / `( ) Label` | Radio button |
+| `# Text` | Heading |
+| `## Text` | Subheading |
+| `---` | Divider |
+| `- text` | List item |
+
+## Keywords
+
+`nav`, `tabs`, `table`, `image`, `modal`, `skeleton`, `alert`, `progress`, `chart`
+
+- `image round` / `image wide` — shape hints
+- `chart line` / `chart bar` / `chart pie` — chart silhouettes
+- `progress 60` — percentage bar
+- `table 5x4` — skeleton table with dimensions
+
+## States
+
+Pipe metadata flags on elements:
+
+```
+(Submit) | disabled
+(Delete) | destructive
+(Cancel) | ghost
+[Email] | password
+[Notes] | textarea
+<x> Dark mode | toggle
+[Cards] | horizontal
+```
+
+## Layout
+
+- **Desktop** (default): 1200px, top-level regions side-by-side
+- **Mobile**: `mobile` keyword, 375px vertical stacking
+- **Smart sizing**: `sidebar` gets ~25%, `main` fills remaining
+- `| horizontal` on any group arranges children in a row
+
+## Multi-Element Lines
+
+Two or more spaces between elements on one line:
+
+```
+Email  [user@example.com]    // label + field
+(-)  1  (+)                  // inline stepper
+```
+
+## Tables
+
+```dgmo
+wireframe Data
+
+table
+  Name, Email, Role
+  John, john@, Admin
+  Sally, sally@, Editor
+
+// Skeleton shorthand:
+table 5x4
+  Name, Email, Role, Status
+```

package/docs/guide/index.md

@@ -4,6 +4,14 @@ Diagrammo is a diagram editor for creating charts and diagrams with a simple pla
 
 Learn more at **[diagrammo.app](https://diagrammo.app)**.
 
+## DGMO and Diagrammo
+
+**DGMO** is the plain-text markup language you write. **Diagrammo** is the app you write it in.
+
+Think of it like Markdown and your editor — Markdown is the syntax, and you can write it anywhere. DGMO works the same way: it's a `.dgmo` text file that describes a diagram. You can create and edit `.dgmo` files in the Diagrammo desktop app, the online editor, Obsidian (via plugin), or any text editor. The `dgmo` CLI renders them from the terminal, and the `@diagrammo/dgmo` npm package lets you render them programmatically.
+
+The name "DGMO" is shorthand for "Diagrammo" — shorter to type, easier to use as a file extension and command name.
+
 ## Getting Started
 
 - **Create a new file** using the file tree on the left, or press **Cmd + N**

package/docs/language-reference.md

@@ -20,7 +20,8 @@
 14. [Timeline Diagrams](#14-timeline-diagrams)
 15. [Data Charts](#15-data-charts)
 16. [Visualizations](#16-visualizations)
-17. [Colon Usage Summary](#17-colon-usage-summary)
+17. [Wireframe Diagrams](#17-wireframe-diagrams)
+18. [Colon Usage Summary](#18-colon-usage-summary)
 
 ---
 
@@ -114,6 +115,79 @@ no-option-name       // off
 - Bare keyword = on; `no-` prefix = off
 - Must appear before diagram content
 
+### 1.9 In-Arrow Message Labels
+
+An **in-arrow label** is the text embedded inside an arrow between the opening delimiter and the arrow token, as in `A -label-> B`.
+
+```
+A -label-> B
+ ^ ^---^ ^^
+ | |     ||
+ | |     |+- destination id
+ | |     +- arrow token
+ | +- label text (plain, no markdown)
+ +- opening delimiter (matches arrow type)
+```
+
+**Chart types that support in-arrow labels**: sequence, flowchart, state, infra, c4, er, class, boxes-and-lines.
+
+#### Cheat sheet
+
+```
+// happy-path: labels are plain text with punctuation allowed
+A -location[]-> B          // label = "location[]"
+A -a[b]c-> B                // label = "a[b]c"
+A -{json}-> B               // label = "{json}"
+
+// unicode: all scripts and emoji preserved verbatim
+A -café-> B
+A -日本語-> B
+A -🎉-> B
+
+// punctuation is literal — no markdown interpretation
+A -(parenthetical)-> B      // label = "(parenthetical)"  (NOT a color)
+A -*emphasis*-> B           // label = "*emphasis*"       (NOT bold)
+A -`code`-> B               // label = "`code`"           (NOT a code span)
+
+// forbidden: -> and ~> substrings inside a label
+A -uses -> chain-> B        // ERROR (E_ARROW_SUBSTRING_IN_LABEL)
+// migration: move the label to the post-colon form
+A -> B: uses -> chain       // works for charts that accept post-colon labels
+
+// migration from pre-gauntlet (legacy) syntax
+A -Makes calls [HTTP]-> B   // label is now the FULL "Makes calls [HTTP]"
+A -Makes calls-> B | tech: HTTP   // preferred: technology on target metadata
+```
+
+#### Character-set contract
+
+- **Allowed**: any Unicode codepoint except the forbidden list below. Brackets `[] {} ()`, pipes `|`, quotes `"' `, backticks, punctuation, digits, emoji, ZWJ sequences, combining marks — all pass through as literal characters.
+- **Forbidden substrings**: `->` and `~>`. These terminate the arrow. If you need them inside a label, use the post-colon form (`A -> B: uses -> to chain`) on chart types that support it; there is no escape mechanism.
+- **Forbidden characters**: C0 control characters U+0000–U+001F except U+0009 (tab), and U+007F (DEL). Silent renderer breakage and log-injection surface — no legitimate use case.
+- **Whitespace**: leading and trailing whitespace is trimmed; internal whitespace runs (including tabs, non-breaking spaces, and zero-width spaces) are **preserved**, never collapsed.
+- **Plain text only**: no markdown interpretation. `*foo*` renders as `*foo*`, not italicized. `[label](url)` renders as literal `[label](url)`, not a hyperlink. Clickable URLs belong in notes, not in in-arrow labels.
+- **HTML-safe**: all renderers emit label text as a DOM text node. `<script>alert(1)</script>` renders as literal text — the entire label is a sequence of codepoints, not a markup fragment.
+
+#### Color suffix (flowchart and state only)
+
+```
+A -(red)-> B         // colored edge, no label
+A -(notacolor)-> B   // label = "(notacolor)" (fall-through)
+A -(red) uses-> B    // label = "(red) uses" (combined form not supported)
+A -red-> B           // label = "red" (bare word is always a label)
+```
+
+A parenthesized palette color is only recognized when the entire label between the opening `-` and the arrow token is exactly `(colorName)` and `colorName` is one of the 11 names in §1.5. Any other content falls through to the label. To combine a color and a label, use the post-colon or pipe-metadata form instead.
+
+#### Migrating from pre-gauntlet syntax
+
+Two legacy forms changed with this spec:
+
+1. **C4 trailing `[technology]` sugar is removed.** A C4 arrow like `-Makes calls [HTTPS]-> API` used to extract `HTTPS` as the technology annotation. The full `Makes calls [HTTPS]` is now the label. Use the post-colon or pipe form for technology: `-Makes calls-> API | tech: HTTPS`.
+2. **Bare palette color suffixes are a literal label.** `A -red-> B` on flowchart/state used to be accepted as a bare color suffix in some surfaces. It is now always a label with text `red`. To color an edge, use the `-(red)->` parens form.
+
+No code migration is required for in-arrow label character escaping — any label that was valid before remains valid, with one exception: if your label happened to contain the literal substring `->` or `~>`, the parser now rejects it with `E_ARROW_SUBSTRING_IN_LABEL`. Move those labels to the post-colon form.
+
 ---
 
 ## 2. Sequence Diagrams
@@ -1253,7 +1327,141 @@ Navigator 0.85 0.8
 
 ---
 
-## 17. Colon Usage Summary
+## 17. Wireframe Diagrams
+
+Wireframe diagrams use **visual-mnemonic syntax** where bracket characters communicate element type.
+
+### Declaration
+
+```
+wireframe Page Title
+```
+
+### Form Factor
+
+```
+mobile
+```
+
+Switches to narrow vertical layout (375px). Desktop (1200px, horizontal regions) is the default.
+
+### Visual-Mnemonic Elements
+
+| Syntax | Element | Example |
+|--------|---------|---------|
+| `[text]` (leaf) | Text input | `[Email address]` |
+| `[Name]` (with children) | Group/region | `[Sidebar]` + indented children |
+| `(Label)` | Button | `(Submit)` |
+| `{A \| B \| C}` | Dropdown/select | `{Small \| Medium \| Large}` |
+| `<x>` / `< >` | Checkbox | `<x> Remember me` |
+| `(*) Label` / `( ) Label` | Radio button | `(*) Option A` |
+| `# Text` / `## Text` | Heading | `# Sign In` |
+| `---` | Divider | `---` |
+| `- text` | List item | `- Electronics` |
+| Bare text | Text/paragraph | `Welcome to our app` |
+
+### Keyword Elements
+
+| Keyword | Type | Parameters |
+|---------|------|------------|
+| `nav` | Block | Children are nav items |
+| `tabs` | Block | Children are tab labels |
+| `table` | Block | Comma-separated rows; first = header |
+| `table RxC` | Skeleton table | `table 5x4` + optional header row |
+| `image` | Leaf | `round`, `wide` hints |
+| `modal Title` | Block | Rendered as separate panel below |
+| `skeleton` | Block | Children render as grey placeholders |
+| `alert` | Block | Optional semantic state |
+| `progress N` | Leaf | Value 0-100: `progress 60` |
+| `chart type` | Leaf | `chart line`, `chart bar`, `chart pie` |
+
+### Pipe Metadata (States)
+
+Wireframe uses flag keywords (not `key: value`):
+
+```
+(Submit) | disabled
+(Delete) | destructive
+(Cancel) | ghost
+[Email] | password
+[Notes] | textarea
+[Cards] | horizontal
+[Advanced] | collapsed
+[Messages] | scrollable
+<x> Dark mode | toggle
+```
+
+Available states: `disabled`, `active`, `selected`, `empty`, `ghost`, `destructive`, `success`, `warning`, `info`, `scrollable`, `collapsed`, `toggle`, `password`, `textarea`, `horizontal`, `primary`.
+
+Free-text annotations after states: `[Email] | required, validates email format`.
+
+### Multi-Element Lines
+
+Two or more spaces between segments create separate elements:
+
+```
+Email  [user@example.com]    // label + field (2 segments)
+(-)  1  (+)                  // 3 inline items
+$299.99  ~~$349.99~~         // 2 inline texts
+```
+
+- **2 segments** (bare text + element): label-for-element pairing
+- **3+ segments**: inline items, no label pairing
+- **Single space = same element**: `Cart (3)` is one text element
+
+### Group Disambiguation
+
+- `[Name]` with indented children = group/container
+- `[Name]` with no children = text input
+- `[Name] | horizontal/scrollable/collapsed` = group (even without children)
+
+### Table Syntax
+
+Explicit rows (comma-separated, first row = header):
+
+```
+table
+  Name, Email, Role
+  John, john@, Admin
+  Sally, sally@, Editor
+```
+
+Skeleton shorthand:
+
+```
+table 5x4
+  Name, Email, Role, Status
+```
+
+### Layout Model
+
+- Desktop: 1200px wide, top-level regions arrange horizontally
+- Mobile: 375px wide, all regions stack vertically
+- Smart sizing: `sidebar` → ~25%, `main`/`content` → fill, `header`/`footer` → full width
+- `| horizontal` on groups arranges children in a row
+
+### Example
+
+```
+wireframe Login Page
+
+[Header]
+  nav
+    Home | active
+    Settings
+
+[Main]
+  # Sign In
+  Email  [user@example.com]
+  Password  [****] | password
+  <x> Remember me
+  (Sign In)
+  (Forgot Password?) | ghost
+```
+
+---
+
+## 18. Colon Usage Summary
 
 ### Constructs Where Colons Are REQUIRED
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.8.19",
+  "version": "0.8.21",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "type": "module",
@@ -55,10 +55,12 @@
   ],
   "sideEffects": false,
   "scripts": {
-    "prebuild": "rm -rf dist && lezer-generator src/editor/dgmo.grammar -o src/editor/dgmo.grammar.js",
+    "codegen": "lezer-generator src/editor/dgmo.grammar -o src/editor/dgmo.grammar.js",
+    "prebuild": "rm -rf dist && pnpm codegen",
     "build": "tsup",
     "typecheck": "tsc --noEmit",
     "dev": "tsup --watch",
+    "pretest": "pnpm codegen",
     "test": "vitest run",
     "test:watch": "vitest",
     "gallery": "pnpm build && node scripts/generate-gallery.mjs",
@@ -69,7 +71,13 @@
     "check:duplication": "jscpd ./src",
     "check:deadcode": "knip",
     "check:spelling": "cspell \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "check:all": "pnpm check:deadcode && pnpm check:spelling && pnpm check:duplication && pnpm check:circular && pnpm check:deps && pnpm check:security && pnpm build && pnpm check:publish && pnpm check:types",
+    "check:circular": "madge --circular --extensions ts src/ --json | node -e \"const c=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); const n=c.length; if(n>7){console.error('New circular deps found ('+n+' > 7 known type-only cycles)');process.exit(1)}else if(n>0){console.log(n+' known type-only/dynamic cycles (safe)')}else{console.log('No circular dependencies')}\"",
+    "check:deps": "depcheck --ignores='@codemirror/language,@lezer/*,husky,lint-staged,tsup'",
+    "check:security": "pnpm audit --prod",
+    "check:publish": "publint",
     "check:size": "pnpm build && du -sh dist/ && echo '---' && ls -lh dist/*.js dist/*.cjs",
+    "check:types": "attw --pack . --ignore-rules no-resolution",
     "postinstall": "node -e \"console.log('\\n💡 Claude Code user? Run: dgmo --install-claude-skill\\n')\"",
     "prepare": "husky"
   },
@@ -83,10 +91,11 @@
     "d3-selection": "^3.0.0",
     "d3-shape": "^3.2.0",
     "echarts": "^6.0.0",
-    "jsdom": "^29.0.1",
+    "jsdom": "^29.0.2",
     "lz-string": "^1.5.0"
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
     "@codemirror/language": "^6.12.3",
     "@eslint/js": "^10.0.1",
     "@lezer/generator": "^1.8.0",
@@ -97,18 +106,22 @@
     "@types/d3-selection": "^3.0.11",
     "@types/d3-shape": "^3.1.8",
     "@types/jsdom": "^28.0.1",
-    "cspell": "^9.7.0",
+    "cspell": "^10.0.0",
+    "depcheck": "^1.4.7",
     "esbuild": "^0.28.0",
     "eslint": "^10.2.0",
+    "eslint-plugin-security": "^4.0.0",
     "husky": "^9.1.7",
-    "jscpd": "^4.0.8",
-    "knip": "^6.3.0",
+    "jscpd": "^4.0.9",
+    "knip": "^6.3.1",
     "lint-staged": "^16.4.0",
-    "prettier": "^3.8.1",
+    "madge": "^8.0.0",
+    "prettier": "^3.8.2",
+    "publint": "^0.3.18",
     "tsup": "^8.5.1",
     "typescript": "^6.0.2",
-    "typescript-eslint": "^8.58.0",
-    "vitest": "^4.1.2"
+    "typescript-eslint": "^8.58.1",
+    "vitest": "^4.1.4"
   },
   "lint-staged": {
     "*.ts": [

package/src/boxes-and-lines/collapse.ts

@@ -40,12 +40,28 @@ export function collapseBoxesAndLines(
   const nodeToGroup = new Map<string, string>();
   const collapsedChildCounts = new Map<string, number>();
 
+  // Recursively collect all descendants of a group (including sub-group children)
+  function collectDescendants(groupLabel: string): string[] {
+    const group = groupByLabel.get(groupLabel);
+    if (!group) return [];
+    const descendants: string[] = [];
+    for (const child of group.children) {
+      descendants.push(child);
+      // If child is itself a group, collect its descendants too
+      if (groupByLabel.has(child)) {
+        descendants.push(...collectDescendants(child));
+      }
+    }
+    return descendants;
+  }
+
   for (const groupLabel of collapsedGroups) {
     const group = groupByLabel.get(groupLabel);
     if (!group) continue;
     const groupId = `__group_${groupLabel}`;
 
-    for (const child of group.children) {
+    const allDescendants = collectDescendants(groupLabel);
+    for (const child of allDescendants) {
       nodeToGroup.set(child, groupId);
     }
     collapsedChildCounts.set(groupLabel, group.children.length);
@@ -67,8 +83,10 @@ export function collapseBoxesAndLines(
     edges.push({ ...edge, source: src, target: tgt });
   }
 
-  // Keep only groups that are not collapsed
-  const groups = parsed.groups.filter((g) => !collapsedGroups.has(g.label));
+  // Keep only groups that are not collapsed and not inside a collapsed group
+  const groups = parsed.groups.filter(
+    (g) => !collapsedGroups.has(g.label) && !nodeToGroup.has(g.label)
+  );
 
   return {
     parsed: { ...parsed, nodes, edges, groups },