@zenuml/core 3.47.1 → 3.47.2

package/docs/superpowers/plans/2026-03-30-self-correcting-scoring.md

@@ -0,0 +1,206 @@
+# Self-Correcting Dia-Scoring Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a gap-detection and self-correction validation loop to the dia-scoring skill so it automatically detects and fixes analyzer blind spots during normal scoring runs.
+
+**Architecture:** The entire change is a new section in `SKILL.md` — behavioral instructions that tell the agent to cross-reference the diff panel's pixel clusters against the analyzer's coverage map, triage unaccounted clusters, and fix `collect-data.mjs` when the gap is a selector/extraction miss. No new scripts or tooling.
+
+**Tech Stack:** Markdown (SKILL.md), Playwright browser_evaluate (runtime), collect-data.mjs (runtime fixes)
+
+---
+
+### Task 1: Add "Gap Detection and Self-Correction" section to SKILL.md
+
+**Files:**
+- Modify: `/Users/pengxiao/.claude/skills/dia-scoring/SKILL.md` (append new section after the existing "Known Analyzer Internals" section, before "Commands")
+
+- [ ] **Step 1: Add the new section**
+
+Open `/Users/pengxiao/.claude/skills/dia-scoring/SKILL.md` and insert the following section between the "Known Analyzer Internals" section (line 167) and the "Commands" section (line 175):
+
+```markdown
+## Gap Detection and Self-Correction
+
+After running the analyzer and producing the JSON report, **automatically validate** that the report covers all visible diff clusters. Do not wait for the user to request calibration.
+
+### Step 1: Build a Coverage Map
+
+Collect every fine-grained bounding box from the analyzer JSON:
+- `html_box` / `svg_box` from labels, numbers, arrows
+- `html_icon_box` / `svg_icon_box` from participant icons
+- `label_box` from participant labels
+- `stereotype_box`, `comment_box`, `divider_box`, occurrence boxes, etc.
+
+Use the most specific boxes available (e.g., `icon_box` rather than the coarse `participant_box`) to avoid masking sub-element gaps.
+
+### Step 2: Find Unaccounted Diff Clusters
+
+Scan the `#diff-panel canvas` for connected clusters of red (HTML-only) or blue (SVG-only) pixels. Filter noise (clusters < 20 pixels). A cluster is **covered** when:
+
+- The cluster's centroid falls inside a reported element's bounding box, OR
+- The overlap between the cluster and a reported element's box is >= 30% of the cluster's area
+
+Clusters meeting neither condition are **unaccounted** and trigger investigation.
+
+`colorDiff` (purple) pixels within a covered region are expected and do not trigger investigation.
+
+### Step 3: Verify Coordinate Mapping
+
+Before inspecting the DOM at gap coordinates:
+
+1. Derive an initial canvas-to-page mapping from frame/canvas geometry (canvas natural size / frame CSS size).
+2. Probe a known anchor — pick a reported element with known page coordinates and verify the mapping lands on it via `document.elementFromPoint`.
+3. If the probe hits the wrong panel, empty space, or an unrelated element, recalibrate once using the probe result.
+4. If the mapping still fails after one recalibration, mark the cluster as `uncertain` and move on.
+
+### Step 4: Inspect DOM at Gap Coordinates
+
+For each unaccounted cluster with a verified mapping:
+
+1. Use `document.elementFromPoint(x, y)` on both the HTML and SVG panels.
+2. Walk up to the semantic parent (participant, message, fragment) to understand the element's role.
+3. Classify: emoji icon, stereotype, arrow, label, or novel element.
+
+### Step 5: Triage
+
+Classify each gap before acting:
+
+- **`likely_analyzer_gap`** — Element exists on both sides, belongs to an existing scoring category (icons, labels, stereotypes, etc.), but the collection logic missed it. Proceed to fix.
+- **`likely_renderer_residual`** — Element exists on only one side, or the difference is a genuine rendering discrepancy. Report in scoring output but do not modify the analyzer.
+- **`uncertain`** — Cannot determine cause confidently. Report with DOM context and coordinates for manual review.
+
+Only `likely_analyzer_gap` triggers a self-fix.
+
+### Step 6: Fix the Collection Logic
+
+For `likely_analyzer_gap` clusters:
+
+1. Read the relevant collection function in `collect-data.mjs` (e.g., `collectHtmlParticipants` for participant sub-elements).
+2. Compare the function's selectors and extraction logic against the actual DOM element's tag, classes, and attributes.
+3. Identify why it wasn't matched.
+4. Fix the collection logic. This may include: adding selector patterns, adding fallback extraction paths, adjusting pairing logic, or modifying measurement paths. Keep changes targeted — no broad refactors.
+
+This fixes the measurement tool, not the renderers.
+
+### Step 7: Re-run and Verify
+
+1. Re-run the analyzer on the target case. Confirm the previously-unaccounted cluster is now covered and semantically correct.
+2. Run 1-2 sibling cases with the same element family and confirm: populated data, no regression in previously-working sections.
+
+### Safety Limits
+
+- Maximum **2 fix-and-rerun iterations** per scoring session.
+- Only auto-fix `likely_analyzer_gap` that maps to an existing scoring category and collection function.
+- Novel element types (no existing category): report as unresolved with element identity and coordinates.
+
+### Limitations
+
+- **Invisible diffs**: If an element renders identically in both HTML and SVG (no diff pixels), this loop cannot detect that the analyzer doesn't cover it. The loop is reactive to visible differences only.
+- **Novel categories**: The loop can detect and report novel element types but does not create new scoring categories autonomously.
+```
+
+- [ ] **Step 2: Update the participant icons scope line**
+
+In the same file, find line 74:
+
+```markdown
+  - participant icons (actor, database, ec2, lambda, azurefunction, sqs, sns, iam, boundary, control, entity)
+```
+
+Replace with:
+
+```markdown
+  - participant icons (actor, database, ec2, lambda, azurefunction, sqs, sns, iam, boundary, control, entity, and emoji-based icons like 🌐, 🔒, 🗄️)
+```
+
+This documents that emoji icons are in scope, which the self-correction loop discovered.
+
+- [ ] **Step 3: Verify the edit is well-formed**
+
+Read the modified SKILL.md and confirm:
+- The new section appears between "Known Analyzer Internals" and "Commands"
+- No existing sections were accidentally modified
+- The markdown renders correctly (no broken formatting)
+
+Run: `cat /Users/pengxiao/.claude/skills/dia-scoring/SKILL.md | head -250`
+Expected: The new "Gap Detection and Self-Correction" section is visible, followed by the existing "Commands" section.
+
+- [ ] **Step 4: Commit**
+
+```bash
+cd /Users/pengxiao/workspaces/zenuml/mmd-zenuml-core
+git add /Users/pengxiao/.claude/skills/dia-scoring/SKILL.md
+git commit -m "feat(dia-scoring): add gap detection and self-correction validation loop"
+```
+
+---
+
+### Task 2: Validate the self-correction loop on the emoji-async-return case
+
+This task verifies the new skill instructions work end-to-end by running a scoring session on the case that originally exposed the gap.
+
+**Files:**
+- No files created or modified — this is a validation task
+
+- [ ] **Step 1: Run the analyzer on emoji-async-return**
+
+```bash
+cd /Users/pengxiao/workspaces/zenuml/mmd-zenuml-core
+node scripts/analyze-compare-case.mjs --case emoji-async-return --json 2>&1 | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+icons = data.get('participant_icons', [])
+print(f'participant_icons count: {len(icons)}')
+for icon in icons:
+    print(f'  {icon.get(\"name\", \"?\")} — presence html:{icon.get(\"presence\",{}).get(\"html\")} svg:{icon.get(\"presence\",{}).get(\"svg\")} status:{icon.get(\"status\")}')
+"
+```
+
+Expected: `participant_icons count: 0` (the analyzer doesn't detect emoji icons yet — this confirms the gap exists before the self-correction loop runs).
+
+- [ ] **Step 2: Navigate to the compare-case page and read the diff panel**
+
+Using Playwright:
+1. Navigate to `http://localhost:8080/e2e/tools/compare-case.html?case=emoji-async-return`
+2. Wait for `[native-diff-ext] Done!` in console
+3. Read the `#diff-panel canvas` pixel data via `browser_evaluate`
+4. Identify unaccounted clusters in the participant icon region
+
+Expected: The diff panel shows HTML-only and SVG-only pixel clusters around the emoji icons (🌐, 🔒, 🗄️) that are not covered by any reported element in the analyzer output.
+
+- [ ] **Step 3: Follow the self-correction loop**
+
+Execute steps 1-7 of the new "Gap Detection and Self-Correction" section:
+1. Build coverage map from analyzer JSON
+2. Find unaccounted clusters (the icon regions)
+3. Verify coordinate mapping with a known anchor probe
+4. Inspect DOM at gap coordinates — find `span.mr-1.flex-shrink-0` (HTML) and emoji `tspan` (SVG)
+5. Triage as `likely_analyzer_gap` (element exists on both sides, belongs to participant icons category)
+6. Fix `collect-data.mjs` — add emoji icon detection to both `collectHtmlParticipants` and `collectSvgParticipants`
+7. Re-run analyzer, verify icons are now detected. Run 1-2 sibling emoji cases.
+
+Expected: After the fix, `participant_icons count: 3` with all three emoji icons detected and scored.
+
+- [ ] **Step 4: Commit the collect-data.mjs fix**
+
+```bash
+cd /Users/pengxiao/workspaces/zenuml/mmd-zenuml-core
+git add scripts/analyze-compare-case/collect-data.mjs
+git commit -m "fix(analyzer): detect emoji-based participant icons in collect-data"
+```
+
+---
+
+### Task 3: Commit the design spec
+
+**Files:**
+- Stage: `docs/superpowers/specs/2026-03-30-self-correcting-scoring-design.md`
+
+- [ ] **Step 1: Commit the spec**
+
+```bash
+cd /Users/pengxiao/workspaces/zenuml/mmd-zenuml-core
+git add docs/superpowers/specs/2026-03-30-self-correcting-scoring-design.md
+git commit -m "docs: add self-correcting dia-scoring design spec"
+```

