@cosmicdrift/kumiko-renderer-web 0.1.0

package/src/primitives/money-input.tsx

@@ -0,0 +1,192 @@
+// MoneyInput — type=text mit focus-aware Locale-Format. Canonical-Wert
+// bleiben Minor-Units (Cents) wie auf der Wire; während Focus zeigt das
+// Input einen rohen, editierbaren Decimal-String. Bei Blur formatiert
+// Intl.NumberFormat mit `style: "currency"` — das liefert Currency-
+// Symbol (€/$/¥) UND Tausender-Trenner UND korrekte Decimals in einem
+// Aufruf.
+//
+// Warum nicht type=number: number-Inputs lehnen formatierte Strings
+// ("1.234,56 €") ab — kein Browser akzeptiert Locale-Decimals (Komma)
+// in number-Inputs. inputMode="decimal" gibt mobiles Numpad-Keyboard
+// trotzdem.
+//
+// +/- Buttons mutieren den Canonical-Wert direkt (1 Major-Unit pro
+// Klick — also 100 cents bei EUR/USD, 1 yen bei JPY). User der nur
+// Cent-genaue Steps will tippt halt im Focus-Modus.
+
+import { Minus, Plus } from "lucide-react";
+import { type FocusEvent, type ReactNode, useState } from "react";
+import { cn } from "../lib/cn";
+
+export type MoneyInputProps = {
+  readonly id: string;
+  readonly name: string;
+  readonly value: number | "";
+  readonly onChange: (v: number | undefined) => void;
+  readonly currency: string;
+  readonly locale?: string;
+  readonly disabled?: boolean;
+  readonly required?: boolean;
+  readonly hasError?: boolean;
+};
+
+const inputClass =
+  "flex h-9 w-full rounded-md border border-input bg-transparent pl-3 pr-1 text-sm shadow-sm " +
+  "transition-colors placeholder:text-muted-foreground focus-visible:outline-none " +
+  "focus-visible:ring-1 focus-visible:ring-ring " +
+  "disabled:cursor-not-allowed disabled:opacity-50 " +
+  // Numerische Inputs rechtsbündig — wie native type=number — damit
+  // Beträge unter Listen-Spalten an den Tausender-Stellen alignen.
+  "text-right tabular-nums";
+
+const stepBtnClass =
+  "inline-flex h-7 w-7 items-center justify-center rounded-sm text-muted-foreground " +
+  "hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-1 " +
+  "focus-visible:ring-ring disabled:opacity-40 disabled:pointer-events-none";
+
+export function MoneyInput({
+  id,
+  name,
+  value,
+  onChange,
+  currency,
+  locale,
+  disabled,
+  required,
+  hasError,
+}: MoneyInputProps): ReactNode {
+  const decimals = currencyDecimals(currency);
+  const factor = 10 ** decimals;
+  const resolvedLocale = locale ?? guessLocale();
+  const [focused, setFocused] = useState(false);
+  // Raw-Edit-Buffer während Focus. Sonst würde jeder Tipp-Step durch
+  // Math.round → format-Roundtrip jagen und der Cursor würde springen.
+  const [draft, setDraft] = useState<string>("");
+
+  const major = value === "" ? null : value / factor;
+
+  const formatted =
+    major === null
+      ? ""
+      : new Intl.NumberFormat(resolvedLocale, {
+          style: "currency",
+          currency,
+          minimumFractionDigits: decimals,
+          maximumFractionDigits: decimals,
+        }).format(major);
+
+  // Edit-Mode: Decimal-String ohne Tausender-Trenner. Konsistente Helper-
+  // Funktion damit Focus-Init und Render-Fallback nicht auseinanderdriften.
+  const toEditable = (m: number | null): string =>
+    m === null
+      ? ""
+      : m.toLocaleString(resolvedLocale, {
+          minimumFractionDigits: decimals,
+          maximumFractionDigits: decimals,
+          useGrouping: false,
+        });
+
+  const editable = focused ? draft : toEditable(major);
+
+  const handleFocus = (_e: FocusEvent<HTMLInputElement>): void => {
+    setDraft(toEditable(major));
+    setFocused(true);
+  };
+
+  const handleBlur = (): void => {
+    setFocused(false);
+    if (draft.trim() === "") {
+      onChange(undefined);
+      return;
+    }
+    const parsed = parseLocaleNumber(draft, resolvedLocale);
+    if (Number.isNaN(parsed)) return;
+    onChange(Math.round(parsed * factor));
+  };
+
+  const bump = (delta: number): void => {
+    const current = value === "" ? 0 : value;
+    onChange(current + delta * factor);
+  };
+
+  return (
+    <div className="relative w-full">
+      <input
+        id={id}
+        name={name}
+        type="text"
+        inputMode="decimal"
+        autoComplete="off"
+        disabled={disabled}
+        aria-required={required}
+        aria-invalid={hasError === true ? true : undefined}
+        value={focused ? editable : formatted}
+        onFocus={handleFocus}
+        onBlur={handleBlur}
+        onChange={(e) => setDraft(e.target.value)}
+        className={cn(
+          inputClass,
+          "pr-20",
+          hasError === true && "border-destructive focus-visible:ring-destructive",
+        )}
+      />
+      <div className="absolute right-1 top-1/2 -translate-y-1/2 flex items-center gap-0.5">
+        <button
+          type="button"
+          aria-label="−"
+          tabIndex={-1}
+          disabled={disabled}
+          onClick={() => bump(-1)}
+          className={stepBtnClass}
+        >
+          <Minus className="size-3.5" aria-hidden="true" />
+        </button>
+        <button
+          type="button"
+          aria-label="+"
+          tabIndex={-1}
+          disabled={disabled}
+          onClick={() => bump(1)}
+          className={stepBtnClass}
+        >
+          <Plus className="size-3.5" aria-hidden="true" />
+        </button>
+      </div>
+    </div>
+  );
+}
+
+// Currency-Decimal-Stellen — überdeckt die wichtigsten Welt-Währungen.
+// Default 2 wenn Code unbekannt.
+export function currencyDecimals(code: string): number {
+  if (code === "JPY" || code === "KRW" || code === "VND" || code === "ISK") return 0;
+  if (code === "BHD" || code === "JOD" || code === "KWD" || code === "OMR" || code === "TND")
+    return 3;
+  return 2;
+}
+
+function guessLocale(): string {
+  if (typeof navigator !== "undefined" && navigator.language) return navigator.language;
+  return "en-US";
+}
+
+// Locale-Decimal-Parse: erkennt automatisch ob Komma oder Punkt der
+// Decimal-Separator ist. Intl.NumberFormat liefert die Trenner für
+// das Locale, daraus bauen wir den Reverse-Parser. Strict beim
+// Vorzeichen: ein `-` darf NUR ganz vorne stehen — `1-23` ist invalid,
+// nicht `-123` (sonst würden vertippte Inputs zu falschen Beträgen).
+export function parseLocaleNumber(raw: string, locale: string): number {
+  const parts = new Intl.NumberFormat(locale).formatToParts(1234.5);
+  const groupSep = parts.find((p) => p.type === "group")?.value ?? ",";
+  const decimalSep = parts.find((p) => p.type === "decimal")?.value ?? ".";
+  const trimmed = raw.trim();
+  const negative = trimmed.startsWith("-");
+  const body = negative ? trimmed.slice(1) : trimmed;
+  // Body darf nur noch Ziffern, Group- und Decimal-Separator enthalten.
+  // Alles andere (zweites Minus, Buchstaben, etc.) → NaN, damit Caller
+  // (handleBlur) den Wert verwirft statt eine korrupte Zahl zu setzen.
+  const cleaned = body.split(groupSep).join("").split(decimalSep).join(".");
+  if (!/^[0-9]*\.?[0-9]*$/.test(cleaned) || cleaned === "" || cleaned === ".") return Number.NaN;
+  const n = Number(cleaned);
+  return negative ? -n : n;
+}

