Skip to content

Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.

159 KB
Raw Blame
/**
 * Die Galaxie als Panel, und der Fokus, der in beide Richtungen laeuft.
 *
 * Die Szene selbst ist uebernommen (src/galaxy/GraphScene.tsx, MIT, DeusData);
 * diese Datei ist das, was dieses Projekt daraus macht. Sie haelt fuenf
 * Entscheidungen, und jede davon ist eine Antwort auf eine Frage, die man beim
 * Lesen sofort stellt:
 *
 * 1. **Das Panel laedt selbst.** Nicht die App: `/api/layout` ist die einzige
 *    Route, die dieses Panel braucht, und niemand sonst im Haus braucht sie.
 *    Ein Fehler wird gezeigt, nicht verschluckt (src/galaxy/layout-source.ts).
 *    Was geladen wurde, meldet das Panel nach oben (`onLayout`), weil die
 *    Bedeutungssuche daraus ihre Fan-in-Zahlen nimmt und der Server sie in der
 *    flachen Suchform nicht mitschickt.
 * 2. **Einmal sichtbar heisst gemountet.** Wird das Panel zugeklappt, bleibt
 *    die Szene im Baum und nur der Renderloop steht still (`active`). Ein
 *    Aushaengen wuerde den WebGL-Kontext wegwerfen, und der naechste Aufklapper
 *    zahlte dafuer mit Sekunden und einem schwarzen Kasten.
 * 3. **Die Kamera faehrt bei neuer Objekt-Identitaet.** So ist der
 *    CameraAnimator der Uebernahme gebaut: `useEffect([target])`. Also wird
 *    fuer jede Fahrt ein frisches Ziel gerechnet, auch wenn es zweimal
 *    dasselbe Symbol ist, und der Zaehler `targetChanges` im Testgriff zaehlt
 *    genau diese frischen Ziele.
 * 4. **Ein Symbol ohne Knoten sagt das.** Der Deckel liegt bei 5000 Knoten;
 *    was darueber liegt, ist nicht im Bild. Ein stiller No-op waere die
 *    Behauptung, das Symbol sei gezeigt worden.
 * 5. **Unter dem Kopf steht, was man sieht.** Die Legende (W4d, Nutzerfeedback)
 *    erklaert Knotenfarbe, Knotengroesse, Kantenfarben, Fokus und Positionen,
 *    und zwar aus den Quellen, die sie erzeugen: src/galaxy/galaxy-legend.ts.
 *    Sie ist auf- und zuklappbar, weil dieses Panel 420 Pixel hoch ist und ein
 *    Leser, der die Erklaerung gelesen hat, den Platz wiederhaben will; der
 *    Zustand liegt im localStorage, damit die Entscheidung den Reload
 *    ueberlebt.
 *
 * Seit W4e zeigt dasselbe Panel zwei Bilder, und daraus kommen vier weitere
 * Entscheidungen:
 *
 * 6. **Ein Canvas, zwei Datensaetze.** Der Chip-Schalter tauscht die Daten der
 *    Szene und nicht die Szene. Ein zweites `<Canvas>` waere ein zweiter
 *    WebGL-Kontext, und ein bedingtes Aushaengen waere derselbe schwarze
 *    Kasten wie in Entscheidung 2, nur bei jedem Umschalten.
 * 7. **Die Hierarchie ist die Vorgabe, sobald es einen Walk gibt.** Wer sich
 *    fuer einen Einstiegspunkt entschieden hat, hat eine Frage nach der Tiefe
 *    gestellt, und die Wolke beantwortet sie nicht. Ein Klick auf `galaxy`
 *    holt das alte Bild zurueck, und diese Wahl haelt die Sitzung: sie ist
 *    eine Antwort und keine Geste. Ohne Walk gibt es nichts zu projizieren,
 *    also steht der Schalter dann auf `galaxy` und der andere Chip sagt, was
 *    ihm fehlt.
 * 8. **Die Kamera rahmt den ganzen Subgraphen, nicht den Schritt.** Genau
 *    darum geht es in dieser Ansicht: man soll die Tiefe SEHEN. Eine Kamera,
 *    die bei jedem Schritt auf eine Spalte zoomt, zeigt wieder nur die
 *    Nachbarschaft, also faehrt sie einmal je Projektion und danach bewegt
 *    sich nur noch der Ring.
 * 9. **Der Ring ist DOM und keine Geometrie.** Der Schritt, auf dem der Leser
 *    steht, bekommt einen pulsenden Ring ueber seinem Punkt (`Html` aus drei
 *    der Uebernahme, dieselbe Technik wie die Hover-Karte). Ihn aus Dreiecken
 *    zu bauen hiesse, bei jedem Schritt die Puffer der Szene neu zu bauen und
 *    fuer die Animation bei jedem Bild.
 *
 * Seit W9 ist die Legende auch der Filter, und daraus kommen zwei weitere:
 *
 * 10. **Gefiltert wird zwischen Bild und Szene, nicht in der Szene.** Das Panel
 *     rechnet aus der geladenen Antwort zuerst das BILD (in der Hierarchie samt
 *     der Beziehungen, die der Index ausser den Aufrufen kennt) und reicht der
 *     Szene davon nur die Arten weiter, die sichtbar sein sollen. Die Szene
 *     kennt keinen Filter, die Legende zaehlt am Bild und nicht am Gefilterten,
 *     und beide Ansichten teilen sich denselben Satz ausgeblendeter Arten:
 *     wer in der Galaxie die Importe weggenommen hat, findet sie in der
 *     Hierarchie nicht wieder.
 * 11. **Der Nachbarschafts-Fokus rechnet weiter am ganzen Bild.** Ein Klick
 *     hebt die Nachbarn eines Symbols hervor, und Nachbar ist, wen der Index
 *     nennt, nicht wen der Filter gerade durchlaesst. Sonst waere dieselbe
 *     Frage je nach Filterlage anders beantwortet, ohne dass die Antwort das
 *     sagt.
 * 12. **Die Legende zeigt ihre Kante.** Der Kasten ist niedriger als sein
 *     Inhalt, und der Bildlauf dieser Plattform ist eine ueberlagernde Leiste,
 *     die im Ruhezustand nicht zu sehen ist. Ohne einen eigenen Hinweis endet
 *     der letzte sichtbare Satz darum an einer harten Kante mitten im Wort, und
 *     das liest sich als Fehler und nicht als Fortsetzung. Das Panel misst
 *     deshalb selbst, ob ueber oder unter dem Kasten noch etwas steht, und sagt
 *     es: ein Verlauf loest die Kante auf, eine Marke nennt die Richtung.
 *
 * Seit W11a liegt eine dritte Ebene ueber demselben Canvas, und daraus kommen
 * drei weitere Entscheidungen:
 *
 * 13. **Die Agentenebene faerbt nichts um.** Sie haengt als `overlay` in
 *     derselben Szene und legt eigene Koerper ueber die Punkte; kein Knoten und
 *     keine Kante aendert dabei ihre Farbe. Warum das die einzige vertretbare
 *     Form ist, steht im Kopf von src/galaxy/AgentLayer.tsx.
 * 14. **Verortet wird HIER, weil hier das Layout liegt.** Ein Ereignis nennt
 *     einen Pfad und manchmal Zeilen; welcher Knoten das ist, weiss nur, wer die
 *     Layout-Antwort hat. Die Rechnung steht in src/agents/agent-view.ts und
 *     wird EINMAL gemacht: die Ebene zeichnet aus demselben Ergebnis, aus dem
 *     das Instrument seine Zeilen schreibt.
 * 15. **Der Leser ist ein Akteur wie die anderen.** Oeffnet er ein Symbol,
 *     entsteht hier ein Ereignis mit dem Namen "you", das durch dieselbe Ebene
 *     laeuft. Es geht NICHT in die Ereignisdatei: die Bruecke hat keine Route,
 *     die etwas entgegennimmt, und dieses Ereignis verlaesst das Fenster nie.
 *
 * Seit W10b kommen drei Entscheidungen aus vier Nutzerbefunden dazu:
 *
 * 16. **Die beiden Ansichts-Knoepfe klappen auch.** Ein Klick auf den AKTIVEN
 *     Knopf klappt die Sektion zu, ein Klick bei zugeklappter Sektion klappt sie
 *     auf und waehlt diese Ansicht. Das ist die Antwort auf den Befund "galaxy
 *     Knopf macht nichts" (2026-08-29) und auf den Auftrag vom Folgetag: "die
 *     beiden Buttons unten links sollten auch aufklappen und zuklappen koennen."
 *     Der beschriftete Ein- und Ausklapper daneben bleibt, und beide Wege gehen
 *     durch DENSELBEN Rueckruf: zwei Wege in denselben Zustand duerfen nicht
 *     zwei Zustaende ergeben.
 * 17. **Die Hierarchie waechst auch aus dem Fokus, waehlt sich aber nicht
 *     selbst.** Bis W10b gab es sie nur nach einem Einstiegs-Spaziergang, und
 *     ein Leser mit einem Symbol vor sich sah einen grauen Knopf (Befund
 *     2026-08-30). Der Walk aus dem Fokus kommt von aussen (`focusWalk`), weil
 *     nur die App einen Provider hat; er hat denselben Vorwaerts-Closure und
 *     dieselben Grenzen. Die VORGABE bleibt trotzdem die Galaxie: ein Fokus
 *     entsteht bei jedem Klick in den Code, und eine Ansicht, die dabei von
 *     selbst umschaltet, waere ein Bild, das der Leser nie bestellt hat. Der
 *     Kopf sagt, woher die Wurzel kommt.
 * 18. **Die Kamera passt das Bild ein, sofort und nicht im Anflug.** Beim
 *     Oeffnen, beim Aufklappen, bei einer neuen Groesse der Zeichenflaeche und
 *     auf Knopfdruck steht sie senkrecht auf der groessten Flaeche der Wolke,
 *     weit genug weg, dass JEDER Knoten im Bild liegt (src/galaxy/camera-frame.ts).
 *     Ohne Anflug, weil eine Einpassung keine Bewegung ist, sondern die Lage, in
 *     der das Bild anfaengt. In der Hierarchie bleibt es bei der frontalen
 *     Rahmung aus W5c: sie ist eine flache Zeichnung mit Spalten, und eine
 *     Kamera, die deren Hauptachsen folgt, stellte das Raster schief.
 */

import type { JSX, ReactNode } from 'react';
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
import { GALAXY_NODE_LIMITS, GALAXY_EDGE_LIMITS, useViewPreferences } from '../settings/view-preferences';
import { Html } from '@react-three/drei';

import { GraphScene, computeCameraTarget, computeFitTarget, computeFrameTarget } from './GraphScene';
import type { CameraTarget } from './GraphScene';
import type { LabelBox } from './NodeLabels';
import { NodeTooltipCard } from './NodeTooltipCard';
import { HoverCardHtml } from './hover-layer';
import GalaxyNavigator from './GalaxyNavigator';
import { TraceEdgeFilter } from './TraceEdgeFilter';
import { PathPicker, PathSteps } from './ScopePathControls';
import { callOrder, pathNodes, shortestScopePath, type ScopePathStep } from './scope-path';
import { galaxyHierarchyNoteText, galaxyHierarchyText, galaxyHistoryText, galaxyLayerText, galaxyPathText, galaxyToolbarText } from './galaxy-strings';
import { graphNodeName, nodeFilePath, scopeDisplayName, scopeTitle } from './node-names';
import { HierarchyBandLabel, HierarchyEdgeLabels } from './HierarchyEdgeLabels';
import { FitLabel, useToolbarFit } from './toolbar-fit';
import { emptyNavigationHistory, moveNavigation, peekNavigation, pushNavigation } from '../graph/navigation-history';
import { useDismissibleMenu } from '../graph/use-dismissible-menu';
import { galaxyHistoryOptions, historyEntryDetail, historyEntryLabel, scopeIdentity, type GalaxyHistoryEntry, type ScopeTrail } from './scope-history';
import { useOrganicLayout } from './use-organic-layout';
import RenderProgress from './RenderProgress';
import { useGraphScope } from './use-graph-scope';
import { SCOPED_HIERARCHY_LABEL_BUDGET, SCOPED_HIERARCHY_LABEL_MAX_TEXT_WIDTH, expandPastLimit, hierarchyLabelWidth, limitGraphRender, nextLayerEstimate, scenePictureFor, scopedHierarchy, type ExpandOutlook } from './graph-scope';
import './graph-exploration.css';
import { layoutNodeForSelection } from './selected-node';
import { galaxyScopeEvidence, useSelectionEvidence, type SelectionEvidenceListener } from './selection-evidence';
import { buildCoverageShadow } from './coverage-shadow';
import type { CoverageShadowNode } from './coverage-shadow';
import {
    GALAXY_NO_FOCUS_NOTE,
    LAYOUT_NODE_BUDGET,
    layoutSummary,
    missingNodeNote,
    neighbourIds,
    nodesByQualifiedName,
    unopenableNodeNote,
} from './galaxy-model';
import { loadLayout } from './layout-source';
import { DEFAULT_DISPLAY_SETTINGS, DEFAULT_GRAPH_DISPLAY, displayWith } from './density';
import type { DisplaySettings, GraphDisplaySettings } from './density';
import {
    edgeKindNote,
    edgeKinds,
    galaxyLegendEntries,
    hierarchyLegendEntries,
    readLegendOpen,
    withoutEdgeKinds,
    writeLegendOpen,
} from './galaxy-legend';
import type { EdgeKind } from './galaxy-legend';
import {
    HIERARCHY_LABEL_BUDGET,
    HIERARCHY_LABEL_FONT_SIZE,
    HIERARCHY_LABEL_MAX_TEXT_WIDTH,
    hierarchyEdgeNote,
    hierarchyFrame,
    hierarchyHeadline,
    hierarchyIndexEdges,
    projectHierarchy,
} from './hierarchy-layout';
import type { HierarchyRootOrigin } from './hierarchy-layout';
import type { ClosureResult } from '../provider/closure';
import type { HierarchyStatus } from './selection-hierarchy';
import { readerFocusFrame, readerGraphFocus, type SourceFocusRange } from './reader-graph-focus';
import { projectReaderHierarchy } from './reader-hierarchy';
import Hint from '../ui/tooltip/Hint';
import type { GraphData, GraphNode } from './types';
import type { SelectionScope } from '../why/SelectionContext';
import {
    AgentLayer,
    agentAngles,
    agentCamera,
    agentMotion,
    agentPositions,
    agentPulseScale,
    agentRenderOrders,
    agentTails,
    orbitRadii,
} from './AgentLayer';
import AgentsHud from '../agents/AgentsHud';
import type { HudSwitches } from '../agents/AgentsHud';
import AgentsTimeline from '../agents/AgentsTimeline';
import { YOU_ID } from '../agents/agent-colors';
import { workKindOf } from '../agents/agent-event';
import { buildPlacementIndex } from '../agents/agent-placement';
import { buildAgentsView } from '../agents/agent-view';
import type { ActorFilter, ActorView, HudSize } from '../agents/agent-view';
import { stateUntil } from '../agents/agent-store';
import { buildTimeline, TIMELINE_MIN_WIDTH } from '../agents/agent-timeline';
import { DRAWN_BODIES_CAP, TRANSITION_MS } from '../agents/agent-motion';
import { WORK_KIND_WORD, agentStrings as agentText } from '../agents/agent-strings';
import type { AgentsRuntime } from '../agents/agent-source';
import { loadAgentsPreference, saveAgentsPreference } from '../agents/agent-preference';
import type { AgentsPreference } from '../agents/agent-preference';
import { fullscreenIsolationRequired, isolateFullscreenBackground } from './fullscreen-isolation';
import { isTypingTarget } from '../app/keyboard';

/**
 * Wie lange die Ereigniszeile des FOLLOW-Modus stehen bleibt.
 *
 * Lang genug, um sie zu lesen, kurz genug, dass sie nicht zur Beschriftung des
 * Bildes wird: sie gehoert zu einem Anflug, der vorbei ist.
 */
export const FOLLOW_LINE_MS = 4000;

/** Welches der beiden Bilder das Panel gerade zeigt. */
export type GraphMode = 'galaxy' | 'hierarchy';

/** Die beiden Chips, in der Reihenfolge, in der sie im Kopf stehen. */
export const GRAPH_MODES: readonly GraphMode[] = ['galaxy', 'hierarchy'];

/*
 * Was der `hierarchy`-Chip sagt, solange es weder Walk noch Fokus gibt, und
 * was das Panel sagt, wenn kein Knoten des Walks im Reader offen ist, stehen
 * seit Runde 4 (N2) in galaxy-strings.ts (`galaxyHierarchyNoteText`). Seit
 * W10b nennt der Chip BEIDE Wege (AC3): ein offenes Symbol genuegt, ein
 * gewaehlter Start ist der andere Weg; im Galaxy-Tab ist es ein gewaehlter
 * Knoten.
 */

/**
 * Wie die Szene im hierarchy-Modus eingestellt ist.
 *
 * Bloom aus und der Knotenglanz halbiert, und das ist die Antwort auf einen
 * Befund und keine Vorliebe (Nutzerfeedback 2026-08-29, Screenshots): das
 * Leuchten ist die Sprache der Galaxie, wo tausende Punkte eine Wolke bilden
 * und der Glanz die Dichte lesbar macht. Hier stehen hoechstens sechzig Punkte
 * in einem Raster, und dieselbe Nachbearbeitung macht aus jedem Namen einen
 * Fleck. Die Antwort dieser Ansicht ist Struktur und nicht Glanz.
 */
export const HIERARCHY_DISPLAY: DisplaySettings = {
    ...DEFAULT_DISPLAY_SETTINGS,
    bloom: 0,
    nodeGlow: 0.5,
};

/** Der Schalter im Panel-Kopf, in beiden Lagen. */
export const GALAXY_COLLAPSE_TITLE = 'hide the graph panel: the header stays, so it can be brought back';
export const GALAXY_EXPAND_TITLE = 'show the graph panel again';

/**
 * Wie der Zuklapp-Schalter heisst, und warum er ein Wort traegt statt eines
 * Zeichens.
 *
 * Bis W8b stand dort `[-]` beziehungsweise `[+]`, und was sie bedeuten, stand
 * nur im Tooltip. Der Nutzer hat es beim Testen am 2026-08-29 nicht verstanden
 * und woertlich gefordert: "wenn Galaxy aufgeklappt ist, sollte 'einklappen
 * Galaxy' auf Englisch stehen, und wenn Galaxy geschlossen ist 'open Galaxy',
 * analog zu hierarchy." Das ist die Auskunft, die zaehlt.
 *
 * Der Name folgt dabei dem, was gerade ZU SEHEN ist, und nicht dem Panel:
 * dasselbe Panel zeigt zwei Bilder, und "collapse galaxy" ueber einer
 * Hierarchie waere ein Schalter, der ein anderes Bild verspricht als das, das
 * er zumacht.
 */
export function graphFoldLabel(open: boolean, mode: GraphMode): string {
    return `${open ? 'collapse' : 'open'} ${mode}`;
}

/**
 * Was der Schalter der Legende sagt. Dieselbe Regel, kuerzere Woerter.
 *
 * "hide" und "show" statt "collapse" und "open", und das ist genau der Weg, den
 * AC3 fuer diesen Fall nennt: "Passt das Wort in einer engen Spalte nicht, wird
 * die Spalte breiter oder das Wort kuerzer, nicht das Zeichen wieder
 * eingesetzt." Vier Zeichen weniger sind hier der Unterschied zwischen einer
 * Kopfzeile mit einer Zeile und einer mit zwei, und zwei Zeilen ueber einem
 * Canvas kosten die Szene ihre Hoehe. Der Zustand steht weiter im Wort, und das
 * ist die Zusicherung, um die es geht.
 */
export function legendFoldLabel(open: boolean): string {
    return `${open ? 'hide' : 'show'} legend`;
}

