@zenuml/core 3.32.6 → 3.33.0

package/.claude/hooks/notify.sh

@@ -0,0 +1,103 @@
+#!/bin/bash
+# Claude Code notification hook script
+# Plays pleasant sounds when Claude needs input or completes tasks
+
+# Get the directory where this script is located
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SOUNDS_DIR="$SCRIPT_DIR/sounds"
+
+# Function to play a sound file with cross-platform support
+play_sound_file() {
+    local sound_file="$1"
+    
+    # Check if file exists
+    if [[ ! -f "$sound_file" ]]; then
+        echo "Warning: Sound file not found: $sound_file" >&2
+        return 1
+    fi
+    
+    # Detect OS and use appropriate command-line audio player
+    local os_type="$(uname -s)"
+    
+    case "$os_type" in
+        Darwin*)  # macOS
+            if command -v afplay &> /dev/null; then
+                afplay "$sound_file" 2>/dev/null &
+                return 0  # Exit immediately after starting playback
+            fi
+            ;;
+            
+        Linux*)   # Linux
+            # Try PulseAudio first (most common on modern desktop Linux)
+            if command -v paplay &> /dev/null; then
+                paplay "$sound_file" 2>/dev/null &
+                return 0  # Exit immediately after starting playback
+            fi
+            
+            # Try ALSA
+            if command -v aplay &> /dev/null; then
+                aplay -q "$sound_file" 2>/dev/null &
+                return 0  # Exit immediately after starting playback
+            fi
+            
+            # Try PipeWire (newer systems)
+            if command -v pw-play &> /dev/null; then
+                pw-play "$sound_file" 2>/dev/null &
+                return 0  # Exit immediately after starting playback
+            fi
+            
+            # Try sox play command
+            if command -v play &> /dev/null; then
+                play -q "$sound_file" 2>/dev/null &
+                return 0  # Exit immediately after starting playback
+            fi
+            ;;
+            
+        MINGW*|CYGWIN*|MSYS*)  # Windows (Git Bash, WSL, etc.)
+            # Try PowerShell
+            if command -v powershell.exe &> /dev/null; then
+                # Use Windows Media Player COM object for better compatibility
+                # Run in background and exit immediately
+                powershell.exe -NoProfile -Command "
+                    Start-Job -ScriptBlock {
+                        \$player = New-Object -ComObject WMPlayer.OCX
+                        \$player.URL = '$sound_file'
+                        \$player.controls.play()
+                        Start-Sleep -Milliseconds 1000
+                        \$player.close()
+                    }
+                " 2>/dev/null
+                return 0  # Exit immediately after starting playback
+            fi
+            ;;
+    esac
+    
+    # If we have ffplay (cross-platform)
+    if command -v ffplay &> /dev/null; then
+        ffplay -nodisp -autoexit -loglevel quiet "$sound_file" 2>/dev/null &
+        return 0  # Exit immediately after starting playback
+    fi
+    
+    # No audio player found - fail silently
+    return 1
+}
+
+# Main script logic
+case "$1" in
+    "input")
+        play_sound_file "$SOUNDS_DIR/input-needed.wav"
+        ;;
+        
+    "complete")
+        play_sound_file "$SOUNDS_DIR/complete.wav"
+        ;;
+        
+    *)
+        echo "Usage: $0 {input|complete}" >&2
+        echo "  input    - Play sound when Claude needs user input" >&2
+        echo "  complete - Play sound when Claude completes tasks" >&2
+        exit 1
+        ;;
+esac
+
+exit 0

package/.claude/hooks/setup/hook-setup.md

