**Status:** Draft for review **Author:** Aidan Foster **Date:** 2026-07-19 --- ## 1. Purpose Review agents produce findings about the rendered page. For the triage workflow to make sense, each finding has to appear _on_ the content it refers to — a highlight around a word, a sentence, a heading, an image, or a whole group of components. This document specifies the parsing and annotation layer that turns "finding + location" into visible, interactive markers on the rendered page. This layer is invisible when it works: its output is the marker overlay the triage tray (sibling document) interacts with. It determines what the triage UI can and cannot do. ## 2. Scope ### In scope * Parsing the rendered front-end page (content region only) so findings can be anchored to it. * Two marker granularities: block markers and inline markers. * Representing overlapping and nested ranges from independent agents — the hard requirement. * Marker visual states and the interaction contract the triage tray consumes. * The location-reference format findings must carry for the parser to resolve. ### Out of scope * Mapping findings back to their source fields. **We assume feedback is based on the rendered output only.** Field mapping becomes relevant to future apply-step automation and is deferred. * The triage tray itself (cards, decisions) — sibling document. * Generating the findings (agent runs) — #3585828. * Content that re-renders after load; v1 assumes a static rendered page. ### Assumptions * Findings arrive from #3585828 tagged with criterion, severity, rationale, suggested change, and a location reference. * The rendered page is the view-mode page the editor is looking at, inside the admin shell. * Header and footer regions (site chrome) are excluded from parsing and annotation. The exclusion mechanism (region config, selector convention, theme annotation) is an open question (§12). ## 3. Entry workflows ### Workflow A — Finding with a text range The finding references a text run inside a block — as small as a single word, as large as several sentences. It renders as an inline marker (highlight). ### Workflow B — Finding about a whole block or component The finding references an entire element or component — a paragraph, heading, image, pull quote, or a group as large as multiple cards — or is a missing-content finding with no text range at all (e.g. absent alt text). It renders as a block marker. ## 4. Layout and components ### 4.1 Block markers * Outline/underlay on the block plus a **criterion dot** (letter-coded, color-coded) at the block's edge. * Letter codes keep markers distinguishable without relying on color alone — same numbers-carry-the-truth principle as #3585821 §4.1. The codes and colors are customizable by the review creator and specified in the criterion-configuration ticket, not here; the ones shown in the comps (SE, AC, RD, ST, FC, IL, TV, BV, LG) are just examples a review creator would have picked. ### 4.2 Inline markers * Inline highlight on the text run, in the criterion's color, with resting / hovered / active states. ### 4.3 Overlapping and nested feedback (the hard requirement) Different agents review independently, so their feedback overlaps: * A readability agent may flag an entire paragraph or an entire card component (block marker) while a tone agent flags one phrase inside it (inline marker). * One agent may flag a whole sentence while another flags a single word _within_ that sentence. * Ranges can also partially cross rather than nest cleanly. > **Architecture flag — plain `<span>` wrapping cannot represent this.** With nested spans, a closing tag cannot express that it terminates the outer "whole sentence" range rather than the innermost open range, and crossing ranges cannot be expressed at all. The annotation mechanism must carry explicit identity per range. Two candidate approaches: > > * A custom element per range (`<marker data-marker-id>` in the prototype) with ownership resolved by id rather than by DOM nesting. The prototype demonstrates this: each annotated block declares which marker id it owns, so stacked and nested markers resolve to the correct finding regardless of DOM depth. > * A range-based approach such as the CSS Custom Highlight API, where ranges live outside the DOM entirely. > > Choosing between them (including an accessibility evaluation of each) is a prerequisite implementation decision (§12). ## 5. States | ID | State | Trigger | Visible appearance | |----|-------|---------|--------------------| | S1 | Resting | Default | Subtle highlight/outline + criterion dot | | S2 | Hovered | Pointer over the marker, resolving to the **innermost** marker under the pointer | Emphasized highlight | | S3 | Active | Marker's finding is focused in the triage tray (either direction) | Strongest emphasis; page scrolled to the marker when activated from the tray | | S4 | Filtered out | Criterion toggled off in the tray's filter chips | Marker and dot hidden, without re-parsing | ## 6. Interactions ### 6.1 Marker → tray Clicking a marker or its dot activates the corresponding finding card in the triage tray (opening the tray if closed). ### 6.2 Tray → marker Activating a finding in the tray highlights its marker and scrolls the page to it. ### 6.3 Filtering Toggling a criterion filter chip shows/hides that criterion's markers instantly (state S4); no re-parse. ## 7. Anchoring model * The parser resolves each finding's location reference against the rendered DOM at display time. * Anchor by position, not string match alone — the same text can appear multiple times on a page. * Ranges may cross element boundaries (e.g. a sentence spanning a link); the chosen annotation mechanism must tolerate this. * Missing-content findings (no text range) anchor at block level. ## 8. Edge cases * **Repeated text.** Two identical sentences on one page must anchor independently. * **Range crossing element boundaries.** A flagged sentence containing a link or emphasis must highlight contiguously. * **Stacked overlap stress case.** Block + sentence + single word markers in one paragraph must all resolve, hover to the innermost, and remain individually clickable. * **Component-group findings.** A marker spanning multiple cards renders as one block marker on the group. * **Un-anchorable finding.** If a location reference cannot be resolved (content changed since the run), the finding must still be reachable in the tray, flagged as unanchored, rather than silently dropped. ## 9. Data and API surface (referenced, not specified here) This functional doc does not name or assume specific entity types, fields, or method signatures. What this layer needs: * A location-reference format findings carry (block path + optional text offsets) that the parser can resolve against the rendered DOM. Defining this format is shared work with #3585828. * A parse/annotate step that runs when review results are displayed on the page. * A declaration mechanism for the excluded header/footer regions. ## 10. Nice-to-have / future scope * Mapping rendered-page anchors back to source fields (enables apply-step automation). * Re-anchoring on client-side re-render / dynamic content. * Right-to-left language support — flagged May 22; needs dedicated testing once the mechanism is chosen. ## 11. Acceptance criteria The layer is functionally complete when, on a reviewed page: 1. Every finding with a resolvable location renders as exactly one marker — inline for text ranges, block for whole components and missing-content findings. 2. Header and footer chrome never receive markers. 3. A paragraph carrying a block marker, an inline sentence marker, and an inline single-word marker inside that sentence renders all three, hover resolves to the innermost, and each is individually clickable to its own finding. 4. Partially crossing ranges render without breaking either highlight. 5. Criterion dots remain distinguishable without color (letter codes present). 6. Marker :left_right_arrow: tray sync works in both directions (click marker → card; activate card → scroll to marker). 7. Filtering a criterion hides its markers instantly and reversibly. 8. An unresolvable finding surfaces in the tray flagged as unanchored rather than disappearing. ## 12. Open questions * **Annotation mechanism.** Custom-element markers vs. CSS Custom Highlight API (prototype uses custom elements; accessibility of each needs evaluation). * **Header/footer exclusion mechanism.** Region config, selector convention, or theme annotation? * **Location-reference format.** Owned jointly with #3585828; must survive minor markup differences between run time and display time. * **RTL behavior** of highlights, dots, and the dot "track" position. ## 14. Video (Entire workflow) https://zoom.us/media/share/VyxVIvnSRYeej3U8lsSySQ?module=clips&product=video-center ## 15. Claude design — standalone HTML export [Plan Improvements v3 (standalone).html](/uploads/84ec0605ab6c7eb85e0c65f502886e6f/Plan_Improvements_v3__standalone_.html) * `Blog View (standalone).html` / v2 — the marker overlay these captures come from (same export as #3585828). --- _Sources: AI review working sessions May 15 and May 22, 2026 (marker/track design; Editorially reverse-engineering conclusion: do not reuse its code; field-mapping deferral: "we don't have to map it back yet"). Comp explorations done in Claude Code._