Repository navigation
feat(artifacts): line-anchored comments on code blocks via Pierre primitives - #8360
Conversation
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks. The rendered evidence covers both themes, the PR removes nothing, and the design uses Pierre's own line primitives instead of reaching into its shadow DOM. Notes
[DESIGN-REVIEWED] d5ba0a1 Description read[DESCRIPTION-READ] 88d02eb380ec6bc5859c99650234e613c6889b23aae34ccc70239941b51b4137 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Every item serves the frozen Goal (#8339). Nothing blocks. The narrow-viewport popover clamp rides along at almost no cost. What this change shipsInventory (10 items) — 9 justifiedIntent: let a reviewer comment on specific lines of a code block in a markdown artifact, through the same composer, popover and sidebar that prose comments use. This is an ADDITION; the description calls the current behaviour a silent failure.
[FIRST-PRINCIPLES-REVIEWED] d5ba0a1 Description read[DESCRIPTION-READ] a690c3ddebf2f5905489a55c939b5c7a265225185a01104a5122e738d54fc811 That sha256 names the PR description this verdict read. Recompute it with |
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS No primary control was misread. The blind reader correctly guessed what the gutter button, the chips, the composer and the popover each do, and would use all of them. Every new state appears in both themes. Notes
[UX-REVIEWED] d5ba0a1 Description read[DESCRIPTION-READ] 3696c0ea3e631fc48c4c0ddc736d310d1151fcf388ac4074b4a711188c156334 That sha256 names everything this verdict read: the PR description, plus the 13 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
6d3af43 to
a3eb1f0
Compare
|
span=0ca69ffbf75f Disposition: fixed — GPT finding "Resolved code threads bypass the anchor-visibility guard" (codeComments.ts:155).
|
a3eb1f0 to
a66861d
Compare
a66861d to
c813024
Compare
|
span=2f715e40b5e4 Finding: at a 320px viewport, activating a code annotation opened the fixed 360px CommentThreadPopover with the close/reply controls clipped off-screen. Fix applied at the root cause in the shared popover (the same component prose bubble clicks and sidebar activation open via the same |
b89daec to
a49d9ec
Compare
|
span=cc8af0798bf3
|
|
span=b668e4e38484
|
|
span=05a4ef9e3ab3
|
|
span=38567192db44
|
|
span=cc5a18751f0f
|
|
span=3d5162e3e77b
|
|
Answers to the two PASS asks on 84a19be: Design ( First Principles (repeated quote + same 32-char prefix): a prose anchor's prefix is 32 chars of RENDERED text ( |
iamwhatever
left a comment
There was a problem hiding this comment.
Approve at 84a19be.
Code comments ride Pierre's own line-selection, gutter and annotation props, so nothing reaches into the shadow DOM. Anchors store source offsets with raw-source context, and routing tries the stored offset first, then a prefix-gated search after edits (codeComments.ts#L149). Replies, resolved threads and prose anchors are never claimed. The feature stays inert outside artifact pages because the context defaults to null.
Every AI item on this head has a reply. The popover clamp rebuttal holds, because code chips open the shared popover. The Design and First Principles PASS asks are answered with reasoning that matches the code. The five deferred UX/Opus items (keyboard path, clearing the range, chip state label, range label, sidebar jump) are all listed by span in #22402, which has an owner and a due date. All checks are green, there are no conflicts and the base is main.
Note for whoever approves: iamwhatever force-pushed this head, so under the last-push rule a different maintainer's approval is needed.
— crew-pr-reviewer (r114)
Steward review — needs a rebase + a design decision before this can moveI picked this up from #8339 to verify and shepherd it. The implementation is sound and the crew reviewer approved it at State as of today
Why the conflict is non-trivial (not a mechanical rebase)After this branch's merge-base,
The two independently add a But the gap this PR fills is still open#21133 wired only the file-viewer ( The decision this needs (maintainer call, not a steward's)Now that
That's a product/architecture choice I shouldn't make unilaterally. What I'd ask of the author
Leaving the issue and PR open pending that rebase + the design decision. This is a UX change, so screenshots of the artifact-page code-comment flow are expected before any merge. |
|
@helenastafford heads-up: this PR blocks #22402, so we will merge current 🤖 AI-assisted comment 🤖 |
|
|
…mitives Code fences render in Pierre's shadow DOM, unreachable by the light-DOM selection capture and highlight overlay — so code comments now ride Pierre's own line-selection / gutter-utility / lineAnnotations APIs. Anchors encode source-content offsets (quote = exact source slice), routing is span + slice-equality against blocks derived from the same parseBlocks the renderer uses, and routed threads render as in-surface annotation chips. Inert outside artifact pages. Fixes #8339
|
@helenastafford heads-up: this branch was rebased onto main and force-pushed (with a lease), because PR Hygiene allows only 1 or 2 commits and refuses merge commits.
Before you push again, please run If you have unpushed local work, save it on another branch first ( |
A code thread's chip sits in Pierre's shadow DOM, where the thread popover's [data-mc-cid] lookup cannot reach it. The chip click passed a frozen rect, so the popover stayed put while the page scrolled, and a sidebar click opened it at the fallback spot without revealing the code. Chips and their code blocks now register as the thread's live anchor (codeAnchorElement). The popover looks the anchor up on every reposition, scrolls the owning block into view from the sidebar, and moves onto the chip once the block's highlight mounts it. Addresses GPT 6.1 finding F2 on bb14517 and the sidebar-jump item of #22402. Also put a range's chip under its selected empty last line: the line count skipped a trailing newline, so a range ending on an empty line showed its chip one line too high (GPT 6.1 finding on 818384e).
|
@helenastafford the head moved again: 818384e -> d5ba0a1. Your commit 91dc994 is unchanged. Only my commit on top changed: it now also fixes the GPT finding about a range that ends on an empty line (the chip sat one line too high), with a test. The same command applies before you push: |
|
Review-ready on d5ba0a1: all 104 checks pass, PR Readiness passes, and GitHub reports MERGEABLE. GPT 6.1, Opus 5.5, Design, First Principles and UX all pass on this head. It waits only on a maintainer review. F1 (prose/code anchor origin) is still open for @helenastafford to decide, per the earlier comment. |
|
HOLD at d5ba0a1 for decisions only people can make. The new commit reads sound. Code-thread chips and their blocks now register as live anchors, so the popover follows the chip on scroll and a sidebar click scrolls to the block (codeComments.ts#L303-L336). The What clears the hold:
No PR code was run locally. — crew-pr-reviewer (r118) |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Every review lane on the head is PASS or skipped, no findings; held by the triage cron on category, size or docs-path rules alone. Approved on the watch holder's request.
Problem / Motivation
Goal: A reviewer can leave an anchored comment on specific lines of a code block in a markdown artifact, through the same composer, thread popover and sidebar prose comments use.
Selecting code inside a fence and trying to comment silently does nothing. Code fences render inside Pierre's shadow DOM, so the page's light-DOM selection capture cannot read the selection, and the highlight overlay's TreeWalker never descends into the shadow root. Code is often exactly what a reviewer wants to discuss.
Why it matters
Review conversations about implementation details have no home today. Reviewers fall back to document-level comments that lose the link to the lines, or paste code into prose comments by hand.
Not a goal
ArtifactPanel); it only stops painting code threads on prose.quote/prefix/suffix; such a code thread no longer matches the source, so it shows in the sidebar without a chip. Prose anchors degrade the same way today. Accepted.kindfield. It would need aCommentAnchorschema change on the backend, the provider sync and the agent-facing tools, for a fact the stored raw-source prefix already decides. The two spaces and the rule for any future writer are recorded indocs/system-specs/modules/artifacts.md.What changed (motivation → approach → change)
Goal: comment on code with the same thread machinery prose uses.
Approach: ride Pierre's own primitives (
enableLineSelection/onLineSelected,renderGutterUtility,lineAnnotations/renderAnnotation) instead of piercing the shadow boundary. Line anchors are the natural unit for code.codeComments.ts(new): derives fence spans fromparseBlocks(the renderer's own block positions), builds code anchors, and routes stored anchors to fences. A code anchor stores SOURCE offsets, the source slice as quote, and raw-source prefix/suffix. Routing is offset-pinned first, then a prefix-gated drift search after an edit. Prose anchors carry no raw-source prefix, so they are never claimed. A chip sits under the range's last line.proseOverlayCommentsdrops code threads from a prose overlay.CodeBlock.tsx: drag line numbers to pick a range; the gutter button comments on it (or on the hovered line). Routed threads render as count chips, filled while unread or active; a chip click passes its box so the thread popover opens beside it. The button copies Pierre's ownz-index/offset so it is clickable and leaves the digits free for a drag, and keeps a picked range when pressed. Prose fences keep soft-wrap.EditableCodeBlock.tsx/MarkdownRenderer.tsx: passsourceStartLinetoCodeBlock, only on artifact pages.pierre/index.tsx/PierreImpl.tsx: pass annotation and gutter props through.ArtifactDetailPageBody.tsx:CodeCommentsScopemounts the context; a gutter click stages the anchor into the existing composer via its external-selection channel (useArtifactDetailPageComments.tsnow returnsstageIframeSelection). Code threads are routed on every markdown view, so a historical version never paints them on prose.ArtifactPanel.tsx: the side panel's overlay drops code threads too.SelectionToolbar.tsx: a press inside the container that itself opens an external selection (a touch tap on the gutter button) no longer closes the box it just opened.CommentThreadPopover.tsx: re-clicking a chip (shadow DOM, read viacomposedPath) no longer closes the popover and its unsent reply. The 360px card also clamps to narrow viewports (320px phones), prose threads included.docs/system-specs/modules/artifacts.md: records the two anchor offset spaces and that the rescan never rewrites offsets or context.website/src/i18n/locales/*.json:codeBlock.add_comment,codeBlock.comment_thread.website/capture/artifact-code-comments.*/website/scripts/capture-artifact-code-comments.mjs: real-browser capture of the page.Backwards compatibility
Compatible: every new prop is optional and the context defaults to null, so chat and preview code blocks render as before.
Removes nothing: no field, prop, key or path is removed or tightened.
Tests
codeComments.test.ts(25): fence spans, prose never claimed, replies and resolved threads skipped, drift after an edit, server-capped quote, EOF anchor, line mapping, round-trip, multi-line chip on the last line,proseOverlayComments.CodeBlock.comments.test.tsx(6): gutter button sends the hovered line or the range; chips pass their box on click; inert without context; prose fence keeps wrap.MarkdownRenderer.codeSourcepos.test.tsx(2):sourceStartLineonly for artifact markdown.ArtifactDetailPage.codeComments.test.tsx(3): gutter → page composer → source-offset post; stored anchor → chip → popover; prose anchor not claimed.CommentThreadPopover.dismiss.test.tsx(+1): a chip press inside a shadow root keeps the popover; another shadow press closes it.SelectionToolbar.composer.test.tsx(+1, fake timers): an open handed over during the same press survives; red on main's toolbar.ArtifactDetailPage.anchoredComments"text artifact" fails under shuffle on main too; not touched here.)ArtifactDetailPage.*,CodeBlock.*,SelectionToolbar.*,ArtifactPanel.*, all ofsrc/i18n.tsc -p tsconfig.app.jsonand eslint clean.Manual verification
node website/scripts/capture-artifact-code-comments.mjsmounts the realArtifactDetailPageand Pierre in headless Chromium, both themes, and asserts each step: read chip outlined and unread chip filled; a drag over line numbers 3..5 shows the gutter button; a real mouse click opens the composer; Enter posts an anchor whose quote is exactly source lines 3..5 and a third chip appears under line 5. All checks OK. This run found and fixed three bugs the jsdom tests could not see: the button sat under the line numbers, a press on it dropped the range, and a fast tap closed the composer. The last pair of shots (chip opens its thread) comes from one more step on the same harness that clicks a chip and asserts the popover shows that thread within 80px of the chip; it is not in the committed script yet.Screenshots / video
Dark theme. Read thread outlined (line 2), unread filled (line 6):
Lines 3..5 dragged; the gutter add-comment button on the range:
The button opens the page's comment composer:
Posted: a third chip under line 5, a third sidebar entry:
Clicking the line-6 chip opens its thread right beside it, with the reply box focused; the sidebar card lights up too:
Light theme, same steps:
Related Issues
Closes #8339
Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)