Cluster event letters inline in the chronological /zeitstrahl (no grouping toggle) (#851)

Closes #850

## Summary

On `/zeitstrahl`, a curated event that has letters linked to it now renders as a contained event card — the event is the card header (accent glyph, title, `{date} · {kuratiert|abgeleitet}` subtitle, count, and a curator edit link), with its linked letters listed inside (first 5, then a keyboard-operable show-more/less toggle). Letters in a year *other* than the event's band get a lighter cross-year `✉ title` card. Every other letter stays a plain, alternating, density-folding chronological letter. There is **no grouping control** — clustering is automatic and always on. The meta-line drops its `Gruppierung: Datum` segment.

This supersedes #827: it keeps that branch's event-card clustering and the computed `linkedEventId`, and drops the toggle, the Thema mode, and the "Weitere Briefe" drawer.

## What changed

**Backend**
- `TimelineEntryDTO` gains a nullable `linkedEventId` (UUID; not `@Schema(REQUIRED)`).
- `TimelineService.resolveLetterEventLinks` resolves each letter's curated event in one batched pass over the events it already loads — no per-letter query, no new column, no Flyway migration.
- Regenerated the single `linkedEventId?` field in `api.ts`.

**Frontend**
- New `eventClustering.ts` (`buildEventLookup`, `splitYearLetters`, `CLUSTER_PREVIEW=5`) — filter-then-cluster: a letter clusters only if its `linkedEventId` is set AND present in the lookup, otherwise it stays loose.
- New `EventCluster.svelte` — the contained event card (same-year event header + edit link, or cross-year ✉ text header; first-5 + show-more).
- `LetterCard.svelte` gains `compact` + `variant='event'` (the `.lcard.ev` in-card letter).
- `YearBand.svelte` rebuilt to render event clusters inline; loose letters keep the alternating layout and density strip, and the strip counts **only** loose letters (no duplication).
- `TimelineView.svelte` builds the event lookup once and threads it + `canWrite` to each band.
- `+page.svelte` drops the grouping meta segment; the unused `timeline_grouping_date` key removed from de/en/es.
- New `timeline_bucket_show_more`/`_less` keys in all locales.
- REQ-010 `{@html}` grep gate over `lib/timeline/`.

## Tests (real runs)

- Backend `TimelineServiceTest`: **30 passed** (incl. the 2 new `linkedEventId` tests); `DerivedEventsAssemblyTest`: 17 passed; backend main sources compile.
- Frontend client sweep (`LetterCard`, `EventCluster`, `YearBand`, `TimelineView`, `zeitstrahl/page`): **81 passed** (5 files).
- Frontend server sweep (`eventClustering`, `messages`, `timeline-no-raw-html`): **18 passed** (3 files).
- `svelte-check`: no new errors in the touched files (pre-existing baseline noise elsewhere unchanged).

RTM: thirteen `REQ-001..013` rows added for #850 (feature `inline-event-clustering`), Status Done.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Marcel <marcel@familienarchiv>
Reviewed-on: #851

backend/src/main/java/org/raddatz/familienarchiv/timeline/TimelineEntryDTO.java

@@ -28,6 +28,13 @@ import java.util.UUID;
  * They are deliberately NOT {@code @Schema(requiredMode = REQUIRED)} so the generated TypeScript
  * types stay optional.
  *
+ * <p><b>Letter→event link ({@code linkedEventId}):</b> for a {@link Kind#LETTER} entry, the id of
+ * the curated {@link TimelineEvent} whose {@code documents} set contains the letter's document, or
+ * {@code null} when the letter is referenced by no curated event (#850). Computed on read from the
+ * existing {@code timeline_event_documents} join — no new column. {@code null} for non-letter
+ * entries. Deliberately NOT {@code @Schema(requiredMode = REQUIRED)} so the generated TypeScript
+ * type stays optional.
+ *
  * <p>Callers of {@code TimelineEventService.assembleDerivedEvents()} must independently enforce
  * {@code READ_ALL} authorization before invoking that method (see ADR-043).
  */
@@ -47,6 +54,7 @@ public record TimelineEntryDTO(
         DerivedEventType derivedType,
         UUID rootTagId,
         String rootTagName,
-        String rootTagColor
+        String rootTagColor,
+        UUID linkedEventId
 ) {
 }

backend/src/main/java/org/raddatz/familienarchiv/timeline/TimelineEventService.java

@@ -267,7 +267,7 @@ public class TimelineEventService {
                         p.getBirthDate(), null,
                         p.getDisplayName(), EventType.PERSONAL,
                         null, null, List.of(p.getId()), DerivedEventType.BIRTH,
-                        null, null, null))
+                        null, null, null, null))
                 .toList();
     }
 
