@diagrammo/dgmo 0.8.22 → 0.8.23

package/docs/guide/chart-cycle.md

@@ -0,0 +1,156 @@
+# Cycle Diagram
+
+```dgmo
+cycle OODA Loop
+
+Observe | color: blue
+  Gather raw information from the environment
+  Monitor unfolding circumstances
+  -Unfold circumstances-> | color: blue
+
+Orient | color: green
+  Analyze and synthesize observations
+  Form a mental model of the situation
+  -Form hypothesis-> | color: green
+
+Decide | color: orange
+  Select a course of action
+  -Commit to action-> | color: orange
+
+Act | color: red
+  Execute the chosen course of action
+  Generate results that feed back
+  -Generate feedback-> | color: red
+```
+
+## Overview
+
+Cycle diagrams show a circular process flow where nodes are arranged on a circle and directed edges connect each to the next, with the last wrapping back to the first. They are ideal for OODA loops, PDCA cycles, product lifecycles, continuous improvement processes, and any workflow that repeats.
+
+## Syntax
+
+```
+cycle Title
+
+NodeLabel
+NodeLabel | color: blue, span: 2
+```
+
+The first line declares the chart type and title. Each top-level line declares a node. Nodes are positioned around a circle in declaration order.
+
+## Nodes
+
+Every non-indented, non-directive line is a node:
+
+```
+cycle Seasons
+
+Spring | color: green
+Summer | color: yellow
+Autumn | color: orange
+Winter | color: blue
+```
+
+### Node Pipe Metadata
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `color` | palette name | auto | Node fill color |
+| `span` | positive number | `1` | Relative arc distance to next node |
+| `description` | string | — | One-liner shown below the label |
+
+### Descriptions
+
+Indented lines under a node add description text. Markdown inline formatting is supported (`**bold**`, `*italic*`, `` `code` ``, `[links](url)`). Bullet points with `- item` render as `• item`.
+
+```
+Observe | color: blue
+  Gather raw information from the environment
+  Monitor unfolding circumstances
+```
+
+If both `| description: text` and indented lines exist, they concatenate (pipe first, then indented).
+
+## Edges
+
+Edges are **implicit** — every node connects to the next, with the last wrapping to the first. The `->` syntax annotates edges with labels, descriptions, and styling:
+
+```
+Observe | color: blue
+  -Unfold circumstances-> | color: blue
+    Synthesize raw data into context
+
+Orient | color: green
+  -> | width: 4
+```
+
+Edge lines are indented under their source node. A label goes between `-` and `->`. Pipe metadata supports `color` and `width`.
+
+### Edge Descriptions
+
+Indented lines under an edge line add description text:
+
+```
+Observe
+  -Analyze->
+    Break down observations into components
+    Identify **key patterns**
+```
+
+## Span
+
+The `span` metadata controls relative arc distance between nodes. A node with `span: 2` gets twice the arc space to the next node:
+
+```
+cycle Weighted Process
+
+Important Step | span: 2
+Quick Step
+Another Step | span: 1.5
+```
+
+## Directives
+
+| Directive | Effect |
+|-----------|--------|
+| `direction-counterclockwise` | Reverse cycle direction (default: clockwise) |
+| `hide-descriptions` | Hide description text on all nodes and edges |
+| `circle-nodes` | Render nodes as circles instead of rounded rectangles |
+
+```
+cycle Simple Loop
+
+direction-counterclockwise
+
+Plan
+Do
+Check
+Act
+```
+
+## Complete Example
+
+```dgmo
+cycle PDCA Continuous Improvement
+
+Plan | color: blue, span: 1.5
+  Define objectives and processes
+  Establish expected outcomes
+  -Start implementation->
+
+Do | color: green
+  Execute the plan on a small scale
+  Collect data for analysis
+  -Gather results->
+
+Check | color: orange
+  Compare results against expectations
+  Identify deviations and root causes
+  -Propose changes-> | color: orange
+
+Act | color: red
+  Standardize successful changes
+  Address remaining gaps
+  -Feed back into planning-> | color: red
+    Begin the next improvement cycle
+```

package/docs/guide/chart-journey-map.md