/**
 * Was der aktive Ansichts-Chip sagt, wenn man ihn beruehrt.
 *
 * Nutzerbefund vom 2026-08-29: "galaxy Knopf macht nichts". W8b hat den Satz
 * ehrlich gemacht ("diese Ansicht laeuft schon"), und der Nutzer hat am Tag
 * darauf gesagt, was er stattdessen will: "die beiden Buttons unten links
 * sollten auch aufklappen und zuklappen koennen." Seit W10b tut der aktive Knopf
 * also etwas, und der Satz sagt beides: dass diese Ansicht schon dasteht, und
 * was ein Klick jetzt bewirkt.
 */
export function graphModeActiveTitle(mode: GraphMode): string {
    return `${mode} is already showing: click to fold the graph away`;
}

/** Was ein Chip sagt, solange die Sektion zugeklappt ist. */
export function graphModeCollapsedTitle(mode: GraphMode): string {
    return `open the graph again and show ${mode}`;
}

/**
 * Was die Einpassung sagt, und warum sie ein Knopf und keine Automatik ist.
 *
 * Die Kamera passt das Bild von selbst ein, sobald es entsteht oder die Flaeche
 * sich aendert (Entscheidung 18 im Kopf). Danach gehoert sie dem Leser: er
 * dreht, zieht und zoomt, und nichts darf ihm dabei ins Steuer greifen. Nach
 * zehn Sekunden Ziehen weiss aber niemand mehr, wie es angefangen hat, und
 * genau dafuer ist dieser Knopf da (Nutzerbefund 2026-08-30, AC5).
 */
export const GALAXY_FIT_LABEL = 'fit view';
export const GALAXY_FIT_TITLE =
    'put the whole graph back in the picture: the camera stands square on its widest side, '
    + 'far enough away that every node fits';

/** Der Griff, an dem der Beweislauf die Projektion anfasst. */
export interface AtlasHierarchySeam {
    /** Die Identitaet der Wurzel, also des gewaehlten Einstiegspunkts. */
    root: string;
    /** Ihr Anzeigename. */
    rootName: string;
    /** Wie viele Symbole im Bild stehen. */
    nodes: number;
    /** Wie viele Ebenen es hat, die Wurzel als erste. */
    depth: number;
    truncated: boolean;
    cap: number;
    walkDepth: number;
    /** Je Knoten: Schluessel, Name, Datei, Hop und die gezeichnete Position. */
    placements: { key: string; name: string; file: string; hop: number; x: number; y: number; side?: -1 | 0 | 1; mixed?: boolean }[];
    /** Zweites Review zu K5: das Band der gemischt erreichten Knoten und wer Namen traegt. */
    band?: { count: number; x: number; y: number; left: number; right: number; bottom: number };
    names?: 'all' | 'neighbours' | 'none';
    /** Die gezeichneten Kanten, in den Schluesseln des Walks. */
    edges: { from: string; to: string }[];
    /** Wie viele Linien aus dem Walk stammen. */
    walkEdges: number;
    /** Wie viele Beziehungen die Layout-Antwort dazugelegt hat. */
    extraEdges: number;
    /** Je dazugelegte Beziehung: Art, Enden und Spur. */
    extras: { type: string; from: string; to: string; offset: number }[];
}

/** Der Griff, an dem der Beweislauf die Galaxie anfasst. */
export interface AtlasGalaxySeam {
    /** Wie viele Knoten geladen sind. Null heisst: noch keine Antwort. */
    nodes: number;
    /** Wie oft ein frisches Kameraziel gesetzt wurde, also wie oft geflogen wurde. */
    targetChanges: number;
    /** Wie viele Knoten gerade hervorgehoben sind. */
    highlightedCount: number;
    /** Der qualifizierte Name des zuletzt angeflogenen Knotens. */
    lastTargetQn: string;
    /**
     * Einen Knoten anklicken, ohne Maus.
     *
     * Ausdruecklich ein Testgriff und nichts anderes: ein Klick auf eine
     * WebGL-Szene ist ein Raycast, und ein Beweislauf, der auf Pixel zielt,
     * misst die Kameraposition und nicht den Klickpfad. Der Griff ruft genau
     * den Weg, den auch die Maus ruft, und faengt nichts ab. Er gilt fuer das
     * Bild, das gerade dasteht.
     */
    clickNode: (qualifiedName: string) => boolean;
    /** Ob die Legende gerade offen ist. */
    legendOpen: boolean;
    /** Wie viele Elemente sie erklaert. */
    legendEntries: number;
    /**
     * Die Bloom-Staerke, mit der die Szene gerade laeuft.
     *
     * Genau der Wert, den die Szene bekommt, und nicht ein zweiter daneben: der
     * Beweislauf liest daran, dass die Hierarchie ohne das Leuchten der Galaxie
     * gezeichnet wird.
     */
    bloom: number;
    /**
     * Die Namenskaesten, so wie die Szene sie wirklich gezeichnet hat, in
     * Weltkoordinaten.
     *
     * Gemeldet und nicht nachgerechnet: was ein Name einnimmt, weiss nur die
     * Ebene, die ihn in eine Textur schreibt. Alle Knoten dieser Ansicht liegen
     * auf z=0 und die Kamera steht frontal davor, also ist eine Ueberlappung
     * dieser Rechtecke genau eine Ueberlappung auf dem Schirm.
     */
    labelBoxes: LabelBox[];
    /** Welches Bild dasteht. */
    mode: GraphMode;
    /** Ob die Sektion aufgeklappt ist. Zugeklappt zeigt sie keines der Bilder. */
    open: boolean;
    /** Ob es einen Walk gibt, den man zeigen koennte. */
    hierarchyAvailable: boolean;
    /** Woher die Wurzel der Hierarchie kommt: aus einem Walk oder aus dem Fokus. */
    hierarchyOrigin: HierarchyRootOrigin | '';
    /**
     * Wie oft die Kamera das Bild eingepasst hat.
     *
     * Der Beweislauf liest daran, DASS eingepasst wurde; WO die Knoten danach
     * liegen, misst er an `globalThis.__atlasGalaxyFit` in der Szene selbst.
     */
    fits: number;
    /** Was bei der letzten Einpassung gerechnet wurde. Leer, solange keine lief. */
    lastFit: {
        mode: GraphMode;
        /** `principal` in der Galaxie, `frontal` in der flachen Hierarchie. */
        kind: string;
        aspect: number;
        nodes: number;
        distance: number;
        width: number;
        height: number;
        depth: number;
        normal: [number, number, number];
        up: [number, number, number];
        /** Worauf die Kamera sieht: in einem Scope die Wurzel. */
        center?: [number, number, number];
    } | undefined;
    /** Genau der Satz, der im Kopf steht. */
    headline: string;
    /** Der Knoten, um den der Ring laeuft. Leer, wenn keiner. */
    pulsedQn: string;
    /** Die Projektion, so wie sie gezeichnet wuerde. Fehlt ohne Walk. */
    hierarchy: AtlasHierarchySeam | undefined;
    /**
     * Die Kantenarten des gezeigten Bildes, gezaehlt, mit Farbe und Lage.
     *
     * Genau die Liste, aus der die Legende ihre Zeilen macht: der Beweislauf
     * soll die Zeilen gegen die geladene Antwort halten koennen, ohne dass eine
     * zweite Zaehlung daneben entsteht.
     */
    edgeKinds: (EdgeKind & { hidden: boolean })[];
    /** Welche Arten gerade aus dem Bild genommen sind. */
    hiddenKinds: string[];
    /** Wie viele Kanten die Szene nach dem Filter wirklich bekommt. */
    drawnEdges: number;
    /** Die zweite Kopfzeile: woraus die Linien bestehen und was fehlt. */
    edgeNote: string;
    /** Der Verlauf aus Zurueck und Vor (K2): Eintraege als Tooltip-Text, der Zeiger, die letzten Wurzeln. */
    history: { index: number; entries: string[]; recent: string[] };
}

/** Ein Akteur, so wie der Beweislauf ihn liest. */
export interface AtlasAgentSeamActor {
    id: string;
    name: string;
    you: boolean;
    color: string;
    letter: string;
    kind: string;
    kindLetter: string;
    placement: string;
    uncertain: boolean;
    nodeId: number;
    qualifiedName: string;
    placeName: string;
    why: string;
    ghosts: number[];
    testedNodeId: number;
    intent: string;
    count: number;
    missed: number;
    strip: number[];
    paths: string[];
    lastTool: string;
    lastPath: string;
    lastLines: number[];
    /** Der Winkel aus dem Bild, in dem dieser Griff geschrieben wurde. */
    angle: number;
    /** Ob dieser Akteur seit ueber einer Minute nichts geliefert hat. */
    idle: boolean;
    /** Wie lange sein letztes Ereignis her ist. */
    sinceMs: number;
    /** Wie viele Ereignisse er im Pulsfenster geliefert hat. */
    recentEvents: number;
    /** Die Dauer eines Atemzugs. `0` heisst: er atmet nicht. */
    pulseMs: number;
    /** Der Ausschlag des Pulses. `0` heisst derselbe Satz. */
    pulseAmplitude: number;
    /** Die Knoten seiner Spur, neuester zuerst. */
    trail: number[];
    /** Ob sein Koerper gezeichnet wird, oder ob der Deckel ihn zurueckhaelt. */
    drawn: boolean;
}

/** Der Griff, an dem der Beweislauf die Agentenebene anfasst. */
export interface AtlasAgentSeam {
    on: boolean;
    layerOn: boolean;
    sourceState: string;
    origin: string;
    /** Wie viele Anfragen an die Bruecke gingen. Aus heisst: null. */
    requests: number;
    drops: number;
    mode: string;
    file: string;
    error: string;
    port: number;
    events: number;
    missed: number;
    perMinute: number;
    unreadable: number;
    size: string;
    filter: string;
    follow: boolean;
    trails: boolean;
    /** Das Vollbild. Hiess bis W11b `cinema` (Nutzerwunsch 2026-08-30). */
    fullscreen: boolean;
    trailWindowMs: number;
    /** Wie viele Akteure der Umschalter gerade durchlaesst. */
    shown: number;
    /** Der Deckel gezeichneter Koerper, und was er zurueckhaelt. */
    cap: number;
    capped: number;
    drawn: number;
    /** Wie lange ein Ortswechsel dauert, in Millisekunden. */
    transitionMs: number;
    /** Welche teuren Wirkungen gerade eingeschaltet sind. */
    effects: { tails: boolean; trails: boolean; waves: boolean; timeline: boolean };
    /** Der Zeitstrahl, so wie er dasteht. */
    timeline: {
        mode: string;
        from: number;
        to: number;
        windowMs: number;
        tracks: number;
        ticks: number;
        shown: boolean;
        width: number;
    } | undefined;
    /** Wohin die FOLLOW-Kamera zuletzt geschickt wurde. */
    follow_: {
        nodeId: number;
        actor: string;
        position: [number, number, number];
        at: number;
    } | undefined;
    /** Die Bahnradien der gezeichneten Koerper. */
    radii: Record<string, number>;
    /** Die Weltposition jedes Koerpers aus dem zuletzt gezeichneten Bild. */
    positions: Record<string, { x: number; y: number; z: number }>;
    /** Wie gross jeder Koerper in jenem Bild gezeichnet wurde. */
    pulses: Record<string, number>;
    /** Wie viele Punkte der Schweif jedes Koerpers gerade traegt. */
    tails: Record<string, number>;
    /** Der letzte Flug je Akteur, mit allen aufgezeichneten Punkten. */
    motion: Record<string, unknown>;
    /** Wo die Kamera stand. */
    camera: { position: { x: number; y: number; z: number }; at: number };
    /** Die Zeichenreihenfolgen: die Spur, und die kleinste aller anderen. */
    renderOrders: {
        trail: number;
        others: number;
        objects: number;
        trails: number;
        dash: [number, number];
    };
    /** Die Schreib-Brueche, die gerade eine Welle tragen. */
    waves: { actor: string; key: string; nodeId: number; events: number; from: number; to: number }[];
    /** Die Zeilen des Ereignis-Tickers, woertlich. */
    ticker: {
        ts: number;
        actor: string;
        kind: string;
        place: string;
        lines: number[];
        text: string;
    }[];
    actors: AtlasAgentSeamActor[];
    unmapped: { ts: number; agent: string; tool: string; path: string; detail: string; why: string }[];
    /**
     * Die Winkel, LEBEND.
     *
     * Ein Verweis auf dieselbe Tabelle, die die Ebene in jedem Bild schreibt
     * (src/galaxy/AgentLayer.tsx). Die Zahl in `actors[].angle` ist die aus dem
     * Bild, in dem dieser Griff geschrieben wurde, und damit alt, sobald der
     * naechste Rahmen laeuft; wer die Bewegung messen will, liest hier.
     */
    angles: Record<string, number>;
}

declare global {
    // eslint-disable-next-line no-var
    var __atlasGalaxy: AtlasGalaxySeam | undefined;
    // eslint-disable-next-line no-var
    var __atlasAgents: AtlasAgentSeam | undefined;
}

export interface GalaxyPanelProps {
    /** Fill the workspace while leaving navigation and local chat interactive. */
    workspaceExpanded?: boolean;
    /** Select graph evidence, including nodes without a source file. */
    onSelectNode?: ((node: GraphNode) => void) | undefined;
    onSelectShadowNode?: ((node: CoverageShadowNode) => void) | undefined;
    selectedNode?: GraphNode | undefined;
    onClearSelection?: () => void;
    onSelectionEvidence?: SelectionEvidenceListener;
    /** Das Projekt, dessen Layout gezeigt wird. Leer heisst: nichts laden. */
    project: string;
    /** Ob das Panel im Layout sichtbar ist. */
    visible: boolean;
    /** Der qualifizierte Name des Twin-Subjekts, dem die Kamera folgt. */
    focusQualifiedName?: string | undefined;
    /** Der Anzeigename desselben Subjekts, fuer die ehrliche Fehlanzeige. */
    focusName?: string | undefined;
    focusFilePath?: string;
    focusSourceRange?: SourceFocusRange;
    /** Ein angeklickter Knoten mit Datei. Die App oeffnet ihn und folgt ihm. */
    onOpenNode: (node: GraphNode) => void;
    /** Was geladen wurde, fuer die Aufrufer, die es brauchen. */
    onLayout?: ((data: GraphData) => void) | undefined;
    /** Ersetzbares fetch, damit Tests ohne Netz laufen. */
    fetch?: typeof globalThis.fetch | undefined;
    /**
     * Der laufende Vorwaerts-Walk, wenn einer laeuft.
     *
     * Der Walk selbst und nicht die daraus gebaute Fuehrung: die Fuehrung hat
     * die Symbole ohne Datei schon weggelassen, weil ein Schritt, den man nicht
     * oeffnen kann, kein Schritt ist. Fuer das Bild gilt das nicht, dort ist so
     * ein Symbol ein Punkt wie jeder andere, und ihn wegzulassen hiesse, eine
     * Kette kuerzer zu zeichnen, als der Index sie kennt.
     */
    walk?: ClosureResult | undefined;
    /**
     * Der Vorwaerts-Walk aus dem Symbol im Fokus (W10b, AC3).
     *
     * Von aussen und nicht hier gerechnet: ein Closure braucht den Provider, und
     * den hat die App. Er gilt nur, solange kein echter Walk laeuft; ein
     * Einstiegs-Spaziergang ist eine Entscheidung des Lesers und schlaegt einen
     * Ort, an dem er zufaellig steht.
     */
    focusWalk?: ClosureResult | undefined;
    focusWalkStatus?: HierarchyStatus;
    focusWalkMessage?: string;
    /**
     * Der Zaehler, mit dem die App eine Einpassung anfordert (W10b, AC5).
     *
     * Eine Zahl und kein Rueckruf, weil es eine Aufforderung ist und kein
     * Zustand: "reset layout" bringt jede Zone auf ihre Vorgabe zurueck, und
     * seit W10b gehoert die eingepasste Ansicht des Graphen dazu. Jede neue Zahl
     * ist eine neue Aufforderung.
     */
    refit?: number;
    /**
     * Der qualifizierte Name des Schrittes, auf dem die Fuehrung gerade steht.
     *
     * Nur als Rueckfall: der Ring folgt dem Symbol vor dem Leser, und das ist
     * `focusQualifiedName`. Steht dort etwas, das gar nicht im Walk vorkommt,
     * sagt dieser Wert trotzdem noch, wo die Fuehrung steht.
     */
    stepQualifiedName?: string | undefined;
    /**
     * Der Speicher fuer den Klappzustand der Legende.
     *
     * Von aussen setzbar, damit ein Test ihn ersetzen kann, ohne globale
     * Objekte zu verbiegen. Fehlt er, wird der localStorage dieses Fensters
     * genommen; gibt es auch den nicht, gilt der Vorgabewert und die
     * Entscheidung haelt eine Sitzung lang.
     */
    legendStore?: Storage | undefined;
    /**
     * Das Panel zu- und wieder aufklappen.
     *
     * Von aussen, weil derselbe Zustand am [a]tlas-Menuepunkt haengt und zwei
     * Schalter fuer eine Lage zwei Lagen waeren. Fehlt der Rueckruf, steht kein
     * Schalter im Kopf: ein Knopf, der nichts tut, ist schlimmer als keiner.
     */
    onToggleVisible?: (() => void) | undefined;
    /**
     * Was der Leser im Einstellungen-Panel eingestellt hat (W10).
     *
     * Von aussen, weil es von aussen entschieden wird: der Nutzerwunsch vom
     * 2026-08-29 war ausdruecklich, dass alles, was Rechenzeit kostet, an EINEM
     * Ort steht. Ein zweiter Satz Schalter hier waere genau der zweite Ort.
     * Fehlt die Angabe, zeichnet das Panel wie vor W10.
     */
    display?: GraphDisplaySettings | undefined;
    /**
     * Der laufende Ereignisstrom der Agenten (W11a).
     *
     * Fehlt er, gibt es weder Koerper noch Instrument, und das Panel zeichnet
     * genau wie vor W11a. Er wird von aussen gefuehrt, weil der Live-Modus eine
     * Entscheidung des ganzen Fensters ist (Menue und Kommandozeile) und nicht
     * eine dieses Panels.
     */
    agents?: AgentsRuntime | undefined;
    /**
     * Ob die Agentenebene ueberhaupt gezeichnet wird.
     *
     * Aus der Darstellungs- und Leistungsgruppe der Einstellungen (W10 AC9), wie
     * jeder andere Schalter, der Rechenzeit kostet. Aus heisst: keine Koerper,
     * keine Pings, keine Linien; das Instrument bleibt und sagt es.
     */
    agentLayer?: boolean;
    /**
     * Was von den teuren Wirkungen der Agentenebene gezeichnet wird (W11b AC7b).
     *
     * Aus derselben Gruppe des Einstellungen-Panels wie `agentLayer`, und aus
     * demselben Grund: was Rechenzeit kostet, steht an EINEM Ort. Fehlt die
     * Prop, ist alles an.
     */
    agentEffects?: {
        tails: boolean;
        trails: boolean;
        waves: boolean;
        timeline: boolean;
    } | undefined;
    /**
     * Ob eine andere Flaeche die Escape-Taste gerade braucht.
     *
     * Die App weiss, was ueber dem Panel liegt (Hilfe, Einstiegsdialog,
     * Suchfenster, Einstellungen); dieses Panel weiss es nicht. Ohne die Auskunft
     * naehme der Vollbildmodus die Taste an sich und stuende damit VOR Flaechen,
     * die es laenger gibt. Die Reihenfolge ist eine Zusicherung dieser
     * Oberflaeche, und sie bleibt gueltig.
     */
    escapeTaken?: boolean;
    /**
     * Der Zaehler, mit dem die Kommandozeile das Vollbild umlegt (W11b).
     *
     * Dieselbe Form wie `refit`: die Wahl liegt hier, weil sie hier gespeichert
     * wird; was von aussen kommt, ist die Bitte.
     */
    fullscreenToggle?: number;
    /** Der Speicher fuer die Lage des Instruments. Ersetzbar fuer Tests. */
    agentStore?: Storage | undefined;
    /**
     * "Selection details". As a function it receives the loaded scope (hand
     * test K13): the relationships of the selection then come from what this
     * panel loaded, not from the capped repository snapshot.
     */
    selectionPanel?: ReactNode | ((scope: SelectionScope | undefined) => ReactNode);
}

