Skip to content

fix: stop Markdown annotation highlights mutating React DOM - #11446

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
Skymore:fix/markdown-annotate-css-highlights-11025
Sep 17, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
Skymore:fix/markdown-annotate-css-highlights-11025

Conversation

@Skymore

@Skymore Skymore commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Markdown annotation highlights wrap selected text in <mark> elements inside react-markdown output. When an agent streams an artifact update that rewrites the annotated passage, React can reconcile against nodes that surroundContents(), removeChild(), or normalize() already moved or replaced and crash the preview with NotFoundError: Failed to execute 'removeChild' on 'Node'.

Why it matters

A normal comment-and-edit workflow can hard-crash the companion Markdown preview while the agent is updating the document. The error boundary limits the blast radius to the panel, but the user loses the live preview until it is reopened.

What changed

Annotation highlighting now stores selected text segments as Range objects in a CSS Custom Highlight rather than inserting and removing React-owned nodes. Clearing or changing a selection updates the registry only.

Multiple mounted file tabs contribute independently to the shared annotation highlight. Closing or unmounting one tab removes only its own ranges, and the generic panel-unmount cleanup no longer deletes the global annotation entry after per-owner cleanup has republished surviving ranges.

When CSS Custom Highlight is unavailable, annotation remains functional but is not painted. The DOM-mutating fallback is intentionally not retained because it reintroduces the crash. The accent fill is preserved; the old 2px <mark> radius is absent because CSS highlights do not paint box geometry.

Tests

  • Added annotation tests for multi-node ranges, clear/reapply behavior, API absence, unmount cleanup, and multiple mounted file tabs.
  • Updated existing MarkdownPanel tests to assert registry-based highlighting rather than <mark> insertion.
  • Passed all eight MarkdownPanel-related test files: 207/207 tests.
  • Passed TypeScript typecheck and ESLint for every changed source file.
  • Passed the production frontend build.

Manual verification

Rendered a deterministic before/after fixture using the production light and dark theme tokens. The annotation accent fill and current find-match fill remain unchanged; only the unsupported 2px annotation radius differs.

Screenshots / video

Light and dark comparison of Markdown annotation and find highlights before and after the fix

Related Issues

Fixes #11025

Pattern harvest

Rule candidate: review-prompt
Pattern: Visual decoration inside React-rendered content must not structurally mutate React-owned DOM; use a paint-only API or an isolated non-React container.

Checklist

  • One commit with a Conventional Commits title
  • Existing tests pass and new tests cover changed behavior
  • Self-review completed; code follows project style guidelines
  • Documentation updated (N/A — no user-facing contract changed)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

N/A — repository CLA wording is not yet available.

@Skymore
Skymore requested review from a team and patrigao September 17, 2026 03:17
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 17, 2026
@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — 🟡 CONCERNS

Design-level review of fa4b85be511703feacf2d5c4ee343a988a3bcb41 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

Half the PR is phantom: the title and description claim backend CI-contract fixes (Fargate, ledger, completion-sound) that this diff does not contain.

Watch

The annotation change itself is the right shape: it fixes the root cause (React-owned DOM mutation) with the same paint-only mechanism find already uses, the per-owner range aggregation is pinned by new multi-tab tests, the no-paint degradation and lost 2px radius are stated and shown in the rendered before/after evidence.

[DESIGN-REVIEWED] fa4b85b

@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed fa4b85be511703feacf2d5c4ee343a988a3bcb41 via the fork AI-review pipeline; updated in place on each push.

Review details

FINDING -- website/src/components/MarkdownPanel.tsx:59 -- the diff adds only the Markdown "mc-annotate" work but the description claims unrelated backend CI-contract changes -> Fix: remove those backend claims from the PR description.
[GPT-REVIEWED] fa4b85b

@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5, fork) — 🟡 CONCERNS

UX-level review of fa4b85be511703feacf2d5c4ee343a988a3bcb41 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: CONCERNS

On browsers without CSS Custom Highlight the annotation passage now paints no highlight at all — users typing a comment lose sight of which text it targets.

