Message-anchored commenting UI MVP (do not merge/deploy)

[simple-agent-manager]

Constituent PR: message-anchored commenting UI MVP

Do not merge this PR directly. Do not deploy this branch to staging.

This is the production web UI constituent PR for idea 01M0JQB842XSJ3W172DYPB37HN. The parent integration PR will combine this with the sibling backend/server-contract task 01M0K4EP5SND5CPK2N6GYS4449.

Scope

Included:

• Message-anchored comments on the real project chat surface.
• Native text selection support for agent/user message text, including desktop pointer selection and mobile/coarse-pointer long-press/selection-handle behavior via debounced selectionchange.
• Create-thread composer with selected quote, body, and explicit note vs send_to_agent.
• Thread body/replies, resolve/reopen/send status, count marker and accent state on commented messages.
• Desktop comment rail at >=1024px driven by fetched comment data, not mounted Virtuoso rows.
• Mobile inline expansion with touch-friendly controls and no permanent gutter clutter.
• Optimistic updates and realtime reconciliation hooks.
• Generic packages/ui primitives: Avatar, Textarea, anchored Popover.

Excluded by design:

• Production file/markdown comments.
• Fuzzy file re-anchoring.
• Mentions, reactions, global inboxes.
• Unrelated chat redesign, staging deployment, or merge.

Agent Preflight (Required)

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

N/A: no external API or third-party integration documentation was required; this constituent PR implements repo-local UI behavior against the sibling SAM backend contract.

Codebase Impact Analysis

Affected paths are apps/web/src/components/project-message-view/, apps/web/src/lib/api/comments.ts, apps/web/src/lib/query-options/comments.ts, packages/ui/src/components/, specs/035-message-comments/contracts/message-comment-api.md, and focused web/UI tests under apps/web/tests/ plus packages/ui/tests/.

Documentation & Specs

Updated specs/035-message-comments/contracts/message-comment-api.md for the UI/backend message-comment REST and realtime contract, and tracked implementation evidence in tasks/active/2026-08-21-message-anchored-commenting-ui.md.

Constitution & Risk Check

Checked Principle XI/no hardcoded values and kept server-owned write limits out of the UI; main risks were cross-component UI/API contract drift, optimistic reconciliation correctness, mobile selection ergonomics, accessibility, and no-staging/do-not-merge constituent-PR constraints.

Assumed server contract for backend integrator

Documented in specs/035-message-comments/contracts/message-comment-api.md.

Types:

• MessageCommentStatus = 'open' | 'sent' | 'resolved'
• MessageCommentAction = 'note' | 'send_to_agent'
• MessageCommentAnchor = { kind: 'message'; messageId: string; quote?: string }
• Thread/reply objects include stable id, optional clientId for optimistic reconciliation, author, createdAt, updatedAt, status, body, anchor, and replies.

REST:

• GET /api/projects/:projectId/sessions/:sessionId/comments?anchorKind=message -> { comments }
• POST /api/projects/:projectId/sessions/:sessionId/comments
  • body { clientId, anchor: { kind: 'message', messageId, quote? }, body, action }
  • response { comment }
• POST /api/projects/:projectId/sessions/:sessionId/comments/:commentId/replies
  • body { clientId, body, action }
  • response { comment }
• POST /api/projects/:projectId/sessions/:sessionId/comments/:commentId/resolve -> { comment }
• POST /api/projects/:projectId/sessions/:sessionId/comments/:commentId/reopen -> { comment }
• POST /api/projects/:projectId/sessions/:sessionId/comments/:commentId/send
  • body { body?: string }
  • response { comment }

Realtime:

• comment.thread.created
• comment.thread.updated
• comment.reply.created
• payload { projectId, sessionId, comment, replyId? }

Client behavior:

• Upsert by server id or matching optimistic clientId.
• send_to_agent creates/updates status to sent; note keeps status open.
• resolved threads remain represented.
• Server owns storage/write limits and validation; UI quote caps are display/layout guards, not backend write boundaries.

Tests and evidence

• Focused web unit/component tests:
  • pnpm --filter @simple-agent-manager/web test -- tests/unit/api/comments.test.ts tests/unit/components/message-comments.test.tsx tests/unit/components/project-message-view.test.tsx tests/unit/components/chat/project-message-view-resume.test.tsx
  • 94 tests passed.
• UI primitive tests:
  • pnpm --filter @simple-agent-manager/ui test
  • 12 files / 104 tests passed.
• Playwright audit:
  • pnpm --filter @simple-agent-manager/web exec playwright test tests/playwright/message-comments-audit.spec.ts --project='Desktop (1280x800)'
  • 3 tests passed, covering desktop 1280x800 and mobile 375x667.
• Root gates:
  • pnpm test passed before the final import-sort-only amend: 21/21 turbo tasks; web 284 files / 3410 tests; API 583 files / 7880 tests.
  • After the final amend, focused web tests passed and root pnpm build, pnpm lint, and pnpm typecheck passed at final SHA.
  • Root lint has only pre-existing warnings in packages/acp-client and unrelated web files.
  • Root typecheck includes the existing apps/www Astro template baseline report.

Screenshot evidence:

• .codex/tmp/playwright-screenshots/message-comments-desktop-thread-flow-1280x800.png
• .codex/tmp/playwright-screenshots/message-comments-desktop-error-state-1280x800.png
• .codex/tmp/playwright-screenshots/message-comments-desktop-empty-state-1280x800.png
• .codex/tmp/playwright-screenshots/message-comments-mobile-inline-send-375x667.png

Specialist Review Evidence

Reviewer	Status	Outcome
ui-ux-specialist	PASS	Screenshot-backed desktop/mobile audits verify rail, inline mobile threads, loading/error/empty states, touch controls, and overflow safety.
test-engineer	PASS	Tests cover API/query transforms, optimistic/realtime reconciliation, actual selection, create/reply/send/resolve/reopen, virtualization/offscreen comments, focus/accessibility paths, and UI primitives.
Accessibility review	PASS	MVP caveat: desktop floating selection chip is a transient pointer affordance, not a trapped modal. Keyboard users have the row Comment action path and labelled composer/thread controls.
constitution-validator	PASS	No hardcoded server write-boundary limits; excluded features stayed out of scope.
doc-sync-validator	PASS	In-repo contract matches typed API/query/WebSocket assumptions.
task-completion-validator	PASS	Backend persistence is intentionally delegated to sibling task 01M0K4EP5SND5CPK2N6GYS4449; this PR provides the documented UI-side contract and stateful API-boundary tests.

Notes

• Remediation started from branch head d323554b1e0c52d752944829f52e0edde0c2df9f.
• apps/web/src/components/project-message-view/index.tsx was reduced from 966 to 786 lines by extracting the comment row/rail wiring and session helper utilities, keeping it below the mandatory 800-line limit.
• No staging deployment was performed.

[codspeed-hq]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing sam/build-production-web-ui-z72qrz (bc252a9) with main (221c48c)}

[sonarqubecloud]

Quality Gate passed

Issues
26 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
1.0% Duplication on New Code

See analysis details on SonarQube Cloud