@cosmicdrift/kumiko-samples 0.385.0 → 0.387.0

package/packages/bundled-features/src/auth-email-password/web/auth-client.ts

@@ -1,12 +1,11 @@
-// Browser-Seite der Auth-Routes. Dünne fetch-Wrapper um /api/auth/*
-// mit Cookie-Transport: JWT lebt im HttpOnly kumiko_auth-Cookie,
-// Double-Submit-CSRF-Token im JS-lesbaren kumiko_csrf-Cookie. Alle
-// state-changing Requests echo'n den CSRF-Token via X-CSRF-Token —
-// der Server rejected sonst mit csrf_token_missing.
+// Browser-side wrappers around /api/auth/* using cookie transport: the JWT
+// lives in the HttpOnly kumiko_auth cookie, while the Double-Submit CSRF
+// token lives in the JS-readable kumiko_csrf cookie. Every state-changing
+// request echoes the CSRF token via X-CSRF-Token; otherwise the server
+// rejects it with csrf_token_missing.
 //
-// Die dispatcher-live nutzt denselben readCsrfToken-Helper; wir
-// reuse'n ihn hier, damit die Konstanten (Cookie-Name, Header-Name)
-// nicht divergieren.
+// dispatcher-live uses the same readCsrfToken helper; reusing it here keeps
+// the cookie and header constants from diverging.
 
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
 import { CSRF_HEADER_NAME, readCsrfToken } from "@cosmicdrift/kumiko-renderer/live";
@@ -14,8 +13,8 @@ import { CSRF_HEADER_NAME, readCsrfToken } from "@cosmicdrift/kumiko-renderer/li
 export type TenantSummary = {
   readonly tenantId: string;
   readonly roles: readonly string[];
-  /** Display-Name aus /auth/tenants — fehlt nur bei App-eigenen
-   *  membership-Queries ohne tenantName-Anreicherung. */
+  /** Display name from /auth/tenants; absent only for app-owned membership
+   * queries without tenantName enrichment. */
   readonly name?: string;
   readonly key?: string;
 };
@@ -154,8 +153,8 @@ export async function login(req: LoginRequest): Promise<LoginResult> {
       return { kind: "success", data: toLoginResponse(body.token, body.user, body.landingPath) };
     }
   }
-  // Der Server schickt error entweder als string ("invalid_body") oder als
-  // strukturiertes Objekt. Wir ziehen uns den sprechendsten Reason raus.
+  // The server sends error either as a string ("invalid_body") or as a
+  // structured object. Extract the most descriptive reason.
   const err = body.error;
   if (typeof err === "string") {
     return { kind: "failure", error: { reason: err } };
@@ -172,10 +171,10 @@ export async function login(req: LoginRequest): Promise<LoginResult> {
   };
 }
 
