@schlenkr/ragents 0.1.0

package/apps/web/src/settings-contributions.ts

@@ -0,0 +1,274 @@
+import type {
+  SettingsAgentExtension,
+  SettingsConfigurationDescriptor,
+  SettingsPromptContribution,
+  SettingsResponse,
+  SettingsSkill,
+  SettingsTool,
+} from "./api";
+import type { SettingsContribution, StartEntry, WebPlugin } from "./PluginRegistry";
+
+export const settingsForCategory = <T extends SettingsContribution>(
+  contributions: readonly T[],
+  category: NonNullable<SettingsContribution["category"]>,
+  can: (right: string) => boolean,
+): readonly T[] => contributions.filter((entry) => entry.category === category && (!entry.readRight || can(entry.readRight)));
+
+export type ContributionKind =
+  | "tools"
+  | "prompts"
+  | "startEntries"
+  | "skills"
+  | "extensions"
+  | "configuration"
+  | "web";
+
+export type ContributionFilter = "all" | ContributionKind;
+
+export interface ContributionFilterOption {
+  id: ContributionFilter;
+  label: string;
+}
+
+export const contributionFilters: readonly ContributionFilterOption[] = [
+  { id: "all", label: "Alle" },
+  { id: "tools", label: "Funktionen" },
+  { id: "prompts", label: "Prompts" },
+  { id: "startEntries", label: "Einstiege" },
+  { id: "skills", label: "Skills" },
+  { id: "extensions", label: "Erweiterungen" },
+  { id: "configuration", label: "Konfiguration" },
+  { id: "web", label: "Web" },
+];
+
+export interface WebContribution {
+  kind: string;
+  details: readonly string[];
+  count: number;
+}
+
+export type PluginWebModule =
+  | { state: "hidden" }
+  | { state: "none" }
+  | { state: "withoutContributions" }
+  | { state: "contributions"; contributions: readonly WebContribution[] };
+
+export interface PluginGroup {
+  id: string;
+  requires: readonly string[];
+  serverRegistered: boolean;
+  webActive: boolean;
+  tools: readonly SettingsTool[];
+  prompts: readonly SettingsPromptContribution[];
+  startEntries: readonly StartEntry[];
+  skills: readonly SettingsSkill[];
+  extensions: readonly SettingsAgentExtension[];
+  configuration: readonly SettingsConfigurationDescriptor[];
+  settings: readonly (SettingsContribution & { owner: string })[];
+  clientConfig: Readonly<Record<string, unknown>> | undefined;
+  web: PluginWebModule;
+}
+
+export interface ContributionSource {
+  plugins: readonly WebPlugin[];
+  activePlugins: readonly { id: string }[];
+  startEntries: readonly StartEntry[];
+  settings?: PluginGroup["settings"];
+}
+
+export const toolKindLabel = (kind: SettingsTool["kind"]): string => {
+  if (kind === "agent-builtin") return "Agent Builtin";
+  if (kind === "agent-extension") return "Agent-Extension";
+  if (kind === "ragents") return "RAgents";
+  return "Plugin";
+};
+
+export const toolScopeLabel = (scope: SettingsTool["scope"]): string => {
+  if (scope === "global") return "Laufzeitweit";
+  if (scope === "per-agent") return "Je Agent";
+  return "Je Turn";
+};
+
+export const toolAvailabilityLabel = (availability: SettingsTool["availability"]): string =>
+  availability === "always" ? "Grundsätzlich verfügbar" : "Bedingt verfügbar";
+
+export const functionSurfaceLabel = (nativeTool: SettingsTool["nativeTool"]): string =>
+  nativeTool === true ? "LLM-Werkzeug" : "TypeScript-Funktion";
+
+export const skillAudienceLabel = (audience: SettingsSkill["audiences"][number]): string =>
+  audience === "coordinator" ? "Koordinator" : "Agenten";
+
+export const groupContributions = (
+  settings: SettingsResponse,
+  source: ContributionSource,
+): readonly PluginGroup[] => {
+  const activeIds = new Set(source.activePlugins.map((plugin) => plugin.id));
+  const webPlugins = new Map(source.plugins.map((plugin) => [plugin.id, plugin]));
+  const serverPlugins = new Map(settings.plugins.map((plugin) => [plugin.id, plugin]));
+  const extensions = settings.agentExtensions.filter((extension) => extension.kind === "plugin");
+  const editableSettings = (source.settings ?? []).filter((contribution) => activeIds.has(contribution.owner));
+  const owners = [
+    ...settings.plugins.map((plugin) => plugin.id),
+    ...ownersOf(settings.tools),
+    ...ownersOf(settings.promptContributions),
+    ...ownersOf(source.startEntries),
+    ...ownersOf(settings.skills),
+    ...ownersOf(extensions),
+    ...activeIds,
+  ];
+  const ordered = [...new Set(owners)];
+  return ordered.map((id) => {
+    const plugin = serverPlugins.get(id);
+    const web = webPlugins.get(id);
+    return {
+      id,
+      requires: plugin?.requires ?? [],
+      serverRegistered: plugin !== undefined,
+      webActive: activeIds.has(id),
+      tools: settings.tools.filter((tool) => tool.owner === id),
+      prompts: settings.promptContributions.filter((contribution) => contribution.owner === id),
+      startEntries: source.startEntries.filter((entry) => entry.owner === id),
+      skills: settings.skills.filter((skill) => skill.owner === id),
+      extensions: extensions.filter((extension) => extension.owner === id),
+      configuration: plugin?.configuration ?? [],
+      settings: editableSettings.filter((contribution) => contribution.owner === id),
+      clientConfig: plugin?.clientConfig,
+      web: webModuleOf(web),
+    };
+  });
+};
+
+export const filterGroup = (
+  group: PluginGroup,
+  filter: ContributionFilter,
+  searchText: string,
+): PluginGroup => {
+  const needle = searchText.trim().toLocaleLowerCase("de-DE");
+  const kept = (kind: ContributionKind) => filter === "all" || filter === kind;
+  const matches = (haystack: readonly (string | undefined)[]) =>
+    needle === "" || haystack.filter((part): part is string => part !== undefined)
+      .join(" ").toLocaleLowerCase("de-DE").includes(needle);
+  const configuration = kept("configuration")
+    ? group.configuration.filter((entry) => matches([entry.key, entry.source]))
+    : [];
+  const clientConfig = kept("configuration")
+    && group.clientConfig !== undefined
+    && matches([group.id, "Client-Konfiguration", JSON.stringify(group.clientConfig)])
+    ? group.clientConfig
+    : undefined;
+  return {
+    ...group,
+    tools: kept("tools") ? group.tools.filter((tool) => matches(toolSearchParts(tool))) : [],
+    prompts: kept("prompts")
+      ? group.prompts.filter((contribution) => matches([contribution.id, contribution.owner]))
+      : [],
+    startEntries: kept("startEntries")
+      ? group.startEntries.filter((entry) => matches(entrySearchParts(entry)))
+      : [],
+    skills: kept("skills")
+      ? group.skills.filter((skill) => matches([skill.id, skill.owner, ...skill.paths]))
+      : [],
+    extensions: kept("extensions")
+      ? group.extensions.filter((extension) => matches([extension.id, extension.owner]))
+      : [],
+    configuration,
+    settings: kept("configuration")
+      ? group.settings.filter((contribution) => matches([contribution.id, contribution.label, contribution.owner]))
+      : [],
+    clientConfig,
+    web: kept("web") ? filterWebModule(group.web, needle) : { state: "hidden" },
+  };
+};
+
+export const countContributions = (group: PluginGroup): number =>
+  group.tools.length
+  + group.prompts.length
+  + group.startEntries.length
+  + group.skills.length
+  + group.extensions.length
+  + group.configuration.length
+  + group.settings.length
+  + (group.clientConfig === undefined ? 0 : 1)
+  + webCount(group.web);
+
+export const capabilityGroups = (
+  groups: readonly PluginGroup[],
+  kind: ContributionKind,
+  query: string,
+): readonly PluginGroup[] => groups
+  .map((group) => filterGroup(group, kind, query))
+  .filter((group) => countContributions(group) > 0);
+
+const webCount = (web: PluginWebModule): number =>
+  web.state === "contributions" ? web.contributions.length : 0;
+
+const filterWebModule = (web: PluginWebModule, needle: string): PluginWebModule => {
+  if (web.state !== "contributions") return needle === "" ? web : { state: "hidden" };
+  const contributions = web.contributions.filter((contribution) =>
+    [contribution.kind, ...contribution.details].join(" ").toLocaleLowerCase("de-DE").includes(needle));
+  return contributions.length === 0 && needle !== "" ? { state: "hidden" } : { state: "contributions", contributions };
+};
+
+const ownersOf = (items: readonly { owner: string }[]): readonly string[] => items.map((item) => item.owner);
+
+export const entryActionLabel = (entry: StartEntry): string =>
+  entry.action === "skill" ? "Skill" : "Run-Script";
+
+const entrySearchParts = (entry: StartEntry): readonly (string | undefined)[] => [
+  entry.id,
+  entry.title,
+  entry.description,
+  entry.guide,
+  entryActionLabel(entry),
+  entry.action === "skill" ? entry.category : undefined,
+  entry.action === "skill" ? entry.skill : undefined,
+];
+
+const webModuleOf = (plugin: WebPlugin | undefined): PluginWebModule => {
+  if (plugin === undefined) return { state: "none" };
+  const contributions = webContributionsOf(plugin);
+  return contributions.length === 0 ? { state: "withoutContributions" } : { state: "contributions", contributions };
+};
+
+const webContributionsOf = (plugin: WebPlugin): readonly WebContribution[] => [
+  listed("Arbeitsbereichs-Tabs", (plugin.workspaceTabs ?? []).map((tab) => `${tab.id} (${tab.label})`)),
+  flagged("Dynamische Arbeitsbereichs-Tabs", plugin.workspaceTabsFor !== undefined),
+  listed("Leitfäden", (plugin.guides ?? []).map((guide) => guide.id)),
+  flagged("Branding", plugin.brand !== undefined),
+  flagged("Canvas", plugin.canvas !== undefined),
+  counted("Canvas-Elemente", (plugin.canvasElements ?? []).length),
+  counted("Karten-Abschnitte", (plugin.cardSections ?? []).length),
+  counted("Werkzeug-Darstellungen", (plugin.toolPresenters ?? []).length),
+  counted("Entitäts-Darstellungen", (plugin.entityPresenters ?? []).length),
+  counted("Session-Kopfbeiträge", (plugin.sessionHeaders ?? []).length),
+  listed("Übersichtsbeiträge", (plugin.overviewPanels ?? []).map((panel) => panel.id)),
+  listed("Einstellungen", (plugin.settings ?? []).map((setting) => `${setting.id} (${setting.label})`)),
+  counted("Session-Metadaten", (plugin.sessionMetadata ?? []).length),
+  counted("Attention-Beiträge", (plugin.attention ?? []).length),
+  listed("Startoptionen", (plugin.startOptions ?? []).map((option) => option.id)),
+  flagged("Chat-Darstellung", plugin.chatDisplayPolicy !== undefined),
+  flagged("Rückfragen-Beantworter", plugin.questionResponder !== undefined),
+  flagged("Session-Provider", plugin.SessionProvider !== undefined),
+].filter((contribution): contribution is WebContribution => contribution !== undefined);
+
+const listed = (kind: string, details: readonly string[]): WebContribution | undefined =>
+  details.length === 0 ? undefined : { kind, details, count: details.length };
+
+const counted = (kind: string, count: number): WebContribution | undefined =>
+  count === 0 ? undefined : { kind, details: [], count };
+
+const flagged = (kind: string, present: boolean): WebContribution | undefined =>
+  present ? { kind, details: [], count: 1 } : undefined;
+
+const toolSearchParts = (tool: SettingsTool): readonly string[] => [
+  tool.id,
+  tool.name,
+  tool.description,
+  tool.owner,
+  tool.source,
+  toolKindLabel(tool.kind),
+  toolScopeLabel(tool.scope),
+  toolAvailabilityLabel(tool.availability),
+  functionSurfaceLabel(tool.nativeTool),
+  tool.availabilityDetail,
+];

