feat: add opt-in native link pill presentation

[juliusmarminge]

What/Why?

Opt-in pill presentation for Markdown links on iOS and Android. A link whose markdownStyle.linkVariants entry sets pill is drawn as a rounded label with an optional icon; every other link is unchanged. Refs #860.

The PR was started by @juliusmarminge. The implementation was then reworked on top of his commits; the comment below explains what changed and why. This description covers the current head.

• Style: pill: true uses the defaults; pill: { label, iconUri, borderRadius, paddingHorizontal, paddingVertical, borderWidth, borderColor, maxWidth } customizes it; omitted, false or null keeps an ordinary link. Colors, underline and font family stay on the link variant.
• Per-link content: the new linkPillContent prop sets the label and icon of individual links by exact URL. It is content, not style, so markdownStyle can stay a stable object while it changes. Per-link content wins over the variant's pill.label / pill.iconUri, which win over the link text.
• Icons: local files and bundled assets show on the first layout. http(s) sources load through the same pipeline as Markdown images, using imageRequestHeaders, and the pill keeps room for them while they load. A source that fails shows no icon and is retried after 30 seconds.
• Layout: a pill wraps as one unit and truncates at the available width or maxWidth. It works in paragraphs, headings, lists, blockquotes and table cells.
• Links that stay ordinary: a link whose text contains an image, inline math, a hard line break or a spoiler. A pill inside an unrevealed spoiler is hidden with the rest of the spoiler.
• Text leaving the view: copy, Markdown/HTML/RTF export, accessibility labels and the iOS selection actions (Look Up, Translate, Share) receive the link's own text and URL.
• Web and macOS: render ordinary links and ignore pill and linkPillContent.

API

<EnrichedMarkdownText
  markdown="Open [src/components/a/long/path/file.ts](https://example.com/files/a/long/path/file.ts)"
  markdownStyle={{
    linkVariants: {
      '^https://example\\.com/files/': {
        color: '#3730A3',
        backgroundColor: '#EEF2FF',
        pill: { iconUri: 'file_icon', borderRadius: 10, maxWidth: 180 },
      },
    },
  }}
  linkPillContent={{
    'https://example.com/files/a/long/path/file.ts': { label: 'file.ts' },
  }}
/>

Docs: docs/MENTIONS.md (pill section), docs/API_REFERENCE.md (linkPillContent), docs/WEB.md, docs/MACOS.md.

Implementation

• iOS: a pill link is one attachment character (ENRMLinkPillAttachment), laid out and drawn by TextKit like images and inline math. The link's rendered text is kept on the attachment and put back by ENRMLinkPillText wherever text leaves the view. ENRMMarkdownTextView does the same for the system selection actions. This replaces the custom text storage and glyph substitution of the first version.
• Android: LinkPillSpan is a ReplacementSpan over the original link text, which stays in the buffer. Widths are prepared per layout thread through a shared helper (prepareWidthAwareSpans), and a span change redraws the pill when its icon arrives or a spoiler over it is revealed.
• Shared: pill is a nested object on the native link variant; linkPillContent is passed like imageRequestHeaders. Measurement caches on both platforms account for link variants and pill content.
• Outside the feature: the Android ImageDownloader now reports a request OkHttp rejects as a failed download instead of throwing into the render. The example's iOS test target inherits only the pods' search paths, because linking the pods into the test bundle loaded every library class twice.
• Packaging: android/src/test is excluded from the npm package (files in package.json). The android folder is published whole, so the unit tests shipped with it; a dry run of npm pack now lists no test files.

Testing

CI passed on 5a694ac1: RN lint, library build, Android and iOS builds, Android and iOS unit tests. The one commit after it (60896773) only adds the npm files exclusion.

• Jest: link-pill-style.test.ts (style normalization, content normalization and equality).
• Android: 38 Robolectric tests in LinkPillSpanTest.kt.
• iOS: 19 XCTest cases in ENRMLinkPillAttachmentTests.mm, now registered in the example's test target and run by CI.
• Manual: iOS simulator (iPhone 17, iOS 26.5) and an Android emulator, with a local demo screen that is not part of this PR. Checked rendering in every block type, remote icons arriving late, a failing icon, and spoiler reveal.

Not covered: drag-and-drop of a selection containing a pill on iOS, and Maestro E2E. After main was merged into the branch, the on-device check was repeated only for rendering on Android.

PR Checklist

• Code compiles and runs on iOS
• Code compiles and runs on Android
• Updated documentation/README if applicable
• Ran example app to verify changes
• E2E tests are passing
• Required E2E tests have been added (if applicable)

