@eifi1/ui-kit 0.17.0 → 0.19.0

package/src/components/number-field.tsx

@@ -154,26 +154,27 @@ const FIELD_ERROR_CLASS = "mt-1 text-[11px] leading-tight text-[var(--danger)]";
  * digit grouping — "1.000" would read as a thousand in German and as one in English,
  * and a field that parses its own display back must not have that ambiguity.
  */
-export function NumberField({
-  value,
-  onCommit,
-  onValueChange,
-  digits,
-  min,
-  max,
-  nullable = false,
-  unit,
-  unitPlacement = "suffix",
-  locale: localeProp,
-  label,
-  invalid,
-  error,
-  id,
-  "aria-describedby": ariaDescribedBy,
-  "aria-invalid": ariaInvalid,
-  "aria-required": ariaRequired,
-  ...rest
-}: NumberFieldProps) {
+export function NumberField(props: NumberFieldProps) {
+  const {
+    value,
+    onCommit,
+    onValueChange,
+    digits,
+    min,
+    max,
+    nullable = false,
+    unit,
+    unitPlacement = "suffix",
+    locale: localeProp,
+    label,
+    invalid,
+    error,
+    id,
+    "aria-describedby": ariaDescribedBy,
+    "aria-invalid": ariaInvalid,
+    "aria-required": ariaRequired,
+    ...rest
+  } = props;
   const locale = useKitLocale(localeProp);
   const mark = decimalMark(locale);
   const localize = (text: string) => (mark === "," ? text.replace(/\./g, ",") : text);
@@ -292,15 +293,20 @@ export function NumberField({
       invalid={invalid || hasError || ariaInvalid === true || ariaInvalid === "true"}
     />
   );
-  // Same shape as Input's FieldGroup: no wrapper at all without a message, so adding
-  // `error` support changed nothing about the DOM a flex row lays out.
-  if (!hasError) return field;
+  // Input's FieldGroup, restated: no wrapper for a field that never takes `error`, so
+  // the prop changed nothing about the DOM a flex row lays out — and a STEADY one for a
+  // field that does, message or not. Wrapping only while a message showed swapped the
+  // element above the <input>, which remounted it: focus, caret and the half-typed
+  // draft's keystrokes were lost the moment the message came or went.
+  if (!hasError && !("error" in props)) return field;
   return (
     <div>
       {field}
-      <p id={errorId} className={FIELD_ERROR_CLASS}>
-        {error}
-      </p>
+      {hasError && (
+        <p id={errorId} className={FIELD_ERROR_CLASS}>
+          {error}
+        </p>
+      )}
     </div>
   );
 }

package/src/components/passkeys-setting.tsx

@@ -42,6 +42,32 @@ export interface PasskeysSettingProps<Id extends PasskeyId = PasskeyId> extends
    * the user cancelling the OS prompt) keeps what was typed.
    */
   onAdd: (name: string) => void | Promise<unknown>;
+  /**
+   * A step the app runs BEFORE `onAdd` (0.18.0) — re-asking for the current password,
+   * a policy notice, anything that may stop the add. Called with the same trimmed name;
+   * resolve `true` to go on to `onAdd`, `false` to stop quietly (nothing is said, the
+   * typed name stays). A rejection, or a throw, stops the same way: the app reports
+   * its own errors. While it runs the add button is disabled and busy, so a second
+   * click cannot start a second check.
+   *
+   * Kurvenschmiede asked for the password in its own dialog by handing `onAdd` a
+   * promise it kept open across that dialog (passkeys-card.tsx) — which still works.
+   * This is the documented place for it: open the dialog here, resolve with whether it
+   * was confirmed, and keep what it produced (the server's registration options) for
+   * `onAdd` in a ref. The ceremony then starts from the dialog's click rather than the
+   * card's, which is the user activation `navigator.credentials.create` wants.
+   *
+   * Left out, `onAdd` is called synchronously in the click, exactly as before.
+   */
+  beforeAdd?: (name: string) => boolean | Promise<boolean>;
+  /**
+   * What a passkey does to the password, which picks the line under the title (0.18.0).
+   * `"instead"` (default): it replaces it — `labels.description`, kastlan's promise.
+   * `"alongside"`: the password stays and the passkey is a second way in —
+   * `labels.descriptionAlongside`. Kurvenschmiede overrode `description` for exactly
+   * this; an app that sets `mode` needs no override.
+   */
+  mode?: "instead" | "alongside";
   /** The ceremony is running. The add button says so and does not start a second one. */
   adding?: boolean;
   /** Offer "Rename" on each row. Return a promise to leave edit mode only on success. */
@@ -92,6 +118,8 @@ export function PasskeysSetting<Id extends PasskeyId = PasskeyId>({
   passkeys,
   loading,
   onAdd,
+  beforeAdd,
+  mode = "instead",
   adding = false,
   onRename,
   onDelete,
@@ -108,6 +136,10 @@ export function PasskeysSetting<Id extends PasskeyId = PasskeyId>({
   const labels = useAccountSettingsLabels("passkeys", labelsProp);
   const locale = useKitLocale(localeProp);
   const [name, setName] = useState("");
+  // `beforeAdd` is running. State for the button, and a ref for the guard: two clicks
+  // in one frame both read the state from before either set it.
+  const [checking, setChecking] = useState(false);
+  const checkingRef = useRef(false);
 
   const date = (value: PasskeyItem["createdAt"]): string | null => {
     if (value === null || value === undefined || value === "") return null;
@@ -117,13 +149,40 @@ export function PasskeysSetting<Id extends PasskeyId = PasskeyId>({
   };
 
   const add = () => {
-    if (adding) return;
+    if (adding || checkingRef.current) return;
     const typed = name;
-    Promise.resolve(onAdd(typed.trim()))
-      // Clear only what was sent: the field stays editable while the OS prompt is up.
-      .then(() => setName((current) => (current === typed ? "" : current)))
-      .catch(() => {});
+    const value = typed.trim();
+    const send = () =>
+      Promise.resolve(onAdd(value))
+        // Clear only what was sent: the field stays editable while the OS prompt is up.
+        .then(() => setName((current) => (current === typed ? "" : current)));
+    if (!beforeAdd) {
+      send().catch(() => {});
+      return;
+    }
+    const done = () => {
+      checkingRef.current = false;
+      setChecking(false);
+    };
+    checkingRef.current = true;
+    setChecking(true);
+    let gate: Promise<boolean>;
+    // Called in the click, not a microtask later, so a step that itself needs the
+    // user's activation (a popup, the clipboard) still has it; a throw is a "no".
+    try {
+      gate = Promise.resolve(beforeAdd(value));
+    } catch (error) {
+      gate = Promise.reject(error);
+    }
+    gate
+      .then((go) => {
+        done();
+        // Strictly `true`: an app whose step resolves `undefined` meant nothing.
+        if (go === true) return send();
+      })
+      .catch(done);
   };
+  const busy = adding || checking;
 
   const isLoading = loading || passkeys === undefined;
   const items = passkeys ?? [];
@@ -171,7 +230,7 @@ export function PasskeysSetting<Id extends PasskeyId = PasskeyId>({
               }}
             />
           )}
-          <Button onClick={add} disabled={adding} aria-busy={adding || undefined}>
+          <Button onClick={add} disabled={busy} aria-busy={busy || undefined}>
             <KeyRound className="size-4" aria-hidden />
             {adding ? labels.adding : labels.add}
           </Button>
@@ -186,7 +245,9 @@ export function PasskeysSetting<Id extends PasskeyId = PasskeyId>({
       <div>
         <div className="text-sm font-medium">{labels.title}</div>
         <div className="text-xs text-[var(--text-muted)]">
-          {labels.description}
+          {mode === "alongside"
+            ? labels.descriptionAlongside
+            : labels.description}
         </div>
       </div>
       {body}

package/src/components/progress-bar.tsx

@@ -2,6 +2,8 @@ import { useId } from "react";
 import type { ComponentPropsWithoutRef, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { DEFAULT_COMMON_LABELS, useKitLabels, useKitLocale } from "../i18n/kit-labels";
+import { toneTextClass } from "./signed-amount";
+import type { TextTone } from "./signed-amount";
 
 /** The words a progress bar adds of its own. */
 export interface ProgressBarLabels {
@@ -169,6 +171,18 @@ export interface ProgressBarProps extends Omit<ComponentPropsWithoutRef<"div">,
    * `legendValue={(seg, share) => <>{share} <Amount … /></>}`.
    */
   legendValue?: (segment: ProgressBarSegment, formatted: string, index: number) => ReactNode;
+  /**
+   * The colour of each legend row's figure, as a {@link TextTone} — `toneTextClass`'s
+   * palette, the money pair included. Default `"muted"`: the legend explains the bar and
+   * should not outshout the headline above it. One tone for every row, or a function
+   * per row. A tone and not the segment's own `tone`: keksdose's tax card fills its
+   * three parts with one bucket's certainty ramp (`className`), while the FIGURES carry
+   * the bucket's money direction — `legendTone="expense"` for the tax owed — which it
+   * could only say before through `legendValue` and an app-side `Amount`. A function
+   * returning `undefined` keeps that row muted. Applies to `legendValue`'s node too
+   * (it inherits the colour unless it sets its own).
+   */
+  legendTone?: TextTone | ((segment: ProgressBarSegment, index: number) => TextTone | undefined);
   /** A muted line under the bar — the plan's reset date, "3 of 5 seats in use". It
    *  describes the bar (`aria-describedby`). */
   hint?: ReactNode;
@@ -224,6 +238,7 @@ export function ProgressBar({
   segments,
   legend = false,
   legendValue,
+  legendTone = "muted",
   hint,
   overage,
   sensitive = false,
@@ -441,7 +456,12 @@ export function ProgressBar({
               <span
                 data-part="legend-value"
                 data-private={priv}
-                className="ms-auto shrink-0 text-xs tabular-nums text-[var(--text-muted)]"
+                className={cn(
+                  "ms-auto shrink-0 text-xs tabular-nums",
+                  toneTextClass(
+                    (typeof legendTone === "function" ? legendTone(seg, i) : legendTone) ?? "muted",
+                  ),
+                )}
               >
                 {legendValue ? legendValue(seg, formatPart(seg.value), i) : formatPart(seg.value)}
               </span>

package/src/components/reauth-dialog.tsx

@@ -0,0 +1,273 @@
+import { useContext, useEffect, useId, useRef, useState } from "react";
+import type { KeyboardEvent, ReactNode } from "react";
+
+import { useKitLabels } from "../i18n/kit-labels";
+import { usePromisePending } from "./danger-confirm";
+import { DialogFrame } from "./dialog-frame";
+import { ModalCloseContext } from "./modal";
+import { Button, Input, Spinner } from "./ui";
+
+/**
+ * Every string the dialog renders — the `reauthDialog` namespace of
+ * `<UiKitProvider labels>`, and overridable per instance through `labels`. The title,
+ * description and submit button are usually worded per action ("Add a passkey"),
+ * which is what the `title` / `description` / `submitLabel` props are for; these are
+ * the fallbacks.
+ */
+export interface ReauthDialogLabels {
+  title: string;
+  description: string;
+  /** Label of the password field. */
+  password: string;
+  submit: string;
+  cancel: string;
+}
+
+export const DEFAULT_REAUTH_DIALOG_LABELS: ReauthDialogLabels = {
+  title: "Confirm it’s you",
+  description: "Enter your current password to continue.",
+  password: "Current password",
+  submit: "Continue",
+  cancel: "Cancel",
+};
+
+export interface ReauthDialogProps {
+  /**
+   * Verifies the password — the app's call, e.g. the request the password guards.
+   *
+   * Return a promise and the dialog manages itself: busy until it settles, closes
+   * (`onClose(true)`) when it resolves, STAYS OPEN with the password kept and selected
+   * when it rejects — a wrong password is a typo to correct, not a sign-out. Pass the
+   * reason as `error`. Return nothing and the app owns the rest: `busy` for the
+   * pending state, unmounting the dialog once it is done.
+   */
+  onSubmit: (password: string) => void | Promise<unknown>;
+  /**
+   * The dialog has closed: `true` after a resolved `onSubmit`, `false` for Cancel,
+   * Escape, the backdrop and Back. A dismissal while `onSubmit` is still running also
+   * answers `false`, and that call's late result is then ignored.
+   */
+  onClose: (confirmed: boolean) => void;
+  /**
+   * Why the last attempt failed ("Wrong password"), shown under the field, which turns
+   * invalid (`aria-invalid`, `--danger-border-strong`). The app decides the wording —
+   * a 400 is a wrong password, a 500 is not. Hidden again as soon as the user edits
+   * the field (the message is about the password they had typed), and shown again by
+   * the next failed submit.
+   */
+  error?: ReactNode;
+  /** The check is running, for a caller that tracks it itself (a mutation's
+   *  `isPending`); a promise returned from `onSubmit` does the same on its own. */
+  busy?: boolean;
+  /** Default: `labels.title` — "Confirm it’s you". */
+  title?: ReactNode;
+  /** The line under the title. Default: `labels.description`. */
+  description?: ReactNode;
+  /** Text of the submit button. Default: `labels.submit` — "Continue". */
+  submitLabel?: ReactNode;
+  /** `"danger"` when what the password unlocks cannot be undone: the submit is then the
+   *  destructive button. Default `"neutral"`. */
+  tone?: "neutral" | "danger";
+  /** Extra body above the field — what is about to happen, a warning. */
+  children?: ReactNode;
+  /** Kept-mounted mode, as on `Modal`: left out, the dialog is open while mounted. A
+   *  flip to `false` animates it out and wipes the password. */
+  open?: boolean;
+  /** User-facing strings; see {@link ReauthDialogLabels}. */
+  labels?: Partial<ReauthDialogLabels>;
+}
+
+/**
+ * "Enter your current password to continue" — the step-up check in front of an
+ * action that changes how an account signs in (adding a passkey) or what it can
+ * reach. Kurvenschmiede asked for the password before registering a passkey in a
+ * dialog of its own; keksdose asks for it inline in `DangerConfirm`'s
+ * `requirePassword` tile. Both are the same three facts — the field is the CURRENT
+ * password (the password manager fills it, never generates one), a wrong one stays in
+ * the dialog with its error, and the APP verifies it — so the promise handling is
+ * `DangerConfirm`'s own, shared, the field is its `CurrentPasswordInput` spelled out
+ * with an `error`, and this is the modal form of them.
+ *
+ * A component rather than a `useReauth()` promise: the step that follows the check
+ * (Kurvenschmiede's WebAuthn ceremony) needs what the server answered, and the error
+ * wording needs the app's own status codes — both already live in the app's mutation,
+ * which this dialog only has to be handed (`onSubmit={(pw) => begin.mutateAsync(pw)}`,
+ * `error={…}`).
+ *
+ * The field is a `<form>`, so Enter submits once something is typed. Focus starts in
+ * the field and returns to the trigger through `Modal`'s trap. While a check runs,
+ * the field is read-only, Cancel is disabled and Escape is held: a request that has
+ * left cannot be cancelled by closing the dialog, and the dialog should not pretend it
+ * can.
+ */
+export function ReauthDialog({
+  onSubmit,
+  onClose,
+  error,
+  busy: busyProp,
+  title,
+  description,
+  submitLabel,
+  tone = "neutral",
+  children,
+  open,
+  labels: labelsProp,
+}: ReauthDialogProps) {
+  const labels = useKitLabels("reauthDialog", DEFAULT_REAUTH_DIALOG_LABELS, labelsProp);
+  const [password, setPassword] = useState("");
+  // The error describes the password that was submitted; once the user edits it, it
+  // describes nothing on screen. Cleared by the next submit, so a second failure with
+  // the same message shows again.
+  const [edited, setEdited] = useState(false);
+  const { pending, run } = usePromisePending();
+  const busy = Boolean(busyProp) || pending;
+  const inputRef = useRef<HTMLInputElement>(null);
+  // `onSubmit` resolved: the actions row lowers the panel (state, so it re-renders),
+  // and `onClose` answers true (a ref, because `Modal` may call the `onClose` it saw
+  // BEFORE that re-render — its latest-callback ref is refreshed in an effect that runs
+  // after the actions row's).
+  const [done, setDone] = useState(false);
+  const confirmed = useRef(false);
+  const formId = useId();
+  const isOpen = open ?? true;
+
+  // A close (kept-mounted) wipes the password: it must not sit in a hidden dialog.
+  // During render, like DangerConfirm's disarm, so no frame holds it.
+  const [wasOpen, setWasOpen] = useState(isOpen);
+  if (wasOpen !== isOpen) {
+    setWasOpen(isOpen);
+    if (!isOpen) {
+      setPassword("");
+      setEdited(false);
+      setDone(false);
+    }
+  }
+
+  // After `Modal`'s own effect (a parent's effects run after its children's), so the
+  // trap has recorded the trigger as its restore target before focus moves in.
+  useEffect(() => {
+    if (!isOpen) return;
+    confirmed.current = false;
+    inputRef.current?.focus();
+  }, [isOpen]);
+
+  const submit = () => {
+    if (busy || password === "") return;
+    setEdited(false);
+    run(onSubmit(password), () => {
+      confirmed.current = true;
+      setDone(true);
+    });
+  };
+
+  // A rejection leaves focus where it was (the field, or the submit button) — select
+  // the password there so the retry replaces it rather than appending to it.
+  const wasPending = useRef(false);
+  useEffect(() => {
+    if (wasPending.current && !pending && !done) inputRef.current?.select();
+    wasPending.current = pending;
+  }, [pending, done]);
+
+  const shownError = edited ? undefined : error;
+
+  return (
+    <DialogFrame
+      open={open}
+      title={title ?? labels.title}
+      description={description ?? labels.description}
+      onClose={() => onClose(confirmed.current)}
+      onKeyDown={(e: KeyboardEvent<HTMLDivElement>) => {
+        if (busy && e.key === "Escape") e.preventDefault();
+      }}
+      aria-busy={busy || undefined}
+      actions={
+        <ReauthActions
+          formId={formId}
+          done={done}
+          busy={busy}
+          canSubmit={password !== ""}
+          danger={tone === "danger"}
+          cancelLabel={labels.cancel}
+          submitLabel={submitLabel ?? labels.submit}
+        />
+      }
+    >
+      {children}
+      <form
+        id={formId}
+        noValidate
+        onSubmit={(e) => {
+          e.preventDefault();
+          submit();
+        }}
+      >
+        {/* CurrentPasswordInput's field — the password manager fills it with the CURRENT
+            password and never offers to generate one; `readOnly`, not `disabled`, while
+            busy, because disabling the field that has focus drops focus to <body> —
+            plus `Input`'s own `error`, which that helper does not take. The message
+            paints the field, sits under it and is its `aria-describedby`; passing the
+            prop on every render keeps the field's box steady, so the message going away
+            on the first keystroke of a retry no longer remounts the <input> under the
+            typist (it did, which is why this used to draw its own message). */}
+        <Input
+          ref={inputRef}
+          type="password"
+          autoComplete="current-password"
+          label={labels.password}
+          value={password}
+          readOnly={busy}
+          error={shownError}
+          onChange={(e) => {
+            setPassword(e.target.value);
+            setEdited(true);
+          }}
+        />
+      </form>
+    </DialogFrame>
+  );
+}
+
+/**
+ * The actions row. A component of its own because it renders INSIDE the `Modal`, where
+ * the panel's animated close is in context: a resolved `onSubmit` lowers the panel
+ * through it, the way Cancel and Escape do, and `Modal` then calls `onClose`.
+ */
+function ReauthActions({
+  formId,
+  done,
+  busy,
+  canSubmit,
+  danger,
+  cancelLabel,
+  submitLabel,
+}: {
+  formId: string;
+  done: boolean;
+  busy: boolean;
+  canSubmit: boolean;
+  danger: boolean;
+  cancelLabel: ReactNode;
+  submitLabel: ReactNode;
+}) {
+  const close = useContext(ModalCloseContext);
+  useEffect(() => {
+    if (done) close?.();
+  }, [done, close]);
+  return (
+    <>
+      <Button type="button" variant="ghost" disabled={busy} onClick={() => close?.()}>
+        {cancelLabel}
+      </Button>
+      <Button
+        type="submit"
+        form={formId}
+        variant={danger ? "danger" : "primary"}
+        disabled={!canSubmit || busy}
+        aria-busy={busy || undefined}
+      >
+        {busy && <Spinner label={null} className="h-4 w-4" />}
+        {submitLabel}
+      </Button>
+    </>
+  );
+}

package/src/components/server-wake.tsx

@@ -0,0 +1,156 @@
+import { useLayoutEffect, useRef, useState, useSyncExternalStore } from "react";
+import type { CSSProperties, RefObject } from "react";
+
+import { useKitLabels } from "../i18n/kit-labels";
+import { cn } from "../lib/cn";
+import { clearanceAbove, subscribeFloating } from "../lib/floating-stack";
+import { serverWake } from "../lib/server-wake";
+import type { ServerWakeStage, ServerWakeWatcher } from "../lib/server-wake";
+import { AlertBanner } from "./alert-banner";
+import { Spinner } from "./ui";
+
+/**
+ * The visible half of the cold-start watchdog (`lib/server-wake.ts`), keksdose's
+ * `app/server-wake-notice.tsx` lifted into the kit: after a couple of seconds of an
+ * unanswered read it says the app is still loading, and after seven it says WHY — the
+ * server sleeps when nobody is using it, and the first request has to start it again.
+ *
+ * Corner-anchored and non-blocking on purpose. The pages underneath already show their
+ * own skeletons; what was missing is the explanation, not another overlay. Start
+ * corner, above the phone's bottom nav, so it collides with neither the centred toasts
+ * nor the nav bar — and above any FloatingActionButton it would otherwise cover
+ * (kastlan's offline pill shares the corner; on a phone the notice spans both).
+ *
+ * Mount it next to the router, not inside the app layout, so it also covers the login
+ * screen and the landing page — a cold start is at its most confusing exactly there,
+ * before anything of the app is on screen.
+ */
+
+// ── Labels ────────────────────────────────────────────────────────────────────
+
+export interface ServerWakeLabels {
+  /** Past `slowMs` (2 s): a warm server would have answered by now. */
+  slow: string;
+  /** Past `wakingMs` (7 s): the explanation. `appName` is the notice's prop; without
+   *  one the sentence says "the app". */
+  waking: (appName?: string) => string;
+}
+
+export const DEFAULT_SERVER_WAKE_LABELS: ServerWakeLabels = {
+  slow: "Still loading — this is taking longer than usual.",
+  waking: (appName) =>
+    `The server goes to sleep when nobody is using ${appName ?? "the app"}, so the first request after a break has to start it again. That can take a moment — nothing is lost, the page fills in by itself.`,
+};
+
+// ── Hook ──────────────────────────────────────────────────────────────────────
+
+/** The watcher's current stage, re-rendering on every change. Default: the shared
+ *  {@link serverWake} instance. */
+export function useServerWakeStage(watcher: ServerWakeWatcher = serverWake): ServerWakeStage {
+  // The server snapshot is `idle`: nothing is in flight while the HTML is rendered.
+  return useSyncExternalStore(watcher.subscribe, watcher.getStage, () => "idle");
+}
+
+// ── Notice ────────────────────────────────────────────────────────────────────
+
+export interface ServerWakeNoticeProps {
+  /** Default: the shared {@link serverWake} instance. Pass the app's own when it was
+   *  made with {@link createServerWake} (e.g. to watch the login POST too). */
+  watcher?: ServerWakeWatcher;
+  /** Named in the `waking` sentence ("…when nobody is using Keksdose…"). Default: the
+   *  label says "the app". */
+  appName?: string;
+  labels?: Partial<ServerWakeLabels>;
+  /**
+   * The height to keep clear at the bottom — AppShell's bottom nav. Default: its
+   * measured `--app-nav-h` (0px from `md` up and on pages without a shell, such as the
+   * login screen), so nothing has to be passed under an AppShell. The safe area is
+   * respected either way, and a 1rem gap is added. Numbers are px.
+   */
+  navOffset?: string | number;
+  /** Extra classes on the fixed anchor — a different width or `start-*`. The bottom
+   *  offset is an inline style, so move it vertically with {@link navOffset}. Either
+   *  way it rises above a visible FloatingActionButton under it. */
+  className?: string;
+}
+
+const px = (v: string | number) => (typeof v === "number" ? `${v}px` : v);
+
+/** Gap between the notice and a floating control it stacks above. */
+const STACK_GAP = "0.5rem";
+
+/**
+ * How far off the bottom the notice must sit to clear the FloatingActionButtons under
+ * it (`lib/floating-stack.ts`), re-measured when one appears, goes, resizes or the
+ * viewport does — or `null` while it is idle or nothing is under it. kastlan 0.18.
+ */
+function useFloatingClearance(anchor: RefObject<HTMLDivElement | null>, stage: ServerWakeStage): number | null {
+  const [clearance, setClearance] = useState<number | null>(null);
+  useLayoutEffect(() => {
+    if (stage === "idle") return;
+    const measure = () => setClearance(clearanceAbove(anchor.current));
+    measure();
+    const unsubscribe = subscribeFloating(measure);
+    window.addEventListener("resize", measure);
+    return () => {
+      unsubscribe();
+      window.removeEventListener("resize", measure);
+    };
+  }, [anchor, stage]);
+  // Idle, the last measurement is stale and nothing shows anyway.
+  return stage === "idle" ? null : clearance;
+}
+
+/**
+ * Renders nothing visible while idle. The LIVE REGION, though, is always mounted: a
+ * `role="status"` element inserted together with its text is announced unreliably
+ * (several screen readers only speak changes to a region they already knew about),
+ * so the region waits empty and the banner appears inside it. keksdose's notice
+ * mounted the region and the words at once.
+ */
+export function ServerWakeNotice({ watcher, appName, labels: labelsProp, navOffset, className }: ServerWakeNoticeProps) {
+  const labels = useKitLabels("serverWake", DEFAULT_SERVER_WAKE_LABELS, labelsProp);
+  const stage = useServerWakeStage(watcher);
+  const waking = stage === "waking";
+  const anchor = useRef<HTMLDivElement>(null);
+  const clearance = useFloatingClearance(anchor, stage);
+  const base = `calc(max(${navOffset === undefined ? "var(--app-nav-h, 0px)" : px(navOffset)}, env(safe-area-inset-bottom, 0px)) + 1rem)`;
+  const style: CSSProperties = {
+    bottom: clearance === null ? base : `max(${base}, calc(${clearance}px + ${STACK_GAP}))`,
+  };
+
+  return (
+    <div
+      ref={anchor}
+      role="status"
+      aria-live="polite"
+      data-stage={stage}
+      style={style}
+      // `pointer-events-none` on the empty anchor: a fixed box, even an empty one, is not
+      // allowed to swallow a tap on what it sits over.
+      className={cn(
+        "fixed start-4 z-50 max-w-[min(24rem,calc(100vw-2rem))]",
+        stage === "idle" && "pointer-events-none",
+        className,
+      )}
+    >
+      {stage !== "idle" && (
+        // `elevated`: OPAQUE in both themes (keksdose live #209) — the notice that
+        // explains a stall is read over whatever stalled, and a translucent dark tint
+        // let the page's own text show through it. A box banner is role-less, so the
+        // wrapper above stays the one live region.
+        <AlertBanner
+          tone={waking ? "warning" : "neutral"}
+          size="sm"
+          elevated
+          // `label={null}`: a Spinner is its own `role="status"` saying "Loading…" —
+          // nested here, a second live region and a second announcement ahead of the
+          // words that actually explain the wait. Here it is decoration.
+          icon={<Spinner label={null} className="h-3.5 w-3.5" />}
+        >
+          {waking ? labels.waking(appName) : labels.slow}
+        </AlertBanner>
+      )}
+    </div>
+  );
+}