@zenuml/core 3.32.6 → 3.32.7

package/docs/ai-context/handoff.md

@@ -0,0 +1,174 @@
+# Task Management & Handoff Template
+
+This file manages task continuity, session transitions, and knowledge transfer for AI-assisted development sessions.
+
+## Purpose
+
+This template helps maintain:
+- **Session continuity** between AI development sessions
+- **Task status tracking** for complex, multi-session work
+- **Context preservation** when switching between team members
+- **Knowledge transfer** for project handoffs
+- **Progress documentation** for ongoing development efforts
+
+## Current Session Status
+
+### Active Tasks
+Document currently in-progress work:
+
+```markdown
+## In Progress
+- [ ] Task 1: [Brief description]
+  - Status: [Started/Blocked/Awaiting review]
+  - Context: [Relevant files, decisions made]
+  - Next steps: [What needs to be done next]
+  - Dependencies: [What this task depends on]
+
+- [ ] Task 2: [Brief description]
+  - Status: [Current status]
+  - Files modified: [List of files changed]
+  - Challenges: [Any issues encountered]
+  - Notes: [Important context for continuation]
+```
+
+### Pending Tasks
+Document queued work:
+
+```markdown
+## Pending
+- [ ] Task A: [Description]
+  - Priority: [High/Medium/Low]
+  - Dependencies: [What must be completed first]
+  - Estimated effort: [Time estimate]
+  - Context: [Background information]
+
+- [ ] Task B: [Description]
+  - Priority: [Priority level]
+  - Requirements: [Specific requirements or constraints]
+  - Resources needed: [Tools, access, information needed]
+```
+
+### Completed Tasks
+Track completed work for context:
+
+```markdown
+## Completed This Session
+- [x] Task X: [Description]
+  - Completed: [Date]
+  - Outcome: [What was accomplished]
+  - Files changed: [Modified files]
+  - Notes: [Important decisions or lessons learned]
+
+- [x] Task Y: [Description]
+  - Completed: [Date]
+  - Impact: [How this affects other tasks]
+  - Follow-up needed: [Any follow-up actions required]
+```
+
+## Architecture & Design Decisions
+
+### Recent Decisions
+Document architectural decisions made during development:
+
+```markdown
+## Design Decisions Made
+- **Decision**: [What was decided]
+  - Date: [When decision was made]
+  - Rationale: [Why this approach was chosen]
+  - Alternatives considered: [Other options evaluated]
+  - Impact: [How this affects the system]
+  - Validation: [How to verify this was the right choice]
+
+- **Decision**: [Another decision]
+  - Context: [Situation that led to this decision]
+  - Trade-offs: [What was gained/lost with this choice]
+  - Dependencies: [What this decision depends on]
+```
+
+### Technical Debt & Issues
+Track technical debt and known issues:
+
+```markdown
+## Technical Debt Identified
+- **Issue**: [Description of technical debt]
+  - Location: [Where in codebase]
+  - Impact: [How it affects development/performance]
+  - Proposed solution: [How to address it]
+  - Priority: [When should this be addressed]
+
+- **Issue**: [Another issue]
+  - Root cause: [Why this debt exists]
+  - Workaround: [Current mitigation strategy]
+  - Long-term fix: [Proper solution approach]
+```
+
+## Next Session Goals
+
+### Immediate Priorities
+Define what should be tackled next:
+
+```markdown
+## Next Session Priorities
+1. **Primary Goal**: [Main objective for next session]
+   - Success criteria: [How to know this is complete]
+   - Prerequisites: [What must be ready beforehand]
+   - Estimated effort: [Time estimate]
+
+2. **Secondary Goal**: [Secondary objective]
+   - Dependencies: [What this depends on]
+   - Resources needed: [Tools, information, access required]
+
+3. **If Time Permits**: [Optional tasks]
+   - Context: [Background on why these are valuable]
+   - Preparation: [What needs to be done to start these]
+```
+
+### Knowledge Gaps
+Document areas needing research or clarification:
+
+```markdown
+## Knowledge Gaps to Address
+- **Question**: [What needs to be clarified]
+  - Impact: [How this affects current work]
+  - Research needed: [What investigation is required]
+  - Decision maker: [Who can answer this]
+
+- **Unknown**: [Technical uncertainty]
+  - Options: [Possible approaches to explore]
+  - Experiments: [What should be tested]
+  - Timeline: [When this needs to be resolved]
+```
+
+## Context for Continuation
+
+### Key Files & Components
+Document important files for session continuity:
+
+```markdown
+## Files Currently Being Modified
+- `[file-path]`: [Purpose and current changes]
+- `[file-path]`: [What's being implemented here]
+- `[file-path]`: [Status and next steps]
+
+## Important Context Files
+- `[context-file]`: [Why this is relevant]
+- `[documentation]`: [What information this contains]
+- `[reference]`: [How this relates to current work]
+```
+
+### Development Environment
+Document environment and setup considerations:
+
+```markdown
+## Environment Status
+- **Development setup**: [Current state of dev environment]
+- **Database**: [Schema changes, migrations, data state]
+- **External services**: [API keys, service configurations]
+- **Testing**: [Test suite status, coverage, failing tests]
+- **Build/Deploy**: [Build status, deployment considerations]
+```
+
+
+---
+
+*This template provides a comprehensive framework for managing task continuity and knowledge transfer. Customize it based on your team's workflow, project complexity, and communication needs.*

