@zenuml/core 3.47.0 → 3.47.2

package/.claude/skills/emoji-eval/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: emoji-eval
+description: Evaluate emoji rendering quality in ZenUML diagrams. Renders test cases in both DOM and SVG modes, takes screenshots, and scores emoji visibility, position, spacing, box fit, and decorator coexistence. Reports per-case scores with HTML-vs-SVG parity check. Use when testing emoji rendering, after emoji-related code changes, or when the user asks to evaluate/score emoji rendering.
+---
+
+# Emoji Rendering Evaluator
+
+Automatically score emoji rendering quality in ZenUML diagrams by rendering test cases in both DOM and SVG modes, taking screenshots, and evaluating what the agent sees.
+
+## Prerequisites
+
+- Dev server running on `http://localhost:8080` (`bun dev`)
+- Playwright MCP available for browser automation
+
+## Test Cases
+
+Run ALL of these cases unless the user specifies a subset:
+
+```javascript
+const EMOJI_TEST_CASES = {
+  "emoji-basic": "[rocket] Production\nA->Production.deploy()",
+  "emoji-multi": "[rocket] Production\n[lock] AuthService\n[fire] Cache\nProduction->AuthService.validate()\nAuthService->Cache.get()",
+  "emoji-with-type": "@Database [fire] HotDB\n@Actor [star] Admin\nAdmin->HotDB.query()",
+  "emoji-with-stereotype": '<<service>> [lock] Auth\n<<gateway>> [globe] API\nAPI->Auth.validate()',
+  "emoji-inline": "[rocket]User->[fire]Server.request()",
+  "emoji-async-message": "A->B: [check] validated\nB->C: [warning] review needed",
+  "emoji-comment": "// [eyes] review phase\nA->B.process()",
+  "emoji-colon-override": "[:red:] Alert\nA->Alert.trigger()",
+  "emoji-css-combo": "// [rocket, red] deploy note\nA->B.deploy()",
+  "emoji-complex": "@Database [fire] HotDB\n[rocket] Production\n<<service>> [lock] Auth\nProduction->Auth.validate(token)\n  Auth->HotDB.check(token)\n  Auth-->Production: [check] valid",
+};
+```
+
+## Procedure
+
+For each test case:
+
+### Step 1: Render in DOM mode
+
+1. Navigate to `http://localhost:8080`
+2. Set the code via CodeMirror:
+   ```javascript
+   page.evaluate((code) => {
+     const cm = document.querySelector('.CodeMirror');
+     cm.CodeMirror.setValue(code);
+   }, testCode);
+   ```
+3. Click the "DOM" button to switch to DOM view
+4. Wait 1 second for rendering to complete
+5. Take a screenshot of the diagram area — save as `emoji-eval-{caseName}-dom.png`
+
+### Step 2: Render in SVG mode
+
+1. Click the "SVG" button to switch to SVG view
+2. Wait 1 second for rendering to complete
+3. Take a screenshot of the diagram area — save as `emoji-eval-{caseName}-svg.png`
+
+### Step 3: Evaluate both screenshots
+
+Read each screenshot and score on the criteria below. Use your understanding of sequence diagrams to judge:
+
+- A participant header should be a box with the name inside
+- Emoji should appear inline to the LEFT of the participant name
+- @Type icons (actor, database) should appear ABOVE the name, in their own row
+- Stereotypes (`<<name>>`) should appear ABOVE the name, below the icon
+- Messages should be horizontal arrows with labels
+- Comments should be italicized text above messages
+
+## Scoring Criteria
+
+Score each criterion 0-3:
+
+### 1. Emoji Visibility (per participant with emoji)
+- **0**: Emoji not visible, blank box, or tofu character
+- **1**: Something visible but wrong character or garbled
+- **2**: Correct emoji visible but poor contrast or very small
+- **3**: Correct emoji clearly visible
+
+### 2. Emoji Position (per participant with emoji)
+- **0**: Emoji in wrong location (after name, outside box, overlapping other elements)
+- **1**: Before name but overlapping the name text
+- **2**: Correct position with minor vertical misalignment
+- **3**: Perfectly aligned inline before the name
+
+### 3. Spacing (per participant with emoji)
+- **0**: Emoji and name overlap or no gap
+- **1**: Too tight (characters touching) or too wide (looks disconnected)
+- **2**: Acceptable gap, slightly off
+- **3**: Natural, comfortable spacing
+
+### 4. Box Fit (per participant with emoji)
+- **0**: Emoji or name overflows the participant box boundary
+- **1**: Box boundary clips the emoji or text
+- **2**: Box fits but looks cramped
+- **3**: Box comfortably accommodates emoji + name with padding
+
+### 5. Decorator Coexistence (only for cases with @Type or stereotype)
+- **0**: @Type icon or stereotype is missing or broken
+- **1**: Both present but overlapping or misaligned
+- **2**: Both present, minor layout issues
+- **3**: Perfect layout — icon above, stereotype below icon, emoji inline with name
+
+### 6. Message/Comment Emoji (only for cases with emoji in messages or comments)
+- **0**: Emoji not visible in message/comment text
+- **1**: Emoji visible but breaks the message layout
+- **2**: Emoji visible, minor alignment issues
+- **3**: Emoji renders naturally inline with message/comment text
+
+## Parity Check
+
+For each criterion scored in both DOM and SVG:
+- **Match**: Both scores are equal → mark as `=`
+- **Close**: Scores differ by 1 → mark as `~`
+- **Divergent**: Scores differ by 2+ → mark as `!=` (flag for investigation)
+
+## Output Format
+
+Present results as a markdown report:
+
+```markdown
+# Emoji Rendering Evaluation Report
+
+**Date:** YYYY-MM-DD
+**Branch:** {current git branch}
+**Total cases:** {N}
+
+## Summary
+
+| Case | DOM Score | SVG Score | Parity | Status |
+|------|----------|-----------|--------|--------|
+| emoji-basic | 12/12 | 10/12 | ~ | PASS |
+| emoji-multi | 12/12 | 11/12 | ~ | PASS |
+| ... | ... | ... | ... | ... |
+
+**Overall DOM:** {total}/{max} ({percentage}%)
+**Overall SVG:** {total}/{max} ({percentage}%)
+**Parity divergences:** {count}
+
+## Detailed Results
+
+### emoji-basic
+**DSL:**
+\`\`\`
+[rocket] Production
+A->Production.deploy()
+\`\`\`
+
+**DOM render:**
+[screenshot: emoji-eval-emoji-basic-dom.png]
+
+| Criterion | Score | Notes |
+|-----------|-------|-------|
+| Emoji visibility | 3 | Rocket emoji clearly visible |
+| Emoji position | 3 | Correctly before "Production" |
+| Spacing | 3 | Natural gap |
+| Box fit | 3 | Box fits comfortably |
+| **Total** | **12/12** | |
+
+**SVG render:**
+[screenshot: emoji-eval-emoji-basic-svg.png]
+
+| Criterion | Score | Notes |
+|-----------|-------|-------|
+| Emoji visibility | 3 | Rocket emoji visible |
+| Emoji position | 2 | Slightly tighter than DOM |
+| Spacing | 2 | Tighter spacing than DOM |
+| Box fit | 3 | Box fits |
+| **Total** | **10/12** | |
+
+**Parity:** Spacing is tighter in SVG (~ close)
+
+---
+(repeat for each case)
+```
+
+## Pass/Fail Thresholds
+
+- **PASS**: All criteria >= 2, total >= 75%
+- **WARN**: Any criterion at 1, or total 50-75%
+- **FAIL**: Any criterion at 0, or total < 50%
+
+## When to use this skill
+
+- After emoji-related code changes
+- Before creating a PR that touches emoji rendering
+- When the user asks to "evaluate emoji", "score emoji rendering", "check emoji quality"
+- When debugging emoji visual issues