@@ -0,0 +1,96 @@
+## Description
+
+This command uses specialized agents to verify, configure, and test your Claude Code hooks installation. It ensures everything is properly set up and working correctly.
+
+## Process
+
+### Phase 1: Multi-Agent Setup Verification
+
+The command spawns specialized agents to handle different aspects:
+
+1. **Installation Agent**
+   - Verifies `.claude/hooks/` directory exists
+   - Checks all hook scripts are present
+   - Ensures executable permissions (`chmod +x`)
+   - Validates sound files and configuration files
+
+2. **Configuration Agent**
+   - Locates Claude Code settings.json for your OS
+   - Verifies hook configurations in settings
+   - Checks WORKSPACE environment variable
+   - Validates MCP server configurations
+
+3. **Documentation Agent**
+   - Ensures project structure documentation exists
+   - Verifies paths used by context injector
+   - Checks log directory setup
+
+### Phase 2: Comprehensive Testing
+
+After setup verification, the main agent runs comprehensive tests:
+
+1. **Security Scanner Tests**
+   - API key detection patterns
+   - Password and secret detection
+   - Whitelist functionality
+   - Command injection protection
+   - File scanning capabilities
+
+2. **Context Injector Tests**
+   - New session detection
+   - File attachment logic
+   - Path resolution
+   - Error handling scenarios
+
+3. **Notification Tests**
+   - Audio playback on current platform
+   - Fallback mechanism verification
+   - Both input and complete sounds
+
+## Expected Output
+
+```
+Starting multi-agent hook setup verification...
+
+[Installation Agent]
+✓ Hooks directory found: .claude/hooks/
+✓ All hook scripts present and executable
+✓ Configuration files valid
+✓ Sound files present
+
+[Configuration Agent]
+✓ Project settings found: .claude/settings.json
+✓ Hook configurations verified
+✓ WORKSPACE environment variable set correctly
+
+[Documentation Agent]
+✓ Project structure documentation found
+✓ Log directories configured
+
+Running comprehensive tests...
+
+[Security Scanner]
+✓ Detected: sk-1234567890abcdef (API key)
+✓ Detected: password=mysecret123
+✓ Allowed: YOUR_API_KEY (whitelisted)
+✓ Blocked: $(malicious) (injection attempt)
+
+[Context Injector]
+✓ New session handling correct
+✓ File attachment working
+✓ Error handling graceful
+
+[Notifications]
+✓ Audio playback successful
+✓ Platform: darwin (macOS)
+
+All hooks configured and tested successfully!
+```
+
+## Troubleshooting
+
+The command provides specific guidance for any issues found:
+- Missing files or permissions
+- Configuration problems
+- Test failures with debugging steps
+- Platform-specific audio issues

package/.claude/hooks/setup/settings.json.template

@@ -0,0 +1,63 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "mcp__gemini__consult_gemini",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${WORKSPACE}/.claude/hooks/gemini-context-injector.sh",
+            "description": "Automatically adds project structure to new Gemini sessions"
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${WORKSPACE}/.claude/hooks/mcp-security-scan.sh",
+            "description": "Scans for sensitive data before sending to external services"
+          }
+        ]
+      },
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${WORKSPACE}/.claude/hooks/subagent-context-injector.sh",
+            "description": "Automatically adds project context to sub-agent prompts"
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${WORKSPACE}/.claude/hooks/notify.sh input",
+            "description": "Plays sound when Claude needs user input"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": ".*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${WORKSPACE}/.claude/hooks/notify.sh complete",
+            "description": "Plays sound when Claude completes tasks"
+          }
+        ]
+      }
+    ]
+  },
+  "environment": {
+    "WORKSPACE": "/path/to/your/project"
+  }
+}

package/.claude/hooks/subagent-context-injector.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# Sub-Agent Context Auto-Loader
+# Automatically enhances Task tool prompts with essential project context
+#
+# This hook ensures every sub-agent spawned via the Task tool automatically
+# receives core project documentation, eliminating the need to manually
+# include context in each Task prompt.
+#
+# IMPLEMENTATION OVERVIEW:
+# - Registered as a PreToolUse hook in .claude/settings.json
+# - Intercepts all Task tool calls before execution
+# - Injects references to CLAUDE.md, project-structure.md, and docs-overview.md
+# - Preserves original prompt by prepending context, not replacing
+# - Passes through non-Task tools unchanged with {"continue": true}
+
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# Read input from stdin
+INPUT_JSON=$(cat)
+
+# Extract tool information
+tool_name=$(echo "$INPUT_JSON" | jq -r '.tool_name // ""')
+
+# Only process Task tool calls - pass through all other tools unchanged
+if [[ "$tool_name" != "Task" ]]; then
+    echo '{"continue": true}'
+    exit 0
+fi
+
+# Extract current prompt from the Task tool input
+current_prompt=$(echo "$INPUT_JSON" | jq -r '.tool_input.prompt // ""')
+
+# Build context injection header with project documentation references
+# These files are automatically available to all sub-agents via @ references
+context_injection="## Auto-Loaded Project Context
+
+This sub-agent has automatic access to the following project documentation:
+- @$PROJECT_ROOT/docs/CLAUDE.md (Project overview, coding standards, and AI instructions)
+- @$PROJECT_ROOT/docs/ai-context/project-structure.md (Complete file tree and tech stack)
+- @$PROJECT_ROOT/docs/ai-context/docs-overview.md (Documentation architecture)
+
+These files provide essential context about the project structure, 
+conventions, and development patterns. Reference them as needed for your task.
+
+---
+
+## Your Task
+
+"
+
+# Combine context injection with original prompt
+# The context is prepended to preserve the original task instructions
+modified_prompt="${context_injection}${current_prompt}"
+
+# Update the input JSON with the modified prompt
+# This maintains all other tool input fields unchanged
+output_json=$(echo "$INPUT_JSON" | jq --arg new_prompt "$modified_prompt" '.tool_input.prompt = $new_prompt')
+
+# Output the modified JSON for Claude Code to process
+# The Task tool will receive the enhanced prompt with context
+echo "$output_json"