package/apps/web/src/theme.ts

@@ -0,0 +1,135 @@
+import { useSyncExternalStore } from "react";
+import { subscribeStorageChanges } from "./lib/local-storage-setting";
+
+export const THEME_STORAGE_KEY = "ragents.theme";
+export type ThemePreference = "light" | "dark" | "system";
+export type ResolvedTheme = Exclude<ThemePreference, "system">;
+
+export const themeOptions = [
+  { value: "light", label: "Hell" },
+  { value: "dark", label: "Dunkel" },
+  { value: "system", label: "System" },
+] as const;
+
+interface ThemeSnapshot {
+  preference: ThemePreference;
+  appearance: ResolvedTheme;
+  error: string | null;
+}
+
+export function parseThemePreference(value: string | null): ThemePreference {
+  if (value === null) return "dark";
+  if (value === "light" || value === "dark" || value === "system") return value;
+  throw new Error(`Ungültige Darstellung in ${THEME_STORAGE_KEY}: ${JSON.stringify(value)}. Erlaubt sind light, dark und system.`);
+}
+
+const errorMessage = (cause: unknown) => cause instanceof Error ? cause.message : String(cause);
+
+export function createThemeStore(browser: Window) {
+  let storage: Storage;
+  let preference: ThemePreference;
+  try {
+    storage = browser.localStorage;
+    preference = parseThemePreference(storage.getItem(THEME_STORAGE_KEY));
+  } catch (cause) {
+    throw new Error(`Die gespeicherte Darstellung konnte nicht geladen werden. ${errorMessage(cause)}`);
+  }
+  const media = browser.matchMedia("(prefers-color-scheme: dark)");
+  const appearanceOf = (value: ThemePreference): ResolvedTheme => value === "system" ? media.matches ? "dark" : "light" : value;
+  let snapshot: ThemeSnapshot = { preference, appearance: appearanceOf(preference), error: null };
+  const listeners = new Set<() => void>();
+  let watchingSystem = false;
+  let disposed = false;
+
+  function notify() {
+    for (const listener of listeners) listener();
+  }
+
+  function systemChanged() {
+    if (snapshot.preference !== "system") return;
+    const appearance = appearanceOf("system");
+    if (appearance === snapshot.appearance) return;
+    snapshot = { ...snapshot, appearance };
+    browser.document.documentElement.dataset.theme = appearance;
+    notify();
+  }
+
+  function apply(next: ThemePreference) {
+    const watchSystem = next === "system";
+    if (watchSystem !== watchingSystem) {
+      if (watchSystem) media.addEventListener("change", systemChanged);
+      else media.removeEventListener("change", systemChanged);
+      watchingSystem = watchSystem;
+    }
+    const appearance = appearanceOf(next);
+    browser.document.documentElement.dataset.theme = appearance;
+    if (snapshot.preference === next && snapshot.appearance === appearance && snapshot.error === null) return;
+    snapshot = { preference: next, appearance, error: null };
+    notify();
+  }
+
+  function reportError(message: string) {
+    snapshot = { ...snapshot, error: message };
+    notify();
+  }
+
+  function storageChanged(event: StorageEvent) {
+    if (event.storageArea !== storage) return;
+    try {
+      apply(parseThemePreference(storage.getItem(THEME_STORAGE_KEY)));
+    } catch (cause) {
+      reportError(`Die Darstellung aus einem anderen Browser-Tab konnte nicht übernommen werden. ${errorMessage(cause)}`);
+    }
+  }
+
+  apply(preference);
+  const unsubscribeStorage = subscribeStorageChanges(browser, (key) => key === THEME_STORAGE_KEY, storageChanged);
+
+  return {
+    getSnapshot: () => snapshot,
+    subscribe(listener: () => void) {
+      if (disposed) throw new Error("Die Darstellung wurde bereits beendet.");
+      listeners.add(listener);
+      return () => { listeners.delete(listener); };
+    },
+    setPreference(next: ThemePreference) {
+      if (disposed) throw new Error("Die Darstellung wurde bereits beendet.");
+      try {
+        parseThemePreference(next);
+        storage.setItem(THEME_STORAGE_KEY, next);
+        apply(next);
+      } catch (cause) {
+        reportError(`Die Darstellung konnte nicht gespeichert werden. ${errorMessage(cause)}`);
+      }
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      unsubscribeStorage();
+      if (watchingSystem) media.removeEventListener("change", systemChanged);
+      listeners.clear();
+    },
+  };
+}
+
+let activeTheme: ReturnType<typeof createThemeStore> | undefined;
+
+export function initializeTheme(browser: Window) {
+  activeTheme?.dispose();
+  activeTheme = undefined;
+  activeTheme = createThemeStore(browser);
+  return activeTheme;
+}
+
+export function getThemeStore() {
+  if (!activeTheme) throw new Error("Die Darstellung wurde noch nicht initialisiert.");
+  return activeTheme;
+}
+
+export function getResolvedTheme(): ResolvedTheme {
+  return getThemeStore().getSnapshot().appearance;
+}
+
+export function useResolvedTheme(): ResolvedTheme {
+  return useSyncExternalStore(getThemeStore().subscribe, getResolvedTheme);
+}

