@eifi1/ui-kit 0.50.0 → 0.51.0

package/src/lib/server-wake.ts

@@ -77,8 +77,9 @@ export interface ServerWakeWatcher {
    */
   start(method?: string, url?: string, request?: ServerWakeRequest): boolean;
   /** A counted request settled — either way: an error still proves the server
-   *  answered or gave up. When the last one does, the notice goes away. Never takes
-   *  the counter below zero. */
+   *  answered or gave up. The stage then follows the oldest request still out (0.51), so
+   *  the notice goes away when the last one does, or sooner when the rest are recent.
+   *  Never takes the counter below zero. */
   end(): void;
   /** `start` + `end` around a promise (or a function returning one), for a request
    *  that does not go through an adapter. Resolves and rejects as the work does. */
@@ -116,7 +117,19 @@ export function createServerWake({
   wakingMs = 7000,
   shouldWatch = watchReadsAnd(),
 }: ServerWakeOptions = {}): ServerWakeWatcher {
-  let inFlight = 0;
+  // When each counted request went out, oldest first; its length is the count.
+  //
+  // The stage is the age of the OLDEST outstanding request (0.51). It used to be the age of
+  // the first request since the count was last zero, so overlapping reads that were each
+  // fast — one going out before the last came back, on a busy page — chained past 2 s and
+  // showed "taking longer than usual" with nothing slow at all (keksdose live #454, found
+  // there while chasing a read that really was slow).
+  //
+  // `end()` names no request, so it retires the OLDEST start. When a newer request comes
+  // back first, the start left standing for the older one is later than its own, so the
+  // age read is never MORE than the oldest request's real age: a notice can come late,
+  // never falsely.
+  const starts: number[] = [];
   let stage: ServerWakeStage = "idle";
   let slowTimer: ReturnType<typeof setTimeout> | null = null;
   let wakingTimer: ReturnType<typeof setTimeout> | null = null;
@@ -135,25 +148,36 @@ export function createServerWake({
     wakingTimer = null;
   };
 
+  // The stage for the oldest outstanding request's age, and timers for what is still to
+  // come. With none outstanding: idle.
+  const arm = () => {
+    clearTimers();
+    if (starts.length === 0) {
+      setStage("idle");
+      return;
+    }
+    const age = Date.now() - starts[0];
+    setStage(age >= wakingMs ? "waking" : age >= slowMs ? "slow" : "idle");
+    if (age < slowMs) slowTimer = setTimeout(() => setStage("slow"), slowMs - age);
+    if (age < wakingMs) wakingTimer = setTimeout(() => setStage("waking"), wakingMs - age);
+  };
+
   const start = (method?: string, url?: string, request: ServerWakeRequest = { method, url }): boolean => {
     if (isOffline()) return false;
     if (!shouldWatch((method ?? "get").toLowerCase(), url ?? "", request)) return false;
-    inFlight += 1;
-    // The clock runs from the FIRST outstanding request: a page firing a second read
-    // at 1.9 s is still waiting on the same sleeping server, not starting afresh.
-    if (inFlight === 1) {
-      clearTimers();
-      slowTimer = setTimeout(() => setStage("slow"), slowMs);
-      wakingTimer = setTimeout(() => setStage("waking"), wakingMs);
-    }
+    starts.push(Date.now());
+    // A request joining others does not move the clock: a page firing a second read at
+    // 1.9 s is still waiting on the same sleeping server, not starting afresh.
+    if (starts.length === 1) arm();
     return true;
   };
 
   const end = () => {
-    inFlight = Math.max(0, inFlight - 1);
-    if (inFlight > 0) return;
-    clearTimers();
-    setStage("idle");
+    if (starts.length === 0) return;
+    // The server answered (or gave up on) one of them, so the oldest's clock is over; the
+    // next oldest's age decides, which may well put the notice away again.
+    starts.shift();
+    arm();
   };
 
   return {
@@ -171,7 +195,7 @@ export function createServerWake({
       return counted ? promise.finally(end) : promise;
     },
     reset() {
-      inFlight = 0;
+      starts.length = 0;
       clearTimers();
       setStage("idle");
     },
@@ -182,7 +206,7 @@ export function createServerWake({
       };
     },
     getStage: () => stage,
-    getInFlight: () => inFlight,
+    getInFlight: () => starts.length,
   };
 }
 

package/src/shell/app-shell.tsx

@@ -164,17 +164,6 @@ export const DEFAULT_MOBILE_MAX_ITEMS: Readonly<Record<TextSize, number>> = {
   xlarge: 4,
 };
 
-/**
- * @deprecated 0.49 — use {@link DEFAULT_MOBILE_MAX_ITEMS} and `AppShell`'s
- * `mobileMaxItems`: the bar is sized in cells, "More" included; removed in 0.51. This is
- * the same default counted as entries before "More" (one fewer).
- */
-export const DEFAULT_MOBILE_BAR_MAX: Readonly<Record<TextSize, number>> = {
-  normal: DEFAULT_MOBILE_MAX_ITEMS.normal - 1,
-  large: DEFAULT_MOBILE_MAX_ITEMS.large - 1,
-  xlarge: DEFAULT_MOBILE_MAX_ITEMS.xlarge - 1,
-};
-
 /**
  * The phone bar's cells (0.49 KIT-6): every entry when there are at most `maxItems`,
  * else `maxItems − 1` entries and a "More" cell for the rest. Which entries stay is
@@ -215,21 +204,10 @@ export function splitMobileBar<T>(entries: readonly T[], max: number): { shown:
   return { shown: entries.slice(0, limit), hidden: entries.slice(limit) };
 }
 
-/** The bar's cell count at `size`: `mobileMaxItems`, else the deprecated `mobileBarMax`
- *  read as cells (one more), else the default. */
-function mobileCells(
-  maxItems: AppShellProps["mobileMaxItems"],
-  barMax: AppShellProps["mobileBarMax"],
-  size: TextSize,
-): number {
-  if (maxItems !== undefined) {
-    return typeof maxItems === "number" ? maxItems : (maxItems[size] ?? DEFAULT_MOBILE_MAX_ITEMS[size]);
-  }
-  if (barMax !== undefined) {
-    const entries = typeof barMax === "number" ? barMax : barMax[size];
-    if (entries !== undefined) return entries + 1;
-  }
-  return DEFAULT_MOBILE_MAX_ITEMS[size];
+/** The bar's cell count at `size`: `mobileMaxItems`, else the default. */
+function mobileCells(maxItems: AppShellProps["mobileMaxItems"], size: TextSize): number {
+  if (maxItems === undefined) return DEFAULT_MOBILE_MAX_ITEMS[size];
+  return typeof maxItems === "number" ? maxItems : (maxItems[size] ?? DEFAULT_MOBILE_MAX_ITEMS[size]);
 }
 
 /** The kit's dev switch, as `lib/logger.ts` reads it: a development build, never a
@@ -263,17 +241,10 @@ function shortLabelNamesLabel(short: string, label: string): boolean {
 const TEXT_SIZE_WORDS: Record<TextSize, string> = { normal: "Normal", large: "Large", xlarge: "Extra large" };
 
 /** A development build's notes on `nav` (0.49 KIT-6): a `shortLabel` that is another word
- *  than its `label` without `shortLabelIsAlias`, and the deprecated `mobileBarMax`. */
-function useNavDevWarnings(nav: AppShellNavItem[], deprecatedBarMax: boolean): void {
+ *  than its `label` without `shortLabelIsAlias`. */
+function useNavDevWarnings(nav: AppShellNavItem[]): void {
   useEffect(() => {
     if (!devWarnings()) return;
-    if (deprecatedBarMax) {
-      warnNavOnce(
-        "mobileBarMax",
-        "[ui-kit] AppShell mobileBarMax is deprecated: use mobileMaxItems, which counts the bar's cells with " +
-          '"More" (mobileBarMax={4} is mobileMaxItems={5}). Removed in 0.51.',
-      );
-    }
     for (const item of nav) {
       if (item.shortLabel === undefined || item.shortLabelIsAlias) continue;
       if (shortLabelNamesLabel(item.shortLabel, item.label)) continue;
@@ -287,7 +258,7 @@ function useNavDevWarnings(nav: AppShellNavItem[], deprecatedBarMax: boolean): v
           "Shorten the label instead, or pass shortLabelIsAlias: true if the other word is meant.",
       );
     }
-  }, [nav, deprecatedBarMax]);
+  }, [nav]);
 }
 
 /**
@@ -352,7 +323,7 @@ export interface AppShellProps extends ComponentPropsWithoutRef<"div"> {
    *
    * Unset (0.32.2, kastlan's 0.32.1 report): `"wrap"` at Normal and `"scroll"` at Large
    * and Extra large, where a wrapped group of eight pages took six or seven rows and
-   * covered the page — the other half of what `mobileBarMax` does for the bar.
+   * covered the page — the other half of what `mobileMaxItems` does for the bar.
    */
   mobileSubNavLayout?: "wrap" | "scroll";
   /**
@@ -368,13 +339,6 @@ export interface AppShellProps extends ComponentPropsWithoutRef<"div"> {
    * `{ xlarge: 5 }` replaces it at one size only. Never fewer than one entry beside More.
    */
   mobileMaxItems?: number | Partial<Record<TextSize, number>>;
-  /**
-   * @deprecated 0.49 — use `mobileMaxItems`, which counts the bar's cells, "More"
-   * included: `mobileBarMax={4}` is `mobileMaxItems={5}`; removed in 0.51. Read as that
-   * (one more, per size), with a development warning; ignored when `mobileMaxItems` is
-   * given.
-   */
-  mobileBarMax?: number | Partial<Record<TextSize, number>>;
   /** The More cell's words over the provider's `appShellMore`. */
   moreLabels?: Partial<AppShellMoreLabels>;
   /**
@@ -498,7 +462,6 @@ export function AppShell({
   mobileSubNav = true,
   mobileSubNavLayout: mobileSubNavLayoutProp,
   mobileMaxItems,
-  mobileBarMax,
   moreLabels,
   toggleGroupLabel,
   embedded: embeddedProp,
@@ -512,13 +475,13 @@ export function AppShell({
   const mobileSubNavLayout = mobileSubNavLayoutProp ?? (large ? "scroll" : "wrap");
   // The bottom bar's cells: every entry the phone does not reach another way, up to the
   // text size's limit, More included; the rest go under More (§10.7, KIT-6).
-  const maxItems = mobileCells(mobileMaxItems, mobileBarMax, textSize);
+  const maxItems = mobileCells(mobileMaxItems, textSize);
   const { shown: barNav, hidden: moreNav } = pickMobileBar(
     nav.filter((item) => !item.mobileHidden),
     maxItems,
     (item) => item.mobilePriority,
   );
-  useNavDevWarnings(nav, mobileBarMax !== undefined && mobileMaxItems === undefined);
+  useNavDevWarnings(nav);
   // An embedded shell sharing the default key would overwrite the outer app's sidebar
   // preference with its own — so it persists only when given a key of its own.
   const collapseStorageKey =
@@ -1079,7 +1042,7 @@ function TourAnchor({ to, dataTour }: { to: string; dataTour?: string }) {
 
 /**
  * The bar's "More" cell (0.32, docs/text-size-harmonization.md §4, §10.7): the entries
- * past `mobileBarMax`, in a sheet — each entry as a link, and under a group its pages,
+ * past `mobileMaxItems`, in a sheet — each entry as a link, and under a group its pages,
  * since a group the bar no longer shows has no sub-row to reach them by either. Marked
  * active while the current page is one of them, as the cell it replaced would be.
  *

package/src/shell/dev-menu.tsx

@@ -0,0 +1,259 @@
+import { useState } from "react";
+import type { ReactNode } from "react";
+import { FlaskConical, Undo2 } from "lucide-react";
+import { DEFAULT_TOP_BAR_LABELS, useKitLabels, type LabelOverride } from "../i18n/kit-labels";
+import { TopBarActionMenu, type TopBarMenuEntry } from "./topbar-action-menu";
+import { useTopBarPartsLabels, type DevSwitchersLabels } from "./top-bar-parts-labels";
+
+/** Where the role the session started with is kept, unless the app names its own key. */
+export const DEV_ORIGINAL_ROLE_KEY = "ui-kit:dev-original-role";
+
+function readKey(key: string): string | null {
+  try {
+    return sessionStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+function writeKey(key: string, value: string | null): void {
+  try {
+    if (value === null) sessionStorage.removeItem(key);
+    else sessionStorage.setItem(key, value);
+  } catch {
+    /* storage blocked: "Back to" lasts as long as this page */
+  }
+}
+
+/**
+ * One of the app's own groups in the {@link DevMenu} (docs/top-bar-harmonization.md
+ * §2.7.1): keksdose's budget role, its "today" override, its resets.
+ *
+ * The rows are plain {@link TopBarMenuEntry}s, and there is no dev item type beside them
+ * (the contract with keksdose, 0.51): a choice of one is radio rows (`checked`), a toggle
+ * is a `checkable: "checkbox"` row, an action is a plain row. No form fields — a menu is
+ * a `role="menu"`, where a text or date input has no place in the arrow keys; a free
+ * value is a "Custom…" row that opens the app's own dialog.
+ */
+export interface DevMenuSection {
+  /** Unique among the sections. The rows' keys need be unique only within theirs: the
+   *  menu prefixes them with this. */
+  key: string;
+  /** The group's heading, drawn above its rows and announced as the group's name. */
+  title: ReactNode;
+  /** The rows, as `TopBarActionMenu` takes them. A `divider` ends the group, as there. */
+  entries: readonly TopBarMenuEntry[];
+}
+
+export interface DevMenuProps<R extends string, P extends string> {
+  /**
+   * Draw anything at all. The app passes `import.meta.env.DEV` AND its probe of the dev
+   * route (§2.7.1): the constant keeps the menu off a production build's screen, the
+   * probe off a dev build whose server has the route shut (§6.1) — flasks with nothing
+   * behind them. Neither takes code out of the bundle; see `sections`.
+   */
+  enabled: boolean;
+  roles?: readonly R[];
+  /** The role the server enforces now. Named `currentRole`, not `role`, because `role` on
+   *  a JSX element is the ARIA role (as `RoleChip`'s `value`). */
+  currentRole?: R;
+  /** Apply a role — the app calls server-kit's `POST /dev/switch {role}` and re-reads
+   *  `/auth/me` (§2.7, §6.2). */
+  onRole?: (role: R) => void;
+  plans?: readonly P[];
+  /** The plan the server enforces now. Left out (not known yet — kastlan's overview is a
+   *  404 while billing is off), the plan group still renders, with no row checked; a
+   *  `GET /dev/switch` answers it. */
+  currentPlan?: P;
+  /** Apply a plan — `POST /dev/switch {plan}`, then the overview (§6.3). */
+  onPlan?: (plan: P) => void;
+  /**
+   * The role to offer "Back to {role}" for. Left out, the kit keeps it itself: the role
+   * before the first switch of this browser session, in `sessionStorage` under
+   * `storageKey` — the server answers with the NEW role after a switch, so only the
+   * browser still knows the old one.
+   */
+  originalRole?: R;
+  /** The `sessionStorage` key for the kept role. Default {@link DEV_ORIGINAL_ROLE_KEY};
+   *  an app with several accounts on one browser may scope it per user. */
+  storageKey?: string;
+  /** Billing is off locally: the plan group says plans change nothing, and stays usable
+   *  (§6.3). */
+  billingOff?: boolean;
+  /** A role's or a plan's words in the menu. Default: the value itself. */
+  roleLabel?: (role: R) => ReactNode;
+  planLabel?: (plan: P) => ReactNode;
+  /** Prop > `<UiKitProvider labels={{ topBarParts: { dev } }}>` > English. */
+  labels?: LabelOverride<DevSwitchersLabels>;
+  /** 0.51: the app's own dev groups, after the kit's role and plan, in this order. Their
+   *  DEFINITIONS belong in a module only a dev build imports (§2.7.1): `enabled={false}`
+   *  hides the menu, but the code of a section built inline stays in the bundle. */
+  sections?: readonly DevMenuSection[];
+  /**
+   * 0.51: an override is on that the developer could forget — a "today" that is not
+   * today, a simulated slow server. The flask wears a dot, and its name says so ("Dev
+   * tools · Role: ADMIN · Plan: free Overrides on"), since a dot alone tells a screen
+   * reader nothing. The app decides what counts; the kit cannot see into its sections.
+   */
+  active?: boolean;
+}
+
+const flask = <FlaskConical className="size-5 text-warning" />;
+
+/** A label's text for a sentence, or the raw value when the label is not text. */
+const textOf = (label: ReactNode, value: string) =>
+  typeof label === "string" || typeof label === "number" ? String(label) : value;
+
+/** A row someone can pick — what makes a menu worth drawing. */
+const isRow = (entry: TopBarMenuEntry) => entry.kind !== "heading" && entry.kind !== "divider";
+
+/**
+ * The top bar's local-dev menu (docs/top-bar-harmonization.md §2.7, §2.7.1, §6.2, §6.3):
+ * ONE amber flask, `RoleSwitcher`'s, over the kit's Account section and the app's own.
+ *
+ * 0.42's `DevSwitchers` drew a flask per switcher and had no place for anything else,
+ * and an app has more dev controls than a role and a plan — keksdose's budget role, a
+ * "today" override, resets (agreed with keksdose for 0.51). So the kit's part is now the
+ * menu, and the app's rows go in it.
+ *
+ * - **The Account section** comes first: the role group, ending in "Back to {role}" once
+ *   the role differs from the one the session started with (the dev route needs only a
+ *   signed-in user, so a switch to a lesser role can always switch back); then the plan
+ *   group, which with `billingOff` notes that plans change nothing. Each renders only
+ *   with its list and handler.
+ * - **The app's `sections`** follow, each a group under its own heading.
+ * - **`active`** puts a dot on the flask for an override that is easy to forget.
+ *
+ * Nothing renders unless `enabled`, and nothing with no row to show. The panel scrolls
+ * (`TopBarActionMenu`'s `scrollable`): some 25 rows ran off a 390×844 phone.
+ */
+export function DevMenu<R extends string, P extends string>({
+  enabled,
+  roles,
+  currentRole: role,
+  onRole,
+  plans,
+  currentPlan: plan,
+  onPlan,
+  originalRole,
+  storageKey = DEV_ORIGINAL_ROLE_KEY,
+  billingOff = false,
+  roleLabel = (r) => r,
+  planLabel = (p) => p,
+  labels: labelsProp,
+  sections = [],
+  active = false,
+}: DevMenuProps<R, P>) {
+  const bar = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS);
+  const words = useTopBarPartsLabels(labelsProp ? { dev: labelsProp } : undefined).dev;
+  const [kept, setKept] = useState<string | null>(() => (enabled ? readKey(storageKey) : null));
+  // 0.43 (keksdose): `enabled` may start false and turn true — an app's GET probe of the
+  // dev route — so the kept role is read again then, or "Back to {role}" is lost after a
+  // reload. Adjusted during render, React's pattern for state that follows a prop.
+  const [wasEnabled, setWasEnabled] = useState(enabled);
+  if (wasEnabled !== enabled) {
+    setWasEnabled(enabled);
+    if (enabled) setKept(readKey(storageKey));
+  }
+  if (!enabled) return null;
+
+  const original = (originalRole ?? kept ?? undefined) as R | undefined;
+
+  const pickRole = (next: R) => {
+    if (originalRole === undefined) {
+      if (next === original) {
+        // Back where the session began: nothing left to go back to.
+        writeKey(storageKey, null);
+        setKept(null);
+      } else if (kept === null && role !== undefined && next !== role) {
+        writeKey(storageKey, role);
+        setKept(role);
+      }
+    }
+    onRole?.(next);
+  };
+
+  const roleGroup: TopBarMenuEntry[] =
+    roles && roles.length > 0 && role !== undefined && onRole
+      ? [
+          { kind: "heading", key: "head-role", label: words.roleHeading },
+          ...roles.map(
+            (r): TopBarMenuEntry => ({ key: `role-${r}`, label: roleLabel(r), checked: r === role, onSelect: () => pickRole(r) }),
+          ),
+          // Behind a rule, which ends the role group: "Back to" is a way out, not a role.
+          ...(original !== undefined && original !== role
+            ? ([
+                { kind: "divider", key: "sep-back" },
+                {
+                  key: "back",
+                  icon: <Undo2 className="size-4" />,
+                  label: words.backTo(textOf(roleLabel(original), original)),
+                  onSelect: () => pickRole(original),
+                },
+              ] satisfies TopBarMenuEntry[])
+            : []),
+        ]
+      : [];
+
+  const planGroup: TopBarMenuEntry[] =
+    plans && plans.length > 0 && onPlan
+      ? [
+          {
+            kind: "heading",
+            key: "head-plan",
+            // The billing-off note is part of the group's NAME, under the heading. In 0.42's
+            // own plan menu it was a trailing `<li>`: not a row, so the arrow keys passed
+            // over it and a screen reader moving through the menu never reached it. Named,
+            // it is read on the way into the plans. And in one menu a trailing note would
+            // sit under the app's sections, not under the plans.
+            label: billingOff ? (
+              <>
+                {words.planHeading}{" "}
+                <span
+                  data-dev-billing-off=""
+                  className="mt-0.5 block font-normal normal-case tracking-normal text-xs text-muted"
+                >
+                  {words.billingOff}
+                </span>
+              </>
+            ) : (
+              words.planHeading
+            ),
+          },
+          ...plans.map(
+            (p): TopBarMenuEntry => ({ key: `plan-${p}`, label: planLabel(p), checked: p === plan, onSelect: () => onPlan(p) }),
+          ),
+        ]
+      : [];
+
+  // The app's rows keyed under their section: two sections may well both have a "reset".
+  const appGroups = sections.flatMap((section): TopBarMenuEntry[] => [
+    { kind: "heading", key: `section:${section.key}`, label: section.title },
+    ...section.entries.map((entry): TopBarMenuEntry => ({ ...entry, key: `${section.key}:${entry.key}` })),
+  ]);
+
+  const entries = [...roleGroup, ...planGroup, ...appGroups];
+  if (!entries.some(isRow)) return null;
+
+  // The menu, then the role and the plan, as 0.42's two triggers named them: the bar
+  // shows the flask only, so its name (and tooltip) is where they are read.
+  const name = [
+    words.menu,
+    roleGroup.length > 0 && role !== undefined ? bar.role(role) : null,
+    planGroup.length > 0 && plan !== undefined ? words.plan(plan) : null,
+  ]
+    .filter((part): part is string => part !== null)
+    .join(" · ");
+
+  return (
+    <TopBarActionMenu
+      icon={flask}
+      // The badge's words join the trigger's name, as the tours compass's NEW dot does.
+      // `danger`, the badge's default: an amber dot would vanish into the amber flask.
+      iconBadge={active ? { label: words.overridesOn } : null}
+      aria-label={name}
+      entries={entries}
+      scrollable
+    />
+  );
+}

package/src/shell/dev-switchers.tsx

@@ -1,179 +1,18 @@
-import { useState } from "react";
-import type { ReactNode } from "react";
-import { FlaskConical, Undo2 } from "lucide-react";
-import { DEFAULT_TOP_BAR_LABELS, useKitLabels, type LabelOverride } from "../i18n/kit-labels";
-import { TopBarActionMenu, type TopBarMenuEntry } from "./topbar-action-menu";
-import { useTopBarPartsLabels, type DevSwitchersLabels } from "./top-bar-parts-labels";
+import { DevMenu, type DevMenuProps } from "./dev-menu";
 
-/** Where the role the session started with is kept, unless the app names its own key. */
-export const DEV_ORIGINAL_ROLE_KEY = "ui-kit:dev-original-role";
+// 0.42's local-dev switchers (docs/top-bar-harmonization.md §2.7, §6.2, §6.3), since 0.51
+// a `DevMenu` with no app sections (§2.7.1). The props are the same and so is every row,
+// "Back to {role}" and its `sessionStorage` included — but it draws ONE flask where it
+// drew two: the role and the plan are groups of one menu, as in DevMenu.
 
-function readKey(key: string): string | null {
-  try {
-    return sessionStorage.getItem(key);
-  } catch {
-    return null;
-  }
-}
-
-function writeKey(key: string, value: string | null): void {
-  try {
-    if (value === null) sessionStorage.removeItem(key);
-    else sessionStorage.setItem(key, value);
-  } catch {
-    /* storage blocked: "Back to" lasts as long as this page */
-  }
-}
-
-export interface DevSwitchersProps<R extends string, P extends string> {
-  /** Draw anything at all: the app passes `import.meta.env.DEV`, so a production build
-   *  tree-shakes the switchers with the constant. */
-  enabled: boolean;
-  roles?: readonly R[];
-  /** The role the server enforces now. Named `currentRole`, not `role`, because `role` on
-   *  a JSX element is the ARIA role (as `RoleChip`'s `value`). */
-  currentRole?: R;
-  /** Apply a role — the app calls server-kit's `POST /dev/switch {role}` and re-reads
-   *  `/auth/me` (§2.7, §6.2). */
-  onRole?: (role: R) => void;
-  plans?: readonly P[];
-  /** The plan the server enforces now. Left out (not known yet — kastlan's overview is a
-   *  404 while billing is off), the plan menu still renders, with no row checked; a
-   *  `GET /dev/switch` answers it. */
-  currentPlan?: P;
-  /** Apply a plan — `POST /dev/switch {plan}`, then the overview (§6.3). */
-  onPlan?: (plan: P) => void;
-  /**
-   * The role to offer "Back to {role}" for. Left out, the kit keeps it itself: the role
-   * before the first switch of this browser session, in `sessionStorage` under
-   * `storageKey` — the server answers with the NEW role after a switch, so only the
-   * browser still knows the old one.
-   */
-  originalRole?: R;
-  /** The `sessionStorage` key for the kept role. Default {@link DEV_ORIGINAL_ROLE_KEY};
-   *  an app with several accounts on one browser may scope it per user. */
-  storageKey?: string;
-  /** Billing is off locally: the plan menu says plans change nothing, and stays usable
-   *  (§6.3). */
-  billingOff?: boolean;
-  /** A role's or a plan's words in the menu. Default: the value itself. */
-  roleLabel?: (role: R) => ReactNode;
-  planLabel?: (plan: P) => ReactNode;
-  /** Prop > `<UiKitProvider labels={{ topBarParts: { dev } }}>` > English. */
-  labels?: LabelOverride<DevSwitchersLabels>;
-}
-
-const flask = <FlaskConical className="size-5 text-warning" />;
-
-/** A label's text for a sentence, or the raw value when the label is not text. */
-const textOf = (label: ReactNode, value: string) =>
-  typeof label === "string" || typeof label === "number" ? String(label) : value;
-
-/**
- * The top bar's local-dev switchers (docs/top-bar-harmonization.md §2.7, §6.2, §6.3): the
- * role, then the plan, each a menu behind `RoleSwitcher`'s amber flask. Nothing renders
- * unless `enabled`; either menu renders only with its list and handler.
- *
- * The role menu ends in "Back to {role}" once the role differs from the one the session
- * started with: the dev route needs only a signed-in user, so a switch to a lesser role
- * can always switch back. With `billingOff` the plan menu notes that plans change nothing
- * while billing is off.
- */
-export function DevSwitchers<R extends string, P extends string>({
-  enabled,
-  roles,
-  currentRole: role,
-  onRole,
-  plans,
-  currentPlan: plan,
-  onPlan,
-  originalRole,
-  storageKey = DEV_ORIGINAL_ROLE_KEY,
-  billingOff = false,
-  roleLabel = (r) => r,
-  planLabel = (p) => p,
-  labels: labelsProp,
-}: DevSwitchersProps<R, P>) {
-  const bar = useKitLabels("topBar", DEFAULT_TOP_BAR_LABELS);
-  const words = useTopBarPartsLabels(labelsProp ? { dev: labelsProp } : undefined).dev;
-  const [kept, setKept] = useState<string | null>(() => (enabled ? readKey(storageKey) : null));
-  // 0.43 (keksdose): `enabled` may start false and turn true — an app's GET probe of the
-  // dev route — so the kept role is read again then, or "Back to {role}" is lost after a
-  // reload. Adjusted during render, React's pattern for state that follows a prop.
-  const [wasEnabled, setWasEnabled] = useState(enabled);
-  if (wasEnabled !== enabled) {
-    setWasEnabled(enabled);
-    if (enabled) setKept(readKey(storageKey));
-  }
-  if (!enabled) return null;
-
-  const original = (originalRole ?? kept ?? undefined) as R | undefined;
-
-  const pickRole = (next: R) => {
-    if (originalRole === undefined) {
-      if (next === original) {
-        // Back where the session began: nothing left to go back to.
-        writeKey(storageKey, null);
-        setKept(null);
-      } else if (kept === null && role !== undefined && next !== role) {
-        writeKey(storageKey, role);
-        setKept(role);
-      }
-    }
-    onRole?.(next);
-  };
-
-  const roleMenu =
-    roles && roles.length > 0 && role !== undefined && onRole ? (
-      <TopBarActionMenu
-        icon={flask}
-        aria-label={`${bar.switchRole} · ${bar.role(role)}`}
-        entries={[
-          { kind: "heading", key: "head-role", label: words.roleHeading },
-          ...roles.map(
-            (r): TopBarMenuEntry => ({ key: `role-${r}`, label: roleLabel(r), checked: r === role, onSelect: () => pickRole(r) }),
-          ),
-          ...(original !== undefined && original !== role
-            ? ([
-                { kind: "divider", key: "sep-back" },
-                {
-                  key: "back",
-                  icon: <Undo2 className="size-4" />,
-                  label: words.backTo(textOf(roleLabel(original), original)),
-                  onSelect: () => pickRole(original),
-                },
-              ] satisfies TopBarMenuEntry[])
-            : []),
-        ]}
-      />
-    ) : null;
+// Where it has always been imported from, until the wrapper goes in 0.52; the key and the
+// "Back to" logic it serves are DevMenu's now.
+export { DEV_ORIGINAL_ROLE_KEY } from "./dev-menu";
 
-  const planMenu =
-    plans && plans.length > 0 && onPlan ? (
-      <TopBarActionMenu
-        icon={flask}
-        aria-label={plan !== undefined ? `${words.switchPlan} · ${words.plan(plan)}` : words.switchPlan}
-        entries={[
-          { kind: "heading", key: "head-plan", label: words.planHeading },
-          ...plans.map(
-            (p): TopBarMenuEntry => ({ key: `plan-${p}`, label: planLabel(p), checked: p === plan, onSelect: () => onPlan(p) }),
-          ),
-        ]}
-      >
-        {billingOff
-          ? () => (
-              <li data-dev-billing-off="" className="mt-1 max-w-64 border-t border-subtle px-3 py-2 text-xs text-muted">
-                {words.billingOff}
-              </li>
-            )
-          : undefined}
-      </TopBarActionMenu>
-    ) : null;
+/** @deprecated 0.51 — use {@link DevMenuProps} (the same props); removed in 0.52. */
+export type DevSwitchersProps<R extends string, P extends string> = Omit<DevMenuProps<R, P>, "sections" | "active">;
 
-  return (
-    <>
-      {roleMenu}
-      {planMenu}
-    </>
-  );
+/** @deprecated 0.51 — use {@link DevMenu} (one flask; same props); removed in 0.52. */
+export function DevSwitchers<R extends string, P extends string>(props: DevSwitchersProps<R, P>) {
+  return <DevMenu {...props} />;
 }