@@ -0,0 +1,179 @@
+# Journey Map
+
+```dgmo
+journey-map Coffee Shop Visit
+
+[Order]
+  Walk in | 4
+  Wait in line | 2
+  Order drink | 4
+
+[Wait]
+  Find a seat | 3
+  Wait for drink | 2
+
+[Enjoy]
+  Get drink | 5
+```
+
+## Overview
+
+Journey maps visualize a user's experience across a process or service, plotting emotional highs and lows as a continuous curve. Each step has a score (1–5, high is good) that drives the emotion landscape. Phases group related steps, annotations capture pain points, opportunities, and thoughts, and tags add cross-cutting dimensions like channel or touchpoint.
+
+Journey maps are ideal for UX research, customer experience mapping, service design, and identifying friction points.
+
+## Syntax
+
+```
+journey-map Title
+
+persona Name
+
+[Phase Name]
+  Step Name | score
+  Step Name | score Emotion
+```
+
+The first line must be `journey-map` followed by a title. Phases use bracket syntax at indent 0. Steps are indented within phases.
+
+## Persona
+
+Declares the journey's protagonist:
+
+```
+persona Tech-Savvy Shopper
+  28yo developer, price-sensitive, does extensive research
+```
+
+Name is everything after `persona `. Indented lines add description text. Only one persona per diagram.
+
+## Phases
+
+Phases group steps into logical stages:
+
+```
+[Research]
+  Compare specs | 4
+  Watch reviews | 5
+
+[Purchase]
+  Add to cart | 3
+  Complete payment | 3
+```
+
+Phases are optional — steps can appear at root level for a flat continuous flow.
+
+## Steps
+
+Steps appear indented within phases (or at indent 0 in flat mode).
+
+### Score Syntax
+
+The score goes in the pipe, separating step name from data:
+
+```
+Step Name | 4                        // bare score
+Step Name | 4 Delighted              // score + emotion label
+Step Name | 4, ch: Web               // score + tag metadata
+Step Name | 4 Delighted, ch: Web     // score + label + metadata
+Step Name | score: 4, ch: Web        // explicit score key
+Step Name                            // no pipe = scoreless step
+```
+
+- **Score scale**: 1–5 integer (high = good)
+- **Emotion label**: optional single word after the score (e.g., `Frustrated`, `Delighted`, `Neutral`)
+- **Scoreless steps**: render as cards but produce no emotion curve point
+
+## Annotations
+
+Deeper-indented lines under a step add context:
+
+```
+  Forced account creation | 1 Frustrated
+    pain: Wants guest checkout
+    opportunity: Add guest checkout option
+    thought: Why do I need an account?
+    description: User abandoned cart twice
+```
+
+| Prefix | Rendering |
+|--------|-----------|
+| `pain:` | Pain point (red accent) |
+| `opportunity:` | Improvement opportunity (green accent) |
+| `thought:` | User thought (italic) |
+| `description:` | General context text |
+
+Multiple annotations per step are allowed.
+
+## Tag Groups
+
+Tags add color-coded dimensions like channel or touchpoint:
+
+```
+tag Channel ch
+  Web(blue)
+  Mobile(purple)
+  In-Person(green)
+
+[Research]
+  Compare specs | 4, ch: Web
+  Ask friends | 4, ch: In-Person
+```
+
+Reference tag values in step pipes via the alias.
+
+## Flat Mode
+
+Steps at root level (no `[Phase]` brackets) render as a continuous horizontal strip:
+
+```dgmo
+journey-map Quick Feedback
+
+Opened app | 4
+Searched for feature | 3
+Hit error | 1 Frustrated
+  pain: No helpful error message
+Contacted support | 2
+Got resolution | 5 Relieved
+```
+
+## Directives
+
+| Directive | Effect |
+|-----------|--------|
+| `no-legend` | Hide the score legend |
+| `active-tag GroupName` | Set the active tag group for coloring |
+
+## Complete Example
+
+```dgmo
+journey-map Buying a Laptop
+
+persona Tech-Savvy Shopper
+  28yo developer, price-sensitive, does extensive research
+
+tag Channel ch
+  Web(blue)
+  Mobile(purple)
+  Email(teal)
+  In-Person(green)
+
+[Research]
+  Compare specs | 4, ch: Web
+    description: Checked 12 laptops across 4 review sites
+  Watch reviews | 5 Engaged, ch: Mobile
+  Ask friends | 4, ch: In-Person
+
+[Purchase]
+  Add to cart | 3, ch: Web
+  Forced account creation | 1 Frustrated, ch: Web
+    pain: Wants guest checkout
+    pain: Password requirements too strict
+  Complete payment | 3, ch: Web
+
+[Delivery]
+  Track package | 4, ch: Mobile
+  Unboxing | 5 Delighted, ch: In-Person
+    opportunity: Include setup guide
+    thought: Excited to try it out
+```

