Skip to content

fix(file-viewer): underline comments on text inside fenced code blocks - #23155

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/21837-code-block-comment-mark
Oct 22, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/21837-code-block-comment-mark

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A comment on text inside a fenced code block in the markdown preview is underlined at that text and shows its words on hover, like a prose comment.

Since #21133 you can select text in a code block and comment on it. The comment is saved, but the preview shows no mark at that text. The underline pass skips every code-block comment (if (!comment.anchor || comment.inCode) continue in website/src/components/MarkdownPanel.tsx).

Why it matters

A reviewer who comments on a command in a doc cannot see where the comment sits. The note is in the sidebar but nothing in the document points to it, and hover shows nothing.

Not a goal

  • Changing how prose comments are found, painted or hit.
  • Marks for a selection made on a block's plain copy (before it is highlighted). That selection is saved as a prose comment today, unchanged here.
  • Comments in the diff view, which opens no comment box.

What changed (motivation → approach → change)

A code-block comment is now underlined in its own block, and the pointer on it shows the comment.

Part Before After
Saving a code comment quote and line only adds codePosition: which block, line and column
Underline pass skips code comments places them inside the block's shadow root
Same words elsewhere n/a the stored block wins; prose is never searched
Block redrawn (plain copy swapped for highlighted) n/a mark is placed again on the new text
Hover caret test only code marks are also hit by their drawn boxes
Drag ending on a code mark n/a keeps its selection; a plain click still jumps to the comment