Watch

  • The PR states "annotation remains functional but is not painted" when CSS.highlights is absent (applyHighlightMarks early-returns: if (!FIND_HL_SUPPORTED …) return). The old <mark> fallback always painted; now a user on an older browser opens the composer over an invisible anchor and must remember what they selected — low frequency (modern browsers support the API), persistent friction for those users every comment. Smallest fix: the codebase's InlineCommentOverlay already paints anchored comments with real overlay elements; reuse that paint path as the no-API fallback for the composer highlight.
  • The rendered accent fill (attachment-01.png, light + dark) is shown but no first-time reader has seen it — this lane reviews a fork with no blind read, which caps the verdict at CONCERNS; pushing the branch to this repository would restore the blind read.

[UX-REVIEWED] fa4b85b

@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of fa4b85be511703feacf2d5c4ee343a988a3bcb41 via the fork AI-review pipeline — 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/CONCERNS are advisory.

First-Principles-Verdict: PASS

This diff ships only the Markdown fix — the "restore CI contracts" half of the title/description already landed on main (#11442, #11445; fargate_engine.py:356 carries the error field); trim it.

What this change ships

Inventory (6 items) — 6 justified

Intent: stop the companion Markdown preview crashing (NotFoundError) when an agent rewrite lands while a comment highlight is active (#11025) — a FIX.

  1. Commenting a selection no longer wraps preview text in <mark>; a CSS Custom Highlight paints it — justified
  2. An agent rewrite while the comment box is open no longer crashes the preview — justified
  3. Highlights in two mounted file tabs coexist; closing one composer no longer erases the other's — justified
  4. Without the Highlight API (old Safari/Firefox) the selection paints nothing; the crashing DOM fallback is gone — justified
  5. The highlight's 2px rounded corners are gone; the accent fill stays — justified
  6. Tests that pinned the <mark> mechanism now pin the paint-only registry — justified

The fix sits at cause level: it removes the DOM mutation itself, reusing the find machinery already in MarkdownPanel.tsx. Sibling scan for surroundContents|normalize() in website/src: the only other hits are widgetSrcdoc.ts:453,540, inside sandboxed iframe srcdoc — not React-owned, 0 unfixed siblings.

[FIRST-PRINCIPLES-REVIEWED] fa4b85b

@github-actions

github-actions Bot commented Sep 17, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ✅ no blocking findings

Reviewed fa4b85be511703feacf2d5c4ee343a988a3bcb41 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] fa4b85b

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 17, 2026
@Skymore
Skymore force-pushed the fix/markdown-annotate-css-highlights-11025 branch 2 times, most recently from 4547d0b to d290c89 Compare September 17, 2026 04:18
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 17, 2026
@Skymore Skymore changed the title fix: stop Markdown annotation highlights mutating React DOM fix: stop Markdown DOM mutation and restore CI contracts Sep 17, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 17, 2026
@Skymore
Skymore force-pushed the fix/markdown-annotate-css-highlights-11025 branch from d290c89 to 93ccb5a Compare September 17, 2026 04:31
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 17, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 17, 2026
@Skymore
Skymore force-pushed the fix/markdown-annotate-css-highlights-11025 branch from b57fc3c to 7f561a4 Compare September 17, 2026 05:43
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 17, 2026
@Skymore
Skymore force-pushed the fix/markdown-annotate-css-highlights-11025 branch from 7f561a4 to fa4b85b Compare September 17, 2026 06:41
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision readiness: action required A blocking check or review needs attention labels Sep 17, 2026
@Skymore Skymore changed the title fix: stop Markdown DOM mutation and restore CI contracts fix: stop Markdown annotation highlights mutating React DOM Sep 17, 2026
@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Sep 17, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Reviewed the full diff on head fa4b85b as part of the 2026-09-17 readiness audit (evidence: pr-ready-audit-20260917-0835). Verified before approving: readiness: passed in place, required status PR Readiness success on this head, no CHANGES_REQUESTED, no unresolved human hold, main-drift checked against files this PR touches, last push by Skymore. Merge follows through the normal protected path (no bypass).

@bolichen97
bolichen97 merged commit 26db5a8 into kirodotdev:main Sep 17, 2026
94 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 17, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

MarkdownPanel annotation marks mutate react-markdown DOM (surroundContents + normalize)

2 participants