package/docs/guide/chart-pyramid.md

@@ -0,0 +1,111 @@
+# Pyramid Diagram
+
+```dgmo
+pyramid Maslow's Hierarchy of Needs
+
+Self-Actualization | color: purple
+  Morality, creativity, acceptance of facts.
+
+Esteem | color: blue
+  Respect, recognition, confidence.
+
+Love & Belonging | color: green
+  Friendship, intimacy, family.
+
+Safety | color: yellow
+  Security, employment, health.
+
+Physiological | color: orange
+  Food, water, warmth, rest.
+```
+
+## Overview
+
+Pyramid diagrams show a hierarchy of stacked layers. Each layer gets a colored band with a label and an optional description. Source order reads apex-first — the first layer in the file is the narrowest (visual top), the last is the widest (visual bottom). Use `inverted` to flip into a funnel orientation.
+
+## Syntax
+
+```
+pyramid Title
+
+LayerLabel
+LayerLabel | color: blue
+LayerLabel | color: green
+  Indented description
+```
+
+The first line declares the chart type and an optional title. Each non-indented, non-directive line declares one layer. At least two layers are required.
+
+## Layers
+
+```
+pyramid Roles
+
+Executives | color: purple
+Managers | color: blue
+Individual Contributors | color: green
+```
+
+### Layer Pipe Metadata
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `color` | palette name | auto-assigned | Layer color |
+| `description` | string | — | One-liner shown beside the layer |
+
+### Descriptions
+
+Indented lines under a layer add description text. Markdown inline formatting is supported (`**bold**`, `*italic*`, `` `code` ``, `[links](url)`). Bullet points with `- item` render as `• item`.
+
+```
+Wisdom | color: purple
+  Ethical judgment, acting with insight.
+  - Knowing *why* something matters
+  - Acting with long-term perspective
+```
+
+If both `| description: text` and indented lines exist, they concatenate (pipe first, then indented).
+
+## Directives
+
+| Directive | Effect |
+|-----------|--------|
+| `inverted` | Flip apex to the bottom (funnel orientation). Source order is preserved — the first layer is always the visual top. |
+
+```
+pyramid Acquisition Funnel
+
+inverted
+
+Visitors | color: blue
+Signups | color: cyan
+Activated | color: green
+Paid | color: orange
+```
+
+## Overflow Handling
+
+When descriptions don't fit a layer's band, the renderer automatically:
+
+- **Wraps** text at the column edge so nothing leaves the canvas
+- **Truncates** with "…" when content exceeds the available lines
+- **Alternates** descriptions left ↔ right when a single column can't hold them
+- **Reveals** the full description when a layer is highlighted (in-app), hiding siblings so it has room
+
+## Complete Example
+
+```dgmo
+pyramid The DIKW Pyramid
+
+Wisdom | color: purple
+  Ethical judgment, acting with insight — knowing *why*.
+
+Knowledge | color: blue
+  Synthesized information — knowing *how*.
+
+Information | color: green
+  Processed data with context — knowing *what*.
+
+Data | color: yellow
+  Raw facts and measurements — unprocessed signals.
+```

package/docs/guide/registry.json

@@ -19,12 +19,15 @@
     { "slug": "chart-er", "title": "Entity Relationship", "group": "software", "file": "chart-er.md" },
     { "slug": "chart-flowchart", "title": "Flowchart", "group": "software", "file": "chart-flowchart.md" },
     { "slug": "chart-infra", "title": "Infrastructure", "group": "software", "file": "chart-infra.md" },
+    { "slug": "chart-mindmap", "title": "Mind Map", "group": "software", "file": "chart-mindmap.md" },
     { "slug": "chart-sequence", "title": "Sequence Diagram", "group": "software", "file": "chart-sequence.md" },
     { "slug": "chart-sitemap", "title": "Sitemap", "group": "software", "file": "chart-sitemap.md" },
     { "slug": "chart-state", "title": "State Diagram", "group": "software", "file": "chart-state.md" },
