Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Feature: Public API for sub-line span decorations

Open
  • Is something wrong?
#884 4 comments 1 reaction 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
38/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Quiet
Tech stack
typescript
Domain
frontend

Research direction

Start by reading the existing intra-line diff highlighting built with Shiki DecorationItems and the exported createDiffSpanDecoration, then compare the consumer APIs on File, FileDiff, CodeView, and BaseCodeOptions. The issue leaves the API shape and naming open, so settle those questions before implementation. Done means consumers can supply character ranges and have them rendered as spans with the requested class.

Written by the indexing model from the issue text.

Description

enhancement
Prerequisites
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 #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:

Image Image
Dominant language
TypeScript
Stars
6.2k
Forks
226
Avg merge
1d 12h
Merged PRs (30d)
34

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from pierrecomputer/pierre

All issues in pierrecomputer/pierre

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.