feat(pdf): hand the annotation gesture policy to the viewer

[andiwand]

🤖 Generated with Claude Code

odr.annotation decided things that are the viewer's to decide, and paid for a
stroke in redraws. Three changes, all inside the emitted script and style.

The host says when to mark

Arming a text tool used to mark whatever the reader selected next. The two
flows are both legitimate and the platforms disagree about which is right —
mobile selects first and offers a toolbar over the selection, desktop arms a
tool and drags — so picking one marks text the reader only meant to select. The
automatic path also has to take the selection with it (removeAllRanges, or
the next selectionchange marks the same range again), which on a phone tears
the range out from under the native selection handles mid-adjustment.

mark() is the explicit trigger now, and leaves the selection standing.
setOptions carries the rest:

option	default	decides
markOnSelection	false	mark as the selection changes, instead of on mark()
inkPointerTypes	null (any)	which pointer types draw — ['pen','mouse'] is palm rejection
touchAction	"none"	what a touch on an armed page does; "pinch-zoom" keeps two-finger zoom
overscrollBehavior	"contain"	scroll chaining out of the document mid-stroke

An unknown key throws rather than being ignored. Where the rendered view sits in
a native scroll container no css we emit can reach it, so the host freezes its
own scroller — it knows when to, having armed the tool. Nothing is added to the
api for that.

The default flip is not a released break (the feature is unreleased), but app
code that only calls setTool now needs mark() too.

A stroke extends its path instead of redrawing the page

pointermove appended a point and called redraw(), which re-serialized every
pending annotation on every page. It now appends to the live path's d and
schedules one dom write per frame, taking every sample getCoalescedEvents()
buffered; the full rebuild is kept for undo/remove/clear/resize. A second
pointer can no longer extend a stroke it did not start.

Measured in the rendered view, same page, before and after:

per pointermove	before	after
stroke alone	0.34 ms	0.051 ms
with 15 marks already pending	4.9 ms	0.054 ms

The second row is the point: the cost no longer grows with what else is on the
page. On a phone the old figure lands around 15–25 ms against an 8 ms budget at
120 Hz. pointerup flushes synchronously, so a window whose rAF is throttled
still ends up with the whole path.

Also added, scoped to an armed page: -webkit-touch-callout /
user-select: none, so a long press cannot interrupt a stroke.

A quad is the run's box, not the range's rect

The vertical extent came from Range.getClientRects(), but the selection layer
is transparent text in whatever font the browser substituted — that rect
measured 10.5 px against the run's 18.7 px box, so the highlight was visibly
shorter than the selection the reader was looking at. It is also not
reproducible: the same pdf on two machines with different fonts installed would
write different /QuadPoints. The quad now follows the .sr run — the line the
renderer laid out from the pdf's own metrics. A partly selected run still takes
its horizontal edges from the rects, clamped to the run.

Checks

test/browser/annotation/tests.html goes from 26 to 41 checks — the explicit
trigger, the options reaching the css, a rejected pointer type, the live path
growing in the node it started in, and the quad following the run box rather
than the substituted font's rect (the harness's .sr is now an inline-block
with a taller line box, so the two geometries differ there as they do in a real
view). All pass, as do 387 odr_test cases over html.*, Pdf* and the pdf
html-output suite.

Two things a reviewer should know:

• The emitted pdf html changed, so the pdf reference-output snapshots need
  regenerating. Not done here.
• The touch behaviour is verified as computed styles in desktop Chrome, not on
  a device. touch-action is honoured by WKWebView (iOS 13+) and Android
  WebView, but the real check is a phone.

Rationale is recorded in docs/design/pdf-annotation.md as decisions 7–9.