package/.storybook/main.ts

@@ -0,0 +1,25 @@
+import type { StorybookConfig } from '@storybook/react-vite';
+
+const config: StorybookConfig = {
+  "stories": [
+    "../src/**/*.mdx",
+    "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"
+  ],
+  "addons": [
+    "@storybook/addon-docs",
+    "@storybook/addon-onboarding"
+  ],
+  "framework": {
+    "name": "@storybook/react-vite",
+    "options": {}
+  },
+  "typescript": {
+    "check": false,
+    "reactDocgen": "react-docgen-typescript",
+    "reactDocgenTypescriptOptions": {
+      "shouldExtractLiteralValuesFromEnum": true,
+      "propFilter": (prop) => (prop.parent ? !/node_modules/.test(prop.parent.fileName) : true),
+    },
+  },
+};
+export default config;

package/.storybook/preview.ts

@@ -0,0 +1,29 @@
+import type { Preview } from '@storybook/react-vite'
+import '../src/index.css'
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+       color: /(background|color)$/i,
+       date: /Date$/i,
+      },
+    },
+    backgrounds: {
+      default: 'light',
+      values: [
+        {
+          name: 'light',
+          value: '#ffffff',
+        },
+        {
+          name: 'dark',
+          value: '#333333',
+        },
+      ],
+    },
+    actions: { argTypesRegex: '^on[A-Z].*' },
+  },
+};
+
+export default preview;

package/MCP-ASSISTANT-RULES.md

@@ -0,0 +1,85 @@
+# MCP Assistant Rules - [Project Name]
+
+## Project Context
+[Brief description of what your project does and its main purpose. Keep it concise - 2-3 sentences max.]
+
+### Core Vision & Architecture
+- **Product Goal**: [Primary goal of your product]
+- **Target Platform**: [Primary platform(s) - web, mobile, desktop, etc.]
+- **Architecture**: [High-level architecture overview]
+- **Key Technologies**: [Main technologies/frameworks used]
+
+### Key Technical Principles
+[List 4-6 core technical principles that guide your project]
+- **Example**: Session-based architecture with clear boundaries
+- **Example**: API-first design with versioning from day one
+- **Example**: Security by default - validate all inputs at boundaries
+- **Example**: Observable systems with structured logging
+
+**Note:** The complete project structure and technology stack are provided in the attached `project-structure.md` file.
+
+## Key Project Standards
+
+### Core Principles
+[List your fundamental development principles]
+- Follow KISS, YAGNI, and DRY - prefer proven solutions over custom implementations
+- Never mock, use placeholders, or omit code - always implement fully
+- Be brutally honest about whether an idea is good or bad
+- [Add project-specific principles]
+
+### Code Organization
+[Define your code organization standards]
+- Keep files under [X] lines - split by extracting utilities, constants, types
+- Single responsibility per file with clear purpose
+- Prefer composition over inheritance
+- [Add language/framework specific organization rules]
+
+### [Language] Standards
+[Replace with your primary language and its standards]
+- Type safety requirements
+- Naming conventions (classes, functions, constants)
+- Documentation requirements (docstring style, required elements)
+- Error handling patterns
+
+### Error Handling & Logging
+- Use specific exceptions with helpful messages
+- Structured logging only - define your logging approach
+- [Specify logging categories or patterns]
+- Every request needs correlation ID for tracing
+
+### API Design
+[If applicable - define API standards]
+- RESTful with consistent URL patterns
+- Version from day one (/v1/, /v2/)
+- Consistent response format
+- Proper HTTP status codes
+
+### Security & State
+- Never trust external inputs - validate at boundaries
+- [Define session/state management approach]
+- [Specify data retention policies]
+- Keep secrets in environment variables only
+
+## Project-Specific Guidelines
+[Add any project-specific guidelines that AI assistants should know]
+
+### Domain-Specific Rules
+[Add rules specific to your problem domain]
+
+### Integration Points
+[List key integration points or external services]
+
+### Performance Considerations
+[Add any performance-critical aspects]
+
+## Important Constraints
+- You cannot create, modify, or execute code
+- You operate in a read-only support capacity
+- Your suggestions are for the primary AI (Claude Code) to implement
+- Focus on analysis, understanding, and advisory support
+
+## Quick Reference
+[Add frequently needed information]
+- Key commands: [List common commands]
+- Important paths: [List critical file paths]
+- Documentation links: [Add links to detailed docs]

