Follow-up to #1016: finish the paint-inside-your-box contract; evaluate inner-<g> rotation

[talpitoo]

Follow-up to #1016 (host clipping + svg { display: block }), which fixed the two overflow classes where they were user-visible. Three remaining items, in descending priority.

1. Four components still have the inline-SVG line-box gap

bearing-indicator, compass-indicator, gauge-horizontal, gauge-vertical render an in-flow inline <svg> with no display: block (audited on develop @ next.122, 2026-08-11 — these are the only four left). Same phantom-height mechanism #1016 fixed for watch, watch-flat and thruster: an inline svg participates in a text line box and reserves ~3–5px of descender space below the graphic, which surfaces as mystery scrollbars / extra height in overflow: auto cells. Their indicator/gauge siblings already carry display: block, so this is aligning stragglers with the established pattern. Expected: zero-pixel snapshot change (the gap is phantom layout height only), as verified for #1016's hunks.

2. One-line docs checklist addition

docs/agents/watch-radial-instruments.md now documents the mechanism ("Host clipping & the arrow-apex shave"), but the new-feature checklist at the bottom doesn't tell the author of a new instrument when the rule applies. Add a checklist line along the lines of: "Rotating an <svg> element box (transform="rotate(...)" on the element)? The host must clip — see Host clipping & the arrow-apex shave." (Edit the source in docs/agents/, then npm run agents:sync.)

3. Decide-by-measurement: inner-<g> rotation refactor

Recording the alternative considered and deliberately not taken in #1016, so it isn't re-discovered later without its trade-offs.

obc-watch (root svg) and obc-compass-sector (overlay svg) are the only two element-box rotations in the codebase. Moving the rotation into an inner <g> would keep the element box axis-aligned, so the svg's own viewport clip would contain all painted content by construction — removing the leak half of the host-clip requirement.

Why it wasn't done in #1016:

• Identical pixels. The svg viewport edge and the host box edge are the same edge — even the compass-sector arrow-apex shave is unchanged. Zero user-visible improvement.
• Baseline churn on the most sensitive shared file. Every rotating story risks AA-level shifts that each need review.
• Open performance question — the reason this item exists. A transform on the svg element is a CSS transform: browsers can update it compositor-side without re-rasterizing vector content. Rotation inside a <g> forces a full SVG re-raster per heading update. With continuously streaming heading data and several instruments per screen on low-power bridge hardware, that difference may be material — or negligible. Nobody has measured it.

Exit criterion: profile both variants under realistic load (several rotating instruments at ~10 Hz heading updates on a low-end target). If inner-<g> is not measurably worse, it's a legitimate hardening refactor to schedule; if it is worse, close this item — the host-clip contract stays the long-term answer (a component never paints outside its box: :host { overflow: hidden }, plus display: block for in-flow svgs).

Context: the "Host clipping & the arrow-apex shave (PR #1016)" section in docs/agents/watch-radial-instruments.md, and the verification comments on #1016.

[talpitoo]

Ran the item-3 measurement. Verdict: keep the element-box rotation + host clip; the inner-<g> refactor is rejected on data. Item 3 can be closed when #1130 (items 1+2) merges.

Setup

Six real <obc-compass> instances (300×300, day palette) driven in headless Chromium via Playwright, 8-second windows × 2 runs per condition, Chrome tracing with cc + devtools.timeline categories so raster-thread work is captured. Two variants: current (transform="rotate()" on the <svg> element) vs a patched watch.ts/compass-sector.ts rotating a wrapping inner <g>.

Performance

metric (8 s, 6 compasses)	element transform	inner <g>
fps @ 10 Hz updates	60	60
fps @ per-frame updates	60	60
main-thread Paint @ 10 Hz	83–94 ms	242–272 ms (~3×)
RunPaintLifecyclePhase @ 10 Hz	83–94 ms	265–272 ms
BeginMainFrame @ 10 Hz	622–662 ms	797–798 ms (+25%)
RasterTask @ 10 Hz	368–405 ms	392–405 ms (≈ equal)
main-thread Paint @ per-frame	183–189 ms	293 ms (+55%)
RasterTask @ per-frame	1991–2133 ms	2180–2216 ms (+4–5%)

Mechanism, confirmed by the trace shape: an element-level transform update reuses the display list — the browser only re-rasters the existing paint records under a new matrix. Mutating a <g> inside the svg dirties the content and rebuilds the display list every update. Raster cost is the same either way (the hypothesis that element transforms skip re-raster was wrong — they don't; the savings are all in main-thread Paint). On this desktop-class container both variants hold 60 fps; on low-end bridge hardware the ~3× Paint multiplier at 10 Hz is the number that scales against you, per instrument on screen.

Fidelity — the sharper finding

The swap is only a drop-in where the viewBox is origin-centred. The element rotates about its CSS box centre; an inner <g> rotates about the SVG user-space origin:

• Full-circle faces (centres coincide): 168 of 700,000 px differ at identical heading (AA-level); every full-circle story — including compass at heading: 311 — stays under the 4-px snapshot threshold.
• compass-sector (cropped frame, centres differ): the naive swap visibly displaces and tilts the arc — 11 of 12 baselines fail, up to ~3,400 px. A faithful port needs per-frame-type translate-rotate-translate compensation, which is exactly the error-prone part.

Conclusion

The refactor costs measurable main-thread work, is a geometry trap on every non-origin-centred frame, and buys zero visual improvement (the arrow-apex shave happens at the same box edge either way). The long-term contract stays: a component never paints outside its box — :host { overflow: hidden } on rotating hosts, display: block on in-flow svgs (#1130 closes the last four stragglers and adds both rules to the docs checklist). The docs section now records the measured verdict so this isn't re-derived.

(Local-only note: indicator-graph and graph-mini visual tests fail in my container even on pristine develop — canvas-family rendering flakes, excluded from all counts above.)