Original description (written for head 7781ab1, before the rework)

What/Why?

Extend the existing markdownStyle.linkVariants configuration with optional iOS/Android pill presentation for explicit Markdown links. Consumers supply label, local icon URI and geometry through pill: { ... }; pill: true uses defaults, and omission, false or null disables it. Link colors and font family remain variant-level fields. Pills wrap as one unit and truncate within the native content width. pill defaults to false; ordinary links keep their existing presentation when it is omitted.

The original characters and URL stay in native text storage for link callbacks, accessible names including both visible and original link text, copy and Markdown export. Pills use the existing block fonts, including their weight, and reach table cells and existing measurement stacks. Inline-code backgrounds are suppressed beneath the pill while code semantics stay intact. Native icon caches are bounded and downsampled.

TextKit retains attachment attributes during ordinary fixing, anchors bounds/images to the first original source character, and tracks callback continuation per layout manager without surrounding glyph queries. Ordinary and unrelated-attachment glyph callbacks skip full buffer copies and longest-range scans.

Refs #860. The font-family foundation #861 merged on September 24, 2026. The maintainer merged upstream main into this branch; that merge is preserved exactly. Review the core diff against current upstream main. Optional icon tint follows in #863.

API

linkVariants: {
  '^https://example\\.com/': {
    color: '#1264A3',
    backgroundColor: '#E8F5FB',
    fontFamily: 'CustomFont',
    pill: { label: 'Document', iconUri: 'file:///path/icon.png', maxWidth: 180 },
  },
}

The internal flat native transport stays aligned with the existing library normalization patterns. iOS icons use the shared file-backed local/bundle resolver and ImageIO thumbnails with a pressure-aware NSCache. Android icons reuse LocalImageLoader and ImageCache with a 512-pixel bound on both axes and bounded cache identity strings. Ordinary image-loading defaults remain unchanged. usesFontLeading = NO now matches the other TextKit stacks. Storage fixing has a no-pill fast path and documents its wider preservation scope.

Testing

Earlier reviewed dedicated-worktree source passed TypeScript, 8 Jest suites/53 tests, Bob modules/declarations and both native code generators. Android ktlint, 17 native-graphics Robolectric regressions and library debug AAR compilation passed. Scoped formatting/whitespace checks and normal commit hooks passed. Regressions cover nested opt-in/default/disabled configuration, accessible link nodes retaining visible and original text, local icon downsampling, cache eviction without recycling visible owners, and original Markdown/callback semantics.

iOS XCTest source includes attachment/source geometry, fragmented attributes, streaming UITextView, pill removal/reintroduction, accessible names and no-font-leading measurement regressions. It remains unwired/unrun. The RN harness is now wired; the maintainer owns the remaining pill test-target registration. Previous-head upstream CI passed RN lint, library, iOS and Android builds on September 23, 2026. These are compilation checks; they do not execute this unwired RN XCTest suite or prove device rendering. No isolated-head device execution was performed.

September 24 update: current core is 7781ab17; tint is 0eca6691. Core integrates upstream main cdb54825 and preserves all preceding maintainer commits exactly. The new iOS paragraph-style conflict adopts upstream's minimum line-height behavior for tall inline code while retaining pill box height in baseline centering. Upstream list-item and code-block adjustments and documentation are preserved. Added XCTest source compares original-character pill geometry and exported Markdown with a replacement-character reference at line-height floors below and above the pill. This test remains unwired/unrun. No public API, Android or JavaScript source delta in this update. Both tint patches replay identically.

On these exact heads, TypeScript and all nine Jest suites passed: core 58 tests, tint 60 tests. Scoped clang-format, whitespace checks and normal commit hooks passed. The preceding 5260f94f/ec5ab1fd heads passed 18/20 focused Android native graphics tests, Kotlin lint, Bob/module/declarations/native codegen locally; their upstream Android build/test jobs passed, with iOS jobs still queued at refresh. Those results precede this iOS compatibility update. Both current branches are free of the reported main conflict. Current-head CI completed successfully, verified through fresh REST run/check/job reads on September 24, 2026 at 18:02 UTC. RN lint, library, Android build/unit tests and iOS build/unit-test jobs passed, with the aggregate ci-success check passing. The successful iOS test job does not execute the unregistered pill XCTest source. This CI result is separate from the combined-consumer UI proof below and does not establish current-head approval or merge readiness. The RN harness still excludes ENRMLinkPillTextStorageTests.mm from its explicit compile-source list. Pill XCTest and strict reference geometry remain unwired/unrun. Isolated upstream-head UI remains unrun. The consumer owner completed integrated native validation for these exact sources on September 24, as labeled below.

