[PR] docs: design for the preview review overlay [magpie-site]

["potiuk (via GitHub)" <gi...@apache.org>]

potiuk opened a new pull request, #185:
URL: https://github.com/apache/magpie-site/pull/185

   Design only — no implementation. A reviewer marks a rectangle on a PR preview
   and gets a screenshot of it on the clipboard with the pull request's comment
   box open, ready to paste into and write in.
   
   ## This supersedes something that was never built
   
   #176's design has a "Reviewing in place" section describing a different
   mechanism: click an element, get a markdown block naming its source file and
   line. It was specified, deferred to a second plan, and never implemented — so
   the repo has been carrying a design for a feature that does not exist. This PR
   marks that section superseded and points forward, rather than leaving two
   contradictory designs for the same thing.
   
   The replacement is considerably smaller: **no `data-magpie-src`, no Vite
   plugin, no preview-only build mode.** Previews stay byte-identical to what
   production serves.
   
   ## What forces the shape
   
   Two facts did most of the design work.
   
   **GitHub has no public API for attaching an image to a comment.** The upload
   endpoint its web UI uses is private, and a prefilled URL can carry text but
   never a file. So "submit and the screenshot is attached" is unreachable without
   a server. The clipboard is the floor, and it costs exactly one paste.
   
   **A clipboard holds one thing, and GitHub's paste handler takes an image and
   discards accompanying text.** So the reviewer writes their prose *in GitHub*,
   not in the overlay. That removes the transfer problem entirely and means
   autocomplete, `@`-mentions, preview and draft recovery all work normally. The
   overlay's only job is to mark and capture.
   
   ## The flow
   
   Drag a rectangle → `html2canvas` rasterizes the viewport → the overlay
   composites the dimming, the outline, and a caption strip carrying the page URL,
   the region, and the build SHA → PNG to the clipboard → the PR opens → one ⌘V.
   
   The caption is burned into the image on purpose: it survives being dragged,
   quoted or downloaded, where a separate line of text would not.
   
   `window.__MAGPIE_PREVIEW__ = {repo, pr, sha}` is injected by the publisher
   alongside the script, so a pull request cannot forge which PR its own preview
   points at.
   
   ## Every failure is visible
   
   Clipboard refused → the PNG downloads with a toast saying to drag it in.
   Capture throws → the toast names the reason and the marked region survives.
   Popup blocked → the toast carries a clickable link.
   
   Two defects in the publishing pipeline were silent no-ops, and both were
   expensive to find. Nothing here degrades into quietly doing nothing.
   
   ## Vendoring
   
   `html2canvas` (MIT, ASF Category A) is vendored pinned in-tree rather than
   pulled from a CDN at publish time — a publish should not depend on a
   third-party host, and a file in-tree is auditable. `LICENSE` gains the entry in
   the implementing PR. It is injected into previews only and never reaches
   `magpie.apache.org`; a check asserts that.
   
   The alternative was the native `getDisplayMedia` API — no dependency, but a
   "share your screen" prompt in front of every screenshot, which kills the
   ergonomics the feature exists for.
   
   ## Open question
   
   Whether GitHub's comment box accepts a **programmatically-written** clipboard
   image on every browser that matters. Chrome and Edge are certain; Firefox
   depends on version; **Safari needs checking by hand.** The download fallback
   exists precisely because that answer may be "not everywhere", and it should be
   verified before the implementation is called done.
   
   🤖 Generated with [Claude Code](https://claude.com/claude-code)
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@magpie.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] docs: design for the preview review overlay [magpie-site]

["potiuk (via GitHub)" <gi...@apache.org>]

potiuk merged PR #185:
URL: https://github.com/apache/magpie-site/pull/185


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@magpie.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] docs: design for the preview review overlay [magpie-site]

["github-actions[bot] (via GitHub)" <gi...@apache.org>]

github-actions[bot] commented on PR #185:
URL: https://github.com/apache/magpie-site/pull/185#issuecomment-5712817919

   ### Preview this pull request
   
   A committer can publish a live preview of this PR by commenting `/show-preview` on its own line. It will appear at https://magpie-pr185.staged.apache.org/ and then track this PR's head commit until it closes.
   
   Staging takes a few minutes to pick up each push.
   
   <!-- magpie-preview-howto -->


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@magpie.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org