@zenuml/core 3.47.1 → 3.47.2

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

@@ -0,0 +1,120 @@
+---
+name: land-pr
+description: Merge a green PR and verify the npm release succeeds. Use when the user says "merge", "land", "land PR", "merge this", "ship to npm", "merge and release", or when a PR has passed CI and is ready to merge. This is a high-stakes action — merging to main triggers an automatic npm publish, so this skill verifies everything before and after merge.
+---
+
+# Land PR
+
+Merge a green PR to `main` and verify the npm release. In this repo, **merge = release** — every merge to main triggers automatic npm publish via GitHub Actions. Treat this as a production deployment, not a casual merge.
+
+## Preconditions
+
+Before merging, verify ALL of these:
+
+1. **All CI checks green** — no pending or failed checks
+2. **No pending reviews** — no requested changes outstanding
+3. **Branch is up to date** — no merge conflicts with main
+4. **PR is the right one** — confirm PR number with the user if ambiguous
+
+```bash
+gh pr view <PR_NUMBER> --json state,mergeable,statusCheckRollup,reviewDecision
+```
+
+If any precondition fails, report which one and stop. Do not attempt to fix — that's `babysit-pr`'s job.
+
+## Steps
+
+### 1. Verify readiness
+
+Run the precondition checks above. If anything is not green, stop and report.
+
+### 2. Decide merge strategy
+
+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.
+
+### 4. Wait for merge
+
+If auto-merge was armed, wait for it:
+
+```bash
+gh pr view <PR_NUMBER> --json state
+```
+
+Poll until state is `MERGED`. Timeout after 5 minutes — if not merged by then, report and stop.
+
+### 5. Monitor npm publish
+
+After merge, the `Build, Test, npm Publish, and Deploy` workflow runs on `main`. Watch it:
+
+```bash
+gh run list --repo mermaid-js/zenuml-core --branch main --limit 1 --json databaseId,status,conclusion
+```
+
+Wait for the run to complete:
+
+```bash
+gh run watch <RUN_ID> --repo mermaid-js/zenuml-core
+```
+
+### 6. Verify npm publish
+
+Check that the new version appeared on npm:
+
+```bash
+npm view @zenuml/core version
+```
+
+Compare with the version before merge. If it didn't bump, check the `npm-publish` job logs for errors.
+
+## Output
+
+Report one of:
+
+- **LANDED** — merged, published to npm as `@zenuml/core@<version>`
+- **MERGE BLOCKED** — which precondition failed
+- **PUBLISH FAILED** — merged but npm publish failed, with error details
+
+## On publish failure
+
+**Do NOT auto-rollback.** A failed npm publish after merge is a serious situation that needs human judgment. Report:
+
+1. The merge commit SHA
+2. The failing workflow run URL
+3. The npm-publish job error output
+4. Whether the version was partially published
+
+The user decides whether to hotfix, revert, or investigate.
+
+## Does NOT
+
+- Fix CI (use `/babysit-pr`)
+- Create PRs (use `/submit-branch`)
+- Run local tests (use `/validate-branch`)

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

