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.

225 KB
Raw Blame
/**
 * Die Verdrahtung: Projekt aus der Adresszeile, Baum aus dem Graphen, Datei in
 * den Reader.
 *
 * Hier steht der Zustand und sonst nichts Darstellendes. Das Chrome
 * (src/app/AtlasChrome.tsx) bekommt fertige Werte, der Reader
 * (src/reader/MonacoReader.tsx) bekommt ein fertiges Dokument. Diese Datei ist
 * die einzige, die weiss, dass es einen Server gibt.
 *
 * Drei Entscheidungen, die man sonst raten muesste:
 *
 * 1. **Das Projekt kommt aus `?project=`.** Fehlt der Parameter, wird das erste
 *    Projekt aus `list_projects` genommen. Gibt es keins, sagt die Oberflaeche
 *    "no project" und zeigt keinen Baum, statt einen leeren zu zeigen: ein
 *    leerer Baum waere die Behauptung, das Projekt sei leer.
 * 2. **Der Baum wird beim Laden aufgeklappt.** `/api/tree` antwortet je Anfrage
 *    mit einer Ebene, und ein Explorer, der mit zwei zugeklappten Ordnern
 *    startet, zeigt von einem indizierten Projekt so gut wie nichts. Es wird
 *    breitenweise nachgeladen, bis ein Deckel erreicht ist; was danach noch
 *    offen ist, bleibt zugeklappt und laedt beim Klick. Der Deckel wird
 *    genannt, wenn er greift.
 * 3. **Eine Datei kommt ueber ihren Modul-Knoten.** Warum es keinen anderen Weg
 *    gibt und was das kostet, steht in src/reader/file-source.ts.
 *
 * Dazu kommt seit W2b die Caret-Strecke des Twins, und die hat drei eigene
 * Entscheidungen:
 *
 * 4. **Aufloesen wird entprellt, Hervorheben nicht.** Ein Caret, der durch eine
 *    Funktion wandert, soll das Badge sofort mitnehmen, aber nicht bei jedem
 *    Tastendruck den Graphen fragen. Also wandert `caretLine` sofort und
 *    `settledCaret` nach 250 ms, und nur das zweite loest auf.
 * 5. **Dasselbe Symbol wird nicht zweimal geholt.** Der Cache in
 *    src/twin/ir-cache.ts schluesselt ueber den qualifizierten Namen und legt
 *    gleichzeitige Anfragen zusammen; hier kommt nur die Regel dazu, bei
 *    unveraendertem Subjekt gar nicht erst in den Ladezustand zu gehen, damit
 *    das Panel beim Wandern des Carets nicht blinkt.
 * 6. **Folgen wechselt das Subjekt sofort und laesst den Editor nachkommen.**
 *    Der Kopf des Panels nennt ab dem Klick das neue Symbol und der Koerper
 *    sagt, dass gelesen wird. Die Fakten kommen erst, wenn der Caret in der
 *    Zieldatei aufgeloest ist: eine IR, die aus dem Klickziel statt aus einer
 *    Aufloesung gebaut waere, traege eine erfundene Symbolart, und "This is a
 *    piece of code" ueber einer Funktion ist genau die Sorte kleiner Luege,
 *    gegen die dieses Panel gebaut ist.
 *
 * Seit W3 kommen die Galaxie und die Bedeutungssuche dazu, mit drei weiteren
 * Entscheidungen:
 *
 * 7. **Der Fokus laeuft in beide Richtungen ueber genau einen Schluessel.**
 *    Das Twin-Subjekt reist als qualifizierter Name zur Galaxie, die Galaxie
 *    schickt einen angeklickten Knoten als Ziel zurueck durch denselben
 *    `followTarget`, den auch der Twin benutzt. Es gibt also keinen zweiten
 *    Navigationsweg, den man vergessen koennte zu pflegen, und keine zweite
 *    Stelle, an der ein Symbol identifiziert wird.
 * 8. **Ein Klick in die Galaxie behauptet nichts ueber das Symbol.** Er
 *    oeffnet die Datei an der gemeldeten Zeile; was dort steht, sagt die
 *    Aufloesung, so wie beim Folgen aus dem Twin. Der Grund ist derselbe wie
 *    in Entscheidung 6.
 * 9. **Getippt wird ohne Anfrage, gefragt wird nach 200 ms Ruhe.** Die
 *    Kommandozeile ist eine Suche und kein Terminal: sie schickt keine Zeile
 *    ab, sie zeigt waehrend des Tippens, was der Index kennt. Ohne die
 *    Entprellung waere jede Taste ein Sweep ueber den Graphen.
 *
 * Seit W4a kommen die Einstiegsmodi dazu, und mit ihnen vier weitere:
 *
 * 10. **Die Frage nach dem Warum ist eine Flaeche, kein Dialog.** Sie fuellt
 *     den leeren Editorbereich, wenn keine Datei offen ist und dieser Browser
 *     fuer dieses Projekt noch keine Antwort kennt. Ein Modal beim ersten
 *     Oeffnen wuerde die Oberflaeche und jeden automatisierten Lauf durch sie
 *     blockieren; das ist die Begruendung des Referenzprojekts und sie gilt
 *     hier unveraendert.
 * 11. **Eine Antwort setzt genau eine Sache und wird dann vergessen.** Sie
 *     setzt das Leseprofil des Twins (Tiefe und Linsen, Zuordnung in
 *     why/why-model.ts) und wird gespeichert, damit die Frage nicht wieder
 *     kommt. Niemand fragt den Intent spaeter zurueck: ein weitergereichter
 *     Intent waere ein Modus, und ein Modus ist ein zweites Produkt im ersten.
 * 12. **Ein Schritt bewegt den Reader ueber dieselbe Strecke wie ein Klick.**
 *     Ein Symbolschritt geht durch `followTarget`, ein Dateischritt durch
 *     `openFile`. Es gibt keinen zweiten Navigationsweg fuer Fuehrungen, also
 *     auch keine zweite Stelle, an der ein Symbol identifiziert wird, und der
 *     Twin folgt einem Schritt aus demselben Grund, aus dem er einem Klick
 *     folgt.
 * 13. **Die stille Anzeige zaehlt Wege, nie Zeit.** Beim Betreten eines
 *     Schrittes und beim Folgen einer Zeile wird ein Checklisten-Item als
 *     besucht vermerkt. Verweildauer ist keine Evidenz, und die Statusleiste
 *     zeigt gar keinen Zaehler, solange es keine Checkliste zu zaehlen gibt,
 *     statt "0 of 0" zu behaupten.
 *
 * Seit W4b sind die beiden letzten Karten der Frage scharf, und mit ihnen
 * kommen drei weitere Entscheidungen:
 *
 * 14. **Der BUG-Assistent uebernimmt das Subjekt des Twins und schiebt
 *     nichts zurueck.** Er liest neu, wenn ein anderes Symbol vor dem Leser
 *     steht, und veroeffentlicht selbst nichts: wer zwei Pfade vergleicht, hat
 *     nicht darum gebeten, dass Reader, Twin und Galaxie unter ihm wegwandern.
 *     Nur ein Klick auf einen Hop navigiert, und der loest den Namen in diesem
 *     Moment auf, statt einen gespeicherten Verweis zu benutzen.
 * 15. **Ein kaputter Ref wird hier abgelehnt und nicht dort.** `detect_changes`
 *     nimmt ein unbekanntes `since` kommentarlos an und antwortet ueber den
 *     Arbeitsbaum. Ein Tippfehler ergaebe also eine plausible Antwort auf eine
 *     andere Frage, und deshalb prueft `refRejection` die Form im Browser und
 *     der Aufruf unterbleibt. Der Beweislauf zaehlt die Anfragen am Proxy und
 *     liest diese Zahl als die Behauptung.
 * 16. **Die beiden Flaechen schliessen einander aus.** Beide brauchen den
 *     ganzen Platz ueber dem Editor, und zwei ganze Antworten uebereinander
 *     waeren keine. Escape schliesst, was offen ist; das [a]tlas-Menue macht
 *     beim Oeffnen der einen die andere zu.
 *
 * Seit W4e reicht diese Datei eine Antwort weiter, die sie bisher wegwarf:
 *
 * 17. **Der Walk bleibt liegen, solange seine Fuehrung laeuft.** `getClosure`
 *     liefert einen Graphen; daraus eine Schrittliste zu machen und den Graphen
 *     zu vergessen hiess, die Tiefe wegzuwerfen, die in ihm steht. Also haelt
 *     `walk` ihn, und das Graph-Panel zeigt ihn als Hierarchie ab dem
 *     gewaehlten Einstiegspunkt. Er endet, wenn die Fuehrung endet: ein Bild
 *     einer beendeten Frage waere eine Antwort, nach der niemand mehr fragt.
 */
import type { JSX, KeyboardEvent } from 'react';
import { useCallback, useEffect, useMemo, useRef, useState } from 'react';

import AtlasChrome, { CLOSE_COMMAND_SEARCH_EVENT, OPEN_COMMAND_SEARCH_EVENT } from './app/AtlasChrome';
import { AtlasTreeIndexDetails } from './app/AtlasTree';
import ArchitecturePanel from './architecture/ArchitecturePanel';
import AdrWorkspace from './adr/AdrWorkspace';
import SelectionContextPanel, { type SelectionScope } from './why/SelectionContext';
import FileImpactSummary from './impact/FileImpactSummary';
import SourceEvidenceDrawer, { fileQualifiedName, type SourceEvidenceTarget } from './architecture/SourceEvidenceDrawer';
import { setUiLogProject } from './app/ui-log-install';
import DiagnosticsPanel from './diagnostics/DiagnosticsPanel';
import { resolveRepositorySelection, useRepositorySnapshot } from './architecture/repository-source';
import ActivityPanel from './agents/ActivityPanel';
import WelcomePanel from './app/WelcomePanel';
import BrowserChatDock from './browser-ai/BrowserChatDock';
import { switchKeepingAgent } from './browser-ai/agent-handover';
import { browserChatHistoryProjectKey } from './browser-ai/chat-history-cache';
import type { BrowserChatAttachment } from './browser-ai/BrowserChatDock';
import { browserGraphContext } from './browser-ai/graph-context';
import { readerChatContext, type ReaderSourceOrigin } from './browser-ai/reader-chat-context';
import type { BrowserChatContext } from './browser-ai/chat-model';
import { selectionEvidenceContext } from './galaxy/selection-evidence';
import SystemWorkspace from './system/SystemWorkspace';
import type { Workspace, Guidance } from './app/workspace-strings';
import { allowedWorkspace, initialWorkspace, workspaceStrings as workspaceText } from './app/workspace-strings';
import { experimentalAgentsEnabled } from './app/feature-flags';
import type { Chip, MenuExtra, MenuWiring, TabDescriptor } from './app/AtlasChrome';
import { AtlasApi, TREE_ROUTE } from './app/atlas-api';
import { ATLAS_BUILD_SUFFIX, ATLAS_VERSION } from './app/build-info';
import { messages } from './i18n/messages';
import {
    KEY_LISTENER_OPTIONS,
    menuShortcutFor,
    tourKeyForEvent,
} from './app/keyboard';
import { markHandled } from './app/key-probe';
import { WIRED_MENU_SHORTCUTS } from './app/shortcuts';
import { baseName, pathSegments } from './app/module-qn';
import HelpOverlay from './help/HelpOverlay';
import {
    directoryPaths,
    EMPTY_COVERAGE,
    flattenTree,
    mergeCoverageIntoLevels,
    moveCursor,
    parentPath,
    treeIntent,
} from './app/tree-model';
import type { CoverageIndex, CoverageState, TreeLevel, TreeRow } from './app/tree-model';
import { loadCoverage, loadPathCoverage } from './app/coverage-source';
import { keepsReadyTwinForTarget } from './app/ready-twin-target';
import type { CoveragePathAnswer } from './app/tree-model';
import {
    freshnessNote,
    freshnessNoteNeeded,
    partialFileNote,
    readerUnavailableNote,
} from './app/coverage-strings';
import { RpcIntelligenceClient } from './provider/rpc-client';
import { CbmRpcProvider, symbolKindOf } from './provider/cbm-rpc-provider';
import MonacoReader from './reader/MonacoReader';
import type { ReaderStatus, ReaderSelection } from './reader/MonacoReader';
import { FileNotReadableError, loadFileDocument, READER_RPC_TOOL } from './reader/file-source';
import type { ReaderDocument } from './reader/file-source';
import { badgesForLines } from './core/step-badge-decorator';
import type { SymbolRef } from './core/focus-protocol';
import type { SemanticIR } from './core/semantic-ir';
import { buildIr } from './ir/semantic-ir-builder';
import { PseudocodeView, type TwinStatus } from './twin/TwinPanel';
import SelectedCodePanel from './twin/SelectedCodePanel';
import { loadFileSymbols, type FileSymbolResult } from './twin/selected-code-context';
import { inspectorChatContext, matchingInspectorIr, type SelectedCodeSnapshot } from './twin/selected-code-snapshot';
import { IrCache } from './twin/ir-cache';
import { ATLAS_WORKSPACE_ROOT, twinLocationOf, twinTargetOf, workspacePathOf } from './twin/twin-target';
import GalaxyPanel from './galaxy/GalaxyPanel';
import { targetRefOfNode } from './galaxy/galaxy-model';
import { hierarchySymbolOf, useSelectionHierarchy } from './galaxy/selection-hierarchy';
import { markedSourceRange, symbolMatchesReader } from './galaxy/reader-graph-focus';
import type { GraphData, GraphNode } from './galaxy/types';
import SearchOverlay from './search/SearchOverlay';
import type { SearchOverlayStatus } from './search/SearchOverlay';
import {
    SEARCH_DEBOUNCE_MS,
    SEARCH_MIN_QUERY,
    findByMeaning,
    searchByMeaning,
} from './search/find-by-meaning';
import type { RankedHit } from './search/semantic-search';
import {
    commandExamplesFor,
    exampleSymbolOf,
} from './search/command-examples';
import { EMPTY_LOCAL_INDEX, localCandidates, rankLocalCandidates, settledSearchHits } from './search/local-suggestions';
import type { LocalIndex } from './search/local-suggestions';
import {
    isSearchable,
    MAX_SEARCH_ROWS,
    moveSelection,
    overlayIntent,
    searchHeadline,
    searchRows,
} from './search/overlay-model';
import type { SearchRow, SearchRowSource } from './search/overlay-model';
import { Facet } from './twin/presentation-profile';
import type { PresentationProfile } from './twin/presentation-profile';
import type { TwinRow } from './twin/twin-view-model';
import WhyPanel from './why/WhyPanel';
import { WHY_MENU_LABEL } from './why/why-model';
import type { WhyIntent } from './why/why-model';
import { readWhyAnswer, recordWhyAnswer } from './why/why-store';
import type { WhyAnswer } from './why/why-store';
import TourCard from './tours/TourCard';
import { generateProjectTour } from './tours/tour-source';
import { entryWalkTour } from './tours/entry-walk';
import type { ActiveTour } from './tours/entry-walk';
import { isLastStep, playerIntent, stepMove } from './tours/tour-player';
import { markableItemId } from './tours/tour-model';
import { getClosure } from './provider/closure';
import type { ClosureResult } from './provider/closure';
import FlowOverlay from './pseudocode/FlowOverlay';
import { buildFlowView, FLOW_CLOSURE_CAP, FLOW_CLOSURE_DEPTH } from './pseudocode/flow-view';
import type { FlowView } from './pseudocode/flow-view';
import { buildImportsGroup } from './pseudocode/imports-group';
import type { ImportsGroup } from './pseudocode/imports-group';
import { fileImportsFor } from './pseudocode/imports-source';
import { buildPseudocode, closureDocumentOf } from './pseudocode/pseudocode-builder';
import type { PseudocodeDocument, PseudocodeSourceRef } from './pseudocode/pseudocode-builder';
import { FLOW_LOADING, FLOW_UNAVAILABLE } from './pseudocode/pseudocode-strings';
import EntryPointDialog from './entry/EntryPointDialog';
import type { EntrySearchStatus } from './entry/EntryPointDialog';
import { entryHeadline, entryRows, routeNote } from './entry/entry-model';
import type { ArchitectureOverviewDto, SymbolSearchHit } from './core/intelligence-provider';
import {
    browserStore,
    exploredLabel,
    markVisited,
    readUnderstanding,
    totalMarks,
    understandingOf,
} from './checklist/understanding-store';
import type { UnderstandingRecord } from './checklist/understanding-store';
import {
    TWIN_EMPTY_HINT,
    TWIN_EMPTY_MESSAGE,
    TWIN_FILE_NOT_INDEXED,
    TWIN_FILE_NOT_INDEXED_HINT,
    TWIN_LOADING,
    TWIN_LOAD_FAILED,
} from './twin/strings';
import BugWizard from './traces/BugWizard';
import type { BugWizardStatus } from './traces/BugWizard';
import { bugPaths, resolveHop } from './traces/bug-paths';
import type { BugPathNode, BugPathsDto } from './traces/bug-paths';
import { BUG_WIZARD_MENU_LABEL } from './traces/bug-wizard-strings';
import { SIDECAR_ORIGIN } from './llm/sidecar';
import type { CacheModel, SidecarReading, SidecarState } from './llm/sidecar';
import AtlasChatPanel from './chat/AtlasChatPanel';
import { askAtlas } from './chat/ask-atlas';
import type { ChatTurn } from './chat/ask-atlas';
import { commandIntent } from './chat/command-intent';
import {
    CHAT_HINT_OFF,
    CHAT_HINT_READY,
} from './chat/chat-strings';
import ExplainZone from './layout/ExplainZone';
import Splitter from './layout/Splitter';
import { explainTabs } from './layout/explain-tabs';
import type { ExplainTabId, ExplainTabState } from './layout/explain-tabs';
import { lineCommandOf } from './layout/layout-command';
import {
    LAYOUT_KEYS,
    clampLayout,
    clampLayoutValue,
    defaultLayout,
    layoutBounds,
    layoutStorageKey,
    readLayout,
    sameLayout,
    writeLayout,
} from './layout/layout-model';
import type { LayoutFrame, LayoutKey, LayoutSizes } from './layout/layout-model';
import { NEIGHBOR_DEPTHS, NEIGHBOR_DEPTH_DEFAULT } from './compiler/fact-recipes';
import type { NeighborDepth, ObservedFact, SubjectCandidate } from './compiler/fact-recipes';
import { modelClassOf } from './compiler/card-compiler';
import type { CardSource } from './compiler/card-compiler';
import { applyRefinement } from './pseudocode/refine';
import { readLlmPolicy } from './llm/policy';
import type { PolicyReading } from './llm/policy';
import { resolveLlmState } from './llm/llm-state';
import { llmChipValue } from './llm/strings';
import SettingsPanel from './settings/SettingsPanel';
import ConfigPanel from './settings/ConfigPanel';
import type { SettingsMeasurement } from './settings/SettingsPanel';
import AddProjectIndexDialog from './projects/AddProjectIndexDialog';
import ProjectSwitcher from './projects/ProjectSwitcher';
import type { ProjectsSource } from './projects/ProjectsPanel';
import { ProjectWindows, useParamInAddress, type ProjectWindow } from './app/project-windows';
import { MODEL_SUGGESTIONS, fetchCommand } from './settings/model-catalog';
import { modelKey, readModelPreference, recordModelPreference } from './settings/model-preference';
import {
    DEFAULT_GRAPH_DISPLAY,
    displayKey,
    isDefaultDisplay,
    loadDisplaySettings,
    saveDisplaySettings,
} from './galaxy/density';
import type { GraphDisplaySettings } from './galaxy/density';
import { bridgePortFromSearch, useAgentStream } from './agents/agent-source';
import { agentsMenuLabel } from './agents/agent-strings';

/**
 * Wie viele Ebenen beim Start von selbst nachgeladen werden.
 *
 * Der Deckel ist da, weil jede Ebene eine eigene Anfrage ist: ein Repository
 * mit tausend Verzeichnissen waere sonst tausend Anfragen beim ersten Bild.
 * Vierzig Ebenen decken die Fixtures und jedes normale Projekt ab; was darueber
 * liegt, klappt der Benutzer selbst auf und die Oberflaeche sagt es ihm.
 */
export const EAGER_LEVEL_BUDGET = 40;

/**
 * Wie lange der Caret stehen muss, bevor gefragt wird.
 *
 * 250 ms ist die Spanne, in der ein Leser mit den Pfeiltasten durch einen
 * Rumpf geht, ohne stehenzubleiben. Kuerzer, und jede Zeile waere eine Frage an
 * den Graphen; laenger, und das Panel haengt spuerbar hinter dem Caret.
 */
export const TWIN_CARET_DEBOUNCE_MS = 250;

/**
 * Start with the supported facts at depth two. Runtime and Changes remain
 * opt-in because their unavailable states otherwise add noise to the panel.
 */
export const TWIN_PROFILE: PresentationProfile = {
    id: 'custom:codeatlasweb-twin',
    label: messages.twin.profileLabel,
    depth: 2,
    facets: [Facet.Logic, Facet.Calls, Facet.Data, Facet.Errors, Facet.Tests],
    terminology: 'technical',
    conceptCallouts: false,
    panels: [],
    aiChangeWatcher: false,
};

/**
 * Die Adressparameter, mit denen die Grenzen des Vorwaerts-Walks von aussen
 * gesetzt werden koennen.
 *
 * Dieselben zwei Namen wie im Referenzprojekt (pseudocode-service.ts), und sie
 * sind kein Debug-Schalter: die Karte sagt am Ende eines gekappten Walks, dass
 * sie gekappt wurde, und dieser Satz muss an einem echten Lauf zu sehen sein,
 * nicht nur in einem Unit-Test. An einem Projekt mit zehn Dateien kappt der
 * Vorgabe-Deckel von fuenfzehn Symbolen nichts; mit `?codeatlasClosureCap=3`
 * kappt er, und der Beweislauf liest den Satz dort, wo ein Leser ihn saehe.
 */
export const CLOSURE_DEPTH_PARAM = 'codeatlasClosureDepth';
export const CLOSURE_CAP_PARAM = 'codeatlasClosureCap';

/*
 * Die sichtbaren Saetze dieser Datei stehen seit W6a im Katalog
 * (src/i18n/messages.ts) und werden hier nur noch unter ihren bisherigen Namen
 * weitergereicht. Die Namen bleiben, weil sie exportiert sind und anderswo
 * gelesen werden; der Wortlaut hat jetzt genau eine Quelle.
 */

/** Was die Statusleiste sagt, wenn eine Fuehrung nicht zustande kam. */
export const TOUR_FAILED = messages.tour.failed;

/** Was in der Kommandozeile steht, wenn nichts gesucht wird. */
export const COMMAND_HINT_IDLE = messages.command.hintIdle;
/** Was dort steht, waehrend das Fenster offen ist. */
export const COMMAND_HINT_OPEN = messages.command.hintOpen;
/** Was das Trefferfenster sagt, solange erst ein Zeichen getippt ist. */
export const COMMAND_ONE_MORE_LETTER = messages.search.oneMoreLetter;
/** Was das Fenster sagt, wenn die Suche selbst gescheitert ist. */
export const SEARCH_FAILED = messages.search.failed;
/** Was es sagt, wenn ein gewaehlter Treffer keine Datei traegt. */
export const SEARCH_NO_FILE = messages.search.noFile;

const emptyLevels = new Map<string, TreeLevel>();
const noBadges: ReturnType<typeof badgesForLines> = [];
const noHits: RankedHit[] = [];
/** Das Trefferfenster ohne Treffer, als stabile Referenz. */
const noRows: SearchRow[] = [];

/**
 * Die beiden Griffe, an denen der Beweislauf die Fuehrung und die stille
 * Anzeige anfasst.
 *
 * Absichtlich schmal, wie die Griffe des Readers, des Twins und der Galaxie:
 * alles davon steht auch im DOM, der Griff spart dem Lauf das Parsen und macht
 * zwei Dinge ueberhaupt messbar, naemlich "dasselbe Dokument zweimal" und "die
 * Zahl der Vermerke ist gestiegen".
 */
export interface AtlasTourSeam {
    id: string;
    kind: 'project' | 'entry';
    title: string;
    steps: number;
    index: number;
    paths: string[];
    titles: string[];
    endNote: string;
    /** Das Dokument, wie es gerade gelaufen wird. */
    json: string;
    /** Noch einmal erzeugen und serialisieren. Nur fuer die Projekt-Fuehrung. */
    regenerate?: () => Promise<string>;
}

/**
 * Der Griff, an dem der Beweislauf den Coverage-Join anfasst.
 *
 * Er traegt genau das, was auch im DOM steht, und spart dem Lauf das Parsen.
 * Die Zeilen kommen mit ihrer Stufe, weil "der Baum zeigt exakt das Gemessene"
 * sonst nur ueber Screenshot-Vergleiche pruefbar waere, und ein Bild ist keine
 * Behauptung ueber Pfade.
 */
export interface AtlasCoverageSeam {
    rows: { path: string; kind: string; coverage: string; reason: string; sources: string[] }[];
    /** Je Pfad genau ein Befund, so wie der Join ihn haelt. */
    records: { path: string; kind: string; state: string; reason: string; sources: string[] }[];
    truncations: string[];
    counts: CoverageIndex['counts'];
    /** Die Metadaten des Coverage-Stores, inklusive der ignored_files-Zahlen. */
    metadata: Record<string, unknown>;
    /** Was ueber die offene Datei gerade bekannt ist. */
    open: { path: string; status: string; freshness: string; action: string; note: string } | undefined;
    /** Leer, solange nichts schiefging. */
    error: string;
}

export interface AtlasChecklistSeam {
    /** Das Symbol, ueber das die Statusleiste gerade zaehlt. Leer, wenn keines. */
    symbol: string;
    explored: number;
    total: number;
    /** Genau das, was in der Statusleiste steht. Leer heisst: kein Zaehler. */
    label: string;
    /** Vermerke dieses Projekts insgesamt. Die eine Zahl, die nur steigt. */
    marks: number;
}

/**
 * Der Griff, an dem der Beweislauf das lokale Modell anfasst.
 *
 * Er traegt zwei Dinge, die im DOM nicht stehen und ohne die der Lauf raten
 * muesste: das Urteil der Policy samt Begruendung, und die Zahl der Proben, die
 * ueberhaupt losgeschickt wurden. Die zweite ist der Gegenbeweis zur ersten
 * Behauptung dieses Zyklus: solange das LLM aus ist, bleibt sie null, und der
 * Netz-Mitschnitt sagt dasselbe aus der anderen Richtung.
 */
/**
 * Der Anfangswert der Probe: nichts gefragt, nichts gefunden.
 *
 * Als Konstante und nicht als Literal an drei Stellen: er wird beim ersten Bild
 * gesetzt, beim Projektwechsel und beim Ausschalten, und drei Fassungen davon
 * waeren drei Gelegenheiten, eine zu vergessen.
 */
const EMPTY_SIDECAR_READING: SidecarReading = {
    state: 'not-running',
    router: false,
    models: [],
    detail: '',
};

/** Eine leere Liste mit fester Identitaet, damit sie keine Effekte anstoesst. */
const NO_CACHE_MODELS: readonly CacheModel[] = [];

export interface AtlasLlmSeam {
    state: SidecarState;
    /** Ob dieser Browser fuer dieses Projekt eingeschaltet hat. */
    preferenceOn: boolean;
    /** Das Urteil der committeten Policy. Leer, solange noch nicht gelesen. */
    policyVerdict: string;
    policyPath: string;
    policyDetail: string;
    /** Der Modellname, so wie er im Panel steht. Leer, wenn keiner bekannt ist. */
    model: string;
    /** Was in der Statusleiste steht. */
    chip: string;
    /** Wie oft ueberhaupt zum Sidecar gefragt wurde, seit die Seite geladen ist. */
    probes: number;
}

/**
 * Der Griff, an dem der Beweislauf den Chat und die Umformulierung anfasst.
 *
 * Zwei Dinge stehen hier, die im DOM nicht stehen und ohne die ein Lauf raten
 * muesste: die Kartennummern, die eine Antwort wirklich zitiert hat (im Text
 * stehen sie als Knoepfe, aber nicht die Liste der gegebenen Karten daneben),
 * und `validateRefine`. Das zweite ist kein Nachbau: es ruft denselben
 * Validator, den der Knopf ruft, mit einer absichtlich kaputten Antwort. Ein
 * Lauf, der die Regel nachbaut, prueft seine Kopie und nicht das Produkt.
 */
