@zenuml/core 3.46.3 → 3.46.5

package/.claude/skills/babysit-pr/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: babysit-pr
+description: Monitor and fix failing GitHub Actions CI checks on PRs for mermaid-js/zenuml-core. Use when the user says "babysit PR", "check PR status", "fix CI", "PR is failing", "watch this PR", "why is CI red", or when used with /loop to continuously monitor a PR. Also use when Playwright snapshot failures occur in CI, lint/format issues block merging, or unit tests fail on a PR. Triggers on any PR monitoring, CI failure diagnosis, or automated fix-and-retry workflow.
+---
+
+# Babysit PR
+
+Monitor a GitHub Actions PR, diagnose failures, attempt fixes, and retry — up to 3 times total.
+
+## Scope
+
+This skill targets **mermaid-js/zenuml-core** only. All commands run from the zenuml-core directory.
+
+## Step 1: Find the PR
+
+Resolve which PR to babysit, in this priority order:
+
+1. **Explicit PR number** — if the user provided one (e.g., `#341`), use it
+2. **Current branch PR** — run `gh pr view --json number,title,headRefName,state,statusCheckRollup` from the zenuml-core directory
+3. **Recently failed PR** — if no PR on current branch, find the most recent failed PR in the last 10 minutes:
+   ```bash
+   gh run list --repo mermaid-js/zenuml-core --status failure --limit 5 --json databaseId,headBranch,event,createdAt,conclusion,name
+   ```
+   Filter to runs created within the last 10 minutes. If multiple, pick the most recent.
+
+If no PR is found, tell the user and stop.
+
+## Step 2: Check CI Status
+
+```bash
+gh pr checks <PR_NUMBER> --repo mermaid-js/zenuml-core
+```
+
+**If all checks pass**: Report success and stop. Nothing to babysit.
+
+**If checks are still running**: Report status and wait. Use `gh run watch <RUN_ID> --repo mermaid-js/zenuml-core` to wait for completion (with a 10-minute timeout). Then re-evaluate.
+
+**If checks failed**: Proceed to Step 3.
+
+## Step 3: Diagnose Failures
+
+For each failed check, pull the logs:
+
+```bash
+gh run view <RUN_ID> --repo mermaid-js/zenuml-core --log-failed
+```
+
+Categorize the failure:
+
+| Category | Indicators |
+|----------|-----------|
+| **Playwright snapshot mismatch** | `Error: A]snapshot.*doesn't match`, `Screenshot comparison failed`, pixel diff errors, `-linux.png` referenced |
+| **Playwright test logic failure** | Assertion errors, timeouts, element not found — but NOT snapshot diffs |
+| **Unit test failure** | Failures in `bun run test`, vitest output |
+| **Lint/format failure** | ESLint errors, Prettier diffs |
+| **Build failure** | Vite build errors, TypeScript compilation errors |
+| **Merge conflict** | `CONFLICT`, `merge conflict`, cannot rebase cleanly |
+| **Infra/flaky** | Network timeouts, runner issues, cache failures |
+
+## Step 4: Attempt Fix
+
+**Important**: Before fixing, make sure the local branch is up to date with the PR branch:
+```bash
+git fetch origin && git checkout <PR_BRANCH> && git pull origin <PR_BRANCH>
+```
+
+### Fix by Category
+
+#### Playwright Snapshot Mismatch (Linux)
+
+This is the most common CI-only failure because snapshots are platform-specific.
+
+1. **Verify it's a snapshot diff** (not a logic error) by reading the failure log
+2. **Check if the change is intentional** — look at recent commits on the branch. If they modified rendering code, SVG output, or CSS, snapshot updates are expected
+3. **Trigger the Linux snapshot update workflow**:
+   ```bash
+   gh workflow run update-snapshots.yml --repo mermaid-js/zenuml-core --ref <PR_BRANCH>
+   ```
+4. **Wait for the workflow to complete**:
+   ```bash
+   # Find the run ID (most recent on that branch)
+   gh run list --repo mermaid-js/zenuml-core --workflow update-snapshots.yml --branch <PR_BRANCH> --limit 1 --json databaseId,status
+   # Watch it
+   gh run watch <RUN_ID> --repo mermaid-js/zenuml-core
+   ```
+5. **Pull the auto-committed snapshots** locally:
+   ```bash
+   git pull origin <PR_BRANCH>
+   ```
+6. The update-snapshots workflow commits and verifies automatically. If it passes, CI should go green on next run.
+
+#### Playwright Test Logic Failure
+
+1. **Reproduce locally first**:
+   ```bash
+   bun pw --grep "<test name pattern>"
+   ```
+2. **Read the failing test** to understand what it expects
+3. **Fix the code** (not the test, unless the test expectation is wrong)
+4. **Verify locally**: `bun pw --grep "<test name pattern>"`
+5. **Commit and push**
+
+#### Unit Test Failure
+
+1. **Reproduce locally**:
+   ```bash
+   bun run test --run
+   ```
+2. **Fix the code or test**
+3. **Verify**: `bun run test --run`
+4. **Commit and push**
+
+#### Lint/Format Failure
+
+1. **Auto-fix**:
+   ```bash
+   bun eslint
+   bun prettier
+   ```
+2. **Verify no remaining issues**:
+   ```bash
+   bun eslint 2>&1 | tail -5
+   ```
+3. **Commit and push** the formatting fixes
+
+#### Build Failure
+
+1. **Reproduce locally**:
+   ```bash
+   bun build
+   ```
+2. **Read the error** — usually TypeScript errors or missing imports
+3. **Fix, verify locally, commit and push**
+
+#### Merge Conflict
+
+1. **Report to user** — do NOT auto-resolve merge conflicts. Show what's conflicting and ask for guidance.
+
+#### Infra/Flaky
+
+1. **Re-run the failed job**:
+   ```bash
+   gh run rerun <RUN_ID> --repo mermaid-js/zenuml-core --failed
+   ```
+2. If it fails again with the same infra error, report to user.
+
+## Step 5: Push and Monitor
+
+After applying a fix:
+
+1. **Run the full local test suite** before pushing (when the failure category allows local reproduction):
+   ```bash
+   bun run test --run   # unit tests
+   bun pw               # playwright (local, macOS — won't catch Linux snapshot diffs)
+   bun eslint           # lint
+   ```
+2. **Commit with a clear message**:
+   ```bash
+   git add <specific files>
+   git commit -m "fix: <what was fixed> to pass CI"
+   ```
+3. **Push**:
+   ```bash
+   git push origin <PR_BRANCH>
+   ```
+4. **Wait for CI** — use `gh run watch` on the new run
+5. **Evaluate result** — go back to Step 2
+
+## Step 6: Retry Budget
+
+Track attempts. Each "attempt" is one push-and-wait cycle (or one workflow trigger-and-wait for snapshot updates).
+
+- **Maximum 3 attempts total**
+- After each failed attempt, re-diagnose from scratch (Step 3) — the failure mode may have changed
+- **If a test passes on retry without code changes**, flag it as potentially flaky:
+  > "Test `<name>` passed on retry without changes — likely flaky. Consider investigating stability."
+- **After 3 failed attempts**, stop and report:
+  - What was tried
+  - What the current failure is
+  - Your best theory for root cause
+  - Suggested next steps for the user
+
+## Step 7: Summary Report
+
+After babysitting completes (success or exhausted retries), produce a brief report:
+
+```
+## PR #<number> Babysit Report
+- **Status**: [PASSED | FAILED after N attempts]
+- **Failures found**: <list of categories>
+- **Fixes applied**: <list of commits pushed>
+- **Flaky tests**: <any tests that passed on retry without changes>
+- **Manual attention needed**: <anything unresolved>
+```
+
+## Safety Rules
+
+- **Never force-push** — always regular `git push`
+- **Never resolve merge conflicts automatically** — report and ask
+- **Never push while CI is still running** from a previous attempt — wait for it to finish first
+- **Never modify the snapshot update workflow itself** — only trigger it
+- **Always verify fixes locally** before pushing (except Linux snapshot updates which can only be verified in CI)
+- **Check for in-progress CI** before pushing — avoid wasting CI minutes on runs that will be superseded

