@zenuml/core 3.47.9 → 3.48.0

package/CLAUDE.md

@@ -1,124 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Development Commands
-
-- **Start development server**: `bun dev` (runs on port 8080)
-- **Build library**: `bun build` (builds library with vite.config.lib.ts)
-- **Build site**: `bun build:site` (builds demo site with vite.config.ts)
-- **Run tests**: `bun run test` (runs Vitest unit tests, excluding E2E). Do NOT use `bun test` — it picks up Playwright E2E files and reports false failures.
-- **Run E2E tests**: `bun pw` (runs Playwright tests)
-- **Run E2E tests (CI)**: `bun pw:ci` (runs with GitHub reporter for CI)
-- **Open Playwright UI**: `bun pw:ui`
-- **Update Playwright snapshots**: `bun pw:update`
-- **Install Playwright browsers**: `bun pw:install`
-- **Run smoke tests**: `bun pw:smoke`
-- **Lint code**: `bun eslint` (runs ESLint with auto-fix)
-- **Format code**: `bun prettier` (runs Prettier)
-- **Generate ANTLR parser**: `bun antlr` (generates JavaScript parser from grammar)
-
-## Project Architecture
-
-ZenUML is a JavaScript-based diagramming library for creating sequence diagrams from text definitions. The project has two main parts:
-
-### 1. DSL Parser (ANTLR-based)
-
-- **Grammar files**: `src/g4/` contains ANTLR grammar definitions
-- **Generated parser**: `src/generated-parser/` contains generated JavaScript parser
-- **Parser enhancements**: `src/parser/` contains custom functionality layered on top of ANTLR
-
-### 2. React-based Renderer
-
-- **Core entry point**: `src/core.tsx` - main library export and ZenUml class
-- **Component structure**: `src/components/` - React components for rendering diagrams
-- **Store management**: `src/store/Store.ts` - Jotai-based state management
-- **Positioning engine**: `src/positioning/` - algorithms for layout and positioning
-
-### Key Components Architecture
-
-- **DiagramFrame**: Main container component that orchestrates the entire diagram
-- **SeqDiagram**: Core sequence diagram renderer with layers:
-  - **LifeLineLayer**: Renders participants and their lifelines
-  - **MessageLayer**: Renders messages and interactions between participants
-- **Statement components**: Individual renderers for different UML elements (interactions, fragments, etc.)
-
-### Parser Architecture
-
-The parser uses a two-stage approach:
-
-1. **ANTLR-generated parser**: Converts text to parse tree
-2. **Custom parser layer**: Transforms parse tree into structured data for rendering
-
-Key parser modules:
-
-- **Participants.ts**: Manages participant detection and ordering
-- **MessageContext.ts**: Handles message parsing and context
-- **FrameBuilder.ts**: Builds the overall diagram structure
-- **Fragment handling**: Support for UML fragments (alt, opt, loop, par, etc.)
-
-## Build System
-
-The project uses Vite with two configurations:
-
-- **vite.config.ts**: Development server and demo site build
-- **vite.config.lib.ts**: Library build (ESM and UMD outputs)
-
-Output formats:
-
-- **ESM**: `dist/zenuml.esm.mjs` for modern bundlers
-- **UMD**: `dist/zenuml.js` for browser scripts
-
-## Testing Strategy
-
-- **Unit tests**: Vitest for parser and utility functions
-- **Component tests**: React Testing Library for component logic
-- **E2E tests**: Playwright for full integration testing with visual snapshots
-- **Test files**: Co-located with source files using `.spec.ts` extension
-
-## Key Dependencies
-
-- **React 19**: UI framework
-- **ANTLR4**: Parser generation
-- **Jotai**: State management
-- **Tailwind CSS**: Styling framework
-- **html-to-image**: PNG export functionality
-- **Vite**: Build tool and development server
-
-## Package Management
-
-Uses Bun as the package manager and JavaScript runtime. Bun is a fast all-in-one JavaScript runtime that includes a package manager, test runner, and bundler.
-
-### Test Configuration
-- **Unit tests with Bun**: `bun test` (alias: `bun run test`) - Runs unit tests in `src/` and `test/unit/` folders (excludes `/tests` E2E folder)
-- **Vitest**: Tests also support Vitest for IDE integration compatibility
-- **E2E tests**: `bun pw` - Runs Playwright tests in `/tests` folder
-- **Test setup**: `test/setup.ts` configures test environment (mocks IntersectionObserver, etc.)
-- Tests use `vi` mocking utilities from Vitest
-- Test files use `.spec.ts` extension and are co-located with source files
-
-## Bug Fix Process
-
-When starting work on a bug (especially from a GitHub issue):
-
-1. **Reproduce first** — write a minimal test case (unit test or Playwright E2E) that demonstrates the bug. The test must fail before any code changes.
-2. **Capture a baseline** — if the bug is visual, take a Playwright snapshot or screenshot of the broken state before fixing. This serves as evidence of what changed.
-3. **Fix the code** — make the minimal change to fix the bug.
-4. **Verify the fix** — the failing test from step 1 must now pass. All other existing tests must still pass.
-
-Never skip the reproduction step. If you can't reproduce it, you don't understand the bug well enough to fix it.
-
-## No Speculative Codebase Claims
-
-**NEVER** claim what the codebase does, uses, or contains without first verifying by reading or grepping the code. Phrases like "if we're currently using X", "since we already have Y", or "the codebase uses Z pattern" are forbidden unless you have Read/Grep/Glob evidence from this conversation.
-
-- Before making a claim about codebase state, verify it — use a subagent (Explore) if needed.
-- General programming knowledge is fine. Claims about *this* codebase require evidence.
-
-## Development Notes
-
-- The project builds both a library and a demo site
-- Parser generation requires Java and ANTLR4
-- E2E tests use visual snapshots for regression testing
-- The library is published as `@zenuml/core` to npm
-- GitHub Pages deployment is automated via GitHub Actions