/**
 * Bis zu wie vielen Knoten ein Ausschnitt auf dem Schirm auseinandergeschoben
 * wird (Handtest K8). Die Trennung hebt Namen und Ringe kleiner Ausschnitte aus
 * der Wolke; eine dichte Wolke aus tausenden Knoten (die dritte Ebene um
 * JSONBAgg) schob sie dagegen zu einem Kreuz aus langen Linien auseinander.
 */
export const SCOPE_SEPARATION_LIMIT = 1500;

/** Wie lange die Zeitangaben im Instrument stehen, bis sie neu gerechnet werden. */
export const AGENT_TICK_MS = 1000;

export default function GalaxyPanel(props: GalaxyPanelProps): JSX.Element {
    const {
        project,
        visible,
        focusQualifiedName,
        focusName,
        onOpenNode,
        onLayout,
        walk,
        stepQualifiedName,
    } = props;

    const [layout, setData] = useState<GraphData | undefined>(undefined);
    const [layoutLoading, setLayoutLoading] = useState(false);
    const [spacingBusy, setSpacingBusy] = useState(false);
    const { preferences: viewPreferences, setPreferences: setViewPreferences } = useViewPreferences(project);
    const { galaxyNodes: nodeBudget, galaxyEdges: edgeBudget, coverageShadow: showCoverage } = viewPreferences;
    const [traceFilter, setTraceFilter] = useState<{ project: string; types?: string[] }>({ project });
    const traceTypes = props.workspaceExpanded && traceFilter.project === project ? traceFilter.types : undefined;
    const changeTraceTypes = useCallback((types: string[] | undefined) => setTraceFilter({ project, types }), [project]);
    const scope = useGraphScope({ project, layout,
        filePath: props.workspaceExpanded ? undefined : props.focusFilePath,
        range: props.focusSourceRange, fetch: props.fetch, edgeTypes: traceTypes,
        // Handtest K8: eine Ebene ueber dem Render-Limit haelt dort an, statt minutenlang weiterzuladen.
        ...(props.workspaceExpanded ? { limits: { nodes: nodeBudget, edges: edgeBudget } } : {}) });
    const organicHistory = useRef<{ key: string; depth: number; data: GraphData } | undefined>(undefined);
    const organicKey = JSON.stringify([project, scope.scope, scope.direction, traceTypes]);
    const organicOptions = useMemo(() => {
        const previous = organicHistory.current;
        return { rootIds: scope.result?.roots,
            previous: previous?.key === organicKey && previous.depth <= scope.depth ? previous.data : undefined };
    }, [scope.result, scope.scope, organicKey, scope.depth]);
    const organicTask = useOrganicLayout(scope.scope ? scope.result?.data : undefined, organicOptions);
    const organic = organicTask.result;
    useEffect(() => {
        if (scope.complete && organic) organicHistory.current = { key: organicKey, depth: scope.depth, data: organic.data };
        if (!scope.scope) organicHistory.current = undefined;
    }, [scope.complete, scope.scope, organic, organicKey, scope.depth]);
    const data = scope.scope ? organic?.data : layout;
    /*
     * Was die Szene zeigt, solange das naechste Bild noch angeordnet wird.
     *
     * Bis hierher war `data` waehrend jeder Anordnung leer, die Szene wurde
     * ausgehaengt, und jeder Schritt (Auswahl, Expand, Vorschau zu Antwort)
     * baute den Canvas neu auf (Review-Befund G1). Jetzt bleibt das letzte Bild
     * stehen, bis das neue fertig ist; vor dem ersten Bild eines Scopes ist das
     * der ganze Graph, der gerade noch zu sehen war. `data` bleibt dabei das
     * AKTUELLE Bild: Einpassung, Legende und Zaehler rechnen nie mit dem alten.
     */
    const sceneData = scope.scope ? scenePictureFor(organic?.data, organicTask.stale?.data, layout) : layout;
    const sceneScoped = Boolean(scope.scope) && sceneData !== layout;
    const scopedRoot = scope.result?.roots.size === 1
        ? scope.result.data.nodes.find(node => scope.result!.roots.has(node.id)) : undefined;
    const notifiedScopedSymbol = useRef('');
    useEffect(() => {
        if (scope.scope?.kind !== 'symbol') { notifiedScopedSymbol.current = ''; return; }
        if (!scope.complete || !scopedRoot) return;
        const identity = `${project}:${scope.scope.qualifiedName}`;
        if (notifiedScopedSymbol.current === identity) return;
        notifiedScopedSymbol.current = identity;
        props.onSelectNode?.(scopedRoot);
    }, [scope.scope, scope.complete, scopedRoot, project, props.onSelectNode]);
    const [error, setError] = useState('');
    useEffect(() => { if (organicTask.error) setError(organicTask.error); }, [organicTask.error]);
    const [note, setNote] = useState(GALAXY_NO_FOCUS_NOTE);
    const [highlighted, setHighlighted] = useState<Set<number> | null>(null);
    const [cameraTarget, setCameraTarget] = useState<CameraTarget | null>(null);

    /*
     * Die Wahl des Lesers, oder nichts.
     *
     * Nichts heisst "noch nichts gewaehlt" und nicht "galaxy": nur so kann die
     * Vorgabe der Lage folgen (Walk da: hierarchy, sonst galaxy), ohne eine
     * getroffene Entscheidung zu ueberschreiben.
     */
    const [chosenMode, setChosenMode] = useState<GraphMode | undefined>(undefined);

    /*
     * Die Kantenarten, die der Leser aus dem Bild genommen hat (W9).
     *
     * Im Zustand dieses Panels und nicht im Speicher des Browsers: eine
     * ausgeblendete Art ist eine Frage an DIESES Bild ("wie sieht es ohne die
     * Definitionen aus"), keine Einstellung. Sie haelt die Sitzung und den
     * Wechsel zwischen den beiden Ansichten, und sie ist nach einem Reload
     * wieder weg, damit niemand vor einem Bild sitzt, dem ohne sein Wissen
     * etwas fehlt.
     */
    const [hiddenKinds, setHiddenKinds] = useState<ReadonlySet<string>>(() => new Set<string>());

    /*
     * Die Zeichenflaeche, gemessen statt geraten.
     *
     * Die Rahmung der Hierarchie braucht das Seitenverhaeltnis: ein breites
     * Panel braucht fuer dieselbe Breite weniger Abstand als ein schmales. Ein
     * fester Wert waere eine Kamera, die nur bei einer Fensterbreite stimmt.
     */
    const scene = useRef<HTMLDivElement | null>(null);
    const panel = useRef<HTMLElement | null>(null);
    const [aspect, setAspect] = useState(1.3);
    /*
     * Die Breite der Zeichenflaeche, in Pixeln.
     *
     * Der Zeitstrahl haengt daran und nicht an einem Modus: unter
     * {@link TIMELINE_MIN_WIDTH} Pixeln waere eine Spur ueber fuenfzehn Minuten
     * ein Strich, in dem kein Ereignis mehr von seinem Nachbarn zu unterscheiden
     * ist, und eine Anzeige, die genauer aussieht als das Bild, das sie zeigt,
     * ist eine Behauptung. Gemessen statt geraten, damit die Grenze nachlesbar
     * ist.
     */
    const [sceneWidth, setSceneWidth] = useState(0);
    const labelBoxes = useRef<LabelBox[]>([]);
    const onLabelLayout = useCallback((boxes: LabelBox[]) => {
        labelBoxes.current = boxes;
    }, []);

    useEffect(() => {
        const node = scene.current;
        if (node === null) {
            return;
        }
        const measure = (): void => {
            setSceneWidth(node.clientWidth);
            if (node.clientHeight > 0) {
                setAspect(node.clientWidth / node.clientHeight);
            }
        };
        measure();
        if (typeof ResizeObserver === 'undefined') {
            return;
        }
        const observer = new ResizeObserver(measure);
        observer.observe(node);
        return () => observer.disconnect();
    }, []);

    /*
     * Der Klappzustand der Legende, einmal aus dem Speicher gelesen.
     *
     * Als Initialisierer und nicht als Effekt: ein Effekt wuerde die Legende
     * beim ersten Bild in der Vorgabelage zeigen und im zweiten umschalten,
     * und ein Kasten, der beim Laden von selbst zuklappt, sieht aus wie ein
     * Fehler.
     */
    const legendStore = props.legendStore
        ?? (typeof localStorage === 'undefined' ? undefined : localStorage);
    const [legendOpen, setLegendOpen] = useState(() => readLegendOpen(legendStore));

    const toggleLegend = useCallback(() => {
        setLegendOpen((open) => {
            writeLegendOpen(legendStore, !open);
            return !open;
        });
    }, [legendStore]);

    /*
     * Die Kante der Legende, gemessen: steht ueber oder unter dem Kasten noch
     * etwas?
     *
     * Der Befund aus dem Beweisbild von W9 (Bernhard, 2026-08-29): der Kasten
     * ist niedriger als sein Inhalt, sein Bildlauf ist auf dieser Maschine eine
     * ueberlagernde Leiste, die im Ruhezustand unsichtbar ist, und damit endete
     * der letzte sichtbare Satz mitten im Wort an einer harten Kante. Das sieht
     * aus wie ein Darstellungsfehler und nicht wie ein Anfang.
     *
     * Gemessen und nicht geraten, weil beide Antworten falsch waeren, wenn man
     * sie fest verdrahtet: ein Hinweis, der immer dasteht, luegt bei einer
     * kurzen Legende, und einer, der nie dasteht, ist der Befund. Der Zustand
     * haengt an drei Dingen, und alle drei koennen sich ohne die anderen
     * aendern: am Bildlauf (der Leser scrollt), an der Groesse des Kastens (das
     * Fenster aendert sich) und am Inhalt (die Ansicht wechselt, eine Art
     * kommt dazu).
     */
    const legendBox = useRef<HTMLDivElement | null>(null);
    const [legendEdge, setLegendEdge] = useState({ above: false, below: false });

    const measureLegendEdge = useCallback(() => {
        const node = legendBox.current;
        if (node === null) {
            return;
        }
        const above = node.scrollTop > 1;
        const below = node.scrollTop + node.clientHeight < node.scrollHeight - 1;
        setLegendEdge((edge) =>
            (edge.above === above && edge.below === below ? edge : { above, below }));
    }, []);

    /* ------------------------------------------------ die Agentenebene (W11a) */

    /*
     * Die Lage des Instruments, einmal aus dem Speicher gelesen.
     *
     * Als Initialisierer und nicht als Effekt, aus demselben Grund wie bei der
     * Legende: ein Kasten, der beim Laden von selbst zuklappt, sieht aus wie ein
     * Fehler.
     */
    const agentStore = props.agentStore
        ?? (typeof localStorage === 'undefined' ? undefined : localStorage);
    const [agentPreference, setAgentPreference] = useState<AgentsPreference>(
        () => loadAgentsPreference(agentStore, project),
    );
    const changeAgentPreference = useCallback((patch: Partial<AgentsPreference>) => {
        setAgentPreference((current) =>
            saveAgentsPreference(agentStore, project, { ...current, ...patch }));
    }, [agentStore, project]);

    /*
     * Und noch einmal, wenn das Projekt ankommt.
     *
     * Der Initialisierer oben laeuft beim ersten Bild, und da steht der
     * Projektname noch nicht immer fest (er kommt aus der Adresszeile und wird
     * von der App durchgereicht). Der Schluessel haengt aber am Projekt: ohne
     * dieses zweite Lesen bekaeme ein Leser, der das Instrument eingeklappt hat,
     * nach dem Reload wieder die Vorgabe, und die gespeicherte Entscheidung
     * waere eine, die niemand je zurueckliest.
     */
    useEffect(() => {
        if (project.length === 0) {
            return;
        }
        setAgentPreference(loadAgentsPreference(agentStore, project));
    }, [agentStore, project]);

    /*
     * Die Bitte der Kommandozeile um das Vollbild.
     *
     * Am Zaehler und nicht am Wert: zwei Orte fuer denselben Zustand waeren zwei
     * Wahrheiten darueber, ob das Bild gerade das ganze Fenster fuellt. Der
     * erste Wert zaehlt nicht als Bitte, sonst legte jedes Laden den Modus um.
     */
    const fullscreenAsked = props.fullscreenToggle ?? 0;
    const lastFullscreenAsk = useRef(fullscreenAsked);
    useEffect(() => {
        if (fullscreenAsked === lastFullscreenAsk.current) {
            return;
        }
        lastFullscreenAsk.current = fullscreenAsked;
        setAgentPreference((current) =>
            saveAgentsPreference(agentStore, project, {
                ...current,
                fullscreen: !current.fullscreen,
            }));
    }, [fullscreenAsked, agentStore, project]);

    /*
     * Die Uhr des Instruments.
     *
     * Die Zeitangaben ("here for 12s") und der Aktivitaetsstreifen der letzten
     * dreissig Sekunden haengen an der Gegenwart und nicht an einem Ereignis.
     * Ohne einen eigenen Takt blieben sie stehen, sobald der Strom eine Pause
     * macht, und ein Streifen, der beim Schweigen einfriert, waere ein Bild
     * ueber eine Zeit, die nicht vergangen ist. Der Takt laeuft nur, solange es
     * ueberhaupt einen Strom gibt.
     */
    const [agentNow, setAgentNow] = useState(() => Date.now());
    const agentsOn = props.agents !== undefined;

    /*
     * Ob der Live-Modus AN ist.
     *
     * Zwei verschiedene Fragen, und sie duerfen nicht zusammenfallen:
     * `props.agents` heisst "es gibt einen Strom, den man fuehren koennte",
     * `props.agents.on` heisst "der Leser sieht gerade zu". Ist der Modus aus,
     * gibt es weder Koerper noch Instrument: es gibt nichts zu erklaeren, und
     * ein Kasten in der Ecke, der bei jedem Laden "der Live-Modus ist aus"
     * sagt, nimmt dem Graphen dauerhaft eine Ecke fuer eine Auskunft, die schon
     * im Menue steht.
     */
    const liveOn = props.agents?.on === true;
    useEffect(() => {
        if (!agentsOn) {
            return;
        }
        setAgentNow(Date.now());
        const timer = window.setInterval(() => setAgentNow(Date.now()), AGENT_TICK_MS);
        return () => window.clearInterval(timer);
    }, [agentsOn]);

    // Der Zaehler und der letzte Zielname wandern durch Refs, weil sie
    // Beobachtungen ueber den Ablauf sind und nichts zeichnen.
    const targetChanges = useRef(0);
    const lastTargetQn = useRef('');

    // Einmal sichtbar, immer gemountet: siehe Entscheidung 2 im Kopf.
    const everVisible = useRef(false);
    if (visible) {
        everVisible.current = true;
    }

    const fetchImpl = props.fetch;

    useEffect(() => {
        if (project.length === 0) {
            setLayoutLoading(false);
            return;
        }
        let cancelled = false;
        setError('');
        setLayoutLoading(true);
        loadLayout(project, { ...(fetchImpl === undefined ? {} : { fetch: fetchImpl }), maxNodes: props.workspaceExpanded ? nodeBudget : LAYOUT_NODE_BUDGET })
            .then((loaded) => {
                if (cancelled) {
                    return;
                }
                setData(loaded);
                if (onLayout !== undefined) {
                    onLayout(loaded);
                }
            })
            .catch((failure: unknown) => {
                if (cancelled) {
                    return;
                }
                setData(undefined);
                setError(failure instanceof Error ? failure.message : String(failure));
            }).finally(() => { if (!cancelled) setLayoutLoading(false); });
        return () => {
            cancelled = true;
        };
    }, [project, fetchImpl, onLayout, nodeBudget, props.workspaceExpanded]);

    /*
     * Der Walk als Bild.
     *
     * Haengt am Walk UND am geladenen Layout, weil Farbe und Groesse von dort
     * kommen, wo das Layout das Symbol kennt. Kommt das Layout spaeter an,
     * faerbt sich das Bild nach und die Kamera rahmt es noch einmal; die
     * Positionen aendern sich dabei nicht, die haengen nur am Walk.
     */
    /*
     * Der Walk, aus dem das Bild entsteht: der echte, sonst der aus dem Fokus.
     *
     * In dieser Reihenfolge, und das ist Entscheidung 17 im Kopf: ein
     * Einstiegs-Spaziergang ist eine Entscheidung ("hier fange ich an"), ein
     * Fokus ist ein Ort ("hier stehe ich gerade"). Laeuft ein Spaziergang, ist
     * er gemeint, auch wenn der Leser darin gerade woanders hinsieht.
     */
    const activeWalk = walk ?? props.focusWalk;
    const readerHierarchyActive = !props.workspaceExpanded && walk === undefined && Boolean(props.focusFilePath);
    const readerProjection = useMemo(() => readerHierarchyActive && data
        ? projectReaderHierarchy(data, props.focusFilePath!, props.focusSourceRange, Number.MAX_SAFE_INTEGER, scope.depth > 1) : undefined,
    [readerHierarchyActive, data, props.focusFilePath, props.focusSourceRange, scope.depth]);
    const hierarchyOrigin: HierarchyRootOrigin = walk !== undefined ? 'walk'
        : readerHierarchyActive ? 'file' : 'focus';

    const scopedProjection = useMemo(() => props.workspaceExpanded && scope.scope && scope.result
        ? scopedHierarchy(scope.result, scope.scope.name) : undefined, [props.workspaceExpanded, scope.scope, scope.result]);
    /*
     * Review zu K5: bis 150 Knoten stehen in der Hierarchie eines Ausschnitts
     * alle Namen. Darueber behalten die Wurzel und ihre direkten Nachbarn ihre
     * Namen und Kantenschilder (zweites Review), und erst eine Wurzel mit mehr
     * Nachbarn als das hat keine; eine Notiz im Bild sagt es.
     */
    const scopedNames = scopedProjection?.names ?? 'all';
    const scopedNeighbours = useMemo(() => scopedProjection?.placements.filter(placement => placement.hop === 1).length ?? 0, [scopedProjection]);
    const scopedNamedIds = useMemo(() => scopedProjection?.namedIds ? new Set(scopedProjection.namedIds) : undefined, [scopedProjection]);
    const scopedNamedSides = useMemo(() => {
        const sides = { root: false, incoming: 0, outgoing: 0 };
        for (const placement of scopedProjection?.placements ?? []) {
            if (!scopedNamedIds?.has(placement.id)) continue;
            if (placement.hop === 0) sides.root = true;
            else if (placement.hop === 1 && placement.side === -1) sides.incoming += 1;
            else if (placement.hop === 1 && placement.side === 1) sides.outgoing += 1;
        }
        return sides;
    }, [scopedProjection, scopedNamedIds]);
    const scopedSpots = useMemo(() => scopedProjection
        ? new Map(scopedProjection.placements.map(placement => [placement.id, { hop: placement.hop, x: placement.x, y: placement.y }])) : undefined,
    [scopedProjection]);
    const projection = useMemo(
        () => scopedProjection ?? (readerHierarchyActive ? readerProjection
            : activeWalk === undefined ? undefined : projectHierarchy(activeWalk, { layout: data })),
        [scopedProjection, readerHierarchyActive, readerProjection, activeWalk, data],
    );

    /*
     * Was dasteht, wenn niemand gewaehlt hat.
     *
     * Ein WALK schaltet um, ein Fokus nicht. Wer einen Einstiegspunkt gewaehlt
     * hat, hat nach der Tiefe gefragt, und die Wolke antwortet nicht darauf
     * (Entscheidung 7). Ein Fokus dagegen entsteht bei jedem Klick in den Code;
     * eine Ansicht, die dabei von selbst wechselt, waere ein Bild, das niemand
     * bestellt hat, und der Leser haette den Ueberblick verloren, ohne etwas
     * dafuer zu tun.
     */
    const mode: GraphMode = chosenMode ?? (walk === undefined ? 'galaxy' : 'hierarchy');

    /*
     * Was der Index ausser den Aufrufen zwischen den gezeigten Symbolen kennt.
     *
     * Haengt an der Projektion UND am geladenen Layout, weil es von dort kommt.
     * Ohne Layout ist die Liste leer, und die Hierarchie zeigt genau das, was
     * sie vor W9 gezeigt hat.
     */
    const indexEdges = useMemo(
        () => (readerHierarchyActive || scopedProjection || projection === undefined ? [] : hierarchyIndexEdges(projection, data)),
        [readerHierarchyActive, scopedProjection, projection, data],
    );

    /*
     * Das Bild, bevor der Filter darueber geht.
     *
     * Es ist die Grundlage fuer drei Dinge, die alle dieselbe Antwort brauchen:
     * die Legende (was gibt es), die Nachbarschaft (wer haengt woran) und der
     * Kopf (wie viel steht da). Die Szene bekommt danach die gefilterte
     * Fassung, und nur sie.
     */
    const picture = useMemo(() => {
        if (mode !== 'hierarchy') {
            return data;
        }
        if (projection === undefined) return undefined;
        return indexEdges.length === 0
            ? projection.data
            : { ...projection.data, edges: [...projection.data.edges, ...indexEdges] };
    }, [mode, projection, indexEdges, data]);

    const kinds = useMemo(() => edgeKinds(picture), [picture]);
    const hiddenHere = kinds.filter((kind) => hiddenKinds.has(kind.type)).length;
    const kindNote = edgeKindNote(kinds.length, hiddenHere);

    /*
     * Die Szene bekommt in der Galaxie das stehende Bild (siehe `sceneData`).
     * Steht dort noch der ganze Graph, gelten auch seine ausgeblendeten
     * Kantenarten weiter; erst ein Scope-Bild filtert ueber `traceTypes`.
     * `shown` ist nur das AKTUELLE Bild: Kantenfilter, Zaehler und Auskunft an
     * den Chat rechnen nie mit dem Platzhalter.
     */
    const scenePicture = mode === 'hierarchy' ? picture : sceneData;
    const sceneShown = useMemo(
        () => {
            if (!scenePicture) return undefined;
            const traced = props.workspaceExpanded && scope.scope && (mode === 'hierarchy' || sceneScoped);
            const filtered = traced ? scenePicture : withoutEdgeKinds(scenePicture, hiddenKinds);
            const requiredNames = new Set(data?.nodes.filter(node => scope.result?.roots.has(node.id)).map(node => node.qualified_name));
            return props.workspaceExpanded ? limitGraphRender(filtered, nodeBudget, edgeBudget, mode === 'hierarchy'
                ? new Set(filtered.nodes.filter(node => requiredNames.has(node.qualified_name)).map(node => node.id))
                : scope.result?.roots) : filtered;
        },
        [scenePicture, hiddenKinds, props.workspaceExpanded, nodeBudget, edgeBudget, scope.result?.roots, scope.scope, mode, data, sceneScoped],
    );
    const shown = mode === 'hierarchy' || sceneData === data ? sceneShown : undefined;

    const traceKinds = useMemo(() => edgeKinds(shown), [shown]);
    const agentEvidence = useMemo(() => scope.scope ? galaxyScopeEvidence({ project, identity: scope.scope,
        nodes: scope.result?.data.nodes ?? [], edges: scope.result?.data.edges ?? [], roots: scope.result?.roots ?? new Set<number>(),
        depth: scope.depth, direction: props.workspaceExpanded ? scope.direction : 'both', edgeTypes: traceTypes ?? 'all',
        // A layer that stopped at the render limit is loaded, not complete: the chat says so (C1).
        state: scope.complete ? scope.result?.partial ? 'render-limit-partial' : 'complete-indexed-scope' : scope.loading ? 'loading-partial-preview' : 'partial',
        error: scope.error, exhausted: scope.result?.exhausted,
        ...scope.complete && scope.result?.partial ? { renderLimit: { layer: scope.result.partial.layer, kind: scope.result.partial.limit,
            limit: scope.result.partial.limit === 'nodes' ? nodeBudget : edgeBudget } } : {},
        // Which picture is shown, so the chat can say how to read it (H1).
        display: mode }) : undefined,
    [project, scope.scope, scope.result, scope.depth, scope.direction, scope.complete, scope.loading, scope.error, traceTypes, props.workspaceExpanded, nodeBudget, edgeBudget, mode]);
    useSelectionEvidence(props.onSelectionEvidence, agentEvidence, visible && props.workspaceExpanded === true);
    const toggleKind = useCallback((type: string) => {
        if (props.workspaceExpanded && scope.scope) {
            const next = new Set(traceTypes ?? kinds.map(kind => kind.type));
            if (!next.delete(type)) next.add(type);
            changeTraceTypes([...next].sort());
            return;
        }
        setHiddenKinds((hidden) => {
            const next = new Set(hidden);
            if (!next.delete(type)) next.add(type);
            return next;
        });
    }, [props.workspaceExpanded, scope.scope, traceTypes, kinds, changeTraceTypes]);

    const renderLimits = <>
        <label>Nodes <select aria-label="Rendered node limit" value={nodeBudget} onChange={event => setViewPreferences({ galaxyNodes: Number(event.target.value) })}>
            {GALAXY_NODE_LIMITS.map(value => <option key={value} value={value}>{value.toLocaleString()}</option>)}
        </select></label>
        <label>Edges <select aria-label="Rendered edge limit" value={edgeBudget} onChange={event => setViewPreferences({ galaxyEdges: Number(event.target.value) })}>
            {GALAXY_EDGE_LIMITS.map(value => <option key={value} value={value}>{value.toLocaleString()}</option>)}
        </select></label>
    </>;

    /*
     * Der Pfad und die Aufrufreihe (Review-Befund G5, nach dem Vorbild von
     * Graphify).
     *
     * Beide rechnen nur auf dem, was dieser Scope schon geladen hat, und in der
     * Richtung, in der er verfolgt wird: der Server wird nicht gefragt, und ein
     * fehlender Pfad heisst "nicht in diesen Beziehungen", nicht "gibt es
     * nicht". Der Abstand ist hier die Zahl der Hops und nur hier (G6); die
     * Wolke selbst behauptet keinen. Die Wahl haengt am Scope (`organicKey`):
     * eine neue Wurzel, Richtung oder Kantenart verwirft sie, ein Expand
     * rechnet sie auf dem groesseren Bild neu. Verworfen heisst verworfen: wer
     * die Richtung zurueckstellt oder dieselbe Wurzel neu waehlt, bekommt den
     * alten Pfad nicht ungefragt wieder. Das Ziel behaelt seinen Namen, auch
     * wenn ein entfernter Layer es aus dem Bild nimmt.
     */
    const [trail, setTrail] = useState<{ key: string; kind: 'path'; target: number; name: string } | { key: string; kind: 'calls' }>();
    const [trailStep, setTrailStep] = useState(0);
    useEffect(() => {
        setTrail(current => (current && current.key !== organicKey ? undefined : current));
        setTrailStep(0);
    }, [organicKey]);
    const trailRoot = scope.result?.roots.size === 1 ? [...scope.result.roots][0] : undefined;
    const rootCalls = useMemo(() => (data && trailRoot !== undefined ? callOrder(data.edges, trailRoot) : []), [data, trailRoot]);
    const pathCandidates = useMemo(() => data?.nodes.filter(node => !scope.result?.roots.has(node.id)) ?? [], [data, scope.result]);
    const trailView = useMemo(() => {
        // Handtest K5: Pfad und Aufrufreihe auch in der Hierarchie eines Ausschnitts.
        if (!props.workspaceExpanded || (mode !== 'galaxy' && !scopedProjection) || trail?.key !== organicKey || !data || !scope.result) return undefined;
        const names = new Map(data.nodes.map(node => [node.id, graphNodeName(node)]));
        const nameOf = (id: number) => names.get(id) ?? `#${id}`;
        if (trail.kind === 'calls') {
            return { nameOf, lines: true, labels: 'active' as const, steps: rootCalls,
                heading: galaxyPathText.callsHeading(trailRoot === undefined ? '' : nameOf(trailRoot), rootCalls.length) };
        }
        const steps: ScopePathStep[] | undefined = shortestScopePath(data.edges, scope.result.roots, trail.target, scope.direction);
        const target = names.get(trail.target) ?? trail.name;
        return { nameOf, lines: false, labels: 'all' as const, steps: steps ?? [],
            heading: galaxyPathText.pathHeading(target, steps?.length ?? 0),
            note: steps === undefined ? galaxyPathText.noPath(target) : steps.length === 0 ? galaxyPathText.isRoot(target) : undefined };
    }, [props.workspaceExpanded, mode, trail, organicKey, data, scope.result, scope.direction, rootCalls, trailRoot]);
    const trailActive = trailView ? Math.min(trailStep, Math.max(0, trailView.steps.length - 1)) : 0;
    const trailIds = useMemo(() => trailView?.steps.length && scope.result ? pathNodes(trailView.steps, scope.result.roots) : undefined,
        [trailView, scope.result]);
    /*
     * Die Hierarchie zeichnet mit eigenen IDs (K5). Der Pfad rechnet im Scope und
     * wird fuer ihr Bild umgeschrieben, damit Linien, Ring und Abdunkeln an den
     * Knoten liegen, die dort zu sehen sind.
     */
    const hierarchyIds = useMemo(() => mode === 'hierarchy' && scopedProjection?.sourceIds
        ? new Map(scopedProjection.sourceIds.map((source, id) => [source, id])) : undefined, [mode, scopedProjection]);
    const sceneTrailIds = useMemo(() => !trailIds || !hierarchyIds ? trailIds
        : new Set([...trailIds].flatMap(id => hierarchyIds.get(id) ?? [])), [trailIds, hierarchyIds]);
    const scenePathSteps = useMemo(() => {
        if (!trailView) return undefined;
        if (!hierarchyIds) return trailView.steps;
        return trailView.steps.flatMap(step => {
            const from = hierarchyIds.get(step.from), to = hierarchyIds.get(step.to);
            const source = hierarchyIds.get(step.edge.source), target = hierarchyIds.get(step.edge.target);
            return from === undefined || to === undefined || source === undefined || target === undefined ? []
                : [{ edge: { ...step.edge, source, target }, from, to }];
        });
    }, [trailView, hierarchyIds]);
    const clearTrail = useCallback(() => { setTrail(undefined); setTrailStep(0); }, []);
    /*
     * Escape gibt den Pfad frei, aber erst nach allen, die vorgehen: liegt eine
     * Flaeche darueber (`escapeTaken`, dieselbe Reihenfolge wie beim
     * Vollbild), gehoert die Taste ihr, und wer in einem Feld oder im Editor
     * tippt, verlaesst mit Escape das Feld und nicht den Pfad.
     */
    const escapeTaken = props.escapeTaken === true;
    useEffect(() => {
        if (!trailView || escapeTaken) return;
        const onKey = (event: globalThis.KeyboardEvent): void => {
            if (event.key !== 'Escape' || event.defaultPrevented) return;
            if (isTypingTarget(event.target instanceof Element ? event.target : null)) return;
            event.preventDefault();
            clearTrail();
        };
        window.addEventListener('keydown', onKey);
        return () => window.removeEventListener('keydown', onKey);
    }, [trailView, escapeTaken, clearTrail]);

    const index = useMemo(
        () => (picture === undefined ? new Map<string, GraphNode>() : nodesByQualifiedName(picture.nodes)),
        [picture],
    );

    // Die Legende haengt am gezeigten Bild: ihre Kantenarten nennen die dieses
    // Graphen und nicht alle, die die Tabelle kennt.
    const legend = useMemo(
        () => (mode === 'hierarchy'
            ? hierarchyLegendEntries(picture, readerHierarchyActive, Boolean(scopedProjection))
            : galaxyLegendEntries(picture)),
        [mode, picture, readerHierarchyActive, scopedProjection],
    );

    // Der Inhalt hat sich geaendert (aufgeklappt, Ansicht gewechselt, eine Art
    // mehr): die Kante gilt neu. Siehe measureLegendEdge.
    useEffect(() => {
        measureLegendEdge();
    }, [measureLegendEdge, legendOpen, legend, hiddenKinds]);

    // Und wenn der Kasten selbst seine Hoehe aendert, weil das Fenster es tut.
    useEffect(() => {
        const node = legendBox.current;
        if (node === null || typeof ResizeObserver === 'undefined') {
            return;
        }
        const observer = new ResizeObserver(measureLegendEdge);
        observer.observe(node);
        return () => observer.disconnect();
    }, [measureLegendEdge, legendOpen]);

    /*
     * Die eigene Navigation des Lesers, als Ereignis.
     *
     * Sie entsteht HIER und geht nirgendwo hin: die Bruecke kennt keine Route,
     * die etwas entgegennimmt, und dieses Ereignis verlaesst das Fenster nie.
     * Es traegt darum auch keinen Lauf einer fremden Aufzeichnung, sondern einen
     * eigenen, und seine Nummer zaehlt in diesem Fenster.
     */
    const youSeq = useRef(0);
    const pushEvent = props.agents?.push;
    useEffect(() => {
        if (pushEvent === undefined || !liveOn) {
            return;
        }
        if (focusQualifiedName === undefined || focusQualifiedName.length === 0) {
            return;
        }
        const node = index.get(focusQualifiedName);
        if (node === undefined) {
            return;
        }
        youSeq.current += 1;
        pushEvent({
            ts: Date.now(),
            agent: YOU_ID,
            run: 'this-window',
            seq: youSeq.current,
            phase: 'end',
            tool: 'Open',
            path: node.file_path ?? '',
            ...(node.start_line !== undefined && node.end_line !== undefined
                ? { lines: [node.start_line, node.end_line] as const }
                : {}),
            detail: node.qualified_name ?? node.name,
            source: 'ui',
            replay: false,
        }, true);
    }, [pushEvent, liveOn, focusQualifiedName, index]);

    /*
     * Die Verortung, EINMAL gerechnet.
     *
     * Aus demselben Ergebnis zeichnet die Ebene ihre Koerper und schreibt das
     * Instrument seine Zeilen. Zwei Rechnungen waeren zwei Wahrheiten ueber
     * dasselbe Bild, und die Stelle, an der sie auseinanderlaufen, faellt
     * niemandem auf.
     */
    const placementIndex = useMemo(
        () => buildPlacementIndex(picture?.nodes ?? []),
        [picture],
    );
    /*
     * Der Zeitstrahl und seine zwei Haltepunkte (W11b AC4).
     *
     * `pausedAt` haelt das FENSTER an: die Ereignisse laufen weiter ein, sie
     * stehen nach dem Fortsetzen alle da, und was steht, ist das Nachlaufen.
     * `replayAt` ist der staerkere Griff: der Leser hat auf eine Stelle
     * geklickt und sieht den Zustand von damals, und dann steht die GANZE
     * Ansicht auf jenem Zeitpunkt, sichtbar gekennzeichnet. Ein alter Zustand
     * ohne Kennzeichnung waere die gefaehrlichste Anzeige dieser Oberflaeche.
     */
    const [pausedAt, setPausedAt] = useState<number | undefined>(undefined);
    const [replayAt, setReplayAt] = useState<number | undefined>(undefined);
    useEffect(() => {
        if (!liveOn) {
            setPausedAt(undefined);
            setReplayAt(undefined);
        }
    }, [liveOn]);

    const agentsView = useMemo(() => {
        const runtime = props.agents;
        if (runtime === undefined) {
            return undefined;
        }
        const at = replayAt ?? agentNow;
        return buildAgentsView({
            state: replayAt === undefined ? runtime.state : stateUntil(runtime.state, replayAt),
            nodes: picture?.nodes ?? [],
            now: at,
            filter: agentPreference.filter,
            trailWindowMs: agentPreference.trailWindowMs,
            index: placementIndex,
            cap: DRAWN_BODIES_CAP,
        });
    }, [props.agents, picture, agentNow, replayAt, agentPreference.filter,
        agentPreference.trailWindowMs, placementIndex]);

    /*
     * Der Zeitstrahl selbst, aus derselben Sicht wie alles andere.
     *
     * Er nimmt ALLE aktiven Akteure und nicht die gefilterten: der Filter
     * you/agents/both entscheidet, wessen Koerper man sieht, und eine Spur, die
     * dabei verschwindet, waere eine Luecke in der Zeit statt einer Auswahl im
     * Bild. Was er zeigt, sind die behaltenen Ereignisse; mehr hat dieses
     * Fenster nicht.
     */
    const timeline = useMemo(() => {
        if (agentsView === undefined) {
            return undefined;
        }
        const stored = props.agents?.state.actors ?? [];
        return buildTimeline({
            actors: agentsView.all.map((actor) => {
                const source = stored.find((entry) => entry.id === actor.id);
                return {
                    id: actor.id,
                    name: actor.name,
                    color: actor.color,
                    letter: actor.letter,
                    you: actor.you,
                    idle: actor.idle,
                    firstTs: source?.firstTs ?? actor.lastTs,
                    events: (source?.events ?? []).map((event) => ({
                        ts: event.ts,
                        kind: workKindOf(event.tool, event.detail),
                    })),
                };
            }),
            now: agentNow,
            windowMs: agentPreference.trailWindowMs,
            ...(pausedAt === undefined ? {} : { pausedAt }),
            ...(replayAt === undefined ? {} : { replayAt }),
        });
    }, [agentsView, props.agents, agentNow, agentPreference.trailWindowMs, pausedAt, replayAt]);

    /*
     * Und die zweite Bedingung: `agentLayer` kommt aus den Einstellungen und
     * heisst "diese Ebene kostet mir zu viel". Sie ist von `liveOn` getrennt,
     * weil sie etwas anderes sagt: der Modus laeuft weiter, das Instrument
     * bleibt stehen und sagt, dass die Ebene abgeschaltet ist.
     */
    const agentLayerOn = props.agentLayer !== false;

    /*
     * Ob der Zeitstrahl gezeigt wird.
     *
     * Drei Bedingungen, und alle drei sind Auskuenfte: der Live-Modus laeuft,
     * der Schalter in den Einstellungen ist an, und die Zeichenflaeche ist breit
     * genug, dass ein Strich von seinem Nachbarn zu unterscheiden ist. Die
     * dritte ist gemessen und nicht an einen Modus gebunden; welche Breite es
     * braucht und warum, steht bei {@link TIMELINE_MIN_WIDTH}.
     */
    const timelineShown = liveOn
        && agentLayerOn
        && props.agentEffects?.timeline !== false
        && sceneWidth >= TIMELINE_MIN_WIDTH;

    /** Ob der Graph gerade das ganze Fenster fuellt. */
    const fullscreen = visible && !props.workspaceExpanded && liveOn && agentPreference.fullscreen;

    /*
     * Der Rahmen wechselt, das Bild bleibt (W11b AC5).
     *
     * Das Umschalten in das Vollbild und zurueck aendert die Groesse der
     * Zeichenflaeche, und auf eine neue Groesse passt dieses Panel sonst das
     * Bild ein (Entscheidung 18). Fuer DIESEN Groessenwechsel gilt das nicht:
     * das Vollbild ist derselbe Graph in einem anderen Rahmen, und AC5 verlangt
     * ausdruecklich, dass die Kameralage dabei erhalten bleibt. Eine Einpassung
     * beim Verlassen waere eine Kamera, die den Leser dorthin zurueckwirft, wo
     * er stand, bevor er selbst gefahren ist.
     *
     * Gemerkt wird genau EINE Aspektaenderung: die, die der Rahmenwechsel
     * ausloest. Jede andere passt weiter ein.
     */
    const lastFrame = useRef(fullscreen);
    const skipNextFit = useRef(false);
    useEffect(() => {
        if (lastFrame.current === fullscreen) {
            return;
        }
        lastFrame.current = fullscreen;
        skipNextFit.current = true;
    }, [fullscreen]);

    /**
     * Auf eine Menge Knoten zufliegen.
     *
     * Immer ein frisches Ziel, auch fuer dieselbe Menge: der CameraAnimator der
     * Uebernahme startet an der Objekt-Identitaet.
     */
    const flyTo = useCallback(
        (
            nodes: GraphNode[],
            ids: Set<number>,
            qualifiedName: string,
            /*
             * Mit Feder statt mit Anflug (W11b). Nur die FOLLOW-Kamera setzt es;
             * jede andere Fahrt dieses Panels bleibt der Anflug, den die
             * Beweisbilder bis W11a zeigen.
             */
            spring = false,
        ): CameraTarget | null => {
            const target = computeCameraTarget(nodes, ids);
            if (target === null) {
                return null;
            }
            const next = spring ? { ...target, spring: true } : target;
            setCameraTarget(next);
            targetChanges.current += 1;
            lastTargetQn.current = qualifiedName;
            return next;
        },
        [],
    );

    /** Wohin die FOLLOW-Kamera zuletzt geschickt wurde. Fuer die Messung. */
    const followGoal = useRef<{
        nodeId: number;
        actor: string;
        position: [number, number, number];
        at: number;
    } | undefined>(undefined);

    /*
     * Die Einpassung (W10b, AC5): das ganze Bild, mit Rand, ohne Anflug.
     *
     * Sie laeuft, wenn ein Bild ENTSTEHT (neues Layout, andere Ansicht, andere
     * Projektion), wenn die Zeichenflaeche eine andere Groesse bekommt und wenn
     * der Leser darum bittet (`refit`, der Knopf und "reset layout"). Sie laeuft
     * NICHT, wenn der Leser die Kamera bewegt, wenn er eine Kantenart aus dem
     * Bild nimmt oder wenn der Fokus wandert: das sind seine Bewegungen, und
     * eine Kamera, die dabei zurueckspringt, nimmt ihm die Ansicht aus der Hand.
     *
     * Zwei Rahmungen, und der Unterschied steht in Entscheidung 18: die Galaxie
     * ist eine dreidimensionale Wolke und braucht auch eine RICHTUNG (senkrecht
     * auf die groesste Flaeche, `computeFitTarget`); die Hierarchie ist eine
     * flache Zeichnung mit Spalten und bleibt bei der frontalen Rahmung aus W5c,
     * damit ihr Raster waagerecht bleibt. Gerahmt wird dort das Rechteck aus
     * `hierarchyFrame`, also samt dem Platz, den die Namen neben den Punkten
     * brauchen.
     */
    const fitCount = useRef(0);
    const lastFit = useRef<AtlasGalaxySeam['lastFit']>(undefined);
    const requestedFit = props.refit ?? 0;
    const [ownFit, setOwnFit] = useState(0);
    const refitNow = useCallback(() => setOwnFit((count) => count + 1), []);
    const coverageShadow = useMemo(() => showCoverage && props.workspaceExpanded && mode === 'galaxy' && data
        ? buildCoverageShadow(data) : null, [data, props.workspaceExpanded, mode, showCoverage]);
    /*
     * Was eine neue Einpassung verlangt.
     *
     * In der gewaehlten Galaxie ist das der Scope selbst (Wurzel, Richtung,
     * Kantenarten) und nicht sein Bild: ein Expand, eine Vorschau und die
     * vollstaendige Antwort danach sind derselbe Ausschnitt, und eine Kamera,
     * die bei jedem davon neu einpasst, stellt den Leser jedes Mal anders hin
     * (Review-Befund G1). Wie weit die Kamera fuer das neue Bild stehen muss,
     * stellt die Szene selbst nach, entlang derselben Blickrichtung und nur,
     * solange der Leser die Kamera nicht bewegt hat (GraphScene,
     * `FitContainment`).
     */
    const fitScope = mode === 'galaxy' && props.workspaceExpanded && scope.scope ? organicKey : undefined;
    const fitPicture = fitScope === undefined ? picture : undefined;
    const fitProjection = fitScope === undefined ? projection : undefined;
    const fitRequest = useMemo(() => ({ scope: fitScope, picture: fitPicture, projection: fitProjection, mode, requestedFit, ownFit, coverageShadow }),
        [fitScope, fitPicture, fitProjection, mode, requestedFit, ownFit, coverageShadow]);
    const lastFitRequest = useRef<typeof fitRequest | undefined>(undefined);

    useEffect(() => {
        if (!visible) {
            return;
        }
        // Chat resizing changes the viewport, not the selected graph neighborhood.
        if (props.workspaceExpanded && lastFitRequest.current === fitRequest) return;
        /* Der Rahmenwechsel des Vollbilds passt nicht ein. Siehe `skipNextFit`. */
        if (skipNextFit.current) {
            skipNextFit.current = false;
            return;
        }
        if (mode === 'hierarchy' && projection !== undefined) {
            // In der Hierarchie eines Ausschnitts rahmt die Kamera die Namen in ihrer Breite (Runde 4, N1); ohne Namen zaehlt der Punkt.
            const box = hierarchyFrame(projection, projection === scopedProjection ? (placement) => {
                const node = projection.data.nodes[placement.id];
                return node === undefined || (scopedNamedIds !== undefined && !scopedNamedIds.has(placement.id)) ? 0 : hierarchyLabelWidth(graphNodeName(node));
            } : undefined);
            const target = computeFrameTarget(box, aspect);
            // Erst eine Einpassung, die wirklich lief, verbraucht die Anfrage:
            // ein Scope, dessen Bild noch angeordnet wird, passt danach ein.
            lastFitRequest.current = fitRequest;
            setCameraTarget(target);
            targetChanges.current += 1;
            fitCount.current += 1;
            lastTargetQn.current = projection.rootKey;
            lastFit.current = {
                mode,
                kind: 'frontal',
                aspect,
                nodes: projection.data.nodes.length,
                distance: target.position.z - target.lookAt.z,
                width: box.width,
                height: box.height,
                depth: 0,
                normal: [0, 0, 1],
                up: [0, 1, 0],
            };
            return;
        }
        const nodes = [...(picture?.nodes ?? []), ...(coverageShadow?.nodes ?? [])];
        if (nodes.length === 0) {
            return;
        }
        /*
         * Die Wurzel steht in der Mitte (Review-Befund G4). Gerahmt wird um sie
         * herum, weit genug, dass auch der fernste Knoten passt; ohne das stand
         * die Mitte der Wolke im Bild und die Wurzel irgendwo darin.
         */
        const roots = fitScope === undefined ? [] : nodes.filter((node) => scope.result?.roots.has(node.id));
        const center = roots.length === 0 ? undefined : {
            x: roots.reduce((sum, node) => sum + node.x, 0) / roots.length,
            y: roots.reduce((sum, node) => sum + node.y, 0) / roots.length,
            z: roots.reduce((sum, node) => sum + node.z, 0) / roots.length,
        };
        const target = computeFitTarget(nodes, aspect, center);
        if (target === null) {
            return;
        }
        lastFitRequest.current = fitRequest;
        setCameraTarget(target);
        targetChanges.current += 1;
        fitCount.current += 1;
        const fit = target.fit;
        lastFit.current = {
            mode,
            kind: 'principal',
            aspect,
            nodes: fit.counted,
            distance: fit.distance,
            width: fit.width,
            height: fit.height,
            depth: fit.depth,
            normal: [fit.normal.x, fit.normal.y, fit.normal.z],
            up: [fit.up.x, fit.up.y, fit.up.z],
            center: [fit.center.x, fit.center.y, fit.center.z],
        };
        // `scope.result` folgt dem Bild und loest selbst keine Einpassung aus.
        // eslint-disable-next-line react-hooks/exhaustive-deps
    }, [visible, mode, projection, picture, aspect, requestedFit, ownFit, coverageShadow, fitRequest, props.workspaceExpanded, fitScope, scopedProjection, scopedNamedIds]);

    const [backgroundCleared, setBackgroundCleared] = useState(false);
    useEffect(() => {
        if (focusQualifiedName || stepQualifiedName || props.focusFilePath) setBackgroundCleared(false);
    }, [focusQualifiedName, stepQualifiedName, props.focusFilePath, props.focusSourceRange?.startLine, props.focusSourceRange?.endLine]);

    // Hin-Richtung in der Galaxie: das Twin-Subjekt zieht die Kamera nach.
    useEffect(() => {
        if (backgroundCleared || mode !== 'galaxy' || data === undefined) {
            return;
        }
        if (props.workspaceExpanded && scope.scope) {
            setHighlighted(new Set(data.nodes.map(node => node.id))); setNote(''); return;
        }
        const node = focusQualifiedName ? index.get(focusQualifiedName) : undefined;
        if (props.focusFilePath === '') {
            setHighlighted(null);
            setNote(GALAXY_NO_FOCUS_NOTE);
            return;
        }
        if (props.focusFilePath) {
            const focus = readerGraphFocus(data.nodes, props.focusFilePath, props.focusSourceRange);
            setHighlighted(focus.ids);
            setNote(focus.message);
            if (focus.ids.size > 0) flyTo(data.nodes, readerFocusFrame(focus.ids, data.edges), props.focusFilePath);
            return;
        }
        if (!focusQualifiedName) return;
        if (node === undefined) {
            setHighlighted(null);
            setNote(missingNodeNote(focusName ?? focusQualifiedName));
            return;
        }
        const ids = neighbourIds(node.id, data.edges);
        setHighlighted(ids);
        flyTo(data.nodes, ids, focusQualifiedName);
        setNote('');
        // `focusName` steht bewusst nicht in der Liste: er begleitet den
        // qualifizierten Namen und darf keine zweite Kamerafahrt ausloesen.
        // eslint-disable-next-line react-hooks/exhaustive-deps
    }, [backgroundCleared, mode, data, index, focusQualifiedName, flyTo, props.focusFilePath, props.focusSourceRange, aspect, visible, props.workspaceExpanded, scope.scope]);

    /*
     * FOLLOW: die Kamera geht dorthin, wo sich zuletzt etwas bewegt hat.
     *
     * Sie faehrt nur, wenn der Ort WECHSELT. Ein Anflug bei jedem Ereignis waere
     * eine Kamera, die bei zehn Aenderungen an derselben Datei zehnmal
     * losfliegt, und die Bewegung waere Zittern und keine Auskunft. Und sie
     * faehrt nur, solange der Schalter an ist: eine Kamera, die von selbst
     * losfaehrt, nimmt dem Leser die Ansicht, die er gerade eingestellt hat.
     */
    const followed = useRef(-1);
    const [followLine, setFollowLine] = useState<ActorView | undefined>(undefined);
    useEffect(() => {
        if (!liveOn || !agentPreference.follow || agentsView === undefined
            || picture === undefined) {
            return;
        }
        const target = agentsView.actors.find((actor) => actor.node !== undefined);
        const node = target?.node;
        if (node === undefined || node.id === followed.current) {
            return;
        }
        followed.current = node.id;
        /*
         * Mit der Feder (W11b AC3c). Die Kamera bekommt hier waehrend eines
         * Anfluges ein neues Ziel, sobald der Agent weiterzieht; der Anflug der
         * Szene faengt bei jedem Ziel wieder bei null an, und genau das ist der
         * Ruck, den dieser Zyklus verbietet. Die Feder traegt ihre
         * Geschwindigkeit ueber das neue Ziel hinweg und schwingt nicht ueber.
         */
        const goal = flyTo(
            picture.nodes,
            new Set([node.id]),
            target?.placement.qualifiedName ?? node.name,
            true,
        );
        followGoal.current = goal === null
            ? undefined
            : {
                nodeId: node.id,
                actor: target?.id ?? '',
                position: [goal.position.x, goal.position.y, goal.position.z],
                at: Date.now(),
            };
        setFollowLine(target);
    }, [liveOn, agentPreference.follow, agentsView, picture, flyTo]);

    /*
     * Die Ereigniszeile, die kurz eingeblendet wird.
     *
     * Sie nennt vier Dinge und alle vier sind gemessen: wer, welche Art von
     * Arbeit, welches Symbol, welche Zeilen. Sie verschwindet nach ein paar
     * Sekunden wieder, weil sie zum Anflug gehoert und nicht zum Bild; eine
     * Zeile, die stehen bleibt, waere eine Auskunft ueber eine Bewegung, die
     * laengst vorbei ist.
     */
    useEffect(() => {
        if (followLine === undefined) {
            return;
        }
        const timer = window.setTimeout(() => setFollowLine(undefined), FOLLOW_LINE_MS);
        return () => window.clearTimeout(timer);
    }, [followLine]);
    useEffect(() => {
        if (!agentPreference.follow || !liveOn) {
            setFollowLine(undefined);
            followed.current = -1;
        }
    }, [agentPreference.follow, liveOn]);

    /*
     * FULLSCREEN: derselbe Graph, das ganze Fenster.
     *
     * Es ist der Rahmen und keine Fuehrung: die Kamera geht weiter dorthin, wo
     * der Leser sie hinschickt, und sie faehrt hier nichts von selbst ab. Escape
     * bringt das Panel zurueck, wie bei jeder anderen Flaeche, die sich ueber
     * die Oberflaeche legt, und zwar ZULETZT: liegt eine andere Flaeche darueber
     * (Hilfe, Einstiegsdialog, Suchfenster, Einstellungen), gehoert die Taste
     * ihr. Der Vollbildmodus reiht sich in die bestehende Reihenfolge ein, er
     * draengt sich nicht vor (`escapeTaken` steht beim Pfad weiter oben).
     */
    useEffect(() => {
        const node = panel.current;
        if (node === null || !fullscreenIsolationRequired(fullscreen, escapeTaken)) {
            return;
        }
        return isolateFullscreenBackground(node);
    }, [fullscreen, escapeTaken]);
    useEffect(() => {
        if (!fullscreen || escapeTaken) {
            return;
        }
        const onKey = (event: globalThis.KeyboardEvent): void => {
            if (event.key !== 'Escape' || event.defaultPrevented) {
                return;
            }
            event.preventDefault();
            changeAgentPreference({ fullscreen: false });
        };
        window.addEventListener('keydown', onKey);
        return () => window.removeEventListener('keydown', onKey);
    }, [fullscreen, escapeTaken, changeAgentPreference]);

    /**
     * Der Knoten, um den der Ring laeuft.
     *
     * Das Symbol vor dem Leser, wenn es im Bild vorkommt, sonst der Schritt,
     * auf dem die Fuehrung steht. In dieser Reihenfolge, weil ein Klick in das
     * Bild das Symbol wechselt, ohne die Fuehrung zu bewegen, und der Ring dann
     * dorthin gehoert, wo der Leser hingegangen ist.
     */
    const pulsedNode = useMemo(() => {
        if (backgroundCleared || mode !== 'hierarchy' || readerHierarchyActive) {
            return undefined;
        }
        for (const candidate of [focusQualifiedName, stepQualifiedName]) {
            if (candidate !== undefined && candidate.length > 0) {
                const node = index.get(candidate);
                if (node !== undefined) {
                    return node;
                }
            }
        }
        return undefined;
    }, [backgroundCleared, mode, readerHierarchyActive, focusQualifiedName, stepQualifiedName, index]);

    /*
     * Ob die Notiz zum Ring gilt (Runde 4, N2). Der Ring folgt dem Symbol, das
     * im Reader von Explore offen ist; die Notiz sagt, dass keiner der Knoten
     * dieses ist. Das gilt nur neben dem Reader: im Galaxy-Tab steht die
     * Wurzel eines Ausschnitts markiert in der Mitte, und Explore ist dort
     * nicht zu sehen. Ein Klick ins Leere blendet den Ring aus, macht die
     * Notiz aber nicht wahr; darum zaehlt hier das Bild und nicht der Ring.
     */
    const hierarchyNoFocusNote = useMemo(() => !props.workspaceExpanded
        && ![focusQualifiedName, stepQualifiedName].some((candidate) => candidate !== undefined && candidate.length > 0 && index.has(candidate))
        ? galaxyHierarchyNoteText.noFocus : '', [props.workspaceExpanded, focusQualifiedName, stepQualifiedName, index]);

    /*
     * In der Hierarchie bleibt alles hell.
     *
     * In der Galaxie dunkelt die Szene alles ausser der Nachbarschaft ab, und
     * das ist dort richtig: eine Wolke aus fuenftausend Punkten braucht eine
     * Auswahl. Hier ist der ganze Subgraph die Antwort. Ihn bis auf zwei
     * Spalten abzudunkeln hiesse, genau die Tiefe wieder zu verstecken, die
     * dieses Bild zeigen soll: die dritte Ebene waere ein Schatten. Wo der
     * Leser steht, sagt der Ring, und der ist ein deutlicheres Zeichen als
     * "nicht abgedunkelt".
     */
    useEffect(() => {
        if (mode !== 'hierarchy' || projection === undefined) {
            return;
        }
        setHighlighted(new Set(projection.data.nodes.map((node) => node.id)));
        setNote(readerProjection ? readerProjection.message : hierarchyNoFocusNote);
    }, [mode, projection, pulsedNode, readerProjection, hierarchyNoFocusNote]);

    // Rueck-Richtung: ein Klick in die Szene oeffnet die Datei.
    const handleNodeClick = useCallback(
        (node: GraphNode) => {
            setBackgroundCleared(false);
            // In der Hierarchie bleibt die Kamera stehen und alles hell: sie
            // rahmt den ganzen Subgraphen, und auf eine Spalte zu zoomen waere
            // wieder die Nachbarschaftsansicht, gegen die dieses Bild gebaut
            // ist. Der Ring wandert, sobald das Symbol vor dem Leser wechselt.
            if (mode === 'galaxy' && picture !== undefined) {
                const ids = neighbourIds(node.id, picture.edges);
                setHighlighted(ids);
                flyTo(picture.nodes, ids, node.qualified_name ?? node.name);
            }
            const selected = layoutNodeForSelection(layout, node) ?? layoutNodeForSelection(data, node) ?? node;
            props.onSelectNode?.(selected);
            if (props.workspaceExpanded) {
                clearTrail();
                scope.select({ kind: 'node', id: selected.id, name: selected.name, qualifiedName: selected.qualified_name });
                setNote('');
                return;
            }
            const file = nodeFilePath(node);
            if (file === undefined || file.length === 0) {
                setNote(unopenableNodeNote(node));
                return;
            }
            setNote('');
            onOpenNode(selected);
        },
        [layout, data, picture, mode, flyTo, onOpenNode, props.onSelectNode, props.workspaceExpanded, scope.select, clearTrail],
    );

    /* "All graph" und Escape: der Ausschnitt wird verlassen, und das ist selbst ein Schritt im Verlauf (K2). */
    const leaveScope = useCallback(() => {
        setBackgroundCleared(true);
        if (props.workspaceExpanded) setChosenMode('galaxy');
        clearTrail();
        scope.reset();
        changeTraceTypes(undefined);
        setHighlighted(null);
        setNote(props.workspaceExpanded ? '' : mode === 'hierarchy' ? readerProjection?.message ?? hierarchyNoFocusNote : GALAXY_NO_FOCUS_NOTE);
        refitNow();
        props.onClearSelection?.();
    }, [mode, refitNow, props.onClearSelection, readerProjection, scope.reset, props.workspaceExpanded, changeTraceTypes, clearTrail, hierarchyNoFocusNote]);
    /*
     * Ein Klick ins Leere hebt im Ausschnitt nur die Markierung auf (Handtest
     * K9). Bis dahin verliess er den Ausschnitt samt Ebenen und Pfad, ohne
     * Rueckfrage, und ein Klick knapp neben einen Knoten genuegte. Aus dem
     * Ausschnitt fuehren jetzt nur "All graph", Escape und Zurueck; der
     * aufgehobene Pfad ist ein Schritt im Verlauf und kommt mit Zurueck wieder.
     */
    const handleBackgroundClick = useCallback(() => {
        if (props.workspaceExpanded && scope.scope) { clearTrail(); return; }
        leaveScope();
    }, [props.workspaceExpanded, scope.scope, clearTrail, leaveScope]);

    /*
     * Zurueck und Vor (Handtest K2), wie beim Blaettern.
     *
     * Der Eintrag ist die ganze Frage dieses Augenblicks: Wurzel, Tiefe,
     * Richtung, Kantenarten, offener Pfad und Ansicht, und nichts von der
     * Antwort. Er wird aus dem Zustand ABGELEITET und nicht an jeder Stelle
     * abgelegt, die ihn aendert; so kann kein Weg in einen neuen Ausschnitt den
     * Verlauf vergessen. Was ein Zurueck selbst herstellt, legt keinen neuen
     * Eintrag ab (`restoringKey`). Regeln und Grenzen: src/graph/navigation-history.ts.
     */
    const historyTrail: ScopeTrail | undefined = trail?.key !== organicKey ? undefined
        : trail.kind === 'calls' ? { kind: 'calls' } : { kind: 'path', target: trail.target, name: trail.name };
    const historyEntry: GalaxyHistoryEntry | undefined = props.workspaceExpanded ? {
        ...(scope.scope ? { scope: scope.scope } : {}), depth: scope.depth, direction: scope.direction,
        ...(traceTypes ? { edgeTypes: traceTypes } : {}), ...(historyTrail ? { trail: historyTrail } : {}), mode,
    } : undefined;
    const historyKey = historyEntry ? galaxyHistoryOptions.key(historyEntry) : '';
    const latestEntry = useRef(historyEntry);
    latestEntry.current = historyEntry;
    const [history, setHistory] = useState(() => emptyNavigationHistory<GalaxyHistoryEntry>());
    const restoringKey = useRef<string | undefined>(undefined);
    const selectOnComplete = useRef<string | undefined>(undefined);
    const historyProject = useRef(project);
    useEffect(() => {
        const entry = latestEntry.current;
        /*
         * Ein Projektwechsel beginnt einen neuen Verlauf. Das Projekt kommt oft
         * erst nach dem ersten Bild aus der Adresszeile; der ganze Graph steht
         * dann schon da und muss der erste Eintrag bleiben. Ein offener
         * Ausschnitt gehoert noch zum alten Projekt und wird nicht uebernommen.
         */
        if (historyProject.current !== project) {
            historyProject.current = project;
            restoringKey.current = undefined;
            const fresh = emptyNavigationHistory<GalaxyHistoryEntry>();
            setHistory(entry !== undefined && !entry.scope ? pushNavigation(fresh, entry, galaxyHistoryOptions) : fresh);
            return;
        }
        if (entry === undefined) return;
        const expected = restoringKey.current;
        restoringKey.current = undefined;
        if (expected === historyKey) return;
        setHistory((current) => pushNavigation(current, entry, galaxyHistoryOptions));
    }, [historyKey, project]);
    const applyEntry = useCallback((entry: GalaxyHistoryEntry) => {
        scope.restore({ ...(entry.scope ? { scope: entry.scope } : {}), depth: entry.depth, direction: entry.direction });
        const types = entry.edgeTypes ? [...entry.edgeTypes] : undefined;
        changeTraceTypes(types);
        setChosenMode(entry.mode);
        const nextKey = JSON.stringify([project, entry.scope, entry.scope ? entry.direction : 'both', types]);
        setTrail(entry.trail ? { key: nextKey, ...entry.trail } : undefined);
        setTrailStep(0);
        setBackgroundCleared(false);
        setNote('');
        /*
         * Die Auswahl folgt der Wurzel: der ganze Graph hat keine, eine andere
         * Wurzel waehlt sich, sobald sie geladen ist (ein Symbol meldet sich
         * selbst, siehe `notifiedScopedSymbol`), und dieselbe Wurzel auf einer
         * anderen Tiefe oder nach einem Abbruch bleibt ausgewaehlt, mit ihren
         * "Selection details" und dem Kontext des Chats.
         */
        if (!entry.scope) { setHighlighted(null); props.onClearSelection?.(); }
        else if (!scope.scope || scopeIdentity(entry.scope) !== scopeIdentity(scope.scope))
            selectOnComplete.current = entry.scope.kind === 'symbol' ? undefined : scopeIdentity(entry.scope);
    }, [scope.restore, scope.scope, changeTraceTypes, project, props.onClearSelection]);
    const historyBack = peekNavigation(history, -1);
    const historyForward = peekNavigation(history, 1);
    const goHistory = useCallback((step: -1 | 1) => {
        const entry = peekNavigation(history, step);
        if (entry === undefined) return;
        restoringKey.current = galaxyHistoryOptions.key(entry);
        setHistory((current) => moveNavigation(current, step, galaxyHistoryOptions));
        applyEntry(entry);
    }, [history, applyEntry]);
    // A recent root is a new navigation: it is pushed and drops the forward branch.
    const jumpToRecent = useCallback((entry: GalaxyHistoryEntry) => applyEntry(entry), [applyEntry]);
    useEffect(() => {
        if (!scope.complete || !scopedRoot || !scope.scope || selectOnComplete.current !== scopeIdentity(scope.scope)) return;
        selectOnComplete.current = undefined;
        props.onSelectNode?.(layoutNodeForSelection(layout, scopedRoot) ?? scopedRoot);
    }, [scope.complete, scopedRoot, scope.scope, layout, props.onSelectNode]);
    useEffect(() => {
        if (!props.workspaceExpanded || escapeTaken) return;
        const onKey = (event: globalThis.KeyboardEvent): void => {
            if (event.defaultPrevented || !event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return;
            if (event.key !== 'ArrowLeft' && event.key !== 'ArrowRight') return;
            if (isTypingTarget(event.target instanceof Element ? event.target : null)) return;
            const step = event.key === 'ArrowLeft' ? -1 : 1;
            if (peekNavigation(history, step) === undefined) return;
            event.preventDefault();
            goHistory(step);
        };
        window.addEventListener('keydown', onKey);
        return () => window.removeEventListener('keydown', onKey);
    }, [props.workspaceExpanded, escapeTaken, history, goHistory]);
    /* Escape ohne offenen Pfad verlaesst den Ausschnitt (K9); den Pfad gibt der Griff weiter oben frei. */
    useEffect(() => {
        if (!props.workspaceExpanded || !scope.scope || trailView || escapeTaken) return;
        const onKey = (event: globalThis.KeyboardEvent): void => {
            if (event.key !== 'Escape' || event.defaultPrevented) return;
            if (isTypingTarget(event.target instanceof Element ? event.target : null)) return;
            event.preventDefault();
            leaveScope();
        };
        window.addEventListener('keydown', onKey);
        return () => window.removeEventListener('keydown', onKey);
    }, [props.workspaceExpanded, scope.scope, trailView, escapeTaken, leaveScope]);
    /* Handtest 2026-10-04 (A2): die Liste schliesst bei einem Klick daneben, mit Escape und mit jedem neuen Ort. */
    const recentMenu = useDismissibleMenu(historyKey);
    const historyControls = props.workspaceExpanded ? <span className="atlas-graph-history" role="group" aria-label={galaxyHistoryText.group}>
        <button type="button" aria-label={galaxyHistoryText.back} disabled={!historyBack} onClick={() => goHistory(-1)}
            title={historyBack ? galaxyHistoryText.backTo(historyEntryLabel(historyBack)) : galaxyHistoryText.noBack}>
            <FitLabel wide={galaxyHistoryText.backWide} narrow={galaxyHistoryText.backGlyph} /></button>
        <button type="button" aria-label={galaxyHistoryText.forward} disabled={!historyForward} onClick={() => goHistory(1)}
            title={historyForward ? galaxyHistoryText.forwardTo(historyEntryLabel(historyForward)) : galaxyHistoryText.noForward}>
            <FitLabel wide={galaxyHistoryText.forwardWide} narrow={galaxyHistoryText.forwardGlyph} /></button>
        {history.recent.length > 1 && <details className="atlas-graph-recent" ref={recentMenu.ref}>
            <summary title={galaxyHistoryText.recentTitle} aria-label={galaxyHistoryText.recent}>{galaxyHistoryText.recentGlyph}</summary>
            <ul className="atlas-graph-recent-menu" aria-label={galaxyHistoryText.recentList}>{history.recent.map((entry) => {
                const current = galaxyHistoryOptions.recentKey?.(entry) === (scope.scope ? scopeIdentity(scope.scope) : undefined);
                return <li key={galaxyHistoryOptions.recentKey?.(entry)}>
                    <button type="button" disabled={current} aria-current={current ? 'true' : undefined} onClick={() => {
                        recentMenu.close();
                        jumpToRecent(entry);
                    }}><strong>{entry.scope && scopeDisplayName(entry.scope)}</strong><span>{historyEntryDetail(entry)}</span></button>
                </li>;
            })}</ul>
        </details>}
    </span> : null;

    /* Der geladene Ausschnitt fuer "Selection details" (K13). */
    const selectionScope = useMemo<SelectionScope | undefined>(() => props.workspaceExpanded && scope.scope && scope.result ? {
        graph: scope.result.data, complete: scope.complete, direction: scope.direction, depth: scope.result.depth,
        ...(traceTypes ? { edgeTypes: traceTypes } : {}), ...(scope.result.partial ? { partial: scope.result.partial } : {}),
    } : undefined, [props.workspaceExpanded, scope.scope, scope.result, scope.complete, scope.direction, traceTypes]);
    const selectionContent = typeof props.selectionPanel === 'function' ? props.selectionPanel(selectionScope) : props.selectionPanel;

    /* K3 und Review: die Leiste misst, ob sie voll, knapp oder umgebrochen passt (toolbar-fit.tsx). */
    const explorationBar = useRef<HTMLDivElement>(null);
    useToolbarFit(explorationBar, Boolean(props.workspaceExpanded && scope.scope));

    /* Was die Leiste sonst noch braucht (K3): Quelle der Wurzel, Gruppen und was ausserhalb der Limits liegt. */
    const openRoot = props.workspaceExpanded && scopedRoot && nodeFilePath(scopedRoot)
        ? () => props.onOpenNode(layoutNodeForSelection(layout, scopedRoot) ?? scopedRoot) : undefined;
    /* Runde 4 (N1): die Wurzel heisst, wie die Galaxie sie zeigt; ein Branch-Knoten "django-demo · detached HEAD". */
    // Ordner und Dateien behalten ihren Pfad; ein Knoten nimmt seine Art von der geladenen Wurzel, wo es sie gibt.
    const rootShown = !scope.scope ? ''
        : (scope.scope.kind === 'node' || scope.scope.kind === 'symbol') && scopedRoot && scopedRoot.qualified_name === scope.scope.qualifiedName
            ? graphNodeName(scopedRoot) : scopeDisplayName(scope.scope);
    const groupCount = mode === 'galaxy' && organic ? organic.groups.length : 0;
    const groupsText = groupCount > 1 ? galaxyToolbarText.groupsTitle(groupCount) : undefined;
    const outsideLimits = props.workspaceExpanded && data && shown && (shown.nodes.length < data.nodes.length || shown.edges.length < data.edges.length)
        ? galaxyToolbarText.outsideLimits(data.nodes.length - shown.nodes.length, data.edges.length - shown.edges.length) : undefined;

    /*
     * "−" waehrend des Ladens ist ein Abbruch (K8), und ein Abbruch ist ein
     * Schritt zurueck und kein neuer: steht die vorige Ebene direkt davor im
     * Verlauf, geht es dorthin, und Vor laedt die abgebrochene Ebene wieder.
     */
    const cancelOrRemoveLayer = () => {
        const previous = historyEntry && { ...historyEntry, depth: scope.depth - 1 };
        if (scope.loading && previous && historyBack && galaxyHistoryOptions.key(historyBack) === galaxyHistoryOptions.key(previous)) goHistory(-1);
        else scope.setDepth(scope.depth - 1);
    };

    /* Was die Leiste ueber das Laden der Ebenen sagt (Handtest K8). */
    const partial = scope.complete ? scope.result?.partial : undefined;
    const scopeState = scope.validating ? 'checking' : scope.loading ? 'loading' : organicTask.loading ? 'arranging'
        : partial ? 'partial' : scope.complete ? 'complete' : 'preview';
    const scopeStatus = scope.validating ? galaxyLayerText.checking
        : scope.loading ? scope.progress ? galaxyLayerText.loadingProgress(scope.progress.layer, scope.progress.nodes, scope.progress.edges) : galaxyLayerText.loading(scope.depth)
            : organicTask.loading ? galaxyLayerText.arranging
                : scope.complete ? partial ? galaxyLayerText.partial(galaxyLayerText.counts(data?.nodes.length ?? 0, data?.edges.length ?? 0))
                    : `${galaxyLayerText.counts(data?.nodes.length ?? 0, data?.edges.length ?? 0)}${scope.result?.exhausted ? galaxyLayerText.endOfTrace : ''}`
                    : galaxyLayerText.partialPreview;
    const estimate = scope.complete ? nextLayerEstimate(scope.result) : undefined;
    // Die gezaehlten Aufrufe am Rand sind eine Untergrenze; das Wachstum allein uebersah die Knoten mit tausend Aufrufern (Review zu K8).
    const edgeCalls = estimate ? scope.edgeCalls : undefined;
    // G3: die Render-Limits gelten nur in der Werkzeugleiste des Galaxy-Arbeitsbereichs; das Mini-Galaxy laedt ohne sie.
    const expandOutlook: ExpandOutlook | undefined = estimate && {
        layer: estimate.layer, frontier: estimate.frontier, estimate: estimate.estimate, calls: edgeCalls,
        loaded: { nodes: data?.nodes.length ?? 0, edges: data?.edges.length ?? 0 },
        limits: props.workspaceExpanded ? { nodes: nodeBudget, edges: edgeBudget } : undefined,
    };
    const expandPast = expandOutlook && expandPastLimit(expandOutlook);
    const expandWarning = Boolean(expandPast);
    const expandBlocked = Boolean(scope.loading || scope.result?.exhausted || scope.result?.partial);
    // Review zu K31: gesperrt heisst immer mit Grund, auch waehrend eine Ebene laedt.
    const expandTitle = scope.loading ? galaxyLayerText.expandLoading(scope.depth)
        : partial ? galaxyLayerText.expandPartial : scope.result?.exhausted ? galaxyLayerText.expandEnd
        : expandOutlook ? galaxyLayerText.expandHint(expandOutlook, expandPast) : undefined;

    /*
     * Die Vorgabe der Ansicht, mit der Wahl des Lesers darauf.
     *
     * In dieser Reihenfolge und multiplikativ (siehe `displayWith` in
     * density.ts): die Hierarchie nimmt das Leuchten weg, weil es dort aus
     * sechzig Namen Flecken macht, und ein eingeschaltetes Bloom im
     * Einstellungen-Panel darf diesen Befund nicht ueberstimmen.
     */
    const choice = props.display ?? DEFAULT_GRAPH_DISPLAY;
    const display = displayWith(
        mode === 'hierarchy' ? HIERARCHY_DISPLAY : DEFAULT_DISPLAY_SETTINGS,
        choice,
    );
    // Ein stehendes Bild ist kein Ladezustand: die Werkzeugleiste sagt, dass angeordnet wird.
    const layoutState = error.length > 0 ? 'failed' : sceneData === undefined ? 'loading' : 'ready';
    // Die Hierarchie braucht das Layout nicht: sie faerbt sich damit, sie lebt
    // nicht davon. Ein Walk, dessen Bild dasteht, ist fertig.
    const state = mode === 'hierarchy' ? projection ? 'ready'
        : readerHierarchyActive ? layoutState === 'ready' ? 'empty' : layoutState
        : props.focusWalkStatus === 'loading' ? 'loading' : props.focusWalkStatus === 'unavailable' ? 'failed' : 'empty' : layoutState;
    const headline =
        mode === 'hierarchy'
            ? projection ? readerProjection?.headline ?? hierarchyHeadline(projection, hierarchyOrigin)
                : readerHierarchyActive ? layoutState === 'loading' ? 'Loading file relationships…'
                    : layoutState === 'failed' ? `layout unavailable: ${error}`
                    : `${props.focusFilePath} is not in the loaded graph layout.`
                : props.focusWalkMessage || 'Choose a symbol to see its outgoing call hierarchy.'
            : layoutState === 'failed'
                ? `layout unavailable: ${error}`
                : layoutState === 'loading'
                    ? `loading the layout of ${project.length > 0 ? project : 'no project'} ...`
                    : layoutSummary((data ?? sceneData) as GraphData, LAYOUT_NODE_BUDGET);

    /*
     * Die zweite Zeile des Kopfes: woraus die Linien bestehen (W9).
     *
     * Eine eigene Zeile und kein Anhang an den Satz darueber, aus zwei
     * Gruenden. Der erste ist inhaltlich: der Satz oben sagt, WORAUF man sieht
     * (welches Symbol, wie viele, wie tief), diese Zeile sagt, WORAUS das Bild
     * besteht und was gerade fehlt. Der zweite ist handfest: der Satz oben ist
     * zitierfaehig, ein Beweislauf aus W4e liest ihn bis zu seinem Ende, und
     * eine Zeile, an die immer noch etwas angehaengt wird, ist kein Satz mehr,
     * sondern eine Sammelstelle.
     *
     * Steht nichts an (Galaxie ohne Filter), steht hier auch nichts.
     */
    const edgeNote = [
        mode === 'hierarchy' && projection !== undefined
            ? readerProjection?.edgeNote ?? hierarchyEdgeNote(projection.data.edges.length, indexEdges.length)
            : '',
        mode === 'hierarchy' && !readerHierarchyActive && walk === undefined && projection ? props.focusWalkMessage ?? '' : '',
        kindNote,
    ].filter((part) => part.length > 0).join('; ');

    /*
     * Der Griff der Agentenebene.
     *
     * Er traegt genau das, was gezeichnet und geschrieben wurde, samt den
     * Winkeln aus dem zuletzt gezeichneten Bild: der Beweislauf soll die
     * Bewegung an derselben Zahl messen, die den Koerper bewegt hat, und nicht
     * an einer zweiten daneben.
     */
    useEffect(() => {
        const runtime = props.agents;
        if (runtime === undefined || agentsView === undefined) {
            globalThis.__atlasAgents = undefined;
            return;
        }
        globalThis.__atlasAgents = {
            on: runtime.on,
            layerOn: agentLayerOn,
            sourceState: runtime.status.state,
            origin: runtime.status.origin,
            requests: runtime.status.requests,
            drops: runtime.status.drops,
            mode: runtime.status.hello?.mode ?? '',
            file: runtime.status.hello?.file ?? '',
            error: runtime.status.error,
            port: runtime.port,
            events: agentsView.events,
            missed: agentsView.missed,
            perMinute: agentsView.perMinute,
            unreadable: agentsView.unreadable,
            size: agentPreference.size,
            filter: agentPreference.filter,
            follow: agentPreference.follow,
            trails: agentPreference.trails,
            fullscreen: agentPreference.fullscreen,
            trailWindowMs: agentPreference.trailWindowMs,
            shown: agentsView.actors.length,
            cap: agentsView.cap,
            capped: agentsView.capped,
            drawn: agentsView.actors.filter((actor) => actor.drawn).length,
            transitionMs: TRANSITION_MS,
            effects: {
                tails: props.agentEffects?.tails !== false,
                trails: props.agentEffects?.trails !== false,
                waves: props.agentEffects?.waves !== false,
                timeline: props.agentEffects?.timeline !== false,
            },
            timeline: timeline === undefined
                ? undefined
                : {
                    mode: timeline.mode,
                    from: timeline.from,
                    to: timeline.to,
                    windowMs: timeline.windowMs,
                    tracks: timeline.tracks.length,
                    ticks: timeline.ticks,
                    shown: timelineShown,
                    width: Math.round(sceneWidth),
                },
            follow_: followGoal.current,
            radii: Object.fromEntries(orbitRadii(
                agentsView.actors.filter((actor) => actor.drawn),
            ).entries()),
            positions: { ...agentPositions },
            pulses: { ...agentPulseScale },
            tails: { ...agentTails },
            motion: JSON.parse(JSON.stringify(agentMotion)) as Record<string, unknown>,
            camera: { ...agentCamera },
            /*
             * SceneProbe schreibt diese kleine bestehende Messnaht direkt aus
             * dem Three-Bild fort. Ein Snapshot hier waere nach seinem
             * naechsten Scan alt, obwohl genau diese Werte als "gerade
             * gezeichnet" angeboten werden. Die Referenz behaelt die
             * Produktlogik unveraendert und zeigt die aktuelle Messung.
             */
            renderOrders: agentRenderOrders,
            waves: agentsView.actors.flatMap((actor) =>
                actor.waves.map((burst) => ({
                    actor: actor.id,
                    key: burst.key,
                    nodeId: burst.nodeId,
                    events: burst.events,
                    from: burst.from,
                    to: burst.to,
                }))),
            ticker: agentsView.ticker.map((entry) => ({
                ts: entry.ts,
                actor: entry.actor,
                kind: entry.kind,
                place: entry.place,
                lines: [...entry.lines],
                text: agentText.tickerLine(
                    entry.name, WORK_KIND_WORD[entry.kind], entry.place, entry.lines,
                ),
            })),
            actors: agentsView.all.map((actor) => ({
                id: actor.id,
                name: actor.name,
                you: actor.you,
                color: actor.color,
                letter: actor.letter,
                kind: actor.kind,
                kindLetter: actor.kindLetter,
                placement: actor.placement.kind,
                uncertain: actor.placement.uncertain,
                nodeId: actor.placement.nodeId ?? -1,
                qualifiedName: actor.placement.qualifiedName,
                placeName: actor.placement.name,
                why: actor.placement.why,
                ghosts: actor.ghostNodes.map((ghost) => ghost.id),
                testedNodeId: actor.testedNode?.id ?? -1,
                intent: actor.intent,
                count: actor.count,
                missed: actor.missed,
                strip: [...actor.strip],
                paths: [...actor.paths],
                lastTool: actor.last.tool,
                lastPath: actor.last.path,
                lastLines: actor.last.lines === undefined ? [] : [...actor.last.lines],
                angle: agentAngles[actor.id] ?? -1,
                idle: actor.idle,
                sinceMs: actor.sinceMs,
                recentEvents: actor.recentEvents,
                pulseMs: actor.pulse.periodMs,
                pulseAmplitude: actor.pulse.amplitude,
                trail: actor.trail.map((node) => node.id),
                drawn: actor.drawn,
            })),
            unmapped: agentsView.unmapped.map((event) => ({ ...event })),
            angles: agentAngles,
        };
    });

    // Der Griff wird bei jedem Zustandswechsel neu gesetzt, damit er nie eine
    // Lage von vorhin beschreibt.
    useEffect(() => {
        globalThis.__atlasGalaxy = {
            nodes: data?.nodes.length ?? 0,
            targetChanges: targetChanges.current,
            highlightedCount: highlighted?.size ?? 0,
            lastTargetQn: lastTargetQn.current,
            clickNode: (qualifiedName: string): boolean => {
                const node = index.get(qualifiedName);
                if (node === undefined) {
                    return false;
                }
                handleNodeClick(node);
                return true;
            },
            legendOpen,
            legendEntries: legend.length,
            bloom: display.bloom,
            // Live: the scene publishes new name boxes from its frame loop, without a render of this panel.
            get labelBoxes() { return labelBoxes.current; },
            mode,
            open: visible,
            hierarchyAvailable: projection !== undefined,
            hierarchyOrigin: projection === undefined ? '' : hierarchyOrigin,
            fits: fitCount.current,
            lastFit: lastFit.current,
            headline,
            pulsedQn: pulsedNode?.qualified_name ?? pulsedNode?.name ?? '',
            edgeKinds: kinds.map((kind) => ({ ...kind, hidden: hiddenKinds.has(kind.type) })),
            hiddenKinds: [...hiddenKinds].sort(),
            drawnEdges: sceneShown?.edges.length ?? 0,
            edgeNote,
            history: { index: history.index, entries: history.entries.map(historyEntryLabel), recent: history.recent.map(historyEntryLabel) },
            hierarchy:
                projection === undefined
                    ? undefined
                    : {
                        root: projection.rootKey,
                        rootName: projection.rootName,
                        nodes: projection.symbols,
                        depth: projection.depth,
                        truncated: projection.truncated,
                        cap: projection.cap,
                        walkDepth: projection.walkDepth,
                        placements: projection.placements.map((placement) => ({
                            key: placement.key,
                            name: placement.name,
                            file: projection.data.nodes[placement.id]?.file_path ?? '',
                            hop: placement.hop,
                            x: placement.x,
                            y: placement.y,
                            ...(placement.side !== undefined ? { side: placement.side } : {}),
                            ...(placement.mixed ? { mixed: true } : {}),
                        })),
                        ...(projection.band ? { band: projection.band } : {}),
                        ...(projection.names ? { names: projection.names } : {}),
                        edges: projection.data.edges.map((edge) => ({
                            from: projection.data.nodes[edge.source]?.qualified_name
                                ?? projection.data.nodes[edge.source]?.name ?? '',
                            to: projection.data.nodes[edge.target]?.qualified_name
                                ?? projection.data.nodes[edge.target]?.name ?? '',
                        })),
                        walkEdges: readerHierarchyActive ? 0 : projection.data.edges.length,
                        extraEdges: readerHierarchyActive ? projection.data.edges.length : indexEdges.length,
                        extras: (readerHierarchyActive ? projection.data.edges : indexEdges).map((edge) => ({
                            type: edge.type,
                            from: projection.data.nodes[edge.source]?.qualified_name
                                ?? projection.data.nodes[edge.source]?.name ?? '',
                            to: projection.data.nodes[edge.target]?.qualified_name
                                ?? projection.data.nodes[edge.target]?.name ?? '',
                            offset: edge.offset ?? 0,
                        })),
                    },
        };
    });

    /*
     * Der Ring um den Schritt, auf dem der Leser steht.
     *
     * Ein DOM-Element in der Szene, kein Objekt der Szene: siehe Entscheidung 9
     * im Kopf. Er zeigt und faengt nichts ab, damit ein Klick weiter den Knoten
     * darunter trifft.
     */
    const pulseRing: ReactNode =
        mode === 'hierarchy' && !backgroundCleared && pulsedNode !== undefined ? (
            <Html
                position={[pulsedNode.x, pulsedNode.y, pulsedNode.z]}
                center
                style={{ pointerEvents: 'none' }}
            >
                <span
                    className="atlas-hierarchy-pulse"
                    data-testid="atlas-hierarchy-pulse"
                    data-qn={pulsedNode.qualified_name ?? pulsedNode.name}
                />
            </Html>
        ) : undefined;

    /*
     * Beide Ueberlagerungen an derselben Prop.
     *
     * Die Szene weiss weiter nicht, was sie da einhaengt (Aenderung 8 in
     * GraphScene.tsx), und sie muss zwischen einem Ring und einer Ebene aus
     * Koerpern nicht unterscheiden: was hier steht, ist ein Kind ihres Baums.
     */
    /* K5: die Kantenarten an den Linien der Hierarchie eines Ausschnitts, solange kein Pfad seine eigenen zeigt. */
    // Review zu K5: Kantenschilder nur neben Namen; ohne Namen waeren sie Schilder an Punkten, die niemand zuordnen kann.
    const labelledEdges = useMemo(() => !sceneShown || !scopedNamedIds ? sceneShown?.edges
        : sceneShown.edges.filter(edge => scopedNamedIds.has(edge.source) && scopedNamedIds.has(edge.target)), [sceneShown, scopedNamedIds]);
    const hierarchyEdgeLabels = mode === 'hierarchy' && scopedProjection && !sceneTrailIds && sceneShown && labelledEdges?.length
        ? <HierarchyEdgeLabels nodes={sceneShown.nodes} edges={labelledEdges} layout={scopedSpots} nameBoxes={labelBoxes} /> : undefined;
    // Zweites Review zu K5: die Ueberschrift des Bandes der gemischt erreichten Knoten.
    const hierarchyBand = mode === 'hierarchy' && scopedProjection?.band ? <HierarchyBandLabel band={scopedProjection.band} /> : undefined;
    const overlay: ReactNode = (pulseRing === undefined && !liveOn && hierarchyEdgeLabels === undefined && hierarchyBand === undefined) ? undefined : (
        <>
            {pulseRing}
            {hierarchyEdgeLabels}
            {hierarchyBand}
            {liveOn && agentLayerOn && agentsView !== undefined && (
                <AgentLayer
                    actors={agentsView.actors}
                    effects={{
                        tails: props.agentEffects?.tails !== false,
                        trails: props.agentEffects?.trails !== false && agentPreference.trails,
                        waves: props.agentEffects?.waves !== false,
                    }}
                />
            )}
        </>
    );

    return (
        <section
            ref={panel}
            className="atlas-galaxy"
            data-testid="atlas-galaxy"
            data-visible={visible}
            data-state={state}
            data-mode={mode}
            data-fullscreen={fullscreen}
            data-replay={replayAt !== undefined}
        >
            <header className="atlas-galaxy-head">
                <div className="atlas-galaxy-head-row" data-hint-keep="graph head">
                    <span className="atlas-galaxy-title">GALAXY</span>
                    {/*
                      * Die beiden Ansichten sind ein Paar, und der Rahmen um sie
                      * sagt das, bevor jemand klickt.
                      *
                      * Nutzerbefund vom 2026-08-29: "galaxy Knopf macht nichts."
                      * Zwei Knoepfe nebeneinander, von denen einer wirklich
                      * etwas zuklappt und der andere ein Umschalter ist, sehen
                      * ohne Rahmen aus wie zwei Knoepfe derselben Art. Mit
                      * Rahmen, `role="group"` und `aria-pressed` ist zu sehen,
                      * dass genau EINER von ihnen aktiv ist.
                      *
                      * Seit W10b klappen sie ausserdem (Entscheidung 16), und
                      * `data-action` sagt an jedem Chip, was ein Klick JETZT
                      * tut: `collapse`, `open` oder `switch`. Nicht `data-fold`:
                      * die Marke gehoert den Schaltern, die nichts anderes tun
                      * als auf- und zuklappen (tools/smoke-w8b.mjs liest sie so),
                      * und diese hier tun je nach Lage zweierlei.
                      *
                      * `aria-pressed` bleibt dabei die GEWAEHLTE Ansicht und
                      * nicht die sichtbare: die Wahl ueberlebt das Zuklappen und
                      * ist es, was beim Aufklappen wieder dasteht. Ob die
                      * Sektion offen ist, sagt `data-open` am Rahmen und der
                      * beschriftete Schalter daneben in Worten.
                      */}
                    <div
                        className="atlas-graph-mode"
                        data-testid="atlas-graph-mode"
                        data-mode={mode}
                        data-open={visible}
                        role="group"
                        aria-label="which picture the panel shows"
                    >
                        {GRAPH_MODES.map((candidate) => {
                            const available = true;
                            const action = !visible
                                    ? 'open'
                                    : mode === candidate && candidate === 'galaxy' && !props.workspaceExpanded ? 'collapse' : 'switch';
                            return (
                                <Hint
                                    key={candidate}
                                    name={`graph-mode-${candidate}`}
                                    text={
                                        candidate === 'hierarchy' && projection === undefined
                                            ? props.workspaceExpanded ? galaxyHierarchyNoteText.unavailableWorkspace : galaxyHierarchyNoteText.unavailable
                                            : !visible
                                                ? graphModeCollapsedTitle(candidate)
                                                : mode === candidate && candidate === 'galaxy' && !props.workspaceExpanded
                                                    ? graphModeActiveTitle(candidate)
                                                    : candidate === 'galaxy'
                                                        ? 'galaxy: the whole project, laid out by the server'
                                                        : readerHierarchyActive ? 'hierarchy: incoming relationships, file definitions, and outgoing relationships'
                                                        : scopedProjection ? galaxyHierarchyText.hint(scope.direction, { mixed: scopedProjection.band?.count ?? 0, names: scopedNames,
                                                            budget: SCOPED_HIERARCHY_LABEL_BUDGET, neighbours: scopedNeighbours, sides: scopedNamedSides })
                                                        : 'hierarchy: what the chosen symbol reaches, one column per call depth'
                                    }
                                >
                                    <button
                                        type="button"
                                        className="atlas-graph-mode-chip"
                                        data-testid="atlas-graph-mode-chip"
                                        data-mode={candidate}
                                        data-active={mode === candidate}
                                        data-action={action}
                                        data-available={available}
                                        aria-pressed={mode === candidate}
                                        /* Hierarchy stays actionable while its root is missing or loading. */
                                        aria-disabled={!available}
                                        onClick={() => {
                                            if (visible && mode === candidate && candidate === 'galaxy' && !props.workspaceExpanded) {
                                                props.onToggleVisible?.();
                                                return;
                                            }
                                            setChosenMode(candidate);
                                            if (props.workspaceExpanded && !scope.scope && !activeWalk) setNote('');
                                            if (!visible) {
                                                props.onToggleVisible?.();
                                            }
                                        }}
                                    >
                                        {candidate}
                                    </button>
                                </Hint>
                            );
                        })}
                    </div>
                    <Hint
                        name="galaxy-legend"
                        text={
                            legendOpen
                                ? 'hide the legend: what the colours, sizes and positions mean'
                                : 'show the legend: what the colours, sizes and positions mean'
                        }
                    >
                        <button
                            type="button"
                            className="atlas-galaxy-legend-toggle"
                            data-testid="atlas-galaxy-legend-toggle"
                            aria-expanded={legendOpen}
                            aria-controls="atlas-galaxy-legend"
                            data-fold={legendOpen ? 'collapse' : 'open'}
                            data-fold-of="legend"
                            onClick={toggleLegend}
                        >
                            {legendFoldLabel(legendOpen)}
                        </button>
                    </Hint>
                    {/*
                      * Der Zuklapp-Schalter steht IM Kopf des Panels.
                      *
                      * Nutzerfeedback vom 2026-08-29: zugeklappt fiel das ganze
                      * Panel auf Hoehe null, und der einzige Weg zurueck war ein
                      * Menuepunkt, den man kennen musste. Der Kopf bleibt jetzt
                      * stehen, und der Schalter darin sagt in beiden Lagen, was
                      * ein Klick tut: seit W8b in Worten und mit dem Namen des
                      * Bildes, das gerade dasteht. Warum, steht an
                      * {@link graphFoldLabel}.
                      */}
                    {props.onToggleVisible !== undefined && !props.workspaceExpanded && (
                        <Hint
                            name="galaxy-collapse"
                            text={visible ? GALAXY_COLLAPSE_TITLE : GALAXY_EXPAND_TITLE}
                        >
                            <button
                                type="button"
                                className="atlas-galaxy-collapse"
                                data-testid="atlas-galaxy-collapse"
                                aria-expanded={visible}
                                data-fold={visible ? 'collapse' : 'open'}
                                data-fold-of={mode}
                                onClick={props.onToggleVisible}
                            >
                                {graphFoldLabel(visible, mode)}
                            </button>
                        </Hint>
                    )}
                </div>
                {showCoverage && props.workspaceExpanded && !scope.scope && <span className="atlas-galaxy-coverage-key">
                    <i aria-hidden="true" />{mode === 'hierarchy' ? 'Coverage shadow is shown in galaxy view' : coverageShadow
                        ? `Coverage shadow: ${coverageShadow.counts.files} files, ${coverageShadow.counts.folders} folders with index gaps`
                        : data?.missed_graph ? 'No coverage-shadow nodes reported' : 'Coverage shadow unavailable in this layout'}
                </span>}
                <span
                    className="atlas-galaxy-headline"
                    hidden={Boolean(scope.scope)}
                    data-testid="atlas-galaxy-headline"
                    data-state={state}
                >
                    {props.workspaceExpanded && mode === 'galaxy' && state === 'ready' && data
                        ? `${shown?.nodes.length.toLocaleString() ?? 0} of ${data.total_nodes.toLocaleString()} nodes · ${shown?.edges.length.toLocaleString() ?? 0} relationships`
                        : headline}
                </span>
                {edgeNote.length > 0 && !scope.scope && (
                    <span
                        className="atlas-galaxy-edgenote"
                        data-testid="atlas-galaxy-edgenote"
                        data-hidden-kinds={hiddenHere}
                        data-kinds={kinds.length}
                    >
                        {edgeNote}
                    </span>
                )}
            </header>
            {(props.workspaceExpanded || scope.scope) && <div className="atlas-graph-exploration" aria-label="Graph scope" ref={explorationBar}
                data-scoped={props.workspaceExpanded && scope.scope ? 'true' : undefined}>
                {historyControls}
                {props.workspaceExpanded && <GalaxyNavigator embedded nodes={layout?.nodes ?? []} project={project} fetch={fetchImpl} onSelect={handleNodeClick} onSelectScope={next => { props.onClearSelection?.(); setBackgroundCleared(false); clearTrail(); scope.select(next); }} />}
                {scope.scope ? <>
                    {props.workspaceExpanded && <button type="button" onClick={leaveScope} aria-label={galaxyHistoryText.allGraph} title={galaxyHistoryText.allGraphTitle}>
                        <FitLabel wide={galaxyHistoryText.allGraph} narrow={galaxyHistoryText.allGraphNarrow} /></button>}
                    {/*
                      * Handtest K3: die Wurzel ist zugleich der Weg zu ihrer
                      * Quelle. Ein eigener Knopf "Open source" daneben kostete die
                      * Zeile bei offenem Chat rund hundert Pixel; er steht fuer
                      * die Tastatur weiter im Menue "⋯".
                      */}
                    {props.workspaceExpanded && openRoot
                        ? <button type="button" className="atlas-graph-scope-name" data-fit-whole="" onClick={openRoot} aria-label={galaxyToolbarText.openRootLabel(rootShown)}
                            title={galaxyToolbarText.openRootTitle(rootShown, scopedRoot?.file_path ?? '', scopedRoot?.start_line)}>{rootShown}</button>
                        : <strong className="atlas-graph-scope-name" data-fit-whole="" title={scopeTitle(scope.scope)}>{rootShown}</strong>}
                    {props.workspaceExpanded && <select aria-label="Trace direction" title={galaxyToolbarText.traceTitle} value={scope.direction}
                        onChange={event => scope.setDirection(event.target.value as 'both' | 'inbound' | 'outbound')}>
                        <option value="both">Both directions</option><option value="inbound">Incoming</option><option value="outbound">Outgoing</option>
                    </select>}
                    {props.workspaceExpanded && <TraceEdgeFilter kinds={traceKinds} availableTypes={kinds.map(kind => kind.type)} selected={traceTypes} onChange={changeTraceTypes} />}
                    {/*
                      * Handtest K8: waehrend eine Ebene laedt, ist "−" der Weg
                      * hinaus. Es bricht das Laden ab und steht sofort wieder auf
                      * der vorigen, schon vollstaendigen Ebene.
                      */}
                    <button type="button" disabled={scope.depth <= scope.minDepth}
                        title={scope.loading ? galaxyLayerText.cancelLoading(scope.depth) : galaxyLayerText.removeLayer}
                        onClick={cancelOrRemoveLayer} aria-label="Remove graph layer">−</button>
                    <span>{scope.depth} {scope.depth === 1 ? 'layer' : 'layers'}</span>
                    {/*
                      * G3: die Erklaerung zu Expand ist lang, und als natives
                      * `title` kam sie erst nach der Verzoegerung des Browsers.
                      * Der eigene Tooltip steht sofort bei Hover und Fokus unter
                      * dem Knopf, auch in der knappen Form "+1", ueber der Szene.
                      * Gesperrt heisst `aria-disabled` und nicht `disabled`: ein
                      * abgeschalteter Knopf nimmt weder Zeiger noch Fokus, und
                      * gerade dann (Ebene unvollstaendig, Ende des Traces) ist der
                      * Grund das, was der Leser wissen will.
                      */}
                    <Hint name="galaxy-expand" text={expandTitle}>
                        <button type="button" aria-disabled={expandBlocked || undefined}
                            data-warning={expandWarning || undefined}
                            onClick={() => { if (!expandBlocked) scope.setDepth(scope.depth + 1); }} aria-label={galaxyToolbarText.expand}>
                            <FitLabel wide={galaxyToolbarText.expand} narrow={galaxyToolbarText.expandNarrow} /></button>
                    </Hint>
                    {props.workspaceExpanded && (mode === 'galaxy' || scopedProjection) && <>
                        <PathPicker nodes={pathCandidates} onPick={node => { setTrail({ key: organicKey, kind: 'path', target: node.id, name: graphNodeName(node) }); setTrailStep(0); }} />
                        <button type="button" disabled={rootCalls.length === 0} aria-pressed={trail?.key === organicKey && trail.kind === 'calls'}
                            title={rootCalls.length ? galaxyPathText.callOrderTitle : galaxyPathText.callOrderUnavailable}
                            onClick={() => { if (trail?.key === organicKey && trail.kind === 'calls') clearTrail(); else { setTrail({ key: organicKey, kind: 'calls' }); setTrailStep(0); } }}>
                            <FitLabel wide={galaxyPathText.callOrder} narrow={galaxyPathText.callOrderNarrow} /></button>
                    </>}
                    <span className="atlas-graph-scope-count" role="status" data-state={scopeState}
                        title={partial ? galaxyLayerText.partialTitle(partial.layer, partial.limit === 'nodes' ? nodeBudget : edgeBudget, partial.limit)
                            : [scopeStatus, scope.loading && scope.progress ? galaxyLayerText.loadingRequest(scope.progress.requests) : groupsText]
                                .filter(Boolean).join('. ')}>{scopeStatus}</span>
                    {scope.error && <span className="atlas-graph-scope-warning" title={scope.error}>Some relationships could not be loaded. <button type="button" onClick={scope.retry}>Retry</button></span>}
                    {!props.workspaceExpanded && scope.complete && <small>All indexed direct dependencies included.</small>}
                    {!props.workspaceExpanded && groupCount > 1 && <small className="atlas-graph-scope-groups" title={groupsText}>{galaxyToolbarText.groups(groupCount)}</small>}
                </> : null}
                {props.workspaceExpanded && <>
                    {/*
                      * Im Scope tritt der Deckel in ein Aufklappfeld zurueck
                      * (Review-Befund G7): die Leiste traegt dort Pfad,
                      * Aufrufreihe und Zaehler, und bei 1600 Pixeln brach die
                      * Zeile sonst um. Ein Scope liegt fast immer unter dem
                      * Deckel; im ganzen Graphen bleibt er in der Zeile.
                      */}
                    {/* K3: im Ausschnitt stehen Quelle, Limits, Gruppen und abgeschnittene Knoten im Menue "⋯". */}
                    {scope.scope ? <details className="atlas-graph-limits atlas-graph-more" title={galaxyToolbarText.moreTitle}
                        data-attention={outsideLimits ? 'true' : undefined} onKeyDown={event => {
                            if (event.key === 'Escape') { event.stopPropagation(); event.currentTarget.open = false; }
                        }}>
                        <summary aria-label={galaxyToolbarText.more}>{galaxyToolbarText.moreGlyph}</summary>
                        <div className="atlas-graph-limits-menu">
                            {openRoot && <button type="button" onClick={openRoot}>{galaxyToolbarText.openSource}</button>}
                            {renderLimits}
                            {groupCount > 1 && <small className="atlas-graph-scope-groups" title={groupsText}>{galaxyToolbarText.groups(groupCount)}</small>}
                            {outsideLimits && <small>{outsideLimits}</small>}
                        </div>
                    </details> : renderLimits}
                    {mode === 'galaxy' && !scope.scope && <label className="atlas-graph-coverage-filter" title="Show files and folders with indexing gaps">
                        <input type="checkbox" aria-label="Show coverage graph" checked={showCoverage} onChange={event => setViewPreferences({ coverageShadow: event.target.checked })} />
                        Coverage
                    </label>}
                    {!scope.scope && outsideLimits && <small>{outsideLimits}</small>}
                </>}
            </div>}
            {legendOpen && (
                /*
                 * Der Rahmen um die Legende traegt ihre Kante.
                 *
                 * Der Hinweis steht NEBEN dem scrollenden Kasten und nicht
                 * darin: was im Kasten steht, scrollt mit und waere genau dann
                 * weg, wenn er gebraucht wird. Er liegt darum absolut im
                 * Rahmen, faengt keine Klicks ab und deckt keinen Text zu; der
                 * Verlauf darunter loest die letzte Zeile auf, statt sie
                 * abzuschneiden, damit ein halber Satz an der Kante als
                 * Fortsetzung zu lesen ist und nicht als Fehler.
                 */
                <div className="atlas-galaxy-legend-frame" data-testid="atlas-galaxy-legend-frame">
                    <div
                        className="atlas-galaxy-legend"
                        id="atlas-galaxy-legend"
                        data-testid="atlas-galaxy-legend"
                        data-more-above={legendEdge.above}
                        data-more-below={legendEdge.below}
                        ref={legendBox}
                        onScroll={measureLegendEdge}
                    >
                        {legend.map((entry) => (
                            <p
                                className="atlas-galaxy-legend-entry"
                                data-testid="atlas-galaxy-legend-entry"
                                data-entry={entry.key}
                                key={entry.key}
                            >
                                <b>{entry.title}</b>
                                {entry.swatches.length > 0 && (
                                    <span className="atlas-galaxy-legend-swatches">
                                        {entry.swatches.map((swatch) => {
                                            const hidden = props.workspaceExpanded && scope.scope
                                                ? traceTypes !== undefined && !traceTypes.includes(swatch.label)
                                                : hiddenKinds.has(swatch.label);
                                            const dot = (
                                                <span
                                                    className="atlas-galaxy-legend-dot"
                                                    style={{ background: swatch.color }}
                                                    aria-hidden="true"
                                                />
                                            );
                                            const label = swatch.count === undefined
                                                ? swatch.label
                                                : `${swatch.label} ${swatch.count}`;
                                            /*
                                             * Ein Schalter nur dort, wo es etwas zu
                                             * schalten gibt: der graue Punkt der
                                             * Hierarchie steht fuer eine
                                             * Abwesenheit, und ein Knopf, der sie
                                             * ausblendet, waere ein Knopf ohne
                                             * Wirkung.
                                             */
                                            return entry.filterable === true ? (
                                                <Hint
                                                    key={swatch.label}
                                                    name={`legend-${swatch.label}`}
                                                    text={
                                                        hidden
                                                            ? `${swatch.label} is hidden: click to draw these edges again`
                                                            : `hide the ${swatch.label} edges; the kind stays here, dimmed`
                                                    }
                                                >
                                                    <button
                                                        type="button"
                                                        className="atlas-galaxy-legend-swatch"
                                                        data-testid="atlas-galaxy-legend-swatch"
                                                        data-type={swatch.label}
                                                        data-color={swatch.color}
                                                        data-count={swatch.count}
                                                        data-hidden={hidden}
                                                        aria-pressed={!hidden}
                                                        onClick={() => toggleKind(swatch.label)}
                                                    >
                                                        {dot}
                                                        {label}
                                                    </button>
                                                </Hint>
                                            ) : (
                                                <span
                                                    className="atlas-galaxy-legend-swatch"
                                                    data-testid="atlas-galaxy-legend-swatch"
                                                    data-type={swatch.label}
                                                    data-color={swatch.color}
                                                    key={swatch.label}
                                                >
                                                    {dot}
                                                    {label}
                                                </span>
                                            );
                                        })}
                                    </span>
                                )}
                                <span className="atlas-galaxy-legend-detail">{entry.detail}</span>
                            </p>
                        ))}
                    </div>
                    {(legendEdge.above || legendEdge.below) && (
                        <span
                            className="atlas-galaxy-legend-more"
                            data-testid="atlas-galaxy-legend-more"
                            data-scroll-hint={[
                                legendEdge.above ? 'top' : '',
                                legendEdge.below ? 'bottom' : '',
                            ].filter((part) => part.length > 0).join(' ')}
                            data-edge={legendEdge.below ? 'bottom' : 'top'}
                        >
                            {legendEdge.below ? '▾ more' : '▴ more'}
                        </span>
                    )}
                </div>
            )}
            <div className="atlas-galaxy-scene" data-testid="atlas-galaxy-scene" ref={scene}
                aria-busy={layoutLoading || scope.loading || organicTask.loading || spacingBusy}>
                <RenderProgress busy={visible && (layoutLoading || scope.loading || organicTask.loading || spacingBusy)}
                    {...(scope.scope && scope.loading ? { label: galaxyLayerText.previewLoading(scope.depth) } : {})} />
                {trailView && <PathSteps heading={trailView.heading} note={trailView.note} steps={trailView.steps} active={trailActive}
                    nameOf={trailView.nameOf} lines={trailView.lines} onStep={setTrailStep} onClear={clearTrail} />}
                {/*
                  * Der Weg zurueck zur eingepassten Ansicht (AC5).
                  *
                  * Er steht IN der Szene und nicht im Kopf, und das ist gemessen
                  * und nicht Geschmack: die Kopfzeile ist bei 440 Pixeln Breite
                  * mit Marke, Ansichts-Schalter, Legenden-Schalter und
                  * Zuklapper schon voll, und ein fuenftes Wort darin haette den
                  * Zuklapper an der Kante abgeschnitten. Hier liegt er ausserdem
                  * dort, wo der Leser gerade zieht und dreht. Dieselbe Bauform
                  * wie das Instrument der Agentenebene, nur in der anderen Ecke.
                  */}
                {visible && (
                    <Hint name="galaxy-fit" text={GALAXY_FIT_TITLE}>
                        <button
                            type="button"
                            className="atlas-galaxy-fit"
                            data-testid="atlas-galaxy-fit"
                            data-fits={fitCount.current}
                            onClick={refitNow}
                        >
                            {GALAXY_FIT_LABEL}
                        </button>
                    </Hint>
                )}
                {sceneShown !== undefined && everVisible.current && (
                    <GraphScene
                        active={visible}
                        separateNodes={mode === 'galaxy' && sceneScoped && sceneShown.nodes.length <= SCOPE_SEPARATION_LIMIT}
                        onRenderBusyChange={setSpacingBusy}
                        idleRotation={mode === 'galaxy' && !sceneScoped}
                        rootIds={mode === 'galaxy' && sceneScoped ? scope.result?.roots : undefined}
                        data={sceneShown}
                        display={display}
                        highlightedIds={sceneTrailIds ?? (scope.scope && scope.depth > 1 && mode === 'galaxy' ? null : highlighted)}
                        path={sceneTrailIds && trailView && scenePathSteps ? { steps: scenePathSteps, active: trailActive, labels: trailView.labels } : undefined}
                        emphasizeIncidentEdges={mode === 'galaxy' && Boolean(props.focusFilePath)}
                        cameraTarget={cameraTarget}
                        /*
                         * In der Hierarchie tragen alle Namen dieselbe
                         * Weltgroesse und eine Breitengrenze, die das
                         * Spaltenraster einhaelt. Warum, steht an den
                         * Konstanten in hierarchy-layout.ts. In der Galaxie
                         * bleibt es bei der Rechnung der Uebernahme.
                         */
                        labelWorldFontSize={
                            mode === 'hierarchy' ? HIERARCHY_LABEL_FONT_SIZE : undefined
                        }
                        labelMaxTextWidth={
                            mode === 'hierarchy' ? scopedProjection ? SCOPED_HIERARCHY_LABEL_MAX_TEXT_WIDTH : HIERARCHY_LABEL_MAX_TEXT_WIDTH : undefined
                        }
                        onLabelLayout={onLabelLayout}
                        /*
                         * Namen erst, wenn etwas im Fokus steht.
                         *
                         * Die Szene beschriftet die achtzig groessten Knoten,
                         * und in einem Panel dieser Breite sind achtzig
                         * Namen bei Uebersichtsabstand kein Text, sondern
                         * Rauschen: sie ueberlagern sich zu Flecken, die wie
                         * ein Rendering-Fehler aussehen. Steht ein Symbol im
                         * Fokus, beschriftet dieselbe Szene nur noch dessen
                         * Nachbarschaft, und dann ist jeder Name lesbar und
                         * jeder Name eine Antwort auf die Frage, die gerade
                         * gestellt wurde.
                         *
                         * In der Hierarchie sind die Namen immer an: dort
                         * stehen hoechstens sechzig Punkte (im Ausschnitt
                         * 150, Review zu K5), und eine Aufrufkette ohne
                         * Namen waere eine Reihe Punkte.
                         */
                        showLabels={
                            mode === 'hierarchy'
                                ? scopedProjection ? scopedNames === 'all' || Boolean(scopedNamedIds?.size) : sceneShown.nodes.length <= HIERARCHY_LABEL_BUDGET
                                : trailIds !== undefined || (highlighted !== null && highlighted.size > 0)
                        }
                        labelBudget={mode === 'hierarchy' && scopedProjection ? SCOPED_HIERARCHY_LABEL_BUDGET : undefined}
                        labelIds={mode === 'hierarchy' ? scopedNamedIds : undefined}
                        /*
                         * Landmarken nur in der Galaxie: der Halo sitzt auf den
                         * groessten Knoten, und "gross" heisst in der Projektion
                         * mal "viele Kanten im ganzen Graphen" und mal "keine
                         * Layout-Angabe". Ein Leuchten darauf waere eine
                         * Behauptung, die die halbe Zeit nichts bedeutet.
                         */
                        landmarks={mode === 'galaxy' && choice.halos}
                        /*
                         * Die vier Einstellungen aus dem Panel (W10). Sie gehen
                         * unveraendert durch: was sie bedeuten, steht in
                         * density.ts, und was sie in der Szene tun, in
                         * GraphScene.tsx.
                         */
                        projection={choice.projection}
                        drawEdges={choice.edges !== 'off'}
                        labelDistanceFactor={choice.labelDistanceFactor}
                        frameCap={choice.frameCap}
                        onNodeClick={handleNodeClick}
                        coverageShadow={coverageShadow}
                        onShadowNodeClick={(node) => {
                            if (coverageShadow) flyTo(coverageShadow.nodes, coverageShadow.ids, node.qualified_name ?? node.name);
                            props.onSelectShadowNode?.(node);
                            setNote(`${node.file_path ?? node.name}: coverage shadow. Detailed indexing reasons are not included in this layout.`);
                        }}
                        renderShadowTooltip={(node) => <HoverCardHtml position={[node.x, node.y, node.z]}>
                            <div className="atlas-coverage-tooltip"><b>{node.file_path ?? node.name}</b><p>Coverage shadow: not fully indexed.</p></div>
                        </HoverCardHtml>}
                        onBackgroundClick={handleBackgroundClick}
                        renderTooltip={(node) => <NodeTooltipCard node={node} />}
                        overlay={overlay}
                    />
                )}
                {/* Zweites Review zu K5: fehlen Namen, sagt das Bild es selbst, und wie man sie bekommt. */}
                {mode === 'hierarchy' && scopedProjection && scopedNames !== 'all' && (
                    <p className="atlas-hierarchy-key" data-testid="atlas-hierarchy-key">
                        {galaxyHierarchyText.namesNote(scope.direction, scopedProjection.data.nodes.length, scopedNames, scopedNeighbours, SCOPED_HIERARCHY_LABEL_BUDGET, scopedNamedSides)}
                    </p>
                )}
                {state !== 'ready' && (
                    <p className="atlas-galaxy-placeholder" data-state={state}>
                        {headline}
                        {mode === 'hierarchy' && state !== 'loading' && <><br /><button type="button" data-testid="atlas-hierarchy-choose-root" onClick={() => setChosenMode('galaxy')}>Choose a symbol in the galaxy</button></>}
                    </p>
                )}
                {/*
                  * Das Instrument liegt IM Kasten der Szene und nicht darunter:
                  * es erklaert, was auf dem Graphen zu sehen ist, und ein Kasten
                  * daneben waere eine zweite Flaeche, die man zwischen Bild und
                  * Text hin und her lesen muesste. Es ist deckend (Review zu
                  * K29) und faengt seine eigenen Klicks ab; der Rest der Flaeche
                  * bleibt die Szene.
                  */}
                {liveOn && agentsView !== undefined && props.agents !== undefined && (
                    <AgentsHud
                        view={agentsView}
                        status={props.agents.status}
                        port={props.agents.port}
                        size={agentPreference.size}
                        onSize={(size: HudSize) => changeAgentPreference({ size })}
                        filter={agentPreference.filter}
                        onFilter={(filter: ActorFilter) => changeAgentPreference({ filter })}
                        switches={{
                            follow: agentPreference.follow,
                            trails: agentPreference.trails,
                            fullscreen: agentPreference.fullscreen,
                        }}
                        onSwitch={(name: keyof HudSwitches) =>
                            changeAgentPreference({ [name]: !agentPreference[name] })}
                        trailWindowMs={agentPreference.trailWindowMs}
                        onTrailWindow={(trailWindowMs: number) =>
                            changeAgentPreference({ trailWindowMs })}
                        layerOn={agentLayerOn}
                        column={fullscreen}
                    />
                )}

                {/*
                  * Der Streifen unten: die Ereigniszeile des FOLLOW-Modus und
                  * darunter der Zeitstrahl.
                  *
                  * Beide in EINEM Stapel und nicht zwei Mal absolut positioniert:
                  * sie stehen beide unten, ihre Hoehen haengen an der Zahl der
                  * Akteure, und zwei Kaesten, die sich mit wachsender Zahl
                  * ineinander schieben, waeren eine Ueberlagerung, die erst beim
                  * neunten Agenten auffaellt. Der Stapel endet vor dem
                  * Instrument, damit auch dort nichts uebereinander liegt.
                  *
                  * Er erscheint erst ab {@link TIMELINE_MIN_WIDTH} Pixeln
                  * Zeichenflaeche, und die Grenze ist gemessen: rechts steht das
                  * Instrument, und was links davon uebrig bleibt, traegt in
                  * einem Panel von 441 Pixeln weder eine lesbare Zeile noch eine
                  * Spur, auf der ein Strich vom naechsten zu unterscheiden ist.
                  */}
                {liveOn && sceneWidth >= TIMELINE_MIN_WIDTH && (
                    <div className="atlas-galaxy-bottom" data-testid="atlas-galaxy-bottom">
                        {agentPreference.follow && followLine !== undefined && (
                            <Hint name="agents-followline" text={agentText.followLineTitle}>
                                <p
                                    className="atlas-agents-followline"
                                    data-testid="atlas-agents-followline"
                                    data-actor={followLine.id}
                                    data-kind={followLine.kind}
                                    data-place={followLine.placement.name}
                                    data-lines={(followLine.last.lines ?? []).join('-')}
                                    style={{ ['--atlas-agent-color' as string]: followLine.color }}
                                >
                                    {agentText.followLine(
                                        followLine.name,
                                        WORK_KIND_WORD[followLine.kind],
                                        followLine.placement.name,
                                        followLine.last.lines ?? [],
                                    )}
                                </p>
                            </Hint>
                        )}
                        {timelineShown && timeline !== undefined && (
                            <AgentsTimeline
                                timeline={timeline}
                                now={agentNow}
                                windowMs={agentPreference.trailWindowMs}
                                onWindow={(trailWindowMs: number) =>
                                    changeAgentPreference({ trailWindowMs })}
                                onPause={() =>
                                    setPausedAt((current) =>
                                        (current === undefined ? Date.now() : undefined))}
                                onScrub={(ts: number) => setReplayAt(ts)}
                                onLive={() => {
                                    setReplayAt(undefined);
                                    setPausedAt(undefined);
                                }}
                            />
                        )}
                    </div>
                )}
            </div>
            {selectionContent && <details className="galaxy-selection-evidence atlas-galaxy-selection-details" aria-label="Selection evidence">
                <summary>Selection details</summary>
                <div className="atlas-galaxy-selection-details-body">{selectionContent}</div>
            </details>}
            {note.length > 0 && !scope.loading && !organicTask.loading && (
                <p className="atlas-galaxy-note" data-testid="atlas-galaxy-note">
                    {props.workspaceExpanded && note === GALAXY_NO_FOCUS_NOTE
                        ? 'Select a node or entry point to attach graph context to chat.' : note}
                </p>
            )}
        </section>
    );
}