# Neva To Mermaid

> Convert Neva programs to valid Mermaid flowchart diagrams. Use when asked to visualize Neva code as Mermaid.

- Skill: `nevalang/neva-to-mermaid` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nevalang/neva-to-mermaid`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nevalang/neva-to-mermaid/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: nevalang (https://skillmd.com/u/nevalang)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nevalang/neva-to-mermaid

---


# Neva to Mermaid

Use this skill to convert any Neva source code into a Mermaid flowchart.

## Instructions

1. Read the Neva code to be converted.
2. Generate a Mermaid `flowchart TB` diagram using the following rules:

   - **Layout**: Always include this header at the top:
     ```mermaid
     ---
     config:
       layout: elk
     ---
     flowchart TB
     ```

   - **Ports**:
     - Use **stadium** shapes for external ports `:in` / `:out`:
       - `([":data"])`, `([":res"])`, `([":err"])`, etc.
     - In edges, label with the **port name** (`data`, `res`, `err`, `sig`, `case[0]`, etc).

   - **Components**:
     - Use unique Mermaid node IDs.
     - Render component nodes as regular boxes using only their declared
       instance name: `id["name"]`.
     - Do not annotate component nodes with type names, generic parameters, or
       usage information.

   - **Literals**:
     - Render numeric and string literals as rectangles using Mermaid shape syntax:
       - `zero@{ label: "0", shape: rect }`
       - `dot@{ label: "'.'", shape: rect }`

   - **Connections**:
     - Use `-- <port> -->` labels for the wire’s port name.
     - For `a:out -> b:in`, label the edge with the **output port name** (`out`), unless Neva explicitly uses the input port name in the wiring (e.g., `b:sig`).
     - Only label an edge with a port name when the Neva source explicitly names a port on that connection.
       - Examples that MUST be labeled:
       - `x:res -> y` → label edge as `res`
       - `x -> y:sig` → label edge as `sig`
       - `x:case[0] -> y` → label edge as `case[0]`
    - If a port name is **omitted** in Neva, do **not** infer or guess it. Render an unlabeled edge:
       - `x -> y` → `x --> y`

   - **Fan-out / Fan-in (IMPORTANT)**:
     - Mermaid edges do not create real “ports as objects”, so list-wiring must be represented explicitly with **virtual junction nodes**.
     - A junction node is a small circle: `jX(( ))` where `jX` is a unique ID.

     **Fan-out**: `src -> [a, b, :out]`
     - Insert a junction node `jX(( ))`.
     - Wire: `src -- <port> --> jX`
     - Then wire: `jX --> a`, `jX --> b`, `jX --> out_port`

     **Fan-in**: `[a, b] -> dst:port`
     - Insert a junction node `jX(( ))`.
     - Wire: `a --> jX` and `b --> jX`
     - Then wire: `jX -- <port> --> dst`

   - **Grouping (`&`)**:
     - You MAY use `&` to reduce clutter only when it does **not** hide fan-in/fan-out topology.
     - If Neva uses list-wiring (`[...]`), prefer junction nodes over `&`.

3. Do not look up other files in the repo or call web search; this text
   describes the conversion rules.
4. Ensure the output is ready to be pasted into the Mermaid playground.

## Reference Example

### Neva

```neva
pub def Tap<T>(data T) (res T, err error) {
    pass1 Pass<T>
    pass2 Pass<T>
    lock Lock<T>
    handler ITapHandler<T>
    ---
    :data -> [lock:data, handler]
    handler:res -> pass1
    handler:err -> [pass2, :err]
    [pass1, pass2] -> lock:sig
    lock -> :res
}