package/README.md

@@ -19,7 +19,7 @@ You can use it ZenUML on your favorite platforms and applications:
 # Integrations
 
 ZenUML can be integrated with your favorite tools and platforms as a library or an embeddable widget.
-Please follow the [integration guide](./docs/asciidoc/integration-guide.adoc) for detailed steps.
+Please follow the [integration tutorial](./TUTORIAL.md) for detailed steps.
 
 # Development
 

package/TUTORIAL.md

@@ -0,0 +1,116 @@
+
+# ZenUML Integration Tutorial
+
+This tutorial provides a comprehensive guide on how to integrate ZenUML into your applications. There are two primary methods for integration: as a library or as an embedded iframe.
+
+## 1. As a Library
+
+This is the most flexible method, allowing for deep integration with your application.
+
+### Installation
+
+First, add the `@zenuml/core` package to your project:
+
+```bash
+npm install @zenuml/core
+```
+
+or
+
+```bash
+yarn add @zenuml/core
+```
+
+### Usage
+
+The main entry point of the library is the `ZenUml` class. Here's a basic example of how to use it:
+
+```javascript
+import ZenUml from '@zenuml/core';
+
+// 1. Get the container element
+const el = document.getElementById('zenuml-container');
+
+// 2. Create a new instance of ZenUml
+const zenUml = new ZenUml(el);
+
+// 3. Render a diagram
+const code = 'A->B: message';
+const config = {
+  theme: 'default',
+};
+zenUml.render(code, config);
+```
+
+### Configuration
+
+The `render` method accepts a configuration object with the following properties:
+
+- `theme`: The name of the theme to use. A list of available themes can be found in the documentation.
+- `enableScopedTheming`: A boolean that indicates whether to scope the theme to the container element. This is useful when you have multiple diagrams on the same page with different themes.
+- `onThemeChange`: A callback function that is called when the theme is changed.
+- `enableMultiTheme`: A boolean that indicates whether to enable multi-theme support.
+- `stickyOffset`: A number that indicates the offset for the sticky header.
+- `onContentChange`: A callback function that is called when the content of the diagram is changed.
+- `onEventEmit`: A callback function that is called when an event is emitted from the diagram.
+- `mode`: The rendering mode. Can be `RenderMode.Dynamic` or `RenderMode.Static`.
+
+### Example
+
+Here's a more advanced example that uses some of the configuration options:
+
+```javascript
+import ZenUml from '@zenuml/core';
+
+const el = document.getElementById('zenuml-container');
+const zenUml = new ZenUml(el);
+
+const code = `
+  // This is a comment
+  A->B: synchronous message
+  B-->A: asynchronous message
+`;
+
+const config = {
+  theme: 'blue',
+  enableScopedTheming: true,
+  onContentChange: (newCode) => {
+    console.log('Diagram code changed:', newCode);
+  },
+};
+
+zenUml.render(code, config);
+```
+
+### Exporting Diagrams
+
+You can export diagrams to PNG and SVG formats. The `ZenUml` class provides the following methods for exporting:
+
+- `getPng()`: Returns a promise that resolves to a PNG data URL.
+- `getSvg()`: Returns a promise that resolves to an SVG data URL.
+
+Here's an example of how to use these methods:
+
+```javascript
+import ZenUml from '@zenuml/core';
+
+const el = document.getElementById('zenuml-container');
+const zenUml = new ZenUml(el);
+
+const code = 'A->B: message';
+
+async function exportDiagram() {
+  await zenUml.render(code, { theme: 'default' });
+  const png = await zenUml.getPng();
+  // Do something with the PNG data URL
+  console.log(png);
+
+  const svg = await zenUml.getSvg();
+  // Do something with the SVG data URL
+  console.log(svg);
+}
+
+exportDiagram();
+```
+
+This tutorial should provide you with a solid foundation for integrating ZenUML into your applications. For more detailed information, please refer to the official documentation.