package/.claude/skills/propagate-core-release/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: propagate-core-release
-description: Propagate a published `@zenuml/core` release to downstream projects by updating each consumer on its own branch and opening or reusing draft PRs. Use when the user says "push core to downstreams", "update downstream projects", "propagate release", "open downstream PRs", "submit downstream drafts", or wants the newly published zenuml/core version rolled out across mermaid, mermaid live editor, web-sequence, the IntelliJ plugin, confluence-plugin-cloud, and diagramly.ai.
+description: Propagate a published `@zenuml/core` release by opening or reusing per-repo downstream issues with explicit rollout instructions. Use when the user says "push core to downstreams", "update downstream projects", "propagate release", "open downstream issues", "file rollout issues", or wants the newly published zenuml/core version handed off across mermaid, mermaid live editor, web-sequence, the IntelliJ plugin, confluence-plugin-cloud, and diagramly.ai.
 ---
 
 # Propagate Core Release
 
-Update downstream consumers after `@zenuml/core` has already been published. This skill creates or reuses per-repo update branches and draft PRs, but does not merge anything.
+Coordinate downstream consumers after `@zenuml/core` has already been published. This skill creates or reuses per-repo GitHub issues with clear implementation instructions for each downstream team. It does not edit downstream repos or open PRs on their behalf.
 
 ## Scope
 