package/.claude/skills/babysit-pr/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Babysit PR"
+  short_description: "Monitor and fix failing PR CI checks"
+  default_prompt: "Use $babysit-pr to diagnose failing GitHub Actions checks on a zenuml-core PR, fix what is actionable, push updates, and watch CI until it is green."
+
+policy:
+  allow_implicit_invocation: true

package/.claude/skills/dia-scoring/SKILL.md

@@ -20,7 +20,7 @@ The workflow:
 
 1. Run `node scripts/analyze-compare-case.mjs --case <name> --json` for structured data.
 2. Use `--output-dir <dir>` when you need saved `html.png`, `svg.png`, `diff.png`, and `report.json`.
-3. For live browser inspection, navigate to `http://localhost:8080/cy/compare-case.html?case=<name>` and use the extension's `#diff-panel canvas`.
+3. For live browser inspection, navigate to `http://localhost:8080/e2e/tools/compare-case.html?case=<name>` and use the extension's `#diff-panel canvas`.
 4. Use Playwright page inspection for semantic attribution (element positions, font metrics, DOM structure).
 
 ## Offset Anchor

package/.claude/skills/land-pr/SKILL.md

@@ -28,17 +28,39 @@ If any precondition fails, report which one and stop. Do not attempt to fix —
 
 Run the precondition checks above. If anything is not green, stop and report.
 