codePosition is the number codePassagePosition (from #21133) already builds for the selection toolbar. codeQuoteRange in website/src/utils/pierreShadow.ts reads it back. If the stored column is past the end of its row, or the text there no longer starts with the quote, or the comment was saved before this change, the quote is marked only when it occurs once across all code blocks. A block that shows only its plain copy gets no mark until the swap; watchText reports the swap and the pass runs again.

Paint uses the same mc-comment CSS highlight, so token colours, the copy button and selection stay as they were.

Backwards compatibility

Compatible: codePosition is an optional new field. Code comments saved before it are still placed when their words occur once in the code.

Removes nothing: the change only adds marks where none were drawn; prose comments take the same path as before.

Tests

  • MarkdownPanelCodeBlock.test.tsx: a code comment is painted inside the code block's shadow root, not on the same words in the prose; with two blocks holding the same words, the commented block is marked; an older comment with no position is marked; the mark comes back after the block is redrawn; hover over the mark shows the comment; a click on the mark with text selected keeps the selection, and one without clears it; a prose comment is still painted in the prose.
  • pierreShadow.test.ts: codeQuoteRange places by position, across two lines, waits while a block is plain or parked, never searches prose, refuses an ambiguous quote, falls back when the text at the position changed, and ignores a column past the end of a shortened row.

The five new panel tests fail on origin/main (the prose one passes there, by design). Removing the watchText call fails only the redraw test; dropping the stored position fails only the two-blocks test.

Manual verification

Ran website/scripts/capture-21837-code-block-comment-mark.mjs against the built SPA with fixture APIs in headless Chromium. It asserts both marks are painted in their places and the tooltip text, then writes the two frames below.

Screenshots / video

The prose comment and the code comment, each underlined in place. The same words in the prose and in the first block are not marked.

Code comment marked in the second block

Pointer on the code mark: the comment text shows.

Hover over the code mark shows the comment

Related Issues

Closes #21837

Pattern harvest

Not generalizable: the skip was a deliberate scope cut in #21133, not a recurring code shape.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners October 22, 2026 18:13
@iamwhatever
iamwhatever requested a review from buluoray October 22, 2026 18:13
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 22, 2026
@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 551251374161cea30db0b1a3f9e2a56b5adb99a1 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. The fix removes a deliberate skip and places the mark from data the selection toolbar already builds. The new field is optional, and when no position is stored it falls back to marking a quote that occurs once.

Notes

  • codePosition saves the internal packing that codePassagePosition uses (block index × 1e12 + line × 1e5 + column) into mc-comment-drafts. If that packing or the way blocks are counted changes later, every saved position will quietly point at the wrong place. The startsWith check means the result is a missing mark rather than a wrong one. Still, add a comment in pierreShadow.ts saying this packing is now a persisted format.

[DESIGN-REVIEWED] 5512513

Description read

[DESCRIPTION-READ] 94e1fa5b56e2f5448c72303d7121466cf3ed58b919db18ddb560e5a433d723a8

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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 551251374161cea30db0b1a3f9e2a56b5adb99a1 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. Each item comes from the issue (#21837), has a test that fails on base, or follows from the new code-mark hit test. The new code reuses the existing helpers boundary, textNodesOf, watchText and codePassagePosition.

What this change ships

Inventory (6 items) — 6 justified

Intent: a reviewer can see where a comment made on text inside a fenced code block sits in the markdown preview, and read it on hover. This is a FIX (closes #21837).

  1. A comment on text in a code block is now underlined in its own block, not on the same words in the prose — justified
  2. A code comment now saves an optional codePosition (block, line, column) with it — justified
  3. Code comments saved without a position are still underlined when their words occur once across the code blocks — justified
  4. The underline comes back when a block's plain copy is swapped for the highlighted one — justified
  5. The pointer on a code mark shows the comment, found by the boxes the text is drawn in — justified
  6. A drag that ends on a code mark keeps its selection; a plain click still jumps to the comment — justified

[FIRST-PRINCIPLES-REVIEWED] 5512513

Description read

[DESCRIPTION-READ] ac32bc917581c643b29a685a49b5fc7969d53d7c7b9ca94842e92c8c70ef9bba

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of 551251374161cea30db0b1a3f9e2a56b5adb99a1 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing blocks: both screenshots show the new code-block underline and its hover note, and the blind reader read them correctly ("a comment or question someone attached to that marked text").

Notes

  • In the shot-02 fixture, the comment asks "Is --force needed here?" but the mark sits on "mycli rm NAME", so the reader concluded "the mark seems to sit on the wrong words". Make the fixture's anchor match its question so the evidence doesn't look like the mark landed in the wrong place.

[UX-REVIEWED] 5512513

Description read

[DESCRIPTION-READ] c65c81fd5f64da07ff8a1277e700484f25961cee4db35b6a2d9c756d222daca3

That sha256 names everything this verdict read: the PR description, plus the 5 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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 551251374161cea30db0b1a3f9e2a56b5adb99a1 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 5512513

Verdict parsed from the review's SHA-scoped output markers for commit 551251374161cea30db0b1a3f9e2a56b5adb99a1.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 551251374161cea30db0b1a3f9e2a56b5adb99a1: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 551251374161cea30db0b1a3f9e2a56b5adb99a1 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 5512513

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 551251374161cea30db0b1a3f9e2a56b5adb99a1: <one-sentence reason>

@iamwhatever
iamwhatever force-pushed the fix/21837-code-block-comment-mark branch from a83e8ba to 5512513 Compare October 22, 2026 18:36
@iamwhatever

iamwhatever commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: positional lookup of a stored code-comment column

  • span=995396e9afaa A stale column anchors the comment on a different line — fixed in 5512513

fixed: codeQuoteRange now uses the stored position only when its column is inside the named row's current text (column < rowLength); otherwise it falls back to the unique-match lookup, which returns null for an ambiguous quote.
evidence: pierreShadow.test.ts 'does not use a column past the named row when the remaining quote is ambiguous' fails without the bounds check (a Range over row 2's hello) and passes with it.

@iamwhatever

iamwhatever commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: painted-box hit test for code-comment clicks

  • span=71429c1d640f Drag-selection over commented code is cleared — fixed in 5512513

fixed: onClick returns before preventDefault and removeAllRanges() when the hit is a code comment and window.getSelection()?.toString().trim() is non-empty; it does not read isCollapsed, which a shadow-root selection reports as true.
scope: prose comment clicks are unchanged, as the PR's Not-a-goal states.
evidence: MarkdownPanelCodeBlock.test.tsx 'clicking a code comment with selection ...' fails without the guard (removeAllRanges called once) and passes with it; the empty-selection case still clears.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 22, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Review-ready on 551251374161cea30db0b1a3f9e2a56b5adb99a1: all 106 checks pass (0 failing) and the label is readiness: passed. Design, First Principles, UX, GPT and Opus have no open blockers on this head. GPT's two findings from the earlier head are fixed and answered above. The branch merges cleanly; main has moved 3 commits in the same folder (website/src/components/ArtifactBody.tsx), not in this PR's files, so it was not rebased. Waiting for a maintainer review; this PR will not be merged, approved or set to auto-merge by its author agent.

@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) October 22, 2026 20:04

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tier 1 auto-approve: fix (6 files). Criteria: no conflict, no requested changes, security path denylist clean, design-doc gate clean, security checklist all-NO, no reviewer-lane findings, readiness signal fresh for this head SHA, declared category matches the diff. Category: bug fix so a comment on text inside a fenced code block is placed by its stored block position and underlined in the markdown preview, with unit tests and a screenshot harness script.

@KiroCrewCaptain
KiroCrewCaptain merged commit cb679cf into main Oct 22, 2026
107 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/21837-code-block-comment-mark branch October 22, 2026 20:06
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Markdown preview: a comment on text in a fenced code block leaves no mark in the document

2 participants