@@ -279,7 +279,7 @@ public class TimelineEventService {
                         p.getDeathDate(), null,
                         p.getDisplayName(), EventType.PERSONAL,
                         null, null, List.of(p.getId()), DerivedEventType.DEATH,
-                        null, null, null))
+                        null, null, null, null))
                 .toList();
     }
 
@@ -304,7 +304,7 @@ public class TimelineEventService {
                         null, null,
                         List.of(r.getPerson().getId(), r.getRelatedPerson().getId()),
                         DerivedEventType.MARRIAGE,
-                        null, null, null));
+                        null, null, null, null));
             }
         }
         return result;

backend/src/main/java/org/raddatz/familienarchiv/timeline/TimelineService.java

@@ -80,13 +80,20 @@ public class TimelineService {
         // Resolve generation person IDs once — used across all three layers
         Set<UUID> genPersonIds = resolveGenerationPersonIds(filter.generation());
 
+        // Fetch curated events once; the events that survive the filter below feed both the
+        // event entries and the batched letter→event link pass (resolveLetterEventLinks), so the
+        // membership pass costs no extra query and touches only on-screen events. REQ-009.
+        List<TimelineEvent> allEvents = eventRepository.findAll();
+
         // ── curated events ───────────────────────────────────────────────────
         List<TimelineEntryDTO> entries = new ArrayList<>();
-        for (TimelineEvent ev : eventRepository.findAll()) {
+        List<TimelineEvent> filteredEvents = new ArrayList<>();
+        for (TimelineEvent ev : allEvents) {
             if (!passesTypeFilter(ev.getType(), filter.type())) continue;
             if (!passesPersonFilter(ev.getPersons(), filter.personId())) continue;
             if (!passesGenerationFilter(ev.getPersons(), genPersonIds)) continue;
             if (!passesYearFilter(ev.getEventDate(), ev.getPrecision(), filter)) continue;
+            filteredEvents.add(ev);
             entries.add(mapEvent(ev));
         }
 
@@ -107,8 +114,9 @@ public class TimelineService {
             letters.add(doc);
         }
         Map<UUID, RootTag> rootByDocId = resolveLetterRootTags(letters);
+        Map<UUID, UUID> eventByDocId = resolveLetterEventLinks(letters, filteredEvents);
         for (Document doc : letters) {
-            entries.add(mapDocument(doc, rootByDocId));
+            entries.add(mapDocument(doc, rootByDocId, eventByDocId));
         }
 
         return bucket(entries);
@@ -229,11 +237,13 @@ public class TimelineService {
                 null,
                 null,
                 null,
+                null,
                 null
         );
     }
 
-    private TimelineEntryDTO mapDocument(Document doc, Map<UUID, RootTag> rootByDocId) {
+    private TimelineEntryDTO mapDocument(Document doc, Map<UUID, RootTag> rootByDocId,
+                                         Map<UUID, UUID> eventByDocId) {
         RootTag root = rootByDocId.get(doc.getId());
         return new TimelineEntryDTO(
                 Kind.LETTER,
@@ -251,10 +261,50 @@ public class TimelineService {
                 null,
                 root == null ? null : root.id(),
                 root == null ? null : root.name(),
-                root == null ? null : root.color()
+                root == null ? null : root.color(),
+                eventByDocId.get(doc.getId())
         );
     }
 
+    /**
+     * Resolves each letter's linked curated event in one batched pass, keyed by document id: the
+     * event whose {@code documents} set contains the letter (REQ-009). A single doc→event map is
+     * built over the already-loaded events — no per-letter query ({@code TimelineEvent.documents}
+     * carries {@code @BatchSize(50)}). When a document is referenced by more than one curated
+     * event, the earliest-dated event wins (then lowest {@code eventId}); the pass runs over a
+     * stably-ordered copy so the link is a deterministic property of the data, not a coin-flip on
+     * the undefined repository iteration order ({@code putIfAbsent} keeps the first = winner). The
+     * map is built only over the events that survived the timeline filter, so the lazy
+     * {@code documents} collection is hydrated for on-screen events alone (finding #10); a letter
+     * whose only linking event was filtered out links to nothing, matching the frontend's
+     * filter-then-cluster (#850). Logs nothing — the assembly path keeps UUIDs out of logs (§2.7).
+     */
+    private Map<UUID, UUID> resolveLetterEventLinks(List<Document> letters, List<TimelineEvent> events) {
+        Set<UUID> letterDocIds = letters.stream().map(Document::getId).collect(Collectors.toSet());
+        if (letterDocIds.isEmpty()) return Map.of();
+
+        // Stable order so a multi-event letter links deterministically: earliest event date
+        // (undated last), then lowest id. putIfAbsent below then keeps the winner (REQ-009).
+        List<TimelineEvent> ordered = events.stream()
+                .sorted(Comparator
+                        .comparing(TimelineEvent::getEventDate,
+                                Comparator.nullsLast(Comparator.naturalOrder()))
+                        .thenComparing(TimelineEvent::getId))
+                .toList();
+
+        Map<UUID, UUID> eventByDocId = new HashMap<>();
+        for (TimelineEvent ev : ordered) {
+            Set<Document> linkedDocs = ev.getDocuments();
+            if (linkedDocs == null) continue;
+            for (Document linked : linkedDocs) {
+                if (letterDocIds.contains(linked.getId())) {
+                    eventByDocId.putIfAbsent(linked.getId(), ev.getId());
+                }
+            }
+        }
+        return eventByDocId;
+    }
+
     /**
      * Resolves each letter's primary root tag in one batched pass, keyed by document id — no
      * per-letter N+1: each letter contributes only its alphabetically-first assigned tag (#835),

backend/src/test/java/org/raddatz/familienarchiv/timeline/TimelineServiceTest.java

@@ -69,10 +69,10 @@ class TimelineServiceTest {
         UUID id2 = UUID.fromString("00000000-0000-0000-0000-000000000002");
         var e1 = new TimelineEntryDTO(Kind.LETTER, DatePrecision.DAY, false, "", "",
                 LocalDate.of(1914, 7, 28), null, "Same Title", null, null, id1, List.of(), null,
-                null, null, null);
+                null, null, null, null);
         var e2 = new TimelineEntryDTO(Kind.LETTER, DatePrecision.DAY, false, "", "",
                 LocalDate.of(1914, 7, 28), null, "Same Title", null, null, id2, List.of(), null,
-                null, null, null);
+                null, null, null, null);
 
         var sorted = List.of(e2, e1).stream()
                 .sorted(TimelineService.WITHIN_BAND_ORDER)
@@ -511,6 +511,106 @@ class TimelineServiceTest {
         verify(tagService, times(1)).resolveRootTags(anyList());
     }
 
+    // ─── letter→event link (#850, REQ-009) ───────────────────────────────────
+
+    @Test
+    void letter_in_a_curated_events_documents_carries_that_events_id() {
+        // REQ-009: linkedEventId = the curated event whose documents set contains the letter.
+        Document letterDoc = docWithDate(LocalDate.of(1915, 5, 1), DatePrecision.MONTH);
+        UUID eventId = UUID.randomUUID();
+        TimelineEvent event = TimelineEvent.builder().id(eventId)
+                .title("Briefe von der Front").type(EventType.PERSONAL)
+                .documents(new HashSet<>(Set.of(letterDoc)))
+                .build(); // no eventDate → event lands undated, leaving the year band to the letter
+        when(eventRepository.findAll()).thenReturn(List.of(event));
+        when(timelineEventService.assembleDerivedEvents()).thenReturn(List.of());
+        when(documentService.getAllForTimeline()).thenReturn(List.of(letterDoc));
+
+        TimelineEntryDTO entry = onlyLetterEntry(timelineService.assemble(noFilters()));
+
+        assertThat(entry.linkedEventId()).isEqualTo(eventId);
+    }
+
+    @Test
+    void letter_in_no_curated_event_has_null_linkedEventId() {
+        // REQ-009: a letter referenced by no curated event → linkedEventId null; the frontend
+        // then renders it as a loose chronological letter (REQ-006).
+        Document letterDoc = docWithDate(LocalDate.of(1915, 5, 1), DatePrecision.MONTH);
+        TimelineEvent event = TimelineEvent.builder().id(UUID.randomUUID())
+                .title("Anderes Ereignis").type(EventType.PERSONAL)
+                .documents(new HashSet<>(Set.of(Document.builder().id(UUID.randomUUID()).build())))
+                .build();
+        when(eventRepository.findAll()).thenReturn(List.of(event));
+        when(timelineEventService.assembleDerivedEvents()).thenReturn(List.of());
+        when(documentService.getAllForTimeline()).thenReturn(List.of(letterDoc));
+
+        TimelineEntryDTO entry = onlyLetterEntry(timelineService.assemble(noFilters()));
+
+        assertThat(entry.linkedEventId()).isNull();
+    }
+
+    @Test
+    void multi_event_letter_links_deterministically_to_the_earliest_event() {
+        // REQ-009: a document referenced by >1 curated event links to the earliest-dated event
+        // (then lowest id), independent of repository iteration order — not a coin-flip on
+        // findAll()'s undefined order.
+        Document shared = docWithDate(LocalDate.of(1916, 5, 1), DatePrecision.MONTH);
+        TimelineEvent earlier = TimelineEvent.builder()
+                .id(UUID.fromString("00000000-0000-0000-0000-000000000001"))
+                .title("Frühes Ereignis").type(EventType.PERSONAL)
+                .eventDate(LocalDate.of(1913, 3, 1)).precision(DatePrecision.MONTH)
+                .documents(new HashSet<>(Set.of(shared)))
+                .build();
+        TimelineEvent later = TimelineEvent.builder()
+                .id(UUID.fromString("00000000-0000-0000-0000-000000000002"))
+                .title("Spätes Ereignis").type(EventType.PERSONAL)
+                .eventDate(LocalDate.of(1914, 3, 1)).precision(DatePrecision.MONTH)
+                .documents(new HashSet<>(Set.of(shared)))
+                .build();
+        when(timelineEventService.assembleDerivedEvents()).thenReturn(List.of());
+        when(documentService.getAllForTimeline()).thenReturn(List.of(shared));
+
+        // `later` first in iteration: a naive putIfAbsent would wrongly pick it.
+        when(eventRepository.findAll()).thenReturn(List.of(later, earlier));
+        assertThat(theLetter(timelineService.assemble(noFilters())).linkedEventId())
+                .isEqualTo(earlier.getId());
+
+        // Reversed order yields the same winner — the link is order-independent.
+        when(eventRepository.findAll()).thenReturn(List.of(earlier, later));
+        assertThat(theLetter(timelineService.assemble(noFilters())).linkedEventId())
+                .isEqualTo(earlier.getId());
+    }
+
+    @Test
+    void letter_linked_only_to_a_filtered_out_event_has_null_linkedEventId() {
+        // finding #10: the link pass runs over the events that survived the filter, not all of
+        // them. A letter whose only linking event is excluded by the active filter links to
+        // nothing (the frontend would drop it loose anyway) — and the lazy `documents` collection
+        // is never hydrated for events that are off-screen.
+        Document letterDoc = docWithDate(LocalDate.of(1916, 5, 1), DatePrecision.MONTH);
+        TimelineEvent worldEvent = TimelineEvent.builder().id(UUID.randomUUID())
+                .title("Somme").type(EventType.HISTORICAL)
+                .documents(new HashSet<>(Set.of(letterDoc)))
+                .build();
+        when(eventRepository.findAll()).thenReturn(List.of(worldEvent));
+        when(timelineEventService.assembleDerivedEvents()).thenReturn(List.of());
+        when(documentService.getAllForTimeline()).thenReturn(List.of(letterDoc));
+
+        // Filter to PERSONAL only → the HISTORICAL event is filtered out of the view.
+        TimelineEntryDTO entry = theLetter(timelineService.assemble(
+                new TimelineFilter(null, null, EventType.PERSONAL, null, null)));
+
+        assertThat(entry.linkedEventId()).isNull();
+    }
+
+    private static TimelineEntryDTO theLetter(TimelineDTO result) {
+        return java.util.stream.Stream.concat(
+                        result.years().stream().flatMap(y -> y.entries().stream()),
+                        result.undated().stream())
+                .filter(e -> e.kind() == Kind.LETTER)
+                .findFirst().orElseThrow();
+    }
+
     private static TimelineEntryDTO onlyLetterEntry(TimelineDTO result) {
         assertThat(result.years()).hasSize(1);
         return result.years().get(0).entries().get(0);
@@ -523,7 +623,7 @@ class TimelineServiceTest {
     private static TimelineEntryDTO letter(LocalDate date, DatePrecision precision, String title) {
         return new TimelineEntryDTO(Kind.LETTER, precision, false, "", "",
                 date, null, title, null, null, UUID.randomUUID(), List.of(), null,
-                null, null, null);
+                null, null, null, null);
     }
 
     private static Document docWithDate(LocalDate date, DatePrecision precision) {