-### 2. Squash merge
+### 2. Decide merge strategy
 
-This repo uses squash merges. The merge commit message should summarize the PR.
+Inspect the branch's commit history to decide between squash and merge:
 
 ```bash
+git log main..HEAD --oneline
+```
+
+**Auto-squash if ANY of these are true:**
+- Only 1 commit on the branch
+- Commit messages contain noise patterns: "wip", "fixup", "temp", "oops", "try again", "fix lint", "fix test", duplicate messages
+- More than half the commits have the same or very similar messages
+
+**Merge (preserve commits) if ALL of these are true:**
+- 2+ commits with distinct, meaningful messages
+- Each commit describes a self-contained step (not just iterations on the same change)
+- Commits follow a logical progression (e.g., "add X" → "refactor Y" → "delete Z")
+
+Announce the decision and why: "Squashing — 3 of 5 commits are fixups" or "Merging — 8 clean commits with distinct steps".
+
+### 3. Execute merge
+
+```bash
+# If squash:
 gh pr merge <PR_NUMBER> --squash --auto
+
+# If merge:
+gh pr merge <PR_NUMBER> --merge --auto
 ```
 
 Using `--auto` arms auto-merge so GitHub merges when all checks pass. If checks are already green, it merges immediately.
 
-### 3. Wait for merge
+### 4. Wait for merge
 
 If auto-merge was armed, wait for it:
 
@@ -48,7 +70,7 @@ gh pr view <PR_NUMBER> --json state
 
 Poll until state is `MERGED`. Timeout after 5 minutes — if not merged by then, report and stop.
 
-### 4. Monitor npm publish
+### 5. Monitor npm publish
 
 After merge, the `Build, Test, npm Publish, and Deploy` workflow runs on `main`. Watch it:
 
