# Mermaid Format Schema — File Format Specification
# KNO Schema Version: 0.0.6
#
# Describes Mermaid as a diagram scripting language and file format.
# Mermaid is a JavaScript-based diagramming and charting tool that uses
# Markdown-inspired text definitions to create diagrams.
#
# OFFICIAL DOCS:
#   - Main Site: https://mermaid.js.org/
#   - Syntax Reference: https://mermaid.js.org/intro/syntax-reference.html
#   - GitHub: https://github.com/mermaid-js/mermaid
#   - Live Editor: https://mermaid.live/
#
# This schema enables .kno systems to understand, process, and render Mermaid diagrams.
# Per thin transformation principles, Mermaid can be converted to D2 for rendering.

# =============================================================================
# SCHEMA DECLARATION
# =============================================================================
$schema: kno@0.0.9

# =============================================================================
# BASIC TIER
# =============================================================================
id: 01KGK3V73NT7ENHE044A41XFXJ
slug: mermaid-format
type: spec
version: 0.2.0

# =============================================================================
# STANDARD TIER
# =============================================================================
title: "Mermaid Format Schema"
purpose: |
  Define Mermaid as a diagram format for .kno systems.

  **What is Mermaid?** Mermaid is a JavaScript-based diagramming and charting
  tool that renders Markdown-inspired text definitions to create and modify
  diagrams dynamically. It's widely used in documentation, GitHub, and wikis.

  **Why Support Mermaid in Possibility?**
  - **Ubiquity** — Native support in GitHub, GitLab, Notion, Obsidian
  - **Text-based** — Satisfies DC-3 (text-editor accessible)
  - **Git-friendly** — Human-readable diffs
  - **Import source** — Common format for existing diagrams
  - **Thin transformation** — Convertible to D2 for unified rendering

  **Key Features:**
  ```
  ┌─────────────────────────────────────────────────────────────────────────┐
  │  MERMAID DIAGRAM TYPES                                                  │
  ├─────────────────────────────────────────────────────────────────────────┤
  │  • Flowchart: flowchart TB/LR, graph TB/LR                              │
  │  • Sequence: sequenceDiagram                                            │
  │  • Class: classDiagram                                                  │
  │  • State: stateDiagram-v2                                               │
  │  • Entity Relationship: erDiagram                                       │
  │  • Gantt: gantt                                                         │
  │  • Pie: pie                                                             │
  │  • Mindmap: mindmap                                                     │
  │  • Timeline: timeline                                                   │
  └─────────────────────────────────────────────────────────────────────────┘
  ```

  **Thin Transformation Pattern:**
  Mermaid diagrams are parsed to DiagramElements (the domain layer), then
  rendered to D2 for final output. This follows the bedrock principle:
  Mermaid → diagram-schema → D2 (never Mermaid → D2 directly).

# =============================================================================
# RICH TIER — Relationships
# =============================================================================
provenance:
  origin:
    id: 01KGK3V73NT7ENHE044A41XFXJ
    timestamp: "2026-02-04T01:47:56Z"
    tool: manual-migration
taxonomy:
  topics:
    - file-formats
    - diagrams
    - visualization
    - developer-tools
  keywords:
    - mermaid
    - diagram
    - flowchart
    - sequence
    - markdown
    - javascript

relationships:
  depends_on:
    - xri: "kno://specs/kno-spec"
      reason: "Conforms to KNO format specification"

  produces:
    # Per bedrock § Bi-directional Produces Relationships:
    # Format schemas declare `produces` to their domain schema (NOT to other formats).
    # "Parsing Mermaid PRODUCES a diagram entity"
    - xri: "kno://specs/diagram-schema"
      reason: "Parsing Mermaid source produces DiagramElements (nodes, edges, containers)"

  related_to:
    - xri: "kno://specs/markdown-format"
      reason: "Mermaid uses Markdown-inspired syntax"
    - xri: "kno://specs/d2-format"
      reason: "Alternative diagram format with similar capabilities"

  enables:
    - xri: "kno://capabilities/diagram-rendering"
      reason: "Render Mermaid source via diagram-schema → D2 pipeline"
    - xri: "kno://capabilities/github-integration"
      reason: "Native rendering in GitHub markdown"

quality:
  completeness: 0.8
  last_reviewed: "2026-01-15"
  review_status: draft
  reviewed_by: "claude"

# =============================================================================
# HISTORY
# =============================================================================
_history:
  retention: full
  format: changelog

  changelog:
    - version: "0.2.0"
      date: "2026-01-15"
      author: "claude"
      summary: "Fix produces relationship to follow bedrock pattern"
      changes:
        - "Changed `produces: d2-format` to `produces: diagram-schema` (bedrock compliance)"
        - "Removed diagram-schema from related_to (now in produces)"
        - "Updated purpose text to document correct transformation path"
        - "Mermaid → diagram-schema → D2, not Mermaid → D2 directly"

    - version: "0.1.0"
      date: "2026-01-15"
      author: "claude"
      summary: "Initial Mermaid format schema"
      changes:
        - "Created from first principles"
        - "Referenced official Mermaid documentation"
        - "Defined diagram types and syntax"
        - "Established produces relationship to d2-format"

# =============================================================================
# SPECIFICATION CONTENT
# =============================================================================
spec:
  status: Draft

  # ---------------------------------------------------------------------------
  # Official Standards References
  # ---------------------------------------------------------------------------
  standards:
    - name: "Mermaid Documentation"
      url: "https://mermaid.js.org/"
      author: "Mermaid Team"
      year: 2019
      description: |
        Official Mermaid documentation and syntax reference.
        Mermaid is "a JavaScript-based diagramming and charting tool."

    - name: "Mermaid Syntax Reference"
      url: "https://mermaid.js.org/intro/syntax-reference.html"
      description: |
        Complete syntax reference for all Mermaid diagram types.

    - name: "Mermaid GitHub Repository"
      url: "https://github.com/mermaid-js/mermaid"
      description: |
        Open-source Mermaid library. MIT licensed.

    - name: "Mermaid Live Editor"
      url: "https://mermaid.live/"
      description: |
        Interactive editor for creating and previewing Mermaid diagrams.

  # ---------------------------------------------------------------------------
  # Format Definition
  # ---------------------------------------------------------------------------
  format:
    name: "Mermaid"
    mime_type: "text/plain"
    extensions:
      - ".mmd"
      - ".mermaid"
    encoding: "UTF-8"
    line_endings:
      - "LF" # Unix (preferred)
      - "CRLF" # Windows (accepted)

  # ---------------------------------------------------------------------------
  # Diagram Types
  # ---------------------------------------------------------------------------
  diagram_types:
    flowchart:
      description: "Flow diagrams with nodes and edges"
      keywords: ["flowchart", "graph"]
      directions: ["TB", "BT", "LR", "RL"]
      examples:
        - |
          flowchart TB
            A[Start] --> B{Decision}
            B -->|Yes| C[Action]
            B -->|No| D[End]

    sequence:
      description: "Sequence diagrams for interactions"
      keyword: "sequenceDiagram"
      examples:
        - |
          sequenceDiagram
            Alice->>Bob: Hello
            Bob-->>Alice: Hi there

    class:
      description: "UML class diagrams"
      keyword: "classDiagram"
      examples:
        - |
          classDiagram
            Animal <|-- Duck
            Animal : +int age
            Animal : +String gender
            Animal: +isMammal()

    state:
      description: "State machine diagrams"
      keyword: "stateDiagram-v2"
      examples:
        - |
          stateDiagram-v2
            [*] --> Still
            Still --> Moving
            Moving --> Still

    er:
      description: "Entity relationship diagrams"
      keyword: "erDiagram"
      examples:
        - |
          erDiagram
            CUSTOMER ||--o{ ORDER : places
            ORDER ||--|{ LINE-ITEM : contains

  # ---------------------------------------------------------------------------
  # Syntax Elements
  # ---------------------------------------------------------------------------
  syntax:
    nodes:
      description: "Node shapes and labels"
      shapes:
        - pattern: "id[Label]"
          shape: "rectangle"
        - pattern: "id(Label)"
          shape: "rounded"
        - pattern: "id{Label}"
          shape: "diamond"
        - pattern: "id([Label])"
          shape: "stadium"
        - pattern: "id[[Label]]"
          shape: "subroutine"
        - pattern: "id[(Label)]"
          shape: "cylinder"
        - pattern: "id((Label))"
          shape: "circle"

    edges:
      description: "Connection types"
      types:
        - pattern: "-->"
          style: "solid arrow"
        - pattern: "---"
          style: "solid line"
        - pattern: "-.->"
          style: "dotted arrow"
        - pattern: "-.-"
          style: "dotted line"
        - pattern: "==>"
          style: "thick arrow"
        - pattern: "==="
          style: "thick line"

    subgraphs:
      description: "Group nodes in subgraphs"
      syntax: |
        subgraph title
          node1
          node2
        end

  # ---------------------------------------------------------------------------
  # Thin Transformation: Mermaid → DiagramElements → D2
  # ---------------------------------------------------------------------------
  transformation:
    target: "diagram-schema"
    approach: "thin"
    description: |
      Mermaid diagrams are parsed to DiagramElements (the domain layer),
      which are then rendered to D2 for output. This follows the bedrock
      principle: Mermaid → diagram-schema → D2 (never direct format-to-format).

      **Pipeline:**
      1. parseMermaidFlowchart(source) → DiagramElements
      2. renderElementsToD2(elements) → D2 source
      3. renderD2ToSvg(d2Source) → SVG output

      **Styling:** The renderer outputs D2 with styling from the Forks style
      guide config. Visual presentation is applied at the D2 render stage.

    mapping:
      # These mappings show semantic equivalence, not direct conversion.
      # Implementation extracts to DiagramElements, then renders to D2.
      nodes:
        "id[Label]": "node with id and label"
        "id(Label)": "node with oval shape"
        "id{Label}": "node with diamond shape"
        "id((Label))": "node with circle shape"
        "id[[Label]]": "node with rectangle shape"

      edges:
        "A --> B": "edge from A to B"
        "A --- B": "undirected edge"
        "A ==> B": "thick edge"
        "A -.-> B": "dotted edge"
        "A -->|label| B": "labeled edge"

      subgraphs:
        "subgraph X ... end": "X: { ... }"

      directions:
        "TB": "direction: down"
        "BT": "direction: up"
        "LR": "direction: right"
        "RL": "direction: left"

    styling:
      approach: "template-based"
      template: "d2-forks-style-template"
      description: |
        Mermaid styling directives (classDef, style) are NOT converted.
        All visual styling is delegated to the D2 style template.
      rationale: |
        - Consistent appearance across all diagram sources
        - Single source of styling truth (template)
        - Simpler converter (structure only, no style mapping)
        - Easy to update styling by changing template

# =============================================================================
# ANNOTATIONS
# =============================================================================
annotations:
  - key: bedrock-compliance
    value: |
      This schema satisfies:
      - DC-3: Text-editor accessible (plain text format)
      - Thin transformation: Produces D2, inferred from schema graph
      - Format singularity: Mermaid source stored in .kno content field

  - key: import-relevance
    value: |
      Mermaid is a priority import format because:
      - Widely used in GitHub repositories
      - Common in documentation (README, wikis)
      - Supported by many note-taking apps (Notion, Obsidian)
      - Users may have existing diagram libraries in Mermaid

  - key: rendering-pipeline
    value: |
      Mermaid → D2 → SVG
      The thin transformation converts Mermaid to D2 syntax,
      then the existing D2 renderer produces the final SVG.
      This avoids duplicating rendering infrastructure.