docs(stammbaum): renumber pan/zoom ADR 026→027 (collision with #361) (#692)

The #361 layout ADR already owns 026; renumber the custom-viewBox pan/zoom ADR
to 027 and update the glossary + panZoom.ts references (Elicit review).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/adr/027-stammbaum-custom-viewbox-pan-zoom.md

@@ -0,0 +1,56 @@
+# ADR-027 — Stammbaum pan/zoom is a custom viewBox layer, not a third-party library
+
+**Date:** 2026-05-29
+**Status:** Accepted
+**Issue:** #692 (mobile read path — pan, zoom, fit-to-view); supersedes OQ-007
+**Milestone:** Stammbaum mobile read path
+
+---
+
+## Context
+
+#692 makes `/stammbaum` usable on phones: drag-to-pan, pinch/keyboard/wheel zoom,
+fit-to-screen, recentre-on-person, a shareable URL view state, and an edge-fade
+affordance. During issue grooming, **OQ-007 was resolved to adopt the `panzoom`
+library** (timmywil v4.x) on the team's recommendation, pinned per NFR-MAINT-001.
+
+That recommendation predated a load-bearing implementation detail: `StammbaumTree.svelte`
+already renders zoom by **deriving the SVG `viewBox`** (`w = baseW / z`, centred on the
+layout bounding box, `preserveAspectRatio="xMidYMid meet"`) — not by applying a CSS
+`transform`. The `panzoom` library operates by writing `transform` to a DOM node. Adopting
+it would mean:
+
+- abandoning the proven viewBox derivation and the in-SVG generation gutter (#689), which
+  lives in SVG user-space coordinates and would have to be reconciled with a CSS-transformed
+  parent;
+- re-deriving fit-to-screen, recentre, and the `?cx&cy&z` URL state against the library's
+  transform coordinate system;
+- a client-only lazy import to keep the SSR-rendered tree from touching `window` at module
+  load; and
+- ~8 KB of bundle for behaviour we can express in a few pure functions.
+
+## Decision
+
+**Build pan/zoom as a thin custom layer over the existing viewBox**, with no third-party
+dependency. This reverses OQ-007.
+
+- All geometry is pure and unit-tested in `frontend/src/lib/person/genealogy/panZoom.ts`:
+  `clampZoom`, `parsePanZoomParams`/`serializePanZoomParams`, `screenDeltaToSvg`,
+  `zoomAtPoint` (centroid-anchored), `clampPan` (edge-clamp), `recentreOn`, `lerpView`.
+- Pan offsets shift the viewBox centre; zoom scales its width/height. The default
+  `{x:0, y:0, z:1}` already frames the whole tree, so **fit-to-screen is a reset to the
+  default** — no bounding-box recomputation.
+- DOM event wiring lives in the `panZoomGestures` action (pointer/wheel/pinch + inertia,
+  reduced-motion aware) and a keyboard handler on the SVG; both delegate to the pure module.
+
+## Consequences
+
+- **NFR-MAINT-001 (library pinning + feature-flag fallback) is moot** — no library is
+  adopted. The "swap-out point" is `panZoom.ts` + `panZoomGestures.ts`.
+- Text stays vector-crisp at any zoom (SVG-native scaling), satisfying US-PAN-002 AC5.
+- The #689 gutter and the #361 seeded-rank invariant are untouched by the pan/zoom layer.
+- Geometry is testable in the fast node project; only the DOM glue needs the browser project.
+- Trade-off: we own the inertia/pinch code (~a few hundred lines across the action) rather
+  than delegating it. This is acceptable given the testability and zero-dependency wins.
+
+The issue body's OQ-007 row is updated to point at this ADR.