@cosmicdrift/kumiko-samples 0.385.0 → 0.387.0

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

@@ -1,13 +1,12 @@
-// ResetPasswordScreen — liest `?token=...` aus der URL, zeigt Form mit
-// new + confirm-password. Submit triggert /api/auth/reset-password mit
-// dem Token. Server collapses alle Token-Verify-Failures auf einen
-// Code (anti-enumeration); UI zeigt unified "Link ungültig oder
-// abgelaufen"-message.
+// ResetPasswordScreen reads `?token=...` from the URL and shows fields for
+// a new and confirmed password. Submission calls /api/auth/reset-password
+// with the token. The server collapses all token-verification failures into
+// one code (anti-enumeration), so the UI shows the unified "link invalid or
+// expired" message.
 //
-// Token-Quelle ist read-once via useUrlToken(): liest `?token=...` beim
-// Mount und scrubbt den Param danach aus der URL (#774). Apps die das
-// anders brauchen (server-injected Token-Prop) reichen `token` als Prop
-// durch — dann bleibt die URL unangetastet.
+// The token is read once via useUrlToken(): `?token=...` is read on mount and
+// then scrubbed from the URL. Apps that need different behavior can pass a
+// server-injected token through the `token` prop; the URL is then left intact.
 
 import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { type FormEvent, type ReactNode, useState } from "react";
@@ -17,11 +16,11 @@ import { AuthCard, useUrlToken } from "./auth-form-primitives.tsx";
 
 export type ResetPasswordScreenProps = {
   readonly title?: string;
-  /** Override für den Token aus der URL — Apps die per server-side-
-   *  Render einen Token reinreichen, brauchen das. Default: parsed aus
-   *  `?token=...` in der URL. */
+  /** Override for the token from the URL. Apps that pass a token during
+   * server-side rendering need this. Default: parsed from `?token=...` in
+   * the URL. */
   readonly token?: string;
-  /** href für "Zum Login"-Link nach Success. Default "/login". */
+  /** href for the "Zum Login" link after success. Default "/login". */
   readonly loginHref?: string;
 };
 