package/docs/ai-context/project-structure.md

@@ -0,0 +1,160 @@
+# Project Structure Template
+
+This document provides a template for documenting the complete technology stack and file tree structure for your project. **AI agents MUST read this file to understand the project organization before making any changes.**
+
+## Technology Stack Template
+
+### Backend Technologies
+Document your backend technology choices:
+- **[Language] [Version]** with **[Package Manager]** - Dependency management and packaging
+- **[Web Framework] [Version]** - Web framework with specific features (async, type hints, etc.)
+- **[Server] [Version]** - Application server configuration
+- **[Configuration] [Version]** - Configuration management approach
+
+Example:
+```
+- Python 3.11+ with Poetry - Dependency management and packaging
+- FastAPI 0.115.0+ - Web framework with type hints and async support
+- Uvicorn 0.32.0+ - ASGI server with standard extras
+- Pydantic Settings 2.5.2+ - Configuration management with type validation
+```
+
+### Integration Services & APIs
+Document external services and integrations:
+- **[Service Name] [API/SDK Version]** - Purpose and usage pattern
+- **[AI Service] [Version]** - AI/ML service integration details
+- **[Database] [Version]** - Data storage and management
+- **[Monitoring] [Version]** - Observability and logging
+
+### Real-time Communication
+Document real-time features:
+- **[WebSocket Library]** - Real-time communication patterns
+- **[HTTP Client]** - Async HTTP communication
+- **[Message Queue]** - Event processing (if applicable)
+
+### Development & Quality Tools
+Document development toolchain:
+- **[Formatter] [Version]** - Code formatting
+- **[Linter] [Version]** - Code quality and linting
+- **[Type Checker] [Version]** - Static type checking
+- **[Testing Framework] [Version]** - Testing approach
+- **[Task Runner]** - Build automation and task orchestration
+
+### Frontend Technologies (if applicable)
+Document frontend technology stack:
+- **[Language] [Version]** - Frontend development language
+- **[Framework] [Version]** - UI framework
+- **[Build Tool] [Version]** - Development and build tooling
+- **[Deployment] [Version]** - Deployment and hosting approach
+
+### Future Technologies
+Document planned technology additions:
+- **[Planned Technology]** - Future integration plans
+- **[Platform]** - Target platform expansion
+- **[Service]** - Planned service integrations
+
+## Complete Project Structure Template
+
+```
+[PROJECT-NAME]/
+├── README.md                           # Project overview and setup
+├── CLAUDE.md                           # Master AI context file
+├── [BUILD-FILE]                        # Build configuration (Makefile, package.json, etc.)
+├── .gitignore                          # Git ignore patterns
+├── .[IDE-CONFIG]/                      # IDE workspace configuration
+│   ├── settings.[ext]                  # IDE settings
+│   ├── extensions.[ext]                # Recommended extensions
+│   └── launch.[ext]                    # Debug configurations
+├── [BACKEND-DIR]/                      # Backend application
+│   ├── CONTEXT.md                      # Backend-specific AI context
+│   ├── src/                            # Source code
+│   │   ├── config/                     # Configuration management
+│   │   │   └── settings.[ext]          # Application settings
+│   │   ├── core/                       # Core business logic
+│   │   │   ├── CONTEXT.md              # Core logic patterns
+│   │   │   ├── services/               # Business services
+│   │   │   │   ├── [service1].[ext]    # Service implementations
+│   │   │   │   └── [service2].[ext]
+│   │   │   ├── models/                 # Data models
+│   │   │   │   ├── [model1].[ext]      # Model definitions
+│   │   │   │   └── [model2].[ext]
+│   │   │   └── utils/                  # Utility functions
+│   │   │       ├── logging.[ext]       # Structured logging
+│   │   │       ├── validation.[ext]    # Input validation
+│   │   │       └── helpers.[ext]       # Helper functions
+│   │   ├── api/                        # API layer
+│   │   │   ├── CONTEXT.md              # API patterns and conventions
+│   │   │   ├── routes/                 # API route definitions
+│   │   │   │   ├── [resource1].[ext]   # Resource-specific routes
+│   │   │   │   └── [resource2].[ext]
+│   │   │   ├── middleware/             # API middleware
+│   │   │   │   ├── auth.[ext]          # Authentication middleware
+│   │   │   │   ├── logging.[ext]       # Request logging
+│   │   │   │   └── validation.[ext]    # Request validation
+│   │   │   └── schemas/                # Request/response schemas
+│   │   │       ├── [schema1].[ext]     # Data schemas
+│   │   │       └── [schema2].[ext]
+│   │   └── integrations/               # External service integrations
+│   │       ├── CONTEXT.md              # Integration patterns
+│   │       ├── [service1]/             # Service-specific integration
+│   │       │   ├── client.[ext]        # API client
+│   │       │   ├── models.[ext]        # Integration models
+│   │       │   └── handlers.[ext]      # Response handlers
+│   │       └── [service2]/
+│   ├── tests/                          # Test suite
+│   │   ├── unit/                       # Unit tests
+│   │   ├── integration/                # Integration tests
+│   │   └── fixtures/                   # Test fixtures and data
+│   ├── [PACKAGE-FILE]                  # Package configuration
+│   └── [ENV-FILE]                      # Environment configuration
+├── [FRONTEND-DIR]/                     # Frontend application (if applicable)
+│   ├── CONTEXT.md                      # Frontend-specific AI context
+│   ├── src/                            # Source code
+│   │   ├── components/                 # UI components
+│   │   │   ├── CONTEXT.md              # Component patterns
+│   │   │   ├── common/                 # Shared components
+│   │   │   └── [feature]/              # Feature-specific components
+│   │   ├── pages/                      # Page components/routes
+│   │   │   ├── [page1].[ext]           # Page implementations
+│   │   │   └── [page2].[ext]
+│   │   ├── stores/                     # State management
+│   │   │   ├── CONTEXT.md              # State management patterns
+│   │   │   ├── [store1].[ext]          # Store implementations
+│   │   │   └── [store2].[ext]
+│   │   ├── api/                        # API client layer
+│   │   │   ├── CONTEXT.md              # Client patterns
+│   │   │   ├── client.[ext]            # HTTP client setup
+│   │   │   └── endpoints/              # API endpoint definitions
+│   │   ├── utils/                      # Utility functions
+│   │   │   ├── logging.[ext]           # Client-side logging
+│   │   │   ├── validation.[ext]        # Form validation
+│   │   │   └── helpers.[ext]           # Helper functions
+│   │   └── assets/                     # Static assets
+│   ├── tests/                          # Frontend tests
+│   ├── [BUILD-CONFIG]                  # Build configuration
+│   └── [PACKAGE-FILE]                  # Package configuration
+├── docs/                               # Documentation
+│   ├── ai-context/                     # AI-specific documentation
+│   │   ├── project-structure.md        # This file
+│   │   ├── docs-overview.md            # Documentation architecture
+│   │   ├── system-integration.md       # Integration patterns
+│   │   ├── deployment-infrastructure.md # Infrastructure docs
+│   │   └── handoff.md                  # Task management
+│   ├── api/                            # API documentation
+│   ├── deployment/                     # Deployment guides
+│   └── development/                    # Development guides
+├── scripts/                            # Automation scripts
+│   ├── setup.[ext]                     # Environment setup
+│   ├── deploy.[ext]                    # Deployment scripts
+│   └── maintenance/                    # Maintenance scripts
+├── [INFRASTRUCTURE-DIR]/               # Infrastructure as code (if applicable)
+│   ├── [PROVIDER]/                     # Cloud provider configurations
+│   ├── docker/                         # Container configurations
+│   └── monitoring/                     # Monitoring and alerting
+└── [CONFIG-FILES]                      # Root-level configuration files
+```
+
+
+---
+
+*This template provides a comprehensive foundation for documenting project structure. Adapt it based on your specific technology stack, architecture decisions, and organizational requirements.*

