@zenuml/core 3.47.1 → 3.47.3

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

@@ -0,0 +1,261 @@
+# 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

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

package/.claude/skills/zenuml-ux-research/references/report-template.md

@@ -0,0 +1,89 @@
+---
+scenario_id: {{scenario_id}}
+scenario_title: {{scenario_title}}
+run_date: {{run_date}}
+zenuml_core_sha: {{zenuml_core_sha}}
+audited_url: {{audited_url}}
+skill_version: 0.1.0
+gap_count: { high: {{gap_count_high}}, med: {{gap_count_med}}, low: {{gap_count_low}} }
+---
+
+# UX Research — {{scenario_title}}
+
+## Executive summary
+
+{{executive_summary}}
+
+## Scenario recap
+
+**User intent:** {{user_intent}}
+
+**Starting DSL:**
+```
+{{starting_dsl}}
+```
+
+**Target DSL:**
+```
+{{target_dsl}}
+```
+
+## Observed walkthrough
+
+{{walkthrough_numbered_steps}}
+
+## Gaps
+
+{{gap_blocks}}
+
+> Each gap block uses this structure:
+>
+> ```
+> ### Gap N — <short headline>
+> **Severity:** <low|med|high>
+> **Catalog ID:** <id or "novel — candidate for new rule">
+> **Observed:** <verbatim>
+> **Expected:** <from hypothesis>
+> **Exemplars:** <tools where expected behavior is seen>
+> **Rationale:** <why this matters>
+> **Suggested fix:** <grep result: file:line; or "no code path found">
+> ```
+>
+> (Blockquote is for documentation inside the template — the rendered report omits it.)
+
+## Coverage
+
+Tested hypotheses (no gap found):
+{{coverage_tested}}
+
+Not tested (out of scope for this scenario):
+{{coverage_out_of_scope}}
+
+Skipped (couldn't form a testable hypothesis):
+{{coverage_skipped}}
+
+## Best-practice sources
+
+**Bundled catalog IDs referenced:**
+{{bundled_sources}}
+
+**Web sources fetched during this run:**
+{{web_sources}}
+
+## Playwright regression snippet
+
+Paste into `zenuml-core/tests/ux/{{scenario_id}}.spec.ts` once the gap is fixed. The skill emits this snippet; it does not run it.
+
+```typescript
+{{playwright_snippet}}
+```
+
+---
+
+## Zero-gap rendering
+
+If the scenario produced zero gaps, render the report omitting the **Gaps** and **Playwright regression snippet** sections. The **Observed walkthrough** section becomes a single line:
+
+> No gaps observed on zenuml-core @ {{zenuml_core_sha}}.
+
+All other sections (metadata, executive summary, scenario recap, coverage, best-practice sources) still render.

package/.claude/skills/zenuml-ux-research/references/scenarios/edit-message-label.md

@@ -0,0 +1,37 @@
+---
+id: edit-message-label
+title: Edit an existing message label
+---
+
+## User intent
+The user has a message `A->B: hello` on the canvas and wants to change the label to `hi`.
+
+## Starting DSL
+```
+A
+B
+A->B: hello
+```
+
+## Target DSL
+```
+A
+B
+A->B: hi
+```
+
+## Relevant assertion categories
+EDT, KBD, SEL, FOC, UND
+
+## Walkthrough hints (not prescriptive)
+- This scenario exercises the inline-edit contract on an existing piece of DSL, not a new one.
+- Candidate paths to try in order:
+  1. Click the message label `hello` once to select, press Enter, retype.
+  2. Double-click the message label.
+  3. Keyboard: navigate to the message via arrows, press Enter.
+  4. Fall back to editing the DSL editor directly.
+- Watch specifically for: undo granularity when the user types `hi` then changes their mind (one undo should revert the whole label, not one character at a time).
+
+## Known issues to watch for (optional)
+- If undo is character-level during a label edit, that is a UND-02 violation.
+- If clicking the message selects the wrong thing (e.g., the arrow instead of the label), that is a SEL-01 violation.

package/.claude/skills/zenuml-ux-research/references/scenarios/insert-message.md

@@ -0,0 +1,36 @@
+---
+id: insert-message
+title: Insert a synchronous message between two participants
+---
+
+## User intent
+The user has two participants `A` and `B` on the canvas and wants to add a synchronous message from `A` to `B` with the label `hello`.
+
+## Starting DSL
+```
+A
+B
+```
+
+## Target DSL
+```
+A
+B
+A->B: hello
+```
+
+## Relevant assertion categories
+INS, KBD, EDT, FOC, FBK
+
+## Walkthrough hints (not prescriptive)
+- This is the most common creation action in any sequence diagramming tool; it is the load-bearing scenario for canvas-first editing of ZenUML.
+- Candidate paths to try in order:
+  1. Click `A`, look for a "send message" affordance or toolbar button, draw/click toward `B`.
+  2. Hover between `A` and `B` in the lifeline area for an inline "+" affordance.
+  3. Keyboard: Tab into widget, select `A`, press a hotkey for "new message".
+  4. Fall back to typing `A->B: hello` into the DSL editor.
+- Watch specifically for: whether a canvas-first path exists at all, whether message creation automatically enters label edit mode on the new message, whether Escape during message creation cancels cleanly.
+
+## Known issues to watch for (optional)
+- If the canvas has no message-creation affordance at all, that is an INS-01 violation at high severity.
+- If the new message is not in edit mode immediately on creation, that is an EDT-03 / FOC-01 violation.

package/.claude/skills/zenuml-ux-research/references/scenarios/insert-participant.md

@@ -0,0 +1,31 @@
+---
+id: insert-participant
+title: Insert a participant on a blank diagram
+---
+
+## User intent
+The user opens ZenUML to a blank diagram and wants to add one participant named `Alice` so they can start modelling.
+
+## Starting DSL
+```
+```
+
+## Target DSL
+```
+Alice
+```
+
+## Relevant assertion categories
+INS, FOC, EDT, KBD
+
+## Walkthrough hints (not prescriptive)
+- Blank canvas is the highest-stakes discoverability test — the skill should record how long it takes to find the insertion affordance.
+- Candidate insertion paths to try in order:
+  1. Click on the canvas background.
+  2. Look for a visible "+" or "Add participant" affordance.
+  3. Keyboard: try pressing Enter or `p` on an empty canvas.
+  4. Fall back to typing directly into the DSL editor pane.
+- The moment the user successfully names the new participant `Alice` is the scenario's end state.
+
+## Known issues to watch for (optional)
+- If the only path is direct DSL editing, that itself is a finding (violates INS-01).

package/.claude/skills/zenuml-ux-research/references/scenarios/rename-participant.md

@@ -0,0 +1,33 @@
+---
+id: rename-participant
+title: Rename a participant via keyboard
+---
+
+## User intent
+The user has a participant `A` on the canvas and wants to rename it to `Alice` without leaving the keyboard.
+
+## Starting DSL
+```
+A
+```
+
+## Target DSL
+```
+Alice
+```
+
+## Relevant assertion categories
+KBD, EDT, SEL, FOC
+
+## Walkthrough hints (not prescriptive)
+- This scenario is the canonical test of KBD-03 (Enter enters edit mode) and EDT-02 (caret at end of text).
+- Candidate paths to try in order:
+  1. Tab into the diagram widget, arrow-key to select `A`, press Enter, type `lice`, press Enter.
+  2. Click `A` to select, press Enter, retype.
+  3. Double-click `A` to enter edit mode.
+  4. Fall back to editing the DSL editor directly.
+- Watch specifically for: whether Enter does anything on the selected participant; whether the caret is placed at the end or the whole label is pre-selected; whether Escape cancels cleanly.
+
+## Known issues to watch for (optional)
+- If Enter does nothing on a selected participant, that is a KBD-03 violation at high severity.
+- If only mouse double-click works, that is a KBD-only violation (no mouse-free path).

package/.claude/skills/zenuml-ux-research/references/scenarios/undo-insert.md

@@ -0,0 +1,35 @@
+---
+id: undo-insert
+title: Undo a just-inserted message
+---
+
+## User intent
+The user has two participants `A` and `B`, inserts a message `A->B: hello`, then immediately presses Ctrl/Cmd+Z to undo. The expected result is that the message is removed and the state is back to just the two participants.
+
+## Starting DSL
+```
+A
+B
+```
+
+## Target DSL
+```
+A
+B
+```
+(after: insert `A->B: hello`, then undo)
+
+## Relevant assertion categories
+UND, FOC, SEL, KBD
+
+## Walkthrough hints (not prescriptive)
+- This scenario exercises the full insertion-then-undo round trip.
+- Steps:
+  1. Follow the `insert-message` scenario's walkthrough to get to the post-insert state.
+  2. Press Ctrl+Z (or Cmd+Z on macOS).
+  3. Observe: is the message removed? Is the DSL editor reverted? Is selection/focus restored to whatever it was before the insert?
+- Watch specifically for: undo granularity (one Ctrl+Z should undo the whole insert, not the individual keystrokes of the label edit) and focus restoration (FOC-03).
+
+## Known issues to watch for (optional)
+- If the undo leaves the label partially typed, UND-02 is violated.
+- If focus ends up on the document body after undo, FOC-03 is violated.

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`.