@@ -0,0 +1,205 @@
+---
+name: propagate-core-release
+description: Propagate a published `@zenuml/core` release by opening or reusing per-repo downstream issues with explicit rollout instructions. Use when the user says "push core to downstreams", "update downstream projects", "propagate release", "open downstream issues", "file rollout issues", or wants the newly published zenuml/core version handed off across mermaid, mermaid live editor, web-sequence, the IntelliJ plugin, confluence-plugin-cloud, and diagramly.ai.
+---
+
+# Propagate Core Release
+
+Coordinate downstream consumers after `@zenuml/core` has already been published. This skill creates or reuses per-repo GitHub issues with clear implementation instructions for each downstream team. It does not edit downstream repos or open PRs on their behalf.
+
+## Scope
+
+This skill is for the post-publish propagation step only.
+
+It should:
+
+1. identify the published `@zenuml/core` version to roll out
+2. inspect each downstream repo's update conventions from [references/downstreams.md](references/downstreams.md)
+3. create or reuse one downstream issue per repo for that version
+4. include explicit repo-specific instructions in each issue body
+5. summarize which repos succeeded, failed, or were skipped
+
+It should not:
+
+- publish `@zenuml/core`
+- update downstream code directly
+- create downstream branches or PRs
+- auto-fix unrelated downstream test failures or implementation details
+
+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, repo slug assumptions, and repo-specific update commands that must be copied into the issue instructions.
+
+## Preconditions
+
+Before starting:
+
+- confirm the target `@zenuml/core` version is already published
+- confirm `gh auth status` is healthy for all target orgs and repos where issues will be filed
+- if the user did not specify the target version, discover the latest published one first
+
+If the published version is ambiguous, stop and ask.
+
+## 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: `issue-opened`, `issue-reused`, `already-tracked`, `blocked`, `failed`.
+- Prefer deterministic, reusable issue text.
+- Check for same-version issues before creating anything new.
+- Reuse an existing open issue when it already targets the same core version.
+- If the same version already has a closed issue, treat it as `already-tracked` and report it instead of opening a duplicate unless the user explicitly asks to reopen or replace it.
+
+## Issue Rules
+
+Each downstream repo should get at most one open issue per core version.
+
+Before creating a new issue, search that repo for issues matching the target version in the title or body. Prefer exact matches on `@zenuml/core v<version>`.
+
+Use a consistent title pattern:
+
+```text
+chore: roll out @zenuml/core v<version>
+```
+
+Use a clear body with actionable instructions:
+
+```markdown
+## Summary
+- `@zenuml/core` `v<version>` has been published
+- this repo needs to adopt that release
+
+## Required Work
+1. Run: `<update-command>`
+2. Run: `<lockfile-refresh-command>` and include the lockfile in the PR when applicable
+3. Run: `<verify-command>` when applicable
+4. Keep the diff scoped to the core upgrade and any required integration fix
+5. Open a downstream PR that links back to this issue
+
+## Repo-Specific Notes
+- <repo-specific note 1>
+- <repo-specific note 2>
+
+## Acceptance Criteria
+- repo is updated to `@zenuml/core` `v<version>` or the equivalent vendored build output
+- lockfile is refreshed when the repo uses one
+- verification command passes locally, or failure details are documented in the PR
+- no unrelated dependency or renderer migrations are mixed into the change
+```
+
+If an issue already exists for the same target version, do not create a duplicate. Reuse the open one, or report the closed one as already tracked.
+
+## Workflow
+
+### 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. Read the repo row carefully and extract the update command, verification command, and notes.
+2. Search for existing issues in that repo for the same core version, checking both open and closed issues.
+3. If an open match exists, reuse it and record the URL.
+4. If only a closed match exists, record it as `already-tracked` and do not create a duplicate unless the user explicitly asked for that.
+5. Otherwise create a new issue using the standard title and a repo-specific body.
+6. Make sure the issue body includes:
+   - the target core version
+   - the exact update command from the table
+   - the lockfile refresh command when the repo uses pnpm or yarn
+   - the exact verify command when one is defined
+   - the renderer and API caveats from the repo notes
+   - an explicit instruction to open a PR linked to the issue after the work is complete
+   - a version marker that makes future deduplication easy, such as `Core version: v<version>`
+
+### Step 3: Handle repo-specific blockers
+
+If a repo fails, capture exactly why:
+
+- missing issue creation permissions
+- existing issue search is ambiguous
+- existing closed issue should be reopened but the policy is unclear
+- dependency location unclear
+- package manager or package filter is unclear
+- repo notes are insufficient to write a safe instruction
+- issue creation failed
+
+Do not let one repo failure stop the rest of the batch.
+
+### Step 4: Summarize the rollout
+
+At the end, produce a per-repo summary with:
+
+- repo
+- issue URL or matched prior issue URL
+- final status
+- blocker if any
+
+## Repo Issue Guidance
+
+Each downstream has specific update and verification commands documented in [references/downstreams.md](references/downstreams.md). Follow the table exactly when drafting instructions. Do not guess package managers, package filters, or update commands.
+
+For each repo:
+
+1. Include the **Update Command** from the table verbatim
+2. Include the lockfile refresh step:
+   - `pnpm install` for pnpm repos
+   - `yarn install` for yarn repos
+3. Include the **Verify Command** from the table verbatim when one exists
+4. Tell the downstream team to keep the change scoped to the core upgrade and any required integration fix
+5. Tell the downstream team to open a PR after verification and link it back to the issue
+
+Special handling for renderer API changes:
+
+- `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 downstream task description that updates the repo safely:
+
+- package dependency bumps
+- lockfile refreshes
+- vendored asset refreshes only when the repo actually vendors core output, such as `jetbrains-zenuml`
+
+Do not ask downstream teams to opportunistically clean up unrelated code while doing the upgrade.
+
+If a downstream repo needs custom update logic that is not obvious from the table or its notes, stop on that repo and report the ambiguity instead of inventing instructions.
+
+## Safety
+
+- Never update downstream repos directly from this skill.
+- Never merge downstream PRs from this skill.
+- Never batch all downstream repos into one issue.
+- Never file duplicate issues for the same repo and core version.
+- Never hide per-repo failures behind a single "batch failed" message.
+- Never ask downstream teams to 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>`: issue opened | issue reused | already tracked | failed
+  issue: <url or none>
+  notes: <short reason or blocker>
+```

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

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

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

@@ -0,0 +1,42 @@
+# Downstream Repos
+
+Canonical downstream targets for filing rollout issues after 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/codemirror-extensions` | `~/workspaces/zenuml/codemirror-extensions` | pnpm | `pnpm update @zenuml/core` | `pnpm build` | CodeMirror language extensions for ZenUML DSL. HTML-renderer consumer. |
+| `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. |
+
+## Issue Authoring Guidance
+
+When writing a downstream issue for an npm consumer, explicitly include the lockfile refresh step:
+
+- **pnpm**: `pnpm install` (updates `pnpm-lock.yaml`)
+- **yarn**: `yarn install` (updates `yarn.lock`)
+
+Tell the downstream team to include the updated lockfile in the PR. A PR without an updated lockfile will usually fail CI.
+
+## Local Checkout Usage
+
+Local checkouts are optional for this skill. Use them only if you need extra context to clarify the issue body safely. Do not clone repos just to file the issue.
+
+If you do need a checkout and the local path does not exist:
+
+```bash
+gh repo clone <repo-slug> <local-path>
+```
+
+## General Rules
+
+- Each repo gets its own rollout issue.
+- Reuse an existing open issue when it already targets 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/.agents/skills/ship-branch/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: ship-branch
+description: Ship the current branch from local validation through to npm release. Orchestrates validate-branch, submit-branch, babysit-pr, and land-pr in sequence. Use when the user says "ship", "ship it", "ship this branch", "ship to production", "release this", "get this to npm", or wants to go from local branch to published npm package in one command. Stops at the first failure with a clear report.
+---
+
+# Ship Branch
+
+Orchestrate the full path from local branch to npm release. This skill composes four sub-skills in sequence, stopping at the first failure.
+
+## Flow
+
+```
+rebase on origin/main → CONFLICT → stop, report
+     | CLEAN
+validate-branch → FAIL → stop, report
+     | PASS
+submit-branch → FAIL → stop, report
+     | PR ready
+babysit-pr → EXHAUSTED → stop, "CI blocked"
+     | GREEN
+land-pr → BLOCKED → stop, report
+     | MERGED
+land-pr → PUBLISH FAIL → alert, stop
+     | PUBLISHED
+     done
+```
+
+## 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.
+
+### Step 2: Submit as PR
+
+Invoke `/submit-branch`. If it reports FAILED, stop and show what went wrong (dirty worktree, push conflict, etc.).
+
+On success, note the PR number and URL.
+
+### Step 3: Get CI green
+
+Invoke `/babysit-pr` with the PR number from Step 2. If it exhausts all 3 retry attempts, stop and report "CI blocked" with the babysit report.
+
+On success, the PR is green and ready to merge.
+
+### Step 4: Land and verify release
+
+Merging to main triggers an npm publish — this is irreversible. To prevent the orchestrator from skipping the land-pr skill's merge strategy logic (which has happened before), **spawn an Agent** for this step:
+
+```
+Spawn an Agent with this prompt:
+"Use the Skill tool to invoke the land-pr skill, then follow it to land PR #<PR_NUMBER>
+on mermaid-js/zenuml-core. Follow every step including the merge strategy evaluation.
+Report back the merge SHA and npm version, or the reason it was blocked."
+```
+
+Replace `<PR_NUMBER>` with the actual PR number from Step 2.
+
+Do NOT run `gh pr merge` directly from the main conversation — the land-pr skill contains merge strategy decision logic that must be evaluated by the Agent.
+
+If merge succeeds but npm publish fails, alert immediately with the failure details. Do NOT auto-rollback.
+
+On full success, report the new npm version.
+
+## Rules
+
+- **Each step is a hard boundary.** No step reaches back to retry a previous step.
+- **No auto-rollback.** Stop and report on any failure. The developer decides next steps.
+- **Only this skill calls babysit-pr.** Sub-skills never cross-call each other.
+- **Confirm before merge.** Since merge = npm release, pause and confirm with the user before Step 4 unless they explicitly said "ship it" (indicating full automation is intended).
+
+## Output
+
+Final report:
+
+```
+## Ship Report: <branch-name>
+- Validation: PASS
+- PR: #<number> (<url>)
+- CI: GREEN (attempt <N>)
+- Merge: <SQUASHED|MERGED> into main (<sha>)
+- npm: @zenuml/core@<version> published
+```
+
+Or on failure:
+
+```
+## Ship Report: <branch-name>
+- Validation: PASS
+- PR: #<number>
+- CI: BLOCKED after 3 attempts
+- Stopped at: babysit-pr
+- Details: <failure summary>
+```

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

@@ -0,0 +1,76 @@
+---
+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/.agents/skills/validate-branch/SKILL.md

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