package/e2e/data/compare-cases.js

@@ -843,6 +843,39 @@ OrderService.handle() {
 B -> C: forward
 ==Done==`,
 
+  // --- Emoji ---
+  "emoji-participant": `[rocket] Production
+Production.deploy()`,
+  "emoji-multi-participants": `[rocket] Production
+[lock] Auth
+[fire] Cache
+Production->Auth: validate
+Auth->Cache: lookup`,
+  "emoji-with-type": `@Database [fire] HotDB
+@Actor [eyes] Reviewer
+Reviewer->HotDB: query`,
+  "emoji-with-stereotype": `<<service>> [lock] Auth
+<<gateway>> [rocket] API
+API->Auth: authenticate`,
+  "emoji-no-emoji-baseline": `Production
+Auth
+Cache
+Production->Auth: validate
+Auth->Cache: lookup`,
+  "emoji-async-message": `A
+B
+A->B: [rocket] launching`,
+  "emoji-alt-condition": `A
+B
+A->B: [check] start
+if(success) {
+  A->B: [rocket] proceed
+}`,
+  "emoji-comment": `A
+B
+// [eyes] review this
+A->B: process`,
+
   // --- Icons ---
   "icons": `@Actor User
 @Database DB
@@ -854,4 +887,204 @@ User.login() {
   MQ.enqueue()
   Topic.publish()
 }`,
+
+  // --- Emoji parity cases ---
+  "emoji-sync-call": `[rocket]A.method() {
+  [database]B.query()
+}`,
+  "emoji-nested-calls": `[globe]API.handle() {
+  [lock]Auth.validate() {
+    [database]DB.lookup()
+  }
+}`,
+  "emoji-async-return": `[globe]API->[lock]Auth: validate
+Auth->[database]DB: lookup
+DB-->Auth: [check] found
+Auth-->API: [check] authorized`,
+  "emoji-with-fragment": `[rocket]Client->[lock]Server.request()
+if(authorized) {
+  Server->[database]DB.query()
+  DB-->Server: [check] result
+} else {
+  Server-->Client: [x] denied
+}`,
+  "emoji-divider-case": `[rocket]A->[lock]B.start()
+== [fire] Deploy Phase ==
+B->[database]C.migrate()`,
+  "emoji-group-case": `group Backend {[database]DB [cache]Redis}
+[globe]Gateway->DB.query()
+Gateway->Redis.get()`,
+  "emoji-group-case-2groups": `group Backend {[database]DB [cache]Redis}
+group Frontend {[globe]Gateway}
+Gateway->DB.query()
+Gateway->Redis.get()`,
+  "group-minimal": `group x {a}`,
+  "group-single-participant": `group Frontend {[globe]Gateway}
+group Backend {[database]DB}
+Gateway->DB.query()`,
+  "emoji-comment-styled": `// [eyes] monitoring
+[rocket]A->[lock]B.deploy()
+// [rocket, red] critical path
+B->[database]C.write()`,
+  "emoji-colon-override": `[:red:] Alert
+[rocket] Normal
+Alert->Normal.notify()`,
+  "emoji-icon-combo": `@Actor [star] Admin
+@Database [fire] HotDB
+Admin->HotDB.query()`,
+  "emoji-long-names": `[rocket]ProductionServer->[lock]AuthService.validate()
+AuthService->[database]UserDB.find()
+UserDB-->AuthService: [check] found`,
+  "emoji-simple-async": `[rocket]A->[lock]B: hello
+B-->A: [check] done`,
+  "emoji-self-call": `[gear]Processor.init() {
+  Processor.validate()
+}`,
+  "emoji-title": `title [rocket] Deploy Pipeline
+[lock]A->[database]B.save()`,
+  // emoji variants of existing patterns
+  "emoji-nested-sync-deep": `[rocket]A.methodA() {
+  [lock]B.methodB() {
+    [database]C.methodC() {
+      [fire]D.process()
+    }
+  }
+}`,
+  "emoji-async-many": `[rocket]A [lock]B [database]C
+A->B: [check] msg1
+B->C: [fire] msg2
+C->B: [check] result
+B->A: [check] done`,
+  "emoji-if-else": `[rocket]Client->[lock]Server.request()
+if(valid) {
+  Server->[database]DB.query()
+} else {
+  Server-->Client: [x] denied
+}`,
+  "emoji-tcf": `[globe]A.process() {
+  try {
+    [database]B.save()
+  } catch(e) {
+    [warning]C.handle()
+  } finally {
+    [gear]D.cleanup()
+  }
+}`,
+  "emoji-loop": `[rocket]A->[lock]B.fetch()
+loop(retries < 3) {
+  B->[database]C.query()
+  C-->B: [check] ok
+}`,
+  "emoji-par": `[rocket]Orchestrator.run() {
+  par {
+    [database]DB.write()
+    [cache]Redis.flush()
+  }
+}`,
+  "emoji-return-chain": `[globe]API->[lock]Auth.check() {
+  Auth->[database]DB.query() {
+    DB-->Auth: [check] found
+  }
+  Auth-->API: [check] valid
+}`,
+  "emoji-creation-simple": `[rocket]A.init() {
+  new B()
+}`,
+  "emoji-color": `[rocket] Prod #FF6600
+[lock] Auth #0747A6
+Prod->Auth.validate()`,
+  "emoji-stereotype-only": `<<service>> [lock] Auth
+<<gateway>> [globe] API
+API->Auth.check()`,
+  "emoji-method-name": `A.[rocket]deploy()
+A.[lock]validate()
+A->[database]B.[fire]save()`,
+  "emoji-condition-label": `[rocket]Client->[lock]Server.request()
+if(authorized) {
+  Server->[database]DB.query()
+  DB-->Server: [check] result
+} else {
+  Server-->Client: [x] denied
+}`,
+  "emoji-in-conditions": `if([check] authorized) {
+  A.proceed()
+} else if([warning] rate limited) {
+  A.wait()
+} else {
+  A.deny()
+}`,
+  "emoji-tcf-labels": `A.process() {
+  try {
+    B.save()
+  } catch(DatabaseError) {
+    C.rollback()
+  } finally {
+    D.cleanup()
+  }
+}`,
+  "emoji-loop-condition": `while([rocket] deploying) {
+  A->[database]B.check()
+  B-->A: [check] status
+}`,
+  "emoji-opt-critical": `[rocket]A->[lock]B.request()
+opt {
+  B.[gear]process()
+}
+critical([warning] important) {
+  B->[database]C.save()
+}`,
+  "emoji-nested-mixed": `[globe]Client->[lock]Server.handle() {
+  if([check] cached) {
+    Server->[cache]Redis.[rocket]get()
+  } else {
+    Server->[database]DB.[fire]query() {
+      try {
+        DB.[gear]process()
+      } catch(timeout) {
+        DB-->Server: [warning] retry
+      }
+    }
+  }
+}`,
+  "emoji-all-features": `title [rocket] System Overview
+@Actor [star] Admin
+@Database [fire] DB
+<<service>> [lock] Auth
+[globe] API
+
+// [eyes] authentication flow
+Admin->API.[key]login(credentials)
+API->Auth.[lock]validate(token) {
+  if([check] valid) {
+    Auth->DB.[fire]query(userId)
+    DB-->Auth: [check] found
+  } else {
+    Auth-->API: [x] denied
+  }
+}
+== [rocket] deploy phase ==
+API->[gear]Worker: [rocket] process`,
+  "emoji-chained-calls": `[rocket]A.[lock]auth().[fire]process().[check]save()`,
+  "emoji-assign-return": `[globe]API->[lock]Auth.check() {
+  result = [database]DB.query()
+  return [check] authorized
+}`,
+  "emoji-multi-async": `[rocket]A->[lock]B: [fire] step 1
+B->[database]C: [gear] step 2
+C->[globe]D: [check] step 3
+D-->A: [check] all done`,
+  "emoji-named-params": `[rocket]A.[lock]method(userId=123, name="John")
+[database]B.[fire]create(type="User", active=true)`,
+  "emoji-self-sync": `[gear]selfSync() {
+  [rocket]A.[lock]method() {
+    [database]B.save()
+  }
+}`,
+  "emoji-fragments-return": `[rocket]A.[lock]method() {
+  if([check] x) {
+    return [check] success
+  } else {
+    return [x] failure
+  }
+}`,
 };

package/e2e/tools/compare-case.html

@@ -17,6 +17,9 @@
       .nav button { padding: 4px 12px; background: #7c3aed; border: none; border-radius: 4px; color: white; font-size: 12px; cursor: pointer; }
       .nav button:hover { background: #6d28d9; }
       .nav button:disabled { background: #64748b; cursor: wait; }
+      .nav-btn { display: inline-flex; align-items: center; justify-content: center; width: 28px; height: 28px; background: #334155; border: none; border-radius: 4px; color: white; font-size: 16px; cursor: pointer; text-decoration: none; line-height: 1; }
+      .nav-btn:hover { background: #475569; }
+      .nav-btn[style*="hidden"] { visibility: hidden; }
       .nav .match-badge { font-size: 11px; color: #94a3b8; }
       .container { display: flex; gap: 0; }
       .container.stacked { flex-direction: column; }
@@ -35,8 +38,8 @@
       <a href="/e2e/tools/compare.html">&larr; All cases</a>
       <h2 id="case-name"></h2>
       <div class="nav">
-        <a id="prev-link" href="#">&larr; Prev</a>
-        <a id="next-link" href="#">Next &rarr;</a>
+        <a id="prev-link" class="nav-btn" href="#" title="Previous case">&#8249;</a>
+        <a id="next-link" class="nav-btn" href="#" title="Next case">&#8250;</a>
         <span class="match-badge" id="match-badge"></span>
       </div>
     </div>
@@ -87,6 +90,15 @@
         nextLink.style.visibility = "hidden";
       }
 
+      // Keyboard navigation
+      document.addEventListener("keydown", (e) => {
+        if (e.key === "ArrowLeft" && prevLink.style.visibility !== "hidden") {
+          window.location.href = prevLink.href;
+        } else if (e.key === "ArrowRight" && nextLink.style.visibility !== "hidden") {
+          window.location.href = nextLink.href;
+        }
+      });
+
       // Expose DSL for the extension's batch mode to read
       window.__currentDSL = code || "";
 
@@ -296,7 +308,9 @@
         if (htmlFrame) {
           const frameRect2 = htmlFrame.getBoundingClientRect();
           // Hide SVG icons in the header area (top 35px) — checkbox, etc.
+          // Skip group outline overlays (data-group-overlay) which are functional rendering elements.
           htmlFrame.querySelectorAll("svg").forEach(svg => {
+            if (svg.hasAttribute("data-group-overlay")) return;
             const r = svg.getBoundingClientRect();
             if (r.width > 0 && (r.top - frameRect2.top) < 35) _hideEl(svg);
           });

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@zenuml/core",
-  "version": "3.47.1",
+  "version": "3.47.2",
   "private": false,
   "license": "MIT",
   "repository": {
     "url": "https://github.com/mermaid-js/zenuml-core"
   },
   "scripts": {
-    "dev": "vite dev --port 8080 --host 0.0.0.0",
-    "preview": "bun run --bun vite preview --port 8080 --host",
+    "dev": "vite dev --port 4000 --host 0.0.0.0",
+    "preview": "bun run --bun vite preview --port 4000 --host",
     "build:site": "bun run --bun vite build",
     "build:gh-pages": "bun run --bun vite build --mode gh-pages",
     "build": "bun run --bun vite build -c vite.config.lib.ts",

package/playwright.config.ts

@@ -1,6 +1,6 @@
 import { defineConfig, devices } from "@playwright/test";
 
-const PORT = Number(process.env.PORT) || 8080;
+const PORT = Number(process.env.PORT) || 4000;
 const BASE_URL = `http://127.0.0.1:${PORT}`;
 
 export default defineConfig({