Combined-consumer proof and limits

On September 24, 2026, the consumer owner rebuilt, installed and personally inspected the integrated iOS app containing core 7781ab17 and tint 0eca6691. This is combined-consumer validation containing other library and consumer changes. It is not isolated upstream-head UI proof or a controlled upstream base/head comparison. Installed native fingerprint: c6809326ed4555205bcbb19db0319156b120257c.

Temporary style probes used 34px inline code with 18px and 44px paragraph/list/quote line-height floors, below and above the pill height. The owner visually inspected full code glyphs, one pill per original source link and no observed overlap. These are visual observations; strict replacement-character reference geometry assertions were not run. The shipping wrapper was then restored byte-identical and fully reloaded.

18px floor, temporary probe	44px floor, temporary probe

Additional 44px list/quote probe capture.

The restored shipping app showed one pill per root, inline-code, quote, nested-quote, table and quoted-table link. Actual native accessibility nodes included environmentPresence.ts plus its original path and Mobile Check plus $mobile-check. After genuine provider metadata resolved following the full reload, the shipping skill menu copied $mobile-check. Relative/full file clipboard values were exact, and routing opened the correct six-line source viewer. Native menus remained anchored in root, quote, nested quote and quoted table contexts. Nonlink quoted-table Copy as Markdown retained the original source label and URL.

Restored shipping quoted-table menu capture. Temporary style probes are separate from this restored shipping evidence.

Combined build provenance and checks

Combined library source is local commit 105fd60e2c57dfec0370ccef577c253ac9d3ec7f; consumer source is 5b6a1441. The consumer's existing #12781 records the inspected evidence. The local combined commit has no claimed GitHub URL. Contributor coauthor credit was retained.

The prepared archive was react-native-enriched-markdown-1.1.0-nightly-20260918-bb2b0942a-main-compat-v1.tgz, 1,033,101 bytes and 926 files, SHA-256 59ba5df5492476181ecbe1ba573a1c163c4da3eaeea0431f30ed5ea235876319. The combined library/consumer passed 14 JavaScript suites/93 tests, types, Bob and both native code generators, normal hooks and frozen installation on Linux and Mac. These are combined-source checks, not a new claim about isolated upstream tests.

The official iOS retry rebuilt and installed successfully. Its first attempt exhausted disk and supplied no proof. The successful retry used the previously documented host-only XCODE_XCCONFIG_FILE resource overrides: CLANG_ENABLE_EXPLICIT_MODULES=NO, SWIFT_ENABLE_EXPLICIT_MODULES=NO, GCC_GENERATE_DEBUGGING_SYMBOLS=NO, DEBUG_INFORMATION_FORMAT=dwarf. These are consumer-host settings, not upstream CI or shipped native-harness configuration.

The full Android consumer APK retry passed, 1,301 tasks in 7m45s. Its first attempt exhausted tmpfs before native compilation and supplied no proof. Shipping Gradle configuration was retained. Android UI was not run; the Device host AVD-listing failure persists.

Native pill XCTest target registration remains maintainer-owned, and that suite and strict U+FFFC reference geometry remain unwired/unrun. No isolated upstream-head UI, Android UI or VoiceOver traversal claim. Consumer full main CI was not observed; fresh metadata/config checks alone do not prove CI. The library example and Maestro E2E were not run. No new full video-playback claim. Earlier September 23 evidence remains recorded in the consumer PR and prior handoff; the September 24 captures above are the current combined-consumer proof for these exact core/tint sources. Maintainer approval is against an earlier reviewed core and does not prove current-head CI or native tests; the maintainer plans to defer merging until next week to exclude the upcoming release. Consumer recognition, metadata and actions remain outside the native API.

PR Checklist

• (unchecked) Code compiles and runs on iOS
• (unchecked) Code compiles and runs on Android
• (checked) Updated documentation/README if applicable
• (unchecked) Ran example app to verify changes
• (unchecked) E2E tests are passing
• (unchecked) Required E2E tests have been added (if applicable)

🤖 Generated with Claude Code

[eszlamczyk]

Hi @juliusmarminge thanks for this big work! Strong PR overall, the pill design is sound, it correctly preserves the text under presentation layer, and the Android test suite is genuinely thorough. In the spirit its already approved, but there are at least four main areas I need attention before we can think about merging this. Rest are nitpicks, that I still'd like to have them resolved, they arent blocking ones.

