@cosmicdrift/kumiko-renderer-web 0.1.0

package/src/app/nav.tsx

@@ -0,0 +1,226 @@
+// Browser-Impl der Navigation: HTML5-History + popstate subscribe.
+// Types + Context + useNav leben im shared `@cosmicdrift/kumiko-renderer`; dieser
+// File liefert nur die Web-spezifische NavApi-Instanz und die
+// `<KumikoLink>` Anchor-Komponente.
+//
+// Bewusst KEIN createStore: Source-of-truth ist `window.location.pathname`
+// (extern, kann via replaceState außerhalb unserer Kontrolle wechseln).
+// Ein Store wäre entweder eine zweite Wahrheit (Drift-Risiko) oder ein
+// reiner Tick-Counter (Anti-Pattern — createStore ist State-Holder, kein
+// Event-Bus). Hand-rolled Listener-Set ist hier idiomatisch: zwei
+// Notify-Trigger (eigenes pushPath, popstate-Event), nicht generalisierbar.
+
+import {
+  formatPath,
+  type NavApi,
+  type NavTarget,
+  parsePath,
+  useNav,
+} from "@cosmicdrift/kumiko-renderer";
+import {
+  type AnchorHTMLAttributes,
+  type MouseEvent,
+  type ReactNode,
+  useCallback,
+  useMemo,
+  useSyncExternalStore,
+} from "react";
+
+// basePath erlaubt es, die App unter einem URL-Prefix zu mounten
+// (z.B. `/admin`). Read-Pfad strippt den Prefix vor dem parsePath,
+// Write-Pfad prepend'd ihn vor dem pushState/replaceState/href.
+//
+// Wenn die URL nicht im basePath liegt (z.B. /marketing/foo bei
+// basePath="/admin"), liefert stripBasePath `undefined` — useBrowserNavApi
+// gibt dann route=undefined zurück, die App rendert ihren "outside"-State
+// (Not-Found, Marketing-Layer, Server-Routing-Pickup, …). Es gibt KEIN
+// Auto-Redirect zur App-Root — die Host-App entscheidet selbst.
+function normalizeBasePath(raw: string | undefined): string {
+  if (raw === undefined || raw === "" || raw === "/") return "";
+  const withLeading = raw.startsWith("/") ? raw : `/${raw}`;
+  return withLeading.endsWith("/") ? withLeading.slice(0, -1) : withLeading;
+}
+
+// Returns the in-app path (basePath-relativ) wenn `path` im basePath liegt,
+// sonst `undefined`. Strict-segment-Boundary: "/administrator" matcht
+// nicht "/admin" — sonst würde der Prefix-Check auf String-Ebene falsche
+// Treffer liefern.
+function stripBasePath(path: string, basePath: string): string | undefined {
+  if (basePath === "") return path;
+  if (path === basePath) return "/";
+  if (path.startsWith(`${basePath}/`)) return path.slice(basePath.length);
+  return undefined;
+}
+
+function prependBasePath(path: string, basePath: string): string {
+  if (basePath === "") return path;
+  // formatPath liefert immer absoluten in-app-Pfad: "/" oder "/screen-id"
+  // oder "/screen-id/entity-id". "/" → einfach basePath, sonst concat.
+  if (path === "/" || path === "") return basePath;
+  return `${basePath}${path}`;
+}
+
+// pushState feuert keinen popstate — wir halten einen eigenen
+// Listener-Set, den navigate() notifiziert. popstate (Back/Forward)
+// läuft über einen window-Listener, den wir einmalig verdrahten.
+const listeners = new Set<() => void>();
+let popstateWired = false;
+
+function ensurePopstateWired(): void {
+  if (popstateWired) return;
+  if (typeof window === "undefined") return;
+  window.addEventListener("popstate", () => {
+    for (const l of listeners) l();
+  });
+  popstateWired = true;
+}
+
+function subscribe(listener: () => void): () => void {
+  ensurePopstateWired();
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+function readPath(): string {
+  return typeof window !== "undefined" ? window.location.pathname : "/";
+}
+
+// Read der aktuellen ?key=value-Pairs als Plain-Record. URLSearchParams-
+// Iterator gibt String/String — wir kollabieren auf "letzter Wert
+// gewinnt" wenn ein Key mehrfach im Query auftaucht (`?a=1&a=2` → "2").
+// Multi-Value-Lists sind kein Use-Case in Kumiko-Filter-State; explizit
+// dokumentieren statt unspezifizierten Behavior zu liefern.
+function readSearch(): string {
+  return typeof window !== "undefined" ? window.location.search : "";
+}
+
+function parseSearchParams(search: string): Readonly<Record<string, string>> {
+  const out: Record<string, string> = {};
+  if (search === "") return out;
+  const params = new URLSearchParams(search);
+  for (const [k, v] of params.entries()) out[k] = v;
+  return out;
+}
+
+// Mergt updates in den aktuellen ?-String. `null` löscht, sonst
+// überschreibt. Verwendet replaceState (KEIN push) — Sort/Filter-Toggles
+// flutten sonst die Back-Navigation und User clicked sich durch
+// dutzende Zwischen-States um zur vorherigen Seite zu kommen.
+function applySearchParamUpdates(updates: Readonly<Record<string, string | null>>): void {
+  if (typeof window === "undefined") return;
+  const params = new URLSearchParams(window.location.search);
+  for (const [key, value] of Object.entries(updates)) {
+    if (value === null) {
+      params.delete(key);
+    } else {
+      params.set(key, value);
+    }
+  }
+  const next = params.toString();
+  const nextSearch = next === "" ? "" : `?${next}`;
+  if (nextSearch === window.location.search) return;
+  const url = `${window.location.pathname}${nextSearch}${window.location.hash}`;
+  window.history.replaceState(null, "", url);
+  for (const l of listeners) l();
+}
+
+function pushPath(path: string): void {
+  if (typeof window === "undefined") return;
+  // Nur pushen wenn sich der Pfad wirklich ändert — doppelte navigate()
+  // Aufrufe mit demselben Ziel sollen nicht die History fluten.
+  if (window.location.pathname === path) return;
+  window.history.pushState(null, "", path);
+  for (const l of listeners) l();
+}
+
+function replacePath(path: string): void {
+  if (typeof window === "undefined") return;
+  // No path-change short-circuit here: callers explicitly chose replace
+  // to avoid creating a history entry, even when the URL is identical.
+  // (pushPath skips no-op pushes; replacePath honors the call so the
+  // entry-stack semantics stay predictable.)
+  window.history.replaceState(null, "", path);
+  for (const l of listeners) l();
+}
+
+/** React-Hook der eine NavApi aus der Browser-History baut. Sollte
+ *  einmal im App-Root aufgerufen und als value an den shared
+ *  `<NavProvider>` durchgereicht werden — createKumikoApp tut das.
+ *
+ *  hasWorkspaces aus dem Schema (schema.workspaces non-empty) entscheidet,
+ *  ob das erste URL-Segment als Workspace-id parsed wird. Pure Pass-
+ *  through an parsePath; formatPath checkt selbst auf target.workspaceId.
+ *
+ *  basePath mounted die App unter einem URL-Prefix (z.B. "/admin"). Read-
+ *  Pfad strippt vor parsePath, Write-Pfad prepend'd vor pushState/href.
+ *  URLs außerhalb des basePath liefern route=undefined, ohne Auto-Redirect.
+ *
+ *  Achtung — Ambiguität bei route=undefined mit basePath:
+ *  Sowohl die App-Root (URL === basePath, z.B. "/admin") als auch URLs
+ *  außerhalb des basePath (z.B. "/marketing") liefern route=undefined. Eine
+ *  App die zwischen "render Default-Screen" und "render Not-Found"
+ *  unterscheiden muss, muss zusätzlich `window.location.pathname` prüfen:
+ *
+ *    if (window.location.pathname.startsWith("/admin")) {
+ *      // in-app, aber an der Root → Default-Screen
+ *    } else {
+ *      // out-of-app → Not-Found / Marketing-Layer
+ *    }
+ *
+ *  Im non-basePath-Modus ergibt sich diese Ambiguität nicht — out-of-app
+ *  ist dort kein Konzept. */
+export function useBrowserNavApi(options?: {
+  readonly hasWorkspaces?: boolean;
+  readonly basePath?: string;
+}): NavApi {
+  const path = useSyncExternalStore(subscribe, readPath, () => "/");
+  // Search wird über denselben Listener-Set notifiziert (popstate +
+  // unsere replaceState-Calls), also reichen wir denselben subscribe
+  // durch. Beide Snapshots werden zusammen recomputed — kein Drift
+  // zwischen Pfad und Query.
+  const search = useSyncExternalStore(subscribe, readSearch, () => "");
+  const hasWorkspaces = options?.hasWorkspaces === true;
+  const basePath = useMemo(() => normalizeBasePath(options?.basePath), [options?.basePath]);
+  const searchParams = useMemo(() => parseSearchParams(search), [search]);
+  const inAppPath = useMemo(() => stripBasePath(path, basePath), [path, basePath]);
+  return useMemo<NavApi>(
+    () => ({
+      route: inAppPath === undefined ? undefined : parsePath(inAppPath, hasWorkspaces),
+      navigate: (target) => pushPath(prependBasePath(formatPath(target), basePath)),
+      replace: (target) => replacePath(prependBasePath(formatPath(target), basePath)),
+      hrefFor: (target) => prependBasePath(formatPath(target), basePath),
+      searchParams,
+      setSearchParams: applySearchParamUpdates,
+    }),
+    [inAppPath, hasWorkspaces, basePath, searchParams],
+  );
+}
+
+// ---- KumikoLink (Anchor-basiert, nur Web) ----
+
+export type KumikoLinkProps = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> & {
+  readonly to: NavTarget;
+};
+
+export function KumikoLink({ to, onClick, children, ...rest }: KumikoLinkProps): ReactNode {
+  const nav = useNav();
+  const handleClick = useCallback(
+    (e: MouseEvent<HTMLAnchorElement>) => {
+      onClick?.(e);
+      if (e.defaultPrevented) return;
+      // Standard-Browser-Verhalten für Cmd/Ctrl/Shift/Alt + Middle-Click
+      // erhalten — nur der plain-left-click landet bei navigate().
+      if (e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+      e.preventDefault();
+      nav.navigate(to);
+    },
+    [nav, to, onClick],
+  );
+  return (
+    <a href={nav.hrefFor(to)} onClick={handleClick} {...rest}>
+      {children}
+    </a>
+  );
+}

package/src/index.ts

@@ -0,0 +1,137 @@
+// Public entry für @cosmicdrift/kumiko-renderer-web. Re-exportiert die shared-
+// API aus @cosmicdrift/kumiko-renderer damit Samples nur ein Paket importieren
+// müssen, und fügt die Web-spezifischen Helpers dazu: createKumikoApp
+// (react-dom-bootstrap), defaultPrimitives (HTML), useBrowserNavApi
+// (window.history), createEventSourceLiveEvents, KumikoLink.
+
+// --- Shared re-exports (Components, Hooks, Types, Contexts) ---
+export type {
+  AppPrimitives,
+  AppSchema,
+  AppTokens,
+  BannerProps,
+  ButtonProps,
+  ColorTokens,
+  CorePrimitives,
+  CoreTokens,
+  DataTableProps,
+  DispatcherProviderProps,
+  FeatureSchema,
+  FieldProps,
+  FormProps,
+  GridCellProps,
+  GridProps,
+  HeadingProps,
+  InputProps,
+  KumikoScreenProps,
+  LiveEvent,
+  LiveEventSubscriber,
+  LiveEventsProviderProps,
+  LocaleProviderProps,
+  NavApi,
+  NavProviderProps,
+  NavRoute,
+  NavTarget,
+  PrimitivesProviderProps,
+  PrimitivesRegistry,
+  RadiusTokens,
+  RenderEditProps,
+  RenderFieldProps,
+  RenderListProps,
+  SectionProps,
+  TextProps,
+  ThemeMode,
+  Tokens,
+  TokensApi,
+  TokensProviderProps,
+  TranslationBundle,
+  TranslationsByLocale,
+  UseFormOptions,
+  UseFormResult,
+  UseQueryOptions,
+  UseQueryResult,
+  WorkspaceSchema,
+} from "@cosmicdrift/kumiko-renderer";
+export {
+  createStaticLocaleResolver,
+  cssVarTokens,
+  DispatcherProvider,
+  formatPath,
+  KumikoScreen,
+  LiveEventsProvider,
+  LocaleProvider,
+  NavProvider,
+  PrimitivesProvider,
+  parsePath,
+  qualifyScreenId,
+  RenderEdit,
+  RenderField,
+  RenderList,
+  TokensProvider,
+  useDispatcher,
+  useDispatcherStatus,
+  useForm,
+  useLiveEvents,
+  useLocale,
+  useNav,
+  usePrimitives,
+  useQuery,
+  useStore,
+  useStoreSelector,
+  useTokenController,
+  useTokens,
+  useTranslation,
+} from "@cosmicdrift/kumiko-renderer";
+// --- Web-platform specifics ---
+export { createBrowserLocaleResolver } from "./app/browser-locale";
+export type { ClientFeatureDefinition } from "./app/client-plugin";
+export type { CreateKumikoAppOptions } from "./app/create-app";
+export { createKumikoApp } from "./app/create-app";
+export type { KumikoLinkProps } from "./app/nav";
+export { KumikoLink, useBrowserNavApi } from "./app/nav";
+export type { AppLayoutProps } from "./layout/app-layout";
+export { AppLayout } from "./layout/app-layout";
+export type { AvatarProps, AvatarSize } from "./layout/avatar";
+export { Avatar } from "./layout/avatar";
+export type { DefaultAppShellProps } from "./layout/default-app-shell";
+export { DefaultAppShell } from "./layout/default-app-shell";
+export type { LanguageSwitcherProps, LocaleOption } from "./layout/language-switcher";
+export { LanguageSwitcher } from "./layout/language-switcher";
+export type { NavTreeProps } from "./layout/nav-tree";
+export { buildNavRegistrySlice, NavTree } from "./layout/nav-tree";
+export type { ProfileMenuItem, ProfileMenuProps } from "./layout/profile-menu";
+export { ProfileMenu } from "./layout/profile-menu";
+export type { SidebarProps } from "./layout/sidebar";
+export { Sidebar } from "./layout/sidebar";
+export type { ThemeToggleProps } from "./layout/theme-toggle";
+export { ThemeToggle } from "./layout/theme-toggle";
+export type { TopbarProps } from "./layout/topbar";
+export { Topbar } from "./layout/topbar";
+export type { WorkspaceShellProps, WorkspaceShellUser } from "./layout/workspace-shell";
+export { filterByAccess, resolveDefaultId, WorkspaceShell } from "./layout/workspace-shell";
+export type { WorkspaceSwitcherProps } from "./layout/workspace-switcher";
+export { WorkspaceSwitcher } from "./layout/workspace-switcher";
+export { cn } from "./lib/cn";
+export { defaultPrimitives } from "./primitives";
+export type { ActionMenuProps, MenuItemDef } from "./primitives/action-menu";
+export { ActionMenu } from "./primitives/action-menu";
+export {
+  DropdownMenu,
+  DropdownMenuCheckboxItem,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuPortal,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "./primitives/dropdown-menu";
+export type { ToastOptions, ToastProviderProps, ToastVariant } from "./primitives/toast";
+export { ToastProvider, useToast } from "./primitives/toast";
+export type { CreateEventSourceLiveEventsOptions } from "./sse/live-events";
+export { createEventSourceLiveEvents } from "./sse/live-events";
+export {
+  applyTokensToCssVars,
+  defaultTokens,
+  lightTokens,
+  useBrowserTokensApi,
+} from "./tokens";

package/src/layout/app-layout.tsx

@@ -0,0 +1,35 @@
+import type { ReactNode } from "react";
+
+// Linear-Pattern: Sidebar ist Geschwister von <Topbar+Main>-Spalte,
+// nimmt die volle Höhe. Wenn ein Topbar gesetzt ist, lebt er NUR über
+// der Main-Spalte rechts neben der Sidebar. So wirkt die Sidebar als
+// kontinuierlicher Chrome-Streifen mit eigener Identität, statt unter
+// einer durchgehenden Kopfzeile geklemmt zu werden.
+
+export type AppLayoutProps = {
+  /** Optional. Lebt nur über dem Main-Bereich, nicht über der Sidebar. */
+  readonly topbar?: ReactNode;
+  readonly sidebar?: ReactNode;
+  readonly children: ReactNode;
+  readonly testId?: string;
+};
+
+export function AppLayout({ topbar, sidebar, children, testId }: AppLayoutProps): ReactNode {
+  return (
+    <div
+      data-testid={testId}
+      data-kumiko-layout="app"
+      className="flex min-h-screen flex-row bg-background text-foreground"
+    >
+      {sidebar}
+      <div className="flex flex-1 min-w-0 flex-col">
+        {topbar}
+        {/* main hat KEIN Padding — Screens (Form, Liste, Demo-Pages)
+             managen ihr Padding selber, damit Action-Bars edge-to-edge
+             spannen können ohne Negative-Margin-Tricks die mit
+             `position: sticky` kollidieren. */}
+        <main className="flex-1 overflow-auto">{children}</main>
+      </div>
+    </div>
+  );
+}

package/src/layout/avatar.tsx

@@ -0,0 +1,93 @@
+// Avatar-Pill mit Initials. Color-coded background basierend auf
+// string-hash damit der gleiche User immer dieselbe Farbe bekommt
+// (Linear-Pattern). 8 Hue-Targets für gute Distinktion ohne über-
+// bunte Sidebar.
+//
+// Nutzung: `<Avatar id="user-123" label="Daniel Hennig" size="md" />`.
+// `id` ist die Hash-Quelle für die Farbe; `label` wird für Initials
+// + aria-label genutzt. Kein Image-Slot im MVP — kommt wenn Apps
+// echte Avatar-URLs haben.
+
+import { type ReactNode, useMemo } from "react";
+import { cn } from "../lib/cn";
+
+export type AvatarSize = "sm" | "md" | "lg";
+
+export type AvatarProps = {
+  /** Stable Identifier — Hash-Quelle für die Background-Farbe. Üblich
+   *  user.id; bei rein labelbasierten Avataren auch der label-String. */
+  readonly id: string;
+  /** Voller Name oder Email — Initials werden daraus extrahiert. */
+  readonly label: string;
+  readonly size?: AvatarSize;
+  readonly testId?: string;
+};
+
+// Tailwind-Klassen pro Hue. Die Background-Lightness ist dezent (550-
+// 600 für saturation), die Foreground-Lightness ist hell (50-100) für
+// Kontrast. Passt zu beiden Modes weil die Tokens via CSS-vars greifen
+// — aber: feste hex-Farben hier sind stabiler als token-mapping
+// (Avatar-Farbe sollte deterministic sein, nicht theme-abhängig).
+const COLOR_CLASSES = [
+  "bg-rose-600 text-rose-50",
+  "bg-orange-600 text-orange-50",
+  "bg-amber-600 text-amber-50",
+  "bg-emerald-600 text-emerald-50",
+  "bg-teal-600 text-teal-50",
+  "bg-sky-600 text-sky-50",
+  "bg-indigo-600 text-indigo-50",
+  "bg-fuchsia-600 text-fuchsia-50",
+] as const;
+
+const SIZE_CLASSES: Record<AvatarSize, string> = {
+  sm: "size-5 text-[10px]",
+  md: "size-6 text-[11px]",
+  lg: "size-8 text-xs",
+};
+
+function hashCode(str: string): number {
+  // djb2-Variante — schnell, deterministic, gut genug verteilt für
+  // 8 Buckets. Crypto-Hash wäre Overkill für color-bucketing.
+  let hash = 5381;
+  for (let i = 0; i < str.length; i++) {
+    hash = ((hash << 5) + hash + str.charCodeAt(i)) >>> 0;
+  }
+  return hash;
+}
+
+function pickColor(id: string): string {
+  const idx = hashCode(id) % COLOR_CLASSES.length;
+  return COLOR_CLASSES[idx] ?? COLOR_CLASSES[0] ?? "bg-muted";
+}
+
+function extractInitials(label: string): string {
+  // "Daniel Hennig" → "DH". "alice@example.com" → "A". Single-word
+  // fällt auf erste 2 Buchstaben zurück ("Daniel" → "DA"). Alles
+  // upper-case.
+  const trimmed = label.trim();
+  if (trimmed.length === 0) return "?";
+  const parts = trimmed.split(/\s+/);
+  if (parts.length >= 2) {
+    return `${(parts[0]?.[0] ?? "").toUpperCase()}${(parts[1]?.[0] ?? "").toUpperCase()}`;
+  }
+  return trimmed.slice(0, 2).toUpperCase();
+}
+
+export function Avatar({ id, label, size = "md", testId }: AvatarProps): ReactNode {
+  const colorClass = useMemo(() => pickColor(id), [id]);
+  const initials = useMemo(() => extractInitials(label), [label]);
+  return (
+    <span
+      data-testid={testId}
+      role="img"
+      aria-label={label}
+      className={cn(
+        "inline-flex items-center justify-center rounded font-semibold uppercase select-none",
+        SIZE_CLASSES[size],
+        colorClass,
+      )}
+    >
+      {initials}
+    </span>
+  );
+}

package/src/layout/default-app-shell.tsx

@@ -0,0 +1,74 @@
+// DefaultAppShell — Linear-Pattern: kein globaler Topbar, Sidebar
+// nimmt full-height und trägt die ganze Chrome-Identität. 90% der
+// Apps brauchen exakt das hier.
+//
+// Sidebar-Slots:
+//   1. brand          — Workspace-Identity oben (z.B. Logo + Name)
+//   2. sidebarActions — Icon-Row mit Search/Theme/Tenant-Switch etc.
+//   3. NavTree        — automatisch aus dem Schema
+//   4. sidebarFooter  — Bottom-Slot für Profile/Help/Plan-Banner
+//
+// Apps die feingranulare Kontrolle wollen, gehen direkt auf
+// <AppLayout>/<Sidebar>/<NavTree>. Wer ein Topbar zurück will (z.B.
+// für Multi-Workspace mit Switcher in der Topbar), nutzt
+// <WorkspaceShell> oder baut den Shell selber.
+
+import type { AppSchema, FeatureSchema } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import { AppLayout } from "./app-layout";
+import { NavTree } from "./nav-tree";
+import { Sidebar } from "./sidebar";
+
+export type DefaultAppShellUser = {
+  readonly id: string;
+  readonly roles: readonly string[];
+};
+
+export type DefaultAppShellProps = {
+  /** Header-Slot oben in der Sidebar — Workspace-Identity (Logo,
+   *  Name, Plan-Tag). Caller liefert frei. */
+  readonly brand: ReactNode;
+  /** Schema (AppSchema oder legacy FeatureSchema) wird an NavTree
+   *  durchgereicht; Sidebar-Einträge bauen sich automatisch aus
+   *  schema.navs (per-Feature) auf. */
+  readonly schema: AppSchema | FeatureSchema;
+  /** Current user — drives nav role-gating. Ohne user-prop werden
+   *  role-gated nav-einträge (`access: { roles: [...] }`) komplett
+   *  ausgeblendet (resolveNavigation behandelt undefined-user als
+   *  anonymous). Symmetrisch zu WorkspaceShell.user. */
+  readonly user?: DefaultAppShellUser;
+  /** Icon-Row zwischen Brand und NavTree — typisch Search-Trigger,
+   *  ThemeToggle, TenantSwitcher. Linear hat hier ~3 Icons in einer
+   *  horizontalen Reihe. */
+  readonly sidebarActions?: ReactNode;
+  /** Footer-Slot unten in der Sidebar — Profile-Row, Help-Link,
+   *  Plan-Banner. Klebt am unteren Rand via `mt-auto`. */
+  readonly sidebarFooter?: ReactNode;
+  /** Screen-Content der in `main` gerendert wird. */
+  readonly children: ReactNode;
+};
+
+export function DefaultAppShell({
+  brand,
+  schema,
+  user,
+  sidebarActions,
+  sidebarFooter,
+  children,
+}: DefaultAppShellProps): ReactNode {
+  return (
+    <AppLayout
+      sidebar={
+        <Sidebar
+          header={brand}
+          {...(sidebarActions !== undefined && { actions: sidebarActions })}
+          {...(sidebarFooter !== undefined && { footer: sidebarFooter })}
+        >
+          <NavTree schema={schema} {...(user !== undefined && { user })} />
+        </Sidebar>
+      }
+    >
+      {children}
+    </AppLayout>
+  );
+}

package/src/layout/language-switcher.tsx

@@ -0,0 +1,101 @@
+// LanguageSwitcher — Dropdown der die App-Locale via
+// LocaleResolver.setLocale umschaltet. Auf Radix-DropdownMenu, gleicher
+// Stack wie UserMenu/TenantSwitcher.
+//
+// Rendert gar nix wenn der Resolver keine setLocale-Methode anbietet
+// (statischer Resolver) — App-Dev sieht dann sofort dass er einen
+// stateful Resolver verdrahten muss, bevor der Switcher UI-sichtbar
+// wird.
+//
+// Icon-Slot optional: das Framework zieht lucide-react nicht selbst
+// rein; eine App die keinen Icon-Import will, kriegt den Globe-
+// Unicode-Glyph (🌐) als Default.
+
+import { useLocale } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useMemo } from "react";
+import { cn } from "../lib/cn";
+import {
+  DropdownMenu,
+  DropdownMenuCheckboxItem,
+  DropdownMenuContent,
+  DropdownMenuTrigger,
+} from "../primitives/dropdown-menu";
+
+export type LocaleOption = {
+  /** BCP-47-Code, z.B. "de", "en-US", "fr-CA". Wird 1:1 an
+   *  resolver.setLocale() weitergereicht. */
+  readonly code: string;
+  /** Menschenlesbare Anzeige im Dropdown. */
+  readonly label: string;
+};
+
+export type LanguageSwitcherProps = {
+  /** Auswählbare Locales. Reihenfolge = Anzeige-Reihenfolge im Menü. */
+  readonly locales: readonly LocaleOption[];
+  /** Icon-Slot links neben dem Button-Label. Default: 🌐. */
+  readonly icon?: ReactNode;
+  /** aria-label + title des Triggers. Default: "Sprache". */
+  readonly label?: string;
+  readonly testId?: string;
+};
+
+export function LanguageSwitcher({
+  locales,
+  icon = "🌐",
+  label = "Sprache",
+  testId,
+}: LanguageSwitcherProps): ReactNode {
+  const resolver = useLocale();
+
+  const activeLocale = resolver.locale();
+  // Match entweder exact ("de-DE") oder Language-Root ("de") gegen die
+  // verfügbaren Optionen. So zeigt der Switcher "Deutsch" aktiv wenn
+  // der Browser "de-AT" liefert und die Option nur "de" heißt.
+  const activeOption = useMemo(() => {
+    const exact = locales.find((o) => o.code === activeLocale);
+    if (exact) return exact;
+    const root = activeLocale.split("-")[0];
+    return locales.find((o) => o.code === root);
+  }, [locales, activeLocale]);
+
+  if (resolver.setLocale === undefined) {
+    // Stateless-Resolver → kein Wechsel möglich. Kein Noise im Topbar.
+    return null;
+  }
+
+  const setLocale = resolver.setLocale;
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <button
+          type="button"
+          aria-label={label}
+          title={label}
+          data-testid={testId}
+          className={cn(
+            "inline-flex h-8 items-center gap-1.5 rounded-md border bg-background px-2 text-sm",
+            "hover:bg-accent hover:text-accent-foreground",
+            "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+          )}
+        >
+          <span aria-hidden="true">{icon}</span>
+          <span className="uppercase text-xs text-muted-foreground">
+            {activeOption?.code ?? activeLocale.slice(0, 2)}
+          </span>
+        </button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="min-w-[10rem]" aria-label={label}>
+        {locales.map((opt) => (
+          <DropdownMenuCheckboxItem
+            key={opt.code}
+            checked={opt === activeOption}
+            onSelect={() => setLocale(opt.code)}
+          >
+            <span className="truncate">{opt.label}</span>
+          </DropdownMenuCheckboxItem>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}