feat: configure native clipboard identity for linked selections - #962

@juliusmarminge thanks for the PR. The use case is valid, but I'd like to land a smaller API for it. I've updated this comment after reading how T3 Code uses the prop, so please read it again if you saw the earlier version.

What I'd keep

A single typed prop for the plain-text form of a copied selection:

<EnrichedMarkdownText copyLinksAs="markdown" />

With 'markdown', every link is written as [label](url), so your example pastes as before[Context](ref:one). 'label' (the default) keeps today's behaviour. The other clipboard formats and Copy as Markdown stay unchanged. A 'url' option can come later if someone needs it.

This applies to every link, so ordinary links would also paste as [docs](https://…), including into plain-text apps. Labels and URLs also need escaping so the output stays valid Markdown.

What I'd drop

• linkTextByUrl: the per-URL table forces apps to list every link up front. T3 Code's values are already in the [label](url) form that 'markdown' produces.
• htmlAttributes and mimeTypes: application-specific formats shouldn't be part of this library's API. mimeTypes are UTIs on iOS, not MIME types, and Android can't honour them.
• The JSON-string prop: this should be typed through codegen.
• The example screen and Maestro flow. I'd keep a small unit test for the link rewriting, since the output has to be exact.

The context fragment

I earlier assumed the plain text carries everything a paste needs. From T3 Code's source, it only carries the reference: the records live in the app.t3.context-fragment pasteboard type on iOS and the data-t3-context-fragment HTML attribute on Android, and your native composer reads them on paste. So copyLinksAs alone wouldn't cover that flow.

Instead of adding those formats to the library, I'd add one event:

<EnrichedMarkdownText
  copyLinksAs="markdown"
  onSelectionCopy={({ text, markdown }) => {
    // add your own clipboard data here
  }}
/>

You already have writeContextClipboard(text, fragment), so you could write the fragment from this callback, and the library wouldn't need to know about UTIs or HTML attributes. The downside is that your write lands slightly after the native copy, so a very fast paste could miss it.

Question

Would copyLinksAs plus onSelectionCopy cover T3 Code, or does anything need the fragment on the clipboard in the same write as the native copy? Have I misread how the fragment is used?

Separately, I found that our own input component reads Markdown from a private pasteboard type that our text component's Copy doesn't write, so copy-paste between the two loses links today. That's our bug and I'll fix it on main regardless of this PR.

Thanks for digging into how we use it. You read it right: the plain text only carries the t3-context:// references, and the records live in the fragment.

copyLinksAs plus onSelectionCopy covers T3 Code. Nothing needs the fragment in the same write as the native copy. Only our own composers read it, pasting is always a user action, and the composer drops records the pasted text doesn't reference. So a late write at worst pastes the references without their records. From the callback we'd merge the fragment into your pasteboard item, rather than calling writeContextClipboard, which replaces everything and would drop your RTF, HTML and Markdown.

A few requests so that merge works:

• Fire onSelectionCopy after the native write, from every copy path: the menu's Copy, Cmd+C, Android's action mode, and Copy as Markdown.
• Keep writing a single pasteboard item on iOS.
• In 'markdown' mode, escape only what would break the link: \, [ and ] in labels, and whatever the URL needs. Our label sanitizer turns \ into a space, so my\_file.ts would come back as my _file.ts.

Happy to drop linkTextByUrl, the HTML attribute and UTI options, the JSON prop and the example screen. Should I rework this PR down to copyLinksAs plus the event, or would you rather take it from here?