[seanpk]

Implements the markupit specification clean-room, test-first. Turns the design-phase repo into a working tool: npx markupit ./dir (or a single .html), open the printed ?markupit URL, click any element to comment / edit / remove, then copy a structured markdown brief for an agent.

Scope

Covered (all MUSTs for local modes):

• CLI + server — local directory and single-file serving, no-store headers, reserved /__markupit__/ namespace, port fallback, clean shutdown, idempotent overlay injection, activation gating via ?markupit.
• Overlay — vanilla-JS, Shadow-DOM isolated. Stable element IDs with cascade re-anchoring, selection, comment/edit/remove (all reversible), the queue/overview, localStorage persistence, and a pure markdown export.
• Design — calm chrome, anchored popover that grows from the click, distinct per-action treatments, prefers-reduced-motion, keyboard fluency.

Deferred to a follow-up (stubbed with a clear notice):

• Proxy URL mode (SRC-3/4/5/7) — reviewing a live http(s) page.

Constraints held

• Zero runtime dependencies — Node built-ins only; CI asserts dependencies stays empty.
• Pure ESM, no build step to use, single npm package.
• Clean-room from docs/.

Tests

• 44 unit (node:test + linkedom) · 13 server integration · 16 Playwright.
• npm run test:ids gates that every MUST requirement has an [ID]-tagged assertion (or a recorded exemption).
• CI: Node 20/22/24 matrix + a separate Playwright job (chromium/firefox/webkit).

Commit trail

Each commit is one milestone, leaves the suite green, and cites the requirement IDs it satisfies — git log reads as a spec-coverage walk.

Notes

• 0.1 uses a system-font stack rather than a bundled brand font (avoids shipping a binary / network fetch); bundling DM Sans is a follow-up.
• npm publish is wired (prepublishOnly runs lint + tests; tarball verified to ship only bin/, src/, assets/overlay/, README, LICENSE) but not yet published — markupit is available on npm.

🤖 Generated with Claude Code

[seanpk]

UX feedback — comment/edit panel behaviour

Noted while reviewing real content with the overlay:

• The comment and edit input panels feel too small — the text area especially needs more vertical room to write a proper note without constant scrolling.
• Clicking outside the panel dismisses it and loses the draft. This is surprising and frustrating; panels should stay open until explicitly confirmed or cancelled.
• It would be worth making the panels draggable/movable — when you've selected an element near the bottom of the viewport the panel can cover the very thing you're annotating.

[seanpk]

Follow-up: review-note history (instead of destructive clear)

Feedback from dogfooding — the system is working well. Two related asks about the review notes, now scoped into a concrete plan.

1. Keep notes as history instead of discarding on clear

Today doReset() (assets/overlay/app.js:207) is fully destructive: model.resetAll empties annotations and persistence.clear() drops the storage key. Instead, archive on clear:

• Extend the model state with a history array (core/model.js). On clear, push the current live annotations into history as a timestamped batch rather than dropping them, then empty the live set.
• liveCount (model.js:123) already counts only live annotations, so history won't inflate counts or re-apply page treatments.
• load() defaults history = [] for states saved before this change (backward-compat guard at persistence.js:14).

History entries are read-only data — the page treatments (edit/remove) are still reverted on clear, and anchors may go stale on later loads, so we don't try to re-apply them.

2. Confirmation + no undo

• Replace the native confirm() (app.js:209) with an in-overlay styled confirmation rendered in our shadow DOM — no native browser dialog. We want beautiful, consistent UX. It stays as the safety net before a destructive clear.
• No undo support in this pass — explicitly out of scope.

History UI / export

• Render history as timestamped items.
• Support individual deletion of a history item and a total clear of all history.
• Render the history comments into a single block of text that can be copied/pasted out, with a copy button on the entry (reuses the clipboard path from doExport).

Out of scope for now: undo, re-applying archived treatments, history size caps.

[seanpk]

Implemented ✅

Both pieces of feedback are in, on build/v0.1, as two commits that follow the same story:

• 919cfd3 — retain cleared review notes as history. Reset is now non-destructive: each clear is archived as a timestamped history batch (one entry per clear) that persists across reloads. The queue panel grows a collapsible History section to copy (full notes brief, via the existing markdown export), delete, or clear past notes. Model gains archiveAndReset / deleteHistoryBatch / clearHistory / historyBatches / summarizeKinds; load() is back-compat for pre-history states.
• be6a88a — styled in-overlay confirmation. The native window.confirm is replaced with a promise-based dialog rendered in the shadow DOM (danger variant, Esc / backdrop to cancel, focus on the primary button), used for both Reset and Clear history.

Per the discussion: no undo this pass; history entries are individually deletable with a total clear; each entry copies out as a single text block via its Copy button.

Requirements

ANN-8 is now non-destructive; added QUE-6 (history), QUE-7 (copy/delete/clear), and UX-11 (no native dialogs).

Verification

• npm run lint clean; npm test (48 unit + 13 server) green; MUST-coverage gate passes.
• npx playwright test — 21/21, including 4 new history specs: archive-on-reset via the styled (non-native) confirm, cancel leaves notes intact, persistence across reload, per-entry copy of the full brief, and individual delete + total clear.

[seanpk]

Round 2 — review-note UX refinements ✅

Pushed to build/v0.1 as three commits:

• a252c9f — confirmation & history UX. Reset dialog now reads "Clear all annotations for this page / and reset for a new review?" with a primary Reset button and a third Copy notes and Clear action (copies the brief, then clears). Deleting a history entry now asks for confirmation and uses a trash-can icon instead of ×. createConfirm was generalized to resolve 'confirm' | 'cancel' | 'extra' with multi-line messages.
• 97cc3b1 — popover focus + composing. The selected-element outline gains a white contrast ring so it stays legible on dark page backgrounds (addresses the missing highlight in screenshot Proxy URL mode: review a live http(s) page #2) and persists in comment/edit mode. While composing a comment/edit, a stray click on the page no longer dismisses the popover or loses your text.
• d626b95 — roadmap. Recorded the bigger ideas for a future release (below).

Mapped to: #1 trash icon ✓, #2 delete confirm ✓, #3 reset wording + "Reset" label ✓, #4 "Copy notes and Clear" ✓, #5 focus highlight ✓, #6 no-dismiss while composing ✓.

Verification

npm run lint clean · npm test 48 unit + 13 server, MUST-gate passes · npx playwright test 25/25 (added: copy-and-clear, delete-confirm + cancel, no-dismiss-while-composing, focus-highlight). New requirements: ANN-8 (copy-and-clear), ANN-9 (focus highlight), ANN-10 (no dismiss while composing).

Backlog (recorded in README roadmap)

• Per-element comment-count badges (QUE-5) #7 Draggable popover — move the box aside to read surrounding context while composing.
• Annotate interactive content — trigger the page's own actions (menus, accordions) and annotate elements that only appear after a JS-driven interaction, rather than intercepting every click.
• Multi-page reviews — follow links and collect annotations across pages into one brief.