Feature: Public API for sub-line span decorations

[chsmc-ant]

Prerequisites

• I have searched for duplicate or closed feature requests
• I have read the contributing guidelines

Proposal

Hi! Big fan.

I (on behalf of design systems @ Anthropic) would like to propose a consumer-facing way to style arbitrary character ranges within a rendered line. Something like a spanDecorations input on File / FileDiff / CodeView that addresses {lineNumber, spanStart, spanLength, className} and wraps the range in a span carrying the class.

The machinery seems to already exists internally... intra-line word/char diff highlighting is implemented with Shiki DecorationItems, and createDiffSpanDecoration is already exported. This would be exposing that stuff for consumer-supplied ranges. I'm aware of #459; this is the character-granularity counterpart, and I'd want to pick a name that doesn't collide with it.

Open API questions I'd defer to y'all on:

• Render prop (like lineAnnotations) vs. option on BaseCodeOptions
• Whether interaction callbacks (onDecoration*, mirroring onToken*) are in scope or a separate ask
• Naming (spanDecorations vs. something else, given Decorations v3 #459)

I'd previously opened #810 with an implementation before discussing it here (sorry for jumping the gun!) That PR is available as a reference if useful, but I'm treating the API shape as fully open.

Motivation and context

We use @pierre/diffs in an internal code review tool. We'd like to add overlays anchored to sub-line ranges for things like...

• Highlighting high-risk spans (e.g. flagging string-concatenated SQL on an added line)
• Muting low-relevance code so the behavioral change stands out
• IDE-style diagnostics squiggles at exact character positions
• Anchoring AI-assist affordances (click a flagged span → explainer card)

I had Claude create some examples of this in action:

[SlexAxton]

hiiiiii chase, sorry for being a little slow on this, the diffs folks are trying to get out some new editor-y features that y'all should beta.

I'll make sure @amadeus sees this and we discuss though so we can get it directionally moving.

[SlexAxton]

oh also cc @cloudhead just for mid-future semantic diff stuff

[chsmc-ant]

@SlexAxton hey dude! No worries we're not in a rush and are excited to try those new editor-y features