@@ -14,17 +14,17 @@ This skill is for the post-publish propagation step only.
 It should:
 
 1. identify the published `@zenuml/core` version to roll out
-2. update each downstream repo to that version
-3. create or reuse a branch in each downstream repo
-4. push the branch
-5. create or reuse a **draft** PR
-6. summarize which repos succeeded, failed, or were skipped
+2. inspect each downstream repo's update conventions from [references/downstreams.md](references/downstreams.md)
+3. create or reuse one downstream issue per repo for that version
+4. include explicit repo-specific instructions in each issue body
+5. summarize which repos succeeded, failed, or were skipped
 
 It should not:
 
 - publish `@zenuml/core`
-- merge downstream PRs
-- auto-fix unrelated downstream test failures beyond straightforward dependency-update fallout
+- update downstream code directly
+- create downstream branches or PRs
+- auto-fix unrelated downstream test failures or implementation details
 
 Renderer integration rule:
 
@@ -33,15 +33,14 @@ Renderer integration rule:
 
 ## Downstream Repos
 
-Read [references/downstreams.md](references/downstreams.md) before starting. It contains the canonical downstream repo list and repo slug assumptions.
+Read [references/downstreams.md](references/downstreams.md) before starting. It contains the canonical downstream repo list, repo slug assumptions, and repo-specific update commands that must be copied into the issue instructions.
 
 ## Preconditions
 
 Before starting:
 
 - confirm the target `@zenuml/core` version is already published
-- confirm `gh auth status` is healthy for all target orgs
-- confirm you have local checkout strategy for each downstream repo
+- confirm `gh auth status` is healthy for all target orgs and repos where issues will be filed
 - if the user did not specify the target version, discover the latest published one first
 
 If the published version is ambiguous, stop and ask.
@@ -51,46 +50,50 @@ If the published version is ambiguous, stop and ask.
 Treat each downstream repo as an independent unit of work.
 
 - Continue processing the remaining repos if one repo fails.
-- Keep a per-repo status ledger as you go: `updated`, `already-updated`, `draft-pr-open`, `blocked`, `failed`.
-- Prefer deterministic updates and small diffs.
-- Reuse existing update branches or draft PRs when they already target the same core version.
+- Keep a per-repo status ledger as you go: `issue-opened`, `issue-reused`, `already-tracked`, `blocked`, `failed`.
+- Prefer deterministic, reusable issue text.
+- Check for same-version issues before creating anything new.
+- Reuse an existing open issue when it already targets the same core version.
+- If the same version already has a closed issue, treat it as `already-tracked` and report it instead of opening a duplicate unless the user explicitly asks to reopen or replace it.
 
-## Branch Naming
+## Issue Rules
 
-Use a consistent branch name across downstream repos:
+Each downstream repo should get at most one open issue per core version.
 
-```text
-chore/zenuml-core-v<version>
-```
-
-Example:
-
-```text
-chore/zenuml-core-v1.2.3
-```
-
-## Draft PR Rules
-
-All PRs created by this skill must be draft PRs.
+Before creating a new issue, search that repo for issues matching the target version in the title or body. Prefer exact matches on `@zenuml/core v<version>`.
 
 Use a consistent title pattern:
 
 ```text
-chore: update @zenuml/core to v<version>
+chore: roll out @zenuml/core v<version>
 ```
 