package/apps/web/src/title-model-settings.ts

@@ -0,0 +1,51 @@
+import { coreContracts } from "@aicontainer/server/api/contracts";
+import type { TitleModelSelection, TitleModelSettings } from "../../server/src/title-settings-contract";
+import { isRecord } from "./lib/guards";
+import { rpc } from "./rpc";
+import type { RpcClient } from "./rpc/client";
+
+export const titleModelSettingsChangedEvent = "ragents-title-model-settings-changed";
+export const titleSelectionKey = (selection: TitleModelSelection | null): string =>
+  selection === null ? "null" : JSON.stringify([selection.provider, selection.model]);
+const text = (value: unknown): value is string => typeof value === "string" && value.trim().length > 0;
+
+export function titleModelSettingsFrom(value: unknown): TitleModelSettings {
+  if (!isRecord(value) || !Array.isArray(value.models)
+    || !value.models.every((model) => isRecord(model) && text(model.provider) && text(model.id) && text(model.label))
+    || (value.selection !== null && (!isRecord(value.selection) || !text(value.selection.provider) || !text(value.selection.model)))) {
+    throw new Error("Der Server hat ungültige Einstellungen für Überschriften geliefert.");
+  }
+  const settings = value as unknown as TitleModelSettings;
+  const keys = settings.models.map((model) => titleSelectionKey({ provider: model.provider, model: model.id }));
+  if (new Set(keys).size !== keys.length || (settings.selection !== null && !keys.includes(titleSelectionKey(settings.selection)))) {
+    throw new Error("Die Einstellungen für Überschriften passen nicht zum verfügbaren Modellkatalog.");
+  }
+  return settings;
+}
+
+export function titleSelectionFromKey(key: string, models: TitleModelSettings["models"]): TitleModelSelection | null {
+  if (key === "null") return null;
+  const model = models.find((entry) => titleSelectionKey({ provider: entry.provider, model: entry.id }) === key);
+  if (!model) throw new Error("Das ausgewählte Modell für Überschriften ist nicht verfügbar.");
+  return { provider: model.provider, model: model.id };
+}
+
+export function titleModelOptions(models: TitleModelSettings["models"], selection: TitleModelSelection | null, query: string) {
+  const search = query.trim().toLocaleLowerCase("de-DE");
+  return [
+    { value: "null", label: "Keine automatischen Überschriften" },
+    ...models.filter((model) => (model.provider === selection?.provider && model.id === selection.model)
+      || `${model.label} ${model.id}`.toLocaleLowerCase("de-DE").includes(search))
+      .map((model) => ({ value: titleSelectionKey({ provider: model.provider, model: model.id }), label: model.label })),
+  ];
+}
+
+export async function requestTitleModelSettings(options: {
+  selection?: TitleModelSelection | null; signal?: AbortSignal; client?: RpcClient;
+} = {}): Promise<TitleModelSettings> {
+  const client = options.client ?? rpc;
+  const settings = options.selection === undefined
+    ? await client.call(coreContracts.settings.titlesRead, {}, { signal: options.signal })
+    : await client.call(coreContracts.settings.titlesSave, { value: { selection: options.selection } }, { signal: options.signal });
+  return titleModelSettingsFrom(settings);
+}