package/docs/ai-context/system-integration.md

@@ -0,0 +1,21 @@
+# System Integration Documentation
+
+This document contains cross-component integration patterns and system-wide architectural decisions.
+
+## Purpose
+
+This template serves as a placeholder for documenting:
+- Cross-component communication patterns
+- Data flow architectures between services
+- Integration strategies with external systems
+- Performance optimization patterns
+- Testing strategies for integrated systems
+- Error handling across service boundaries
+
+## Implementation Note
+
+Replace this template with your actual system integration documentation as your project develops. Focus on patterns that AI agents need to understand when working across component boundaries or implementing features that span multiple services.
+
+---
+
+*Customize this template based on your specific integration patterns and architectural requirements.*

package/docs/open-issues/example-api-performance-issue.md

@@ -0,0 +1,79 @@
+# API Performance Issue - Example Template
+
+## Issue Description
+
+Describe the specific performance issue or bug that needs to be addressed. Include symptoms, affected features, and user impact.
+
+Example: "API endpoint `/api/data/process` has intermittent high latency (>5 seconds) under normal load conditions, causing user timeout errors."
+
+## Root Cause
+
+Detailed analysis of what's causing the issue. Include:
+- Technical root cause
+- Contributing factors
+- System conditions that trigger the issue
+
+Example: "Database query optimization needed for complex joins. Current query scans entire table without proper indexing."
+
+## Impact Assessment
+
+- **Severity**: Critical/High/Medium/Low
+- **Affected Users**: Percentage or number of users impacted
+- **Business Impact**: Revenue, user experience, or operational impact
+- **Workarounds**: Any temporary solutions currently in place
+
+## Proposed Solution
+
+### Technical Approach
+Detailed technical solution including:
+- Code changes required
+- Architecture modifications
+- Database schema updates
+- Performance improvements expected
+
+### Implementation Plan
+1. **Phase 1**: Initial fixes (timeline)
+2. **Phase 2**: Optimization improvements (timeline)
+3. **Phase 3**: Monitoring and validation (timeline)
+
+## Testing Strategy
+
+- **Unit Tests**: Specific test cases to validate the fix
+- **Integration Tests**: End-to-end testing scenarios
+- **Performance Tests**: Load testing and benchmarking
+- **Regression Tests**: Ensure no existing functionality breaks
+
+## Related Files
+
+List all files that need to be modified:
+- `src/api/routes/data.py` - Main endpoint logic
+- `src/database/models.py` - Database model updates
+- `src/utils/query_optimizer.py` - Query optimization utilities
+- `tests/test_api_performance.py` - Performance test suite
+
+## References
+
+- [External documentation or APIs]
+- [Related GitHub issues or PRs]
+- [Performance benchmarking results]
+- [Stack Overflow discussions or solutions]
+
+## Status
+
+- [ ] **Open** - Issue identified and documented
+- [ ] **In Progress** - Solution being implemented
+- [ ] **Testing** - Fix implemented, undergoing testing
+- [ ] **Fixed** - Issue resolved and deployed
+- [ ] **Closed** - Issue confirmed resolved in production
+
+## Implementation Notes
+
+Track progress and implementation details:
+- Date started: [DATE]
+- Key decisions made: [DECISIONS]
+- Challenges encountered: [CHALLENGES]
+- Performance improvements achieved: [METRICS]
+
+---
+
+*This template provides a structured approach to documenting and tracking technical issues. Customize sections based on your project's specific needs and workflow.*