1. API / native TextKit usage. ENRMPillLayout omits usesFontLeading = NO maink it the only TextKit stack that violates the "must be set to NO rule (ENRMViewFreeMeasurement.h`)

2. Image loading/caching. The pill icon cache reinvents already existing caching for both IOS and android. Additionaly the file-only buset bunde-asset handling. I'd like already working solutions reused.

3. Accessibility. Currently with label override enabled the pill shows something different than the Talkback/voiceover say. This is a violation of WCAG 2.5.3 (Label in Name). We should resolve this before merging.

4. API shape, currently the API is very unpleasant for end user to work with, more informations are in the relevant inline comments

[eszlamczyk]

Excellent, real-graphics test coverage (pixel + exact-width assertions, not shadow no-ops). Note these aren't in CI yet - the lane only runs the standalone @enriched-markdown/android package. Harness is ready; I'll wire the RN Android + iOS test lanes in a separate follow-up PR.

Thanks for the good tests!

[juliusmarminge]

The RN Android suite passed locally through the library harness: 17 core tests and 19 after tint propagation in e3e7b18e. This is not upstream CI execution. I have left RN native test-lane wiring to your follow-up, and the iOS XCTest suite remains explicitly unwired/unrun.

[eszlamczyk]

Hi again @juliusmarminge, everything looks good to me! All the issues got addressed and I believe everything should be alright.

One note, we will not merge this before next week, because we don't want this to land into next release. Due to this I will review rest of the pull requests in this stack (they appear as smaller changes that should have less pushback) after merging of this one

[hryhoriiK97]

@juliusmarminge a few comments from my side. I've tested this locally on both platforms (unit tests plus a demo screen in the example app) and it looks fine overall — the pills render well and I saw no slowdown for documents without them.

I left some inline comments. Four I'd like fixed before merge: the Android blockquote offset, the style cache miss for nested pill objects, the iOS test file not compiling, and the accessibility lookup that regresses #898 after merging main. The rest are smaller.

[hryhoriiK97]

@juliusmarminge @eszlamczyk a heads-up on where this PR is going.

Instead of continuing in review comments, I pushed commits on top of Julius's branch. They rework how pills are implemented. The public pill option is unchanged, so existing linkVariants configs keep working. I also updated the PR description to match the current head; the original text is kept at the bottom of it.

Why the change of direction

On iOS the first version kept the link's characters in text storage and hid them with a custom text storage and glyph substitution. It worked, but it was a second layout mechanism next to the one we already use for images and inline math, and most of the points in my review came from it. I want pills to go through the same path as the other inline attachments, so they share the layout, measurement and table code we already maintain.

What changed

• iOS: a pill is now a single attachment character, laid out and drawn by TextKit. The link's own text is kept on the attachment and put back wherever text leaves the view: copy, Markdown/HTML/RTF export, accessibility and the system selection actions (Look Up, Translate, Share). That is the trade-off of this design: new code that takes text out of the view has to call the same helper.
• Android: the approach is the same as before, a replacement span over the original link text. The changes are per-thread layout state, a redraw when an icon arrives or a spoiler is revealed, and performance fixes.
• New prop linkPillContent: label and icon per link, keyed by exact URL, so markdownStyle can stay a stable object while the content changes.
• Remote icons: iconUri also accepts http(s) URLs, loaded through the image pipeline with imageRequestHeaders.
• Spoilers: a pill inside an unrevealed spoiler is hidden, and a link that contains a spoiler stays an ordinary link.
• Tests: the iOS pill tests are now part of the example's test target and run in CI, next to the Android and Jest ones.
• The points from my earlier review are addressed in these commits.

main is merged in and CI is green on the current head.

What I'd ask from you

• @eszlamczyk: your approval was for the previous implementation, so please take another look at the current head.

Known gaps: drag-and-drop of a selection that contains a pill is untested on iOS, and there are no E2E tests for pills yet.

[hryhoriiK97]

Update on how this lands.

I merged this PR into feat/link-pills, a new integration branch in this repo, not into main. The branch holds exactly this PR's last head: Julius's implementation plus the rework from my comment above.

From here:

• The feature reaches main through feat: add native link pills #920 (feat/link-pills → main). CI runs there.
• Follow-ups go in as small PRs against feat/link-pills, so each one shows only its own diff. The first is the icon tint: I'm redoing feat: support optional tint for native link pill icons #863 on top of the new implementation in a new PR and will close feat: support optional tint for native link pill icons #863 with a link once it is up. @juliusmarminge, the option and its tests are yours, so you stay credited on it.
• @eszlamczyk, please leave further review comments on the pill work in feat: add native link pills #920.