@@ -75,10 +74,10 @@ export function ResetPasswordScreen({
 
   const effectiveTitle = title ?? t("auth.resetPassword.title");
 
-  // Kein Token in der URL → User soll den Link aus seiner Mail nochmal
-  // klicken oder einen neuen Reset anfordern. Form ohne Token zu
-  // submitten würde nur den invalidResetToken-Error zeigen — das ist
-  // verwirrend. Lieber upfront eine klare Message.
+  // No token in the URL: the user should click the link from their email again
+  // or request a new reset. Submitting without a token would only show the
+  // invalidResetToken error, which is confusing, so show a clear message
+  // immediately instead.
   if (token === "") {
     return (
       <AuthCard title={effectiveTitle}>

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

@@ -1,12 +1,12 @@
-// Session-State für den Browser-Renderer. Hält den aktuell eingeloggten
-// User (Profile + aktive Tenant-Zuordnung + Memberships), reagiert auf
-// Login/Logout/Switch-Tenant und refresh't die Daten automatisch.
+// Session state for the browser renderer. Holds the currently signed-in
+// user (profile + active tenant assignment + memberships), responds to
+// login/logout/tenant switching, and refreshes the data automatically.
 //
-// Warum Context + useReducer statt z.B. Zustand? Weil die State-Menge
-// klein ist (ein Handful Felder, ein paar Transitionen) und wir damit
-// eine Dependency weniger im Browser-Bundle haben. Die Consumer leben
-// unter `<SessionProvider>`; der `useSession()`-Hook liefert den State
-// und die Transitions.
+// Context + useReducer is used instead of, for example, Zustand because
+// the state is small (a handful of fields and a few transitions), avoiding
+// another dependency in the browser bundle. Consumers live under
+// `<SessionProvider>`; the `useSession()` hook provides the state
+// and transitions.
 
 import {
   type CurrentUser,
@@ -50,11 +50,12 @@ export type SessionState = {
   readonly user: CurrentUserProfile | null;
   readonly activeTenantId: string | null;
   readonly tenants: readonly TenantSummary[];
-  /** Merged session-roles für den active tenant: globalRoles (z.B.
-   *  SystemAdmin) + membership-roles des activeTenant. Server hat sie
-   *  schon im JWT gemerged, aber das JWT ist HttpOnly + nicht JS-lesbar;
-   *  Client computed dieselbe merge-Logik aus user.globalRoles +
-   *  tenants[active].roles damit nav-filtering greift. Dedupliziert. */
+  /** Merged session roles for the active tenant: globalRoles (for example,
+   *  SystemAdmin) plus the active tenant's membership roles. The server has
+   *  already merged them into the JWT, but the JWT is HttpOnly and cannot be
+   *  read by JavaScript; the client computes the same merge from
+   *  user.globalRoles + tenants[active].roles so navigation filtering works.
+   *  The result is deduplicated. */
   readonly roles: readonly string[];
   readonly bootstrapFailure: SessionBootstrapFailure | null;
   /** Set when an authenticated session was ended server-side (revoked,
@@ -97,15 +98,15 @@ const INITIAL: SessionState = {
   signedOutReason: null,
 };
 
-// kumiko_auth ist HttpOnly — kumiko_csrf wird beim Login gemeinsam gesetzt.
+// kumiko_auth is HttpOnly; kumiko_csrf is set together with it at login.
 export function hasLikelyAuthSession(cookieSource?: string): boolean {
   return readCsrfToken(cookieSource) !== undefined;
 }
 
-// Exported damit tests den merge-pfad direkt pinnen können — der hier
-// muss byte-identisch zum server-side merge in auth-routes.ts +
-// login.write.ts sein, sonst sieht der Client andere session-rollen
-// als der Server.
+// Exported so tests can pin the merge path directly: this must be
+// byte-identical to the server-side merge in auth-routes.ts +
+// login.write.ts, otherwise the client sees different session roles
+// from the server.
 export function computeActiveRoles(
   user: CurrentUserProfile | null,
   activeTenantId: string | null,
@@ -120,14 +121,14 @@ export function computeActiveRoles(
   return Array.from(new Set([...user.globalRoles, ...membershipRoles]));
 }
 
-/** Internal — exposed for tests die einen Mock-SessionApi-Wert reinreichen
- *  wollen, ohne durch SessionProvider's refresh-Lifecycle zu müssen. App-
- *  Code nutzt SessionProvider + useSession; direkter Context-Zugriff ist
- *  für Tests/Stories. */
+/** Internal — exposed so tests can pass a mock SessionApi value
+ *  without going through SessionProvider's refresh lifecycle. Application
+ *  code uses SessionProvider + useSession; direct context access is
+ *  intended for tests/stories. */
 export const SessionContext = createContext<SessionApi | undefined>(undefined);
 
-// Eine Refresh-Runde: /auth/tenants → wenn 401 nicht-eingeloggt, sonst
-// /user:me. Beides zusammen ergibt den vollen SessionState.
+// One refresh round: /auth/tenants → if 401, unauthenticated; otherwise
+// /user:me. Together, both requests produce the complete SessionState.
 async function refresh(): Promise<SessionState> {
   if (!hasLikelyAuthSession()) {
     return UNAUTHENTICATED;
@@ -183,7 +184,7 @@ export function SessionProvider({
     }
   }, []);
 
-  // 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(() => {
     void doRefresh();
   }, [doRefresh]);
@@ -191,7 +192,7 @@ export function SessionProvider({
   const sessionEndedSignal = useSessionEndedSignal();
   // Only an authenticated session can "end": an anonymous 401 on a public
   // surface must not show the hint.
-  // 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(() => {
     return sessionEndedSignal?.subscribe(() => {
       setState((prev) =>
@@ -222,10 +223,10 @@ export function SessionProvider({
       return;
     }
     setState(UNAUTHENTICATED);
-    // Hard-Reload: React-Tree, dispatcher-live-Caches, EventSource —
-    // alles fliegt auf Null. Nach Logout ist das der billigste Weg zu
-    // sauberer Ausgangslage, ohne dass wir jeden einzelnen Consumer
-    // per Context-Bust invalidieren müssen.
+    // Hard reload: the React tree, dispatcher live caches, and EventSource
+    // are all reset. After logout, this is the cheapest way to reach a clean
+    // state without having to invalidate every consumer through a context
+    // reset.
     if (typeof window !== "undefined") {
       window.location.reload();
     }
@@ -233,10 +234,9 @@ export function SessionProvider({
 
   const switchTenant = useCallback<SessionApi["switchTenant"]>(async (tenantId) => {
     await switchTenantApi(tenantId);
-    // Tenant-Wechsel rotiert JWT + Cookies. React-Tree enthält
-    // tenant-gebundene Caches (Queries, Live-Events) — simpler
-    // Reload ist konsistent mit dem Logout-Pfad und vermeidet
-    // halbe State-Übergänge.
+    // Tenant switching rotates the JWT + cookies. The React tree contains
+    // tenant-bound caches (queries, live events), so a simple reload is
+    // consistent with the logout path and avoids partial state transitions.
     if (typeof window !== "undefined") {
       window.location.reload();
     }

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

@@ -5,7 +5,7 @@
 // JWT + cookies (auto-login!) and returns the tenantKey.
 //
 // Token source is read-once via useUrlToken: reads `?token=...` on mount
-// and scrubs the param from the URL afterwards (#774). Apps that inject a
+// and scrubs the param from the URL afterwards. Apps that inject a
 // server-side token pass `token` as a prop instead.
 //
 // On success: shows a confirmation (account active, signed in) with a
@@ -117,8 +117,8 @@ export function SignupCompleteScreen({
       ? t("auth.signupComplete.activatedTitle")
       : t("auth.signupComplete.title"));
 
-  // Kein Token in der URL → klare Message statt Form ohne Token
-  // (würde nur invalidSignupToken zeigen, verwirrend).
+  // No token in the URL → show a clear message instead of a form without a token
+  // (which would only show invalidSignupToken and confuse the user).
   if (token === "") {
     return (
       <AuthCard title={effectiveTitle}>

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

@@ -1,15 +1,15 @@
-// SignupScreen — Magic-Link-Self-Signup, Step 1.
+// SignupScreen — Magic-Link self-signup, Step 1.
 //
-// Form mit Email-Input. Submit triggert /api/auth/signup-request
-// (silent-success, kein account-enumeration). UI zeigt unconditional
-// ein "Mail unterwegs"-Confirm mit Resend-Button — auch wenn die Email
-// schon registriert ist (Server schickt dann dieselbe Mail mit dem
-// existing Token aus Redis = idempotent).
+// Form with an email input. Submission triggers /api/auth/signup-request
+// (silent success, no account enumeration). The UI always shows a
+// "email on its way" confirmation with a Resend button, even if the email
+// is already registered (the server then sends the same email with the
+// existing token from Redis, making the request idempotent).
 //
-// App ist verantwortlich, den Screen unter einer URL zu mounten (z.B.
-// /signup) und ihn anonymous reachable zu machen (AuthPathGate VOR
-// AuthGate). Apex-Marketing kann via Link "Kostenlos starten" auf den
-// /signup-Pfad routen.
+// The app is responsible for mounting the screen at a URL (e.g.
+// /signup) and making it anonymously reachable (AuthPathGate before
+// AuthGate). An apex marketing site can route its "Start for free" link to
+// the /signup path.
 
 import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { type FormEvent, type ReactNode, useState } from "react";
@@ -20,7 +20,7 @@ import { AuthCard } from "./auth-form-primitives.tsx";
 export type SignupScreenProps = {
   readonly title?: string;
   readonly subtitle?: ReactNode;
-  /** href für den "Bereits einen Account?"-Link. App-spezifisch — Default
+  /** href for the "Already have an account?" link. App-specific; defaults to
    *  "/login". */
   readonly loginHref?: string;
 };
@@ -67,9 +67,9 @@ export function SignupScreen({
   };
 
   const onResend = async (): Promise<void> => {
-    // Resend nutzt den gleichen Endpunkt — Server returnt den existing
-    // Token aus Redis und schickt eine zweite Mail mit dem GLEICHEN
-    // Activation-Link (alte Mail bleibt also gültig).
+    // Resend uses the same endpoint: the server returns the existing
+    // token from Redis and sends a second email with the SAME
+    // activation link, so the old email remains valid.
     setSubmitting(true);
     setError(null);
     try {

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

@@ -1,17 +1,16 @@
-// TenantSwitcher — kleines Dropdown, zeigt den aktiven Tenant und
-// erlaubt Wechsel zu anderen Memberships. Auf Radix-DropdownMenu für
-// konsistentes Verhalten (Click-outside/Escape/Keyboard-Nav).
+// TenantSwitcher — compact dropdown showing the active tenant and
+// allowing switches to other memberships. Uses Radix-DropdownMenu for
+// consistent click-outside, Escape, and keyboard-navigation behavior.
 //
-// Rendert NICHT wenn kein User eingeloggt ist und auch NICHT wenn der
-// User nur einen Tenant hat (Single-Tenant-Apps brauchen keinen
-// Switcher).
+// Does NOT render when no user is logged in or when the user has only one
+// tenant (single-tenant apps do not need a switcher).
 //
-// Der Display-Name kommt aus einem optionalen `tenantName`-Prop
-// oder fallback zum ID-Hash. Design-Entscheidung: der TenantSwitcher
-// holt NICHT selbst tenant:query:me — das würde Round-Trips pro Mount
-// kosten und bräuchte Query-Caching-Infrastruktur. Stattdessen reicht
-// der Host den Resolver rein (kommt z.B. aus einer useTenantNames()-
-// Hook die einmalig am App-Boot geladen wird).
+// The display name comes from the optional `tenantName` prop or falls back
+// to the ID hash. Design decision: TenantSwitcher does NOT fetch
+// tenant:query:me itself, which would cost round trips per mount and
+// require query-caching infrastructure. Instead, the host passes in the
+// resolver (for example, from a useTenantNames() hook loaded once at app
+// boot).
 
 import { useTranslation } from "@cosmicdrift/kumiko-renderer";
 import {
@@ -27,10 +26,10 @@ import { type ReactNode, useCallback, useState } from "react";
 import { useSession } from "./session.tsx";
 
 export type TenantSwitcherProps = {
-  /** Optional: liefert einen menschenlesbaren Namen pro Tenant-ID.
-   *  Default: die ID wird direkt angezeigt (kurze UUID genügt für
-   *  Dev-Umgebungen). Für prod sollte der Host z.B. die Tenant-Namen
-   *  beim Login cachen und hier durchreichen. */
+  /** Optional: provides a human-readable name for each tenant ID.
+   *  Default: displays the ID directly (a short UUID is sufficient for
+   *  development environments). In production, the host should cache
+   *  tenant names at login and pass them here. */
   readonly tenantName?: (tenantId: string) => string;
 };
 
@@ -46,28 +45,28 @@ export function TenantSwitcher({ tenantName }: TenantSwitcherProps): ReactNode {
       try {
         await switchTenant(tenantId);
       } finally {
-        // In der Praxis führt switchTenant zu einem full-page reload,
-        // also sehen wir den cleared-state nie — das `finally` ist nur
-        // für den Edge-Case dass switchTenant throwt, damit die UI
-        // nicht mit dem Spinner hängen bleibt.
+        // In practice, switchTenant causes a full-page reload, so we never see
+        // the cleared state — `finally` only handles the edge case where
+        // switchTenant throws, preventing the UI from remaining stuck with
+        // the spinner.
         setSwitching(null);
       }
     },
     [activeTenantId, switchTenant],
   );
 
-  // Label-Priorität: App-eigener Resolver (Prop) > Server-geliefertes
-  // name/key aus /auth/tenants > UUID-Präfix. Letzteres ist nur noch der
-  // Notnagel — bei Seed-Tenants (00000000-…) ist es ununterscheidbar.
+  // Label priority: app-provided resolver (prop) > server-provided
+  // name/key from /auth/tenants > UUID prefix. The latter is only a
+  // last resort — it is indistinguishable for seeded tenants (00000000-…).
   const nameOf = (tenantId: string): string => {
     if (tenantName !== undefined) return tenantName(tenantId);
     const membership = tenants.find((m) => m.tenantId === tenantId);
-    // || statt ??: ein leerer name/key-String darf nicht als Label durchrutschen.
+    // || instead of ??: an empty name/key string must not be used as a label.
     return membership?.name || membership?.key || tenantId.slice(0, 8);
   };
 
-  // Rendering-Gate: kein User → nix; nur ein Tenant → auch nix
-  // (Single-Tenant-Apps brauchen keinen Switcher).
+  // Rendering gate: no user → nothing; only one tenant → nothing as well
+  // (single-tenant apps do not need a switcher).
   if (user === null || tenants.length <= 1) return null;
 
   const activeLabel =
@@ -76,7 +75,7 @@ export function TenantSwitcher({ tenantName }: TenantSwitcherProps): ReactNode {
   return (
     <DropdownMenu>
       <DropdownMenuTrigger asChild>
-        {/* kumiko-lint-ignore primitives-discipline radix-asChild braucht DOM-Element als Trigger; Native kriegt eigene .native.tsx-Variante mit ActionSheet */}
+        {/* kumiko-lint-ignore primitives-discipline radix-asChild requires a DOM element as the trigger; Native has its own .native.tsx variant with ActionSheet */}
         <button
           type="button"
           className={cn(

package/packages/bundled-features/src/auth-email-password/web/use-shell-user.ts

@@ -1,18 +1,17 @@
-// Liest den eingeloggten User + die Rollen aus dem aktiven Tenant aus
-// der Session. Der Hook ist die Standard-Brücke zwischen Session-State
-// und Layout-Komponenten (WorkspaceShell.user, DefaultAppShell-Gates,
-// custom permission checks).
+// Reads the logged-in user and roles for the active tenant from the session.
+// This hook is the standard bridge between session state and layout components
+// (WorkspaceShell.user, DefaultAppShell gates, custom permission checks).
 //
-// Returns undefined solange:
-//   - die Session lädt (status="loading")
-//   - der User unauthenticated ist
-//   - der activeTenantId in der tenants-Liste fehlt (defensiver Pfad —
-//     sollte nicht passieren, schadet aber nicht zu prüfen)
+// Returns undefined while:
+//   - the session is loading (status="loading")
+//   - the user is unauthenticated
+//   - activeTenantId is missing from the tenants list (a defensive path that
+//     should not occur, but is harmless to check)
 //
-// WorkspaceShell + DefaultAppShell akzeptieren undefined als "keine
-// Workspaces sichtbar", was im Loading-/Logged-Out-Fall die richtige UX
-// ist. Apps die mehr brauchen (Loading-Indicator etc.) prüfen
-// useSession().status direkt.
+// WorkspaceShell and DefaultAppShell treat undefined as "no workspaces
+// visible", which is the correct UX while loading or logged out. Apps that
+// need more (such as a loading indicator) should check useSession().status
+// directly.
 
 import { useMemo } from "react";
 import { useSession } from "./session.tsx";

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

@@ -1,12 +1,11 @@
-// UserMenu — Avatar-Dropdown für die Topbar (variant="pill", Default) oder den
-// Sidebar-Footer (variant="sidebar" = die sidebar-07-NavUser-Row). Zeigt
-// Name/Email + Logout. Auf Radix-DropdownMenu, damit Click-outside, Escape,
-// Focus-Management, Keyboard-Nav (↑↓/Home/End) und ARIA-Roles aus der Kiste
-// funktionieren.
+// UserMenu — avatar dropdown for the top bar (variant="pill", default) or the
+// sidebar footer (variant="sidebar" = the sidebar-07-NavUser-Row). Shows
+// name/email and logout. Uses Radix-DropdownMenu so click-outside, Escape,
+// focus management, keyboard navigation (↑↓/Home/End), and ARIA roles work
+// out of the box.
 //
-// Rendert NICHTS wenn kein User eingeloggt ist — Hosts dürfen das
-// Component außerhalb des AuthGate einhängen ohne dass ein harter
-// Fehler entsteht.
+// Renders nothing when no user is logged in, so hosts can mount the component
+// outside AuthGate without causing a hard error.
 
 import { useTranslation } from "@cosmicdrift/kumiko-renderer";
 import {
@@ -28,20 +27,20 @@ import { useSession } from "./session.tsx";
 export type UserMenuVariant = "pill" | "sidebar";
 
 export type UserMenuProps = {
-  /** Zusätzliche Menu-Items über dem Logout. Per-item class/behaviour
-   *  controlliert der Caller — wir packen nur den Frame drumrum. */
+  /** Additional menu items above logout. The caller controls per-item
+   *  classes and behavior; this component only provides the surrounding frame. */
   readonly children?: ReactNode;
-  /** "pill" (Default) = kompakter Topbar-Trigger; "sidebar" = volle NavUser-
-   *  Row (Avatar + Name + Email) für den `sidebarFooter`-Slot der App-Shell.
+  /** "pill" (default) = compact top-bar trigger; "sidebar" = full NavUser-
+   *  row (avatar + name + email) for the App-Shell's `sidebarFooter` slot.
    *  Requires a `SidebarProvider` ancestor — the default App-Shell
    *  `sidebarFooter` slot already provides one. */
   readonly variant?: UserMenuVariant;
 };
 
 function initials(value: string): string {
-  // Vor- und Nachname falls Displayname einen Spacebar hat, sonst
-  // erste zwei Chars der Email-Lokalseite. Deterministisch,
-  // damit der Avatar-Content nicht bei jedem Re-Render flattert.
+  // Uses the first and last name when the display name contains a space;
+  // otherwise uses the first two characters of the email local part. This is
+  // deterministic, so the avatar content does not change between re-renders.
   const trimmed = value.trim();
   if (trimmed.length === 0) return "?";
   const parts = trimmed.split(/\s+/);
@@ -84,8 +83,8 @@ export function UserMenu({ children, variant = "pill" }: UserMenuProps): ReactNo
     </DropdownMenuContent>
   );
 
-  // Sidebar-Footer: volle NavUser-Row (sidebar-07) als Dropdown-Trigger —
-  // gleiche Optik wie SidebarUser, aber klickbar mit Logout/Profil.
+  // Sidebar footer: full NavUser row (sidebar-07) as the dropdown trigger —
+  // matches SidebarUser visually while providing clickable logout/profile actions.
   if (variant === "sidebar") {
     return (
       <SidebarMenu>
@@ -123,7 +122,7 @@ export function UserMenu({ children, variant = "pill" }: UserMenuProps): ReactNo
   return (
     <DropdownMenu>
       <DropdownMenuTrigger asChild>
-        {/* kumiko-lint-ignore primitives-discipline radix-asChild braucht DOM-Element als Trigger; Native kriegt eigene .native.tsx-Variante mit ActionSheet */}
+        {/* kumiko-lint-ignore primitives-discipline radix-asChild requires a DOM element as the trigger; the native version in .native.tsx uses ActionSheet */}
         <button
           type="button"
           className={cn(

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

@@ -1,13 +1,12 @@
-// VerifyEmailScreen — liest `?token=...` aus URL, schickt ihn auto an
-// /api/auth/verify-email beim Mount, zeigt success/error. Idempotent
-// auf Server-Seite (mehrfaches Klicken setzt emailVerified=true erneut),
-// also kein Re-Submit-Risiko.
+// VerifyEmailScreen — reads `?token=...` from the URL and automatically sends it to
+// /api/auth/verify-email on mount, then shows success/error. The server-side
+// operation is idempotent (repeating it sets emailVerified=true again), so
+// retries are safe.
 //
-// useEffect mit empty-deps + once-Guard damit React Strict-Mode den
-// Verify-Call nur einmal feuert (Strict-Mode dispatched useEffect 2x in
-// dev). Token-roundtrip ist server-side single-use, aber wir wollen
-// nicht den ersten valid-call beim Mount und den zweiten als invalid-
-// Banner sehen.
+// The empty-deps effect and once guard prevent React Strict Mode from firing
+// the verification call twice (Strict Mode dispatches useEffect twice in dev).
+// The token roundtrip is single-use server-side, but this avoids showing an
+// invalid-token banner after the first valid mount call.
 
 import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { type ReactNode, useEffect, useRef, useState } from "react";
@@ -16,9 +15,9 @@ import { AuthCard, useUrlToken } from "./auth-form-primitives.tsx";
 
 export type VerifyEmailScreenProps = {
   readonly title?: string;
-  /** Override für Token aus URL. Default: parsed aus `?token=...`. */
+  /** Override the token from the URL. Default: parsed from `?token=...`. */
   readonly token?: string;
-  /** href für "Zum Login"-Link. Default "/login". */
+  /** href for the "Zum Login" link. Default "/login". */
   readonly loginHref?: string;
 };
 
@@ -35,7 +34,7 @@ export function VerifyEmailScreen({
   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-foundation/boot-checks.ts

@@ -1,5 +1,5 @@
 // Multiplicity boot-check for auth-foundation's `tokenVerifier` extension
-// point (#1368, #1570). Two static-shape conflicts a boot-check CAN catch (a
+// point. Two static-shape conflicts a boot-check CAN catch (a
 // runtime shape-match predicate's overlap can't be proven at boot): a
 // malformed plugin registration, and two providers both claiming the same
 // shape (resolveTokenVerifier can't tell them apart). Zero tokenVerifier
@@ -46,7 +46,7 @@ export function validateTokenVerifierMultiplicity(features: readonly FeatureDefi
 
   if (namesByShape.size === 0) {
     // Session-only apps (email-password + sessions) never hit tokenVerifier —
-    // cookie JWT auth uses sessionStore alone (#1570 / phronexsis#296).
+    // cookie JWT auth uses sessionStore alone.
     for (const feature of features) {
       for (const usage of feature.extensionUsages) {
         // skip: sessionStore present — tokenVerifier optional for cookie-session apps.
@@ -114,7 +114,7 @@ function validateSingleProvider(
   }
 }
 
-// Multiplicity boot-check for the `sessionStore` extension point (#1370).
+// Multiplicity boot-check for the `sessionStore` extension point.
 // Single-provider, unlike tokenVerifier — no shape to route on, so ≥2 fails
 // boot. Zero registrations is a valid configuration (see
 // validateSingleProvider doc) — a pure machine API using auth-foundation for
@@ -129,7 +129,7 @@ export function validateSessionStoreMultiplicity(features: readonly FeatureDefin
   });
 }
 
-// Optional single-provider (#1373). Zero registrations = OK (single-tenant /
+// Optional single-provider. Zero registrations = OK (single-tenant /
 // header-cookie path). ≥2 or malformed = boot fail.
 export function validateTenantResolverMultiplicity(features: readonly FeatureDefinition[]): void {
   validateSingleProvider(features, {

package/packages/bundled-features/src/auth-foundation/resolve-anonymous-access.ts

@@ -1,6 +1,6 @@
 /**
  * Merge app-facing AnonymousAccessConfig with auth-foundation tenant providers.
- * Providers win over any leftover callback fields (hard cutover #1374).
+ * Providers win over any leftover callback fields.
  * Test stacks may still pass Resolved callbacks when no provider is mounted.
  */
 import type {
@@ -30,7 +30,7 @@ export async function resolveAnonymousAccessFromRegistry(
   // (EXT_TENANT_RESOLVER/EXT_TENANT_EXISTENCE) alone must never make
   // anonymousAccess become defined for an app that never set it — that
   // would upgrade every roles:["anonymous"] handler to reachable without
-  // a JWT the moment such a routing feature is mounted (#1452).
+  // a JWT the moment such a routing feature is mounted.
   if (!base) {
     const needing = ANONYMOUS_ROUTE_FEATURES.filter((name) => deps.registry.getFeature(name));
     if (needing.length > 0) {
@@ -42,7 +42,7 @@ export async function resolveAnonymousAccessFromRegistry(
     return undefined;
   }
 
-  // Fail-closed (#1374 security): inline tenantResolver without trust is the
+  // Fail-closed (security): inline tenantResolver without trust is the
   // old ambiguous config — providers always carry trust; test stacks must too.
   if (
     !tenantResolver &&
@@ -57,7 +57,7 @@ export async function resolveAnonymousAccessFromRegistry(
     );
   }
 
-  // Providers win (#1374). When none are mounted, keep any test-injected
+  // Providers win. When none are mounted, keep any test-injected
   // Resolved callbacks so framework middleware suites stay self-contained.
   return {
     ...(base ?? {}),

package/packages/bundled-features/src/auth-foundation/types.ts

@@ -80,7 +80,7 @@ export function tokenShapeKey(shape: TokenShape): string {
   return shape.kind === "jwt" ? "jwt" : `prefix:${shape.prefix}`;
 }
 
-// Session-store extension point (#1370). Unlike EXT_TOKEN_VERIFIER, this is
+// Session-store extension point. Unlike EXT_TOKEN_VERIFIER, this is
 // single-provider — sessions have no per-provider shape to route on, so
 // exactly one implementation must be registered (boot-fails on 0 or ≥2).
 
@@ -108,7 +108,7 @@ export function isSessionStoreProvider(o: unknown): o is SessionStoreProvider {
   return typeof o === "object" && o !== null && "build" in o && typeof o.build === "function";
 }
 
-// Tenant-resolution extension points (#1373). Both are single-provider and
+// Tenant-resolution extension points. Both are single-provider and
 // optional — zero registered means today's single-tenant / header-cookie
 // path (no subdomain resolver, no existence check). ≥2 fails boot.
 

package/packages/bundled-features/src/auth-mfa/handlers/disable.write.ts

@@ -45,9 +45,9 @@ export function createDisableHandler(opts: DisableOptions) {
       if (!row) return mfaNotEnabled();
 
       // Fail closed, matching verify.write.ts/enable-confirm-preauth.write.ts
-      // (#1467): without ctx.redis, verifyMfaFactor's TOTP-replay burn is
-      // skipped, and a code observed once (phishing proxy/shoulder-surfing)
-      // could be replayed within the ±1-step window to disable MFA outright.
+      // without ctx.redis, verifyMfaFactor's TOTP-replay burn is skipped, and
+      // a code observed once (phishing proxy/shoulder-surfing) could be
+      // replayed within the ±1-step window to disable MFA outright.
       // "no ctx.redis means no one gets through MFA login" doesn't cover
       // this route — it's session-authed, and JWTs issued before Redis was
       // unwired stay valid until they expire.