@zenuml/core 3.47.9 → 3.48.1

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

@@ -1,76 +0,0 @@
----
-name: submit-branch
-description: Push the current branch and create or reuse a PR on mermaid-js/zenuml-core. Use when the user says "submit", "create PR", "push and PR", "open a pull request", "submit branch", or wants to publish their work as a PR without merging. Does not fix CI or merge — those are separate skills.
----
-
-# Submit Branch
-
-Publish the current branch as a pull request on `mermaid-js/zenuml-core`. Reuses an existing PR if one already exists for this branch.
-
-## Preconditions
-
-The worktree must be in a committable state:
-
-- **Clean worktree** — nothing to commit, just push. This is the ideal case.
-- **Scoped changes** — all modified files relate to the current work. Stage and commit them.
-- **Mixed/unrelated changes** — modified files include unrelated work. **Stop and ask the user** which files to include. Never auto-commit a mixed worktree.
-
-To check: `git status` and review the file list. If in doubt, ask.
-
-## Steps
-
-### 1. Check worktree state
-
-```bash
-git status
-```
-
-If dirty, evaluate whether changes are scoped (all related to the branch's purpose) or mixed. If mixed, stop and ask.
-
-If scoped, stage the relevant files and commit with a descriptive message. Follow the repo's commit conventions (one-line message, Co-Authored-By trailer).
-
-### 2. Push
-
-```bash
-git push -u origin <branch-name>
-```
-
-Use regular push — never force-push. If push fails due to upstream changes, report the conflict and stop.
-
-### 3. Create or reuse PR
-
-Check if a PR already exists:
-
-```bash
-gh pr view --json number,title,url 2>/dev/null
-```
-
-If a PR exists, report its URL and stop — nothing more to do.
-
-If no PR exists, create one:
-
-```bash
-gh pr create --title "<concise title>" --body "$(cat <<'EOF'
-## Summary
-<bullet points>
-
-## Test plan
-<what was tested>
-EOF
-)"
-```
-
-The PR targets `main` on `mermaid-js/zenuml-core`.
-
-## Output
-
-Report:
-
-- **SUBMITTED** — PR number, URL, and branch name
-- **FAILED** — what went wrong (dirty worktree, push conflict, gh error)
-
-## Does NOT
-
-- Run tests or lint (use `/validate-branch` for that)
-- Fix CI failures (use `/babysit-pr` for that)
-- Merge the PR (use `/land-pr` for that)

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

@@ -1,72 +0,0 @@
----
-name: validate-branch
-description: Run local validation checks on the current branch before shipping. Use when the user says "validate", "check branch", "am I good", "run tests", "preflight", "is this ready", or wants to verify their branch passes all checks before pushing or creating a PR. Also use as a precondition check before invoking submit-branch or ship-branch.
----
-
-# Validate Branch
-
-Verify the current branch passes all local checks. This is the "am I good?" skill — run it anytime before shipping, or just to check your work.
-
-## Why this order matters
-
-Checks run fastest-first so you get feedback quickly. Lint catches syntax issues in seconds. Unit tests catch logic errors in a few seconds. Playwright E2E is slowest (~1-2 min) and catches integration regressions. No point waiting for E2E if lint fails.
-
-## Steps
-
-Run from the `zenuml-core` directory. Stop on first failure.
-
-### 1. Lint
-
-```bash
-bun eslint
-```
-
-If lint fails, report the errors and stop. These are usually quick fixes.
-
-### 2. Unit tests
-
-```bash
-bun run test
-```
-
-Do NOT use `bun test` — it picks up Playwright files and gives false failures. If tests fail, report the failing test names and stop.
-
-### 3. Playwright E2E
-
-Before running Playwright, make sure port `8080` is either free or owned by a dev server started from **this repo**. `playwright.config.ts` uses `reuseExistingServer`, so an unrelated Vite server on `8080` will cause false results.
-
-```bash
-PORT="${PORT:-8080}"
-THIS_REPO="$(pwd -P)"
-LISTENER_PID="$(lsof -tiTCP:${PORT} -sTCP:LISTEN 2>/dev/null | head -n1 || true)"
-
-if [ -n "$LISTENER_PID" ]; then
-  LISTENER_CMD="$(ps -p "$LISTENER_PID" -o command=)"
-  if [[ "$LISTENER_CMD" != *"$THIS_REPO"* ]]; then
-    echo "Port ${PORT} is owned by another repo; killing PID ${LISTENER_PID}"
-    kill "$LISTENER_PID"
-  fi
-fi
-```
-
-If you killed a different repo's server, do **not** start Vite manually. `bun pw` will launch the correct dev server from this folder via Playwright's `webServer` config.
-
-```bash
-bun pw
-```
-
-If snapshot tests fail, check whether the changes are intentional (rendering code changed) or unexpected. Report which snapshots failed.
-
-## Output
-
-Report one of:
-
-- **PASS** — all 3 checks passed, branch is ready
-- **FAIL** — which check failed, the error output, and a one-line suggestion
-
-## Gotchas
-
-- `bun run test` not `bun test` — critical difference, the latter runs E2E too
-- Playwright needs browsers installed (`bun pw:install` if missing)
-- Before `bun pw`, verify any existing `8080` listener belongs to this repo; otherwise kill it and let Playwright start the right server
-- HTML Playwright snapshot failures are a hard stop — never update HTML snapshots without understanding why they changed

package/.claude/skills/zenuml-ux-research/SKILL.md

@@ -1,183 +0,0 @@
----
-name: zenuml-ux-research
-description: Audit one ZenUML user interaction scenario at a time (e.g., inserting a message, renaming a participant) against diagramming-tool best practices. Uses claude-in-chrome to walk through the flow in a live browser and writes a gap-only markdown report to docs/ux-research/. Use when the user says "audit ux of", "zenuml ux research", "analyze interaction for zenuml", "run ux research on", or "/zenuml-ux-research". Produces a research report, not an audit pass/fail matrix.
----
-
-# ZenUML UX Research
-
-This skill audits a single ZenUML interaction scenario against diagramming-tool best practices and writes a gap-only markdown report. It is a research tool, not an audit or regression tool. Run it interactively, read the report, and act on it by hand. Never wire it into CI.
-
-## When to invoke
-
-- User asks "audit ux of X", "zenuml ux research", "analyze interaction for X".
-- User runs `/zenuml-ux-research <scenario-id>` or `/zenuml-ux-research "free-text goal"`.
-- User asks for a specific gap analysis in the ZenUML editor experience.
-
-Do NOT invoke this skill for pixel-level comparison (that is `dia-scoring`), parser behavior, or build/deploy tasks.
-
-## Invocation parameters
-
-- **Scenario identifier (positional):** either a catalog ID like `insert-message` or a free-text goal like `"audit how users insert a message between A and B"`.
-- **`--url <url>` (optional):** target URL. Default `http://localhost:4000`. Can point to a deployed staging URL.
-- **`--allow-prod` (optional):** required for any URL that is not `localhost`, `127.0.0.1`, or a known staging subdomain. The skill is read-only against the target, but this flag forces the human to confirm they know they're pointing at a real-users environment.
-
-## Dependencies
-
-- `claude-in-chrome` MCP tools (for walkthrough). If these are not yet loaded in the session, the skill must instruct the user to load them via `ToolSearch` and stop; the walkthrough cannot run in text-only mode.
-- `ZenUML dev server or a reachable URL` (default `http://localhost:4000`).
-- `Read` / `Grep` tools (for static source analysis of `zenuml-core/src/`).
-- `WebSearch` / `WebFetch` tools (for targeted best-practice lookups; optional).
-
-## Files this skill uses at runtime
-
-- `references/scenarios/<scenario-id>.md` — loaded at Phase A.
-- `references/assertion-catalog.md` — loaded at Phase B.
-- `references/best-practices-overview.md` — loaded at Phase B for narrative framing.
-- `references/report-template.md` — loaded at Phase F.
-
-## Report output
-
-- Written to `zenuml-core/docs/ux-research/YYYY-MM-DD-<scenario-id>.md`.
-- Create the directory if it doesn't exist (`mkdir -p`).
-- On filename collision, append `-2`, `-3`, etc. Never overwrite.
-- Never commit the report automatically — the human decides.
-
-## Workflow
-
-### Phase A — Scenario resolution
-
-1. Determine whether the invocation is a catalog ID or free-text.
-2. **Catalog ID:**
-   - Check that `references/scenarios/<id>.md` exists.
-   - If not, list all available scenario filenames (glob `references/scenarios/*.md`) and stop.
-   - Load the file. Verify it has front matter with `id` and `title`, plus headings for `User intent`, `Starting DSL`, `Target DSL`, `Relevant assertion categories`. If any are missing, print which field is missing from which file and stop.
-3. **Free-text:**
-   - Synthesize a scenario record with the same fields (id, title, user intent, starting DSL, target DSL, relevant categories).
-   - Present the synthesized record to the user and wait for explicit confirmation.
-   - Do NOT proceed on an unconfirmed synthesized scenario.
-4. Check `--url` reachability with a quick HTTP GET.
-   - If unreachable and the URL is local: print the exact fix command (`cd /Users/penxia/ai-personal/zenuml-core && bun run dev`) and stop.
-   - If unreachable and the URL is remote: print the HTTP status and stop.
-   - If reachable and the URL is non-local but does NOT have `--allow-prod`: warn and stop. Non-local URLs that look like known staging patterns (e.g., contain `staging`, `preview`, `github.io` for the gh-pages build) may proceed with a one-line warning but no hard stop.
-5. Confirm `claude-in-chrome` tools are loaded. If not: instruct the user to load them via `ToolSearch` with query `"select:mcp__claude-in-chrome__tabs_context_mcp,mcp__claude-in-chrome__tabs_create_mcp,mcp__claude-in-chrome__navigate,mcp__claude-in-chrome__find,mcp__claude-in-chrome__computer,mcp__claude-in-chrome__read_page,mcp__claude-in-chrome__read_console_messages,mcp__claude-in-chrome__javascript_tool"` and stop.
-
-### Phase B — Hypothesis formation
-
-1. Read the scenario's User intent.
-2. Read `references/best-practices-overview.md` for narrative framing.
-3. Scan `references/assertion-catalog.md` for rules whose category is in the scenario's Relevant assertion categories list. Treat these as **priors** — starting points for what you expect to see — not as a checklist.
-4. Form a short list of expectations in working memory. Example for `rename-participant`: "I expect Enter on selected participant to enter edit mode (KBD-03). I expect caret at end (EDT-02). I expect Escape to cancel (KBD-04). I expect undo granularity to be at the label level (UND-02)."
-5. **Hypotheses are NOT limited to the catalog.** Form open-ended expectations based on general best practices and common sense. If the scenario suggests territory the catalog is silent on, run **1–3** targeted `WebSearch` queries (e.g., "how does tldraw handle arrow-key navigation between shapes"). Keep the budget tight.
-
-### Phase C — Browser walkthrough
-
-1. `mcp__claude-in-chrome__tabs_context_mcp` → get current tab state (do not reuse existing tabs from prior sessions).
-2. `mcp__claude-in-chrome__tabs_create_mcp` → open a new tab.
-3. `mcp__claude-in-chrome__navigate` → navigate to the `--url`.
-4. Wait for the page to load. `mcp__claude-in-chrome__read_console_messages` at each interaction to catch runtime errors.
-5. **Seed the starting state** by interacting with the DSL editor pane to type the scenario's Starting DSL. This is setup, not walkthrough — failures here are infrastructure errors.
-   - If Starting DSL is empty, no seeding is needed.
-   - If seeding itself fails (e.g., the DSL editor is unreachable), stop, report "could not seed starting state via DSL editor" as a walkthrough-blocker, and do NOT write a report. This is worse than a gap — it's a dead environment.
-6. **Attempt to reach Target DSL via the most discoverable path a new user would try first.** Record each step:
-   - What was attempted (e.g., "clicked canvas area to the right of participant B")
-   - What happened (e.g., "no visible change; console warning: `[zenuml] unknown click target`")
-   - Whether it advanced toward Target DSL
-7. If the first path fails or hits friction, try 1–2 alternative paths (toolbar, keyboard shortcut, DSL edit). Record each.
-8. **Capture screenshots only at decision moments**, not every step — keeps reports readable. Use `mcp__claude-in-chrome__computer` for screenshots if the tool is available.
-9. **Hard stop after 3 failed attempts on the same step.** Record "could not perform step X after 3 attempts" and move on or stop. Do NOT loop.
-
-### Phase D — Gap detection
-
-1. For each observation, compare against the corresponding hypothesis.
-2. **If observation matches hypothesis: drop it. Do not record. Silence is correct.**
-3. **If observation diverges from hypothesis: record a gap.** Each gap has:
-   - Headline (short, e.g., "Enter on selected participant does nothing")
-   - Observed (verbatim)
-   - Expected (from hypothesis)
-   - Catalog ID (scan `references/assertion-catalog.md` for a rule whose `Applies when` and `Check` match; cite that ID. If no rule matches, label the gap `novel — candidate for new rule`.)
-   - Exemplars (from the catalog if cited, else from web search)
-   - Rationale
-   - Severity (`low`, `med`, `high`) — use the catalog rule's severity if cited, else judge based on impact
-4. Novel gaps are flagged but NOT auto-written to the catalog. The human reviews them and folds them in manually later.
-
-### Phase E — Targeted static source analysis
-
-For each gap, use `Grep` on `/Users/penxia/ai-personal/zenuml-core/src/` to find the relevant code path:
-
-- For keyboard interactions: grep for the key name (`'Enter'`, `'Escape'`) and keydown listeners.
-- For selection state: grep for `select`, `Selection`, `aria-selected`, and the Jotai atoms.
-- For inline editing: grep for `contenteditable`, `input`, component names like `Participant`, `Message`.
-- For undo/redo: grep for `undo`, `history`, `Jotai` atoms that track history state.
-
-Attach `file:line` pointers to each gap. If no handler is found, write `"no code path found — this is a missing implementation, not a misrouted one."` Often the most useful finding.
-
-### Phase F — Report writing
-
-1. Load `references/report-template.md`.
-2. Fill in all `{{placeholder}}` fields.
-3. Determine the output path:
-   - Today's date in `YYYY-MM-DD` format.
-   - Filename: `YYYY-MM-DD-<scenario-id>.md`.
-   - Full path: `/Users/penxia/ai-personal/zenuml-core/docs/ux-research/YYYY-MM-DD-<scenario-id>.md`.
-4. Create `docs/ux-research/` if it doesn't exist.
-5. If the filename already exists for today, append `-2`, `-3`, etc.
-6. Write the file.
-7. If gap count is zero, render the zero-gap form (omit Gaps and Playwright snippet sections, collapse the walkthrough to a one-line "No gaps observed on <sha>").
-
-### Phase G — Hand-off
-
-1. Print the report path.
-2. Print a one-line summary: `"Found N gaps (X high, Y med, Z low). Report at <path>."`
-3. Stop. Do NOT:
-   - auto-commit the report
-   - auto-fix any gap
-   - open a PR
-   - notify anyone
-   - run additional scenarios
-
-## Error handling
-
-**Invocation-time (fail fast, clear instructions):**
-
-- Scenario ID not found → list `references/scenarios/*.md` filenames, stop.
-- Free-text goal too ambiguous (e.g., can't infer starting or target DSL) → ask one clarifying question, re-confirm, only proceed on confirmation.
-- Scenario file malformed → print file path and missing field, stop.
-- `claude-in-chrome` tools not loaded → instruct user to load via ToolSearch (query shown above), stop.
-- URL unreachable → print fix command, stop.
-- Non-local URL without `--allow-prod` → warn and stop.
-
-**Walkthrough-time (observe and record, do not panic):**
-
-- Target state unreachable after 2–3 paths → this is itself a high-severity gap. Write a report with "scenario target is unreachable via discovered interaction paths" as the primary finding.
-- Console error mid-walkthrough → captured, included in the walkthrough step, does not halt unless the app becomes unresponsive.
-- Browser crash → stop, print observations so far, do NOT write a partial report.
-- Screenshot failure → skipped, walkthrough step still recorded with `screenshot: failed`.
-- Same step fails 3 times → stop retrying, record "could not perform step X", move on or stop.
-
-**Analysis-time (degrade gracefully):**
-
-- Static analysis finds no handler → say so explicitly.
-- Web search returns nothing → fall back to catalog and common sense.
-- Catalog has no matching rule → label gap `novel`, flag as growth candidate.
-
-**Output-time:**
-
-- `docs/ux-research/` does not exist → create it.
-- Filename collision → append `-2`, `-3`, etc.
-- Git SHA capture fails → write `unknown` in metadata. Do not abort.
-
-## What this skill does NOT do
-
-- Retry failed walkthrough paths indefinitely.
-- Auto-fix any gap.
-- Commit the report, open a PR, notify anyone.
-- Run multiple scenarios in one invocation.
-- Run Playwright — only emits a snippet for the human to use.
-- Touch production deploy state.
-
-## Extending the skill
-
-- **New scenario:** drop a new file into `references/scenarios/`, matching the format of existing scenarios. The skill discovers it automatically.
-- **New assertion rule:** append it to `references/assertion-catalog.md` with the next sequential ID in its category. Never renumber existing rules.
-- **Catalog growth from novel gaps:** when a run flags a `novel` gap, the human reviews and, if appropriate, adds a new rule to the catalog by hand.
-- **Calibration drift:** any substantial change to this SKILL.md should be followed by re-running both calibration scenarios (see the plan document).

package/.claude/skills/zenuml-ux-research/references/assertion-catalog.md

@@ -1,261 +0,0 @@
-# ZenUML UX Assertion Catalog
-
-Atomic, testable best-practice rules for diagramming-tool interactions. Each rule has a stable ID that may be cited in gap reports. The catalog is a **reference library and hypothesis primer**, not a checklist — the skill does NOT grind through all rules on every run.
-
-## Catalog structure
-
-Each rule has:
-
-- **ID** — stable, citable (e.g., `KBD-03`). Category prefix + two-digit number. Never renumber.
-- **Rule** — one sentence describing the expected behavior.
-- **Exemplars** — 2–3 tools where the rule is observed.
-- **Rationale** — why the rule matters.
-- **Applies when** — precondition that must hold for the rule to be meaningful.
-- **Check** — concrete, observable outcome the skill can verify (optional for subjective rules).
-- **Severity** — `low`, `med`, `high`.
-
-New rules are appended; IDs are never reused.
-
----
-
-## SEL — Selection model
-
-### SEL-01
-**Rule:** Clicking an item on the canvas selects it exclusively, deselecting anything else that was selected.
-**Exemplars:** Figma, tldraw, draw.io.
-**Rationale:** The standard single-select model users expect from any canvas editor; anything else forces the user to explicitly clear prior selection.
-**Applies when:** The canvas has at least one selectable item and the user clicks it with a single unmodified click.
-**Check:** Before click: zero or more items selected. After click: only the clicked item is selected.
-**Severity:** high
-
-### SEL-02
-**Rule:** Clicking empty canvas area deselects all items.
-**Exemplars:** Figma, tldraw, Excalidraw.
-**Rationale:** Gives the user an always-available "get out of selection" gesture that does not require keyboard.
-**Applies when:** At least one item is selected and the user clicks an area of the canvas with no item under the cursor.
-**Check:** After click: zero items selected.
-**Severity:** med
-
-### SEL-03
-**Rule:** Selected items have a visible, persistent selection indicator (outline, highlight, or handles).
-**Exemplars:** Figma (blue outline), tldraw (dashed outline), draw.io (handles).
-**Rationale:** Without visual feedback, selection state is invisible and any subsequent keyboard action feels random.
-**Applies when:** One or more items are selected.
-**Check:** The selected item's bounding box has a visually distinct marker compared to its non-selected state.
-**Severity:** high
-
-### SEL-04
-**Rule:** Selection state is exposed to assistive technologies via `aria-selected` or equivalent.
-**Exemplars:** VS Code editor, GitHub file tree.
-**Rationale:** Screen-reader users need programmatic access to selection. Day 1 this rule is observational (the skill notes whether the attribute is present); it is not a hard fail.
-**Applies when:** One or more items are selected.
-**Check:** Inspect DOM for `aria-selected="true"` on the selected element or its representative.
-**Severity:** low
-
----
-
-## KBD — Keyboard interaction
-
-### KBD-01
-**Rule:** Tab moves focus INTO the diagram composite widget from the surrounding page; Shift+Tab moves focus OUT.
-**Exemplars:** VS Code tree view, GitHub file tree, Figma.
-**Rationale:** The diagram is one Tab stop from the page's perspective; arrow keys navigate inside. This is the ARIA composite-widget convention.
-**Applies when:** Focus is on the element immediately before or after the diagram in tab order.
-**Check:** Press Tab; focus lands on the diagram root. Press Tab again from inside; focus leaves the diagram.
-**Severity:** high
-
-### KBD-02
-**Rule:** Arrow keys navigate between items inside the diagram composite widget when it has focus.
-**Exemplars:** Figma (arrows move selection), tldraw, Excalidraw.
-**Rationale:** Once inside the widget, the user needs a keyboard-only way to move the cursor/selection across items.
-**Applies when:** Focus is inside the diagram and at least one item is selectable.
-**Check:** Press an arrow key; focus or selection visibly moves to an adjacent item.
-**Severity:** high
-
-### KBD-03
-**Rule:** Enter on a selected canvas item enters edit mode with the cursor at the end of the item's label.
-**Exemplars:** Figma (text layers), Notion (table cells), tldraw (shapes), VS Code (F2 rename).
-**Rationale:** Keyboard-first editing; no mouse round-trip after selection. The most-expected canvas-editor keybinding after Tab/Arrow.
-**Applies when:** A single selectable item is selected and the diagram widget has focus.
-**Check:** After selection, send Enter. Within 300ms the item's label should become an editable input, focused, with the caret at the end of the existing text.
-**Severity:** high
-
-### KBD-04
-**Rule:** Escape while an item is in edit mode cancels the edit without committing changes.
-**Exemplars:** Figma, Notion, tldraw, VS Code rename.
-**Rationale:** Undoing an in-flight edit should never require actually committing then undoing. Escape is the universal cancel.
-**Applies when:** An item is currently in edit mode and the input has unsaved changes.
-**Check:** Enter edit mode, modify text, press Escape. Label reverts to pre-edit value; item exits edit mode.
-**Severity:** high
-
-### KBD-05
-**Rule:** Escape on a selected (but not editing) item either deselects or exits the widget; it should not silently do nothing.
-**Exemplars:** Figma, tldraw.
-**Rationale:** Escape is the "get me out" key. Silent no-op leaves the user uncertain about what's selected.
-**Applies when:** Focus is inside the diagram and exactly one item is selected (not in edit mode).
-**Check:** Press Escape. Selection clears OR focus leaves the diagram widget.
-**Severity:** med
-
-### KBD-06
-**Rule:** Tab inside edit mode commits the current edit and spawns a new sibling in edit mode (Miro pattern).
-**Exemplars:** Miro sticky notes, Notion database rows, Linear issue creation.
-**Rationale:** Speed-of-flow creation for power users. Not universally expected but is the gold standard when present.
-**Applies when:** An item is in edit mode.
-**Check:** Type label, press Tab. Edit commits; a new sibling of the same type appears next in order, already in edit mode with focus.
-**Severity:** med
-
----
-
-## EDT — Inline editing
-
-### EDT-01
-**Rule:** Entering edit mode replaces the label rendering with a focused, editable input in the same visual position.
-**Exemplars:** Figma, Notion, tldraw.
-**Rationale:** Prevents layout shift and makes the edit feel like direct manipulation rather than a modal.
-**Applies when:** An item is entering edit mode by any means (Enter, double-click, toolbar).
-**Check:** The input element is visible at the label's prior position; no modal or popover opens; the input has focus.
-**Severity:** high
-
-### EDT-02
-**Rule:** On edit mode entry via Enter, the caret is placed at the end of the existing text with no pre-selection.
-**Exemplars:** Notion cell edit, Linear issue title edit.
-**Rationale:** Appending to an existing label (the common case) should not require arrow-right; deleting the whole label should be an explicit second step.
-**Applies when:** Edit mode was entered via Enter on a selected item with an existing, non-empty label.
-**Check:** After entering edit mode, caret is at end-of-text; no characters are pre-selected.
-**Severity:** med
-
-### EDT-03
-**Rule:** Edit mode entered on a newly inserted item places an empty input with focus, ready to accept typing.
-**Exemplars:** Miro sticky notes, Notion new row, tldraw new shape.
-**Rationale:** New items should not require a second click to start typing.
-**Applies when:** A new item was just inserted and is expected to be named.
-**Check:** Immediately after insertion, the item is in edit mode with an empty input and keyboard focus.
-**Severity:** high
-
-### EDT-04
-**Rule:** Committing an edit (Enter or blur) persists the change; cancelling (Escape) discards without side-effects.
-**Exemplars:** Figma, Notion, VS Code rename.
-**Rationale:** The commit/cancel contract is the most-trusted UX primitive in inline editing; violating it silently loses user work.
-**Applies when:** An item is in edit mode.
-**Check:** Make an edit. Press Enter → change persists in the DSL and on the canvas. Separately, make an edit and press Escape → change is fully discarded.
-**Severity:** high
-
----
-
-## FOC — Focus management
-
-### FOC-01
-**Rule:** After inserting a new item via keyboard, focus lands on the new item in edit mode.
-**Exemplars:** Miro stickies, tldraw new shapes, Excalidraw text boxes.
-**Rationale:** The user's next likely action on a new item is to name it. Requiring a separate selection step is friction.
-**Applies when:** An insertion was triggered via keyboard (shortcut, Tab-to-sibling, Enter on a "plus" affordance).
-**Check:** Immediately after insertion, the new item is selected AND in edit mode AND has keyboard focus.
-**Severity:** high
-
-### FOC-02
-**Rule:** After deleting an item, focus moves to a predictable sibling (previous if any, else next, else parent).
-**Exemplars:** VS Code file explorer, Linear list delete, Notion row delete.
-**Rationale:** Focus-left-hanging after delete is one of the top accessibility complaints in web apps; any sibling is better than the document root.
-**Applies when:** An item is deleted while the diagram widget has focus.
-**Check:** After delete, a sibling or parent element has focus (not `document.body`, not `:focus-visible` on nothing).
-**Severity:** med
-
-### FOC-03
-**Rule:** Undo restores selection and focus to the pre-operation state, not just the data.
-**Exemplars:** Figma undo, Linear undo.
-**Rationale:** The point of undo is to undo what the user *experienced*, which includes selection and focus. Undoing data without selection is disorienting.
-**Applies when:** Undo was triggered after an operation that changed selection or focus.
-**Check:** Before operation: selection = X. After operation: selection = Y. After undo: selection = X.
-**Severity:** med
-
-### FOC-04
-**Rule:** Focus indicator is always visible when keyboard-focused; `:focus-visible` suppression is not applied to the entire widget.
-**Exemplars:** any WAI-ARIA-compliant widget.
-**Rationale:** A keyboard user should always know where focus is.
-**Applies when:** A focusable element inside the diagram is focused via keyboard navigation.
-**Check:** Inspect the focused element; it has a visible focus outline or equivalent.
-**Severity:** med
-
----
-
-## INS — Insertion affordances
-
-### INS-01
-**Rule:** A new item can be inserted without opening or touching the DSL editor pane directly.
-**Exemplars:** Mermaid Live (no, this is a known weakness; cited as a negative exemplar), tldraw (yes), Figma (yes).
-**Rationale:** For a tool that is text-first but growing canvas editing, the canvas should be a primary creation surface. Falling back to the DSL is acceptable; being forced into it is a gap.
-**Applies when:** A scenario's target state requires inserting a new participant, message, note, or other item.
-**Check:** The skill must find at least one insertion path that does not require editing the DSL editor text area.
-**Severity:** high
-
-### INS-02
-**Rule:** The primary insertion affordance is discoverable by a new user within ~10 seconds of looking at the canvas.
-**Exemplars:** tldraw (visible toolbar), Figma (visible plus button).
-**Rationale:** Discoverability is the gateway to every other interaction; hidden affordances turn new users away.
-**Applies when:** A scenario involves inserting something.
-**Check:** Subjective; the skill records whether the insertion affordance was obvious on first look and, if not, how long it took to find.
-**Severity:** med
-
-### INS-03
-**Rule:** Insertion has at least one keyboard-only path.
-**Exemplars:** Miro (Tab-to-sibling), Linear (Cmd+Enter on issues).
-**Rationale:** Text-first tool users are keyboard-native; a mouse-only insertion affordance loses them.
-**Applies when:** A scenario involves inserting something.
-**Check:** The skill must find at least one path from "blank state" to "new item present" that uses only the keyboard.
-**Severity:** high
-
----
-
-## UND — Undo / redo
-
-### UND-01
-**Rule:** Ctrl/Cmd+Z undoes the last logical operation.
-**Exemplars:** every text editor, every canvas editor.
-**Rationale:** The universal baseline.
-**Applies when:** At least one undoable operation has occurred.
-**Check:** Perform operation X. Press Ctrl/Cmd+Z. State reverts to pre-X.
-**Severity:** high
-
-### UND-02
-**Rule:** Undo/redo granularity matches a logical user action, not individual keystrokes during a label edit.
-**Exemplars:** Figma undo, Notion undo, Linear undo.
-**Rationale:** One undo should undo one perceived action. Undoing character-by-character turns Ctrl+Z into an "erase this text" macro, which is worse than useless.
-**Applies when:** A label was edited and then undo was pressed.
-**Check:** Edit a label from `A` to `Alice`. Press Ctrl/Cmd+Z once. The label returns to `A`, not `Alic`.
-**Severity:** high
-
-### UND-03
-**Rule:** Undo restores the selection to the item that was operated on, not an arbitrary state.
-**Exemplars:** Figma, Linear.
-**Rationale:** Undo should put the user back where they can immediately re-try or explore, which requires selection to match.
-**Applies when:** An operation that affected selection is being undone.
-**Check:** Before: select X, modify X. After undo: X is selected again.
-**Severity:** med
-
----
-
-## FBK — Visual feedback
-
-### FBK-01
-**Rule:** Hover states are visible on interactive elements.
-**Exemplars:** every canvas editor.
-**Rationale:** Hover is the pre-interaction affordance; its absence forces trial-and-error clicks.
-**Applies when:** A clickable or draggable element exists on the canvas.
-**Check:** Hover over the element; visual state changes (cursor, outline, tint).
-**Severity:** low
-
-### FBK-02
-**Rule:** Invalid actions show immediate non-blocking feedback rather than silently failing.
-**Exemplars:** Figma toast, Linear inline errors.
-**Rationale:** Silent failure trains users to distrust the tool; even a toast is better than nothing.
-**Applies when:** The user attempts an operation that is not currently valid (e.g., delete with nothing selected).
-**Check:** Trigger an invalid operation. Observe any feedback within 500ms.
-**Severity:** med
-
-### FBK-03
-**Rule:** Drop targets or alignment guides are shown during drag operations where applicable.
-**Exemplars:** Figma smart guides, tldraw snap lines.
-**Rationale:** Without guides, drag feels imprecise.
-**Applies when:** The scenario involves a drag operation.
-**Check:** During an active drag, alignment guides or drop indicators appear before release.
-**Severity:** low

package/.claude/skills/zenuml-ux-research/references/best-practices-overview.md

@@ -1,56 +0,0 @@
-# Diagramming Tool UX — Best-Practice Overview
-
-This document frames the interaction-design context the ZenUML UX research skill reasons about. It is **not** a checklist. Atomic, testable rules live in `assertion-catalog.md`. This file provides the *why* behind the rules.
-
-## Two tool families
-
-Diagramming tools split along a single axis: **what is the primary input method for the user who is actively creating diagram content?**
-
-### Text-first (DSL-driven)
-
-The user types structured text; the rendered diagram is a side-effect.
-
-Examples: **Mermaid Live**, **PlantUML editors**, **D2 Playground**, **ZenUML**.
-
-Typical strengths:
-- Keyboard-first by construction.
-- Versionable, diffable, pasteable content.
-- Fast iteration for users who know the DSL.
-
-Typical weaknesses:
-- Discoverability for new users is poor ("what's the syntax for a loop?").
-- Visual affordances (clicking a participant to rename it, dragging to reorder) are bolted on, not native.
-- Round-trip between "I see a shape on the canvas" and "I edit the text that produced it" is often clunky.
-
-### Drag-first (graphical, canvas-driven)
-
-The user drags shapes; a model is built behind the scenes.
-
-Examples: **Lucidchart**, **draw.io (diagrams.net)**, **Figma**, **Miro**, **tldraw**, **Excalidraw**.
-
-Typical strengths:
-- New-user discoverability is very high.
-- Inline editing on the canvas is the default path.
-- Rich direct-manipulation gestures (drag, marquee, snap).
-
-Typical weaknesses:
-- Power-user keyboard flows are often worse than text-first tools.
-- Hard to version or diff the output.
-- Harder to reuse content across diagrams.
-
-### Hybrids
-
-Some tools occupy the middle and are the most instructive comparisons for ZenUML, which is fundamentally text-first but is growing canvas affordances:
-
-- **Mermaid Live** — text-first with live preview and basic canvas interactions (click-to-select in generated SVG, no canvas editing).
-- **tldraw** / **Excalidraw** — drag-first, but with aggressive keyboard shortcuts and inline editing patterns that text-first tools can borrow.
-- **Notion databases / Airtable** — not diagramming, but their inline edit + Tab-to-sibling patterns are the gold standard for keyboard-first editing in any grid/canvas context.
-- **Miro sticky note flows** — the current "speed of thought" standard for inserting, renaming, and connecting items without touching a mouse.
-
-## Why this matters for ZenUML
-
-ZenUML is text-first but is moving toward canvas-embedded editing. That means every scenario this skill audits has at least two valid interaction paths — DSL and canvas — and the user experience should be coherent across both. The assertion catalog is structured so that each rule is testable in either path; the walkthrough tries the most discoverable new-user path first and notes alternative paths second.
-
-## How this overview is used by the skill
-
-During Phase B (hypothesis formation), the skill reads this overview to calibrate expectations: for a text-first tool, "you can always fall back to the DSL editor" is a valid mitigation; "this requires a mouse" is a valid finding worth recording, because ZenUML's history of DSL-first users means keyboard-only paths matter disproportionately.