From b1309db8db9d81c2c5028f89cd4d65cfe9359bce Mon Sep 17 00:00:00 2001
From: Marcel <marcel@familienarchiv>
Date: Fri, 29 May 2026 19:25:03 +0200
Subject: [PATCH] feat(stammbaum): land a fresh visit on the tree's top-left
 corner (#692)

At z=3 a pan of {0,0} centres on the tree midpoint; a fresh visit (no shared
?z) now anchors the viewBox to the tree's top-left corner via topLeftView
(the negative clamp limit), emitted on mount. Shared links still win.
Verified live: lands at cx<0, cy<0.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../src/lib/person/genealogy/StammbaumTree.svelte   | 12 +++++++++++-
 frontend/src/lib/person/genealogy/panZoom.test.ts   | 13 +++++++++++++
 frontend/src/lib/person/genealogy/panZoom.ts        |  9 +++++++++
 frontend/src/routes/stammbaum/+page.svelte          |  1 +
 4 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/frontend/src/lib/person/genealogy/StammbaumTree.svelte b/frontend/src/lib/person/genealogy/StammbaumTree.svelte
index 72009b4a..811b2c9f 100644
--- a/frontend/src/lib/person/genealogy/StammbaumTree.svelte
+++ b/frontend/src/lib/person/genealogy/StammbaumTree.svelte
@@ -1,5 +1,5 @@
 <script lang="ts">
-import { untrack } from 'svelte';
+import { untrack, onMount } from 'svelte';
 import { SvelteMap, SvelteSet } from 'svelte/reactivity';
 import type { components } from '$lib/generated/api';
 import {
@@ -13,6 +13,7 @@ import {
 	type PanZoomState,
 	clampZoom,
 	recentreOn,
+	topLeftView,
 	ZOOM_STEP_KB
 } from '$lib/person/genealogy/panZoom';
 import { panZoomGestures } from '$lib/person/genealogy/panZoomGestures';
@@ -32,6 +33,8 @@ interface Props {
 	centreOnId?: string | null;
 	/** Fired on the first pointer interaction with the canvas (affordance dismiss). */
 	onActivity?: () => void;
+	/** When true, the initial view is anchored to the tree's top-left corner. */
+	anchorTopLeft?: boolean;
 	onSelect: (id: string) => void;
 	/**
 	 * Force-show or force-hide the generation gutter. When undefined, falls
@@ -50,6 +53,7 @@ let {
 	onPanZoom = () => {},
 	centreOnId = null,
 	onActivity,
+	anchorTopLeft = false,
 	onSelect,
 	showGutter
 }: Props = $props();
@@ -139,6 +143,12 @@ const railRows = $derived(
 		.map((r) => ({ rank: r.rank, label: r.label, centerY: r.y + NODE_H / 2 }))
 );
 
+// A fresh visit (no shared URL state) lands on the tree's top-left corner rather
+// than its centre (#692). Runs once after layout is available.
+onMount(() => {
+	if (anchorTopLeft) onPanZoom(topLeftView(baseDims.w, baseDims.h, panZoom.z));
+});
+
 const viewBox = $derived.by(() => {
 	const w = baseDims.w / panZoom.z;
 	const h = baseDims.h / panZoom.z;
diff --git a/frontend/src/lib/person/genealogy/panZoom.test.ts b/frontend/src/lib/person/genealogy/panZoom.test.ts
index e881f6a4..9b3664ae 100644
--- a/frontend/src/lib/person/genealogy/panZoom.test.ts
+++ b/frontend/src/lib/person/genealogy/panZoom.test.ts
@@ -9,6 +9,7 @@ import {
 	stepInertia,
 	recentreOn,
 	clampPan,
+	topLeftView,
 	lerpView,
 	DEFAULT_VIEW,
 	DEFAULT_ZOOM,
@@ -207,6 +208,18 @@ describe('clampPan', () => {
 	});
 });
 
+describe('topLeftView', () => {
+	it('aligns the viewBox top-left with the tree corner at the given zoom', () => {
+		expect(topLeftView(1000, 800, 2)).toEqual({ x: -250, y: -200, z: 2 });
+	});
+
+	it('sits exactly at the negative clamp limit (the corner is reachable)', () => {
+		const v = topLeftView(1000, 800, 3);
+		// clampPan must leave the corner view untouched (it is on the boundary).
+		expect(clampPan(v, 1000, 800)).toEqual(v);
+	});
+});
+
 describe('lerpView', () => {
 	const from = { x: 0, y: 0, z: 1 };
 	const to = { x: 100, y: -40, z: 2 };
diff --git a/frontend/src/lib/person/genealogy/panZoom.ts b/frontend/src/lib/person/genealogy/panZoom.ts
index b306d095..00d480a9 100644
--- a/frontend/src/lib/person/genealogy/panZoom.ts
+++ b/frontend/src/lib/person/genealogy/panZoom.ts
@@ -195,6 +195,15 @@ export function clampPan(state: PanZoomState, baseW: number, baseH: number): Pan
 	return { x: clampAxis(state.x, baseW), y: clampAxis(state.y, baseH), z: state.z };
 }
 
+/**
+ * The view whose viewBox top-left aligns with the tree's top-left corner at zoom
+ * `z` (the landing view for a fresh visit). This is the pan at the most-negative
+ * edge of the pannable range, i.e. `-clampPan` limit on each axis.
+ */
+export function topLeftView(baseW: number, baseH: number, z: number): PanZoomState {
+	return { x: (baseW / z - baseW) / 2, y: (baseH / z - baseH) / 2, z };
+}
+
 /**
  * Pan so a node sits at the viewBox centre (US-PAN-005). Because the viewBox
  * centre is `baseCentre + pan` independent of zoom, centring is a pure pan:
diff --git a/frontend/src/routes/stammbaum/+page.svelte b/frontend/src/routes/stammbaum/+page.svelte
index 1232827c..f26f1fce 100644
--- a/frontend/src/routes/stammbaum/+page.svelte
+++ b/frontend/src/routes/stammbaum/+page.svelte
@@ -140,6 +140,7 @@ $effect(() => {
 					selectedId={selectedId}
 					panZoom={view}
 					centreOnId={centreOnId}
+					anchorTopLeft={!page.url.searchParams.has('z')}
 					onPanZoom={(v) => (view = v)}
 					onActivity={() => (canvasActivity = true)}
 					onSelect={(id) => (selectedId = id)}