Skip to content

PIDL v0.3.0 Release Notes

Release Date: 2025-05-18

This release introduces native SVG rendering capabilities including static sequence diagrams, animated flow visualizations with moving dots, and network boundary diagrams for security architecture visualization.

Highlights

  • Native SVG rendering with static sequence diagrams, animated flow visualizations, and network boundary diagrams
  • CSS animation support with per-message control and semantic presets (request, success, error, warning, highlight)
  • Template system with 5 built-in styles: default, minimal, sketch, blueprint, dark
  • Network boundary diagrams for visualizing trust zones and security boundaries

What's New

SVG Sequence Diagrams

Generate self-contained SVG sequence diagrams directly from PIDL:

# Static SVG sequence diagram
pidl generate -f svg oauth2_pkce

# Animated SVG with flow dots
pidl generate -f svg-animated oauth2_pkce

Features:

  • Light and dark theme support via --theme flag
  • CSS custom properties for easy styling
  • Print-friendly output with animation fallback

Animated Flow Visualization

CSS-based animations show data flow with moving dots along message paths:

pidl generate -f svg-animated --theme=dark oauth2_pkce

Animation features:

  • offset-path CSS animations for smooth dot movement
  • Configurable duration, delay, and easing
  • Print media query disables animations automatically

Per-Message Animation Control

Control animation on individual flows with the animation field:

{
  "flows": [
    {
      "from": "client",
      "to": "server",
      "action": "request",
      "animation": {
        "enabled": true,
        "preset": "request",
        "duration": "1.5s",
        "dot_color": "#3182ce"
      }
    }
  ]
}

Semantic Animation Presets

Use semantic presets for consistent styling:

Preset Color Effect Use Case
request Blue Standard Outgoing requests
success Green Standard Successful operations
error Red Pulse Errors, failures
warning Orange Pulse Warnings
highlight Yellow Glow Critical path
none N/A Static No animation 
{
  "from": "server",
  "to": "client",
  "action": "error",
  "animation": "error"
}

SVG Template System

Choose from 5 built-in templates:

pidl generate -f svg --template=sketch oauth2_pkce
pidl generate -f svg-animated --template=blueprint oauth2_pkce
Template Description
default Clean, professional styling
minimal Ultra-clean, reduced chrome
sketch Hand-drawn, informal look
blueprint Technical with monospace fonts
dark Dark background optimized

Custom templates from directory:

pidl generate -f svg --template-dir=./my-template protocol.json

Network Boundary Diagrams

Visualize protocols with trust zone boundaries:

pidl generate -f svg-network oauth2_pkce

Features:

  • Automatic boundary inference from entity.metadata.network
  • Explicit boundary configuration via metadata.networks
  • Four boundary styles: trusted, dmz, external, cloud
  • Horizontal and vertical layout directions
  • Cross-boundary connection highlighting

CLI boundary overrides:

pidl generate -f svg-network \
  --boundary="dmz:auth_server,gateway" \
  --boundary="internal:api,database" \
  protocol.json

PIDL Schema Extensions

New metadata types for SVG features:

{
  "entities": [
    {
      "id": "api",
      "name": "Backend API",
      "metadata": {
        "network": "internal"
      }
    }
  ],
  "metadata": {
    "networks": {
      "internal": {
        "name": "Internal Network",
        "style": "trusted"
      },
      "dmz": {
        "name": "DMZ",
        "style": "dmz"
      }
    },
    "network_layout": {
      "direction": "horizontal",
      "order": ["external", "dmz", "internal"]
    },
    "animation": {
      "default_enabled": true,
      "default_duration": "2s",
      "stagger": "0.3s"
    }
  }
}

CLI Enhancements

New flags for SVG generation:

Flag Description
--template SVG template name (default, minimal, sketch, blueprint, dark)
--template-dir Path to custom template directory
--theme SVG theme (light, dark, auto)
--boundary Network boundary assignment (repeatable)

Updated format options:

Formats:
  svg              SVG sequence diagram
  svg-animated     Animated SVG with flow dots
  svg-network      Network boundary diagram

Migration

Existing PIDL files remain fully compatible. New fields (entity.metadata, protocol.metadata, flow.animation) are optional.

Documentation

License

MIT License