Add viewer comments for private projects

[koomen]

What

Authenticated viewers of a private, comments-enabled project can leave Google-Docs-style comments on any page: add (pinned to a click point), resolve/reopen, edit, and delete. Anyone with read access may comment and resolve; only the author or a writer+ may edit or delete. Enabled per project with scratchwork publish --comments; comments on a public project fail the deploy on both client and server, and flipping the toggle requires admin (like public/private).

Live demo (private, owner koomen@gmail.com): https://pages.sndbx.sh/comments-demo/ — sndbx.sh is already running this branch.

Design

• Anchoring: each comment stores a fallback chain of {selector, x, y} candidates — the clicked element, then its ancestors, ending body-relative. Pins render at the first selector that still matches, so republished/dynamic pages degrade gracefully instead of losing comments (verified live: a republish that shifted the layout kept the pin on its element).
• API on the content origin: the app-origin JSON API is unreachable from content pages (SameSite=Lax + no CORS, by design), so the comments API is a content-origin route family at /:project/__scratchwork/comments (prefix now reserved at publish time), authenticated by the existing path-scoped project-access cookie — which always exists because comment-enabled projects are always private. Same origin/Referer guards as private-content serving, applied before auth; own typed policy registry + matrix test in the spirit of invariant 4.
• Storage: a new comments PrimitiveDb namespace keyed {project}/{page}/{creation-ordered id} — no storage-contract changes, so all three deploy targets work unchanged. Comments are purged before a deleted project's name is released.
• UI: a self-contained vanilla-JS widget (shadow DOM) shipped as a generated string module (renderer-style) and injected via the existing htmlTransforms hook into HTML responses of private comments-enabled projects only.
• Contract: commentsEnabled added to the shared publish request/response and ProjectInfo (optional fields, older CLIs unaffected).

Testing

• 28 new server tests, including a policy matrix over the comments route registry (credential × role × route, origin/Referer guards, existence masking, body/anchor validation caps, purge-on-delete, publish validation).
• CLI flag tests (--comments/--no-comments, saved-config reuse, comments+public rejection before upload).
• e2e comments scenario in the shared publish-loop suite, run on all three lanes (local-dev, miniflare Cloudflare, LocalStack AWS).
• Real-Chromium browser-security test: widget boots for an authorized viewer, persisted pin after reload, attacker project blocked by the Referer guard, cross-origin form POST rejected by the origin gate.
• bun run ci fully green; /check-invariants pass done before commit (one finding — widget duplicating server page-normalization — fixed by making the server solely responsible for canonicalization).

Notes for review

• Resolve semantics were unspecified: went with the Google Docs convention (any reader can resolve/reopen, resolvedBy recorded); edit/delete stays author-or-writer+ as specified.
• Trust-model note documented in comments-routes.ts: a project's own published JS can act as its viewer within that project's comment space only — inherent to same-origin cookie auth, scoped to a project whose author the viewer already trusts.

🤖 Generated with Claude Code