-Use a concise body:
+Use a clear body with actionable instructions:
 
 ```markdown
 ## Summary
-- update `@zenuml/core` to `v<version>`
-
-## Notes
-- automated downstream propagation after core publish
-- draft PR for repo-specific verification
+- `@zenuml/core` `v<version>` has been published
+- this repo needs to adopt that release
+
+## Required Work
+1. Run: `<update-command>`
+2. Run: `<lockfile-refresh-command>` and include the lockfile in the PR when applicable
+3. Run: `<verify-command>` when applicable
+4. Keep the diff scoped to the core upgrade and any required integration fix
+5. Open a downstream PR that links back to this issue
+
+## Repo-Specific Notes
+- <repo-specific note 1>
+- <repo-specific note 2>
+
+## Acceptance Criteria
+- repo is updated to `@zenuml/core` `v<version>` or the equivalent vendored build output
+- lockfile is refreshed when the repo uses one
+- verification command passes locally, or failure details are documented in the PR
+- no unrelated dependency or renderer migrations are mixed into the change
 ```
 
-If a draft PR already exists for the same branch or same target version, reuse it and report it instead of creating a duplicate.
+If an issue already exists for the same target version, do not create a duplicate. Reuse the open one, or report the closed one as already tracked.
 
 ## Workflow
 
@@ -110,31 +113,31 @@ Record:
 
 For each repo in [references/downstreams.md](references/downstreams.md):
 
-1. Ensure you have a local checkout or clone target.
-2. Fetch latest default branch state.
-3. Create or reuse `chore/zenuml-core-v<version>`.
-4. Update the dependency or bundled artifact according to the repo's conventions.
-5. Inspect the diff and keep it scoped to the propagation work.
-6. Run lightweight repo-appropriate verification if it is cheap and obvious.
-7. Commit with:
-
-   ```text
-   chore: update @zenuml/core to v<version>
-   ```
-
-8. Push the branch.
-9. Create or reuse a **draft** PR.
+1. Read the repo row carefully and extract the update command, verification command, and notes.
+2. Search for existing issues in that repo for the same core version, checking both open and closed issues.
+3. If an open match exists, reuse it and record the URL.
+4. If only a closed match exists, record it as `already-tracked` and do not create a duplicate unless the user explicitly asked for that.
+5. Otherwise create a new issue using the standard title and a repo-specific body.
+6. Make sure the issue body includes:
+   - the target core version
+   - the exact update command from the table
+   - the lockfile refresh command when the repo uses pnpm or yarn
+   - the exact verify command when one is defined
+   - the renderer and API caveats from the repo notes
+   - an explicit instruction to open a PR linked to the issue after the work is complete
+   - a version marker that makes future deduplication easy, such as `Core version: v<version>`
 
 ### Step 3: Handle repo-specific blockers
 
 If a repo fails, capture exactly why:
 
+- missing issue creation permissions
+- existing issue search is ambiguous
+- existing closed issue should be reopened but the policy is unclear
 - dependency location unclear
-- package manager / lockfile conflict
-- update compiles locally but tests fail
-- missing permissions
-- repo missing locally and clone failed
-- PR creation failed
+- package manager or package filter is unclear
+- repo notes are insufficient to write a safe instruction
+- issue creation failed
 
 Do not let one repo failure stop the rest of the batch.
 
@@ -143,21 +146,23 @@ Do not let one repo failure stop the rest of the batch.
 At the end, produce a per-repo summary with:
 
 - repo
-- branch
-- PR URL or reused PR URL
+- issue URL or matched prior issue URL
 - final status
 - blocker if any
 
-## Repo Update Guidance
+## Repo Issue Guidance
 
-Each downstream has specific update and verification commands documented in [references/downstreams.md](references/downstreams.md). Follow the table exactly — do not guess package managers or update commands.
+Each downstream has specific update and verification commands documented in [references/downstreams.md](references/downstreams.md). Follow the table exactly when drafting instructions. Do not guess package managers, package filters, or update commands.
 
 For each repo:
 