+    { "slug": "chart-wireframe", "title": "Wireframe", "group": "software", "file": "chart-wireframe.md" },
 
     { "slug": "chart-area", "title": "Area Chart", "group": "data", "file": "chart-area.md" },
     { "slug": "chart-bar", "title": "Bar Chart", "group": "data", "file": "chart-bar.md" },
+    { "slug": "chart-cycle", "title": "Cycle Diagram", "group": "data", "file": "chart-cycle.md" },
     { "slug": "chart-chord", "title": "Chord Diagram", "group": "data", "file": "chart-chord.md" },
     { "slug": "chart-doughnut", "title": "Doughnut Chart", "group": "data", "file": "chart-doughnut.md" },
     { "slug": "chart-function", "title": "Function Plot", "group": "data", "file": "chart-function.md" },
@@ -38,8 +41,10 @@
     { "slug": "chart-slope", "title": "Slope Chart", "group": "data", "file": "chart-slope.md" },
     { "slug": "chart-bar-stacked", "title": "Stacked Bar Chart", "group": "data", "file": "chart-bar-stacked.md" },
 
+    { "slug": "chart-journey-map", "title": "Journey Map", "group": "business", "file": "chart-journey-map.md" },
     { "slug": "chart-funnel", "title": "Funnel Chart", "group": "business", "file": "chart-funnel.md" },
     { "slug": "chart-org", "title": "Org Chart", "group": "business", "file": "chart-org.md" },
+    { "slug": "chart-pyramid", "title": "Pyramid Diagram", "group": "business", "file": "chart-pyramid.md" },
     { "slug": "chart-quadrant", "title": "Quadrant Chart", "group": "business", "file": "chart-quadrant.md" },
     { "slug": "chart-sankey", "title": "Sankey Diagram", "group": "business", "file": "chart-sankey.md" },
     { "slug": "chart-tech-radar", "title": "Technology Radar", "group": "business", "file": "chart-tech-radar.md" },

package/docs/language-reference.md

@@ -1570,7 +1570,68 @@ wireframe Login Page
 
 ---
 
-## 19. Colon Usage Summary
+## 19. Pyramid Diagrams
+
+Hierarchical pyramid visualization with stacked layers, descriptions, and optional per-layer color. Source order reads apex-first (top of file = top of pyramid).
+
+### Declaration
+
+```
+pyramid [Title]
+
+LayerLabel
+LayerLabel | color: blue
+LayerLabel | color: green
+  Indented description
+```
+
+The first line declares the chart type and an optional title. Each non-indented, non-directive line declares one layer. At least two layers are required.
+
+### Example
+
+```
+pyramid Maslow's Hierarchy
+
+Self-Actualization | color: purple
+  Morality, creativity, acceptance of facts.
+
+Esteem | color: blue
+  Respect, recognition, confidence.
+
+Love & Belonging | color: green
+  Friendship, intimacy, family.
+
+Safety | color: yellow
+  Security, employment, health.
+
+Physiological | color: orange
+  Food, water, warmth, rest.
+```
+
+### Layer Pipe Metadata
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `color` | palette name | auto | Layer color |
+| `description` | string | — | One-liner description |
+
+### Descriptions
+
+Indented lines under a layer are description text. Markdown inline formatting (`**bold**`, `*italic*`, `` `code` ``, `[links](url)`) is supported. Bullets written as `- item` render as `• item`.
+
+### Directives
+
+| Directive | Effect |
+|-----------|--------|
+| `inverted` | Flip apex to the bottom (funnel orientation). Source order is preserved — the first layer is always the visual top. |
+
+### Overflow Handling
+
+When descriptions don't fit a layer's band the renderer wraps at the column edge, truncates with `…`, auto-alternates descriptions left ↔ right when one column can't hold them, and (in-app) reveals the full description on highlight while hiding siblings.
+
+---
+
+## 20. Colon Usage Summary
 
 ### Constructs Where Colons Are REQUIRED
 

package/gallery/fixtures/pyramid/dikw.dgmo

@@ -0,0 +1,17 @@
+pyramid The DIKW Pyramid
+
+Wisdom | color: purple
+  Ethical judgment, acting with
+  insight — knowing *why*.
+
+Knowledge | color: blue
+  Synthesized information —
+  knowing *how*.
+
+Information | color: green
+  Processed data with context —
+  knowing *what*.
+
+Data | color: yellow
+  Raw facts and measurements —
+  unprocessed signals.

