feat(extensions): support dim tone in line highlighters (#852)

[benvinegar]

Resolves #852

Summary

Adds the "dim" line highlight tone to hunkdiff/extension (registerLineHighlighter), the daemon protocol, and the agent session CLI. This enables review-progress workflows (e.g., hunk-mark-as-reviewed), code coverage, and noise reduction by receding diff text toward the line background while preserving syntax token hues and guaranteeing minimum readable contrast.

Key Details

• Per-token foreground blending: Blends each syntax token's foreground color (span.fg) ~45% toward the line's effective background (contextBg, addedBg, removedBg, or word-diff emphasisBg), preserving individual keyword, string, number, and identifier colors rather than flattening text into a monochrome gray.
• Readability floor: Bounded by MIN_DIM_TEXT_CONTRAST = 1.6 with step-strengthening for low-contrast tokens/themes to ensure text remains legible across dark, light, and transparent themes.
• Paint-time performance: Results are memoized in dimSpanFgCache per (theme, baseBg, sourceFg, ratio) so subsequent renders resolve in $\mathcal{O}(1)$ without re-computing distance/contrast or allocating intermediate RGB objects.
• Geometry neutrality: Affects only paint styling; measurements, column wrapping, and row geometry remain completely untouched.
• Protocol & CLI parity: HIGHLIGHT_TONES, protocol.ts, protocolSchemas.ts, and SessionHighlightAddCommandInput support --tone dim.

Visual Preview

Live interactive mockup: https://sideshow.sh/p/wGMiKmQWjkM

Changes

• Expand ExtensionLineHighlightTone with "dim".
• Implement dimSpanFg and transformFg in src/ui/diff/rowStyle.ts and src/ui/diff/lineHighlightPaint.ts.
• Update session protocol schemas, agent CLI vocabulary, and generated documentation/skill files.
• Add unit tests across rowStyle.test.ts, lineHighlightPaint.test.ts, and validate.test.ts.
• Add changeset fragment .changeset/dim-line-highlighter-tone.md.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hunk-web	Ready	Preview	Aug 30, 2026 12:41am

[greptile-apps]

Greptile Summary

Adds the dim line-highlight tone across the extension API, session protocol, agent CLI, validation, documentation, and diff renderer.

• Blends syntax-token foregrounds toward their effective line or word-diff background while enforcing a minimum contrast floor.
• Preserves highlight geometry and overlapping-tone precedence through paint-time span transformations.
• Adds focused tests and a package changeset for the new public capability.

Confidence Score: 4/5

The PR appears safe to merge, with only a non-blocking documentation formatting issue to address.

The dim tone is propagated through the public types, CLI and daemon contracts, validation, storage, and production paint path, and no concrete behavioral or security failure remains; the sole accepted concern is an overlong modified documentation line.

Files Needing Attention: website/src/content/docs/docs/extend/extension-api.md

Important Files Changed

Filename	Overview
src/ui/diff/rowStyle.ts	Adds cached foreground dimming against effective backgrounds with a contrast floor and a dedicated dim style.
src/ui/diff/lineHighlightPaint.ts	Extends paint styles with foreground transforms while preserving existing span backgrounds and later-range precedence.
src/session/protocolSchemas.ts	Accepts the dim tone in daemon highlight-add requests.
src/session/agent/surface.ts	Adds dim to the shared agent CLI highlight vocabulary.
src/ui/highlights/validate.ts	Allows extension and session line-highlight marks to use the dim tone.
website/src/content/docs/docs/extend/extension-api.md	Documents the new public tone, but the modified paragraph violates the repository's maximum line length.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Extension[Extension highlighter] --> Validation[Highlight validation]
    CLI[Session CLI] --> Protocol[Daemon protocol]
    Protocol --> Validation
    Validation --> Marks[Stored line marks]
    Marks --> Paint[Span paint resolution]
    Paint --> Dim[Foreground blended toward effective background]

Loading

Prompt To Fix All With AI

### Issue 1
website/src/content/docs/docs/extend/extension-api.md:147
**Overlong extension API paragraph**

The expanded line-highlight documentation remains on one line far beyond the repository's 120-character limit, making this public API contract harder to review and maintain. Please wrap the paragraph to conform to the required formatting convention.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "feat(extensions): support dim tone in li..." | Re-trigger Greptile}

[greptile-apps]

Overlong extension API paragraph

The expanded line-highlight documentation remains on one line far beyond the repository's 120-character limit, making this public API contract harder to review and maintain. Please wrap the paragraph to conform to the required formatting convention.

Context Used: guidelines.mdc Cursor rule (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: website/src/content/docs/docs/extend/extension-api.md
Line: 147

Comment:
**Overlong extension API paragraph**

The expanded line-highlight documentation remains on one line far beyond the repository's 120-character limit, making this public API contract harder to review and maintain. Please wrap the paragraph to conform to the required formatting convention.

**Context Used:** guidelines.mdc Cursor rule ([source](https://github.com/modem-dev/modem/blob/main/.cursor/rules/guidelines.mdc))

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[benvinegar]

Wrapped the paragraph to conform to the documentation line-length convention.

_{Responded by opencode using gemini-3.7-flash.}

[evantravers]

Thank you! This looks lovely in the extension.