package/eslint.config.mjs

@@ -1,3 +1,6 @@
+// For more info, see https://github.com/storybookjs/eslint-plugin-storybook#configuration-flat-config-format
+import storybook from "eslint-plugin-storybook";
+
 import js from "@eslint/js";
 import globals from "globals";
 import reactHooks from "eslint-plugin-react-hooks";
@@ -5,31 +8,28 @@ import reactRefresh from "eslint-plugin-react-refresh";
 import tseslint from "typescript-eslint";
 import eslintConfigPrettier from "eslint-config-prettier/flat";
 
-export default tseslint.config(
-  { ignores: ["dist"] },
-  {
-    extends: [
-      js.configs.recommended,
-      ...tseslint.configs.recommended,
-      eslintConfigPrettier,
+export default tseslint.config({ ignores: ["dist"] }, {
+  extends: [
+    js.configs.recommended,
+    ...tseslint.configs.recommended,
+    eslintConfigPrettier,
+  ],
+  files: ["**/*.{ts,tsx}"],
+  languageOptions: {
+    ecmaVersion: 2020,
+    globals: globals.browser,
+  },
+  plugins: {
+    "react-hooks": reactHooks,
+    "react-refresh": reactRefresh,
+  },
+  rules: {
+    ...reactHooks.configs.recommended.rules,
+    "react-refresh/only-export-components": [
+      "warn",
+      { allowConstantExport: true },
     ],
-    files: ["**/*.{ts,tsx}"],
-    languageOptions: {
-      ecmaVersion: 2020,
-      globals: globals.browser,
-    },
-    plugins: {
-      "react-hooks": reactHooks,
-      "react-refresh": reactRefresh,
-    },
-    rules: {
-      ...reactHooks.configs.recommended.rules,
-      "react-refresh/only-export-components": [
-        "warn",
-        { allowConstantExport: true },
-      ],
-      "@typescript-eslint/no-unsafe-function-type": "off",
-      "@typescript-eslint/no-explicit-any": "off",
-    },
+    "@typescript-eslint/no-unsafe-function-type": "off",
+    "@typescript-eslint/no-explicit-any": "off",
   },
-);
+}, storybook.configs["flat/recommended"]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenuml/core",
-  "version": "3.32.6",
+  "version": "3.32.7",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -34,7 +34,9 @@
     "git:branch:clean:merged": "git branch --merged|egrep -v \"(\\*|master|main|dev|skip_branch_name)\" | xargs git branch -d",
     "git:branch:safe-delete": "echo '> git log --graph --left-right --cherry --oneline another-branch...main'",
     "git:forget": "git rm -r --cached . && git add . && git commit -m \"Forget all ignored files\"",
-    "test:specs": "echo \"Error: test:specs is not supported\""
+    "test:specs": "echo \"Error: test:specs is not supported\"",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build"
   },
   "main": "./dist/zenuml.js",
   "module": "./dist/zenuml.esm.mjs",
@@ -79,6 +81,9 @@
   "devDependencies": {
     "@eslint/js": "^9.21.0",
     "@playwright/test": "^1.54.1",
+    "@storybook/addon-docs": "^9.0.16",
+    "@storybook/addon-onboarding": "^9.0.16",
+    "@storybook/react-vite": "^9.0.16",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.3.0",
     "@types/antlr4": "~4.11.2",
@@ -96,12 +101,14 @@
     "eslint-config-prettier": "^10.1.1",
     "eslint-plugin-react-hooks": "^5.1.0",
     "eslint-plugin-react-refresh": "^0.4.19",
+    "eslint-plugin-storybook": "^9.0.16",
     "globals": "^15.15.0",
     "jsdom": "^26.1.0",
     "less": "^4.3.0",
     "postcss": "^8.5.3",
     "prettier": "3.5.3",
     "sass": "^1.86.3",
+    "storybook": "^9.0.16",
     "typescript": "~5.7.2",
     "typescript-eslint": "^8.24.1",
     "vite": "^6.2.0",

package/tailwind.config.js

@@ -38,8 +38,6 @@ module.exports = {
           message: "var(--color-text-message, var(--color-text-base, #000))",
           "message-arrow":
             "var(--color-message-arrow, var(--color-border-frame, var(--color-border-base, #000)))", // message arrow head
-          "message-hover":
-            "var(--color-text-message-hover, var(--color-bg-base, var(--color-backup-white, #ffffff)))",
           comment:
             "var(--color-text-comment, var(--color-text-secondary, var(--color-text-base, #000)))",
           "fragment-header":
@@ -71,8 +69,6 @@ module.exports = {
             "var(--color-border-participant, var(--color-border-participant, var(--color-border-frame, var(--color-border-base, #000))))",
           divider:
             "var(--color-border-participant, var(--color-border-frame, var(--color-border-base, #000)))",
-          "message-hover":
-            "var(--color-bg-message-hover, var(--color-text-base, #000))",
           "fragment-header":
             "var(--color-bg-fragment-header, var(--color-bg-frame, var(--color-bg-canvas, var(--color-bg-base, var(--color-backup-white, #ffffff)))))",
           occurrence: