%% Bad
end --> start

%% Good
endState --> startState

%% Bad — unescaped quotes
A["She said "hello""]

%% Good — use single quotes inside double, or HTML entities
A["She said 'hello'"]
A["She said "hello""]

%% Bad — backslash in labels
A[C:\Users\path]

%% Good — use forward slash or quote the label
A["C:\Users\path"]

%% Bad — empty node
A[] --> B

%% Good
A[Start] --> B[End]

%% Bad — empty subgraph
subgraph Group
end

%% Good
subgraph Group
    A[Content]
end

%% Use line breaks
A["Order Processing<br/>Service"]

%% Shorten labels
A["Order Svc"]

%% For sequence diagrams, use aliases
participant OrderSvc as Order Processing Service

%% Bad — subgraph must have content
subgraph Empty
end

%% Good — needs at least one node
subgraph Group["Service Layer"]
    A[Service A]
end

%% Bad — nested subgraph direction before content
subgraph Parent
    direction LR
end

%% Good — direction followed by nodes
subgraph Parent
    direction LR
    A --> B
end

# Re-run setup
bash $SKILL_DIR/scripts/setup.sh

# Check file encoding
file diagram.mmd
# Should say: UTF-8 Unicode text

# Validate first
node $SKILL_DIR/scripts/validate.mjs diagram.mmd

# Check if installed
npx mmdc --version

# If not, install
npm install -g @mermaid-js/mermaid-cli

# Or use npx (no global install)
npx -y @mermaid-js/mermaid-cli -i input.mmd -o output.svg

# Install Chromium for puppeteer
npx puppeteer browsers install chrome

# Or set custom path
export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser

# Or use puppeteer config
echo '{"args": ["--no-sandbox"]}' > puppeteer-config.json
npx mmdc -i input.mmd -o output.svg -p puppeteer-config.json

%% Bad — activate without deactivate
A->>+B: Request
B->>C: Forward

%% Good — always pair +/-
A->>+B: Request
B-->>-A: Response

%% Bad — wrong cardinality syntax
USER --o{ ORDER

%% Good — must include both sides
USER ||--o{ ORDER : "places"

%% Bad — missing label
USER ||--o{ ORDER

%% Good — relationship label is required
USER ||--o{ ORDER : "places"

%% Bad — missing quotes around parameters
Container(api, API, NestJS, Backend service)

%% Good — all text parameters in quotes
Container(api, "API", "NestJS", "Backend service")

%% Bad — wrong boundary nesting
Container_Boundary(app, "App") {
    System(sys, "External")  %% System inside Container boundary
}

%% Good — use appropriate element types for context
Container_Boundary(app, "App") {
    Component(cmp, "Internal Component", "Tech", "Desc")
}

%% Bad — wrong format
dateFormat DD-MM-YYYY

%% Good — supported formats
dateFormat YYYY-MM-DD
%% or
dateFormat DD/MM/YYYY
%% or
dateFormat X  (Unix timestamp)

%% Problematic — direct circular
A --> B --> A

%% Still valid but may cause layout issues. Fix by adding direction:
flowchart LR
    A --> B
    B --> A  %% Renders as two arrows between A and B

%% Bad — missing initial state in composite
state Active {
    Running --> Paused
}

%% Good — composite states need initial transition
state Active {
    [*] --> Running
    Running --> Paused
}

# Use the --icons flag to register icon packs
node $SKILL_DIR/scripts/render.mjs --input diagram.mmd --output diagram.svg --icons logos

# Or use built-in icons as fallback (no registration needed)
# Replace: service api(logos:aws-api-gateway)[API Gateway]
# With:    service api(server)[API Gateway]

%% Add to the END of every C4 diagram, after all Rel() definitions
%% Apply to EACH Rel() with soft colors
UpdateRelStyle(from, to, $textColor="#475569", $lineColor="#94a3b8")

%% Add offsets when labels overlap elements
UpdateRelStyle(from, to, $textColor="#475569", $lineColor="#94a3b8", $offsetY="-10")

%% Spread out elements
UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

%%{init: {'theme': 'base', 'themeVariables': {
  'lineColor': '#94a3b8'
}}}%%

%%{init: {'theme': 'base', 'themeVariables': {...}}}%%
flowchart LR
    A --> B

flowchart LR
%%{init: {'theme': 'base', 'themeVariables': {...}}}%%  %% THIS WILL NOT WORK
    A --> B

# Update the validation script's dependency
cd $SKILL_DIR && npm update mermaid

# Or skip validation and render directly (rendering validates implicitly)
node $SKILL_DIR/scripts/render.mjs --input diagram.mmd --output test.svg

# Reduce workers
node $SKILL_DIR/scripts/batch.mjs --workers 1

# Increase timeout (ms)
node $SKILL_DIR/scripts/batch.mjs --timeout 60000

# Process problematic files individually to isolate the issue

%% BAD — these fonts don't exist in headless Chromium
%%{init: {'theme': 'base', 'themeVariables': {
  'fontFamily': 'system-ui, -apple-system, sans-serif'
}}}%%

%% GOOD — use Mermaid defaults (don't set fontFamily at all)
%%{init: {'theme': 'base', 'themeVariables': {
  'primaryColor': '#4f46e5', 'lineColor': '#94a3b8'
}}}%%

%% GOOD — if you must set a font, use web-safe ones
%%{init: {'theme': 'base', 'themeVariables': {
  'fontFamily': 'trebuchet ms, verdana, arial, sans-serif'
}}}%%