verify-markdown-viewer

name	verify-markdown-viewer
description	Drive Markdown Viewer Pro (Vite + vanilla JS) like a user and capture proof. Use when verifying UI changes, markdown rendering, themes, view modes, or any feature in this repo's web app.

Verify Markdown Viewer Pro

Project-local verification for the primary surface: web UI at http://127.0.0.1:3000/markdown-viewer-app/. Secondary surfaces: Vitest (npm test), ESLint (npm run lint) — use those for unit checks; this skill drives the real browser path.

Read .cursor/skills/verify-markdown-viewer/features/README.md before driving. One feature file per user-facing capability.

Launch

Start an isolated dev instance (never reuse the user's personal dev server):

export RUN_ID="verify-$(date +%s)"
bash .cursor/skills/verify-markdown-viewer/scripts/control-viewer.sh launch

Ready when control-viewer.sh doctor prints HTTP: OK and TITLE: OK (Vite listening on port 3000).

Teardown after every run (success or failure):

bash .cursor/skills/verify-markdown-viewer/scripts/control-viewer.sh cleanup

Doctor

Run first whenever anything looks off:

export RUN_ID=<same id used for launch>
bash .cursor/skills/verify-markdown-viewer/scripts/control-viewer.sh doctor

Requires: HTTP 200 at the app URL, page contains Markdown Viewer Pro, vite process on port 3000 owned by this run's tmux session mv-$RUN_ID.

Drive

Harness: agent-browser (repo devDependency). Load core patterns before guessing commands:

npx agent-browser skills get core

Typical session:

URL=$(RUN_ID=$RUN_ID bash .cursor/skills/verify-markdown-viewer/scripts/control-viewer.sh url)
npx agent-browser open "$URL"
npx agent-browser wait "#markdown-editor"
npx agent-browser snapshot --json   # accessibility tree with @refs
npx agent-browser fill "#markdown-editor" "# Hello\n\n**bold** text"
npx agent-browser wait "h1"         # preview rendered heading
npx agent-browser screenshot /opt/cursor/artifacts/verify-preview.png

Stable handles (prefer over coordinates):

Element	Handle
Editor	#markdown-editor or [aria-label="Markdown editor input"]
Preview pane	#markdown-preview
Split view	#split-view-btn / [aria-label="Split View"]
Preview only	#preview-only-btn
Editor only	#editor-only-btn
Theme picker	#theme-picker-trigger / [aria-label="Select theme"]
Zen mode	#zen-mode-btn / [aria-label="Enter Distraction Free Mode"]

Do not drive a dev server you did not start with control-viewer.sh launch for this RUN_ID.

Evidence

Proof artifacts go to /opt/cursor/artifacts/ (survive cleanup).

Standards:

• Exercise the real user path (type in editor, click toolbar) — not internal setters or test-only hooks.
• Capture the action and resulting DOM state, not only a final screenshot.
• For markdown rendering: show editor source and preview output (screenshot + ARIA snapshot or innerHTML check via snapshot).
• Record feature ID and entry point in artifact filenames, e.g. verify-markdown-preview-split.png.
• Side effects: localStorage auto-save is acceptable; do not mutate git state.

Minimum proof set per feature: one screenshot + one accessibility snapshot or structured assertion output.

Cleanup

Always run after verification (keeps evidence, removes instances):

bash .cursor/skills/verify-markdown-viewer/scripts/control-viewer.sh cleanup

Confirm evidence still exists:

ls -la /opt/cursor/artifacts/verify-*

Never pkill -f vite; kill only via control-viewer.sh cleanup (tmux session mv-$RUN_ID).

Helpers

Script	Purpose
scripts/control-viewer.sh launch	Start vite on port 3000 in isolated tmux session
scripts/control-viewer.sh doctor	Read-only health check
scripts/control-viewer.sh cleanup	Stop instance and scratch state
scripts/control-viewer.sh url	Print app URL

All helpers require RUN_ID in the environment for isolation.

Maintenance

Re-run /create-verification-skill or /maintain-verification-skill when routes, selectors, or ports change.