package/src/primitives/toast.tsx

@@ -0,0 +1,166 @@
+// Toast-Primitive auf @radix-ui/react-toast. Ein globaler Provider
+// + ein useToast()-Hook der von überall in der App aus Toasts auslösen
+// kann. Kein Context-Boilerplate für Konsumenten — der Hook returned
+// einen `toast()`-Trigger, mehr Public-API gibt's nicht.
+//
+// Variants: "default" (neutral) und "destructive" (Fehler-Akzent).
+// Auto-dismiss nach 5s, manuell schließbar via X-Button. Der ARIA-
+// Live-Region-Setup kommt komplett aus Radix.
+
+import * as Primitive from "@radix-ui/react-toast";
+import { X } from "lucide-react";
+import {
+  createContext,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { cn } from "../lib/cn";
+
+export type ToastVariant = "default" | "destructive";
+
+export type ToastOptions = {
+  readonly title: string;
+  readonly description?: string;
+  readonly variant?: ToastVariant;
+  // Self-service deep-link (z.B. KumikoError.docsUrl). Wenn gesetzt
+  // rendert der Toast einen "Mehr erfahren →" Link der in neuem Tab
+  // öffnet. Label override via `docsLinkLabel` (Default: deutsch).
+  readonly docsUrl?: string;
+  readonly docsLinkLabel?: string;
+};
+
+type ToastEntry = ToastOptions & {
+  readonly id: string;
+};
+
+type ToastApi = {
+  readonly toast: (opts: ToastOptions) => void;
+};
+
+const ToastContext = createContext<ToastApi | null>(null);
+
+export function useToast(): ToastApi {
+  const ctx = useContext(ToastContext);
+  if (ctx === null) {
+    // Nicht throwen — Tests die einen Component ohne Provider rendern
+    // sollen nicht crashen. No-op statt fehlerhaftes Mount.
+    return { toast: () => undefined };
+  }
+  return ctx;
+}
+
+export type ToastProviderProps = {
+  readonly children: ReactNode;
+};
+
+export function ToastProvider({ children }: ToastProviderProps): ReactNode {
+  const [entries, setEntries] = useState<readonly ToastEntry[]>([]);
+  // Monoton wachsender Counter via useRef — useState hätte einen
+  // closure-Bug: zwei toast()-Calls im selben Tick lesen denselben
+  // alten Wert aus dem Closure und kollidieren bei der ID. Ref ist
+  // synchron-mutabel, jeder Aufruf bekommt eine garantiert neue ID.
+  const idPrefix = useId();
+  const counterRef = useRef(0);
+
+  const toast = useCallback(
+    (opts: ToastOptions) => {
+      counterRef.current += 1;
+      const id = `${idPrefix}-${counterRef.current}`;
+      setEntries((current) => [...current, { ...opts, id }]);
+    },
+    [idPrefix],
+  );
+
+  const api = useMemo<ToastApi>(() => ({ toast }), [toast]);
+
+  return (
+    <ToastContext.Provider value={api}>
+      <Primitive.Provider swipeDirection="right" duration={5000}>
+        {children}
+        {entries.map((entry) => (
+          <ToastItem
+            key={entry.id}
+            entry={entry}
+            onClose={() => setEntries((current) => current.filter((e) => e.id !== entry.id))}
+          />
+        ))}
+        <Primitive.Viewport
+          className={cn(
+            "fixed top-0 right-0 z-[100] flex max-h-screen w-full flex-col-reverse gap-2 p-4",
+            "sm:bottom-0 sm:right-0 sm:top-auto sm:flex-col md:max-w-[420px]",
+          )}
+        />
+      </Primitive.Provider>
+    </ToastContext.Provider>
+  );
+}
+
+const rootClass =
+  "group pointer-events-auto relative flex w-full items-center justify-between space-x-2 " +
+  "overflow-hidden rounded-md border p-4 pr-6 shadow-lg transition-all " +
+  "data-[swipe=cancel]:translate-x-0 data-[swipe=end]:translate-x-[var(--radix-toast-swipe-end-x)] " +
+  "data-[swipe=move]:translate-x-[var(--radix-toast-swipe-move-x)] data-[swipe=move]:transition-none " +
+  "data-[state=open]:animate-in data-[state=closed]:animate-out data-[swipe=end]:animate-out " +
+  "data-[state=closed]:fade-out-80 data-[state=closed]:slide-out-to-right-full " +
+  "data-[state=open]:slide-in-from-top-full data-[state=open]:sm:slide-in-from-bottom-full";
+
+function ToastItem({
+  entry,
+  onClose,
+}: {
+  readonly entry: ToastEntry;
+  readonly onClose: () => void;
+}): ReactNode {
+  const variantClass =
+    entry.variant === "destructive"
+      ? "destructive group border-destructive bg-destructive text-destructive-foreground"
+      : "border bg-background text-foreground";
+  return (
+    <Primitive.Root
+      className={cn(rootClass, variantClass)}
+      onOpenChange={(open) => {
+        if (!open) onClose();
+      }}
+    >
+      <div className="grid gap-1">
+        <Primitive.Title className="text-sm font-semibold">{entry.title}</Primitive.Title>
+        {entry.description !== undefined && (
+          <Primitive.Description className="text-sm opacity-90">
+            {entry.description}
+          </Primitive.Description>
+        )}
+        {entry.docsUrl !== undefined && (
+          <Primitive.Action altText={entry.docsLinkLabel ?? "Mehr erfahren"} asChild>
+            <a
+              href={entry.docsUrl}
+              target="_blank"
+              rel="noopener noreferrer"
+              className={cn(
+                "text-xs underline opacity-90 hover:opacity-100",
+                "focus:outline-none focus:ring-1 focus:ring-current rounded",
+              )}
+            >
+              {entry.docsLinkLabel ?? "Mehr erfahren"} →
+            </a>
+          </Primitive.Action>
+        )}
+      </div>
+      <Primitive.Close
+        className={cn(
+          "absolute right-2 top-2 rounded-md p-1 text-foreground/50 opacity-0 transition-opacity",
+          "hover:text-foreground focus:opacity-100 focus:outline-none focus:ring-1",
+          "group-hover:opacity-100",
+          "group-[.destructive]:text-red-300 group-[.destructive]:hover:text-red-50",
+        )}
+        aria-label="Close"
+      >
+        <X className="h-4 w-4" />
+      </Primitive.Close>
+    </Primitive.Root>
+  );
+}

package/src/sse/live-events.ts

@@ -0,0 +1,90 @@
+import type { LiveEvent, LiveEventSubscriber } from "@cosmicdrift/kumiko-renderer";
+
+// EventSource-backed Live-Events für den Web-Renderer. Der shared
+// Layer konsumiert nur das `LiveEventSubscriber`-Interface; diese Datei
+// liefert eine Factory die intern eine EventSource auf /api/sse aufbaut,
+// pro (entity, verb)-Kombi einen addEventListener verdrahtet und
+// subscriptions routet.
+//
+// Verbindungs-Lifecycle: lazy beim ersten subscribe, close wenn der
+// letzte unsubscribe feuert. Mehrere Consumer teilen sich dieselbe
+// EventSource, sparen CPU + Server-Load.
+
+const VERBS = ["created", "updated", "deleted", "restored"] as const;
+
+type EntitySubscriber = {
+  readonly entityName: string;
+  readonly listener: (event: LiveEvent) => void;
+};
+
+export type CreateEventSourceLiveEventsOptions = {
+  /** URL des SSE-Endpoints. Default: /api/sse (das ist wo
+   *  createSseRoute im Kumiko-Server mountet). Override wenn der
+   *  Mountpath divergiert. */
+  readonly url?: string;
+};
+
+/** Liefert einen `LiveEventSubscriber` der EventSource-backed ist.
+ *  Normalerweise einmal im App-Bootstrap gerufen und als value an
+ *  `<LiveEventsProvider>` durchgereicht — createKumikoApp tut das. */
+export function createEventSourceLiveEvents(
+  options: CreateEventSourceLiveEventsOptions = {},
+): LiveEventSubscriber {
+  const url = options.url ?? "/api/sse";
+
+  const subscribers = new Set<EntitySubscriber>();
+  let source: EventSource | undefined;
+  const wiredTypes = new Set<string>();
+
+  const handleEvent = (type: string, raw: string): void => {
+    let parsed: LiveEvent["data"];
+    try {
+      parsed = JSON.parse(raw) as LiveEvent["data"];
+    } catch {
+      // Malformed payload — drop it. Besser als einen fangenden Listener
+      // zu crashen und alle anderen subscribers mitzureißen.
+      return;
+    }
+    const event: LiveEvent = { type, data: parsed };
+    for (const sub of subscribers) {
+      if (sub.entityName === parsed.aggregateType) sub.listener(event);
+    }
+  };
+
+  const ensureConnected = (): void => {
+    if (source !== undefined) return;
+    if (typeof window === "undefined" || typeof EventSource === "undefined") return;
+    source = new EventSource(url);
+  };
+
+  const ensureListenersForEntity = (entityName: string): void => {
+    if (source === undefined) return;
+    for (const verb of VERBS) {
+      const type = `${entityName}.${verb}`;
+      if (wiredTypes.has(type)) continue;
+      source.addEventListener(type, (e) => {
+        handleEvent(type, (e as MessageEvent).data);
+      });
+      wiredTypes.add(type);
+    }
+  };
+
+  const closeIfEmpty = (): void => {
+    if (subscribers.size > 0) return;
+    if (source === undefined) return;
+    source.close();
+    source = undefined;
+    wiredTypes.clear();
+  };
+
+  return (entityName, listener) => {
+    ensureConnected();
+    ensureListenersForEntity(entityName);
+    const sub: EntitySubscriber = { entityName, listener };
+    subscribers.add(sub);
+    return () => {
+      subscribers.delete(sub);
+      closeIfEmpty();
+    };
+  };
+}

package/src/styles.css

@@ -0,0 +1,113 @@
+/* Tailwind v4 + shadcn-Token-Schema. Die :root + .dark Blocks
+   halten die Design-Tokens als CSS-Variablen. Theme-Toggle =
+   `document.documentElement.classList.toggle("dark")` — keine
+   JS-State-Management-Pipeline nötig.
+
+   Tokens-Namen folgen der shadcn-Konvention (background/foreground/
+   primary/secondary/muted/accent/destructive/border/input/ring).
+   Werte sind HSL-triplets ohne hsl() wrapper, damit Tailwind-
+   Klassen wie `bg-primary` direkt funktionieren.
+*/
+
+@import "tailwindcss";
+
+/* react-day-picker v9 liefert seine Struktur-CSS separat (kein bundled
+   Default mehr seit v9). Ohne diesen Import bricht das Calendar-Layout
+   — Wochen rutschen ineinander, weil rdp den table-Reset (border-
+   collapse, cell-Geometrie) extern hält. Unsere classNames-Map in
+   `date-input.tsx` überschreibt nur Slot-Tokens, die strukturellen
+   Defaults bleiben rdp's eigenes Stylesheet. */
+@import "react-day-picker/style.css";
+
+/* Tailwind v4 scannt per default vom Import-Ort aus; da das CSS
+   aus einem temp-dir kompiliert wird, findet es sonst keine
+   Source-Dateien. Explizite @source-Direktiven decken alle
+   Workspace-Sources ab — der CLI scannt dann unsere Primitives,
+   Layout-Components UND die Sample-App. */
+@source "../../renderer-web/src/**/*.{ts,tsx}";
+@source "../../renderer/src/**/*.{ts,tsx}";
+@source "../../../samples/**/src/**/*.{ts,tsx}";
+
+/* Dark-Mode via class-selector (nicht media). Erlaubt JS-Toggle
+   und überschreibt System-Preference wenn die App will. */
+@custom-variant dark (&:where(.dark, .dark *));
+
+@theme {
+  /* Dark-Mode (Default) — Linear-Style: blau-graues Background statt
+     pures Schwarz. background <-> card haben minimal-Distinction
+     (1-2% lightness shift) damit Cards subtle "schweben" ohne harte
+     Borders. Primary ist das Linear-Brand-Purple (~#5e6ad2). */
+  --color-background: hsl(220 13% 9%);
+  --color-foreground: hsl(220 14% 96%);
+  --color-card: hsl(220 13% 11%);
+  --color-card-foreground: hsl(220 14% 96%);
+  --color-popover: hsl(220 13% 11%);
+  --color-popover-foreground: hsl(220 14% 96%);
+  --color-primary: hsl(232 60% 64%);
+  --color-primary-foreground: hsl(0 0% 100%);
+  --color-secondary: hsl(220 13% 16%);
+  --color-secondary-foreground: hsl(220 14% 96%);
+  --color-muted: hsl(220 13% 14%);
+  --color-muted-foreground: hsl(220 8% 56%);
+  --color-accent: hsl(220 13% 16%);
+  --color-accent-foreground: hsl(220 14% 96%);
+  --color-destructive: hsl(0 75% 58%);
+  --color-destructive-foreground: hsl(0 0% 100%);
+  --color-border: hsl(220 13% 18%);
+  --color-input: hsl(220 13% 16%);
+  --color-ring: hsl(232 60% 64%);
+
+  /* Radius-Skala: Linear hat größere Radii — Cards/Modals 10-12px,
+     Buttons/Inputs 6-8px, Pills voll. */
+  --radius-sm: 0.25rem;
+  --radius-md: 0.375rem;
+  --radius-lg: 0.5rem;
+  --radius-xl: 0.75rem;
+}
+
+/* Light-Mode-Overrides — aktiv wenn `<html>` KEINE `.dark` Klasse
+   hat. Dark ist der Default (siehe @theme oben); toggled der User
+   auf light, greifen diese Werte. */
+@layer base {
+  :root:not(.dark) {
+    /* Light-Mode — Linear-Style: warmes weiß-grau Background, Cards
+       leicht heller. Primary bleibt Brand-Purple (gleicher hue wie
+       dark, höhere saturation für Kontrast auf weiß). Borders sehr
+       dezent (rgba-style alpha statt full grey-200). */
+    --color-background: hsl(0 0% 100%);
+    --color-foreground: hsl(220 14% 14%);
+    --color-card: hsl(0 0% 100%);
+    --color-card-foreground: hsl(220 14% 14%);
+    --color-popover: hsl(0 0% 100%);
+    --color-popover-foreground: hsl(220 14% 14%);
+    --color-primary: hsl(232 60% 58%);
+    --color-primary-foreground: hsl(0 0% 100%);
+    --color-secondary: hsl(220 14% 96%);
+    --color-secondary-foreground: hsl(220 14% 14%);
+    --color-muted: hsl(220 14% 97%);
+    --color-muted-foreground: hsl(220 8% 46%);
+    --color-accent: hsl(220 14% 96%);
+    --color-accent-foreground: hsl(220 14% 14%);
+    --color-destructive: hsl(0 72% 51%);
+    --color-destructive-foreground: hsl(0 0% 100%);
+    --color-border: hsl(220 14% 92%);
+    --color-input: hsl(220 14% 92%);
+    --color-ring: hsl(232 60% 58%);
+  }
+
+  * {
+    border-color: var(--color-border);
+  }
+
+  body {
+    background-color: var(--color-background);
+    color: var(--color-foreground);
+    font-family:
+      -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+    font-size: 14px;
+    line-height: 1.5;
+    margin: 0;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+}

package/src/tokens.ts

@@ -0,0 +1,63 @@
+import { createStore } from "@cosmicdrift/kumiko-headless";
+import {
+  cssVarTokens,
+  type ThemeMode,
+  type Tokens,
+  type TokensApi,
+} from "@cosmicdrift/kumiko-renderer";
+import { useSyncExternalStore } from "react";
+
+// Web-spezifische TokensApi-Impl. Theme-Toggle via `.dark`-Class auf
+// <html>. Die echten Farben leben in styles.css; hier ist nur die
+// JS-Seite die den class-switch triggert und React-Consumer mit
+// useSyncExternalStore darüber informiert.
+//
+// Source-of-truth ist der DOM (`<html class="dark">`); der Store ist
+// reiner Notification-Bus (Tick-Counter), den setMode/toggleMode bei
+// jedem Class-Wechsel hochzählen. So bleibt die DOM-Klasse die einzige
+// Wahrheit — readCurrentMode liest sie frisch bei jedem getSnapshot.
+
+const themeTick = createStore(0);
+
+function readCurrentMode(): ThemeMode {
+  if (typeof document === "undefined") return "dark";
+  return document.documentElement.classList.contains("dark") ? "dark" : "light";
+}
+
+function notifyThemeChange(): void {
+  themeTick.setState((t) => t + 1);
+}
+
+/** Hook der eine TokensApi für den Browser baut. Wird von
+ *  createKumikoApp genutzt; App-Code der einen eigenen Token-State
+ *  braucht (z.B. User-Präferenz aus localStorage) kann selber
+ *  `<TokensProvider value={...}>` mounten. */
+export function useBrowserTokensApi(): TokensApi {
+  const mode = useSyncExternalStore(themeTick.subscribe, readCurrentMode, () => "dark" as const);
+  return {
+    tokens: cssVarTokens,
+    mode,
+    setMode: (next) => {
+      if (typeof document === "undefined") return;
+      document.documentElement.classList.toggle("dark", next === "dark");
+      notifyThemeChange();
+    },
+    toggleMode: () => {
+      if (typeof document === "undefined") return;
+      document.documentElement.classList.toggle("dark");
+      notifyThemeChange();
+    },
+  };
+}
+
+/** Default-Tokens — identisch zu `cssVarTokens` (var-string-refs).
+ *  Light- und Dark-Werte switchen via `.dark`-class auf <html>. */
+export const defaultTokens: Tokens = cssVarTokens;
+export const lightTokens: Tokens = cssVarTokens;
+
+/** Historisch: schrieb Tokens auf :root als CSS-vars. Jetzt no-op —
+ *  die CSS-vars leben in styles.css, nicht in JS. Bleibt als Export
+ *  damit alter App-Code nicht bricht. */
+export function applyTokensToCssVars(_tokens: Tokens): void {
+  // Absichtlich leer — siehe Kommentar oben.
+}