package/DEPLOYMENT.md

@@ -1,62 +0,0 @@
-# ZenUML Web Renderer Deployment
-
-This document describes the deployment process for the ZenUML Web Renderer to Cloudflare Pages.
-
-## Deployment Strategy
-
-- **Production**: Deploys from `main` branch to `zenuml-web-renderer` project
-- **Staging**: Deploys from any non-main branch to `zenuml-web-renderer-staging` project
-
-## GitHub Actions Workflow
-
-The deployment is automated through GitHub Actions (`.github/workflows/cloudflare-pages.yml`):
-
-1. **Triggers**: 
-   - Push to `main` or `feat/public-renderer` branches
-   - Pull requests to `main` branch
-   - Only when relevant files are changed (renderer.html, public/**, src/**, etc.)
-
-2. **Build Process**:
-   - Install dependencies with pnpm
-   - Build the site using `pnpm build:site`
-   - Deploy to appropriate Cloudflare Pages project
-
-## Required Secrets
-
-Add these secrets to your GitHub repository settings:
-
-- `CLOUDFLARE_API_TOKEN`: Cloudflare API token with Pages permissions
-- `CLOUDFLARE_ACCOUNT_ID`: Your Cloudflare account ID
-
-## Manual Deployment
-
-You can also deploy manually using wrangler:
-
-```bash
-# Deploy to staging
-pnpm pages:deploy:staging
-
-# Deploy to production  
-pnpm pages:deploy
-```
-
-## Project Structure
-
-- `renderer.html`: Main renderer page (root level)
-- `public/renderer.html`: Copy of renderer page for static hosting
-- `dist/`: Build output directory (created by `pnpm build:site`)
-- `wrangler.toml`: Cloudflare configuration
-
-## URLs
-
-- **Production**: `https://zenuml-web-renderer.pages.dev`
-- **Staging**: `https://zenuml-web-renderer-staging.pages.dev`
-
-## Usage
-
-Once deployed, you can use the renderer by visiting:
-- `https://your-domain.pages.dev/renderer.html`
-- `https://your-domain.pages.dev/` (if configured as index)
-
-Future URL parameter support will allow:
-- `https://your-domain.pages.dev/renderer.html?code=<base64-encoded-zenuml>`

package/Dockerfile

@@ -1,36 +0,0 @@
-FROM node:20-slim AS base
-
-# Set environment variables for pnpm
-ENV PNPM_HOME="/pnpm"
-ENV PATH="$PNPM_HOME:$PATH"
-ENV DOCKER=true
-
-# Enable corepack to use pnpm
-RUN corepack enable
-
-# Set the working directory
-WORKDIR /app
-
-# Copy the project files to the working directory
-COPY . .
-
-RUN pnpm add -g serve
-
-FROM base As prod-deps
-RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile --prod --ignore-scripts
-FROM base AS deps
-RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install --frozen-lockfile
-
-FROM base AS build
-COPY --from=deps /app/node_modules /app/node_modules
-RUN pnpm build:site
-
-FROM base
-COPY --from=prod-deps /app/node_modules /app/node_modules
-COPY --from=build /app/dist /app/dist
-
-# Expose the port the app runs on
-EXPOSE 8080
-
-# Command to run the application
-CMD ["serve", "-s", "dist", "-l", "8080"]

package/IMPLEMENTATION_PLAN.md

@@ -1,163 +0,0 @@
-# Implementation Plan: Named Parameters Support
-
-## Overview
-Add support for named parameters in method calls, allowing syntax like `A.method(param=value)` alongside existing positional parameters.
-
-## Current State Analysis
-
-### Grammar Structure
-- **Parser**: `src/g4/sequenceParser.g4` defines parameter rules at lines 220-230
-- **Current parameter rule**: `parameter: declaration | expr`
-- **Parameters rule**: `parameters: parameter (COMMA parameter)* COMMA?`
-- **Invocation**: Method calls use `invocation: OPAR parameters? CPAR`
-
-### Parser Logic
-- **SignatureText.ts**: Handles parameter display via `getFormattedText()`
-- **Parser.types.ts**: Defines `Parameter` and `Parameters` interfaces
-- **Current behavior**: Parameters are parsed as expressions or type declarations
-
-## Implementation Stages
-
-### Stage 1: Grammar Extension
-**Goal**: Extend ANTLR grammar to support named parameter syntax
-**Success Criteria**: 
-- Grammar accepts `param=value` syntax
-- Backward compatibility with existing positional syntax
-- Parser generates successfully
-
-**Tasks**:
-- [x] Add `namedParameter` rule: `ID ASSIGN expr`
-- [x] Update `parameter` rule to include `namedParameter | declaration | expr`
-- [x] Add tests for grammar parsing
-- [x] Regenerate parser with `pnpm antlr`
-
-**Tests**: 
-- [x] `A.method(x=1, y=2)` parses correctly
-- [x] `A.method(1, name="test")` mixed parameters work
-- [x] Existing `A.method(1, 2)` still works
-
-**Status**: Complete
-
-### Stage 2: Parser Type Extensions
-**Goal**: Extend parser types and interfaces to handle named parameters
-**Success Criteria**:
-- Named parameter data accessible in parser contexts
-- Type definitions support both named and positional parameters
-
-**Tasks**:
-- [x] Extend `Parameter` interface to distinguish parameter types
-- [x] Add `NamedParameter` interface with name and value properties
-- [x] Update `SignatureText.ts` to handle named parameter formatting
-- [x] Update type assertions and context handling
-
-**Tests**:
-- [x] Named parameters accessible via parser API
-- [x] `getFormattedText()` displays named parameters correctly
-- [x] Type safety maintained
-
-**Status**: Complete
-
-### Stage 3: Rendering Support
-**Goal**: Update React components to render named parameters appropriately
-**Success Criteria**:
-- Named parameters displayed in sequence diagrams
-- Clear visual distinction between parameter types
-- Consistent formatting with existing design
-
-**Tasks**:
-- [x] Update message rendering components (via SignatureText.ts)
-- [x] Enhance parameter display logic (formatParameters helper)
-- [x] Ensure consistent formatting with existing design
-- [x] Test rendering in development environment
-
-**Tests**:
-- [x] Named parameters render correctly: `method(userId=123,name="John")`
-- [x] Mixed parameters work: `method(123,name="John",active=true)`
-- [x] Backward compatibility maintained: `oldMethod(1,2,3)`
-- [x] Complex scenarios: `mixedCall("first",second=456,"third")`
-
-**Status**: Complete
-
-### Stage 4: Test Coverage & Integration
-**Goal**: Comprehensive testing and integration with existing features
-**Success Criteria**:
-- Full test coverage for named parameter scenarios
-- E2E tests validate end-to-end functionality
-- No regressions in existing functionality
-
-**Tasks**:
-- [ ] Unit tests for parser logic
-- [ ] Component tests for rendering
-- [ ] E2E tests with Playwright
-- [ ] Performance regression testing
-- [ ] Documentation updates
-
-**Tests**:
-- All test suites pass
-- Performance benchmarks maintained
-- Edge cases handled properly
-
-**Status**: Not Started
-
-### Stage 5: Documentation & Examples
-**Goal**: User-facing documentation and examples
-**Success Criteria**:
-- Clear documentation of named parameter syntax
-- Working examples in demo site
-- Migration guidance for users
-
-**Tasks**:
-- [ ] Update grammar documentation
-- [ ] Add examples to demo site
-- [ ] Update README with new syntax
-- [ ] API documentation updates
-
-**Tests**:
-- Documentation examples work correctly
-- Demo site renders named parameter examples
-- No broken links or outdated information
-
-**Status**: Not Started
-
-## Technical Considerations
-
-### Backward Compatibility
-- Existing positional parameter syntax must continue working
-- Mixed parameter styles (positional + named) should be supported
-- No breaking changes to existing APIs
-
-### Performance Impact
-- Minimal impact on parser performance
-- Named parameter detection should be efficient
-- Memory usage considerations for parameter storage
-
-### Edge Cases
-- Parameter name validation and uniqueness
-- Error handling for invalid syntax
-- Interaction with existing features (fragments, loops, etc.)
-
-### Dependencies
-- ANTLR4 parser regeneration
-- No new external dependencies required
-- Maintain compatibility with existing build system
-
-## Risk Assessment
-
-**Low Risk**:
-- Grammar extension is straightforward
-- Existing infrastructure supports parameter handling
-
-**Medium Risk**:
-- Rendering changes may require careful CSS updates
-- Type system changes need thorough testing
-
-**High Risk**:
-- Parser performance impact needs monitoring
-- Complex interaction with expression parsing
-
-## Success Metrics
-- [ ] All existing tests pass
-- [ ] New functionality covered by tests
-- [ ] No performance degradation
-- [ ] Documentation complete
-- [ ] Community feedback positive

package/Integration/vanilla-js/index.html

@@ -1,42 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <title>Integration ZenUML Library with Vanilla JavaScript</title>
-    <script>
-      window.process = { env: "production" };
-    </script>
-    <script src="https://www.unpkg.com/@zenuml/core/dist/zenuml.js"></script>
-  </head>
-  <body class="zenuml">
-    <div id="app"></div>
-    <script>
-      const ZenUml = window["zenuml"].default;
-      const zenuml = new ZenUml(document.getElementById("app"));
-      const code = `
-A B C D
-
-A->B.method() {
-  ret0_assign_rtl =C.method_long_to_give_space {
-    @return C->D: ret1_annotation_ltr
-    ret5_assign_ltr = B.method
-    if(x) {
-      ret0_assign_rtl =C.method_long_to_give_space {
-        @return C->D: ret1_annotation_ltr
-        ret5_assign_ltr = B.method
-      }
-    }
-    B.method2 {
-      return ret2_return_ltr
-    }
-  }
-
-  return ret2_return_rtl
-  @return B->A: ret4_annotation_rtl
-}
-
-`;
-      zenuml.render(code, { theme: "theme-blue" });
-    </script>
-  </body>
-</html>

package/MCP-ASSISTANT-RULES.md

@@ -1,85 +0,0 @@
-# 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_CN.md

@@ -1,15 +0,0 @@
-# Development
-
-```
-pnpm install
-pnpm dev
-```
-
-# 代码结构
-
-DSL 解析器和渲染器都在这个代码库中。
-
-DSL 解析器是基于 Antlr4 构建的。其定义文件位于`src/g4`。生成的解析器位于 `src/generated-parser`。
-对解析器的增强相关的代码位于`src/parser`文件夹。
-
-所有其他的文件基本上都是跟渲染器相关的。渲染器是基于 VueJs 2.x 开发的。

package/TUTORIAL.md

@@ -1,116 +0,0 @@
-
-# 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
-bun 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.