export interface AtlasChatSeam {
    turns: {
        id: number;
        question: string;
        status: string;
        klass: string;
        rule: string;
        depth: number;
        cards: number;
        cardIds: string[];
        sources: number;
        citations: string[];
        unknownCitations: string[];
        uncitedLines: number;
        answer: string;
        refusal: string;
        tokens: number;
        budget: number;
        tokensPerSecond: number;
        /** Die Kandidaten, wenn dieser Zug auf eine Wahl wartet. */
        candidates: { name: string; qualifiedName: string; filePath: string; line: number }[];
        /** Der Name, der mehrdeutig war oder nicht gefunden wurde. Leer, wenn keiner. */
        askedName: string;
        /** Das Fokus-Symbol, das statt eines nicht gefundenen Namens geantwortet hat. */
        focusFallbackUsed: string;
    }[];
    /**
     * Ob der Chat gerade sichtbar ist.
     *
     * Seit W8 heisst das: der Erklaeren-Bereich ist offen UND sein Reiter ist
     * `chat`. Eingeklappt oder auf einem anderen Reiter bleiben die Zuege
     * trotzdem stehen, und genau das ist die Zusicherung, die W7c erkaempft hat
     * und die hier weiter gemessen wird.
     */
    open: boolean;
    /** Die Hoehe, die der Chat gerade hat. Seit W8 ist es die Hoehe seiner Zone. */
    height: number;
    /** Der Deckel, den dieses Fenster gerade zulaesst. Ebenfalls der der Zone. */
    maxHeight: number;
    depth: number;
    depthDefault: number;
    depthOptions: number[];
    refineAvailable: boolean;
    refineState: string;
    refineMessage: string;
    validateRefine: (answer: string) => { applied: boolean; reason: string };
}

/**
 * Der Griff, an dem der Beweislauf die Suche und die Menuezeile anfasst.
 *
 * Er traegt genau das, was im DOM nicht steht und was ein Lauf sonst aus
 * Wartezeiten raten muesste: wie lange der Serverweg gedauert hat, wie oft ein
 * Verlaengern des Wortes aus dem Praefix-Cache beantwortet wurde, wie oft eine
 * ueberholte Runde abgebrochen wurde, und ob je eine ueberholte Antwort die
 * neuere ueberschrieben hat. Die letzte Zahl ist die einzige, die falsch sein
 * darf: sie ist der Gegenbeweis zur Zusicherung dieses Zyklus und muss null
 * bleiben.
 *
 * `activatedMenus` ist die Liste der Menuepunkte, die wirklich GELAUFEN sind,
 * je Buchstabe. Sie wird an der Stelle geschrieben, an der die Handlung
 * ausgefuehrt wird, und nicht dort, wo geklickt wurde: ein Lauf, der einen
 * Klick zaehlt, hat den Klick bewiesen und nicht die Handlung dahinter.
 */
export interface AtlasSearchSeam {
    /** Die Entprellung, wie sie wirklich gilt. */
    debounceMs: number;
    minQuery: number;
    /** Was gerade in der Zeile steht. */
    currentQuery: string;
    /** Die Anfrage, die die gezeigten Zeilen beantworten. */
    shownQuery: string;
    /** Woher die gezeigten Zeilen kommen. */
    shownSource: SearchRowSource;
    shownRows: number;
    /** Wie oft vorlaeufige Zeilen VOR einer Antwort des Index dastanden. */
    localFirst: number;
    /** Wie oft ein verlaengertes Wort aus dem Praefix-Cache beantwortet wurde. */
    prefixCacheHits: number;
    /** Runden, die wirklich zum Server gingen. */
    serverRequests: number;
    /** Der letzte gemessene Serverweg, in Millisekunden. */
    serverRoundtripMs: number;
    /** Jeder gemessene Serverweg dieser Sitzung. */
    roundtrips: number[];
    /** Runden, die abgebrochen wurden, weil ein Tastendruck sie ueberholt hat. */
    abortedRequests: number;
    /** Antworten, die zu spaet kamen und deshalb verworfen wurden. */
    staleDropped: number;
    /** Muss false bleiben: eine ueberholte Antwort hat die neuere ueberschrieben. */
    staleAnswerWins: boolean;
    /** Kandidaten, die ohne Serverweg zur Verfuegung stehen. */
    localCandidates: number;
    /** Die Buchstaben der Menuepunkte, deren Handlung gelaufen ist, in ihrer Reihenfolge. */
    activatedMenus: string[];
    /** Ob der Griff am Fenster in der einfangenden Phase haengt. */
    keyListenerCapture: boolean;
}

/**
 * Der Griff, an dem der Beweislauf das Layout anfasst.
 *
 * Er traegt drei Dinge, die im DOM nicht oder nur als Pixel stehen, und jedes
 * davon ist eine Frage, die ein Lauf sonst raten muesste:
 *
 *  - **Die Zahlen mit ihren Grenzen.** Ein Lauf kann ein Rechteck messen; ob
 *    das gemessene Rechteck am Anschlag steht oder nur zufaellig so gross ist,
 *    sagt ihm erst `bounds`. Genau daran haengt AC2 ("keine Zone darf
 *    wegziehbar sein"): gemessen wird gegen die Grenze, die die Oberflaeche
 *    selbst nennt, und nicht gegen eine im Lauf abgeschriebene Zahl.
 *  - **Der Zustand hinter den Reitern.** AC5 verlangt, dass ein Reiterwechsel
 *    keinen Zustand kostet. Der Chat-Verlauf steht im DOM, der Walk-Schritt und
 *    die Flow-Stelle stehen dort nur, solange ihr Reiter offen ist. Hier stehen
 *    alle drei jederzeit, und deshalb kann ein Lauf sie VOR und NACH einem
 *    Wechsel vergleichen, statt zu behaupten, sie seien noch da.
 *  - **Der Schluessel im Speicher.** Damit ein Lauf pruefen kann, dass die
 *    Masse pro Projekt gefuehrt werden, ohne den Schluessel nachzubauen.
 */
export interface AtlasLayoutSeam {
    /** Die Masse, die WIRKLICH gezeichnet werden. Gegen sie misst der Lauf Rechtecke. */
    sizes: LayoutSizes;
    /**
     * Die Masse, die der Leser gezogen hat.
     *
     * Sie koennen groesser sein als `sizes`: ein kleines Fenster begrenzt die
     * Darstellung und nicht den Wunsch. Ohne diese zweite Zahl saehe ein Lauf
     * nur, dass eine Spalte schmal ist, und nicht, ob sie es bleiben wird.
     */
    requested: LayoutSizes;
    bounds: Record<LayoutKey, { min: number; max: number }>;
    defaults: LayoutSizes;
    /** Ob alle vier Zahlen auf ihrer Vorgabe stehen. */
    isDefault: boolean;
    frame: LayoutFrame;
    explainOpen: boolean;
    explainTab: string;
    tabs: { id: string; enabled: boolean; reason: string; note: string }[];
    storageKey: string;
    /** Was hinter den Reitern liegt, unabhaengig davon, welcher offen ist. */
    state: {
        chatTurns: number;
        walkStep: number;
        walkSteps: number;
        flowStep: number;
        flowSteps: number;
    };
}

/**
 * Der Griff, an dem der Beweislauf das Einstellungen-Panel anfasst (W10).
 *
 * Er traegt drei Dinge, die im DOM nicht oder nur als Text stehen, und jedes
 * davon ist eine Frage, die ein Lauf sonst raten muesste:
 *
 *  - **Die Wahl und ihr Speicherort.** Ob eine Wahl den Reload ueberlebt, kann
 *    ein Lauf nur pruefen, wenn er den Schluessel kennt, ohne ihn nachzubauen.
 *  - **Was der Prozess wirklich gemeldet hat.** Die Liste der Cache-Modelle
 *    steht auch im DOM, aber ohne die Angabe, ob der Prozess ein Router ist,
 *    und genau daran haengt, ob eine Auswahl ueberhaupt wirkt.
 *  - **Die letzten Messungen.** Sie stehen als Saetze auf dem Schirm; hier
 *    stehen sie als Zahlen, mit dem Rauschband daneben, damit ein Lauf das
 *    Urteil nachrechnen kann, statt einen Satz zu lesen.
 */
export interface AtlasSettingsSeam {
    open: boolean;
    /** Ob das lokale Modell an ist. Ist es aus, hat dieses Panel nichts gefragt. */
    llmOn: boolean;
    /** Wie oft ueberhaupt zum Sidecar gefragt wurde. Dieselbe Zahl wie in __atlasLlm. */
    probes: number;
    /** Ob der Prozess als Router ueber ein Cache-Verzeichnis laeuft. */
    router: boolean;
    /** Die id, an die die naechste Frage geht. Leer heisst: keine Wahl getroffen. */
    selectedModel: string;
    /** Was `/v1/models` gelistet hat, mit der aktiven Zeile markiert. */
    cacheModels: { id: string; name: string; loaded: boolean; status: string; active: boolean }[];
    /** Die vier Zahlen des laufenden Modells, so wie das Panel sie zeigt. */
    running: {
        model: string;
        modelPath: string;
        quantization: string;
        contextTokens: number;
        trainedContextTokens: number;
        weightsBytes: number;
        parameters: number;
    };
    /** Die kuratierten Vorschlaege mit ihren gemessenen Zahlen und ihrem Befehl. */
    suggestions: {
        id: string;
        name: string;
        repo: string;
        modelClass: string;
        passRate: number;
        citationCompliance: number;
        /** `null` heisst: der aufgezeichnete Lauf weist die Zahl nicht aus. */
        citationUnmeasured: number | null;
        tokensPerSecond: number;
        bytes: number;
        command: string;
    }[];
    /** Die Anzeige-Einstellungen, ihre Vorgabe und ob beides dasselbe ist. */
    display: GraphDisplaySettings;
    displayDefault: GraphDisplaySettings;
    isDefaultDisplay: boolean;
    /** Die zwei Schluessel im Speicher dieses Browsers. */
    storageKeys: { model: string; display: string };
    /** Die letzten abgeschlossenen Messungen, eine je Einstellung. */
    measurements: SettingsMeasurement[];
}

declare global {
    // eslint-disable-next-line no-var
    var __atlasSettings: AtlasSettingsSeam | undefined;
    // eslint-disable-next-line no-var
    var __atlasLayout: AtlasLayoutSeam | undefined;
    // eslint-disable-next-line no-var
    var __atlasSearch: AtlasSearchSeam | undefined;
    // eslint-disable-next-line no-var
    var __atlasChat: AtlasChatSeam | undefined;
    // eslint-disable-next-line no-var
    var __atlasTour: AtlasTourSeam | undefined;
    // eslint-disable-next-line no-var
    var __atlasChecklist: AtlasChecklistSeam | undefined;
    // eslint-disable-next-line no-var
    var __atlasCoverage: AtlasCoverageSeam | undefined;
    // eslint-disable-next-line no-var
    var __atlasLlm: AtlasLlmSeam | undefined;
}

/** Was ein Projektfenster dem naechsten mitgibt (K24): den Arbeitsbereich, die Kopfzeile des Agenten und ob der Chat offen ist. */
interface WindowCarry {
    workspace: Workspace;
    chatOpen: boolean;
    agentState: 'off' | 'loading' | 'active' | 'busy' | 'error';
    agentModelName: string;
    agentHasOpened: boolean;
}

/**
 * Jedes Projekt bekommt ein frisches Fenster in derselben Seite (K24, Kopf von
 * src/app/project-windows.tsx). Der Agent reicht beim Wechsel sein geladenes
 * Modell an das Fenster des neuen Projekts weiter. Die Adresse behaelt dabei
 * den Arbeitsbereich und die Grenzen des Walks, nichts vom alten Projekt (A5).
 */
const PAGE_PARAMS = ['workspace', CLOSURE_DEPTH_PARAM, CLOSURE_CAP_PARAM] as const;
export default function App(): JSX.Element {
    return <ProjectWindows<WindowCarry> around={switchKeepingAgent} keepParams={PAGE_PARAMS}>
        {shown => <ProjectWindowView key={shown.key} projectWindow={shown} />}
    </ProjectWindows>;
}