@@ -62,7 +84,7 @@ Wait for the run to complete:
 gh run watch <RUN_ID> --repo mermaid-js/zenuml-core
 ```
 
-### 5. Verify npm publish
+### 6. Verify npm publish
 
 Check that the new version appeared on npm:
 

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

@@ -0,0 +1,200 @@
+---
+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.
+---
+
+# 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.
+
+## Scope
+
+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
+
+It should not:
+
+- publish `@zenuml/core`
+- merge downstream PRs
+- auto-fix unrelated downstream test failures beyond straightforward dependency-update fallout
+
+Renderer integration rule:
+
+- Only `mermaid-js/mermaid` and `mermaid-js/mermaid-live-editor` should be treated as SVG-renderer integration work for `@zenuml/core` API changes.
+- All other downstreams remain HTML-renderer consumers. Do not migrate them to `renderToSvg` or other SVG-renderer APIs during propagation.
+
+## Downstream Repos
+
+Read [references/downstreams.md](references/downstreams.md) before starting. It contains the canonical downstream repo list and repo slug assumptions.
+
+## 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
+- if the user did not specify the target version, discover the latest published one first
+
+If the published version is ambiguous, stop and ask.
+
+## Batch Strategy
+
+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.
+
+## Branch Naming
+
+Use a consistent branch name across downstream repos:
+
+```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.
+
+Use a consistent title pattern:
+
+```text
+chore: update @zenuml/core to v<version>
+```
+
+Use a concise body:
+
+```markdown
+## Summary
+- update `@zenuml/core` to `v<version>`
+
+## Notes
+- automated downstream propagation after core publish
+- draft PR for repo-specific verification
+```
+
+If a draft PR already exists for the same branch or same target version, reuse it and report it instead of creating a duplicate.
+
+## Workflow
+
+### Step 1: Resolve target version
+
+Determine the `@zenuml/core` version to propagate.
+
+- If the user supplied a version, use it.
+- Otherwise, query npm or the release source of truth and resolve the latest published version.
+
+Record:
+
+- target version
+- source used to resolve it
+
+### Step 2: Process each downstream repo
+
+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.
+
+### Step 3: Handle repo-specific blockers
+
+If a repo fails, capture exactly why:
+
+- dependency location unclear
+- package manager / lockfile conflict
+- update compiles locally but tests fail
+- missing permissions
+- repo missing locally and clone failed
+- PR creation failed
+
+Do not let one repo failure stop the rest of the batch.
+
+### Step 4: Summarize the rollout
+
+At the end, produce a per-repo summary with:
+
+- repo
+- branch
+- PR URL or reused PR URL
+- final status
+- blocker if any
+
+## Repo Update 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.
+
+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
+
+Special handling for renderer API changes:
+
+- `mermaid-js/mermaid` is the direct `@zenuml/core` SVG-renderer integration. When core export APIs change, it may require code updates in `packages/mermaid-zenuml`, not just a dependency bump.
+- `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:
+
+- package dependency bumps
+- lockfile refreshes
+- vendored asset refreshes only when the repo actually vendors core output (e.g., `jetbrains-zenuml`)
+
+Do not opportunistically clean up unrelated code while touching the downstream repo.
+
+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.
+
+## Safety
+
+- 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 hide per-repo failures behind a single "batch failed" message.
+- Never update unrelated dependencies in the same PR.
+
+## Output
+
+Final report format:
+
+```markdown
+## Downstream Propagation Report
+- 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>
+  notes: <short reason or blocker>
+```

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

@@ -0,0 +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."
+
+policy:
+  allow_implicit_invocation: true

package/.claude/skills/propagate-core-release/references/downstreams.md

@@ -0,0 +1,41 @@
+# Downstream Repos
+
+Canonical downstream targets for propagating a published `@zenuml/core` release.
+
+## Repo Table
+
+| Repo | Local Path | Pkg Manager | Update Command | Verify Command | Notes |
+|------|-----------|-------------|----------------|----------------|-------|
+| `mermaid-js/mermaid` | `~/workspaces/zenuml/native-svg-renderer/mermaid` | pnpm | `pnpm --filter @mermaid-js/mermaid-zenuml update @zenuml/core` | `pnpm build` | Direct SVG-renderer integration. Only touch `packages/mermaid-zenuml`; export API changes may require source edits in addition to the version bump. |
+| `mermaid-js/mermaid-live-editor` | clone if missing | pnpm | `pnpm update @mermaid-js/mermaid-zenuml` | `pnpm build` | Indirect SVG-renderer consumer via `@mermaid-js/mermaid-zenuml`. Do not add `@zenuml/core` directly here. |
+| `ZenUml/web-sequence` | `~/workspaces/zenuml/web-sequence` | yarn | `yarn upgrade @zenuml/core` | `yarn build` | HTML-renderer consumer. Do not migrate to SVG-renderer APIs during routine propagation. |
+| `ZenUml/confluence-plugin-cloud` | `~/workspaces/zenuml/confluence-plugin-cloud` | pnpm | `pnpm update @zenuml/core` | `pnpm build:full` | HTML-renderer consumer. Do not migrate to SVG-renderer APIs during routine propagation. |
+| `ZenUml/diagramly.ai` | `~/workspaces/diagramly/diagramly.ai` | pnpm | `pnpm update @zenuml/core --filter <pkg>` | `pnpm build` | HTML-renderer consumer. Do not migrate to SVG-renderer APIs during routine propagation. |
+| `ZenUml/jetbrains-zenuml` | `~/workspaces/zenuml/jetbrains-zenuml` | — | See notes | — | **Not an npm consumer.** Vendors a built JS bundle. Update by copying the new `dist/` output from core's build. Skip if unsure and report. |
+
+## Lockfile Handling
+
+After every dependency update, regenerate the lockfile:
+
+- **pnpm**: `pnpm install` (updates `pnpm-lock.yaml`)
+- **yarn**: `yarn install` (updates `yarn.lock`)
+
+Always commit the lockfile alongside the `package.json` change. A PR without an updated lockfile will fail CI.
+
+## Clone Strategy
+
+If a local path does not exist:
+
+```bash
+gh repo clone <repo-slug> <local-path>
+```
+
+Then proceed with fetch + branch creation as usual.
+
+## General Rules
+
+- Each repo gets its own update branch and its own draft PR.
+- Reuse existing propagation branches or draft PRs when they already target the same core version.
+- `mermaid-js/mermaid` and `mermaid-js/mermaid-live-editor` are under the `mermaid-js` GitHub org (not `ZenUml`).
+- Only `mermaid-js/mermaid` and `mermaid-js/mermaid-live-editor` should receive SVG-renderer integration changes tied to core API/export changes.
+- Treat all other downstreams as HTML-renderer consumers unless the user explicitly asks for a renderer migration.

package/.claude/skills/ship-branch/SKILL.md

@@ -10,6 +10,8 @@ Orchestrate the full path from local branch to npm release. This skill composes
 ## Flow
 
 ```
+rebase on origin/main → CONFLICT → stop, report
+     | CLEAN
 validate-branch → FAIL → stop, report
      | PASS
 submit-branch → FAIL → stop, report
@@ -25,6 +27,17 @@ land-pr → PUBLISH FAIL → alert, stop
 
 ## Steps
 
+### Step 0: Rebase on remote main
+
+Fetch and rebase onto `origin/main` to ensure the branch is up to date before validating.
+
+```bash
+git fetch origin main
+git rebase origin/main
+```
+
+If the rebase has conflicts, stop immediately and report. The developer must resolve conflicts manually before shipping.
+
 ### Step 1: Validate locally
 
 Invoke `/validate-branch`. If it reports FAIL, stop and show the failure. The developer needs to fix locally before shipping.