merman: Instructions file for Codex

Agents Guide

Orientation for AI assistants and humans dropping into this repo. Keep this in sync with the actual layout — tests and consumers depend on the public surface described here.

What this package is

merman parses a small Mermaid-flavored DSL and renders three diagram families to the terminal:

• Flowchart — boxed nodes, routed edges, subgraphs, animated pulses
• State — composite states, nested regions, active-transition highlighting
• Sequence — participants, messages, notes, fragments, activations

Each family has three rendering paths:

1. Plain text (renderXDiagram) — uncolored grid, ideal for tests
2. ANSI (renderXDiagramAnsi) — colored string for direct terminal print
3. OpenTUI Renderable (XDiagramRenderable) — live, themeable, interactive

@opentui/core is a peer dependency. We do not own renderable primitives, the CLI loop, or styled text — we own diagram parsing, layout, routing, and the diagram-specific rendering pipeline.

Source layout

src/
├── index.ts             # Single public entrypoint (re-exports flowchart/state/sequence)
├── cli/                 # Bun CLI output and source-comment transforms
│   ├── main.ts          #   Args, diagram dispatch, terminal/doc-comment output
│   ├── doc-comment.ts   #   TypeScript /** ... */ formatting
│   └── replace.ts       #   Inline Mermaid fences -> rendered TS or Markdown lines
├── flowchart/           # Flowchart pipeline
│   ├── parser.ts        #   Mermaid string -> FlowchartDiagram
│   ├── layout.ts        #   FlowchartDiagram -> placed bounds/routes
│   ├── routing.ts       #   Edge routing on the diagram grid
│   ├── labels.ts        #   Edge label placement
│   ├── render.ts        #   Plain/ANSI rendering facade
│   ├── drawing.ts       #   FlowchartDiagram -> styled diagram grid
│   ├── style.ts         #   Themes, color keys
│   ├── options.ts       #   Public option types
│   ├── renderable.ts    #   FlowchartDiagramRenderable (OpenTUI)
│   ├── types.ts         #   Public data model
│   └── index.ts         #   Public re-exports for this family
├── state/               # State diagrams
│   ├── parser.ts        #   Mermaid string -> StateDiagram
│   ├── visible-model.ts #   StateDiagram -> visible transitions/states for drawing
│   ├── layout.ts        #   StateDiagram -> placed bounds
│   ├── routing.ts       #   Visible State transitions -> route kinds for drawing
│   ├── drawing.ts       #   StateDiagram -> styled diagram grid
│   ├── style.ts         #   Themes, colors, pulse style ramps
│   ├── render-grid.ts   #   Grid -> string / ANSI / StyledText
│   ├── diagram.ts       #   Plain/ANSI rendering facade
│   ├── renderable.ts    #   StateDiagramRenderable (OpenTUI)
│   ├── options.ts       #   Defaults and option normalization
│   ├── types.ts         #   Public data model and options
│   └── index.ts         #   Public re-exports for this family
├── sequence/            # Sequence diagrams
│   ├── parser.ts        #   Mermaid string -> SequenceDiagram
│   ├── placement.ts     #   SequenceDiagram -> static participant/step placement plan
│   ├── drawing.ts       #   SequenceDiagram -> styled diagram grid
│   ├── style.ts         #   Themes, colors, pulse style ramps
│   ├── render-grid.ts   #   Grid -> string / ANSI / StyledText
│   ├── diagram.ts       #   Plain/ANSI rendering facade
│   ├── renderable.ts    #   SequenceDiagramRenderable (OpenTUI)
│   ├── options.ts       #   Defaults and option normalization
│   ├── types.ts         #   Public data model and options
│   └── index.ts         #   Public re-exports for this family
├── core/                # Package-internal primitives, NOT publicly exported
│   ├── canvas.ts        #   DiagramCanvas: 2D char grid abstraction
│   ├── geometry.ts      #   Boxes, points, intersection helpers
│   ├── drawing.ts       #   Box / line drawing primitives
│   ├── render-grid.ts   #   Grid -> string / ANSI / StyledText
│   ├── text.ts          #   Width-aware text helpers (string-width)
│   ├── text-lines.ts    #   Wrapping / line splitting
│   ├── mermaid.ts       #   Shared Mermaid line tokenization
│   ├── adapter/         #   OpenTUI color parsing and renderable invalidation pipeline
│   ├── animation/       #   Pulse animation core (frame counter, cell styling)
│   ├── color/           #   Color ramps, theme maps, fade levels
│   └── terminal/        #   ANSI escape helpers
└── test/                # Cross-cutting integrity tests + shared test helpers