package/apps/web/src/toolLine.ts

@@ -0,0 +1,67 @@
+import type { Message, ToolInfo } from "./chat/types";
+
+const SUMMARY_LIMIT = 140;
+
+const SUMMARY_KEYS = [
+  "path",
+  "file_path",
+  "filePath",
+  "command",
+  "cmd",
+  "pattern",
+  "query",
+  "url",
+  "handle",
+  "title",
+  "name",
+  "body",
+  "text",
+  "message",
+  "prompt",
+];
+
+const oneLine = (value: string) => {
+  const line = value.replace(/\s+/g, " ").trim();
+  return line.length > SUMMARY_LIMIT ? `${line.slice(0, SUMMARY_LIMIT)} ...` : line;
+};
+
+const preferredValue = (values: Record<string, unknown>) => {
+  for (const key of SUMMARY_KEYS) {
+    const value = values[key];
+    if (typeof value === "string" && value.trim() !== "") return value;
+  }
+  return undefined;
+};
+
+export const toolSummary = (tool: ToolInfo): string => {
+  const raw = (tool.arguments ?? "").trim();
+  if (raw === "" || raw === "{}") return "";
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return oneLine(raw);
+  }
+  if (typeof parsed === "string") return oneLine(parsed);
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return oneLine(raw);
+  const values = parsed as Record<string, unknown>;
+  const preferred = preferredValue(values);
+  if (preferred !== undefined) return oneLine(preferred);
+  const scalars = Object.entries(values)
+    .filter(([, value]) => typeof value !== "object" || value === null)
+    .map(([key, value]) => `${key}=${String(value)}`);
+  return oneLine(scalars.length > 0 ? scalars.join(" ") : raw);
+};
+
+export const toolLine = (tool: ToolInfo, label?: string): string => {
+  const name = label !== undefined && label.trim() !== "" ? label : tool.name;
+  const summary = toolSummary(tool);
+  return summary === "" ? name : `${name} ${summary}`;
+};
+
+export const withToolSummaries = (messages: readonly Message[]): Message[] =>
+  messages.map((message) =>
+    message.tool
+      ? { ...message, text: toolLine(message.tool, message.text) }
+      : message
+  );