package/gallery/fixtures/pyramid/inverted-funnel.dgmo

@@ -0,0 +1,16 @@
+pyramid Acquisition Funnel
+
+inverted
+
+Visitors | color: blue
+  Landed on the site from any channel
+  this month.
+
+Signups | color: cyan
+  Provided an email and confirmed.
+
+Activated | color: green
+  Completed the first meaningful action.
+
+Paid | color: orange
+  Converted to a paid plan.

package/gallery/fixtures/pyramid/minimal.dgmo

@@ -0,0 +1,5 @@
+pyramid
+
+Top
+Middle
+Bottom

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.8.22",
+  "version": "0.8.23",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,16 @@
         "types": "./dist/highlight.d.cts",
         "default": "./dist/highlight.cjs"
       }
+    },
+    "./internal": {
+      "import": {
+        "types": "./dist/internal.d.ts",
+        "default": "./dist/internal.js"
+      },
+      "require": {
+        "types": "./dist/internal.d.cts",
+        "default": "./dist/internal.cjs"
+      }
     }
   },
   "files": [

package/src/cli.ts

@@ -6,7 +6,11 @@ import { resolve, join, basename, extname } from 'node:path';
 import { createInterface } from 'node:readline';
 import { Resvg } from '@resvg/resvg-js';
 import { render } from './render';
-import { parseDgmo, getAllChartTypes } from './dgmo-router';
+import {
+  parseDgmo,
+  getAllChartTypes,
+  CHART_TYPE_DESCRIPTIONS,
+} from './dgmo-router';
 import { parseDgmoChartType } from './dgmo-router';
 import { formatDgmoError } from './diagnostics';
 import { getPalette, getAvailablePalettes } from './palettes';
@@ -19,40 +23,6 @@ const PALETTES = getAvailablePalettes().map((p) => p.id);
 
 const THEMES = ['light', 'dark', 'transparent'] as const;
 
-const CHART_TYPE_DESCRIPTIONS: Record<string, string> = {
-  bar: 'Bar chart — categorical comparisons',
-  line: 'Line chart — trends over time',
-  'multi-line': 'Multi-line chart — multiple series trends',
-  area: 'Area chart — filled line chart',
-  pie: 'Pie chart — part-to-whole proportions',
-  doughnut: 'Doughnut chart — ring-style pie chart',
-  radar: 'Radar chart — multi-dimensional metrics',
-  'polar-area': 'Polar area chart — radial bar chart',
-  'bar-stacked': 'Stacked bar chart — multi-series categorical',
-  scatter: 'Scatter plot — 2D data points or bubble chart',
-  sankey: 'Sankey diagram — flow/allocation visualization',
-  chord: 'Chord diagram — circular flow relationships',
-  function: 'Function plot — mathematical expressions',
-  heatmap: 'Heatmap — matrix intensity visualization',
-  funnel: 'Funnel chart — conversion pipeline',
-  slope: 'Slope chart — change between two periods',
-  wordcloud: 'Word cloud — term frequency visualization',
-  arc: 'Arc diagram — network relationships',
-  timeline: 'Timeline — events, eras, and date ranges',
-  venn: 'Venn diagram — set overlaps',
-  quadrant: 'Quadrant chart — 2x2 positioning matrix',
-  sequence: 'Sequence diagram — message/interaction flows',
-  flowchart: 'Flowchart — decision trees and process flows',
-  class: 'Class diagram — UML class hierarchies',
-  er: 'ER diagram — database schemas and relationships',
-  org: 'Org chart — hierarchical tree structures',
-  kanban: 'Kanban board — task/workflow columns',
-  c4: 'C4 diagram — system architecture (context, container, component, deployment)',
-  infra: 'Infra chart — infrastructure traffic flow with rps computation',
-  'boxes-and-lines':
-    'Boxes and lines — general-purpose node-edge diagrams with groups and tags',
-};
-
 const CLAUDE_SKILL_CONTENT = `# dgmo — Diagrammo Diagram Assistant
 
 You are helping the user author, render, and share diagrams using the \`dgmo\` CLI and \`.dgmo\` file format.