function ProjectWindowView({ projectWindow }: { projectWindow: ProjectWindow<WindowCarry> }): JSX.Element {
    const carried = projectWindow.carried;
    const [workspace, setWorkspace] = useState<Workspace>(() => {
        try {
            // A project switch keeps the workspace in view; Back and Forward restore the one of their entry (K24).
            const requested = new URLSearchParams(window.location.search).get('workspace') ?? carried?.workspace ?? null;
            let saved: string | null = null;
            try { saved = localStorage.getItem('cbm.workspace'); } catch { /* URL navigation works without storage. */ }
            return initialWorkspace(requested, saved);
        } catch { return 'architecture'; }
    });
    const changeWorkspace = (value: Workspace): void => {
        value = allowedWorkspace(value);
        if (value !== workspace) {
            setProactiveSelection(undefined); setChatGraphSelection(undefined); setChatAttachment(undefined);
        }
        setWorkspace(value);
        try { localStorage.setItem('cbm.workspace', value); } catch { /* Session-only preference. */ }
    };
    // The address always names the workspace in view, also one carried over a project switch, so a reload keeps it (A5).
    useParamInAddress('workspace', workspace);
    const [welcomeOpen, setWelcomeOpen] = useState(() => {
        try { return localStorage.getItem('cbm.workspace.setup') !== 'done'; } catch { return false; }
    });
    // The agent's lamp and the chat stay as they were across a project switch (K24).
    const [browserAiOpen, setBrowserAiOpen] = useState(carried?.chatOpen ?? false);
    const [localAgentState, setLocalAgentState] = useState<'off' | 'loading' | 'active' | 'busy' | 'error'>(carried?.agentState ?? 'off');
    const [agentSettingsRequest, setAgentSettingsRequest] = useState(0);
    const [agentModelName, setAgentModelName] = useState(carried?.agentModelName ?? '');
    const agentHasOpened = useRef(carried?.agentHasOpened ?? false);
    useEffect(() => {
        projectWindow.report({ workspace, chatOpen: browserAiOpen, agentState: localAgentState, agentModelName, agentHasOpened: agentHasOpened.current });
    });
    const onAgentStateChange = useCallback((state: 'off' | 'loading' | 'active' | 'busy' | 'error') => {
        setLocalAgentState(state);
        if ((state === 'active' || state === 'busy') && !agentHasOpened.current) {
            agentHasOpened.current = true; setBrowserAiOpen(true);
        }
    }, []);
    const openAgentSettings = () => { setAgentSettingsRequest(value => value + 1); };
    const [codeDetailsOpen, setCodeDetailsOpen] = useState(false);
    const [readerSelection, setReaderSelection] = useState<ReaderSelection>();
    const [pinnedCode, setPinnedCode] = useState<SelectedCodeSnapshot>();
    const [fileSymbols, setFileSymbols] = useState<FileSymbolResult & { project: string; path: string; status: 'loading' | 'ready' | 'error' }>({ project: '', path: '', symbols: [], message: '', status: 'ready' });
    const [chatAttachment, setChatAttachment] = useState<BrowserChatAttachment>();
    const [chatGraphSelection, setChatGraphSelection] = useState<BrowserChatContext>();
    const [proactiveSelection, setProactiveSelection] = useState<{ scope: string; context: BrowserChatContext }>();
    const [galaxySelection, setGalaxySelection] = useState<GraphNode>();
    const [galaxySelectionProject, setGalaxySelectionProject] = useState('');
    const finishSetup = (): void => {
        setWelcomeOpen(false);
        setWhyDismissed(true);
        try { localStorage.setItem('cbm.workspace.setup', 'done'); } catch { /* Session-only preference. */ }
    };
    const guidance: Guidance = 'brief';
    // Requests of this window end with it: a switch to another project aborts them (K24).
    const client = useMemo(() => new RpcIntelligenceClient({ signal: projectWindow.signal }), [projectWindow.signal]);
    const api = useMemo(() => new AtlasApi({ signal: projectWindow.signal }), [projectWindow.signal]);
    const [diagnosticsPath, setDiagnosticsPath] = useState<string>();

    /*
     * What the projects panel asks the server. The list comes over /rpc like
     * every other read of this window; the rest are the /api routes the panel
     * names in its own text. Opening a project replaces this window with a
     * fresh one for that project in the same page, because every panel of this
     * window is keyed to the project it started with (K24).
     */
    const projectsSource = useMemo<ProjectsSource>(
        () => ({
            listProjects: () => client.listProjects().then((result) => result.projects),
            projectHealth: (name) => api.projectHealth(name),
            deleteProject: (name) => api.deleteProject(name),
            browse: (path) => api.browse(path),
            startIndex: (rootPath, projectName) => api.startIndex(rootPath, projectName),
            indexJobs: () => api.indexJobs(),
            adr: (name) => api.adr(name),
            saveAdr: (name, content) => api.saveAdr(name, content),
            logs: (lines) => api.logs(lines),
            processes: () => api.processes(),
            uiLogTail: (lines) => api.uiLogTail(lines),
        }),
        [client, api],
    );
    // Opening a project stays in this page and keeps a loaded agent (K24).
    const openProject = projectWindow.open;

    const [project, setProject] = useState('');
    const selectionScope = `${project}:${workspace}`;
    const onSelectionEvidence = useCallback((context: BrowserChatContext | undefined) => {
        setProactiveSelection(previous => context
            ? previous?.scope === selectionScope && previous.context.text === context.text ? previous : { scope: selectionScope, context }
            : undefined);
    }, [selectionScope]);
    useEffect(() => { setProactiveSelection(undefined); setChatGraphSelection(undefined); setChatAttachment(undefined); }, [project]);
    const [projectDetail, setProjectDetail] = useState('resolving project ...');
    const [serverOk, setServerOk] = useState<boolean | undefined>(undefined);
    const [counts, setCounts] = useState<{ nodes?: number; edges?: number }>({});

    const [levels, setLevels] = useState<ReadonlyMap<string, TreeLevel>>(emptyLevels);
    const [expanded, setExpanded] = useState<ReadonlySet<string>>(new Set<string>());
    const [budgetHit, setBudgetHit] = useState(false);
    const [treeError, setTreeError] = useState('');
    const [cursor, setCursor] = useState(0);

    /*
     * Der Coverage-Befund: die zweite Haelfte der Baumquelle.
     *
     * `EMPTY_COVERAGE` heisst "noch nicht gefragt" und nicht "keine Luecken";
     * der Unterschied steht in der Notiz unter dem Baum. Ein gescheiterter Lauf
     * wird darum ausdruecklich gemeldet, statt einen leeren Befund zu setzen.
     */
    const [coverage, setCoverage] = useState<CoverageIndex>(EMPTY_COVERAGE);
    const [coverageMeta, setCoverageMeta] = useState<Record<string, unknown>>({});
    const [coverageAsked, setCoverageAsked] = useState(false);
    const [coverageError, setCoverageError] = useState('');
    /** Was der Store ueber die offene Datei sagt, mit Frische. */
    const [openCoverage, setOpenCoverage] = useState<CoveragePathAnswer | undefined>(undefined);

    const [tabs, setTabs] = useState<string[]>([]);
    const [activePath, setActivePath] = useState('');
    const [document, setDocument] = useState<ReaderDocument | undefined>(undefined);
    const [documentOrigin, setDocumentOrigin] = useState<ReaderSourceOrigin>();
    const [readerStatus, setReaderStatus] = useState<ReaderStatus>('idle');
    const [readerMessage, setReaderMessage] = useState('pick a file in the explorer');
    const [command, setCommand] = useState('');

    useEffect(() => { setPinnedCode(undefined); }, [project]);
    useEffect(() => {
        if (!project || !activePath) return;
        let cancelled = false;
        setFileSymbols({ project, path: activePath, symbols: [], message: '', status: 'loading' });
        void loadFileSymbols(client, project, activePath).then(result => {
            if (!cancelled) setFileSymbols({ ...result, project, path: activePath, status: 'ready' });
        }).catch((error: unknown) => {
            if (!cancelled) setFileSymbols({ project, path: activePath, symbols: [], status: 'error',
                message: error instanceof Error ? error.message : String(error) });
        });
        return () => { cancelled = true; };
    }, [client, project, activePath]);

    // Zaehler gegen Wettlaeufe: klickt jemand schnell durch zwei Dateien, darf
    // die langsamere Antwort die schnellere nicht ueberschreiben.
    const loadTicket = useRef(0);

    // Der Coverage-Befund als Ref, damit `openFile` ihn lesen kann, ohne bei
    // jeder neuen Antwort seine Identitaet zu wechseln: an `openFile` haengen
    // die Fuehrungen, der Twin und die Galaxie, und ein Wechsel dort haengt
    // eine Handvoll Effekte neu auf.
    const coverageRef = useRef<CoverageIndex>(EMPTY_COVERAGE);
    coverageRef.current = coverage;
    const coverageTicket = useRef(0);

    // ------------------------------------------------------- Twin ----------

    const provider = useMemo(() => new CbmRpcProvider(client, { generation: 1 }), [client]);
    // Das Profil ist seit W4a beweglich: die Antwort auf "warum bist du hier"
    // setzt es. Die Regler des Lesers liegen als Overlay darauf, so wie vorher,
    // und werden beim Profilwechsel geleert: eine abgeschaltete Linse, die ueber
    // ein neues Profil hinweg abgeschaltet bliebe, waere eine Sektion, die
    // fehlt, ohne dass jemand sagt warum.

    const [twinSymbol, setTwinSymbol] = useState<SymbolRef | undefined>(undefined);
    const [twinIr, setTwinIr] = useState<SemanticIR | undefined>(undefined);
    const [twinStatus, setTwinStatus] = useState<TwinStatus>('empty');
    const [twinMessage, setTwinMessage] = useState(TWIN_EMPTY_MESSAGE);
    const [twinHint, setTwinHint] = useState(TWIN_EMPTY_HINT);
    const [twinName, setTwinName] = useState('no symbol');
    const [caretLine, setCaretLine] = useState<number | undefined>(undefined);
    const [settledCaret, setSettledCaret] = useState<number | undefined>(undefined);
    const [pointedLine, setPointedLine] = useState<number | undefined>(undefined);
    const [reveal, setReveal] = useState<{ line: number; nonce: number } | undefined>(undefined);

    /*
     * Der Erklaeren-Bereich: welcher Reiter gilt, und ob der Bereich offen ist.
     *
     * Zwei Angaben und nicht fuenf Schalter, und das ist der ganze Umbau von W8.
     * Bis dahin hatte jede der fuenf Flaechen ihren eigenen "offen"-Zustand, und
     * genau daraus entstand der Nutzerbefund vom 2026-08-29: drei davon standen
     * gleichzeitig auf `true`, lagen uebereinander und waren alle drei
     * angeschnitten. Mit EINEM Reiter kann das nicht mehr vorkommen; es ist
     * keine Regel, die jemand einhalten muss, sondern eine Form, in der der
     * Fehler nicht formulierbar ist.
     *
     * Eingeklappt per Vorgabe (AC4): eine Flaeche, die beim Oeffnen eines
     * Projekts von selbst aufgeht, erklaert etwas, wonach niemand gefragt hat.
     */
    const [explainOpen, setExplainOpen] = useState(false);
    const [explainTab, setExplainTab] = useState<ExplainTabId>('flow');
    /*
     * Der aktive Reiter, auch fuer die Rueckrufe, die ihn nicht als Abhaengigkeit
     * haben duerfen. Derselbe Umweg wie bei `menuActionsRef` und aus demselben
     * Grund: ein Griff, der bei jedem Reiterwechsel ab- und wieder angemeldet
     * wird, ist ein Griff, der zwischendurch taub ist.
     */
    const explainTabRef = useRef<ExplainTabId>('flow');
    explainTabRef.current = explainTab;
    /*
     * Die Reiter, wie sie das letzte Bild gezeichnet hat, fuer den Griff des
     * Beweislaufs. Sie entstehen unten aus Tatsachen; hier steht nur die
     * Ablage, damit der Effekt, der den Griff schreibt, sie sehen kann.
     */
    const explainTabsRef = useRef<ExplainTabState[]>([]);
    /*
     * Ob der Flow gerade zu sehen ist.
     *
     * Abgeleitet und nicht gespeichert: ein zweiter Schalter neben dem Reiter
     * waere die Stelle, an der beide auseinanderlaufen. Der Schritt selbst steht
     * auf -1, weil "noch keiner" kein Schritt ist; eine 0 hier waere der erste
     * Schritt und wuerde beim Oeffnen ungefragt den Editor bewegen.
     */
    const flowOpen = explainOpen && explainTab === 'flow';
    /*
     * Die Hilfeseite (W7a).
     *
     * Zu per Vorgabe, aus demselben Grund wie der Erklaerer: eine Flaeche ueber
     * dem Editor geht nicht ungefragt auf. Ein Zustand und kein Router-Pfad,
     * weil diese Oberflaeche keine Adressen hat, hinter denen Seiten liegen; sie
     * hat Flaechen, die auf- und zugehen.
     */
    const [helpOpen, setHelpOpen] = useState(false);
    /*
     * Das Einstellungen-Panel (W10), aus denselben Gruenden zu per Vorgabe wie
     * die Hilfe: eine Flaeche ueber dem Editor geht nicht ungefragt auf.
     */
    const [settingsOpen, setSettingsOpen] = useState(false);
    const [projectsOpen, setProjectsOpen] = useState(false);
    const [indexActivity, setIndexActivity] = useState<{ name: string; status: 'indexing' | 'done' | 'error' }>();
    /*
     * Die Anzeige-Einstellungen des Lesers.
     *
     * Sie stehen HIER und nicht im Panel, weil zwei Flaechen sie brauchen: das
     * Panel stellt sie ein, das Graph-Panel zeichnet danach. Ein Zustand im
     * Einstellungen-Panel waere weg, sobald jemand es zuklappt, und genau das
     * darf eine Einstellung nicht sein.
     */
    const [display, setDisplay] = useState<GraphDisplaySettings>(DEFAULT_GRAPH_DISPLAY);
    /*
     * Der Live-Modus der Agenten (W11a).
     *
     * AUS per Vorgabe, und er wird auch nicht gespeichert. Dieselbe Regel wie
     * beim lokalen Modell: solange er aus ist, geht keine einzige Agentenabfrage an den
     * Daemon, und eine Seite, die nach dem naechsten Laden von selbst wieder zu
     * reden anfaengt, waere ein Schalter, ueber den der Leser nur einmal
     * entschieden hat. Er steht hier und nicht im Graph-Panel, weil ihn zwei
     * Wege umlegen: der Menuepunkt und die Kommandozeile.
     */
    const [liveAgentsOn, setLiveAgentsOn] = useState(false);
    /*
     * Die Bitte um das Vollbild, als Zaehler (W11b).
     *
     * Dieselbe Form wie `graphRefit`: die Wahl selbst liegt im Panel, weil sie
     * dort gespeichert wird; was von hier kommt, ist die Bitte. Ein zweiter Ort
     * fuer denselben Zustand waere zwei Wahrheiten darueber, ob das Bild gerade
     * das ganze Fenster fuellt.
     */
    const [fullscreenToggle, setFullscreenToggle] = useState(0);
    // Compatibility prop for existing HUD consumers; the stream uses this daemon origin.
    const bridgePort = useMemo(
        () => bridgePortFromSearch(typeof location === 'undefined' ? '' : location.search),
        [],
    );
    const agentStream = useAgentStream({ on: experimentalAgentsEnabled && liveAgentsOn, project });
    const agents = useMemo(
        () => ({ ...agentStream, port: bridgePort, on: experimentalAgentsEnabled && liveAgentsOn }),
        [agentStream, bridgePort, liveAgentsOn],
    );
    /** Die letzten Messungen des Panels, je Einstellung. Nur fuer die Naht. */
    const [measurements, setMeasurements] = useState<Record<string, SettingsMeasurement>>({});
    const [flowView, setFlowView] = useState<FlowView | undefined>(undefined);
    const [flowStep, setFlowStep] = useState(-1);
    const [flowMessage, setFlowMessage] = useState(FLOW_LOADING);
    const [imports, setImports] = useState<ImportsGroup | undefined>(undefined);
    const [pseudocode, setPseudocode] = useState<PseudocodeDocument | undefined>(undefined);
    const flowTicket = useRef(0);
    /**
     * Fuer welches Symbol der Walk schon geholt ist.
     *
     * Neu in W8, und der Grund ist AC5: der Flow behaelt seine Stelle ueber einen
     * Reiterwechsel hinweg. Bis dahin holte der Effekt den Walk jedes Mal neu,
     * wenn der Erklaerer aufging, und setzte den Schritt dabei auf -1 zurueck.
     * Als Overlay war das richtig (jedes Aufschlagen war eine neue Sitzung), als
     * Reiter waere es der Verlust, den dieser Zyklus verbietet. Der Vermerk
     * unterscheidet die beiden Faelle: dasselbe Symbol wird nicht noch einmal
     * geholt, ein anderes schon, und der Effekt darueber leert ihn.
     */
    const flowLoadedFor = useRef('');
    const importsTicket = useRef(0);
    /*
     * Waehrend einer Stepper-Sitzung folgt der Twin dem Caret nicht.
     *
     * Ein Schritt kann in eine andere Datei zeigen (ein erhobener Fehlertyp
     * steht fast immer im Aufgerufenen), und der Editor folgt ihm. Ohne diese
     * Klammer wuerde die Aufloesung am Zielort das Subjekt wechseln, der Kasten
     * waere der eines anderen Symbols, und der Leser haette die Sitzung
     * verloren, die er gerade fuehrt. Escape beendet sie und gibt den Caret
     * wieder frei.
     */
    /**
     * Das Subjekt des Twins als Zeichenkette.
     *
     * Der Schluessel und nicht das Objekt, und das ist keine Feinheit: die
     * Aufloesung liefert bei jedem Lauf ein NEUES `SymbolRef`, auch wenn es
     * dasselbe Symbol meint. Ein Effekt, der an der Objektgleichheit haengt,
     * wirft dann den geladenen Walk weg, sobald der Caret sich noch einmal
     * setzt, und der Erklaerer stuende dauerhaft auf "wird geladen". Genau das
     * ist beim ersten Lauf dieses Zyklus passiert, und der Schluessel ist die
     * Antwort darauf: gleiches Symbol, gleicher Schluessel, kein Wegwerfen.
     */
    const twinKey = twinSymbol === undefined ? '' : (twinSymbol.qualifiedName ?? twinSymbol.name);

    const flowPinned = useRef(false);
    /*
     * Der Reiter und nicht die Sichtbarkeit haelt die Klammer.
     *
     * Bis W8 stand hier `flowOpen`, also "das Overlay ist zu sehen". Seit der
     * Erklaerer ein Reiter ist, gibt es einen dritten Zustand: der Reiter ist
     * gewaehlt, aber die Zone ist eingeklappt (Escape). Die Sitzung ist dann
     * NICHT beendet, denn Escape kostet seit W8 nichts, und eine Klammer, die
     * sich beim Einklappen loeste, gaebe den Caret frei und wechselte hinter dem
     * eingeklappten Bereich das Subjekt. Der Leser klappte wieder auf und faende
     * das Bild eines anderen Symbols.
     */
    flowPinned.current = explainTab === 'flow' && flowStep >= 0;

    /**
     * Was jeder verdrahtete Menuebuchstabe tut, immer auf dem Stand des Bildes.
     *
     * Geschrieben wird es unten bei den Menuepunkten, gelesen oben im
     * Tastatur-Griff, und der Grund fuer den Umweg ueber ein Ref steht an beiden
     * Stellen. Der Schluessel ist der Buchstabe aus {@link WIRED_MENU_SHORTCUTS}.
     */
    const menuActionsRef = useRef<Record<string, () => void>>({});

    /**
     * Was der Tastatur-Griff ueber den Bildschirm wissen muss, ohne ihn neu
     * aufzuhaengen.
     *
     * Zwei Fragen, und beide aendern sich mit jedem Bild: liegt gerade eine
     * Flaeche ueber dem Editor, und laeuft eine Fuehrung. Sie in die
     * Abhaengigkeitsliste des Effekts zu schreiben hiesse, den Griff bei jedem
     * geoeffneten Panel ab- und wieder anzumelden; sie in seine Schliessung zu
     * schreiben hiesse, dass er die Lage von vor hundert Bildern liest.
     */
    const keyboardGuardRef = useRef<{ overlayOpen: boolean; walkRunning: boolean }>({
        overlayOpen: false,
        walkRunning: false,
    });

    /*
     * Das geladene Dokument als Ref.
     *
     * Die Imports-Lesung braucht den Text der Datei, die schon offen ist, und
     * soll dafuer nicht jedesmal neu aufgehaengt werden, wenn der Reader ein
     * Zeichen mehr geladen hat. Der Effekt haengt am Pfad und an der IR; der
     * Text wird zum Zeitpunkt der Frage gelesen.
     */
    const documentRef = useRef<ReaderDocument | undefined>(undefined);
    documentRef.current = document;

    const twinTicket = useRef(0);
    // Das aktuelle Subjekt als Ref, damit die Aufloesung es lesen kann, ohne
    // dass der Effekt bei jedem Subjektwechsel neu aufgehaengt wird.
    const shownSymbol = useRef<SymbolRef | undefined>(undefined);
    shownSymbol.current = twinSymbol;
    // Die IR ebenfalls als Ref: der Klick auf eine Zeile muss wissen, aus
    // welcher Checkliste die Zeile stammt, und darf dafuer nicht neu gebunden
    // werden, sooft das Panel neu zeichnet.
    const shownIr = useRef<SemanticIR | undefined>(undefined);
    shownIr.current = twinIr;

    const irCache = useMemo(
        () =>
            new IrCache(
                async (symbol) => buildIr(provider, ATLAS_WORKSPACE_ROOT, symbol, {
                    projectName: project,
                    generation: 1,
                }),
                () => {
                    // Nur hier, und nur bei einer echten Anfrage. Der Beweislauf
                    // misst an dieser Zahl, ob ein Caret-Wechsel nachgeladen hat.
                    window.__atlasTwinFetches = (window.__atlasTwinFetches ?? 0) + 1;
                },
            ),
        [provider, project],
    );

    // ------------------------------------------------- Galaxie und Suche ---

    const [galaxyOn, setGalaxyOn] = useState(true);
    const [layout, setLayout] = useState<GraphData | undefined>(undefined);
    const [sourceEvidence, setSourceEvidence] = useState<{ project: string; target: SourceEvidenceTarget }>();
    const [hits, setHits] = useState<RankedHit[]>(noHits);
    const [selectedHit, setSelectedHit] = useState(0);
    const [searchStatus, setSearchStatus] = useState<SearchOverlayStatus>('ready');
    const [searchMessage, setSearchMessage] = useState('');
    const [answeredQuery, setAnsweredQuery] = useState('');
    /** Woher die gezeigten Zeilen kommen: aus der Antwort des Index, oder vorlaeufig. */
    const [hitSource, setHitSource] = useState<SearchRowSource>('index');
    const searchTicket = useRef(0);
    /**
     * Der Abbruch der laufenden Runde.
     *
     * Die Ticketpruefung allein reicht seit W7b nicht mehr: sie verhindert, dass
     * eine ueberholte Antwort die neuere ueberschreibt, laesst die ueberholte
     * Runde aber zu Ende laufen. Bei einem Wort je Anfrage sind das mehrere
     * Anfragen, die niemand mehr liest, und sie stehen in der Warteschlange vor
     * denen, die noch jemand liest. Beides bleibt: der Abbruch spart den Weg,
     * das Ticket ist die Zusicherung.
     */
    const searchAbort = useRef<AbortController | undefined>(undefined);
    /**
     * Die letzte vollstaendige Antwort des Index, roh.
     *
     * Sie traegt das Verlaengern eines Wortes: wer `valid` gefragt hat und dann
     * `validate` tippt, sieht sofort die neu gerankten Kandidaten der vorigen
     * Runde, statt auf einen zweiten Weg zum Server zu warten.
     *
     * Sie ERSETZT den Weg nicht, und das ist eine bewusste Grenze. Die Antwort
     * des Servers auf ein laengeres Wort ist nicht garantiert eine Teilmenge
     * seiner Antwort auf das kuerzere: die BM25-Suche zerlegt Bezeichner in
     * Woerter, und `validate` kann ein Symbol treffen, das `valid` nicht traf.
     * Ein Cache, der die Anfrage einspart, wuerde solche Treffer still
     * verschlucken. Er spart also die WARTEZEIT und nicht die Wahrheit: die
     * Zeilen stehen sofort da und tragen ihre Marke, und die Antwort des Index
     * ersetzt sie, sobald sie da ist.
     */
    const prefixCache = useRef<
        { query: string; candidates: SymbolSearchHit[]; complete: boolean } | undefined
    >(undefined);
    /** Die Zahlen, die der Beweislauf liest. Siehe AtlasSearchSeam. */
    const searchStats = useRef({
        localFirst: 0,
        prefixCacheHits: 0,
        serverRequests: 0,
        serverRoundtripMs: 0,
        roundtrips: [] as number[],
        abortedRequests: 0,
        staleDropped: 0,
        staleAnswerWins: false,
        appliedTicket: 0,
    });
    /** Die Menuepunkte, deren Handlung gelaufen ist. Siehe AtlasSearchSeam. */
    const activatedMenus = useRef<string[]>([]);

    // ------------------------------- Warum, Fuehrungen und die Checkliste ---

    /**
     * Der Speicher dieses Browsers.
     *
     * Einmal geholt und weitergereicht, damit jede Stelle, die etwas merkt oder
     * nachschlaegt, denselben Speicher benutzt und ein Test ihn ersetzen kann,
     * ohne globale Objekte zu verbiegen.
     */
    const store = useMemo(() => browserStore(), []);

    // ------------------------------------------------ Die Zonen (W8) -------

    /*
     * Wie gross das Fenster ist, als Zustand und nicht als Abfrage.
     *
     * Die Hoechstmasse der vier Zonen haengen daran (src/layout/layout-model.ts),
     * und ein Griff, dessen `aria-valuemax` aus der Fenstergroesse von vor dem
     * letzten Ziehen stammt, meldet einen Anschlag, den es nicht gibt. Der
     * Anfangswert wird beim ersten Bild gelesen und im Effekt darunter sofort
     * korrigiert: `window.innerHeight` ist beim ersten Bild noch die Hoehe vor
     * dem Layout. Dieselbe Ueberlegung wie beim Deckel des Antwort-Panels in
     * W7c, nur fuer alle vier Masse.
     */
    const [frame, setFrame] = useState<LayoutFrame>(() => ({
        width: window.innerWidth,
        height: window.innerHeight,
    }));
    const [zones, setZones] = useState<LayoutSizes>(() =>
        defaultLayout({ width: window.innerWidth, height: window.innerHeight }));
    const frameRef = useRef(frame);
    frameRef.current = frame;
    const zonesRef = useRef(zones);
    zonesRef.current = zones;
    const projectRef = useRef('');

    useEffect(() => {
        const measure = (): void => {
            setFrame({ width: window.innerWidth, height: window.innerHeight });
        };
        measure();
        window.addEventListener('resize', measure);
        return () => window.removeEventListener('resize', measure);
    }, []);

    /**
     * Die vier Zahlen setzen und merken, an einer Stelle.
     *
     * Beides zusammen und nicht in zwei Effekten: ein Effekt, der bei jeder
     * Aenderung schreibt, schreibt beim Laden zuerst die Vorgabe ueber den
     * gemerkten Stand und danach den gemerkten Stand zurueck. Das geht gut, bis
     * jemand das Fenster genau dazwischen schliesst.
     */
    const applyZones = useCallback((next: LayoutSizes) => {
        setZones(next);
        /*
         * Gespeichert wird nur, was sich wirklich geaendert hat.
         *
         * Ein Zug schickt zwanzig Ereignisse zwischen zwei Bildern, und die
         * meisten davon tragen dieselbe Zahl (der Griff steht am Anschlag, oder
         * die Bewegung war kleiner als ein Pixel). Sie alle zu speichern hiesse,
         * zwanzigmal in localStorage zu schreiben, um nichts zu aendern.
         *
         * Der Zustand wird trotzdem IMMER gesetzt, und das ist keine
         * Unachtsamkeit: `setZones` mit einem neuen Objekt zeichnet ein Bild,
         * und an diesem Bild haengen die Naehte, an denen der Beweislauf liest.
         * Ein "reset layout" auf ein Layout, das schon die Vorgabe ist, aendert
         * nichts und muss trotzdem sichtbar stattgefunden haben; ohne das Bild
         * meldete der Griff des Laufs, der Menuepunkt habe nicht ausgeloest.
         * Gemessen an genau diesem Fall (smoke:w7b, `a-layout`).
         */
        if (!sameLayout(next, zonesRef.current)) {
            writeLayout(store, projectRef.current, next);
        }
    }, [store]);

    /** Eine Grenze verschieben. Die Grenzen der Grenze kommen aus dem Modell. */
    const changeZone = useCallback((key: LayoutKey, value: number) => {
        applyZones({
            ...zonesRef.current,
            [key]: clampLayoutValue(key, value, frameRef.current),
        });
    }, [applyZones]);

    /** Doppelklick auf einen Griff: genau diese eine Grenze zurueck. */
    const resetZone = useCallback((key: LayoutKey) => {
        changeZone(key, defaultLayout(frameRef.current)[key]);
    }, [changeZone]);

    /**
     * Die Bitte an das Graph-Panel, sein Bild wieder einzupassen (W10b, AC5).
     *
     * Eine Zahl und kein Zustand: jede Erhoehung ist eine neue Bitte. Sie steht
     * hier, weil "reset layout" sie ausloest; der Knopf in der Szene hat seinen
     * eigenen Zaehler, und beide gehen im Panel durch dieselbe Rechnung.
     */
    const [graphRefit, setGraphRefit] = useState(0);

    /**
     * Der Weg zurueck aus AC3: alle vier Grenzen auf die Vorgabe.
     *
     * Eine Funktion fuer beide Wege (Menuepunkt und Kommandozeile), damit sie
     * nicht auseinanderlaufen koennen. Der Erklaeren-Bereich klappt dabei NICHT
     * zu: "reset layout" ist eine Aussage ueber Groessen und nicht darueber, was
     * der Leser gerade erklaert haben will.
     *
     * Seit W10b passt der Graph sein Bild dabei wieder ein. Das ist kein zweiter
     * Gegenstand, sondern derselbe: die Zonen bekommen ihre Vorgabegroesse
     * zurueck, und die eingepasste Ansicht IST die Vorgabe des Graphen. Wer sich
     * in der Wolke verdreht hat, kommt sonst nur ueber den Knopf in der Szene
     * zurueck, und "reset layout" liesse ausgerechnet die Flaeche stehen, in der
     * man sich am leichtesten verliert.
     */
    const resetLayout = useCallback(() => {
        applyZones(defaultLayout(frameRef.current));
        setGraphRefit((count) => count + 1);
    }, [applyZones]);

    /**
     * Was gezeichnet wird: der Wunsch des Lesers, so weit das Fenster ihn traegt.
     *
     * Zwei Zahlen und nicht eine, und der Unterschied ist ein Nutzerbefund im
     * Kleinen: `zones` ist, was der Leser GEZOGEN hat, `shownZones` ist, was
     * davon in dieses Fenster passt. Bis dahin hatte ein Effekt die gezogene
     * Zahl beim Verkleinern des Fensters einfach ueberschrieben, und beim
     * Vergroessern kam sie nicht zurueck: wer sein Fenster kurz klein macht,
     * findet danach schmale Spalten vor und muss alles neu ziehen. Gemessen im
     * Beweislauf von W5c, der fuer seinen Tab-Test das Fenster verkleinert und
     * wieder vergroessert: die rechte Spalte blieb bei 402 statt 439 Pixeln
     * stehen, und der Graph verlor seinen Anteil an der Spalte.
     *
     * Der Wunsch bleibt also stehen, und begrenzt wird nur die Darstellung.
     */
    const shownZones = useMemo(() => clampLayout(zones, frame), [zones, frame]);

    /*
     * Die gemerkten Masse dieses Projekts, beim Projektwechsel neu gelesen.
     *
     * Pro Projekt, wie der Contract es verlangt: ein Repository mit tiefen
     * Pfaden braucht einen breiten Explorer, ein flaches nicht, und wer zwischen
     * beiden wechselt, will nicht jedes Mal nachziehen.
     */
    useEffect(() => {
        projectRef.current = project;
        setZones(readLayout(store, project, frameRef.current));
    }, [project, store]);

    const [whyAnswer, setWhyAnswer] = useState<WhyAnswer>({ asked: false });
    /** Von Hand wieder aufgerufen, ueber das [a]tlas-Menue. */
    const [whyReopened, setWhyReopened] = useState(false);
    /**
     * Ob der Leser die Frage in dieser Sitzung weggelegt hat, indem er anfing zu
     * lesen.
     *
     * Nutzerbefund vom 2026-08-29 mit zwei Screenshots: "wenn ich eine Klasse
     * anklicke, zum Beispiel orderService.ts, bleibt das und nicht der Code wird
     * gezeigt." Die Frage verschwand von selbst nur, solange KEINE Datei offen
     * war; von Hand wieder aufgerufen blieb sie ueber allem stehen, auch ueber
     * einer Datei. Das war Absicht fuer den Fall "mitten im Lesen den Modus
     * wechseln", und es ist die falsche Absicht, sobald der Leser danach etwas
     * anderes tut: der Klick im Explorer OEFFNETE die Datei, Tab und Breadcrumb
     * wechselten, und sichtbar blieb die Frage. Eine Aktion, die wirkt, ohne
     * dass man ihre Wirkung sieht, ist die schlimmste Sorte stillen Fehlschlags.
     *
     * Wer eine Datei oeffnet, ein Symbol waehlt oder eine Frage stellt, hat die
     * Frage beantwortet, indem er anfing zu lesen. Nur fuer diese Sitzung und
     * nicht im Speicher des Browsers: was er dauerhaft beantwortet, beantwortet
     * er mit einer der vier Karten oder mit dem Knopf darunter.
     */
    const [whyDismissed, setWhyDismissed] = useState(() => {
        try { return localStorage.getItem('cbm.workspace.setup') === 'done'; }
        catch { return true; }
    });

    const [tour, setTour] = useState<ActiveTour | undefined>(undefined);
    const [tourStep, setTourStep] = useState(0);
    const [tourMessage, setTourMessage] = useState('');
    const tourStepRef = useRef(0);
    tourStepRef.current = tourStep;

    /*
     * Der Walk hinter einem Vorwaerts-Gang, aufgehoben statt weggeworfen.
     *
     * Bis W4d wurde die Antwort von `getClosure` sofort in eine Fuehrung
     * uebersetzt und danach vergessen. Die Fuehrung ist aber eine Liste, und
     * eine Liste zeigt keine Tiefe: sie hat die Symbole ohne Datei schon
     * weggelassen und aus dem Graphen eine Reihe gemacht. Das Graph-Panel
     * bekommt deshalb den Walk selbst (W4e) und projiziert ihn, statt aus
     * Schritten einen Graphen zurueckzurechnen, den es nie gab.
     */
    const [walk, setWalk] = useState<ClosureResult | undefined>(undefined);

    const [entryOpen, setEntryOpen] = useState(false);
    const [overview, setOverview] = useState<ArchitectureOverviewDto | undefined>(undefined);
    const [overviewLoading, setOverviewLoading] = useState(false);
    const [overviewError, setOverviewError] = useState<string | undefined>();
    const [overviewRevision, setOverviewRevision] = useState(0);
    const repositoryReading = useRepositorySnapshot(project, overviewRevision);
    const [entryQuery, setEntryQuery] = useState('');
    const [entryHits, setEntryHits] = useState<RankedHit[]>(noHits);
    const [entryStatus, setEntryStatus] = useState<EntrySearchStatus>('idle');
    const [entryMessage, setEntryMessage] = useState('');
    const entryTicket = useRef(0);

    const [marks, setMarks] = useState<UnderstandingRecord>({ visited: {}, confirmed: {} });

    // -------------------------------------- Der BUG-Assistent und die Aenderung

    /*
     * Ob der Assistent zu sehen ist, abgeleitet aus dem Reiter.
     *
     * Kein eigener Schalter mehr, und das ist der Kern von W8: ein Schalter
     * neben dem Reiter waere die Stelle, an der beide auseinanderlaufen, und
     * zwei Flaechen mit je einem eigenen Schalter sind genau der Zustand, in
     * dem der Nutzer sie am 2026-08-29 uebereinander liegen sah.
     */
    const bugOpen = explainOpen && explainTab === 'bug';
    const [bugTarget, setBugTarget] = useState<BugPathNode | undefined>(undefined);
    const [bugPathsDto, setBugPathsDto] = useState<BugPathsDto | undefined>(undefined);
    const [bugStatus, setBugStatus] = useState<BugWizardStatus>('idle');
    const [bugMessage, setBugMessage] = useState('');
    const bugTicket = useRef(0);

    // ------------------------------------------ Das lokale Modell (W5a) ----

    /*
     * Drei Zustaende und kein vierter: was das Projekt erlaubt, was dieser
     * Browser eingestellt hat, und was der Prozess auf 4141 gerade von sich
     * gibt. Die ersten beiden entscheiden ueber das Fragen, der dritte ist die
     * Antwort auf das Gefragte.
     *
     * `llmPolicy` bleibt undefined, bis die Datei des Zielprojekts gelesen ist.
     * Genau so lange ist das LLM aus, auch wenn die Praeferenz an sagt: siehe
     * src/llm/llm-state.ts, Regel 3.
     */
    const [llmPolicy, setLlmPolicy] = useState<PolicyReading | undefined>(undefined);
    const llmPreferenceOn = false;
    const [llmProbe, setLlmProbe] = useState<SidecarReading>(EMPTY_SIDECAR_READING);
    const llmProbes = useRef(0);

    /*
     * Die Modellwahl dieses Browsers (W10), und der Griff, der sofort nachfragt.
     *
     * Die Wahl steht als Ref DANEBEN, weil der Probe-Timer sie liest: haenge er
     * an ihr, wuerde jede Wahl den Timer ab- und neu aufhaengen. Der Griff geht
     * die andere Richtung: wer waehlt, will die Zahlen des gewaehlten Modells
     * sehen, ohne drei Sekunden auf die naechste Runde zu warten. Er ruft
     * dieselbe Probe wie der Timer und landet damit im selben Zaehler; ein
     * zweiter Weg zum Sidecar waere eine Anfrage, die `__atlasLlm.probes` nicht
     * mitzaehlt, und der Beweislauf misst an der neuen Flaeche vorbei.
     */
    const [selectedModel, setSelectedModel] = useState('');
    const selectedModelRef = useRef('');
    selectedModelRef.current = selectedModel;

    // ------------------------------------------- Der Atlas-Chat (W5b) ------

    /*
     * Der Verlauf dieser Sitzung, und nur dieser.
     *
     * Im Speicher und nirgends sonst: kein localStorage, keine Datei, kein
     * Server. Das ist keine fehlende Funktion, sondern Non-Goal des Contracts.
     * Ein Verlauf, der den Reload ueberlebt, ist ein Protokoll darueber, was
     * jemand nicht verstanden hat, und dieses Produkt legt keines an.
     */
    const [chatTurns, setChatTurns] = useState<ChatTurn[]>([]);
    /** Martins Kontextregel als Einstellung. Vorgabe: Fokus plus erste Nachbarschaft. */
    const [chatDepth, setChatDepth] = useState<NeighborDepth>(NEIGHBOR_DEPTH_DEFAULT);
    const chatTicket = useRef(0);
    /*
     * Ob der Chat zu sehen ist, abgeleitet aus dem Reiter.
     *
     * Der Zustand, den W7c hier eingefuehrt hat, ist nicht verschwunden, er ist
     * eine Ebene hoeher gewandert: "hat dieser Leser schon gefragt" steht in
     * `chatTurns`, "will er die Antworten gerade sehen" im Reiter des
     * Erklaeren-Bereichs. Der Nutzerbefund vom 2026-08-29 dahinter gilt
     * unveraendert: Zumachen laesst den Verlauf stehen, und nur `clear` loescht.
     */
    const chatOpen = explainOpen && explainTab === 'chat';

    /*
     * Die Umformulierung des Pseudocode-Blocks.
     *
     * `refined` haelt das Ergebnis getrennt vom deterministischen Block, statt
     * ihn zu ersetzen: das Original muss jederzeit zurueckholbar sein, und ein
     * ueberschriebener Block waere genau das nicht mehr.
     */
    const [refineState, setRefineState] = useState<'idle' | 'running' | 'applied' | 'refused'>('idle');
    const [refineMessage, setRefineMessage] = useState('');

    /** Der Griff auf das Eingabefeld, fuer den einen Weg zurueck in die Suche. */
    const commandInputRef = useRef<HTMLInputElement | null>(null);

    /**
     * Die Grenzen des Vorwaerts-Walks, einmal aus der Adresszeile gelesen.
     *
     * Fehlt ein Parameter, entscheidet der Vorgabewert in provider/closure.ts.
     * Gelesen wird nur beim Start: eine Grenze, die sich waehrend eines Walks
     * aendert, waere ein Walk, der auf halber Strecke eine andere Frage
     * beantwortet.
     */
    const closureBounds = useMemo(() => {
        const params = new URLSearchParams(window.location.search);
        const read = (name: string): number | undefined => {
            const raw = params.get(name);
            if (raw === null) {
                return undefined;
            }
            const value = Number.parseInt(raw, 10);
            return Number.isFinite(value) ? value : undefined;
        };
        return { depth: read(CLOSURE_DEPTH_PARAM), cap: read(CLOSURE_CAP_PARAM) };
    }, []);

    /*
     * Der Vorwaerts-Walk aus dem Symbol im Fokus (W10b, AC3).
     *
     * Nutzerbefund vom 2026-08-30: "und hierarchies werden auch nicht
     * angezeigt." Die Ursache stand in GalaxyPanel.tsx: die Projektion hing am
     * WALK, und einen Walk gab es nur nach einem Einstiegs-Spaziergang oder in
     * einer Fuehrung. Ein Symbol im Fokus reichte nicht, obwohl der Leser genau
     * dann seinen Aufrufbaum sehen will.
     *
     * Drei Entscheidungen stecken darin:
     *
     *  1. **Derselbe Closure, dieselben Grenzen.** Gerechnet wird mit
     *     `getClosure` und mit `closureBounds`, also Zeichen fuer Zeichen wie
     *     beim Einstiegs-Spaziergang. Ein zweiter, eigener Weg waere ein zweites
     *     Bild derselben Frage.
     *  2. **Nur ohne laufenden Spaziergang.** Laeuft einer, ist er gemeint; ihn
     *     zu ueberschreiben, weil der Leser in ihm gerade woanders hinsieht,
     *     waere das Ende des Spaziergangs ohne Ansage.
     *  3. **Das Ergebnis waehlt keine Ansicht.** Es macht die Hierarchie
     *     moeglich, mehr nicht; die Vorgabe bleibt die Galaxie (Entscheidung 17
     *     im Kopf von GalaxyPanel.tsx).
     */
    const markedGraphRange = useMemo(() => markedSourceRange(readerSelection, activePath), [readerSelection, activePath]);
    const readerFocusRange = useMemo(() => markedGraphRange
        ?? (caretLine !== undefined && caretLine > 0 ? { startLine: caretLine, endLine: caretLine } : undefined), [markedGraphRange, caretLine]);
    const activeGalaxySelection = useMemo(() => resolveRepositorySelection(
        galaxySelectionProject === project ? galaxySelection : undefined, repositoryReading.snapshot,
    ), [galaxySelectionProject, project, galaxySelection, repositoryReading.snapshot]);
    const selectionUnavailable = Boolean(galaxySelectionProject === project && galaxySelection && repositoryReading.snapshot && !activeGalaxySelection);
    const selectionUnavailableText = 'The previous selection is absent from this bounded index snapshot. Choose a source element again to inspect its current evidence.';
    const selectedGraphSymbol = useMemo(() => hierarchySymbolOf(activeGalaxySelection, project), [activeGalaxySelection, project]);
    const readerFocusSymbol = (twinSymbol?.projectName === undefined || twinSymbol.projectName === project) && symbolMatchesReader(twinSymbol, activePath, readerFocusRange)
        ? twinSymbol : symbolMatchesReader(selectedGraphSymbol, activePath, readerFocusRange) ? selectedGraphSymbol : undefined;
    const hierarchyRoot = workspace === 'galaxy' ? selectedGraphSymbol : readerFocusSymbol;
    const focusHierarchy = useSelectionHierarchy(provider, ATLAS_WORKSPACE_ROOT, project, hierarchyRoot, closureBounds,
        workspace === 'galaxy' || (workspace === 'explore' && walk === undefined));
    const focusWalk = focusHierarchy.walk;

    // ------------------------------------------------------- Projekt -------

    useEffect(() => {
        const fromUrl = new URLSearchParams(window.location.search).get('project') ?? '';
        if (fromUrl.length > 0) {
            setUiLogProject(fromUrl);
            setProject(fromUrl);
            setProjectDetail('');
            return;
        }
        let cancelled = false;
        client
            .listProjects()
            .then((result) => {
                if (cancelled) {
                    return;
                }
                const first = result.projects[0];
                if (first === undefined) {
                    setProjectDetail(messages.statusbar.noProjectIndexed);
                    return;
                }
                setUiLogProject(first.name);
                    setProject(first.name);
                setProjectDetail('');
            })
            .catch((error: unknown) => {
                if (!cancelled) {
                    setServerOk(false);
                    setProjectDetail(messages.statusbar.noProjectError(String(error)));
                }
            });
        return () => {
            cancelled = true;
        };
    }, [client]);

    // ------------------------------------------------------- Kennzahlen ----

    useEffect(() => {
        if (project.length === 0) {
            return;
        }
        let cancelled = false;
        client
            .indexStatus(project)
            .then((status) => {
                if (cancelled) {
                    return;
                }
                setServerOk(true);
                const next: { nodes?: number; edges?: number } = {};
                if (status.nodes !== undefined) {
                    next.nodes = status.nodes;
                }
                if (status.edges !== undefined) {
                    next.edges = status.edges;
                }
                setCounts(next);
            })
            .catch(() => {
                if (!cancelled) {
                    setServerOk(false);
                    setCounts({});
                }
            });
        return () => {
            cancelled = true;
        };
    }, [client, project, overviewRevision]);

    // ------------------------------------------------------- Baum ----------

    useEffect(() => {
        if (project.length === 0) {
            return;
        }
        let cancelled = false;
        (async () => {
            const root = await api.tree(project, '');
            const nextLevels = new Map<string, TreeLevel>([['', root]]);
            const nextExpanded = new Set<string>();
            const queue = directoryPaths(root);
            while (queue.length > 0 && nextLevels.size < EAGER_LEVEL_BUDGET) {
                const dir = queue.shift();
                if (dir === undefined || nextLevels.has(dir)) {
                    continue;
                }
                const level = await api.tree(project, dir);
                if (cancelled) {
                    return;
                }
                nextLevels.set(dir, level);
                nextExpanded.add(dir);
                queue.push(...directoryPaths(level));
            }
            if (cancelled) {
                return;
            }
            setLevels(nextLevels);
            setExpanded(nextExpanded);
            setBudgetHit(queue.length > 0);
            setTreeError('');
            setServerOk(true);
        })().catch((error: unknown) => {
            if (!cancelled) {
                setLevels(emptyLevels);
                setExpanded(new Set<string>());
                setTreeError(String(error instanceof Error ? error.message : error));
                setServerOk(false);
            }
        });
        return () => {
            cancelled = true;
        };
    }, [api, project, overviewRevision]);

    /*
     * Die zweite Baumquelle: der Coverage-Store.
     *
     * Ein eigener Effekt und nicht ein Anhaengsel des Baum-Effekts, aus zwei
     * Gruenden. Erstens haengen die beiden an verschiedenen Dingen: der Baum an
     * `/api`, die Coverage an `/rpc`, und ein Ausfall der einen darf die andere
     * nicht mitnehmen. Zweitens ist die Reihenfolge egal: der Join ist eine
     * reine Funktion ueber beide Ergebnisse, also darf ankommen, was zuerst
     * fertig ist.
     */
    useEffect(() => {
        if (project.length === 0) {
            return;
        }
        let cancelled = false;
        setCoverageAsked(false);
        loadCoverage(client, project)
            .then((reading) => {
                if (cancelled) {
                    return;
                }
                setCoverage(reading.index);
                setCoverageMeta({ ...reading.answer.metadata });
                setCoverageAsked(true);
                setCoverageError('');
            })
            .catch((error: unknown) => {
                if (cancelled) {
                    return;
                }
                // Kein stiller Rueckfall auf "keine Luecken": ein Baum, der
                // Vollstaendigkeit behauptet, weil er nicht nachfragen konnte,
                // waere die teuerste Luege dieses Zyklus.
                setCoverage(EMPTY_COVERAGE);
                setCoverageMeta({});
                setCoverageAsked(false);
                setCoverageError(error instanceof Error ? error.message : String(error));
            });
        return () => {
            cancelled = true;
        };
    }, [client, project, overviewRevision]);

    /**
     * Die Vereinigung, aus der der Explorer zeichnet.
     *
     * Der Nur-Graph-Weg ist damit weg: `rows` haengt an dieser Karte und nicht
     * mehr an `levels`. Solange die Coverage-Antwort fehlt, ist die Vereinigung
     * genau der Graph, und die Notiz unter dem Baum sagt, dass noch niemand
     * gefragt hat.
     */
    const mergedLevels = useMemo(() => mergeCoverageIntoLevels(levels, coverage), [levels, coverage]);

    const rows = useMemo(() => flattenTree(mergedLevels, expanded), [mergedLevels, expanded]);

    const loadLevel = useCallback(
        async (path: string) => {
            const level = await api.tree(project, path);
            setLevels((current) => {
                const next = new Map(current);
                next.set(path, level);
                return next;
            });
        },
        [api, project],
    );

    const toggleDirectory = useCallback(
        (row: TreeRow) => {
            setExpanded((current) => {
                const next = new Set(current);
                if (next.has(row.path)) {
                    next.delete(row.path);
                } else {
                    next.add(row.path);
                }
                return next;
            });
            if (!levels.has(row.path)) {
                void loadLevel(row.path).catch((error: unknown) => {
                    // Ein Ordner, den nur die Coverage-Listen kennen, hat im
                    // Graphen keine Ebene. Dass /api/tree ihn nicht kennt, ist
                    // dann der erwartete Fall und kein Baumfehler; die Zeilen
                    // darunter kommen ohnehin aus der Vereinigung.
                    if (mergedLevels.get(row.path)?.synthetic === true) {
                        return;
                    }
                    setTreeError(String(error instanceof Error ? error.message : error));
                });
            }
        },
        [levels, loadLevel, mergedLevels],
    );

    // ------------------------------------------------------- Datei oeffnen -

    /**
     * Eine Datei oeffnen, mit dem Coverage-Befund als erster Instanz.
     *
     * Steht die Datei in einer der Listen, die "kein Inhalt" bedeuten, wird gar
     * nicht erst geladen: der Server liefert Inhalt ausschliesslich ueber einen
     * Modul-Knoten, und den gibt es fuer eine uebersprungene Datei nicht. Ein
     * Aufruf, dessen Ausgang schon feststeht, waere eine Anfrage, um eine
     * Fehlermeldung zu erzeugen, die man vorher kannte.
     *
     * Scheitert das Laden trotzdem an einem fehlenden Modul-Knoten, ist das
     * dieselbe Grenze und nicht ein Ausfall: `unavailable` statt `failed`, mit
     * der Begruendung, die der Lader selbst geschrieben hat.
     */
    const openFile = useCallback(
        (path: string) => {
            setWorkspace('explore');
            /*
             * Wer eine Datei oeffnet, hat die Frage beantwortet, indem er
             * anfing zu lesen (Nutzerbefund 2026-08-29, AC6f). Hier und nicht
             * im Explorer, weil dieselbe Funktion auch die Suche, die Zitate
             * des Chats, der Walk und jeder Sprung des Twin benutzen: eine
             * Regel an einer Stelle statt sechs Aufrufen derselben Regel.
             */
            setWhyReopened(false);
            setWhyDismissed(true);
            setTabs((current) => (current.includes(path) ? current : [...current, path]));
            setActivePath(path);
            setReaderSelection(undefined);
            // Flow steps retain their root across files. Reloading the same
            // document also keeps ready facts until the caret resolves again.
            if (!flowPinned.current && documentRef.current?.path !== path) {
                setTwinSymbol(undefined);
                setTwinIr(undefined);
                setTwinStatus('empty');
                setTwinName(messages.twin.noSymbol);
            }
            setImports(undefined);
            setDocument(undefined);
            setDocumentOrigin(undefined);
            loadTicket.current += 1;
            const ticket = loadTicket.current;

            const record = coverageRef.current.records.get(path);
            const state: CoverageState = record?.state ?? 'indexed';
            if (state === 'skipped' || state === 'not-indexed' || state === 'ignored') {
                setReaderStatus('unavailable');
                setReaderMessage(readerUnavailableNote(path, state, record?.reason ?? ''));
                return;
            }

            setReaderStatus('loading');
            setReaderMessage(messages.reader.loading(path, READER_RPC_TOOL));
            loadFileDocument(client, project, path)
                .then((loaded) => {
                    if (ticket !== loadTicket.current) {
                        return;
                    }
                    setDocument(loaded);
                    setDocumentOrigin({ project, version: `reader-load:${ticket}` });
                    setReaderStatus('ready');
                })
                .catch((error: unknown) => {
                    if (ticket !== loadTicket.current) {
                        return;
                    }
                    setDocument(undefined);
                    setReaderStatus(error instanceof FileNotReadableError ? 'unavailable' : 'failed');
                    setReaderMessage(error instanceof Error ? error.message : String(error));
                });
        },
        [client, project],
    );

    const closeTab = useCallback(
        (path: string) => {
            setTabs((current) => {
                const next = current.filter((entry) => entry !== path);
                if (path === activePath) {
                    const fallback = next[next.length - 1];
                    if (fallback === undefined) {
                        setActivePath('');
                        setDocument(undefined);
                        setReaderStatus('idle');
                        setReaderMessage(messages.reader.pickFile);
                    } else {
                        openFile(fallback);
                    }
                }
                return next;
            });
        },
        [activePath, openFile],
    );

    /*
     * Die Frische der offenen Datei.
     *
     * Eine eigene Frage je Datei, weil die Antwort nur beim Fragen entsteht:
     * der Server vergleicht mtime und Groesse der Datei auf der Platte mit dem,
     * was beim Indexlauf notiert wurde (mcp.c, coverage_path_freshness). Genau
     * darum meldet sie eine Datei, die seit dem Index geaendert wurde, und
     * genau darum steht sie nicht schon in den Listen, die beim Start geholt
     * wurden.
     *
     * Ein Fehler hier loescht die Notiz, statt eine alte stehenzulassen: eine
     * Frische-Angabe ueber die vorige Datei waere schlimmer als keine.
     */
    useEffect(() => {
        if (project.length === 0 || activePath.length === 0) {
            setOpenCoverage(undefined);
            return;
        }
        coverageTicket.current += 1;
        const ticket = coverageTicket.current;
        let cancelled = false;
        setOpenCoverage(undefined);
        loadPathCoverage(client, project, activePath)
            .then((answer) => {
                if (!cancelled && ticket === coverageTicket.current) {
                    setOpenCoverage(answer);
                }
            })
            .catch(() => {
                if (!cancelled && ticket === coverageTicket.current) {
                    setOpenCoverage(undefined);
                }
            });
        return () => {
            cancelled = true;
        };
    }, [activePath, client, project]);

    // ------------------------------------------------------- Caret-Strecke -

    // Der Caret wandert sofort in die Anzeige (Badge-Puls, data-current) und
    // erst nach der Ruhezeit in die Frage an den Graphen.
    useEffect(() => {
        if (caretLine === undefined) {
            return;
        }
        const timer = window.setTimeout(() => setSettledCaret(caretLine), TWIN_CARET_DEBOUNCE_MS);
        return () => window.clearTimeout(timer);
    }, [caretLine]);

    // Ein Dateiwechsel loescht die alte Lage. Der Caret der neuen Datei meldet
    // sich von selbst, sobald Monaco sein Modell getauscht hat; bis dahin
    // stehenzulassen, was ueber die vorige Datei bekannt war, waere ein Panel,
    // das ueber die falsche Datei spricht.
    useEffect(() => {
        setCaretLine(undefined);
        setSettledCaret(undefined);
        setPointedLine(undefined);
    }, [activePath]);

    useEffect(() => {
        if (project.length === 0 || activePath.length === 0 || settledCaret === undefined) {
            return;
        }
        // Waehrend einer Stepper-Sitzung bleibt das Subjekt stehen. Warum,
        // steht bei `flowPinned`.
        if (flowPinned.current) {
            return;
        }
        let cancelled = false;
        twinTicket.current += 1;
        const ticket = twinTicket.current;
        const current = () => !cancelled && ticket === twinTicket.current;

        (async () => {
            const resolved = await provider.resolveSymbolAt(
                ATLAS_WORKSPACE_ROOT,
                activePath,
                settledCaret,
                { projectName: project },
            );
            if (!current()) {
                return;
            }
            if (resolved.kind !== 'ok') {
                // Jeder der drei Faelle sagt etwas anderes, und keiner davon
                // heisst "dieses Symbol hat keine Fakten".
                setTwinSymbol(undefined);
                setTwinIr(undefined);
                setTwinName(messages.twin.noSymbol);
                if (resolved.kind === 'file-not-indexed') {
                    setTwinStatus('not-indexed');
                    setTwinMessage(TWIN_FILE_NOT_INDEXED);
                    setTwinHint(TWIN_FILE_NOT_INDEXED_HINT);
                } else if (resolved.kind === 'engine-unavailable') {
                    setTwinStatus('failed');
                    setTwinMessage(TWIN_LOAD_FAILED);
                    setTwinHint(resolved.reason);
                } else {
                    setTwinStatus('empty');
                    setTwinMessage(TWIN_EMPTY_MESSAGE);
                    setTwinHint(TWIN_EMPTY_HINT);
                }
                return;
            }

            const symbol = resolved.symbol;
            const unchanged =
                shownSymbol.current?.qualifiedName !== undefined &&
                shownSymbol.current.qualifiedName === symbol.qualifiedName;
            if (unchanged && twinIr !== undefined) {
                // Gleiches Subjekt, neuer Caret: nichts zu holen und nichts zu
                // melden. Auch nur kurz in den Ladezustand zu gehen waere ein
                // Blinken, das behauptet, es passiere etwas.
                return;
            }
            setTwinSymbol(symbol);
            setTwinIr(undefined);
            setTwinName(symbol.name);
            setTwinStatus('loading');
            setTwinMessage(TWIN_LOADING);
            setTwinHint('');
            const entry = await irCache.load(symbol);
            if (!current()) {
                return;
            }
            setTwinIr(entry.ir);
            setTwinStatus('ready');
        })().catch((error: unknown) => {
            if (!current()) {
                return;
            }
            setTwinIr(undefined);
            setTwinStatus('failed');
            setTwinMessage(TWIN_LOAD_FAILED);
            setTwinHint(error instanceof Error ? error.message : String(error));
        });

        return () => {
            cancelled = true;
        };
        // `twinIr` steht bewusst nicht in der Liste: es aendert sich als Folge
        // dieses Effekts, und eine Abhaengigkeit darauf waere eine Schleife.
        // Gelesen wird es nur, um zu entscheiden, ob schon etwas dasteht.
        // eslint-disable-next-line react-hooks/exhaustive-deps
    }, [provider, irCache, project, activePath, settledCaret, flowStep]);

    /**
     * Einem Ziel folgen: das Subjekt wechselt sofort, der Editor kommt nach.
     *
     * Die Fakten kommen aus der Aufloesung in der Zieldatei und nicht aus dem
     * Klickziel. Warum, steht oben im Kopf dieser Datei.
     */
    /**
     * Die stille Anzeige beim Folgen: das Item, dem gefolgt wurde, ist besucht.
     *
     * Vermerkt wird am Symbol, dessen Checkliste die Zeile traegt, und nicht am
     * Ziel: die Verpflichtung "verstehe den Aufruf von validateUser" gehoert
     * demjenigen, der aufruft. Findet sich keine Zeile, die auf dieses Ziel
     * zeigt, wird nichts vermerkt; ein Klick auf etwas, das nicht auf der Liste
     * steht, ist kein abgearbeiteter Punkt.
     */
    const markFollowed = useCallback(
        (target: SymbolRef) => {
            const ir = shownIr.current;
            const owner = ir?.symbol.qualifiedName;
            if (ir === undefined || owner === undefined || project.length === 0) {
                return;
            }
            const item = ir.checklist.find((entry) =>
                entry.target !== undefined
                && ((target.qualifiedName !== undefined
                    && entry.target.qualifiedName === target.qualifiedName)
                    || (target.qualifiedName === undefined && entry.target.uri === target.uri)));
            if (item === undefined) {
                return;
            }
            setMarks(markVisited(store, project, owner, item.id));
        },
        [project, store],
    );

    const followTarget = useCallback(
        (target: SymbolRef) => {
            setWorkspace('explore');
            setFlowStep(-1);
            flowPinned.current = false;
            markFollowed(target);
            const location = twinLocationOf(target);
            const keepReadyTwin = location.path.length > 0
                && keepsReadyTwinForTarget(target, shownSymbol.current, shownIr.current, twinStatus);
            setTwinName(target.name);
            if (!keepReadyTwin) {
                setTwinIr(undefined);
                setTwinSymbol(undefined);
                setTwinStatus('loading');
                setTwinMessage(TWIN_LOADING);
                setTwinHint('');
            }
            if (location.path.length === 0) {
                setTwinStatus('empty');
                setTwinMessage(TWIN_EMPTY_MESSAGE);
                setTwinHint(TWIN_EMPTY_HINT);
                return;
            }
            if (location.path !== activePath) {
                openFile(location.path);
            }
            setReveal((previous) => ({ line: location.line, nonce: (previous?.nonce ?? 0) + 1 }));
            if (location.path === activePath) setSettledCaret(location.line);
        },
        [activePath, markFollowed, openFile, twinStatus],
    );

    const pointRow = useCallback((row: TwinRow | undefined) => {
        setPointedLine(row?.siteLine);
    }, []);

    // ------------------------------------- Flow-Erklaerer und Pseudocode ---

    /**
     * Eine Zeile oeffnen: Datei anfahren, Zeile offenbaren, Zeile anleuchten.
     *
     * Derselbe Weg, den `followTarget` fuer eine Twin-Zeile geht, nur ohne den
     * Subjektwechsel: eine Pseudocode-Zeile zeigt auf eine Stelle im Text und
     * behauptet nicht, dass dort ein anderes Symbol das Thema wird. Was dort
     * steht, sagt der Reader; wer dort steht, sagt die Aufloesung, sobald der
     * Leser die Sitzung beendet.
     */
    const openLine = useCallback(
        (ref: PseudocodeSourceRef) => {
            const path = workspacePathOf(ref.uri);
            if (path.length === 0) {
                return;
            }
            if (path !== activePath) {
                openFile(path);
            }
            setPointedLine(ref.line);
            setReveal((previous) => ({ line: ref.line, nonce: (previous?.nonce ?? 0) + 1 }));
        },
        [activePath, openFile],
    );

    /**
     * Einen Schritt anlaufen: Kasten, STEPS-Liste und Editor bewegen sich
     * zusammen.
     *
     * Der Kasten und die Liste folgen dem Index (das Panel rechnet beides aus
     * demselben Modell), der Editor folgt der Quellangabe der Zeile. Eine
     * Zeile ohne Quellangabe bewegt den Editor nicht, statt irgendwohin zu
     * springen.
     */
    const stepFlow = useCallback(
        (index: number) => {
            const step = flowView?.steps[index];
            if (step === undefined) {
                return;
            }
            setFlowStep(index);
            flowPinned.current = true;
            if (step.line.sourceRef !== undefined) {
                openLine(step.line.sourceRef);
            }
        },
        [flowView, openLine],
    );

    /**
     * Der flow()-Kopf im Twin schaltet den Reiter.
     *
     * Steht der Bereich schon auf `flow`, klappt er zu; steht er woanders oder
     * ist er zu, geht er auf `flow` auf. Das ist dieselbe Bedienung wie vorher
     * (ein Kopf, ein Klick, auf und zu), und sie kostet seit W8 nichts mehr: der
     * Schritt bleibt, wo er war, und ein zweiter Klick zeigt wieder dieselbe
     * Stelle. Bis W8 setzte dieses Zumachen den Stepper zurueck, weil ein
     * Overlay eine Sitzung war; ein Reiter ist keine.
     */
    const toggleFlow = useCallback(() => {
        setExplainOpen((open) => !(open && explainTabRef.current === 'flow'));
        setExplainTab('flow');
    }, []);

    /**
     * Etwas erklaeren lassen: den Bereich aufmachen, auf DIESEM Reiter.
     *
     * Der eine Weg, auf dem jede der fuenf Flaechen aufgeht (AC4). Bis W8 hatte
     * jede ihren eigenen, und drei davon machten dabei die anderen zu, was der
     * Grund war, aus dem der Zustand jedes Mal verlorenging. Hier geht nichts zu:
     * es wird nur umgeschaltet.
     */
    const openExplain = useCallback((tab: ExplainTabId) => {
        setExplainTab(tab);
        setExplainOpen(true);
    }, []);

    /**
     * Den Bereich zuklappen, ohne irgendetwas zu kosten.
     *
     * Escape und der Knopf im Kopf gehen denselben Weg. Was hier NICHT steht,
     * ist der Punkt: kein `setChatTurns([])`, kein `setFlowStep(-1)`, kein
     * `setTour(undefined)`. Zumachen ist nicht loeschen, und das war der
     * Nutzerbefund, aus dem W7c den zweiten Knopf des Chats gebaut hat.
     */
    const collapseExplain = useCallback(() => {
        setExplainOpen(false);
    }, []);

    /*
     * Der Fakten-Block des aktiven Symbols. Rein aus dem, was schon dasteht:
     * die Pseudocode-Ansicht kostet keine einzige weitere Anfrage.
     *
     * Seit W8c sind es ZWEI Dinge, die schon dastehen, und das zweite ist der
     * Punkt: die IR des Symbols, und das geladene Layout der Galaxie. Aus dem
     * Layout liest der Block, was der Index ueber die AUFGERUFENEN Symbole
     * aufgezeichnet hat (was sie erheben koennen, was sie ihrerseits rufen, was
     * sie aus der Umgebung lesen), und schreibt es an die Schrittzeile. Es ist
     * dieselbe Quelle, aus der die Bedeutungssuche ihre Kandidaten nimmt
     * (`localIndex` weiter oben), und aus demselben Grund: sie ist da, sie ist
     * eine Antwort fuer das ganze Projekt, und sie noch einmal zu holen waere
     * ein zweiter Serverweg fuer eine Antwort, die im Speicher liegt. Was das
     * Layout NICHT hergibt, wird nicht nachgeladen und nicht erfunden; es steht
     * als `enrichmentAvailable.missing` im Dokument (src/pseudocode/
     * step-insights.ts).
     *
     * Ein Subjektwechsel wirft die Umformulierung weg. Sie gehoert zu genau
     * einem Block; sie ueber einen Symbolwechsel hinweg stehenzulassen waere
     * eine Umschreibung der Fakten eines anderen Symbols.
     */
    useEffect(() => {
        const ir = twinIr;
        setRefineState('idle');
        setRefineMessage('');
        if (ir === undefined) {
            setPseudocode(undefined);
            return;
        }
        setPseudocode(buildPseudocode(
            { kind: 'symbol', label: ir.symbol.name },
            { irs: [ir], ...(layout === undefined ? {} : { graph: layout }) },
        ));
    }, [layout, twinIr]);

    // Was die Datei um das Symbol herum hereinholt. Zwei Lesungen, eine davon
    // ist der Text, den der Reader ohnehin schon geladen hat; siehe
    // src/pseudocode/imports-source.ts.
    useEffect(() => {
        const ir = matchingInspectorIr(twinIr, twinSymbol, project, activePath);
        const uri = ir?.symbol.uri ?? twinTargetOf({ name: baseName(activePath), filePath: activePath, kind: 'module' })?.uri;
        if (!uri || project.length === 0 || activePath.length === 0) {
            setImports(undefined);
            return;
        }
        importsTicket.current += 1;
        const ticket = importsTicket.current;
        let cancelled = false;
        void fileImportsFor(provider, ATLAS_WORKSPACE_ROOT, {
            filePath: activePath,
            source: documentRef.current?.path === activePath ? documentRef.current.source : undefined,
            opts: { projectName: project, generation: 1 },
        })
            .then((answer) => {
                if (cancelled || ticket !== importsTicket.current) {
                    return;
                }
                setImports(buildImportsGroup({ imports: answer, irs: ir ? [ir] : [], uri }));
            })
            .catch(() => {
                if (!cancelled && ticket === importsTicket.current) {
                    // Eine fehlgeschlagene Import-Lesung ist kein Grund, die
                    // Fakten zu verlieren. Der Data-Block steht ohne sie.
                    setImports(undefined);
                }
            });
        return () => {
            cancelled = true;
        };
    }, [activePath, document, project, provider, twinIr, twinSymbol]);

    /*
     * Der Walk hinter dem Kasten.
     *
     * Er laeuft, sobald der Kasten offen ist und ein Subjekt dasteht: das
     * Design zeigt den Kasten sichtbar, also muss er sich selbst fuellen und
     * nicht auf einen zweiten Klick warten. Die IRs der erreichten Symbole
     * kommen aus dem IR-Cache; ein Symbol, das der Leser eben erst besucht hat,
     * kostet dabei keine Anfrage.
     */
    /*
     * Ein Subjektwechsel wirft den Walk weg, und zwar HIER und nicht im Lader.
     *
     * Bis W8 tat es der Lader mit, weil er ohnehin bei jedem Aufschlagen lief.
     * Seit der Erklaerer ein Reiter ist, laeuft der Lader nicht mehr bei jedem
     * Aufschlagen (sonst waere der Schritt bei jedem Reiterwechsel weg), und
     * damit braucht das Wegwerfen eine eigene Stelle. Ohne sie stuende nach
     * einem Symbolwechsel das Bild des vorigen Symbols da, und das waere die
     * schlimmste Sorte Fehler dieser Oberflaeche: eine richtige Antwort auf eine
     * andere Frage.
     */
    useEffect(() => {
        flowLoadedFor.current = '';
        setFlowView(undefined);
        setFlowStep(-1);
        setFlowMessage(twinKey.length === 0 ? FLOW_UNAVAILABLE : FLOW_LOADING);
    }, [twinKey]);

    useEffect(() => {
        const symbol = twinSymbol;
        if (!flowOpen || symbol === undefined || project.length === 0) {
            return;
        }
        // Dasselbe Symbol wird nicht zweimal geholt: sonst kostete jeder
        // Reiterwechsel den Schritt, an dem der Leser steht.
        if (flowLoadedFor.current === twinKey) {
            return;
        }
        flowLoadedFor.current = twinKey;
        flowTicket.current += 1;
        const ticket = flowTicket.current;
        let cancelled = false;
        const current = () => !cancelled && ticket === flowTicket.current;
        setFlowView(undefined);
        setFlowStep(-1);
        setFlowMessage(FLOW_LOADING);

        (async () => {
            const walk = await getClosure(provider, ATLAS_WORKSPACE_ROOT, symbol, {
                projectName: project,
                generation: 1,
                depth: FLOW_CLOSURE_DEPTH,
                cap: FLOW_CLOSURE_CAP,
            });
            if (!current()) {
                return;
            }
            const closure = closureDocumentOf(walk);
            // Was ankommt, kommt an. Ein Symbol, dessen IR nicht zu holen war,
            // wird vom Builder als Gruppe ohne Zeilen gezeigt und im ehrlichen
            // Block genannt; es wird nicht stillschweigend weggelassen.
            const irs: SemanticIR[] = [];
            for (const reached of closure.symbols) {
                const entry = await irCache.load(reached).catch(() => undefined);
                if (!current()) {
                    return;
                }
                if (entry !== undefined) {
                    irs.push(entry.ir);
                }
            }
            setFlowView(buildFlowView({
                closure,
                irs,
                depth: FLOW_CLOSURE_DEPTH,
                cap: FLOW_CLOSURE_CAP,
            }));
        })().catch(() => {
            if (current()) {
                // Der Vermerk faellt zurueck, damit ein zweiter Versuch moeglich
                // ist. Ein gemerkter Fehlschlag waere ein Symbol, das dieses
                // Fenster nie wieder zeichnet.
                flowLoadedFor.current = '';
                setFlowView(undefined);
                setFlowMessage(FLOW_UNAVAILABLE);
            }
        });

        return () => {
            cancelled = true;
        };
    }, [flowOpen, irCache, project, provider, twinKey, twinSymbol]);

    // ------------------------------------------------------- Galaxie -------

    const onLayout = useCallback((loaded: GraphData) => {
        setLayout(loaded);
    }, [project]);

    /**
     * Ein Klick in die Galaxie.
     *
     * Er geht durch denselben `followTarget` wie ein Klick im Twin: Datei
     * oeffnen, Zeile anfahren, und was dort steht, sagt die Aufloesung. Ein
     * Knoten ohne Datei kommt hier gar nicht an; das Panel sagt selbst, warum.
     */
    const openGalaxyNode = useCallback(
        (node: GraphNode) => {
            setGalaxySelection(node);
            setGalaxySelectionProject(project);
            const target = targetRefOfNode(node);
            if (target === undefined) {
                return;
            }
            followTarget(target);
        },
        [followTarget, project],
    );

    // ------------------------------------------------- Bedeutungssuche -----

    /**
     * Wie oft der Index ein Symbol erreicht, aus dem geladenen Layout.
     *
     * Die flache Suchform des Servers traegt keine solche Spalte
     * des Fan-in; das Layout traegt sie an jedem Knoten. Solange
     * keines geladen ist, hat kein Kandidat eine Zahl, und das entscheidet nur
     * bei Gleichstand.
     */
    const fanIn = useMemo(() => {
        const readings = new Map<string, number>();
        for (const node of layout?.nodes ?? []) {
            const qualifiedName = node.qualified_name;
            if (qualifiedName !== undefined && node.in_calls !== undefined) {
                readings.set(qualifiedName, node.in_calls);
            }
        }
        return readings;
    }, [layout]);

    const fanInOf = useCallback(
        (hit: { qualifiedName?: string }) => fanIn.get(hit.qualifiedName ?? '') ?? 0,
        [fanIn],
    );

    /**
     * Was dieses Fenster schon weiss, als Kandidatenmenge fuer die Suche.
     *
     * Zwei Quellen, beide schon im Speicher, beide ohne einen Serverweg: die
     * Knoten der Galaxie (Name, qualifizierter Name, Datei, Zeile) und die
     * Dateien des Baums. Warum daraus Vorschlaege werden duerfen und was sie
     * NICHT behaupten, steht in src/search/local-suggestions.ts.
     *
     * Gemerkt, weil daran der Sofort-Vorschlag zu jedem Tastendruck haengt: die
     * Menge neu zu bauen, sooft jemand einen Buchstaben tippt, waere die eine
     * Rechnung, die diesen Weg wieder langsam machen wuerde.
     */
    const localIndex = useMemo<LocalIndex>(() => {
        const nodes = layout?.nodes ?? [];
        if (nodes.length === 0 && rows.length === 0) {
            return EMPTY_LOCAL_INDEX;
        }
        return {
            symbols: nodes
                .filter((node) => node.name.length > 0)
                .map((node) => ({
                    name: node.name,
                    qualifiedName: node.qualified_name,
                    kind: symbolKindOf(node.label),
                    filePath: node.file_path,
                    line: node.start_line,
                })),
            files: rows.filter((row) => row.kind === 'file').map((row) => row.path),
        };
    }, [layout, rows]);

    const localPool = useMemo(() => localCandidates(localIndex), [localIndex]);

    /*
     * Woran die Beispiele der Kommandozeile haengen (AC6c).
     *
     * Ein Name aus dem geladenen Index und keine feste Liste: ein Beispiel mit
     * einem Symbol, das dieses Projekt nicht hat, waere eine Einladung ins
     * Leere. Gerechnet aus `localIndex.symbols`, also aus den Knoten des
     * Layouts, weil die den Namen UND die Art tragen; die Dateien des Baums
     * bleiben aussen vor, denn eine Datei ruft nichts, und zwei der drei
     * Beispiele fragen nach Aufrufen. Steht nichts, gibt es keine Beispiele.
     */
    const exampleSymbol = useMemo(
        () => exampleSymbolOf(localIndex.symbols.map((hit) => ({ name: hit.name, kind: hit.kind }))),
        [localIndex],
    );
    const commandExamples = useMemo(
        () => (exampleSymbol === undefined ? [] : commandExamplesFor(exampleSymbol)),
        [exampleSymbol],
    );

    /**
     * Die Zeilen, die sofort dastehen koennen, ohne dass jemand gefragt wird.
     *
     * Erst der Praefix-Cache (die vorige Antwort des Index, neu gerankt), dann
     * das schon Geladene, und beides in EINEN Rang: zwei Listen zu mischen
     * hiesse, eine zweite Ordnung neben der einen zu haben, die dieses Produkt
     * hat.
     */
    const instantHits = useCallback(
        (query: string): RankedHit[] => {
            const cached = prefixCache.current;
            const extendsCached =
                cached !== undefined
                && cached.complete
                && query.length > cached.query.length
                && query.startsWith(cached.query);
            if (extendsCached) {
                searchStats.current.prefixCacheHits += 1;
            }
            const pool = extendsCached
                ? [...(cached?.candidates ?? []), ...localPool]
                : localPool;
            return pool.length === 0
                ? noHits
                : rankLocalCandidates(pool, query, fanInOf, MAX_SEARCH_ROWS);
        },
        [fanInOf, localPool],
    );

    /*
     * Der Sofort-Vorschlag als Ref, und nicht als Abhaengigkeit des Effekts.
     *
     * Er haengt am Baum und an der Galaxie, und beide wachsen waehrend des
     * Ladens weiter. Stuende er in der Abhaengigkeitsliste, wuerde jede
     * nachgeladene Baumebene die laufende Suche zuruecksetzen und noch einmal
     * fragen. Gelesen wird er beim Tastendruck, und dann ist er auf dem Stand
     * dieses Bildes.
     */
    const instantRef = useRef(instantHits);
    instantRef.current = instantHits;

    /*
     * Die Suche, in zwei Schritten statt in einem.
     *
     * Nutzerbefund vom 2026-08-29: die Vorschlaege erscheinen zu langsam. Bis
     * dahin lief alles hintereinander: tippen, 200 ms Entprellung, ein Weg zum
     * Server je Wort, dann die erste Zeile. Der Bildschirm blieb in dieser Zeit
     * leer, obwohl die Antwort auf einen guten Teil der Frage schon im Browser
     * lag.
     *
     * Jetzt passieren zwei Dinge, und die Reihenfolge ist die Aussage:
     *
     *  1. **Sofort**, im selben Bild wie der Tastendruck, stehen die
     *     vorlaeufigen Zeilen da: aus der vorigen Antwort des Index, wenn das
     *     Wort nur verlaengert wurde, sonst aus Baum und Galaxie. Sie tragen
     *     ihre Marke, damit niemand sie fuer die Antwort haelt.
     *  2. **Nach der Entprellung** geht die Frage an den Index, mit einem
     *     Abbruch am Hals. Liefert die Antwort keine Treffer, bleiben die
     *     geladenen Vorschlaege erhalten und als geladen gekennzeichnet.
     *
     * Die Ticketpruefung bleibt und ist die eigentliche Zusicherung: eine
     * Antwort, die zu spaet kommt, wird verworfen und nicht angezeigt. Der
     * Abbruch spart zusaetzlich den Weg, den niemand mehr liest.
     */
    useEffect(() => {
        const query = command.trim();
        // Retire the previous response before the next debounce window begins.
        searchTicket.current += 1;
        const ticket = searchTicket.current;
        searchAbort.current?.abort();
        searchAbort.current = undefined;
        if (project.length === 0 || !isSearchable(query, SEARCH_MIN_QUERY)) {
            setHits(noHits);
            setAnsweredQuery('');
            setHitSource('index');
            setSearchStatus('ready');
            setSearchMessage('');
            return;
        }

        // Schritt 1: was ohne Serverweg zu haben ist, und zwar jetzt.
        const instant = instantRef.current(query);
        setHits(instant);
        setSelectedHit(0);
        setAnsweredQuery(query);
        setHitSource('loaded');
        setSearchStatus('searching');
        setSearchMessage('');
        if (instant.length > 0) {
            searchStats.current.localFirst += 1;
        }

        // Schritt 2: die Frage an den Index, sobald die Zeile still steht.
        const timer = window.setTimeout(() => {
            searchAbort.current?.abort();
            const controller = new AbortController();
            searchAbort.current = controller;
            searchStats.current.serverRequests += 1;
            const started = performance.now();
            searchByMeaning(
                provider,
                ATLAS_WORKSPACE_ROOT,
                query,
                { projectName: project, signal: controller.signal },
                fanInOf,
            )
                .then((answer) => {
                    const elapsed = Math.round(performance.now() - started);
                    if (answer.aborted) {
                        searchStats.current.abortedRequests += 1;
                        return;
                    }
                    if (ticket !== searchTicket.current) {
                        searchStats.current.staleDropped += 1;
                        return;
                    }
                    if (ticket < searchStats.current.appliedTicket) {
                        // Kann nicht passieren, solange die Zeile darueber
                        // greift. Steht trotzdem hier, weil eine Zusicherung,
                        // die niemand nachrechnet, keine ist.
                        searchStats.current.staleAnswerWins = true;
                        return;
                    }
                    searchStats.current.appliedTicket = ticket;
                    searchStats.current.serverRoundtripMs = elapsed;
                    searchStats.current.roundtrips.push(elapsed);
                    prefixCache.current = {
                        query,
                        candidates: answer.candidates,
                        complete: answer.complete,
                    };
                    const settled = settledSearchHits(answer.hits, instant);
                    setHits(settled.hits);
                    setSelectedHit(0);
                    setAnsweredQuery(query);
                    setHitSource(settled.source);
                    setSearchStatus('ready');
                    setSearchMessage('');
                })
                .catch((error: unknown) => {
                    if (controller.signal.aborted) {
                        searchStats.current.abortedRequests += 1;
                        return;
                    }
                    if (ticket !== searchTicket.current) {
                        searchStats.current.staleDropped += 1;
                        return;
                    }
                    setHits(noHits);
                    setAnsweredQuery(query);
                    setHitSource('index');
                    setSearchStatus('failed');
                    setSearchMessage(
                        `${SEARCH_FAILED}: ${error instanceof Error ? error.message : String(error)}`,
                    );
                });
        }, SEARCH_DEBOUNCE_MS);
        return () => {
            window.clearTimeout(timer);
            searchTicket.current += 1;
            searchAbort.current?.abort();
        };
    }, [command, project, provider, fanInOf]);

    const closeSearch = useCallback(() => {
        window.dispatchEvent(new Event(CLOSE_COMMAND_SEARCH_EVENT));
        searchTicket.current += 1;
        searchAbort.current?.abort();
        searchAbort.current = undefined;
        setCommand('');
        setHits(noHits);
        setAnsweredQuery('');
        setHitSource('index');
        setSearchStatus('ready');
        setSearchMessage('');
    }, []);

    /**
     * Einen Treffer waehlen: Datei oeffnen, Twin folgen, Galaxie hinterher.
     *
     * Die Kamerafahrt steht hier nicht: sie haengt am Twin-Subjekt, und das
     * wechselt, sobald die Aufloesung in der Zieldatei da ist. Sie von hier aus
     * zusaetzlich anzustossen hiesse, zweimal auf dasselbe zu zeigen und beim
     * zweiten Mal auf den Treffer statt auf das aufgeloeste Symbol.
     */
    const chooseHit = useCallback(
        (index: number) => {
            const chosen = hits[index];
            if (chosen === undefined) {
                return;
            }
            const target = twinTargetOf({
                name: chosen.hit.name,
                qualifiedName: chosen.hit.qualifiedName,
                kind: chosen.hit.kind,
                filePath: chosen.hit.filePath,
                startLine: chosen.hit.line,
            });
            if (target === undefined) {
                setSearchMessage(SEARCH_NO_FILE);
                return;
            }
            closeSearch();
            followTarget(target);
        },
        [closeSearch, followTarget, hits],
    );

    // ------------------------------- Warum, Fuehrungen und die Checkliste ---

    // Was dieser Browser ueber dieses Projekt weiss, beim Projektwechsel neu
    // gelesen. Beides ist an das Projekt gebunden und an nichts sonst.
    useEffect(() => {
        setWhyAnswer(readWhyAnswer(store, project));
        setMarks(readUnderstanding(store, project));
        setWhyReopened(false);
        setTour(undefined);
        setTourStep(0);
        setTourMessage('');
        setWalk(undefined);
    }, [project, store]);

    /**
     * Wann die Frage dasteht.
     *
     * Von selbst nur im leeren Editorbereich und nur, solange dieser Browser
     * fuer dieses Projekt keine Antwort kennt. Waehrend einer laufenden
     * Fuehrung nie: die Fuehrung ist die Antwort, die gerade ausgefuehrt wird.
     * Von Hand ueber das Menue jederzeit, und dann auch ueber einer offenen
     * Datei, weil der Wiederaufruf sonst genau dann nicht ginge, wenn jemand
     * mitten im Lesen den Modus wechseln will.
     */
    const whyVisible =
        tour === undefined
        && !entryOpen
        && !bugOpen
        && project.length > 0
        && !whyDismissed
        && (whyReopened || (!whyAnswer.asked && activePath.length === 0));

    /*
     * Der Stand fuer den Tastatur-Griff, bei jedem Bild neu geschrieben.
     *
     * Hier und nicht weiter unten, weil `whyVisible` hier entsteht: die Liste
     * soll an der Stelle stehen, an der ihr letzter Bestandteil bekannt ist,
     * damit niemand sie fuer vollstaendig haelt, waehrend eine Flaeche fehlt.
     */
    keyboardGuardRef.current = {
        /*
         * Nur die zwei Flaechen, die die Tastatur wirklich fuehren: die Hilfe
         * nimmt Escape, der Einstiegsdialog hat sein eigenes Suchfeld.
         *
         * Der Erklaeren-Bereich stand hier bis W8 mit drin, solange er ein
         * Overlay ueber dem Editor war. Als ZONE gehoert er nicht mehr dazu: er
         * liegt neben dem Reader, die Kommandozeile ist sichtbar, und wer bei
         * offenem Flow lostippt, meint die Zeile, die er sieht. Genau diese
         * Lesart hatten die Frage nach dem Warum, der Assistent und die
         * Aenderungsansicht schon vorher, und aus demselben Grund.
         */
        /*
         * Seit W10 sind es drei: das Einstellungen-Panel fuehrt die Tastatur
         * genauso wie die Hilfe (Escape schliesst es) und hat ausserdem ein
         * eigenes Eingabefeld. Ohne diesen Eintrag fielen Buchstaben, die
         * jemand vor dem offenen Panel tippt, in die Kommandozeile dahinter.
         */
        overlayOpen: helpOpen || entryOpen || settingsOpen || projectsOpen,
        walkRunning: tour !== undefined,
    };

    const closeTour = useCallback(() => {
        setTour(undefined);
        setTourStep(0);
        // Mit der Fuehrung geht auch der Walk: das Graph-Panel wuerde sonst die
        // Hierarchie einer Frage zeigen, die der Leser beendet hat.
        setWalk(undefined);
    }, []);

    /**
     * Der Vorwaerts-Walk ab einem gewaehlten Symbol.
     *
     * Zuerst wird die Wahl aufgeloest und erst danach gelaufen. Eine Suchzeile
     * und ein Eintrag der Zusammenfassung nennen eine Stelle, kein Symbol; der
     * Walk fragt den Graphen nach den Aufrufen eines qualifizierten Namens, und
     * die Wurzel muss deshalb das sein, was der Index an dieser Stelle kennt.
     * Scheitert die Aufloesung, wird mit dem gewaehlten Ziel gelaufen, damit
     * eine Wahl nicht folgenlos bleibt; was dabei fehlt, sagt der Walk selbst.
     */
    const startEntryWalk = useCallback(
        async (chosen: { name: string; qualifiedName?: string; kind: SymbolRef['kind']; filePath: string; line?: number }) => {
            setEntryOpen(false);
            setTourMessage('');
            const fallback = twinTargetOf({
                name: chosen.name,
                qualifiedName: chosen.qualifiedName,
                kind: chosen.kind,
                filePath: chosen.filePath,
                startLine: chosen.line,
            });
            try {
                let root = fallback;
                if (chosen.line !== undefined) {
                    const resolved = await provider.resolveSymbolAt(
                        ATLAS_WORKSPACE_ROOT,
                        chosen.filePath,
                        chosen.line,
                        { projectName: project },
                    );
                    if (resolved.kind === 'ok') {
                        root = resolved.symbol;
                    }
                }
                if (root === undefined) {
                    setTourMessage(messages.tour.failedNoFile(chosen.name));
                    return;
                }
                const closure = await getClosure(provider, ATLAS_WORKSPACE_ROOT, root, {
                    projectName: project,
                    generation: 1,
                    ...(closureBounds.depth === undefined ? {} : { depth: closureBounds.depth }),
                    ...(closureBounds.cap === undefined ? {} : { cap: closureBounds.cap }),
                });
                setWalk(closure);
                setTour(entryWalkTour(closure));
                setTourStep(0);
                openExplain('walk');
            } catch (error) {
                setTour(undefined);
                setWalk(undefined);
                setTourMessage(`${TOUR_FAILED}: ${error instanceof Error ? error.message : String(error)}`);
            }
        },
        [closureBounds, openExplain, project, provider],
    );

    const chooseIntent = useCallback(
        (intent: WhyIntent) => {
            setWhyAnswer(recordWhyAnswer(store, project, intent));
            setWhyReopened(false);
            if (intent === 'understand') {
                changeWorkspace('architecture');
            } else if (intent === 'entry') {
                setEntryOpen(true);
            } else if (intent === 'bug') {
                openExplain('bug');
            } else if (intent === 'change') {
                changeWorkspace('explore');
            }
        },
        [openExplain, project, changeWorkspace, store],
    );

    const declineWhy = useCallback(() => {
        // Der Knopf merkt sich nur die Antwort. Kein Profilwechsel: wer nichts
        // gesagt hat, hat nichts ueber seine Lesetiefe gesagt.
        setWhyAnswer(recordWhyAnswer(store, project));
        setWhyReopened(false);
        setWhyDismissed(true);
    }, [project, store]);

    /**
     * Die Frage weglegen, weil der Leser angefangen hat zu lesen.
     *
     * Anders als der Knopf darunter schreibt das NICHTS in den Speicher dieses
     * Browsers: eine Datei zu oeffnen ist keine Antwort auf "warum bist du
     * hier", sondern der Beweis, dass die Frage gerade nicht dran ist. Beim
     * naechsten Projekt oder nach dem Menuepunkt steht sie wieder da.
     */
    const dismissWhy = useCallback(() => {
        setWhyReopened(false);
        setWhyDismissed(true);
    }, []);

    // Ein Schritt bewegt den Reader. Die beiden Rueckrufe liegen in Refs, damit
    // dieser Effekt nur an Schritt und Fuehrung haengt: `followTarget` wechselt
    // seine Identitaet, sobald die geoeffnete Datei wechselt, was genau die
    // Folge dieses Effekts ist, und eine Abhaengigkeit darauf waere eine
    // Schleife.
    const followRef = useRef(followTarget);
    followRef.current = followTarget;
    const openRef = useRef(openFile);
    openRef.current = openFile;

    useEffect(() => {
        const step = tour?.document.steps[tourStep];
        if (step === undefined) {
            return;
        }
        const primary = step.primary;
        if (primary.kind === 'symbol') {
            const target = twinTargetOf({
                name: primary.name,
                qualifiedName: primary.qualifiedName,
                kind: primary.symbolKind,
                filePath: primary.filePath,
                startLine: primary.line,
            });
            if (target !== undefined) {
                followRef.current(target);
                return;
            }
        }
        openRef.current(primary.filePath);
    }, [tour, tourStep]);

    /**
     * Ein betretener Schritt ist ein besuchtes Item.
     *
     * Vermerkt wird erst, wenn die IR des Schritt-Symbols da ist: vorher gibt es
     * keine Checkliste, und ein Vermerk auf eine Id, die dieses Symbol gar nicht
     * hat, waere ein Haken an nichts. Welches Item, entscheidet
     * `markableItemId` aus dem portierten tour-model: das erste core-logic-Item,
     * so wie im Referenzprojekt.
     */
    useEffect(() => {
        if (tour === undefined || twinIr === undefined || project.length === 0) {
            return;
        }
        const owner = twinIr.symbol.qualifiedName;
        if (owner === undefined) {
            return;
        }
        const state = understandingOf(readUnderstanding(store, project), owner, twinIr.checklist);
        const item = markableItemId(state.items);
        if (item === undefined) {
            return;
        }
        setMarks(markVisited(store, project, owner, item));
    }, [tour, twinIr, project, store]);

    /** Die Zusammenfassung, sobald der Einstiegsdialog sie braucht. */
    useEffect(() => {
        if ((!entryOpen && workspace !== 'architecture') || project.length === 0) {
            return;
        }
        let cancelled = false;
        setOverviewLoading(true);
        setOverviewError(undefined);
        provider
            .architectureOverview(ATLAS_WORKSPACE_ROOT, { projectName: project, generation: 1 })
            .then((loaded) => {
                if (!cancelled) {
                    setOverview(loaded);
                    setOverviewLoading(false);
                }
            })
            .catch((error: unknown) => {
                if (!cancelled) {
                    setOverviewLoading(false);
                    setOverviewError(error instanceof Error ? error.message : String(error));
                    setEntryMessage(messages.entry.overviewFailed(
                        error instanceof Error ? error.message : String(error),
                    ));
                }
            });
        return () => {
            cancelled = true;
        };
    }, [entryOpen, workspace, project, provider, overviewRevision]);

    // Die Suche des Dialogs ist dieselbe Suche wie in der Kommandozeile, mit
    // derselben Entprellung. Zwei Rangfolgen fuer dasselbe Wort waeren zwei
    // Antworten auf eine Frage.
    useEffect(() => {
        const query = entryQuery.trim();
        if (!entryOpen || project.length === 0 || !isSearchable(query, SEARCH_MIN_QUERY)) {
            setEntryHits(noHits);
            setEntryStatus('idle');
            return;
        }
        setEntryStatus('searching');
        const timer = window.setTimeout(() => {
            entryTicket.current += 1;
            const ticket = entryTicket.current;
            findByMeaning(provider, ATLAS_WORKSPACE_ROOT, query, { projectName: project }, fanInOf)
                .then((ranked) => {
                    if (ticket !== entryTicket.current) {
                        return;
                    }
                    setEntryHits(ranked);
                    setEntryStatus('ready');
                    setEntryMessage(ranked.length === 0 ? messages.entry.noAnswer(query) : '');
                })
                .catch((error: unknown) => {
                    if (ticket !== entryTicket.current) {
                        return;
                    }
                    setEntryHits(noHits);
                    setEntryStatus('failed');
                    setEntryMessage(
                        `${SEARCH_FAILED}: ${error instanceof Error ? error.message : String(error)}`,
                    );
                });
        }, SEARCH_DEBOUNCE_MS);
        return () => window.clearTimeout(timer);
    }, [entryOpen, entryQuery, fanInOf, project, provider]);

    const offered = useMemo(() => entryRows(overview), [overview]);
    const entryHitRows = useMemo(() => searchRows(entryHits), [entryHits]);

    const chooseFlagged = useCallback(
        (key: string) => {
            const row = offered.rows.find((entry) => entry.key === key);
            const target = row?.target;
            if (target?.filePath === undefined) {
                return;
            }
            void startEntryWalk({
                name: target.name,
                qualifiedName: target.qualifiedName,
                kind: target.kind,
                filePath: target.filePath,
                line: target.startLine,
            });
        },
        [offered, startEntryWalk],
    );

    const chooseEntryHit = useCallback(
        (index: number) => {
            const chosen = entryHits[index];
            if (chosen === undefined) {
                return;
            }
            if (chosen.hit.filePath === undefined || chosen.hit.filePath.length === 0) {
                setEntryMessage(SEARCH_NO_FILE);
                return;
            }
            void startEntryWalk({
                name: chosen.hit.name,
                qualifiedName: chosen.hit.qualifiedName,
                kind: chosen.hit.kind,
                filePath: chosen.hit.filePath,
                line: chosen.hit.line,
            });
        },
        [entryHits, startEntryWalk],
    );

    // ------------------------- Der BUG-Assistent: Ziel, Lesung, Hop-Klick ---

    /**
     * Das Subjekt, das der Assistent uebernimmt.
     *
     * Das des Twins, und nur bei einem echten Symbolwechsel: ein Assistent, der
     * sich das erste Symbol merkt, das er gesehen hat, vergliche noch Pfade in
     * eine Funktion, die der Leser vor zehn Minuten verlassen hat, und nichts auf
     * dem Bildschirm sagte es. Umgekehrt darf ein Caret, der innerhalb desselben
     * Symbols wandert, die Lesung nicht neu anstossen.
     */
    useEffect(() => {
        if (!bugOpen) {
            return;
        }
        const next: BugPathNode | undefined =
            twinSymbol === undefined
                ? undefined
                : {
                    name: twinSymbol.name,
                    qualifiedName: twinSymbol.qualifiedName,
                    filePath: workspacePathOf(twinSymbol.uri),
                };
        setBugTarget((current) =>
            current?.name === next?.name && current?.qualifiedName === next?.qualifiedName
                ? current
                : next);
    }, [bugOpen, twinSymbol]);

    useEffect(() => {
        if (!bugOpen || project.length === 0 || bugTarget === undefined) {
            return;
        }
        bugTicket.current += 1;
        const ticket = bugTicket.current;
        setBugStatus('loading');
        setBugMessage('');
        bugPaths(client, api, bugTarget, { project })
            .then((paths) => {
                if (ticket !== bugTicket.current) {
                    return;
                }
                setBugPathsDto(paths);
                setBugStatus('ready');
            })
            .catch((error: unknown) => {
                if (ticket !== bugTicket.current) {
                    return;
                }
                setBugPathsDto(undefined);
                setBugStatus('failed');
                setBugMessage(error instanceof Error ? error.message : String(error));
            });
    }, [api, bugOpen, bugTarget, client, project]);

    /**
     * Ein Klick auf einen Hop.
     *
     * Der Name wird jetzt aufgeloest und nicht vorher: was in einer Aufzeichnung
     * steht, hat irgendwessen Rekorder geschrieben, und ein gespeicherter
     * SymbolRef ohne nodeId waere die Behauptung, dieses Symbol sei nicht
     * indiziert. Loest der Index nichts auf, wird nichts geoeffnet und der
     * Assistent sagt es.
     */
    const openHop = useCallback(
        (hop: BugPathNode) => {
            setBugMessage('');
            void resolveHop(provider, ATLAS_WORKSPACE_ROOT, hop, { projectName: project })
                .then((symbol) => {
                    if (symbol === undefined) {
                        setBugMessage(messages.wizard.unresolvedHop(hop.name));
                        return;
                    }
                    followRef.current(symbol);
                })
                .catch((error: unknown) => {
                    setBugMessage(error instanceof Error ? error.message : String(error));
                });
        },
        [project, provider],
    );

    // ------------------------------------------ Das lokale Modell (W5a) ----

    /*
     * Die Praeferenz dieses Browsers, beim Projektwechsel neu gelesen, so wie
     * die Antwort auf die Warum-Frage und die Vermerke. Sie haengt am Projekt
     * und an nichts sonst.
     */
    useEffect(() => {
        setLlmPolicy(undefined);
        setLlmProbe(EMPTY_SIDECAR_READING);
        // Die Modellwahl und die Anzeige haengen am selben Projekt und werden
        // deshalb hier mitgelesen. Beides ist pro Projekt gefuehrt, wie die
        // Zonenmasse und die Vermerke: ein anderes Repository ist eine andere
        // Frage und darf eine andere Antwort haben.
        setSelectedModel(readModelPreference(store, project).id);
        setDisplay(loadDisplaySettings(store, project));
    }, [project, store]);

    /*
     * Die committete Policy des ZIELprojekts, einmal je Projekt.
     *
     * Sie wird gelesen, sobald ein Projekt dasteht, und nicht erst, wenn jemand
     * den Schalter anfasst. Der Grund ist AC4 selbst: der Schalter soll
     * WIRKUNGSLOS sein und das auch sagen, bevor ihn jemand drueckt. Eine
     * Policy, die erst beim Einschalten gelesen wird, waere eine, die man einmal
     * umgehen kann.
     *
     * Das ist eine Anfrage an den Graph-Server, nicht an den Sidecar: sie geht
     * ueber denselben Weg wie jede Datei dieses Frontends und sagt ueber 4141
     * nichts.
     */
    useEffect(() => {
        if (project.length === 0) {
            return;
        }
        let cancelled = false;
        readLlmPolicy(client, project)
            .then((reading) => {
                if (!cancelled) {
                    setLlmPolicy(reading);
                }
            })
            .catch((error: unknown) => {
                if (!cancelled) {
                    // Kein stiller Rueckfall auf "erlaubt": wer die Datei nicht
                    // lesen konnte, weiss nicht, ob dort eine Sperre steht.
                    setLlmPolicy({
                        verdict: 'unreadable',
                        path: '.codeatlas/policy.json',
                        detail: error instanceof Error ? error.message : String(error),
                    });
                }
            });
        return () => {
            cancelled = true;
        };
    }, [client, project]);

    // Browser models have their own explicit opt-in. Saved sidecar settings cannot enable them.
    const llmMode = resolveLlmState(llmPolicy?.verdict, false);

    const llmState: SidecarState =
        llmMode === 'disabled-by-policy' ? 'disabled-by-policy' : llmMode === 'off' ? 'off' : llmProbe.state;
    const llmFacts = llmState === 'ready' ? llmProbe.facts : undefined;
    const llmModel = llmFacts?.model ?? '';
    /*
     * Die Liste des Cache-Verzeichnisses, und ob eine Auswahl daraus ueberhaupt
     * wirkt. Beides gilt nur, solange der Prozess wirklich antwortet: eine Liste
     * von vorhin unter einem gestorbenen Sidecar waere eine Auswahl ohne
     * Gegenstelle.
     */
    const llmRouter = llmState === 'ready' && llmProbe.router;
    const llmModels: readonly CacheModel[] = llmState === 'ready' ? llmProbe.models : NO_CACHE_MODELS;

    /**
     * Das Modell, das eine Chat-Anfrage mitschickt, oder nichts.
     *
     * Nur im Router-Modus: ein Einzel-Server ignoriert ein fremdes `model`-Feld
     * stillschweigend (gemessen, siehe src/llm/sidecar.ts), und ein Feld, das
     * nichts bewirkt, mitzuschicken hiesse, sich auf eine Wirkung zu verlassen,
     * die es nicht gibt. Ohne Wahl bleibt der Rumpf der Anfrage genau der, den
     * er vor W10 hatte.
     */
    const requestModel = llmRouter && selectedModel.length > 0 ? selectedModel : undefined;
    const selectedModelName = requestModel === undefined
        ? llmModel
        : llmModels.find((model) => model.id === requestModel)?.name ?? llmModel;

    /** Die Wahl umlegen: gemerkt, und sofort nachgefragt. */
    const chooseModel = useCallback(
        (id: string) => {
            const selected = recordModelPreference(store, project, id).id;
            /* The immediate probe below runs before React necessarily renders
             * the new state. Keep its request and the next explicit AI request
             * on the same router id. */
            selectedModelRef.current = selected;
            setSelectedModel(selected);
        },
        [project, store],
    );

    /** Eine Anzeige-Einstellung umlegen: gemerkt, und sofort wirksam. */
    const changeDisplay = useCallback(
        (next: GraphDisplaySettings) => {
            setDisplay(saveDisplaySettings(store, project, next));
        },
        [project, store],
    );

    /**
     * Der Schalter.
     *
     * Gegen eine Sperre tut er nichts, und zwar sichtbar nichts: die Praeferenz
     * wird dann nicht einmal geschrieben. Eine gespeicherte Praeferenz, die
     * niemals wirkt, waere ein Wert, der beim naechsten Projekt ohne Policy
     * ploetzlich etwas einschaltet, um das an dieser Stelle niemand gebeten hat.
     */
    const toggleLlm = useCallback(() => {
        setBrowserAiOpen(open => !open);
    }, []);

    // ------------------------------------------- Der Atlas-Chat (W5b) ------

    /**
     * Was eine Aufzeichnung auf dem Weg in ein Symbol gesehen hat.
     *
     * Eine Anfrage je Aufrufer an /api/trace, und keine fuenfte: die Route
     * haengt `observed` an einen Hop einer Antwort, die aus dem STATISCHEN
     * Graphen gerechnet ist (siehe src/traces/bug-paths.ts). Es gibt also keine
     * Liste beobachteter Aufrufe, die man abfragen koennte, sondern nur die
     * Frage "was wurde auf diesem Weg gesehen", und genau die wird hier
     * gestellt. Ohne importierte Aufzeichnung kommt nichts zurueck, und das
     * Rezept schreibt das als Notiz unter die Antwort statt es zu verschweigen.
     */
    const observedInto = useCallback(
        async (subject: SymbolRef, callers: readonly { qualifiedName?: string; name: string }[]) => {
            const to = subject.qualifiedName;
            if (to === undefined || project.length === 0) {
                return [] as ObservedFact[];
            }
            const found: ObservedFact[] = [];
            for (const caller of callers) {
                const from = caller.qualifiedName;
                if (from === undefined) {
                    continue;
                }
                const answer = await api.trace(project, from, to).catch(() => undefined);
                if (answer === undefined || !answer.reachable) {
                    continue;
                }
                answer.path.forEach((node, index) => {
                    const observed = node.observed;
                    const previous = answer.path[index - 1];
                    if (observed !== undefined && previous !== undefined) {
                        found.push({
                            from: previous.name,
                            to: node.name,
                            count: observed.count,
                            lastSeen: observed.lastSeen,
                        });
                    }
                });
            }
            return found;
        },
        [api, project],
    );

    /** Eine Karte oeffnen: derselbe Weg, den jeder andere Klick dieser Oberflaeche geht. */
    const openCardSource = useCallback(
        (source: CardSource) => {
            const target = twinTargetOf({
                name: source.name,
                qualifiedName: source.qualifiedName,
                kind: 'unknown',
                filePath: source.filePath,
                startLine: source.line,
            });
            if (target === undefined) {
                return;
            }
            followRef.current(target);
        },
        [],
    );

    /**
     * Eine Frage an den Atlas.
     *
     * Der Compiler steht vor dem optionalen Modellzug: auch wenn das Modell
     * aus, gesperrt oder nicht gestartet ist, bleiben Karten und ihre Quellen
     * lesbar. Der Zug nennt den echten Grund und schickt nichts an den Sidecar.
     */
    const askQuestion = useCallback(
        (question: string, chosenSubject?: string) => {
            chatTicket.current += 1;
            const id = chatTicket.current;
            const base: ChatTurn = {
                id,
                question,
                status: 'compiling',
                depth: chatDepth,
                cards: [],
                gaps: [],
                sources: [],
                answer: '',
                message: '',
            };
            const put = (turn: ChatTurn): void => {
                setChatTurns((current) => current.map((entry) => (entry.id === id ? turn : entry)));
            };
            setChatTurns((current) => [...current, base]);
            // Wer fragt, hat angefangen. Siehe AC6f und `dismissWhy`.
            setWhyReopened(false);
            setWhyDismissed(true);
            // Eine Antwort hinter einer eingeklappten Flaeche waere genau die
            // Stille, gegen die dieses Panel gebaut ist. Seit W8 heisst das: der
            // Erklaeren-Bereich geht auf, und zwar auf DEM Reiter, der die
            // Antwort traegt, statt einen zweiten Kasten aufzumachen.
            openExplain('chat');

            void askAtlas({
                question,
                source: provider,
                root: ATLAS_WORKSPACE_ROOT,
                origin: SIDECAR_ORIGIN,
                fetch: (url, init) => window.fetch(url, init),
                modelName: llmModel,
                modelClass: modelClassOf(llmFacts?.contextTokens),
                /*
                 * Die Modellwahl des Lesers, wenn sie wirkt. Siehe
                 * `requestModel`: ohne Router bleibt sie weg, und der Rumpf der
                 * Anfrage ist dann derselbe wie vor W10.
                 */
                depth: chatDepth,
                context: {
                    focusName: twinSymbol?.name,
                    focusQualifiedName: twinSymbol?.qualifiedName,
                    mode: bugOpen ? 'bug' : entryOpen ? 'entry'
                        : tour !== undefined ? 'tour' : 'none',
                },
                ...(twinSymbol === undefined ? {} : { focus: twinSymbol }),
                ...(chosenSubject === undefined ? {} : { chosenSubject }),
                observed: observedInto,
                opts: { projectName: project, generation: 1 },
                /* The normal turn always stops at the built card path. The
                 * model is an explicit choice in the rendered answer. */
                useModel: false,
                ...(llmState === 'ready' ? {} : {
                    modelUnavailableReason: llmState === 'disabled-by-policy'
                        ? 'policy'
                        : llmState === 'not-running' ? 'not-running' : 'off',
                }),
            }, id).then(put);
        },
        [
            bugOpen, chatDepth, entryOpen, llmFacts, llmMode, llmModel, llmState,
            observedInto, project, provider, tour, twinSymbol,
        ],
    );

    /**
     * Der Leser hat aus einer Kandidatenliste gewaehlt.
     *
     * Dieselbe Frage noch einmal, mit dem qualifizierten Namen daneben. Ein
     * NEUER Zug und keine Aenderung am alten: der Zug mit der Liste bleibt
     * stehen, damit sichtbar bleibt, dass es die Wahl gab und wie sie ausging.
     * Ein Zug, der sich unter der Hand in eine Antwort verwandelt, waere ein
     * Verlauf, dem man nicht ansieht, was passiert ist.
     */
    const pickCandidate = useCallback(
        (turn: ChatTurn, candidate: SubjectCandidate) => {
            askQuestion(turn.question, candidate.qualifiedName ?? candidate.name);
        },
        [askQuestion],
    );

    /*
     * Der Layout-Griff, bei jedem Bild neu geschrieben.
     *
     * Ohne Abhaengigkeitsliste, wie die anderen Naehte dieser Datei: eine Liste
     * waere eine zweite Stelle, an der jemand vergisst, ein Feld nachzutragen,
     * und ein Griff, der eine Lage von vorhin meldet, ist schlimmer als keiner.
     */
    useEffect(() => {
        globalThis.__atlasLayout = {
            sizes: { ...shownZones },
            requested: { ...zones },
            bounds: Object.fromEntries(
                LAYOUT_KEYS.map((key) => [key, layoutBounds(key, frame)]),
            ) as Record<LayoutKey, { min: number; max: number }>,
            defaults: defaultLayout(frame),
            isDefault: sameLayout(shownZones, defaultLayout(frame)),
            frame: { ...frame },
            explainOpen,
            explainTab,
            tabs: explainTabsRef.current.map((tab) => ({
                id: tab.id,
                enabled: tab.enabled,
                reason: tab.reason,
                note: tab.note,
            })),
            storageKey: layoutStorageKey(project),
            state: {
                chatTurns: chatTurns.length,
                walkStep: tour === undefined ? -1 : tourStep,
                walkSteps: tour?.document.steps.length ?? 0,
                flowStep,
                flowSteps: flowView?.steps.length ?? 0,
            },
        };
    });

    useEffect(() => {
        globalThis.__atlasChat = {
            turns: chatTurns.map((turn) => ({
                id: turn.id,
                question: turn.question,
                status: turn.status,
                klass: turn.klass ?? '',
                rule: turn.rule ?? '',
                depth: turn.depth,
                cards: turn.cards.length,
                cardIds: turn.cards.map((card) => card.id),
                sources: turn.sources.length,
                citations: turn.check?.cited ?? [],
                unknownCitations: turn.check?.unknown ?? [],
                uncitedLines: (turn.check?.violations ?? [])
                    .filter((entry) => entry.reason === 'no-citation').length,
                answer: turn.answer,
                refusal: turn.refusal ?? '',
                tokens: turn.tokens ?? 0,
                budget: turn.budget ?? 0,
                tokensPerSecond: turn.tokensPerSecond ?? 0,
                candidates: (turn.choice?.candidates ?? []).map((candidate) => ({
                    name: candidate.name,
                    qualifiedName: candidate.qualifiedName ?? '',
                    filePath: candidate.filePath ?? '',
                    line: candidate.line ?? 0,
                })),
                askedName: turn.choice?.name ?? turn.focusFallback?.asked ?? '',
                focusFallbackUsed: turn.focusFallback?.used ?? '',
            })),
            open: chatOpen,
            height: shownZones.explainHeight,
            maxHeight: layoutBounds('explainHeight', frame).max,
            depth: chatDepth,
            depthDefault: NEIGHBOR_DEPTH_DEFAULT,
            depthOptions: [...NEIGHBOR_DEPTHS],
            refineAvailable: llmState === 'ready',
            refineState,
            refineMessage,
            // Der echte Validator, an derselben Stelle, an der ihn der Knopf
            // ruft. Ein Beweislauf, der eine kaputte Antwort nachbaut, prueft
            // sonst eine Kopie der Regel statt der Regel.
            validateRefine: (answer: string) => {
                if (pseudocode === undefined) {
                    return { applied: false, reason: 'no block is shown' };
                }
                const outcome = applyRefinement(pseudocode, answer);
                return outcome.kind === 'applied'
                    ? { applied: true, reason: '' }
                    : { applied: false, reason: outcome.reason };
            },
        };
    });

    useEffect(() => {
        globalThis.__atlasLlm = {
            state: llmState,
            preferenceOn: llmPreferenceOn,
            policyVerdict: llmPolicy?.verdict ?? '',
            policyPath: llmPolicy?.path ?? '',
            policyDetail: llmPolicy?.detail ?? '',
            model: llmModel,
            chip: llmChipValue(llmState, llmModel),
            probes: llmProbes.current,
        };
    });

    /*
     * Der Griff des Einstellungen-Panels, bei jedem Bild neu.
     *
     * Er steht HIER und nicht im Panel, obwohl das Panel die Messungen macht:
     * die Wahl, die Anzeige-Einstellungen und die Modell-Liste gehoeren der
     * Anwendung und ueberleben das Zuklappen. Ein Griff, den nur ein offenes
     * Panel schreibt, waere nach dem Schliessen eine Beschreibung von vorhin,
     * und `llmOffMakesNoRequests` muss auch bei geschlossenem Panel lesbar sein.
     */
    useEffect(() => {
        globalThis.__atlasSettings = {
            open: settingsOpen,
            llmOn: llmMode === 'on',
            probes: llmProbes.current,
            router: llmRouter,
            selectedModel,
            cacheModels: llmModels.map((model) => ({
                id: model.id,
                name: model.name,
                loaded: model.loaded,
                status: model.status,
                active: model.id === selectedModel
                    || (selectedModel.length === 0 && model.name === llmModel),
            })),
            running: {
                model: llmModel,
                modelPath: llmFacts?.modelPath ?? '',
                quantization: llmFacts?.quantization ?? '',
                contextTokens: llmFacts?.contextTokens ?? 0,
                trainedContextTokens: llmFacts?.trainedContextTokens ?? 0,
                weightsBytes: llmFacts?.weightsBytes ?? 0,
                parameters: llmFacts?.parameters ?? 0,
            },
            suggestions: MODEL_SUGGESTIONS.map((entry) => ({
                id: entry.id,
                name: entry.name,
                repo: entry.repo,
                modelClass: entry.modelClass,
                passRate: entry.passRate,
                citationCompliance: entry.citationCompliance,
                citationUnmeasured: entry.citationUnmeasured ?? null,
                tokensPerSecond: entry.tokensPerSecond,
                bytes: entry.bytes,
                command: fetchCommand(entry.repo, entry.quant),
            })),
            display: { ...display },
            displayDefault: { ...DEFAULT_GRAPH_DISPLAY },
            isDefaultDisplay: isDefaultDisplay(display),
            storageKeys: { model: modelKey(project), display: displayKey(project) },
            measurements: Object.values(measurements),
        };
    });

    // ------------------------------------------------------- Tastatur ------

    const overlayOpen = isSearchable(command, SEARCH_MIN_QUERY);
    /**
     * Ob genau ein Zeichen dasteht: zu wenig zum Suchen, genug fuer eine
     * Antwort auf die Frage "warum passiert nichts".
     */
    const oneCharTyped = command.trim().length > 0 && !overlayOpen;
    const hitRows = useMemo(() => searchRows(hits, MAX_SEARCH_ROWS, hitSource), [hits, hitSource]);

    /*
     * Der Griff der Suche und der Menuezeile, bei jedem Bild neu geschrieben.
     *
     * Bei jedem Bild und nicht nur bei einer Aenderung: die Zaehler stehen in
     * Refs, also weiss React nichts von ihnen, und ein Effekt mit
     * Abhaengigkeitsliste wuerde sie nur zufaellig mitnehmen.
     */
    useEffect(() => {
        globalThis.__atlasSearch = {
            debounceMs: SEARCH_DEBOUNCE_MS,
            minQuery: SEARCH_MIN_QUERY,
            currentQuery: command.trim(),
            shownQuery: answeredQuery,
            shownSource: hitSource,
            shownRows: hitRows.length,
            localFirst: searchStats.current.localFirst,
            prefixCacheHits: searchStats.current.prefixCacheHits,
            serverRequests: searchStats.current.serverRequests,
            serverRoundtripMs: searchStats.current.serverRoundtripMs,
            roundtrips: [...searchStats.current.roundtrips],
            abortedRequests: searchStats.current.abortedRequests,
            staleDropped: searchStats.current.staleDropped,
            staleAnswerWins: searchStats.current.staleAnswerWins,
            localCandidates: localPool.length,
            activatedMenus: [...activatedMenus.current],
            keyListenerCapture: KEY_LISTENER_OPTIONS.capture,
        };
    });

    /**
     * Die Tasten des Suchfensters.
     *
     * Nur solange es offen ist, und nur die vier, die ihm gehoeren. Ein
     * verbrauchtes Ereignis wird als verbraucht markiert, damit das Chrome
     * Escape nicht ein zweites Mal liest und das Feld den Fokus verliert,
     * waehrend der Leser noch tippt.
     */
    /**
     * Was Enter in der Kommandozeile bedeutet.
     *
     * Die Entscheidung selbst steht in src/chat/command-intent.ts, samt
     * Begruendung: die Suche behaelt den Vorrang, und eine Zeile mit
     * Fragezeichen, eine Zeile mit @ und eine Zeile, auf die die Suche mit
     * nichts geantwortet hat, sind Fragen. Hier steht nur, was mit der
     * Entscheidung passiert.
     */
    const enterIntent = useMemo(
        () => commandIntent({
            line: command,
            hitCount: hitRows.length,
            answered: answeredQuery === command.trim() && searchStatus === 'ready',
        }),
        [answeredQuery, command, hitRows.length, searchStatus],
    );

    const onCommandKeyDown = useCallback(
        (event: KeyboardEvent<HTMLInputElement>) => {
            /*
             * Der eine Befehl steht VOR der Suche und vor der Frage.
             *
             * Nicht, weil er wichtiger waere, sondern weil er sonst nie
             * ankaeme: "reset layout" findet kein Symbol, also waere die Zeile
             * eine Frage an das Modell, und der Leser bekaeme eine Antwort
             * darueber, dass es kein Symbol dieses Namens gibt. Die Erkennung
             * ist absichtlich eng (src/layout/layout-command.ts); jede
             * Unschaerfe hier waere eine Suche, die stattdessen das Layout
             * umbaut.
             */
            if (event.key === 'Enter') {
                const line = lineCommandOf(command);
                if (line === 'reset-layout') {
                    event.preventDefault();
                    resetLayout();
                    setCommand('');
                    closeSearch();
                    return;
                }
                if (line === 'open-settings') {
                    event.preventDefault();
                    setSettingsOpen(true);
                    setCommand('');
                    closeSearch();
                    return;
                }
                if (experimentalAgentsEnabled && line === 'toggle-live-agents') {
                    event.preventDefault();
                    setLiveAgentsOn((on) => !on);
                    setCommand('');
                    closeSearch();
                    return;
                }
                /*
                 * "fullscreen" (W11b). Der Modus ist der Rahmen der
                 * Agenten-Ansicht; ist der Live-Modus aus, geht er mit an,
                 * statt dass die Zeile still nichts tut.
                 */
                if (experimentalAgentsEnabled && line === 'toggle-fullscreen') {
                    event.preventDefault();
                    setLiveAgentsOn(true);
                    setFullscreenToggle((count) => count + 1);
                    setCommand('');
                    closeSearch();
                    return;
                }
            }
            // Enter gilt auch dann, wenn kein Suchfenster offen ist: eine Frage
            // von zwei Zeichen Laenge oeffnet keines, und sie muss trotzdem
            // abschickbar sein.
            if (event.key === 'Enter' && enterIntent === 'ask') {
                event.preventDefault();
                const question = command.trim();
                closeSearch();
                askQuestion(question);
                return;
            }
            if (!overlayOpen) {
                return;
            }
            const intent = overlayIntent(event.key);
            if (intent === 'none') {
                return;
            }
            event.preventDefault();
            switch (intent) {
                case 'up':
                    setSelectedHit((current) => moveSelection(hitRows.length, current, -1));
                    return;
                case 'down':
                    setSelectedHit((current) => moveSelection(hitRows.length, current, 1));
                    return;
                case 'close':
                    closeSearch();
                    return;
                case 'choose':
                    chooseHit(selectedHit);
                    return;
                default:
                    return;
            }
        },
        [
            askQuestion, chooseHit, closeSearch, command, enterIntent, hitRows.length, overlayOpen,
            resetLayout, selectedHit,
        ],
    );

    /*
     * Der eine Griff am Fenster, der entscheidet, wer eine Taste bekommt.
     *
     * Er liegt am Fenster und nicht am Menue oder an der Zeile: beides soll
     * gelten, waehrend der Fokus im Baum, auf einem Knopf oder nirgends steht.
     * WANN eine Taste was bedeutet, entscheidet src/app/keyboard.ts (dort steht
     * auch, warum die Kuerzel seit dem 2026-08-29 Alt/Option tragen); WAS ein
     * Kuerzel tut, steht in `menuActionsRef`, das weiter unten bei den
     * Menuepunkten geschrieben wird.
     *
     * Die Reihenfolge ist die ganze Aussage, und sie steht hier einmal:
     *
     *  1. **Ein Menuekuerzel zuerst.** Alt/Option + Buchstabe, oder die
     *     reservierte Hilfetaste.
     *  2. **Eine Flaeche, die die Tastatur fuehrt, behaelt sie.** Das sind seit
     *     W8 noch zwei, die Hilfe und der Einstiegsdialog (siehe
     *     `keyboardGuardRef`); hinter ihnen faellt kein Zeichen in eine Zeile,
     *     die der Leser gerade nicht ansieht.
     *  3. **Einer laufenden Fuehrung gehoeren ihre vier Tasten.** Welche das
     *     sind, sagt `playerIntent` und nicht eine zweite Liste hier.
     *  4. **Alles andere Druckbare gehoert der Kommandozeile.** Sie holt sich
     *     den Fokus und bekommt das Zeichen, damit Tippen sichtbar ankommt,
     *     statt im Hintergrund Panels zu oeffnen (Nutzerbefund 2026-08-29).
     *
     * Seit W7b haengt der Griff in der EINFANGENDEN Phase. Der Grund steht bei
     * KEY_LISTENER_OPTIONS in src/app/keyboard.ts: der Nutzerbefund "alt plus
     * letter funktioniert nur fuer atlas" liess sich nicht nachstellen, also
     * wird nicht an einer Ursache geraten, sondern die eine Klasse von Ursachen
     * ausgeschlossen, die diese Anwendung selbst in der Hand hat, naemlich ein
     * Griff auf dem Weg nach oben, der die Taste vorher verbraucht. In der
     * einfangenden Phase sieht das Fenster den Druck als erster, und niemand
     * kann ihm zuvorkommen.
     *
     * Ein verbrauchtes Ereignis wird zusaetzlich gezeichnet (`markHandled`).
     * Das ist nicht fuer die Verdrahtung, sondern fuer den Tastentest der
     * Hilfeseite: `defaultPrevented` allein kann nicht sagen, ob DIESER Griff
     * die Taste genommen hat oder jemand vor ihm, und genau das ist die Frage,
     * die der Nutzerbefund stellt.
     */
    useEffect(() => {
        const onKeyDown = (event: globalThis.KeyboardEvent): void => {
            const target = event.target as Element | null;
            const shortcut = menuShortcutFor(event, target, WIRED_MENU_SHORTCUTS);
            if (shortcut !== undefined) {
                const act = menuActionsRef.current[shortcut];
                if (act !== undefined) {
                    event.preventDefault();
                    markHandled(event, shortcut);
                    act();
                }
                return;
            }
            const guard = keyboardGuardRef.current;
            if (guard.overlayOpen) {
                return;
            }
            if (guard.walkRunning && playerIntent(event.key) !== 'none') {
                return;
            }
        };
        window.addEventListener('keydown', onKeyDown, KEY_LISTENER_OPTIONS);
        return () => window.removeEventListener('keydown', onKeyDown, KEY_LISTENER_OPTIONS);
    }, []);

    /*
     * Escape schliesst die Hilfe, auch von ausserhalb der Hilfe.
     *
     * Die Seite faengt Escape schon selbst ab (sie holt sich den Fokus beim
     * Aufschlagen). Dieser Griff ist fuer den Fall danach: wer im Baum oder in
     * der Kommandozeile geklickt hat, waehrend die Hilfe offen steht, drueckt
     * Escape und meint trotzdem die Hilfe. Er haengt nur, solange sie offen ist,
     * damit Escape sonst genau so wenig bedeutet wie vorher.
     */
    useEffect(() => {
        if (!helpOpen) {
            return;
        }
        const onKeyDown = (event: globalThis.KeyboardEvent): void => {
            if (event.key !== 'Escape' || event.defaultPrevented) {
                return;
            }
            event.preventDefault();
            setHelpOpen(false);
        };
        window.addEventListener('keydown', onKeyDown);
        return () => window.removeEventListener('keydown', onKeyDown);
    }, [helpOpen]);

    // Dasselbe fuer das Einstellungen-Panel, und aus demselben Grund: wer im
    // Baum oder in der Kommandozeile geklickt hat, waehrend es offen steht,
    // drueckt Escape und meint trotzdem das Panel.
    useEffect(() => {
        if (!settingsOpen) {
            return;
        }
        const onKeyDown = (event: globalThis.KeyboardEvent): void => {
            if (event.key !== 'Escape' || event.defaultPrevented) {
                return;
            }
            event.preventDefault();
            setSettingsOpen(false);
        };
        window.addEventListener('keydown', onKeyDown);
        return () => window.removeEventListener('keydown', onKeyDown);
    }, [settingsOpen]);

    // And for the projects panel, which has input fields of its own as well.
    useEffect(() => {
        if (!projectsOpen) {
            return;
        }
        const onKeyDown = (event: globalThis.KeyboardEvent): void => {
            if (event.key !== 'Escape' || event.defaultPrevented) {
                return;
            }
            event.preventDefault();
            setProjectsOpen(false);
        };
        window.addEventListener('keydown', onKeyDown);
        return () => window.removeEventListener('keydown', onKeyDown);
    }, [projectsOpen]);

    /**
     * Die vier Tasten einer laufenden Fuehrung.
     *
     * Am Fenster und nicht an der Karte, weil der Fokus waehrend einer Fuehrung
     * fast immer im Editor steht: waeren die Tasten an der Karte, muesste der
     * Leser vor jedem Schritt erst dorthin klicken. Wo sie NICHT gelten, sagt
     * `tourKeyForEvent`; in Kuerze: in einem echten Eingabefeld.
     *
     * `d` ist die vierte und bewegt die Fuehrung nicht: sie schlaegt das Bild
     * zum Schritt auf. Es gibt es nur, wenn der Schritt ein Symbol hat, und
     * ohne Symbol passiert nichts und die Taste bleibt unverbraucht, damit ein
     * gedrueckte `d` nicht so aussieht, als haette es etwas getan.
     */
    useEffect(() => {
        const steps = tour?.document.steps.length ?? 0;
        if (steps === 0) {
            return;
        }
        const onKeyDown = (event: globalThis.KeyboardEvent): void => {
            const key = tourKeyForEvent(event, event.target as Element | null);
            if (key === undefined) {
                return;
            }
            const intent = playerIntent(key);
            if (intent === 'none') {
                return;
            }
            if (intent === 'diagram') {
                const step = tour?.document.steps[tourStepRef.current];
                if (step?.primary.kind !== 'symbol') {
                    return;
                }
                event.preventDefault();
                openExplain('flow');
                return;
            }
            event.preventDefault();
            if (intent === 'exit') {
                closeTour();
                return;
            }
            if (intent === 'prev') {
                setTourStep(stepMove(steps, tourStepRef.current, -1));
                return;
            }
            if (isLastStep(tourStepRef.current, steps)) {
                closeTour();
                return;
            }
            setTourStep(stepMove(steps, tourStepRef.current, 1));
        };
        window.addEventListener('keydown', onKeyDown);
        return () => window.removeEventListener('keydown', onKeyDown);
    }, [closeTour, openExplain, tour]);

    // Escape schliesst den Einstiegsdialog, auch aus seinem eigenen Suchfeld
    // heraus: dort ist Escape sonst nichts, und ein Dialog ohne Ausgang ueber
    // die Tastatur ist ein Dialog, aus dem man nur mit der Maus herauskommt.
    useEffect(() => {
        if (!entryOpen) {
            return;
        }
        const onKeyDown = (event: globalThis.KeyboardEvent): void => {
            if (event.key !== 'Escape') {
                return;
            }
            event.preventDefault();
            setEntryOpen(false);
        };
        window.addEventListener('keydown', onKeyDown);
        return () => window.removeEventListener('keydown', onKeyDown);
    }, [entryOpen]);

    /*
     * Escape schliesst die Frage nach dem Warum.
     *
     * Sie stand bis W8b NICHT im Escape-Griff dieser Datei: dort standen Hilfe,
     * Flow, Einstieg, Assistent, Aenderungsansicht und Suchfenster, und die
     * einzige Flaeche, die ueber dem Editor liegen und dort bleiben konnte,
     * hatte keinen Ausgang ueber die Tastatur (Nutzerbefund 2026-08-29, AC6f).
     * Der einzige Ausweg war ein Knopf, der "Not now" hiess.
     *
     * Die Stelle in der Reihenfolge ist die richtige und keine beliebige: die
     * Hilfe und der Einstiegsdialog liegen UEBER der Frage, das Suchfenster
     * gehoert der Kommandozeile, und der Erklaeren-Bereich liegt darunter. Der
     * Griff nimmt die Taste also nach den drei ersten und vor dem letzten, und
     * er markiert sie als verbraucht, damit der Bereich sie liegenlaesst.
     */
    useEffect(() => {
        if (!whyVisible) {
            return;
        }
        const onKeyDown = (event: globalThis.KeyboardEvent): void => {
            if (event.key !== 'Escape' || event.defaultPrevented) {
                return;
            }
            if (helpOpen || entryOpen || overlayOpen) {
                return;
            }
            event.preventDefault();
            dismissWhy();
        };
        window.addEventListener('keydown', onKeyDown);
        return () => window.removeEventListener('keydown', onKeyDown);
    }, [dismissWhy, entryOpen, helpOpen, overlayOpen, whyVisible]);

    /*
     * Escape klappt den Erklaeren-Bereich ein, und zwar zuletzt.
     *
     * Ein Griff fuer alle fuenf Reiter, wo bis W8 drei Griffe standen (Chat,
     * Flow-Overlay, und die Sammelklausel fuer Assistent und Aenderungsansicht).
     * Was dabei gilt, ist genau die Zusage aus W7c, nur breiter: Escape kostet
     * NICHTS. Kein Zug wird geloescht, kein Schritt zurueckgesetzt, keine
     * Fuehrung beendet; der Streifen darunter sagt weiter, was noch dasteht, und
     * ein Klick auf den Reiter bringt alles zurueck. Der Nutzerbefund vom
     * 2026-08-29, aus dem diese Trennung entstanden ist, gilt damit fuer jede
     * der fuenf Flaechen statt nur fuer den Chat.
     *
     * Der Griff nimmt die Taste nur, wenn sie sonst niemand braucht, und das ist
     * keine Hoeflichkeit, sondern die Reihenfolge: die Hilfe und der
     * Einstiegsdialog liegen ueber dem Editor, das Suchfenster steht ueber der
     * Kommandozeile, und eine Zone weiter unten, die ihnen Escape wegnaehme,
     * waere eine Zone, die eine offene Flaeche stehenlaesst. Dazu das Feld unter
     * dem Zeiger: wer in der Kommandozeile steht, verlaesst mit Escape die
     * Zeile, und dieser Griff hat dort nichts zu suchen.
     */
    useEffect(() => {
        if (!explainOpen) {
            return;
        }
        const onKeyDown = (event: globalThis.KeyboardEvent): void => {
            if (event.key !== 'Escape' || event.defaultPrevented) {
                return;
            }
            if (helpOpen || entryOpen || overlayOpen) {
                return;
            }
            /*
             * Genau EIN Feld behaelt Escape fuer sich, und es ist die
             * Kommandozeile: wer dort steht, verlaesst mit Escape die Zeile.
             * Nicht `isTypingTarget`, obwohl der Chat-Griff aus W7c das so
             * hatte: der Editor faellt darunter, und der Flow-Erklaerer schickt
             * bei jedem Schritt den Caret dorthin. Mit der weiten Pruefung waere
             * Escape genau dann taub, wenn der Leser gerade Schritte gegangen
             * ist, und das war bis W8 der Fall, den das Overlay mit einem
             * eigenen Griff ohne diese Pruefung abgedeckt hat.
             */
            if (event.target === commandInputRef.current) {
                return;
            }
            event.preventDefault();
            collapseExplain();
        };
        window.addEventListener('keydown', onKeyDown);
        return () => window.removeEventListener('keydown', onKeyDown);
    }, [collapseExplain, entryOpen, explainOpen, helpOpen, overlayOpen]);

    /**
     * Der Griff, an dem der Beweislauf die Fuehrung anfasst.
     *
     * `regenerate` ist der Determinismus-Beweis und steht deshalb hier und nicht
     * im Lauf: der Lauf soll dieselbe Erzeugung noch einmal ausloesen, die die
     * Anwendung benutzt, und nicht eine nachgebaute daneben. Angeboten wird sie
     * nur fuer die Projekt-Fuehrung; ein Vorwaerts-Walk haengt an einer Wahl und
     * ist nicht dieselbe Frage zweimal.
     */
    useEffect(() => {
        globalThis.__atlasTour =
            tour === undefined
                ? undefined
                : {
                    id: tour.document.id,
                    kind: tour.kind,
                    title: tour.document.title,
                    steps: tour.document.steps.length,
                    index: tourStep,
                    paths: tour.document.steps.map((step) => step.primary.filePath),
                    titles: tour.document.steps.map((step) => step.title),
                    endNote: tour.endNote,
                    json: JSON.stringify(tour.document),
                    regenerate:
                        tour.kind === 'project'
                            ? async () =>
                                JSON.stringify(
                                    (
                                        await generateProjectTour(provider, ATLAS_WORKSPACE_ROOT, {
                                            projectName: project,
                                            generation: 1,
                                        })
                                    ).document,
                                )
                            : undefined,
                };
    });

    const onTreeKeyDown = useCallback(
        (event: KeyboardEvent<HTMLUListElement>) => {
            const row = rows[cursor];
            const intent = treeIntent(event.key, row);
            if (intent === 'none') {
                return;
            }
            event.preventDefault();
            switch (intent) {
                case 'down':
                    setCursor(moveCursor(rows.length, cursor, 1));
                    return;
                case 'up':
                    setCursor(moveCursor(rows.length, cursor, -1));
                    return;
                case 'open':
                    if (row !== undefined) {
                        openFile(row.path);
                    }
                    return;
                case 'expand':
                case 'collapse':
                    if (row !== undefined) {
                        toggleDirectory(row);
                    }
                    return;
                case 'toParent': {
                    if (row === undefined) {
                        return;
                    }
                    const parent = parentPath(row.path);
                    const index = rows.findIndex((candidate) => candidate.path === parent);
                    if (index >= 0) {
                        setCursor(index);
                    }
                    return;
                }
                default:
                    return;
            }
        },
        [cursor, openFile, rows, toggleDirectory],
    );

    // ------------------------------------------------------- Anzeige -------

    /**
     * Die stille Anzeige fuer das Symbol vor dem Leser.
     *
     * Undefiniert, solange es keine Checkliste gibt, und die Statusleiste laesst
     * den Punkt dann ganz weg. "explored 0 of 0" waere ein Befund ueber das
     * Symbol, wo in Wahrheit noch niemand gefragt hat.
     */
    const understanding = useMemo(() => {
        const owner = twinIr?.symbol.qualifiedName;
        return owner === undefined || twinIr === undefined
            ? undefined
            : understandingOf(marks, owner, twinIr.checklist);
    }, [marks, twinIr]);
    const explored = exploredLabel(understanding);

    useEffect(() => {
        globalThis.__atlasChecklist = {
            symbol: understanding?.symbolQualifiedName ?? '',
            explored: understanding?.exploration.visited ?? 0,
            total: understanding?.exploration.total ?? 0,
            label: explored ?? '',
            marks: totalMarks(marks),
        };
    });

    const rootLevel = levels.get('');
    const treeNoteParts: string[] = [];
    if (treeError.length > 0) {
        treeNoteParts.push(`tree unavailable: ${treeError}`);
    } else if (rootLevel !== undefined) {
        treeNoteParts.push(`${rootLevel.files} files, ${rootLevel.symbols} symbols from ${TREE_ROUTE}`);
        const dropped = [...levels.values()].reduce((sum, level) => sum + level.droppedNonPaths, 0);
        if (dropped > 0) {
            treeNoteParts.push(
                dropped === 1
                    ? '1 index entry names no path and is not shown'
                    : `${dropped} index entries name no path and are not shown`,
            );
        }
        if (budgetHit) {
            treeNoteParts.push(`only ${EAGER_LEVEL_BUDGET} folders opened up front, the rest load on click`);
        }
    } else if (project.length === 0) {
        treeNoteParts.push(projectDetail.length > 0 ? projectDetail : 'no project');
    } else {
        treeNoteParts.push('loading the tree ...');
    }
    // Die zweite Quelle bekommt ihren eigenen Satz. "Noch nicht gefragt" und
    // "gefragt, nichts gefunden" sehen im Baum gleich aus und sind es nicht.
    if (coverageError.length > 0) {
        treeNoteParts.push(`coverage unavailable: ${coverageError}`);
    } else if (!coverageAsked) {
        treeNoteParts.push('joining the coverage lists ...');
    } else {
        treeNoteParts.push(
            `${coverage.counts.partial} partial, ${coverage.counts.skipped} skipped, `
            + `${coverage.counts.notIndexedFiles} files and ${coverage.counts.notIndexedDirs} folders `
            + `not indexed, ${coverage.counts.scopeEntries} coverage entries joined in`,
        );
    }

    const chips: Chip[] = [
        {
            label: messages.statusbar.chipProject,
            value: project.length > 0 ? project : messages.app.noProject,
            state: project.length > 0 ? 'plain' : 'absent',
        },
        {
            label: messages.statusbar.chipSymbols,
            value: counts.nodes === undefined ? messages.statusbar.noCount : String(counts.nodes),
            state: counts.nodes === undefined ? 'absent' : 'plain',
        },
        {
            label: messages.statusbar.chipEdges,
            value: counts.edges === undefined ? messages.statusbar.noCount : String(counts.edges),
            state: counts.edges === undefined ? 'absent' : 'plain',
        },
    ];

    const status: Chip[] = [
        {
            label: messages.statusbar.chipProject,
            value: project.length > 0 ? project : messages.app.noProject,
            state: project.length > 0 ? 'ok' : 'absent',
        },
        {
            label: messages.statusbar.chipServer,
            value: serverOk === undefined
                ? messages.statusbar.serverContacting
                : serverOk ? messages.statusbar.serverReady : messages.statusbar.serverUnreachable,
            state: serverOk === true ? 'ok' : serverOk === false ? 'absent' : 'plain',
        },
        {
            label: messages.statusbar.chipPort,
            value: window.location.port.length > 0 ? window.location.port : '80',
        },
        { label: messages.statusbar.chipTree, value: TREE_ROUTE },
        {
            label: messages.statusbar.chipSource,
            value: document === undefined ? messages.statusbar.noFileLoaded : READER_RPC_TOOL,
            state: document === undefined ? 'absent' : 'ok',
        },
        {
            label: messages.statusbar.chipGalaxy,
            value:
                layout === undefined
                    ? messages.galaxy.noLayout
                    : messages.galaxy.nodeCount(layout.nodes.length, !galaxyOn),
            state: layout === undefined ? 'absent' : galaxyOn ? 'ok' : 'plain',
        },
        /*
         * Der Chip des lokalen Modells. Er steht IMMER da, auch im Zustand aus,
         * und das ist der Punkt: "es gibt hier ein lokales Modell und es ist
         * aus" ist eine andere Aussage als ein Chip, der erst auftaucht, wenn
         * etwas laeuft. Der zweite waere aus der Ferne nicht von "dieses Produkt
         * kann das nicht" zu unterscheiden.
         */
        {
            label: messages.statusbar.chipLlm,
            value: llmChipValue(llmState, llmModel),
            state: llmState === 'ready' ? 'ok' : llmState === 'starting' ? 'plain' : 'absent',
        },
    ];
    /*
     * Die Frische-Notiz der offenen Datei.
     *
     * Sie steht nur da, wenn der Server etwas zu sagen hat: `metadata_match`
     * zusammen mit `no_recorded_issue` ist die Lage, in der die Datei seit dem
     * Index unveraendert ist und keine Quelle etwas gemeldet hat. Ein Chip, der
     * auch das anzeigt, waere eine Ampel, die immer leuchtet.
     */
    const coverageAnswer = openCoverage;
    const freshnessLabel =
        coverageAnswer !== undefined
        && freshnessNoteNeeded(coverageAnswer.status, coverageAnswer.freshness)
            ? freshnessNote(
                coverageAnswer.status,
                coverageAnswer.freshness,
                coverageAnswer.recommendedAction,
            )
            : '';
    if (freshnessLabel.length > 0) {
        status.push({ label: messages.statusbar.chipCoverage, value: freshnessLabel, state: 'absent' });
    }
    // Die stille Anzeige steht nur da, wenn sie etwas zu zaehlen hat.
    if (explored !== undefined) {
        status.push({ label: messages.statusbar.chipExplored, value: explored, state: 'ok' });
    }

    /*
     * Die Notiz ueber dem Editor.
     *
     * Nur fuer die eine Lage, in der der Text dasteht und trotzdem
     * unvollstaendig gelesen wurde: eine partiell geparste Datei. Die Faelle
     * ohne Inhalt sagen ihre Begruendung an der Stelle, an der sonst der Text
     * stuende, und brauchen darum keine zweite Zeile darueber.
     */
    const openRecord = coverage.records.get(activePath);
    const coverageNote =
        readerStatus === 'ready' && openRecord?.state === 'partial'
            ? { state: 'partially parsed', text: partialFileNote(activePath, openRecord.reason) }
            : undefined;

    useEffect(() => {
        globalThis.__atlasCoverage = {
            rows: rows.map((row) => ({
                path: row.path,
                kind: row.kind,
                coverage: row.coverage ?? 'indexed',
                reason: row.coverageReason ?? '',
                sources: row.coverageSources ?? [],
            })),
            records: [...coverage.records.values()].map((record) => ({
                path: record.path,
                kind: record.kind,
                state: record.state,
                reason: record.reason,
                sources: [...record.sources],
            })),
            truncations: [...coverage.truncations],
            counts: { ...coverage.counts },
            metadata: { ...coverageMeta },
            open:
                coverageAnswer === undefined
                    ? undefined
                    : {
                        path: coverageAnswer.path,
                        status: coverageAnswer.status,
                        freshness: coverageAnswer.freshness,
                        action: coverageAnswer.recommendedAction,
                        note: freshnessLabel,
                    },
            error: coverageError,
        };
    });
    if (tourMessage.length > 0) {
        status.push({ label: messages.statusbar.chipWalk, value: tourMessage, state: 'absent' });
    }

    const tabDescriptors: TabDescriptor[] = tabs.map((path) => ({
        path,
        name: baseName(path),
        active: path === activePath,
    }));

    // Badges nur, solange der Reader die Datei zeigt, in der das Symbol steht.
    // Ohne diese Bedingung malte ein Dateiwechsel fuer einen Wimpernschlag die
    // Aufrufstellen des vorigen Symbols in die neue Datei.
    const twinPath = twinSymbol === undefined ? '' : workspacePathOf(twinSymbol.uri);
    // Gemerkt, damit der Editor seine Dekorationen nur dann neu setzt, wenn sich
    // die Schritte wirklich geaendert haben, und nicht bei jedem Bild.
    const badges = useMemo(
        () =>
            twinIr !== undefined && twinPath === activePath
                ? badgesForLines(
                      twinIr.steps.value.map((call) => ({ line: call.line, label: call.targetName })),
                  )
                : noBadges,
        [twinIr, twinPath, activePath],
    );

    /*
     * Die vier Eintraege der Atlas-Zeile, EINMAL.
     *
     * Sie stehen als Liste da und nicht zweimal ausgeschrieben, weil sie seit
     * dem 2026-08-29 zwei Leser haben: das Menue zeichnet sie, und die Tastatur
     * ruft sie. Zwei Fassungen derselben Liste waeren zwei Gelegenheiten, ein
     * Etikett zu aendern und das Kuerzel dabei zu vergessen, und ein Menuepunkt,
     * dessen Buchstabe etwas anderes tut, als daneben steht, ist schlimmer als
     * einer ohne Buchstaben.
     *
     * `key` ist das Suffix von `data-menu` (also `a-why`) und bleibt, was es
     * war: die Beweislaeufe fassen die Eintraege daran an. `shortcut` ist der
     * Buchstabe, und er steht im Etikett in Klammern, weil ein Terminal keine
     * Unterstreichung hat.
     */
    const atlasEntries: readonly (MenuExtra & { shortcut: string })[] = [
        {
            key: 'why',
            shortcut: 'w',
            label: WHY_MENU_LABEL,
            title: messages.menu.why,
            onSelect: () => {
                // Die Frage neu zu stellen heisst, von vorn anzufangen: die
                // laufende Fuehrung endet, und der Erklaeren-Bereich klappt zu,
                // damit die Frage die leere Editorflaeche bekommt.
                closeTour();
                setEntryOpen(false);
                collapseExplain();
                setWhyDismissed(false);
                setWhyReopened(true);
            },
        },
        {
            key: 'bug',
            shortcut: 'b',
            label: BUG_WIZARD_MENU_LABEL,
            title: messages.menu.bug,
            onSelect: () => {
                /*
                 * Kein `closeTour()` mehr, und das ist eine Aenderung mit Grund.
                 * Bis W8 deckte der Assistent den Editor ab und die Schrittkarte
                 * lag darunter, also musste die Fuehrung weichen. Jetzt teilen
                 * sich beide einen Platz und wechseln ueber einen Reiter; eine
                 * Fuehrung zu beenden, weil jemand kurz in den Assistenten
                 * schaut, waere genau der Zustandsverlust, den dieser Zyklus
                 * abschafft.
                 */
                setEntryOpen(false);
                setWhyReopened(false);
                openExplain('bug');
            },
        },
        /*
         * Der Weg zurueck aus AC3, als Menuepunkt.
         *
         * Er steht in derselben Zeile wie die anderen vier und traegt wie sie
         * einen Buchstaben: eine Handlung, die es nur in der Kommandozeile gibt,
         * ist in einer Oberflaeche, deren Vorbild die Tastatur ist, eine halbe
         * Handlung.
         */
        {
            key: 'layout',
            shortcut: 'r',
            label: messages.layout.resetMenuLabel,
            title: messages.layout.resetTooltip,
            onSelect: resetLayout,
        },
        /*
         * Der Schalter im Menue, mit demselben Ausgang wie der im Panel.
         * Ein Extra traegt keinen Zustand, also traegt ihn sein Etikett:
         * `[l]lm off` heisst "es ist aus" und nicht "hier ausschalten".
         * Diese Lesart ist dieselbe wie bei [a]tlas, dessen `data-state`
         * ebenfalls die Lage und nicht die Wirkung faerbt.
         */
        {
            key: 'llm',
            shortcut: 'l',
            label: messages.browserChat.menuLabel,
            title: messages.browserChat.menuTitle,
            onSelect: toggleLlm,
        },
        /*
         * Das Einstellungen-Panel (W10), als Eintrag der Atlas-Zeile.
         *
         * Es schaltet, wie [a]tlas und [?]help: der Buchstabe steht fuer die
         * Flaeche, und ein zweiter Druck macht sie wieder zu. Ein Eintrag, der
         * nur oeffnet, waere in dieser Zeile der einzige.
         */
        {
            key: 'settings',
            shortcut: 's',
            label: messages.settings.menuLabel,
            title: messages.menu.settings,
            onSelect: () => setSettingsOpen((open) => !open),
        },
        /*
         * The projects panel, as an entry of the atlas row. It toggles like
         * [s]ettings next to it: the letter stands for the surface, and a
         * second press closes it again.
         */
        {
            key: 'projects',
            shortcut: 'p',
            label: messages.projects.addIndexLabel,
            title: messages.projects.addIndexTitle,
            onSelect: () => setProjectsOpen((open) => !open),
        },
        /*
         * Der Live-Modus der Agenten (W11a), als Eintrag der Atlas-Zeile.
         *
         * Er schaltet, wie [l]ocal llm daneben, und sein Etikett traegt den
         * ZUSTAND und nicht die Wirkung: "off" heisst "es ist aus". Es gibt ihn
         * hier und in der Kommandozeile ("live agents"), weil ein Modus, der per
         * Vorgabe aus ist, sonst nur denen gehoert, die das Kuerzel kennen.
         */
        ...(experimentalAgentsEnabled ? [{
            key: 'agents',
            shortcut: 'g',
            label: agentsMenuLabel(liveAgentsOn),
            title: liveAgentsOn ? messages.menu.agentsOn : messages.menu.agentsOff,
            onSelect: () => setLiveAgentsOn((on) => !on),
        }] : []),
    ];

    /*
     * Was ein Buchstabe tut, in einem Ref und nicht in einer Abhaengigkeit.
     *
     * Der Griff am Fenster wird einmal eingehaengt (unten, mit leerer
     * Abhaengigkeitsliste), weil ein Menuekuerzel keinen Grund hat, bei jedem
     * Bild ab- und wieder anzumelden. Die Handlungen darin haengen aber an
     * `llmState`, an `tour` und an drei Zustandssetzern; sie in die Schliessung
     * des Effekts zu schreiben hiesse, dass der Buchstabe die Lage von vor
     * hundert Bildern schaltet. Das Ref ist die Stelle, an der beides
     * zusammengeht: bei jedem Bild neu geschrieben, vom Griff bei jedem
     * Tastendruck frisch gelesen.
     */
    /**
     * Eine Handlung, mit einem Vermerk davor.
     *
     * Der Vermerk steht dort, wo die Handlung LAEUFT, und nicht dort, wo
     * geklickt wird: ein Beweislauf, der Klicks zaehlt, hat Klicks bewiesen. Er
     * ist auch der Grund, aus dem Knopf und Taste dieselbe Funktion rufen statt
     * zwei gleich aussehender: dass die Maus und die Tastatur dasselbe tun,
     * soll keine Behauptung sein, sondern eine Eigenschaft der Verdrahtung.
     */
    const menuAct = (letter: string, act: () => void) => () => {
        setWorkspace('explore');
        activatedMenus.current = [...activatedMenus.current, letter];
        act();
    };

    menuActionsRef.current = {
        a: menuAct('a', () => setGalaxyOn((current) => !current)),
        '?': menuAct('?', () => setHelpOpen((current) => !current)),
        ...Object.fromEntries(
            atlasEntries.map((entry) => [entry.shortcut, menuAct(entry.shortcut, entry.onSelect)]),
        ),
    };

    const menus: Partial<Record<string, MenuWiring>> = {
        a: {
            title: galaxyOn ? messages.menu.atlasHide : messages.menu.atlasShow,
            state: galaxyOn ? 'on' : 'off',
            onSelect: menuActionsRef.current['a'] ?? (() => undefined),
            extras: atlasEntries.map((entry) => ({
                ...entry,
                onSelect: menuActionsRef.current[entry.shortcut] ?? entry.onSelect,
            })),
        },
        /*
         * `[?]help` schaltet, statt nur zu oeffnen, und zwar aus demselben
         * Grund wie `[a]tlas`: der Buchstabe steht fuer die Flaeche, und ein
         * zweiter Druck auf denselben Buchstaben macht sie wieder zu. Ein
         * Menuepunkt, der nur oeffnet, waere der einzige der Zeile, dessen
         * `data-state` eine Lage anzeigt, die er selbst nicht umkehren kann.
         */
        '?': {
            title: helpOpen ? messages.menu.helpClose : messages.menu.helpOpen,
            state: helpOpen ? 'on' : 'off',
            onSelect: menuActionsRef.current['?'] ?? (() => undefined),
        },
    };

    const commandOverlay = overlayOpen ? (
        <SearchOverlay
            /*
             * Drei Saetze und nicht zwei, seit die Liste vor der Antwort
             * dasteht. "searching for x" waere ueber einer gefuellten Liste
             * eine halbe Auskunft: es stimmt, dass gesucht wird, und es
             * verschweigt, woher die Zeilen darunter kommen.
             */
            headline={
                hitSource === 'loaded'
                    ? searchStatus === 'ready'
                        ? workspaceText.loadedSearchHeadline(answeredQuery, hitRows.length)
                        : hitRows.length === 0
                            ? messages.search.provisionalEmpty(answeredQuery)
                            : messages.search.provisionalHeadline(answeredQuery, hitRows.length)
                    : searchStatus === 'searching' && answeredQuery !== command.trim()
                        ? messages.search.searching(command.trim())
                        : searchHeadline(answeredQuery, hits.length, hitRows.length)
            }
            rows={hitRows}
            selected={selectedHit}
            status={searchStatus}
            message={searchMessage}
            onChoose={chooseHit}
            onPoint={setSelectedHit}
        />
    ) : oneCharTyped ? (
        /*
         * Ein einziges Zeichen sucht noch nicht, und das steht jetzt DORT, wo
         * die Treffer stehen wuerden.
         *
         * Nutzerbefund vom 2026-08-29: der Grund stand nur klein am rechten Rand
         * der Zeile, und wer tippt, sieht nach oben, wo die Antwort erscheint.
         * Dort stand nichts, also sah es aus, als antworte die Suche gar nicht.
         * Dasselbe Fenster, dieselbe Stelle, ein Satz statt einer Leere.
         */
        <SearchOverlay
            headline={COMMAND_ONE_MORE_LETTER}
            rows={noRows}
            selected={-1}
            status="ready"
            message=""
            onChoose={chooseHit}
            onPoint={setSelectedHit}
        />
    ) : undefined;

    /*
     * Wo die Fuehrung steht, als qualifizierter Name.
     *
     * Nur fuer den Vorwaerts-Gang: die Fuehrung durchs Projekt hat keinen
     * Subgraphen, in dem ein Schritt liegen koennte. Ein Dateischritt hat kein
     * Symbol und liefert deshalb nichts; das Bild sagt dann, dass nichts von
     * diesem Walk im Fokus steht, statt auf den naechstbesten Punkt zu zeigen.
     */
    const walkStep = tour?.kind === 'entry' ? tour.document.steps[tourStep]?.primary : undefined;
    const walkStepQualifiedName =
        walkStep !== undefined && walkStep.kind === 'symbol' ? walkStep.qualifiedName : undefined;

    const liveIr = matchingInspectorIr(twinIr, readerFocusSymbol, project, activePath);
    const liveOutline = useMemo(() => liveIr ? buildPseudocode(
        { kind: 'symbol', label: liveIr.symbol.name },
        { irs: [liveIr], ...(layout === undefined ? {} : { graph: layout }) },
    ) : undefined, [liveIr, layout]);
    const liveSelection = readerSelection?.path === activePath && document?.path === activePath
        ? readerSelection : undefined;
    const currentReaderContext = useMemo(() => readerChatContext({
        project, path: activePath, status: readerStatus, document, origin: documentOrigin, selection: liveSelection,
    }), [project, activePath, readerStatus, document, documentOrigin, liveSelection]);
    const symbolList = fileSymbols.project === project && fileSymbols.path === activePath ? fileSymbols : undefined;
    const liveCode: SelectedCodeSnapshot = {
        project, filePath: activePath, symbol: readerFocusSymbol, ir: liveIr,
        selection: liveSelection, document: document?.path === activePath ? document : undefined,
        imports: activePath ? imports : undefined,
        pseudocode: liveOutline,
        status: liveIr ? 'ready' : readerStatus === 'loading' ? 'loading'
            : twinStatus === 'failed' ? 'failed' : twinStatus === 'not-indexed' ? 'not-indexed'
                : readerFocusSymbol ? 'loading' : 'empty',
        message: twinHint || twinMessage,
        coverageNote: coverageNote?.text,
        fileSymbols: symbolList?.symbols,
        fileSymbolsStatus: symbolList?.status ?? (activePath ? 'loading' : 'ready'),
        fileSymbolsMessage: symbolList?.message,
    };
    const inspector = pinnedCode?.project === project ? pinnedCode : liveCode;
    const evidenceGraph = repositoryReading.snapshot;
    const inspectorNode = evidenceGraph?.nodes.find(node => inspector.symbol?.qualifiedName
        ? node.qualified_name === inspector.symbol.qualifiedName
        : node.file_path === inspector.filePath && (node.label === 'File' || node.label === 'Module'));
    const exploreEvidence = ({ filePath, line, name }: SourceEvidenceTarget): void => {
        setSourceEvidence(undefined);
        changeWorkspace('explore');
        setPinnedCode(undefined);
        const target = twinTargetOf({ filePath, startLine: line, name: name ?? filePath, kind: 'unknown' });
        if (target) followTarget(target);
    };
    const navigateEvidence = (filePath: string, line?: number, name?: string): void => {
        setSourceEvidence({ project, target: { filePath, line, name } });
    };
    const readMapSource = useCallback(async (path: string, startLine = 1, maxLines = 65) => {
        const qualifiedName = fileQualifiedName(repositoryReading.snapshot, path);
        if (!qualifiedName) throw new Error(workspaceText.sourceOutsideSnapshot);
        return client.getCodeSnippet(project, qualifiedName, { startLine, maxLines });
    }, [client, project, repositoryReading.snapshot]);
    const clearGraphSelection = () => {
        setGalaxySelection(undefined);
        setGalaxySelectionProject('');
        setChatGraphSelection(undefined);
        setProactiveSelection(undefined);
    };
    const readerImpactTarget = activePath ? { filePath: activePath,
        qualifiedName: markedGraphRange ? readerFocusSymbol?.qualifiedName : undefined,
        name: markedGraphRange ? readerFocusSymbol?.name : undefined } : undefined;
    const selectMapNode = (node: GraphNode): void => {
        setGalaxySelection(node);
        setGalaxySelectionProject(project);
    };
    const mapSelectionPanel = selectionUnavailable ? <p role="status" className="repo-map-note">{selectionUnavailableText}</p> : activeGalaxySelection && (workspace === 'architecture' || workspace === 'galaxy') && <>
        <SelectionContextPanel graph={evidenceGraph} selected={activeGalaxySelection}
            path={activeGalaxySelection.file_path ?? ''} agents={experimentalAgentsEnabled ? agents.state : undefined} onNavigate={navigateEvidence} />
    </>;
    /*
     * Galaxy reads its selection from the loaded scope (hand test K13). The
     * repository snapshot is capped at 20,000 nodes by file path; a symbol in
     * the scope but behind that cap is still a valid selection here.
     */
    const galaxySelectionPanel = (scope: SelectionScope | undefined) => {
        const raw = galaxySelectionProject === project ? galaxySelection : undefined;
        const inScope = raw && scope?.graph.nodes.some(node => raw.qualified_name
            ? node.qualified_name === raw.qualified_name && node.file_path === raw.file_path : node.id === raw.id);
        const selected = inScope ? raw : activeGalaxySelection;
        if (!selected) return selectionUnavailable ? <p role="status" className="repo-map-note">{selectionUnavailableText}</p> : undefined;
        return <SelectionContextPanel graph={evidenceGraph} selected={selected} scope={scope}
            path={selected.file_path ?? ''} agents={experimentalAgentsEnabled ? agents.state : undefined} onNavigate={navigateEvidence} />;
    };
    const followInspectorTarget = (target: SymbolRef): void => {
        setPinnedCode(undefined);
        followTarget(target);
    };
    const askInspector = (): void => {
        if (!inspector.filePath) return;
        setChatAttachment(workspace !== 'explore' && inspector.selection ? { ...inspector.selection, project: inspector.project, id: crypto.randomUUID() } : undefined);
        // Explorer supplies its current source separately, once per request.
        setChatGraphSelection(inspectorChatContext(workspace === 'explore' ? { ...inspector, document: undefined } : inspector, crypto.randomUUID()));
        setBrowserAiOpen(true);
    };
    const showInspectorGraph = (): void => {
        const node = layout?.nodes.find(entry => inspector.symbol?.qualifiedName
            ? entry.qualified_name === inspector.symbol.qualifiedName
            : entry.file_path === inspector.filePath && (entry.label === 'File' || entry.label === 'Module'));
        if (node) {
            setGalaxySelection(node);
            setGalaxySelectionProject(project);
            changeWorkspace('galaxy');
        } else {
            setGalaxyOn(true);
            if (inspector.symbol) followTarget(inspector.symbol);
            else if (inspector.filePath) openFile(inspector.filePath);
        }
    };
    const selectedCode = <SelectedCodePanel {...inspector}
        selectionContext={<SelectionContextPanel graph={evidenceGraph}
            selected={inspector.symbol ? inspectorNode : undefined} path={inspector.filePath}
            agents={experimentalAgentsEnabled ? agents.state : undefined} onNavigate={navigateEvidence} />}
        pinned={pinnedCode?.project === project}
        onTogglePin={() => setPinnedCode(current => current?.project === project ? undefined : { ...liveCode,
            selection: liveCode.selection ? { ...liveCode.selection } : undefined })}
        onAsk={askInspector} onShowGraph={showInspectorGraph} onFollow={followInspectorTarget}
        onPointRow={inspector.filePath === activePath ? pointRow : undefined}
        onOpenFlow={inspector.symbol && inspector.symbol.qualifiedName === twinSymbol?.qualifiedName ? toggleFlow : undefined}
        callOutline={inspector.pseudocode && inspector.symbol ? <PseudocodeView document={inspector.pseudocode}
            symbolName={inspector.symbol.name} imports={inspector.imports} onOpenLine={openLine} /> : undefined} />;

    const galaxy = (
        <GalaxyPanel
            project={project}
            onClearSelection={clearGraphSelection}
            onSelectionEvidence={workspace === 'galaxy' ? onSelectionEvidence : undefined}
            selectionPanel={workspace === 'galaxy' ? galaxySelectionPanel : undefined}
            visible={workspace === 'galaxy' || (workspace === 'explore' && galaxyOn)}
            workspaceExpanded={workspace === 'galaxy'}
            focusQualifiedName={workspace === 'galaxy' ? activeGalaxySelection?.qualified_name : markedGraphRange ? readerFocusSymbol?.qualifiedName : undefined}
            focusName={workspace === 'galaxy' ? activeGalaxySelection?.name : markedGraphRange ? readerFocusSymbol?.name : undefined}
            focusFilePath={workspace === 'explore' ? activePath : undefined}
            focusSourceRange={workspace === 'explore' ? markedGraphRange : undefined}
            selectedNode={activeGalaxySelection}
            onOpenNode={openGalaxyNode}
            onSelectNode={workspace === 'galaxy' ? (node) => {
                setGalaxySelection(node);
                setGalaxySelectionProject(project);
            } : undefined}
            onSelectShadowNode={(node) => {
                setGalaxySelection(undefined);
                onSelectionEvidence(selectionEvidenceContext({ project, view: 'galaxy-coverage', source: '/api/layout missed_graph',
                    label: messages.galaxy.coverageSelection(node.name), selected: { id: node.sourceId, name: node.name, path: node.file_path, kind: node.label },
                    limitations: 'Coverage metadata only, not a code symbol. Detailed reasons, source ranges, relationships and freshness are unavailable.' }));
            }}
            onLayout={onLayout}
            walk={workspace === 'galaxy' ? undefined : walk}
            focusWalk={focusWalk}
            focusWalkStatus={focusHierarchy.status}
            focusWalkMessage={focusHierarchy.message}
            refit={graphRefit}
            stepQualifiedName={walkStepQualifiedName}
            onToggleVisible={() => setGalaxyOn((current) => !current)}
            display={display}
            {...(experimentalAgentsEnabled ? {
                agents,
                agentLayer: display.agents,
                agentEffects: {
                    tails: display.agentTails,
                    trails: display.agentTrails,
                    waves: display.agentWaves,
                    timeline: display.agentTimeline,
                },
                fullscreenToggle,
            } : {})}
            /*
             * Der Vollbildmodus nimmt Escape nur, wenn sonst niemand sie
             * braucht. Dieselbe Reihenfolge wie ueberall in dieser Datei: was
             * ueber dem Panel liegt, hat den Vortritt.
             */
            escapeTaken={helpOpen || entryOpen || overlayOpen || settingsOpen || projectsOpen}
        />
    );

    /*
     * Die fuenf Reiter des Erklaeren-Bereichs, und was gerade dahinter liegt.
     *
     * Die Liste entsteht aus Tatsachen und nicht aus Schaltern
     * (src/layout/explain-tabs.ts): ein Reiter ist bedienbar, WEIL etwas
     * dahinterliegt, und nicht, weil ihn jemand aufgeschlagen hat.
     */
    const explainTabList = explainTabs({
        hasProject: project.length > 0,
        flowSubject: twinSymbol === undefined ? '' : twinName,
        flowStep,
        walkRunning: tour !== undefined,
        walkStep: tourStep,
        walkSteps: tour?.document.steps.length ?? 0,
        chatTurns: chatTurns.length,
    }).filter(tab => tab.id !== 'change');
    explainTabsRef.current = explainTabList;

    /*
     * Der Inhalt des aktiven Reiters, und NUR er.
     *
     * Fuenf Flaechen gleichzeitig im Baum zu halten und vier davon
     * wegzublenden waere die bequeme Loesung: kein Zustand ginge verloren, und
     * niemand muesste darueber nachdenken, wo er liegt. Genau darum ist es die
     * falsche: der Zustand laege dann in fuenf Komponenten, das Wegblenden
     * waere eine CSS-Regel, an der man sich vertun kann, und die Zusicherung
     * "immer nur eine Flaeche" waere eine Behauptung ueber eine Regel statt
     * eine Eigenschaft der Form. Der Zustand liegt oben in dieser Datei; ein
     * Reiterwechsel haengt nur die Darstellung aus.
     */
    const explainPanel =
        explainTab === 'flow' ? (
            <FlowOverlay
                symbolName={twinName}
                flow={flowView}
                message={flowMessage}
                step={flowStep}
                onStep={stepFlow}
                onOpenLine={openLine}
                aiAvailable={llmState === 'ready'}
                modelName={selectedModelName}
                requestModel={requestModel}
            />
        ) : explainTab === 'walk' && tour !== undefined ? (
            <TourCard
                title={tour.document.title}
                steps={tour.document.steps}
                index={tourStep}
                endNote={tour.endNote}
                onPrev={() => setTourStep(stepMove(tour.document.steps.length, tourStep, -1))}
                onNext={() =>
                    isLastStep(tourStep, tour.document.steps.length)
                        ? closeTour()
                        : setTourStep(stepMove(tour.document.steps.length, tourStep, 1))
                }
                onExit={closeTour}
                /*
                 * Das Bild zum Schritt. Der Kasten steht schon auf dem Symbol
                 * dieses Schrittes: die Fuehrung setzt bei jedem Schritt das
                 * Subjekt des Twins (der Effekt mit `followRef` weiter oben),
                 * und der Flow haengt am Subjekt. Aufzuschlagen ist also genau
                 * dieser Reiter, und ein zweiter Weg, dasselbe Symbol noch
                 * einmal zu setzen, waere ein zweiter Weg, an dem es abweichen
                 * kann. Die Fuehrung laeuft dabei weiter: sie hat ihren Reiter
                 * und ihren Schritt, und beide stehen noch, wenn der Leser
                 * zurueckwechselt.
                 */
                onDiagram={() => openExplain('flow')}
            />
        ) : explainTab === 'chat' && chatTurns.length > 0 ? (
            <AtlasChatPanel
                turns={chatTurns}
                depth={chatDepth}
                onDepth={setChatDepth}
                onOpenCard={openCardSource}
                /*
                 * Loeschen leert den Verlauf. Zuklappen tut es nicht, und das
                 * ist seit W7c der ganze Unterschied zwischen den beiden; seit
                 * W8 gehoert das Zuklappen der Zone, und der Knopf hier ist der
                 * einzige, der loescht.
                 */
                onClear={() => setChatTurns([])}
                onPickCandidate={pickCandidate}
                /*
                 * Das Angebot aus AC6b: dieselbe Frage noch einmal, mit der
                 * Tiefe, die jetzt eingestellt ist. `askQuestion` liest
                 * `chatDepth` selbst, also braucht der Aufruf keine Zahl; und
                 * er legt einen NEUEN Zug an, waehrend der alte mit seiner
                 * alten Tiefe stehenbleibt. Genau darum geht es: zwei Antworten
                 * nebeneinander, von denen jede sagt, womit sie gerechnet
                 * wurde, statt einer, die sich unter der Hand aendert und ihre
                 * Zitate dabei entwertet.
                 */
                onAskAgain={(turn) => askQuestion(turn.question)}
                aiAvailable={llmState === 'ready'}
                modelName={selectedModelName}
                requestModel={requestModel}
            />
        ) : explainTab === 'bug' && project.length > 0 ? (
            <BugWizard
                project={project}
                target={bugTarget}
                paths={bugPathsDto}
                status={bugStatus}
                message={bugMessage}
                onHop={openHop}
                onChangeTarget={() => {
                    // Derselbe Weg wie jede andere Suche dieser Oberflaeche.
                    // Der Assistent bleibt offen und uebernimmt das neue
                    // Subjekt, sobald der Twin es hat.
                    window.dispatchEvent(new Event(OPEN_COMMAND_SEARCH_EVENT));
                }}
                onClose={collapseExplain}
            />
        ) : undefined;

    /** Ein Griff, mit seinen Grenzen aus dem Modell. */
    const splitter = (
        key: LayoutKey,
        testId: string,
        orientation: 'vertical' | 'horizontal',
        label: string,
        invert = false,
    ): JSX.Element => {
        const bounds = layoutBounds(key, frame);
        return (
            <Splitter
                testId={testId}
                orientation={orientation}
                label={label}
                value={key === 'rightWidth' ? Math.max(360, shownZones[key]) : shownZones[key]}
                min={key === 'rightWidth' ? Math.max(360, bounds.min) : bounds.min}
                max={key === 'rightWidth' ? Math.max(360, bounds.max) : bounds.max}
                invert={invert}
                onChange={(value) => changeZone(key, value)}
                onReset={() => resetZone(key)}
            />
        );
    };

    const attachSelection = (selection: ReaderSelection): void => {
        if (selection.path !== activePath || document?.path !== activePath) return;
        const range = { startLine: selection.startLine, endLine: selection.endLine
            - (selection.endColumn === 1 && selection.endLine > selection.startLine ? 1 : 0) };
        const symbol = symbolMatchesReader(liveCode.symbol, selection.path, range) ? liveCode.symbol : undefined;
        setReaderSelection(selection);
        setChatAttachment(undefined);
        setChatGraphSelection(inspectorChatContext({ ...liveCode, symbol,
            ir: matchingInspectorIr(liveCode.ir, symbol, project, activePath), selection }, crypto.randomUUID()));
        setBrowserAiOpen(true);
    };
    // The chat grounds explanations in the selected symbol's source, read like "Read source evidence" (K14).
    const readSymbolSource = useCallback((qualifiedName: string, window: { maxLines: number }) =>
        client.getCodeSnippet(project, qualifiedName, window), [client, project]);
    const clearAttachment = (id: string): void => {
        setChatAttachment(current => current?.id === id ? undefined : current);
    };
    const clearChatGraphSelection = (id: string): void => {
        setChatGraphSelection(current => current?.id === id ? undefined : current);
    };

    return (
        <AtlasChrome
            workspace={workspace}
            projectSwitcher={<ProjectSwitcher currentProject={project} listProjects={projectsSource.listProjects}
                onSelectProject={openProject} onAddProject={() => setProjectsOpen(true)} indexActivity={indexActivity} />}
            onWorkspaceChange={value => { setDiagnosticsPath(undefined); changeWorkspace(value); }}
            onOpenBrowserAi={openAgentSettings}
            onToggleBrowserAi={() => setBrowserAiOpen(open => !open)}
            agentState={localAgentState} agentModelName={agentModelName}
            onOpenSystem={() => changeWorkspace('system')}
            daemonState={serverOk === undefined ? 'checking' : serverOk ? 'connected' : 'disconnected'}
            chatOpen={browserAiOpen}
            chatDock={<BrowserChatDock open={browserAiOpen} onClose={() => setBrowserAiOpen(false)}
                historyKey={project ? browserChatHistoryProjectKey(window.location.origin, project) : undefined}
                proactiveSelection={proactiveSelection?.scope === selectionScope ? proactiveSelection.context : undefined}
                selectionScope={selectionScope} onAgentStateChange={onAgentStateChange} onAgentModelChange={setAgentModelName} settingsRequest={agentSettingsRequest}
                readerContext={workspace === 'explore' ? currentReaderContext : undefined}
                pendingContext={chatGraphSelection} onContextConsumed={clearChatGraphSelection} onContextRemoved={clearChatGraphSelection}
                context={browserGraphContext(inspector.ir, project, inspector.filePath, inspector.symbol ? workspacePathOf(inspector.symbol.uri) : '')}
                attachment={chatAttachment} onAttachmentConsumed={clearAttachment} onAttachmentRemoved={clearAttachment} readSource={readSymbolSource} />}
            readerActions={<>
                <button type="button" disabled={!liveSelection} aria-keyshortcuts="Control+Shift+L Meta+Shift+L"
                    onClick={() => { if (liveSelection) attachSelection(liveSelection); }}>{workspaceText.askSelection}</button>
                <button type="button" aria-expanded={codeDetailsOpen} onClick={() => setCodeDetailsOpen(open => !open)}>{workspaceText.codeDetails}</button>
            </>}
            readerSummary={workspace === 'explore' && activePath ? <FileImpactSummary
                project={project} target={readerImpactTarget}
                onOpen={target => exploreEvidence({ filePath: target.filePath, line: target.line, name: target.name })} /> : undefined}
            readerDetails={codeDetailsOpen ? selectedCode : undefined}
            globalOverlay={<>
                {sourceEvidence?.project === project && <SourceEvidenceDrawer key={`${project}:${sourceEvidence.target.filePath}:${sourceEvidence.target.line ?? 1}`}
                    project={project} target={sourceEvidence.target} graph={evidenceGraph} client={client}
                    onClose={() => setSourceEvidence(undefined)} onExplore={exploreEvidence} />}
                {welcomeOpen && <WelcomePanel workspace={workspace}
                onWorkspace={changeWorkspace} onContinue={finishSetup}
                onLocalAi={() => { finishSetup(); setBrowserAiOpen(true); }} />}
                <AddProjectIndexDialog open={projectsOpen} source={projectsSource} onActivityChange={setIndexActivity}
                    onOpenProject={openProject} onClose={() => setProjectsOpen(false)} />
                {helpOpen && <HelpOverlay onClose={() => setHelpOpen(false)} />}
                {settingsOpen && <SettingsPanel project={project} state={llmState} facts={llmFacts}
                    onOpenBrowserModels={() => { setSettingsOpen(false); openAgentSettings(); }}
                    router={llmRouter} models={llmModels} selectedModel={selectedModel}
                    onSelectModel={chooseModel}
                    display={display} onDisplay={changeDisplay}
                    onMeasurement={(measurement) => setMeasurements((current) => ({
                        ...current, [measurement.setting]: measurement,
                    }))}
                    onClose={() => setSettingsOpen(false)} />}
            </>}
            guidance={guidance}
            workspacePanel={<>
                <div hidden={workspace !== 'architecture'}>
                <ArchitecturePanel projectName={project} overview={overview} active={workspace === 'architecture'}
                    escapeTaken={helpOpen || entryOpen || overlayOpen || settingsOpen || projectsOpen}
                    onClearSelection={clearGraphSelection}
                    onSelectionEvidence={onSelectionEvidence}
                    coverage={coverageAsked && coverageMeta.generation === repositoryReading.snapshot?.generation ? coverage : undefined}
                    readSource={readMapSource}
                    graph={repositoryReading.snapshot} graphGeneration={repositoryReading.snapshot?.generation} selection={activeGalaxySelection} selectionPanel={mapSelectionPanel}
                    graphNote={repositoryReading.error ?? (repositoryReading.snapshot
                        ? `Index: ${repositoryReading.snapshot.indexedAt || 'timestamp unknown'} · snapshot ${repositoryReading.snapshot.generation}. ${repositoryReading.snapshot.nodesTruncated || repositoryReading.snapshot.edgesTruncated ? 'The architecture query reached a bound; some evidence is omitted.' : 'All matching source symbols and dependency edges in this index snapshot were read.'}${selectionUnavailable ? ` ${selectionUnavailableText}` : ''}`
                        : undefined)}
                    onSelect={selectMapNode}
                    loading={overviewLoading} error={overviewError}
                    onRefresh={() => setOverviewRevision((value) => value + 1)}
                    onNavigate={navigateEvidence} />
                </div>
                {experimentalAgentsEnabled && <div hidden={workspace !== 'agents'}>
                <ActivityPanel project={project} api={api} state={agents.state} status={agents.status} on={liveAgentsOn} port={bridgePort}
                    graph={evidenceGraph} onToggle={() => setLiveAgentsOn((value) => !value)}
                    onOpenNode={(node) => { setWorkspace('explore'); openGalaxyNode(node); }} />
                </div>}
                <div className="atlas-adr-host" hidden={workspace !== 'adr'}>
                    <AdrWorkspace key={project} project={project} source={projectsSource} active={workspace === 'adr'} />
                </div>
                <div hidden={workspace !== 'system'}>
                    <SystemWorkspace api={api} listProjects={projectsSource.listProjects} project={project} active={workspace === 'system'} version={ATLAS_VERSION}
                        configuration={active => <ConfigPanel embedded active={active} service={api} project={project} display={display} onDisplay={changeDisplay}
                            onOpenBrowserModels={openAgentSettings} onOpenDisplay={() => setSettingsOpen(true)} onClose={() => {}} />}
                        onOpenProjects={() => setProjectsOpen(true)} />
                </div>
                <div hidden={workspace !== 'coverage'}>
                    <DiagnosticsPanel project={project} client={client} coverage={coverageAsked ? coverage : undefined}
                        coverageError={coverageError} active={workspace === 'coverage'} path={diagnosticsPath}
                        indexDetails={<AtlasTreeIndexDetails rows={rows} note={treeNoteParts.join('; ')}
                            noteIsAbsence={treeError.length > 0 || coverageError.length > 0 || !project} truncations={coverage.truncations} />}
                        onNavigate={path => { changeWorkspace('explore'); navigateEvidence(path); }}
                        onCoverage={reading => { setCoverage(reading.index); setCoverageMeta({ ...reading.answer.metadata }); setCoverageAsked(true); setCoverageError(''); setOverviewRevision(value => value + 1); }} />
                </div>
            </>}
            version={ATLAS_VERSION}
            buildSuffix={ATLAS_BUILD_SUFFIX}
            chips={chips}
            tabs={tabDescriptors}
            onSelectTab={openFile}
            onCloseTab={closeTab}
            tree={{
                explained: false,
                projectName: project.length > 0 ? project : messages.app.noProject,
                rows,
                cursor,
                activePath,
                note: treeNoteParts.join('; '),
                noteIsAbsence: treeError.length > 0 || coverageError.length > 0 || project.length === 0,
                truncations: coverage.truncations,
                onCursorChange: setCursor,
                onOpen: (row) => openFile(row.path),
                onToggle: toggleDirectory,
                onKeyDown: onTreeKeyDown,
            }}
            breadcrumb={activePath.length > 0 ? pathSegments(activePath) : []}
            truncationNote={document?.truncationNote ?? ''}
            coverageNote={coverageNote}
            commandValue={command}
            onCommandChange={setCommand}
            onCommandKeyDown={onCommandKeyDown}
            commandInputRef={commandInputRef}
            commandOverlay={commandOverlay}
            commandPlaceholder={workspaceText.searchPlaceholder}
            commandExamples={commandExamples}
            /*
             * Ein Beispiel wird in die Zeile GESCHRIEBEN und nicht
             * abgeschickt: der Leser soll den Namen darin gegen seinen
             * eigenen tauschen koennen, bevor er drueckt. Der Fokus geht
             * dabei zurueck ins Feld, weil er sonst auf einem Knopf staende,
             * der im selben Moment verschwindet.
             */
            onCommandExample={(text) => {
                setCommand(text);
                window.dispatchEvent(new Event(OPEN_COMMAND_SEARCH_EVENT));
            }}
            commandHint={
                enterIntent === 'ask'
                    ? llmState === 'ready' ? CHAT_HINT_READY : CHAT_HINT_OFF
                    : overlayOpen ? COMMAND_HINT_OPEN : COMMAND_HINT_IDLE
            }
            menus={menus}
            status={status}
            galaxy={galaxy}
            zones={{
                leftWidth: shownZones.leftWidth,
                rightWidth: shownZones.rightWidth,
                twinHeight: shownZones.twinHeight,
            }}
            splitLeft={splitter('leftWidth', 'atlas-split-left', 'vertical', messages.layout.splitter.left)}
            splitExplain={splitter(
                'explainHeight',
                'atlas-split-explain',
                'horizontal',
                messages.layout.splitter.explain,
                // Nach oben ziehen macht den Bereich groesser: die Kante folgt
                // dem Zeiger, statt vor ihm wegzulaufen.
                true,
            )}
            splitRight={splitter(
                'rightWidth',
                'atlas-split-right',
                'vertical',
                messages.layout.splitter.right,
                true,
            )}
            splitTwin={galaxyOn
                ? splitter('twinHeight', 'atlas-split-twin', 'horizontal', messages.layout.splitter.twin)
                : undefined}
            explain={explainOpen ? (
                <ExplainZone
                    tabs={explainTabList}
                    active={explainTab}
                    onSelect={(id) => {
                        setExplainTab(id);
                        setExplainOpen(true);
                    }}
                    open={explainOpen}
                    onToggle={() => setExplainOpen((open) => !open)}
                    height={shownZones.explainHeight}
                >
                    {explainPanel}
                </ExplainZone>
            ) : undefined}
        >
            {/*
              * Die Frage und der Einstiegsdialog liegen UEBER dem Editor statt
              * an seiner Stelle, aus demselben Grund wie der Platzhalter des
              * Readers: ein Editor, der nur manchmal im Layout haengt, misst
              * sich beim Auftauchen auf null und zeichnet nichts, bis ihn etwas
              * anstoesst.
              */}
            {whyVisible && (
                <WhyPanel project={project} onChoose={chooseIntent} onDecline={declineWhy} />
            )}
            {/*
              * Der Einstiegsdialog liegt aus demselben Grund ueber dem Editor
              * wie die Frage: eine Flaeche, die nur manchmal im Layout haengt,
              * misst sich beim Auftauchen auf null.
              *
              * Der Assistent und die Aenderungsansicht standen bis W8 hier
              * daneben. Sie sind seit W8 Reiter des Erklaeren-Bereichs: sie
              * ERKLAEREN den gelesenen Code, also gehoeren sie an den Platz, an
              * dem erklaert wird, und nicht vor den Text, den sie erklaeren.
              */}
            {entryOpen && (
                <EntryPointDialog
                    headline={entryHeadline(offered.total, offered.rows.length)}
                    rows={offered.rows}
                    query={entryQuery}
                    onQueryChange={setEntryQuery}
                    hits={entryHitRows}
                    status={entryStatus}
                    message={entryMessage}
                    routeNote={routeNote(overview)}
                    onChooseFlagged={chooseFlagged}
                    onChooseHit={chooseEntryHit}
                    onClose={() => setEntryOpen(false)}
                />
            )}
            <MonacoReader
                status={readerStatus}
                document={document}
                message={readerMessage}
                badges={badges}
                pulseLine={caretLine}
                highlightLine={pointedLine}
                onCursorLine={setCaretLine}
                onSelectionChange={setReaderSelection}
                onAskSelection={attachSelection}
                revealLine={reveal?.line}
                revealNonce={reveal?.nonce}
            />
        </AtlasChrome>
    );
}