package/apps/web/src/ui/ListDetail.tsx

@@ -0,0 +1,149 @@
+import { useEffect, useId, useLayoutEffect, useRef, useState, type ReactNode } from "react";
+import { ArrowLeftIcon, ChevronDownIcon } from "lucide-react";
+import { cn } from "cn";
+import { Button } from "./button";
+
+export interface ListDetailItem {
+  id: string;
+  title: string;
+  description?: string;
+  group?: string;
+  icon?: ReactNode;
+  meta?: ReactNode;
+  tone?: "neutral" | "accent" | "success" | "purple";
+}
+
+export interface ListDetailProps {
+  label: string;
+  items: readonly ListDetailItem[];
+  selectedId?: string;
+  onSelect: (id: string) => void;
+  disabled?: boolean;
+  toolbar?: ReactNode;
+  detailHeader?: ReactNode;
+  children?: ReactNode;
+  detailFooter?: ReactNode;
+  emptyState?: ReactNode;
+  detailLabel?: string;
+  className?: string;
+}
+
+// Tone und Tonfläche kommen aus data-tone und färben Symbol, Titel und Detailkopf.
+const toneVariables = "[--tone:var(--muted-foreground)] [--tone-soft:var(--secondary)] "
+  + "data-[tone=accent]:[--tone:var(--primary)] data-[tone=accent]:[--tone-soft:var(--accent)] "
+  + "data-[tone=success]:[--tone:var(--success)] data-[tone=success]:[--tone-soft:var(--success-soft)] "
+  + "data-[tone=purple]:[--tone:var(--primary)] data-[tone=purple]:[--tone-soft:var(--accent)]";
+
+const focusRing = "focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-ring/60";
+
+const itemClasses = cn(toneVariables, focusRing,
+  "group/item flex w-full min-w-0 items-center gap-2.5 rounded-lg border border-transparent px-2.5 py-3 text-left",
+  "not-disabled:hover:bg-foreground/7 disabled:cursor-default disabled:opacity-55",
+  "aria-pressed:border-border-strong aria-pressed:bg-(--tone-soft)");
+
+const paneClasses = "min-h-0 min-w-0 flex-auto overflow-auto overscroll-contain [scrollbar-gutter:stable]";
+
+// Maßgeblich ist die Breite des Bausteins, nicht die des Fensters; CSS und Messung nutzen dieselbe Schwelle.
+const narrowWidth = 900;
+
+/** Controlled grouped selection with a detail surface and a return path on narrow surfaces. */
+export function ListDetail({ label, items, selectedId, onSelect, disabled = false, toolbar,
+  detailHeader, children, detailFooter, emptyState, detailLabel = "Details", className }: ListDetailProps) {
+  const prefix = useId();
+  const rootRef = useRef<HTMLElement>(null);
+  const detailRef = useRef<HTMLElement>(null);
+  const listRef = useRef<HTMLDivElement>(null);
+  const buttons = useRef(new Map<string, HTMLButtonElement>());
+  const focusRequest = useRef<{ target: "detail" | "list"; id: string } | null>(null);
+  const [narrowDetailId, setNarrowDetailId] = useState<string>();
+  const [isNarrow, setNarrow] = useState(false);
+  const groups = new Map<string, ListDetailItem[]>();
+  const ids = new Set<string>();
+  for (const item of items) {
+    if (!item.id.trim() || ids.has(item.id)) throw new Error("ListDetail-Einträge benötigen eindeutige, nicht leere IDs.");
+    ids.add(item.id);
+    const key = item.group ?? "";
+    const group = groups.get(key) ?? [];
+    group.push(item);
+    groups.set(key, group);
+  }
+  const selected = items.find((item) => item.id === selectedId);
+  const showNarrowDetail = selected !== undefined && narrowDetailId === selected.id;
+
+  useEffect(() => {
+    const root = rootRef.current;
+    if (!root) throw new Error("ListDetail benötigt sein Wurzelelement für die Breitenmessung.");
+    const observer = new ResizeObserver(([entry]) => {
+      const next = entry.contentRect.width < narrowWidth;
+      setNarrow(next);
+      if (!next) setNarrowDetailId(undefined);
+    });
+    observer.observe(root);
+    return () => observer.disconnect();
+  }, []);
+
+  useLayoutEffect(() => {
+    const request = focusRequest.current;
+    if (!request) return;
+    focusRequest.current = null;
+    if (request.target === "detail" && (!showNarrowDetail || selected?.id !== request.id)) return;
+    const target = request.target === "detail" ? detailRef.current : buttons.current.get(request.id) ?? listRef.current;
+    target?.focus({ preventScroll: true });
+    target?.scrollIntoView({ block: "nearest", inline: "nearest" });
+  }, [narrowDetailId, selected?.id, showNarrowDetail]);
+
+  const choose = (id: string) => {
+    if (isNarrow) {
+      focusRequest.current = { target: "detail", id };
+      setNarrowDetailId(id);
+    }
+    onSelect(id);
+  };
+  const returnToList = () => {
+    if (!selected) return;
+    focusRequest.current = { target: "list", id: selected.id };
+    setNarrowDetailId(undefined);
+  };
+
+  return <section aria-label={label} className={cn("group/list-detail @container/list-detail flex min-h-0 min-w-0 flex-auto flex-col", className)}
+    data-detail={showNarrowDetail} ref={rootRef}>
+    {toolbar !== undefined && <div className="flex flex-none flex-wrap items-center gap-2.5 pb-4.5 @max-[900px]/list-detail:group-data-[detail=true]/list-detail:hidden">{toolbar}</div>}
+    <div className="grid min-h-0 min-w-0 flex-auto grid-cols-[minmax(0,0.9fr)_minmax(0,1.1fr)] grid-rows-[minmax(0,1fr)] gap-6 @max-[900px]/list-detail:grid-cols-[minmax(0,1fr)] @max-[900px]/list-detail:gap-0">
+      <div aria-label={label} className={cn(paneClasses, focusRing, "pt-0.5 pr-1.5 pb-3 @max-[900px]/list-detail:group-data-[detail=true]/list-detail:hidden")}
+        ref={listRef} role="region" tabIndex={-1}>
+        {items.length === 0 ? <div className="p-6 text-[0.8rem] leading-relaxed text-muted-foreground">{emptyState ?? <p>Keine Einträge vorhanden.</p>}</div>
+          : [...groups].map(([group, entries], groupIndex) => <section aria-labelledby={group ? `${prefix}-group-${groupIndex}` : undefined} className="not-first:mt-4.5" key={group}>
+            {group && <h3 className="mx-2 mb-2 flex items-center gap-2.5 text-[0.67rem] font-bold tracking-[0.04em] text-muted-foreground" id={`${prefix}-group-${groupIndex}`}>
+              {group}<span className="font-mono text-[0.63rem] opacity-80" aria-label={`${entries.length} Einträge`}>{entries.length}</span>
+            </h3>}
+            <ul className="grid grid-cols-[minmax(0,1fr)] gap-1 *:min-w-0">
+              {entries.map((item) => <li key={item.id}>
+                <button aria-controls={`${prefix}-detail`} aria-pressed={item.id === selectedId}
+                  className={itemClasses} data-tone={item.tone ?? "neutral"} disabled={disabled}
+                  onClick={() => choose(item.id)} ref={(element) => { if (element) buttons.current.set(item.id, element); else buttons.current.delete(item.id); }} type="button">
+                  {item.icon !== undefined && <span className="flex h-9 w-8 flex-none items-center justify-center rounded-sm border border-border-soft bg-(--tone-soft) text-(--tone) data-[tone=accent]:border-l-[3px] data-[tone=accent]:[border-left-color:var(--tone)] data-[tone=purple]:rounded-[10px_10px_10px_3px]" aria-hidden="true" data-tone={item.tone ?? "neutral"}>{item.icon}</span>}
+                  <span className="flex min-w-0 flex-1 flex-col gap-1"><span className="text-[0.77rem] font-semibold leading-snug [overflow-wrap:anywhere] group-aria-pressed/item:font-bold group-aria-pressed/item:text-(--tone)">{item.title}</span>
+                    {item.description && <span className="overflow-hidden text-[0.67rem] leading-[1.45] text-ellipsis whitespace-nowrap text-muted-foreground">{item.description}</span>}
+                  </span>
+                  {item.meta !== undefined && <span className="max-w-[30%] flex-none text-[0.62rem] leading-snug text-muted-foreground [overflow-wrap:anywhere] @max-[900px]/list-detail:max-w-[24%] @max-[900px]/list-detail:text-[0.6rem]">{item.meta}</span>}
+                  <ChevronDownIcon className="flex-none -rotate-90 text-muted-foreground" size={14} />
+                </button>
+              </li>)}
+            </ul>
+          </section>)}
+      </div>
+      <section aria-label={detailLabel} className={cn(toneVariables, focusRing,
+        "flex max-h-full min-h-0 min-w-0 flex-col self-stretch overflow-hidden rounded-panel border border-border bg-card",
+        "@max-[900px]/list-detail:hidden @max-[900px]/list-detail:group-data-[detail=true]/list-detail:flex")}
+        data-tone={selected?.tone ?? "neutral"}
+        id={`${prefix}-detail`} ref={detailRef} tabIndex={-1}>
+        {selected ? <>
+          <div className="hidden flex-none border-b border-border-soft px-3.5 py-2.5 @max-[900px]/list-detail:flex"><Button aria-label="Zur Auswahl" className="rounded-full" onClick={returnToList} size="icon" variant="outline"><ArrowLeftIcon /></Button></div>
+          {detailHeader !== undefined && <header className="flex-none border-b border-border-soft bg-(--tone-soft) px-6 py-6 [&>*:first-child]:mt-0 [&>*:last-child]:mb-0 @max-[900px]/list-detail:p-4.5">{detailHeader}</header>}
+          <div aria-label={`${detailLabel}: Inhalt`} className={cn(paneClasses, focusRing, "flex-1 px-6 py-6 text-[0.8rem] leading-[1.7] [overflow-wrap:anywhere] [&>*:first-child]:mt-0 [&>*:last-child]:mb-0 @max-[900px]/list-detail:p-4.5")} role="region" tabIndex={0}>{children}</div>
+          {detailFooter !== undefined && <footer className="flex flex-none flex-wrap items-center gap-2.5 border-t border-border-soft px-6 py-4 @max-[900px]/list-detail:px-4.5 @max-[900px]/list-detail:py-3.5">{detailFooter}</footer>}
+        </> : <div className="p-6 text-[0.8rem] leading-relaxed text-muted-foreground"><p>{items.length ? "Wähle einen Eintrag, um die Details zu sehen." : "Keine Auswahl verfügbar."}</p></div>}
+      </section>
+    </div>
+  </section>;
+}