fix(ui): anchor annotation quotes that carry source markdown

[centraldogma99]

Draft: the behavior change is verified, but the scope decision at the end (how far to chase the remaining case) is worth your call before this is ready.

You have probably hit this

You POST a few annotations into a session from a tool or an agent, and most of them come back sidebar-only. No error, no warning in the UI — just comments that never found their sentence. On the session that prompted this, 2 of 11 anchored.

The cause is not text drift. Every one of those 11 quotes was present in the document, exactly once. They failed because they were accurate.

The mismatch

An external annotation's originalText is its only address. POST /api/external-annotations carries no position data (transformPlanInput pins blockId: "external" and both offsets to 0), so applyAnnotationsInternal skips the metas branch entirely and restores through findTextInDOM(originalText) — a verbatim search of the rendered DOM. That is the documented contract, and it is a reasonable one: an external tool cannot compute browser coordinates, so the quote is the address.

But the two ends of that contract look at different representations of the same document:

	what it holds
where a tool gets the quote	GET /api/plan → the document's markdown — `config.ts` still has its backticks
where the quote is matched	the rendered DOM → config.ts, no backticks anywhere

Nothing reconciles them, so quoting faithfully is what breaks it. In the sample, the 9 misses were exactly the quotes containing a backtick, an asterisk, or a table pipe; the 2 hits were the only two lines with no inline markup at all.

The change

findTextInDOM already has this shape — literal first, then a retry with the renderer's plain-text transform (emoji shortcodes, smart punctuation) when that misses. This adds two more tiers to the same cascade, least destructive first:

3. stripInlineMarkdown — code spans, emphasis, strikethrough, links, images, wiki links.
4. stripTableCellDelimiters — the above plus | and its padding, because a row renders as adjacent <td>s with no text between them: | a | b | reads back as ab, not a b.

Same session: 2 → 10 of 11. A quote that matches the page verbatim returns on tier 1 and never reaches the new code.

The transform is applied to the needle, never the haystack. The search has to end in a DOM Range (which text node, which offset) so a highlight can be painted, and those coordinates only exist in the real DOM — so the rendered text is what stays fixed and the quote is what moves.

Two things worth reviewing closely

Code spans are parked, not unwrapped in place. Their content is literal to the renderer, so ** and __ inside one are ordinary characters. Unwrapping backticks first would hand that content to the emphasis rules — `a__b__c` came out as abc in my first attempt, which a test caught. Spans go behind a sentinel and are restored last.

The new tiers refuse to guess. Stripping shortens the needle and makes it more generic, and searchOnce takes the first hit — so a quote that becomes ambiguous once stripped would silently highlight the wrong paragraph. A highlight on text the comment was never about is worse than no highlight, so tiers 3 and 4 anchor only when the transformed needle is unique. The literal tiers keep first-match-wins; their behavior is untouched.

Known limitation (the scope question)

The 11th quote still misses, for a different reason. Its `config.ts` renders as an ambiguous code-file link, which injects a candidate-count badge into the text stream:

source    | ... | `config.ts` — ... |
rendered    ...   config.ts7 — ...
                           ^ <sup>7</sup>, text the source never had

That is on the haystack side — the renderer added characters, rather than removing syntax — so no transform of the quote can reach it. Fixing it means filtering UI adornments out of the rendered text, which would change what the literal tiers see too. I stopped here rather than widen the blast radius; say the word if you'd rather that were in scope.

Verification

• New unit tests for both pure transforms (inlineTransforms.test.ts), including the code-span protection case that caught the first implementation.
• New DOM tests (useAnnotationHighlighter.test.tsx) covering all four branches: inline-markdown quote anchors, table-row quote anchors, ambiguous-after-strip refuses, and a verbatim quote of duplicated text still anchors (the unchanged literal path). Mutation-checked — relaxing the uniqueness demand fails exactly the refusal test.
• bun run typecheck clean; bun test 4036 pass / 0 fail across 426 files.
• Verified in a browser against the session that prompted this: replayed the same 12 annotations, 2 anchored before, 10 after.

A note on the test run: three apps/pi-extension/server/network.test.ts port cases fail on bun 1.4.0 (server.listenerCount("error") after a failed bind) and pass on 1.3.14, the version CI pins. Reproduced on a clean tree, so it is unrelated to this change — but it is a real forward-incompatibility someone will hit again.

Per CONTRIBUTING.md: fork → PR, dual Apache-2.0/MIT.