feat(timeline): add the event-clustering split helper

buildEventLookup maps each curated event in the (already layer-filtered)
timeline to its title; splitYearLetters partitions a year's letters into
event clusters (keyed by a linkedEventId present in the lookup) and the
loose chronological remainder. A letter linking to a filtered-out event
falls back to loose (filter-then-cluster); each letter appears once.

Refs #850

frontend/src/lib/timeline/eventClustering.spec.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect } from 'vitest';
+import { buildEventLookup, splitYearLetters, CLUSTER_PREVIEW } from './eventClustering';
+import { makeEntry } from './test-factories';
+import type { components } from '$lib/generated/api';
+
+type TimelineDTO = components['schemas']['TimelineDTO'];
+type TimelineEntryDTO = components['schemas']['TimelineEntryDTO'];
+
+const EV_A = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
+const EV_B = 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb';
+
+const makeEvent = (overrides: Partial<TimelineEntryDTO> = {}): TimelineEntryDTO =>
+	makeEntry({ kind: 'EVENT', type: 'PERSONAL', documentId: undefined, ...overrides });
+
+describe('eventClustering — buildEventLookup', () => {
+	it('maps each curated event (kind EVENT + eventId) to its title across years + undated', () => {
+		const timeline: TimelineDTO = {
+			years: [
+				{
+					year: 1916,
+					entries: [makeEvent({ eventId: EV_A, title: 'Ein gewaltiger Stadtbrand' })]
+				}
+			],
+			undated: [makeEvent({ eventId: EV_B, title: 'Briefe von der Front' })]
+		};
+		const lookup = buildEventLookup(timeline);
+		expect(lookup.get(EV_A)).toBe('Ein gewaltiger Stadtbrand');
+		expect(lookup.get(EV_B)).toBe('Briefe von der Front');
+		expect(lookup.size).toBe(2);
+	});
+
+	it('ignores derived events (no eventId) and letters', () => {
+		const timeline: TimelineDTO = {
+			years: [
+				{
+					year: 1916,
+					entries: [
+						makeEvent({ eventId: undefined, title: 'Geburt' }), // derived
+						makeEntry({ kind: 'LETTER', documentId: 'doc-1' })
+					]
+				}
+			],
+			undated: []
+		};
+		expect(buildEventLookup(timeline).size).toBe(0);
+	});
+});
+
+describe('eventClustering — splitYearLetters', () => {
+	it('exposes a CLUSTER_PREVIEW of 5', () => {
+		expect(CLUSTER_PREVIEW).toBe(5);
+	});
+
+	it('clusters letters by linkedEventId with matching counts', () => {
+		const lookup = new Map([[EV_A, 'Stadtbrand']]);
+		const letters = [
+			makeEntry({ kind: 'LETTER', documentId: 'd1', linkedEventId: EV_A }),
+			makeEntry({ kind: 'LETTER', documentId: 'd2', linkedEventId: EV_A })
+		];
+		const { clusters, loose } = splitYearLetters(letters, lookup);
+		expect(clusters).toHaveLength(1);
+		expect(clusters[0].eventId).toBe(EV_A);
+		expect(clusters[0].title).toBe('Stadtbrand');
+		expect(clusters[0].letters).toHaveLength(2);
+		expect(loose).toHaveLength(0);
+	});
+
+	it('keeps a letter with no linkedEventId loose', () => {
+		const lookup = new Map([[EV_A, 'Stadtbrand']]);
+		const letters = [makeEntry({ kind: 'LETTER', documentId: 'd1', linkedEventId: undefined })];
+		const { clusters, loose } = splitYearLetters(letters, lookup);
+		expect(clusters).toHaveLength(0);
+		expect(loose).toHaveLength(1);
+	});
+
+	it('keeps a letter whose linkedEventId is absent from the lookup loose (filter-then-cluster, REQ-008)', () => {
+		const lookup = new Map([[EV_A, 'Stadtbrand']]);
+		const letters = [makeEntry({ kind: 'LETTER', documentId: 'd1', linkedEventId: EV_B })];
+		const { clusters, loose } = splitYearLetters(letters, lookup);
+		expect(clusters).toHaveLength(0);
+		expect(loose).toHaveLength(1);
+	});
+
+	it('places each letter in exactly one place (REQ-007)', () => {
+		const lookup = new Map([[EV_A, 'Stadtbrand']]);
+		const letters = [
+			makeEntry({ kind: 'LETTER', documentId: 'd1', linkedEventId: EV_A }),
+			makeEntry({ kind: 'LETTER', documentId: 'd2', linkedEventId: undefined }),
+			makeEntry({ kind: 'LETTER', documentId: 'd3', linkedEventId: EV_B })
+		];
+		const { clusters, loose } = splitYearLetters(letters, lookup);
+		const clustered = clusters.flatMap((c) => c.letters.length).reduce((a, b) => a + b, 0);
+		expect(clustered + loose.length).toBe(3);
+		expect(clustered).toBe(1);
+		expect(loose).toHaveLength(2);
+	});
+
+	it('keeps clusters in first-seen order', () => {
+		const lookup = new Map([
+			[EV_B, 'Front'],
+			[EV_A, 'Stadtbrand']
+		]);
+		const letters = [
+			makeEntry({ kind: 'LETTER', documentId: 'd1', linkedEventId: EV_A }),
+			makeEntry({ kind: 'LETTER', documentId: 'd2', linkedEventId: EV_B })
+		];
+		const { clusters } = splitYearLetters(letters, lookup);
+		expect(clusters.map((c) => c.eventId)).toEqual([EV_A, EV_B]);
+	});
+});