-// POST /api/auth/logout. Server revoked die Session (wenn sessionRevoker
-// gewired ist) und clear't die Cookies. Wir triggern hinterher einen
-// Navigation-Refresh, damit alle caches (React-State, query-cache) auf
-// Null gehen — billigster Weg zu sauberer Ausgangslage.
+// POST /api/auth/logout. The server revokes the session when
+// sessionRevoker is wired and clears the cookies. A navigation refresh
+// afterward ensures that all caches (React state, query cache) return to
+// an unauthenticated state—the simplest way to restore a clean baseline.
 export async function logout(): Promise<void> {
   await fetch("/api/auth/logout", {
     method: "POST",
@@ -184,29 +183,29 @@ export async function logout(): Promise<void> {
   });
 }
 
-// Gemeinsamer Failure-Type für die vier Token-Flow-Endpoints (request-
+// Shared failure type for the four token-flow endpoints (request-
 // password-reset, reset-password, request-email-verification, verify-
-// email). Server collapses alle Token-Verify-Fehler (malformed / bad-
-// signature / expired) auf einen einzigen Code pro Flow (anti-
-// enumeration); UI mappt reason → i18n-Key. Plus rate-limit (429) wird
-// als reason "rate_limited" + retryAfterSeconds durchgereicht — gleiche
-// Shape wie LoginFailure damit Apps die Errors uniform mappen können.
+// email). The server collapses all token-verification errors (malformed,
+// bad signature, expired) into one code per flow to prevent enumeration;
+// the UI maps reason to an i18n key. Rate limits (429) pass through as
+// reason "rate_limited" with retryAfterSeconds, using the same shape as
+// LoginFailure so apps can map errors uniformly.
 export type AuthTokenFailure = {
   readonly reason: string;
   readonly retryAfterSeconds?: number;
 };
 
-// Backward-compat-Aliase für die alten Type-Namen — damit Code, der
-// `ResetPasswordFailure` / `VerifyEmailFailure` importiert hat, ohne
-// Änderung weiterläuft. Für neuen Code direkt `AuthTokenFailure` nutzen.
+// Backward-compatible aliases for the old type names, so code importing
+// `ResetPasswordFailure` or `VerifyEmailFailure` continues to work without
+// changes. New code should use `AuthTokenFailure` directly.
 export type ResetPasswordFailure = AuthTokenFailure;
 export type VerifyEmailFailure = AuthTokenFailure;
 
-// 4xx/5xx → typed AuthTokenFailure parsen. 429 (Rate-Limit) hat einen
-// dedizierten reason damit das UI einen Retry-Hinweis zeigen kann.
+// Parse 4xx/5xx responses into AuthTokenFailure. 429 uses a dedicated
+// reason so the UI can display a retry hint.
 async function parseTokenFailure(res: Response): Promise<AuthTokenFailure> {
   if (res.status === 429) {
-    // @cast-boundary engine-payload — server schickt details.retryAfterSeconds bei 429
+    // @cast-boundary engine-payload — the server sends details.retryAfterSeconds for 429
     const body = (await res.json().catch(() => ({}))) as {
       error?: { details?: { retryAfterSeconds?: number } };
     };
@@ -238,11 +237,12 @@ export async function requestPasswordReset(
   return { ok: false, error: await parseTokenFailure(res) };
 }
 
-// POST /api/auth/reset-password. Token aus URL + neues Passwort. Auf
-// 422 collapses der Server alle Token-Verify-Fehler (malformed / bad-
-// signature / expired) auf den einzigen Code `invalid_reset_token` —
-// anti-enumeration. Plus zod-validation-failures (newPassword < 8) als
-// eigene 4xx mit code "validation_failed". UI mappt reason → i18n-Key.
+// POST /api/auth/reset-password. The token comes from the URL and the
+// request includes the new password. On 422, the server collapses all
+// token-verification errors (malformed, bad signature, expired) into the
+// single code `invalid_reset_token` to prevent enumeration. Zod validation
+// failures (newPassword < 8) use a separate 4xx code, "validation_failed".
+// The UI maps reason to an i18n key.
 export async function resetPassword(
   token: string,
   newPassword: string,
@@ -272,9 +272,9 @@ export async function requestEmailVerification(
   return { ok: false, error: await parseTokenFailure(res) };
 }
 
-// POST /api/auth/verify-email. Auto-submitted vom VerifyEmailScreen
-// nach `?token=...`-parse. Server collapses alle Verify-Failures auf
-// `invalid_verification_token` (anti-enumeration, parallel zu reset).
+// POST /api/auth/verify-email. VerifyEmailScreen submits this automatically
+// after parsing `?token=...`. The server collapses all verification failures
+// into `invalid_verification_token` to prevent enumeration, as with reset.
 export async function verifyEmail(
   token: string,
 ): Promise<{ ok: true } | { ok: false; error: AuthTokenFailure }> {
@@ -321,15 +321,14 @@ export async function confirmAccountUnlock(
   return { ok: false, error: await parseTokenFailure(res) };
 }
 
-// POST /api/auth/signup-request. Always-200 (anti-enumeration; wir
-// sagen nicht ob die Email schon registriert ist). Server schickt
-// Activation-Mail an die Adresse — beim Klick auf den Link landet der
-// User auf /signup/complete?token=… wo er sein Password setzt.
+// POST /api/auth/signup-request. Always returns 200 to prevent enumeration;
+// the response does not reveal whether the email is already registered. The
+// server sends an activation email to the address; following its link takes
+// the user to /signup/complete?token=… to set a password.
 export async function requestSignup(
   email: string,
-  // Cross-device try-first handover (kumiko-framework#3035 follow-up,
-  // offlot-app#454): forwards a row-bound tenant-handover grant so the
-  // server can verify + rebind it to the signup token. The grant never
+  // Cross-device try-first handover: forwards a row-bound tenant-handover
+  // grant so the server can verify + rebind it to the signup token. The grant never
   // travels any further than this request — never in the URL, the mail,
   // or the confirm response.
   handover?: { readonly entityType: string; readonly token: string },
@@ -397,8 +396,8 @@ export async function confirmSignup(
   return { ok: false, error: await parseTokenFailure(res) };
 }
 
-// GET /api/auth/tenants. Liefert die Memberships des aktuellen Users;
-// der Server liefert 401 wenn das Cookie fehlt oder abgelaufen ist.
+// GET /api/auth/tenants. Returns the current user's memberships; the server
+// returns 401 when the cookie is missing or expired.
 export async function fetchTenants(): Promise<{
   readonly tenants: readonly TenantSummary[];
   readonly activeTenantId: string;
@@ -422,9 +421,9 @@ export async function fetchTenants(): Promise<{
   };
 }
 
-// POST /api/auth/switch-tenant. Mintet ein neues JWT für den Ziel-Tenant
-// und rotated beide Cookies. 400 wenn already_in_tenant oder tenant_
-// switch_not_available, 403 wenn not_a_member.
+// POST /api/auth/switch-tenant. Mints a new JWT for the target tenant and
+// rotates both cookies. Returns 400 for already_in_tenant or
+// tenant_switch_not_available, and 403 for not_a_member.
 export async function switchTenant(tenantId: string): Promise<void> {
   const res = await fetch("/api/auth/switch-tenant", {
     method: "POST",
@@ -438,14 +437,15 @@ export async function switchTenant(tenantId: string): Promise<void> {
   }
 }
 
-// POST /api/query → user:query:user:me. Profil-Daten (email, displayName)
-// für das UserMenu im Topbar. 401 → kein Cookie / abgelaufen, wird
-// vom SessionProvider als "ausgeloggt" interpretiert.
+// POST /api/query → user:query:user:me. Returns profile data (email,
+// displayName) for the UserMenu in the top bar. A 401 for a missing or
+// expired cookie is interpreted by SessionProvider as signed out.
 //
-// globalRoles: tenant-unabhängige user-rollen (z.B. SystemAdmin) aus
-// users.roles. Im JWT schon mit tenant-membership-roles gemerged, aber
-// das JWT ist HttpOnly + nicht JS-lesbar — der Client muss die globalen
-// Rollen separat aus dem user-row holen damit nav-filtering greift.
+// globalRoles are tenant-independent user roles (for example, SystemAdmin)
+// from users.roles. They are merged into the JWT with tenant-membership
+// roles, but the JWT is HttpOnly and unreadable by JavaScript, so the client
+// must fetch the global roles separately from the user row for navigation
+// filtering.
 export type CurrentUserProfile = {
   readonly id: string;
   readonly email: string;
@@ -479,8 +479,8 @@ export async function fetchCurrentUser(): Promise<CurrentUserProfile | null> {
       displayName: string;
       locale?: string;
       effectiveTimeZone?: string;
-      // JSON-encoded string[] — siehe userEntity.roles. Default "[]" wenn
-      // keine globalen Rollen.
+      // JSON-encoded string[]; see userEntity.roles. Defaults to "[]" when
+      // there are no global roles.
       roles?: string;
     };
   };

package/packages/bundled-features/src/auth-email-password/web/auth-form-primitives.tsx

@@ -14,10 +14,10 @@ import { usePrimitives } from "@cosmicdrift/kumiko-renderer";
 import { BareFormProvider, cn } from "@cosmicdrift/kumiko-renderer/web";
 import { createContext, type ReactNode, useContext, useEffect, useState } from "react";
 
-// Wrappt die zentrierte Auth-Card in ihre Umgebung. Default = Fullscreen-
-// zentriert (Standalone-Auth-Page). Eine Apex-/Marketing-Chrome reicht über
-// AuthShellProvider eine eigene Variante rein, ohne dass `min-h-screen` die
-// Chrome übermalt.
+// Wraps the centered auth card in its surrounding layout. The default is
+// fullscreen-centered for standalone auth pages. Apex/marketing chrome can
+// provide its own variant through AuthShellProvider without `min-h-screen`
+// covering that chrome.
 export type AuthShellRenderer = (card: ReactNode) => ReactNode;
 
 const defaultAuthShell: AuthShellRenderer = (card) => (
@@ -64,8 +64,9 @@ export function AuthCard({
 }: AuthCardProps): ReactNode {
   const { Card } = usePrimitives();
   const shell = useAuthShell() ?? defaultAuthShell;
-  // h1 (Seiten-Hauptüberschrift) via Header-Slot erhalten — die Card-Default-
-  // Header wäre h3. padded:false = Form sitzt randlos wie bisher (bare form).
+  // Keep an h1 (page heading) through the header slot; the Card's default
+  // header would be h3. padded:false keeps the form edge-to-edge as before
+  // (bare form).
   const card = (
     <Card
       className={cn("w-full max-w-sm", className)}
@@ -94,14 +95,13 @@ export function AuthCard({
   return shell(card);
 }
 
-// Liest `?<paramName>=<value>` aus der aktuellen URL — typisches
-// Pattern für Token-bearing Pages (reset, verify). Returnt "" wenn der
-// Browser nicht da ist (SSR-safety) oder der Parameter fehlt.
+// Reads `?<paramName>=<value>` from the current URL, as used by token-bearing
+// pages (reset, verify). Returns "" during SSR or when the parameter is absent.
 //
-// Nicht über useState/useEffect - das wäre ein read-once-on-mount
-// pattern aber URL-changes sind hier irrelevant (Token-Pages re-loaden
-// für neue Tokens). Caller setzt useState(() => parseUrlToken(...)) wenn
-// gewünscht.
+// This is intentionally not read through useState/useEffect: that would be a
+// read-once-on-mount pattern, while URL changes are irrelevant here because
+// token pages reload for new tokens. Callers can use
+// useState(() => parseUrlToken(...)) when needed.
 export function parseUrlToken(paramName = "token"): string {
   if (typeof window === "undefined") return "";
   return new URLSearchParams(window.location.search).get(paramName) ?? "";
@@ -109,7 +109,7 @@ export function parseUrlToken(paramName = "token"): string {
 
 // Reads the magic-link token from `?<paramName>=` once on mount, then strips
 // that param from the URL via history.replaceState so the single-use token
-// doesn't linger in browser history / Referer (#774). An explicit `override`
+// doesn't linger in browser history / Referer. An explicit `override`
 // (server-injected token) short-circuits both the URL read and the scrub.
 export function useUrlToken(override?: string, paramName = "token"): string {
   const [token] = useState(() => override ?? parseUrlToken(paramName));

package/packages/bundled-features/src/auth-email-password/web/auth-gate.tsx

@@ -1,12 +1,12 @@
-// Auth-Gate: rendert den LoginScreen solange der Session-Status
-// "unauthenticated" ist, sonst die Kinder. "loading" zeigt einen
-// minimalen Placeholder — die initiale Refresh-Runde liefert in der
-// Regel in <100ms, also kein Spinner-Overkill.
+// Auth gate: renders the LoginScreen while the session status is
+// "unauthenticated" and the children otherwise. "loading" shows a
+// minimal placeholder—the initial refresh usually completes in <100ms,
+// so a spinner would be excessive.
 //
-// Die Factory makeAuthGate schließt die LoginScreen-Komponente in,
-// damit das Gate der ClientFeatureDefinition-Signatur entspricht
-// (nur `{ children }`-Prop). Der Sample kann so einen eigenen Login-
-// Screen rein konfigurieren, ohne den Gate selbst ersetzen zu müssen.
+// The makeAuthGate factory closes over the LoginScreen component so the
+// gate matches the ClientFeatureDefinition signature (only a `{ children }`
+// prop). This lets the sample configure a custom login screen without
+// replacing the gate.
 
 import { useLocale } from "@cosmicdrift/kumiko-renderer";
 import { type ComponentType, type ReactNode, useEffect, useMemo, useState } from "react";
@@ -57,12 +57,11 @@ export type LoginRouteOptions = {
 // their own standalone login route outside any gate (createPublicSurface
 // apex pages stack providers, not gates — see auth-mount.tsx recipes).
 // Handing an app raw LoginScreen + telling it to hand-roll the challenge-
-// token swap itself is exactly how kumiko-framework#266's login-time MFA
-// step went missing in a real apex surface; this prevents the *most common*
-// version of that mistake. MFA still only actually works once a consumer
-// wires `mfaVerifyScreen` — omitting it is a silent no-MFA fallback, not
-// something this route can catch on its own (auth-mfa is a separate,
-// optional package).
+// token swap itself is exactly how the login-time MFA step went missing in a
+// real apex surface; this prevents the *most common* version of that mistake.
+// MFA still only actually works once a consumer wires `mfaVerifyScreen` —
+// omitting it is a silent no-MFA fallback, not something this route can catch
+// on its own (auth-mfa is a separate, optional package).
 export function createLoginRoute(
   opts: LoginRouteOptions = {},
 ): ComponentType<Record<string, never>> {
@@ -82,7 +81,7 @@ export function createLoginRoute(
       readonly accountLabel: string;
     } | null>(null);
 
-    // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
+    // kumiko-lint-ignore no-raw-hooks not yet converted to the framework hook set
     useEffect(() => {
       if (status === "authenticated") onAuthenticated?.();
     }, [status]);
@@ -236,7 +235,7 @@ export function makeAuthGate(opts: AuthGateOptions = {}): ComponentType<{
       [status, locale, origin, pathname, search, hash],
     );
     const redirectUrl = loginRedirect?.kind === "redirect" ? loginRedirect.url : null;
-    // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
+    // kumiko-lint-ignore no-raw-hooks not yet converted to the framework hook set
     useEffect(() => {
       if (redirectUrl !== null) window.location.replace(redirectUrl);
     }, [redirectUrl]);

package/packages/bundled-features/src/auth-email-password/web/client-plugin.ts

@@ -1,8 +1,7 @@
-// Client-Feature-Factory für auth-email-password. Wird vom App-Code
-// in createKumikoApp({ clientFeatures: [emailPasswordClient()] })
-// eingehängt und bringt Session-Context + AuthGate + Default-UI-
-// Translations (de/en) mit. Alles ist overridbar — Login-Screen,
-// Strings pro Locale, pro Key.
+// Client feature factory for auth-email-password. App code mounts it in
+// createKumikoApp({ clientFeatures: [emailPasswordClient()] }) to provide
+// session context, AuthGate, and default UI translations (de/en). All of
+// these can be overridden: the login screen and strings per locale and key.
 
 import type { ClientActionHandler, TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
 import type { ComponentType, ReactNode } from "react";
@@ -18,9 +17,9 @@ import { defaultTranslations, mergeTranslations } from "./i18n.ts";
 import type { LoginScreenProps } from "./login-screen.tsx";
 
 export type EmailPasswordClientOptions = {
-  /** Eigener Login-Screen. Default: der shadcn-stylte LoginScreen
-   *  aus diesem Modul. Für Branding- oder Layout-Overrides einfach
-   *  eine eigene Komponente mit derselben Signatur reichen. */
+  /** Custom login screen. Default: the shadcn-styled LoginScreen
+   *  from this module. Provide a component with the same signature for
+   *  branding or layout overrides. */
   readonly loginScreen?: ComponentType<LoginScreenProps>;
   readonly loginScreenProps?: LoginScreenProps;
   /** auth-mfa's MfaVerifyScreen, wired in from the app so this feature
@@ -41,10 +40,10 @@ export type EmailPasswordClientOptions = {
   readonly loginUrl?: AuthGateOptions["loginUrl"];
   /** Where logout navigates to (root-relative path or http(s) URL). Default: reload. */
   readonly postLogoutUrl?: string;
-  /** Key-Overrides pro Locale. Wird mit den Default-Bundles (de/en)
-   *  aus `translations.ts` gemerged — jeder hier gesetzte Key gewinnt.
-   *  Für Branding ("Sign in" → "Login to Acme") oder weitere Sprachen
-   *  (`fr`, `es`, …) zusätzlich. */
+  /** Per-locale key overrides. Merged with the default bundles (de/en)
+   *  from `translations.ts`; each key supplied here takes precedence.
+   *  Use this for branding ("Sign in" → "Login to Acme") or to add
+   *  further languages (`fr`, `es`, …). */
   readonly translations?: TranslationsByLocale;
   /** Serve the forgot-password, reset-password and unlock-account pages at
    *  their convention paths for signed-out visitors. Apps with their own

package/packages/bundled-features/src/auth-email-password/web/confirm-account-unlock-screen.tsx

@@ -32,7 +32,7 @@ export function ConfirmAccountUnlockScreen({
   const [status, setStatus] = useState<Status>(token === "" ? "missing-token" : "verifying");
   const startedRef = useRef(false);
 
-  // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
+  // kumiko-lint-ignore no-raw-hooks not yet converted to the framework hook set
   useEffect(() => {
     if (status !== "verifying") return;
     if (startedRef.current) return;

package/packages/bundled-features/src/auth-email-password/web/constants.ts

@@ -17,7 +17,7 @@ export const AuthHandlers = {
   requestEmailVerification: "auth-email-password:write:request-email-verification",
   verifyEmail: "auth-email-password:write:verify-email",
   // Account-Unlock Magic-Link (fixes the lockout-DoS where the monotonic
-  // failure-counter re-locks immediately after expiry, #1266). Mirrors
+  // failure-counter re-locks immediately after expiry). Mirrors
   // reset: request mints an HMAC token + mails it, confirm clears the
   // Redis lockout state.
   requestAccountUnlock: "auth-email-password:write:request-account-unlock",
@@ -85,7 +85,7 @@ export const AuthErrors = {
   invalidSignupToken: "invalid_signup_token",
   signupNotConfigured: "signup_not_configured",
   // Self-signup: confirm rejects an already-registered email instead of
-  // reusing the existing user (account takeover, #365). NO
+  // reusing the existing user (account takeover). NO
   // anti-enumeration collapse like invalidSignupToken: whoever gets here
   // controls the inbox (has the magic link), so revealing "email exists"
   // is not new information.
@@ -105,7 +105,7 @@ export const AuthErrors = {
   // deliberate enumeration trade-off: the lockout event itself is already
   // observable to the attacker, and legit users benefit from a clear signal.
   accountLocked: "account_locked",
-  // S2.U6 (GDPR Art. 18) — account is in Restricted status. Login is
+  // (GDPR Art. 18) — account is in Restricted status. Login is
   // explicitly refused with its own code (not collapsed into
   // invalid_credentials) so the UI can say "account is currently paused,
   // click here to lift it". Enumeration leak accepted: restriction is

package/packages/bundled-features/src/auth-email-password/web/default-topbar-actions.tsx

@@ -1,9 +1,9 @@
-// Standard-Topbar-Actions Komposition für Apps mit Auth + Workspaces.
-// Bündelt das Pattern das jeder App-Sample sonst hand-ausschreibt:
-// TenantSwitcher (links) → optional Extras (z.B. LanguageSwitcher) →
-// ThemeToggle → UserMenu (rechts). Apps mit eigener Anordnung
-// importieren weiter die Einzelkomponenten direkt — DefaultTopbarActions
-// ist Convenience, kein Muss.
+// Composes the standard top-bar actions for apps with auth and workspaces.
+// This bundles the pattern that each app sample would otherwise write by hand:
+// TenantSwitcher (left) → optional extras (for example, LanguageSwitcher) →
+// ThemeToggle → UserMenu (right). Apps with a custom arrangement can still
+// import the individual components directly; DefaultTopbarActions is
+// convenience, not a requirement.
 
 import { ThemeToggle } from "@cosmicdrift/kumiko-renderer/web";
 import type { ReactNode } from "react";
@@ -11,16 +11,16 @@ import { TenantSwitcher } from "./tenant-switcher.tsx";
 import { UserMenu } from "./user-menu.tsx";
 
 export type DefaultTopbarActionsProps = {
-  /** Mapped Tenant-ID auf einen sprechenden Namen (z.B. branded label
-   *  pro Tenant). TenantSwitcher's Default zeigt sonst die ersten 8
-   *  Zeichen der UUID. */
+  /** Maps a tenant ID to a human-readable name (for example, a branded label
+   *  per tenant). TenantSwitcher's default otherwise displays the first 8
+   *  characters of the UUID. */
   readonly tenantName?: (tenantId: string) => string;
-  /** Slot zwischen TenantSwitcher und ThemeToggle. Typischer Use-Case:
-   *  LanguageSwitcher pro App. ReactNode (nicht Array) damit die App
-   *  selbst Reihenfolge + Spacing bestimmt. */
+  /** Slot between TenantSwitcher and ThemeToggle. Typical use case:
+   *  an app-specific LanguageSwitcher. ReactNode, rather than an array, so the
+   *  app controls the ordering and spacing. */
   readonly extras?: ReactNode;
-  /** Light-Mode-Icon im ThemeToggle. Default: Unicode ☀. Apps die
-   *  Lucide-Icons o.ä. wollen, übergeben ein eigenes Icon-Element. */
+  /** Light-mode icon for ThemeToggle. Default: Unicode ☀. Apps that want
+   *  Lucide icons or similar can provide a custom icon element. */
   readonly lightIcon?: ReactNode;
   /** Dark-Mode-Icon. Default: Unicode ☾. */
   readonly darkIcon?: ReactNode;

package/packages/bundled-features/src/auth-email-password/web/forgot-password-screen.tsx

@@ -1,12 +1,12 @@
-// ForgotPasswordScreen — Form mit email-input. Submit triggert
-// /api/auth/request-password-reset (silent-success, kein account-
-// enumeration). UI zeigt unconditional ein "Wenn Account existiert,
-// Mail unterwegs"-Confirm — auch wenn der Server intern erkannt hat
-// dass die Email nicht existiert.
+// ForgotPasswordScreen — form with an email input. Submission triggers
+// /api/auth/request-password-reset (silent success, no account enumeration).
+// The UI always shows a "If an account exists, the email is on its way"
+// confirmation, even when the server determines internally that the email
+// does not exist.
 //
-// App ist verantwortlich, den Screen unter einer URL zu mounten (z.B.
-// /forgot-password) und ihn zu erreichen — der LoginScreen kann einen
-// "Passwort vergessen?"-Link auf die App-Route setzen.
+// The app is responsible for mounting and exposing the screen at a URL
+// (for example, /forgot-password); the LoginScreen can link to that app
+// route with a "Forgot password?" link.
 
 import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { type FormEvent, type ReactNode, useState } from "react";
@@ -16,8 +16,8 @@ import { AuthCard } from "./auth-form-primitives.tsx";
 export type ForgotPasswordScreenProps = {
   readonly title?: string;
   readonly subtitle?: ReactNode;
-  /** href für den "Zurück zum Login"-Link in success + form. App-
-   *  spezifisch — Default "/login". */
+  /** href for the "Back to login" link in the success and form states. App-
+   * specific — defaults to "/login". */
   readonly loginHref?: string;
 };
 
@@ -33,7 +33,7 @@ export function ForgotPasswordScreen({
   const [done, setDone] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
-  // guard:dup-ok — gleiches Submit-Muster wie signup-screen, aber verschiedene API-Endpoints und State
+  // guard:dup-ok — same submission pattern as signup-screen, but with different API endpoints and state
   const doSubmit = async (): Promise<void> => {
     setSubmitting(true);
     setError(null);

package/packages/bundled-features/src/auth-email-password/web/index.ts

@@ -1,8 +1,8 @@
-// Public exports für die Browser-Seite des auth-email-password Features.
-// Wird über den Sub-Path-Export `@cosmicdrift/kumiko-bundled-features/auth-email-
-// password/web` konsumiert — die Server-Seite (defineFeature) lebt in
-// `@cosmicdrift/kumiko-bundled-features/auth-email-password` und hat keine
-// React-/DOM-Deps. Trennung bleibt sauber so wie renderer vs renderer/web.
+// Public exports for the browser side of the auth-email-password feature.
+// Consumed through the subpath export `@cosmicdrift/kumiko-bundled-features/auth-email-
+// password/web`; the server side (defineFeature) lives in
+// `@cosmicdrift/kumiko-bundled-features/auth-email-password` and has no
+// React-/DOM dependencies. This keeps the separation clean, like renderer vs renderer/web.
 
 export type {
   AuthTokenFailure,

package/packages/bundled-features/src/auth-email-password/web/invite-accept-screen.tsx

@@ -1,19 +1,19 @@
-// InviteAcceptScreen — Magic-Link-Accept für Tenant-Invitations.
+// InviteAcceptScreen — accepts tenant invitations through a magic link.
 //
-// Liest `?token=...` aus der URL und branched intern je nach session-state:
-//   - Logged-in + Email-Match: 1-click accept (Branch 1, dispatcher
-//     invite-accept). Bei Email-Mismatch zeigen wir die fehlermeldung
-//     und einen "Mit anderem Account anmelden"-Link.
-//   - Anonymous: Email + Password-Form. Toggle "Schon einen Account?"
-//     entscheidet Branch 2 (existing user, login + accept) vs Branch 3
-//     (neuer user, signup + accept).
+// Reads `?token=...` from the URL and selects a flow based on session state:
+//   - Logged in with a matching email: one-click accept (Branch 1, via the
+//     invite-accept dispatcher). For an email mismatch, show an error and a
+//     "Sign in with a different account" link.
+//   - Anonymous: email and password form. The "Already have an account?" toggle
+//     selects Branch 2 (existing user, login + accept) or Branch 3 (new user,
+//     signup + accept).
 //
-// Anti-enumeration: invalidInviteToken collapsed alle Token/User/
-// Password-Failures auf einen Code (gleicher Trade-off wie reset).
+// Anti-enumeration: invalidInviteToken collapses token, user, and password
+// failures into one code, using the same trade-off as reset.
 //
-// Auto-Login: Branch 2+3 setzen Cookies via Server, Frontend redirected
-// zu loggedInHref. Branch 1 hat schon eine Session — Frontend redirected
-// auch zu loggedInHref damit der invitee in seinem neuen Tenant landet.
+// Auto-login: Branches 2 and 3 set cookies through the server, then the
+// frontend redirects to loggedInHref. Branch 1 already has a session, but the
+// frontend also redirects to loggedInHref so the invitee enters the new tenant.
 
 import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { type FormEvent, type ReactNode, useContext, useState } from "react";
@@ -34,7 +34,7 @@ export type InviteAcceptScreenProps = {
   readonly loggedInHref?:
     | string
     | ((args: { tenantId: string; roles: readonly string[] }) => string);
-  /** Login-Href für "Mit anderem Account anmelden". Default "/login". */
+  /** Login href for "Mit anderem Account anmelden". Default "/login". */
   readonly loginHref?: string;
 };
 
@@ -112,7 +112,7 @@ export function InviteAcceptScreen({
   const acceptLoggedIn = async (): Promise<void> => {
     setSubmitting(true);
     setError(null);
-    // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
+    // kumiko-lint-ignore no-raw-hooks not yet converted to the framework hook set
     const res = await fetch("/api/auth/invite-accept", {
       method: "POST",
       credentials: "same-origin",
@@ -132,7 +132,7 @@ export function InviteAcceptScreen({
   const acceptAnonExisting = async (): Promise<void> => {
     setSubmitting(true);
     setError(null);
-    // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
+    // kumiko-lint-ignore no-raw-hooks not yet converted to the framework hook set
     const res = await fetch("/api/auth/invite-accept-with-login", {
       method: "POST",
       credentials: "same-origin",
@@ -152,7 +152,7 @@ export function InviteAcceptScreen({
   const acceptAnonNew = async (): Promise<void> => {
     setSubmitting(true);
     setError(null);
-    // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
+    // kumiko-lint-ignore no-raw-hooks not yet converted to the framework hook set
     const res = await fetch("/api/auth/invite-signup-complete", {
       method: "POST",
       credentials: "same-origin",

package/packages/bundled-features/src/auth-email-password/web/login-screen.tsx

@@ -41,7 +41,7 @@ export type LoginScreenProps = {
    *  default path once the server offers the reset flow (login-options);
    *  `null` hides the link deliberately. */
   readonly forgotPasswordHref?: string | null;
-  /** Optional href to RequestAccountUnlockScreen (#1266). When set, an
+  /** Optional href to RequestAccountUnlockScreen. When set, an
    *  account_locked login error renders an "Unlock account?" link inline —
    *  the account-lockout escape hatch, since forgotPasswordHref does NOT
    *  help here: the lockout gate blocks login before password verify even
@@ -71,9 +71,8 @@ export type LoginScreenProps = {
   readonly onMfaSetupRequired?: (preauthSetupToken: string, accountLabel: string) => void;
 };
 
-// Map vom Reason-Code des Login-Handlers auf einen i18n-Key plus
-// optional extrahierte Interpolations-Parameter. Ungekannte Codes
-// fallen auf `auth.errors.loginFailed` zurück.
+// Maps login-handler reason codes to i18n keys and optional interpolation parameters.
+// Unknown codes fall back to `auth.errors.loginFailed`.
 function reasonToKey(failure: LoginFailure): {
   readonly key: string;
   readonly params?: Readonly<Record<string, unknown>>;