-1. Run the **Update Command** from the table
-2. Run the **lockfile refresh** (`pnpm install` or `yarn install`) — always commit the updated lockfile
-3. Run the **Verify Command** from the table — if it fails, report the failure and move on
-4. Commit only the dependency change + lockfile — nothing else
+1. Include the **Update Command** from the table verbatim
+2. Include the lockfile refresh step:
+   - `pnpm install` for pnpm repos
+   - `yarn install` for yarn repos
+3. Include the **Verify Command** from the table verbatim when one exists
+4. Tell the downstream team to keep the change scoped to the core upgrade and any required integration fix
+5. Tell the downstream team to open a PR after verification and link it back to the issue
 
 Special handling for renderer API changes:
 
@@ -165,23 +170,24 @@ Special handling for renderer API changes:
 - `mermaid-js/mermaid-live-editor` is an indirect SVG-renderer consumer through `@mermaid-js/mermaid-zenuml`. Do not add `@zenuml/core` directly there just to follow a core release.
 - `web-sequence`, `confluence-plugin-cloud`, `diagramly.ai`, and similar downstreams stay on the HTML-renderer path unless the user explicitly asks for a renderer migration.
 
-Prefer the smallest change that updates the downstream safely:
+Prefer the smallest downstream task description that updates the repo safely:
 
 - package dependency bumps
 - lockfile refreshes
-- vendored asset refreshes only when the repo actually vendors core output (e.g., `jetbrains-zenuml`)
+- vendored asset refreshes only when the repo actually vendors core output, such as `jetbrains-zenuml`
 
-Do not opportunistically clean up unrelated code while touching the downstream repo.
+Do not ask downstream teams to opportunistically clean up unrelated code while doing the upgrade.
 
-If a downstream repo needs custom update logic that is not obvious from the table or its files, stop on that repo and report the ambiguity.
+If a downstream repo needs custom update logic that is not obvious from the table or its notes, stop on that repo and report the ambiguity instead of inventing instructions.
 
 ## Safety
 
+- Never update downstream repos directly from this skill.
 - Never merge downstream PRs from this skill.
-- Never force-push unless the user explicitly asks.
-- Never batch all downstream repos into one branch or one PR.
+- Never batch all downstream repos into one issue.
+- Never file duplicate issues for the same repo and core version.
 - Never hide per-repo failures behind a single "batch failed" message.
-- Never update unrelated dependencies in the same PR.
+- Never ask downstream teams to update unrelated dependencies in the same PR.
 
 ## Output
 
@@ -189,12 +195,11 @@ Final report format:
 
 ```markdown
 ## Downstream Propagation Report
-- Core version: v<version>
+- Core version: `v<version>`
 - Overall: <N> succeeded, <N> reused, <N> skipped, <N> failed
 
 ### Repo Results
-- `<repo>`: draft PR opened | draft PR reused | already updated | failed
-  branch: `<branch-name>`
-  pr: <url or none>
+- `<repo>`: issue opened | issue reused | already tracked | failed
+  issue: <url or none>
   notes: <short reason or blocker>
 ```

package/.claude/skills/propagate-core-release/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
   display_name: "Propagate Core Release"
-  short_description: "Open downstream draft PRs for a published core version"
-  default_prompt: "Use $propagate-core-release after @zenuml/core has been published to update the configured downstream repos on per-repo branches and open or reuse draft PRs. Do not merge the downstream PRs."
+  short_description: "Open downstream rollout issues for a published core version"
+  default_prompt: "Use $propagate-core-release after @zenuml/core has been published to open or reuse per-repo downstream issues with explicit rollout instructions. Do not update downstream repos directly and do not open PRs on their behalf."
 
 policy:
   allow_implicit_invocation: true

package/AGENTS.md

@@ -5,7 +5,7 @@
 
 ## Build, Test, and Development Commands
 - `bun install` – install dependencies (Bun 1.x, Node ≥20).
-- `bun run dev` – Vite dev server on `http://localhost:8080`.
+- `bun run dev` – Vite dev server on `http://localhost:4000`.
 - `bun run build` – library bundle via `vite.config.lib.ts`.
 - `bun run build:site` / `bun run build:gh-pages` – demo/docs build (standard vs GitHub Pages).
 - `bun run test` – Bun unit tests covering `src` and `test/unit`.