@eifi1/ui-kit 0.41.0 → 0.43.0

package/dist/tour/use-tour-progress.js

@@ -0,0 +1,116 @@
+"use client";
+import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
+import { readStored, removeStored, writeStored } from "../lib/safe-storage.js";
+import { isTourDone } from "./tour-info.js";
+const EMPTY = Object.freeze({});
+const listeners = /* @__PURE__ */ new Map();
+const memory = /* @__PURE__ */ new Map();
+const cache = /* @__PURE__ */ new Map();
+function emit(key) {
+  listeners.get(key)?.forEach((listener) => listener());
+}
+function rawOf(key) {
+  return memory.get(key) ?? readStored(key);
+}
+function isKitShape(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  return Object.values(value).every((at) => at === null || typeof at === "string");
+}
+function fromRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const out = {};
+  for (const [id, at] of Object.entries(value)) {
+    if (at === null || at === "") out[id] = null;
+    else if (typeof at === "string") out[id] = at;
+  }
+  return out;
+}
+function parse(raw, migrate) {
+  if (raw === null) return EMPTY;
+  let value = raw;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+  }
+  if (migrate && !isKitShape(value)) {
+    try {
+      const migrated = migrate(value);
+      if (migrated !== void 0) return fromRecord(migrated) ?? EMPTY;
+    } catch {
+    }
+  }
+  return fromRecord(value) ?? EMPTY;
+}
+function snapshot(key, migrate) {
+  const raw = rawOf(key);
+  const hit = cache.get(key);
+  if (hit && hit.raw === raw) return hit.value;
+  const value = parse(raw, migrate);
+  cache.set(key, { raw, value });
+  return value;
+}
+function write(key, record) {
+  const raw = JSON.stringify(record);
+  writeStored(key, raw);
+  if (readStored(key) === raw) memory.delete(key);
+  else memory.set(key, raw);
+  emit(key);
+}
+function subscribe(key, listener) {
+  let set = listeners.get(key);
+  if (!set) listeners.set(key, set = /* @__PURE__ */ new Set());
+  set.add(listener);
+  const onStorage = (event) => {
+    if (event.key !== null && event.key !== key) return;
+    memory.delete(key);
+    listener();
+  };
+  if (typeof window !== "undefined") window.addEventListener("storage", onStorage);
+  return () => {
+    set.delete(listener);
+    if (typeof window !== "undefined") window.removeEventListener("storage", onStorage);
+  };
+}
+function resetTourProgress(storageKey) {
+  removeStored(storageKey);
+  memory.delete(storageKey);
+  cache.delete(storageKey);
+  emit(storageKey);
+}
+function useTourProgress({ storageKey, migrate }) {
+  const migrateRef = useRef(migrate);
+  useEffect(() => {
+    migrateRef.current = migrate;
+  });
+  const completed = useSyncExternalStore(
+    useCallback((listener) => subscribe(storageKey, listener), [storageKey]),
+    () => snapshot(storageKey, migrateRef.current),
+    () => EMPTY
+  );
+  const complete = useCallback(
+    (tour) => {
+      const subject = typeof tour === "string" ? { id: tour } : tour;
+      const current = snapshot(storageKey, migrateRef.current);
+      if (isTourDone(subject, current[subject.id])) return false;
+      write(storageKey, { ...current, [subject.id]: (/* @__PURE__ */ new Date()).toISOString() });
+      return true;
+    },
+    [storageKey]
+  );
+  const reset = useCallback(
+    (id) => {
+      const current = snapshot(storageKey, migrateRef.current);
+      if (current[id] === void 0) return;
+      const next = { ...current };
+      delete next[id];
+      write(storageKey, next);
+    },
+    [storageKey]
+  );
+  return useMemo(() => ({ completed, complete, reset }), [completed, complete, reset]);
+}
+export {
+  resetTourProgress,
+  useTourProgress
+};
+//# sourceMappingURL=use-tour-progress.js.map

package/dist/tour/use-tour-progress.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tour/use-tour-progress.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from \"react\";\nimport { readStored, removeStored, writeStored } from \"../lib/safe-storage\";\nimport { isTourDone, type TourCompletions } from \"./tour-info\";\n\n/**\n * Which tours this device has completed (docs/tours-harmonization.md §2.6, §6.2) —\n * keksdose's `tour-progress-store` and kastlan's `completions.ts`, as one hook.\n *\n * - **Device storage, the app's key.** `storageKey` is always the app's: an app on shared\n *   devices scopes it per account (KS, bench PCs), and an app that lists its keys\n *   (KS `storage-keys.ts`) spells it there. Every access is guarded: a blocked or full\n *   storage keeps the marks for this page's life instead of throwing.\n * - **One store, every reader.** A change notifies every hook on the same key in this tab\n *   (an in-tab emitter) and in other tabs (the `storage` event), so the tours page and\n *   `TourMenu` agree without a reload (ka F3).\n * - **`migrate(raw)`** reads an older shape, so nobody loses their done marks at adoption:\n *   it gets the stored JSON (or the raw text, if it is no JSON) and returns the record for\n *   a shape it recognises, `undefined` for any other — the kit's own shape included,\n *   which it then reads itself. keksdose: zustand's `{state: {completed}, version: 1}`;\n *   kastlan: an array of ids, completed without a date (`null`). It runs only on a stored\n *   text that is not the kit's shape already, once per text and key, whichever reader\n *   reads it first; its identity is ignored. **Define `migrate` once, at module level**,\n *   and hand every reader of the key the same one: readers of one key share one snapshot.\n * - **Resetting the device** (settings §11): register the key with `reset: () =>\n *   resetTourProgress(storageKey)`, which clears storage and the page's memory and tells\n *   every reader in this tab.\n *\n * The kit's own shape is the record itself, `{ [id]: ISO | null }`; an empty string reads\n * as `null` (kastlan's record of 0.42).\n */\nexport interface UseTourProgressOptions {\n  storageKey: string;\n  migrate?: (raw: unknown) => Record<string, string | null> | undefined;\n}\n\nexport interface TourProgress {\n  /** Tour id → the completion's ISO timestamp, or `null` when recorded without a date. */\n  completed: TourCompletions;\n  /**\n   * Record a completion. Keeps the FIRST completion's date, so a replay changes nothing —\n   * unless the tour was reset by an update since (§8): pass the tour (`{id, updated}`) and\n   * a completion from before `updated.date` is replaced by today's.\n   *\n   * Returns `true` when this counts as a new completion — the moment to award the tour's\n   * points and show the app's toast (§6.1) — and `false` for a replay.\n   */\n  complete: (tour: string | { id: string; updated?: { date: string } | null }) => boolean;\n  /** \"Mark as not done\": forget the completion. */\n  reset: (id: string) => void;\n}\n\n/* ── The store: one per key, shared by every hook ───────────────────────────── */\n\nconst EMPTY: TourCompletions = Object.freeze({});\n/** In-tab listeners per key. */\nconst listeners = new Map<string, Set<() => void>>();\n/** What this page wrote where storage refused to keep it (blocked, full): per key. */\nconst memory = new Map<string, string>();\n/**\n * The last raw text read per key and what it parsed to, so a snapshot keeps its identity:\n * the same text gives the same object, whichever reader asks and whatever `migrate` it\n * holds. Several readers of one key with inline `migrate` arrows used to evict each other\n * here and loop (kastlan B1, 0.43).\n */\nconst cache = new Map<string, { raw: string | null; value: TourCompletions }>();\n\nfunction emit(key: string) {\n  listeners.get(key)?.forEach((listener) => listener());\n}\n\nfunction rawOf(key: string): string | null {\n  return memory.get(key) ?? readStored(key);\n}\n\n/** Is this the kit's own shape already: a record whose every value is a string or null? */\nfunction isKitShape(value: unknown): boolean {\n  if (!value || typeof value !== \"object\" || Array.isArray(value)) return false;\n  return Object.values(value as Record<string, unknown>).every((at) => at === null || typeof at === \"string\");\n}\n\n/** The kit's own shape: a record of string or null; anything else is dropped. */\nfunction fromRecord(value: unknown): TourCompletions | undefined {\n  if (!value || typeof value !== \"object\" || Array.isArray(value)) return undefined;\n  const out: Record<string, string | null> = {};\n  for (const [id, at] of Object.entries(value as Record<string, unknown>)) {\n    if (at === null || at === \"\") out[id] = null;\n    else if (typeof at === \"string\") out[id] = at;\n  }\n  return out;\n}\n\nfunction parse(raw: string | null, migrate: UseTourProgressOptions[\"migrate\"]): TourCompletions {\n  if (raw === null) return EMPTY;\n  let value: unknown = raw;\n  try {\n    value = JSON.parse(raw);\n  } catch {\n    // Not JSON: `migrate` still sees the text.\n  }\n  if (migrate && !isKitShape(value)) {\n    try {\n      const migrated = migrate(value);\n      if (migrated !== undefined) return fromRecord(migrated) ?? EMPTY;\n    } catch {\n      // A migrate that throws reads as \"not a shape it knows\".\n    }\n  }\n  return fromRecord(value) ?? EMPTY;\n}\n\nfunction snapshot(key: string, migrate: UseTourProgressOptions[\"migrate\"]): TourCompletions {\n  const raw = rawOf(key);\n  const hit = cache.get(key);\n  if (hit && hit.raw === raw) return hit.value;\n  const value = parse(raw, migrate);\n  cache.set(key, { raw, value });\n  return value;\n}\n\nfunction write(key: string, record: TourCompletions) {\n  const raw = JSON.stringify(record);\n  writeStored(key, raw);\n  // Storage refused it (blocked, full): keep it for this page's life instead.\n  if (readStored(key) === raw) memory.delete(key);\n  else memory.set(key, raw);\n  emit(key);\n}\n\nfunction subscribe(key: string, listener: () => void): () => void {\n  let set = listeners.get(key);\n  if (!set) listeners.set(key, (set = new Set()));\n  set.add(listener);\n  // Another tab wrote (or cleared all storage: `key` null).\n  const onStorage = (event: StorageEvent) => {\n    if (event.key !== null && event.key !== key) return;\n    memory.delete(key);\n    listener();\n  };\n  if (typeof window !== \"undefined\") window.addEventListener(\"storage\", onStorage);\n  return () => {\n    set.delete(listener);\n    if (typeof window !== \"undefined\") window.removeEventListener(\"storage\", onStorage);\n  };\n}\n\n/**\n * Forget every tour completion under `storageKey` on this device: the stored key, what the\n * page kept in memory where storage refused it, and every reader in this tab moves at\n * once. For \"Reset this device's settings\" (settings §11):\n *\n *     registerDeviceSetting({ key: TOUR_KEY, kind: \"view\", reset: () => resetTourProgress(TOUR_KEY) });\n */\nexport function resetTourProgress(storageKey: string): void {\n  removeStored(storageKey);\n  memory.delete(storageKey);\n  cache.delete(storageKey);\n  emit(storageKey);\n}\n\n/** The device's tour completions under `storageKey`; see {@link UseTourProgressOptions}. */\nexport function useTourProgress({ storageKey, migrate }: UseTourProgressOptions): TourProgress {\n  // Held, not depended on: an inline arrow is a new function every render, and neither the\n  // snapshot nor the callbacks may change with it.\n  const migrateRef = useRef(migrate);\n  useEffect(() => {\n    migrateRef.current = migrate;\n  });\n  const completed = useSyncExternalStore(\n    useCallback((listener: () => void) => subscribe(storageKey, listener), [storageKey]),\n    () => snapshot(storageKey, migrateRef.current),\n    () => EMPTY,\n  );\n\n  const complete = useCallback(\n    (tour: string | { id: string; updated?: { date: string } | null }) => {\n      const subject = typeof tour === \"string\" ? { id: tour } : tour;\n      // Read now rather than from the render: two completions in one handler both count.\n      const current = snapshot(storageKey, migrateRef.current);\n      if (isTourDone(subject, current[subject.id])) return false;\n      write(storageKey, { ...current, [subject.id]: new Date().toISOString() });\n      return true;\n    },\n    [storageKey],\n  );\n\n  const reset = useCallback(\n    (id: string) => {\n      const current = snapshot(storageKey, migrateRef.current);\n      if (current[id] === undefined) return;\n      const next = { ...current };\n      delete next[id];\n      write(storageKey, next);\n    },\n    [storageKey],\n  );\n\n  return useMemo(() => ({ completed, complete, reset }), [completed, complete, reset]);\n}\n"],"mappings":";AAAA,SAAS,aAAa,WAAW,SAAS,QAAQ,4BAA4B;AAC9E,SAAS,YAAY,cAAc,mBAAmB;AACtD,SAAS,kBAAwC;AAmDjD,MAAM,QAAyB,OAAO,OAAO,CAAC,CAAC;AAE/C,MAAM,YAAY,oBAAI,IAA6B;AAEnD,MAAM,SAAS,oBAAI,IAAoB;AAOvC,MAAM,QAAQ,oBAAI,IAA4D;AAE9E,SAAS,KAAK,KAAa;AACzB,YAAU,IAAI,GAAG,GAAG,QAAQ,CAAC,aAAa,SAAS,CAAC;AACtD;AAEA,SAAS,MAAM,KAA4B;AACzC,SAAO,OAAO,IAAI,GAAG,KAAK,WAAW,GAAG;AAC1C;AAGA,SAAS,WAAW,OAAyB;AAC3C,MAAI,CAAC,SAAS,OAAO,UAAU,YAAY,MAAM,QAAQ,KAAK,EAAG,QAAO;AACxE,SAAO,OAAO,OAAO,KAAgC,EAAE,MAAM,CAAC,OAAO,OAAO,QAAQ,OAAO,OAAO,QAAQ;AAC5G;AAGA,SAAS,WAAW,OAA6C;AAC/D,MAAI,CAAC,SAAS,OAAO,UAAU,YAAY,MAAM,QAAQ,KAAK,EAAG,QAAO;AACxE,QAAM,MAAqC,CAAC;AAC5C,aAAW,CAAC,IAAI,EAAE,KAAK,OAAO,QAAQ,KAAgC,GAAG;AACvE,QAAI,OAAO,QAAQ,OAAO,GAAI,KAAI,EAAE,IAAI;AAAA,aAC/B,OAAO,OAAO,SAAU,KAAI,EAAE,IAAI;AAAA,EAC7C;AACA,SAAO;AACT;AAEA,SAAS,MAAM,KAAoB,SAA6D;AAC9F,MAAI,QAAQ,KAAM,QAAO;AACzB,MAAI,QAAiB;AACrB,MAAI;AACF,YAAQ,KAAK,MAAM,GAAG;AAAA,EACxB,QAAQ;AAAA,EAER;AACA,MAAI,WAAW,CAAC,WAAW,KAAK,GAAG;AACjC,QAAI;AACF,YAAM,WAAW,QAAQ,KAAK;AAC9B,UAAI,aAAa,OAAW,QAAO,WAAW,QAAQ,KAAK;AAAA,IAC7D,QAAQ;AAAA,IAER;AAAA,EACF;AACA,SAAO,WAAW,KAAK,KAAK;AAC9B;AAEA,SAAS,SAAS,KAAa,SAA6D;AAC1F,QAAM,MAAM,MAAM,GAAG;AACrB,QAAM,MAAM,MAAM,IAAI,GAAG;AACzB,MAAI,OAAO,IAAI,QAAQ,IAAK,QAAO,IAAI;AACvC,QAAM,QAAQ,MAAM,KAAK,OAAO;AAChC,QAAM,IAAI,KAAK,EAAE,KAAK,MAAM,CAAC;AAC7B,SAAO;AACT;AAEA,SAAS,MAAM,KAAa,QAAyB;AACnD,QAAM,MAAM,KAAK,UAAU,MAAM;AACjC,cAAY,KAAK,GAAG;AAEpB,MAAI,WAAW,GAAG,MAAM,IAAK,QAAO,OAAO,GAAG;AAAA,MACzC,QAAO,IAAI,KAAK,GAAG;AACxB,OAAK,GAAG;AACV;AAEA,SAAS,UAAU,KAAa,UAAkC;AAChE,MAAI,MAAM,UAAU,IAAI,GAAG;AAC3B,MAAI,CAAC,IAAK,WAAU,IAAI,KAAM,MAAM,oBAAI,IAAI,CAAE;AAC9C,MAAI,IAAI,QAAQ;AAEhB,QAAM,YAAY,CAAC,UAAwB;AACzC,QAAI,MAAM,QAAQ,QAAQ,MAAM,QAAQ,IAAK;AAC7C,WAAO,OAAO,GAAG;AACjB,aAAS;AAAA,EACX;AACA,MAAI,OAAO,WAAW,YAAa,QAAO,iBAAiB,WAAW,SAAS;AAC/E,SAAO,MAAM;AACX,QAAI,OAAO,QAAQ;AACnB,QAAI,OAAO,WAAW,YAAa,QAAO,oBAAoB,WAAW,SAAS;AAAA,EACpF;AACF;AASO,SAAS,kBAAkB,YAA0B;AAC1D,eAAa,UAAU;AACvB,SAAO,OAAO,UAAU;AACxB,QAAM,OAAO,UAAU;AACvB,OAAK,UAAU;AACjB;AAGO,SAAS,gBAAgB,EAAE,YAAY,QAAQ,GAAyC;AAG7F,QAAM,aAAa,OAAO,OAAO;AACjC,YAAU,MAAM;AACd,eAAW,UAAU;AAAA,EACvB,CAAC;AACD,QAAM,YAAY;AAAA,IAChB,YAAY,CAAC,aAAyB,UAAU,YAAY,QAAQ,GAAG,CAAC,UAAU,CAAC;AAAA,IACnF,MAAM,SAAS,YAAY,WAAW,OAAO;AAAA,IAC7C,MAAM;AAAA,EACR;AAEA,QAAM,WAAW;AAAA,IACf,CAAC,SAAqE;AACpE,YAAM,UAAU,OAAO,SAAS,WAAW,EAAE,IAAI,KAAK,IAAI;AAE1D,YAAM,UAAU,SAAS,YAAY,WAAW,OAAO;AACvD,UAAI,WAAW,SAAS,QAAQ,QAAQ,EAAE,CAAC,EAAG,QAAO;AACrD,YAAM,YAAY,EAAE,GAAG,SAAS,CAAC,QAAQ,EAAE,IAAG,oBAAI,KAAK,GAAE,YAAY,EAAE,CAAC;AACxE,aAAO;AAAA,IACT;AAAA,IACA,CAAC,UAAU;AAAA,EACb;AAEA,QAAM,QAAQ;AAAA,IACZ,CAAC,OAAe;AACd,YAAM,UAAU,SAAS,YAAY,WAAW,OAAO;AACvD,UAAI,QAAQ,EAAE,MAAM,OAAW;AAC/B,YAAM,OAAO,EAAE,GAAG,QAAQ;AAC1B,aAAO,KAAK,EAAE;AACd,YAAM,YAAY,IAAI;AAAA,IACxB;AAAA,IACA,CAAC,UAAU;AAAA,EACb;AAEA,SAAO,QAAQ,OAAO,EAAE,WAAW,UAAU,MAAM,IAAI,CAAC,WAAW,UAAU,KAAK,CAAC;AACrF;","names":[]}

package/dist/tour/use-tour-url-sync.d.ts

@@ -0,0 +1,58 @@
+export interface UseTourUrlSyncOptions {
+    /**
+     * Start the tour `id` at `startIndex` (0-based) — the app's launcher, which builds the
+     * steps, awaits its own `prepare()` and passes `onFinish` (the completion, the points
+     * toast) to `useTour().start`. An unknown id should do nothing. May return a promise:
+     * the parameters are kept until it settles.
+     */
+    launch: (id: string, options: {
+        startIndex: number;
+    }) => void | Promise<unknown>;
+    /**
+     * Are the facts a tour's steps are built from loaded yet (keksdose's `ready`: the
+     * caches a branching tour reads)? A deep link waits for it, keeping its parameters, so
+     * an F5 mid-tour resumes the right variant at the right step. Default `true`.
+     */
+    ready?: boolean;
+    /**
+     * Older names of `tourStep`, read when it is absent and removed with it — kastlan's
+     * `ts` (§2.7, for one minor). Their value is a 0-based step index, as kastlan wrote it.
+     */
+    stepAliases?: readonly string[];
+}
+/**
+ * Tours and the URL (docs/tours-harmonization.md §2.7, §6.4) — keksdose's `TourUrlSync`,
+ * on the kit's engine (`useTourOptional`):
+ *
+ * - **`?tour=<id>` starts that tour whenever it APPEARS** — on load, and on in-app
+ *   navigation too (kastlan's assistant links to `/help/tours?tour=<id>`, ka F4) —
+ *   resuming at `&tourStep=<n>` (1-based). It waits for `ready`.
+ * - **While a tour runs, `?tour=&tourStep=` mirror where it is**, so a reload or a copied
+ *   link pins the step (kk K-3). A step that navigates drops them; this puts them back.
+ * - **At the end it strips only its own parameters**; `?q=`, `?state=` and the hash stay.
+ *
+ * Mount it once inside the router and the `TourProvider`. Without a provider it still
+ * launches through `launch` and never mirrors.
+ */
+export declare function useTourUrlSync({ launch, ready, stepAliases }: UseTourUrlSyncOptions): void;
+/** The catalogue's state filter. */
+export type TourStateFilter = "all" | "todo" | "done";
+/** The catalogue's filters: the search, the group (`null`: every group), the state. */
+export interface TourCatalogueFilter {
+    query: string;
+    group: string | null;
+    state: TourStateFilter;
+}
+/**
+ * The catalogue's filters in the URL (§2.8) — keksdose's `?q`, `?topic`, `?state`, each
+ * written with `replace` (typing does not bury the Back button), the defaults as the
+ * clean URL. Spread it onto the catalogue: `<TourCatalogue {...useTourCatalogueUrlState()} … />`.
+ * `params` renames them (kastlan's `?group`). Requires a react-router Router.
+ */
+export declare function useTourCatalogueUrlState(params?: {
+    query?: string;
+    group?: string;
+    state?: string;
+}): TourCatalogueFilter & {
+    onChange: (patch: Partial<TourCatalogueFilter>) => void;
+};

package/dist/tour/use-tour-url-sync.js

@@ -0,0 +1,110 @@
+"use client";
+import { createContext, useContext, useEffect, useLayoutEffect, useRef, useState } from "react";
+import * as ReactRouter from "react-router";
+import { useLocation, useNavigate } from "react-router";
+import { useSearchParamsState } from "../hooks/use-search-param-state.js";
+import { useTourOptional } from "./tour.js";
+function navigationInFlight(history, dataRouter, rendered) {
+  const state = dataRouter?.router?.state;
+  if (state && (state.navigation?.state ?? "idle") !== "idle") return true;
+  const live = state?.location ?? history?.location;
+  if (!live) return false;
+  return live.pathname !== rendered.pathname || (live.search ?? "") !== rendered.search || (live.hash ?? "") !== rendered.hash;
+}
+const NO_NAVIGATION = createContext(null);
+const NO_DATA_ROUTER = createContext(null);
+const DataRouterContext = (() => {
+  try {
+    return ReactRouter.UNSAFE_DataRouterContext ?? NO_DATA_ROUTER;
+  } catch {
+    return NO_DATA_ROUTER;
+  }
+})();
+const NavigationContext = (() => {
+  try {
+    return ReactRouter.UNSAFE_NavigationContext ?? NO_NAVIGATION;
+  } catch {
+    return NO_NAVIGATION;
+  }
+})();
+function stepOf(params, aliases) {
+  const step = Number(params.get("tourStep"));
+  if (params.has("tourStep")) return Number.isFinite(step) && step > 0 ? step - 1 : 0;
+  for (const alias of aliases) {
+    const value = Number(params.get(alias));
+    if (params.has(alias)) return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+  }
+  return 0;
+}
+function useTourUrlSync({ launch, ready = true, stepAliases = [] }) {
+  const navigate = useNavigate();
+  const location = useLocation();
+  const { pathname, search, hash } = location;
+  const history = useContext(NavigationContext)?.navigator;
+  const dataRouter = useContext(DataRouterContext);
+  const engine = useTourOptional();
+  const active = engine?.active ?? false;
+  const activeId = engine?.activeId ?? null;
+  const index = engine?.index ?? 0;
+  const urlTour = new URLSearchParams(search).get("tour");
+  const aliases = stepAliases.join("\n");
+  const launchRef = useRef(launch);
+  const activeIdRef = useRef(activeId);
+  useLayoutEffect(() => {
+    launchRef.current = launch;
+    activeIdRef.current = active ? activeId : null;
+  });
+  const seenRef = useRef(null);
+  const pendingRef = useRef(null);
+  const launchingRef = useRef(false);
+  const [settled, setSettled] = useState(0);
+  useEffect(() => {
+    if (urlTour !== seenRef.current) {
+      seenRef.current = urlTour;
+      pendingRef.current = urlTour && urlTour !== activeIdRef.current ? { id: urlTour, startIndex: stepOf(new URLSearchParams(search), aliases ? aliases.split("\n") : []) } : null;
+    }
+    const pending = pendingRef.current;
+    if (!pending || !ready) return;
+    pendingRef.current = null;
+    launchingRef.current = true;
+    void Promise.resolve().then(() => launchRef.current(pending.id, { startIndex: pending.startIndex })).catch(() => void 0).finally(() => {
+      launchingRef.current = false;
+      setSettled((n) => n + 1);
+    });
+  }, [urlTour, ready]);
+  useEffect(() => {
+    if (navigationInFlight(history, dataRouter, { pathname, search, hash })) return;
+    if (pendingRef.current || launchingRef.current) return;
+    const tourId = active && activeId ? activeId : null;
+    const own = ["tour", "tourStep", ...aliases ? aliases.split("\n") : []];
+    const current = new URLSearchParams(search);
+    if (!tourId && !own.some((key) => current.has(key))) return;
+    const next = new URLSearchParams(search);
+    for (const key of tourId ? own.slice(2) : own) next.delete(key);
+    if (tourId) {
+      next.set("tour", tourId);
+      next.set("tourStep", String(index + 1));
+    }
+    if (next.toString() === current.toString()) return;
+    void navigate({ pathname, search: next.toString(), hash }, { replace: true, state: location.state });
+  }, [active, activeId, index, pathname, search, hash, settled, aliases]);
+}
+const STATES = ["all", "todo", "done"];
+function useTourCatalogueUrlState(params = {}) {
+  const [filter, setFilter] = useSearchParamsState({
+    query: { param: params.query ?? "q", default: "", history: "replace" },
+    group: { param: params.group ?? "topic", default: null, history: "replace", parse: (raw) => raw || void 0 },
+    state: {
+      param: params.state ?? "state",
+      default: "all",
+      history: "replace",
+      parse: (raw) => STATES.find((x) => x === raw)
+    }
+  });
+  return { ...filter, onChange: setFilter };
+}
+export {
+  useTourCatalogueUrlState,
+  useTourUrlSync
+};
+//# sourceMappingURL=use-tour-url-sync.js.map

package/dist/tour/use-tour-url-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tour/use-tour-url-sync.ts"],"sourcesContent":["import { createContext, useContext, useEffect, useLayoutEffect, useRef, useState, type Context } from \"react\";\nimport * as ReactRouter from \"react-router\";\nimport { useLocation, useNavigate, type Navigator } from \"react-router\";\nimport { useSearchParamsState } from \"../hooks/use-search-param-state\";\nimport { useTourOptional } from \"./tour\";\n\n/* ── useTourUrlSync ─────────────────────────────────────────────────────────── */\n\nexport interface UseTourUrlSyncOptions {\n  /**\n   * Start the tour `id` at `startIndex` (0-based) — the app's launcher, which builds the\n   * steps, awaits its own `prepare()` and passes `onFinish` (the completion, the points\n   * toast) to `useTour().start`. An unknown id should do nothing. May return a promise:\n   * the parameters are kept until it settles.\n   */\n  launch: (id: string, options: { startIndex: number }) => void | Promise<unknown>;\n  /**\n   * Are the facts a tour's steps are built from loaded yet (keksdose's `ready`: the\n   * caches a branching tour reads)? A deep link waits for it, keeping its parameters, so\n   * an F5 mid-tour resumes the right variant at the right step. Default `true`.\n   */\n  ready?: boolean;\n  /**\n   * Older names of `tourStep`, read when it is absent and removed with it — kastlan's\n   * `ts` (§2.7, for one minor). Their value is a 0-based step index, as kastlan wrote it.\n   */\n  stepAliases?: readonly string[];\n}\n\ntype Place = { pathname: string; search: string; hash: string };\n\n/**\n * Has the router already moved on from the location React is still rendering?\n * keksdose's check (tour-url-sync.tsx, tours audit 2026-10-02): a mirror write built\n * from the page being LEFT is a replace back onto it, which cancels a step's `go()`.\n *\n * - A data router (`createBrowserRouter`, kastlan): its navigator has no location (build\n *   review 0.43, kastlan A2), so the router's own state answers — a navigation still\n *   loading, or a location it has committed that React has not rendered yet.\n * - A declarative router (`BrowserRouter`, keksdose): its navigator is its history and\n *   carries where it is.\n * - Anything else answers \"not in flight\".\n */\nfunction navigationInFlight(history: Navigator | undefined, dataRouter: DataRouterProbe, rendered: Place) {\n  const state = dataRouter?.router?.state;\n  if (state && (state.navigation?.state ?? \"idle\") !== \"idle\") return true;\n  const live = state?.location ?? (history as (Navigator & { location?: Partial<Place> }) | undefined)?.location;\n  if (!live) return false;\n  return (\n    live.pathname !== rendered.pathname || (live.search ?? \"\") !== rendered.search || (live.hash ?? \"\") !== rendered.hash\n  );\n}\n\ntype NavigationProbe = { navigator?: Navigator } | null;\nconst NO_NAVIGATION = createContext<NavigationProbe>(null);\n/** The data router's state, as `useSearchParamState` reads it. */\ntype DataRouterProbe = {\n  router?: { state?: { navigation?: { state?: string }; location?: Partial<Place> } };\n} | null;\nconst NO_DATA_ROUTER = createContext<DataRouterProbe>(null);\nconst DataRouterContext: Context<DataRouterProbe> = (() => {\n  try {\n    return (\n      (ReactRouter as unknown as { UNSAFE_DataRouterContext?: Context<DataRouterProbe> }).UNSAFE_DataRouterContext ??\n      NO_DATA_ROUTER\n    );\n  } catch {\n    return NO_DATA_ROUTER;\n  }\n})();\n/** Read off the namespace inside a `try`, as `useSearchParamState` reads the data router:\n *  a test's partial `vi.mock(\"react-router\")` throws on an export it does not define. */\nconst NavigationContext: Context<NavigationProbe> = (() => {\n  try {\n    return (\n      (ReactRouter as unknown as { UNSAFE_NavigationContext?: Context<NavigationProbe> }).UNSAFE_NavigationContext ??\n      NO_NAVIGATION\n    );\n  } catch {\n    return NO_NAVIGATION;\n  }\n})();\n\n/** The step a link asks for, 0-based: `tourStep` is 1-based (keksdose), an alias 0-based. */\nfunction stepOf(params: URLSearchParams, aliases: readonly string[]): number {\n  const step = Number(params.get(\"tourStep\"));\n  if (params.has(\"tourStep\")) return Number.isFinite(step) && step > 0 ? step - 1 : 0;\n  for (const alias of aliases) {\n    const value = Number(params.get(alias));\n    if (params.has(alias)) return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;\n  }\n  return 0;\n}\n\n/**\n * Tours and the URL (docs/tours-harmonization.md §2.7, §6.4) — keksdose's `TourUrlSync`,\n * on the kit's engine (`useTourOptional`):\n *\n * - **`?tour=<id>` starts that tour whenever it APPEARS** — on load, and on in-app\n *   navigation too (kastlan's assistant links to `/help/tours?tour=<id>`, ka F4) —\n *   resuming at `&tourStep=<n>` (1-based). It waits for `ready`.\n * - **While a tour runs, `?tour=&tourStep=` mirror where it is**, so a reload or a copied\n *   link pins the step (kk K-3). A step that navigates drops them; this puts them back.\n * - **At the end it strips only its own parameters**; `?q=`, `?state=` and the hash stay.\n *\n * Mount it once inside the router and the `TourProvider`. Without a provider it still\n * launches through `launch` and never mirrors.\n */\nexport function useTourUrlSync({ launch, ready = true, stepAliases = [] }: UseTourUrlSyncOptions): void {\n  const navigate = useNavigate();\n  const location = useLocation();\n  const { pathname, search, hash } = location;\n  const history = useContext(NavigationContext)?.navigator;\n  const dataRouter = useContext(DataRouterContext);\n  const engine = useTourOptional();\n  const active = engine?.active ?? false;\n  const activeId = engine?.activeId ?? null;\n  const index = engine?.index ?? 0;\n  const urlTour = new URLSearchParams(search).get(\"tour\");\n  const aliases = stepAliases.join(\"\\n\");\n\n  const launchRef = useRef(launch);\n  const activeIdRef = useRef(activeId);\n  useLayoutEffect(() => {\n    launchRef.current = launch;\n    activeIdRef.current = active ? activeId : null;\n  });\n  /** The `tour` value last seen in the URL: a tour starts when it CHANGES to an id. */\n  const seenRef = useRef<string | null>(null);\n  /** A deep link waiting for `ready`. */\n  const pendingRef = useRef<{ id: string; startIndex: number } | null>(null);\n  /** A launch under way (an app's `prepare()`). */\n  const launchingRef = useRef(false);\n  /** Bumped when a launch settles, so the mirror looks again. */\n  const [settled, setSettled] = useState(0);\n\n  useEffect(() => {\n    if (urlTour !== seenRef.current) {\n      seenRef.current = urlTour;\n      // Its own mirror writing the running tour back is no new link.\n      pendingRef.current =\n        urlTour && urlTour !== activeIdRef.current\n          ? { id: urlTour, startIndex: stepOf(new URLSearchParams(search), aliases ? aliases.split(\"\\n\") : []) }\n          : null;\n    }\n    const pending = pendingRef.current;\n    if (!pending || !ready) return;\n    pendingRef.current = null;\n    launchingRef.current = true;\n    void Promise.resolve()\n      .then(() => launchRef.current(pending.id, { startIndex: pending.startIndex }))\n      .catch(() => undefined)\n      .finally(() => {\n        launchingRef.current = false;\n        setSettled((n) => n + 1);\n      });\n    // Only a change of the parameter, or readiness, starts a tour.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [urlTour, ready]);\n\n  useEffect(() => {\n    if (navigationInFlight(history, dataRouter, { pathname, search, hash })) return;\n    // A link not yet used keeps its parameters: a reload in that window resumes.\n    if (pendingRef.current || launchingRef.current) return;\n    const tourId = active && activeId ? activeId : null;\n    const own = [\"tour\", \"tourStep\", ...(aliases ? aliases.split(\"\\n\") : [])];\n    const current = new URLSearchParams(search);\n    // Nothing to mirror and nothing to strip: never touch the URL (a no-op replace\n    // clobbers a page's own just-issued navigation, keksdose feedback #4).\n    if (!tourId && !own.some((key) => current.has(key))) return;\n    const next = new URLSearchParams(search);\n    // `set` keeps a parameter where it stands; only the aliases (and, at the end, the\n    // tour's own) go.\n    for (const key of tourId ? own.slice(2) : own) next.delete(key);\n    if (tourId) {\n      next.set(\"tour\", tourId);\n      next.set(\"tourStep\", String(index + 1));\n    }\n    if (next.toString() === current.toString()) return;\n    // Spelled out, not `setSearchParams` (\"?…\" drops the hash, keksdose dev#495).\n    void navigate({ pathname, search: next.toString(), hash }, { replace: true, state: location.state });\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [active, activeId, index, pathname, search, hash, settled, aliases]);\n}\n\n/* ── useTourCatalogueUrlState ───────────────────────────────────────────────── */\n\n/** The catalogue's state filter. */\nexport type TourStateFilter = \"all\" | \"todo\" | \"done\";\n\n/** The catalogue's filters: the search, the group (`null`: every group), the state. */\nexport interface TourCatalogueFilter {\n  query: string;\n  group: string | null;\n  state: TourStateFilter;\n}\n\nconst STATES: readonly TourStateFilter[] = [\"all\", \"todo\", \"done\"];\n\n/**\n * The catalogue's filters in the URL (§2.8) — keksdose's `?q`, `?topic`, `?state`, each\n * written with `replace` (typing does not bury the Back button), the defaults as the\n * clean URL. Spread it onto the catalogue: `<TourCatalogue {...useTourCatalogueUrlState()} … />`.\n * `params` renames them (kastlan's `?group`). Requires a react-router Router.\n */\nexport function useTourCatalogueUrlState(\n  params: { query?: string; group?: string; state?: string } = {},\n): TourCatalogueFilter & { onChange: (patch: Partial<TourCatalogueFilter>) => void } {\n  const [filter, setFilter] = useSearchParamsState<TourCatalogueFilter>({\n    query: { param: params.query ?? \"q\", default: \"\", history: \"replace\" },\n    group: { param: params.group ?? \"topic\", default: null, history: \"replace\", parse: (raw) => raw || undefined },\n    state: {\n      param: params.state ?? \"state\",\n      default: \"all\",\n      history: \"replace\",\n      parse: (raw) => STATES.find((x) => x === raw),\n    },\n  });\n  // `group: null` is a value to the setter (it clears `?topic`); `undefined` leaves it.\n  return { ...filter, onChange: setFilter };\n}\n"],"mappings":"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","names":[]}

package/dist/tour.d.ts

@@ -1 +1,9 @@
 export * from "./tour/tour.js";
+export { TourCatalogue, TourCatalogueCard, DEFAULT_TOUR_CATALOGUE_LABELS } from "./tour/tour-catalogue.js";
+export type { TourCatalogueProps, TourCatalogueCardProps, TourCatalogueLabels } from "./tour/tour-catalogue.js";
+export { isTourNew, isTourReset, isTourDone, doneCount, earnedPoints } from "./tour/tour-info.js";
+export type { TourInfo, TourGroup, TourUpdate, TourCompletions } from "./tour/tour-info.js";
+export { useTourProgress, resetTourProgress } from "./tour/use-tour-progress.js";
+export type { UseTourProgressOptions, TourProgress } from "./tour/use-tour-progress.js";
+export { useTourUrlSync, useTourCatalogueUrlState } from "./tour/use-tour-url-sync.js";
+export type { UseTourUrlSyncOptions, TourCatalogueFilter, TourStateFilter } from "./tour/use-tour-url-sync.js";

package/dist/tour.js

@@ -1,3 +1,21 @@
 "use client";
 export * from "./tour/tour.js";
+import { TourCatalogue, TourCatalogueCard, DEFAULT_TOUR_CATALOGUE_LABELS } from "./tour/tour-catalogue.js";
+import { isTourNew, isTourReset, isTourDone, doneCount, earnedPoints } from "./tour/tour-info.js";
+import { useTourProgress, resetTourProgress } from "./tour/use-tour-progress.js";
+import { useTourUrlSync, useTourCatalogueUrlState } from "./tour/use-tour-url-sync.js";
+export {
+  DEFAULT_TOUR_CATALOGUE_LABELS,
+  TourCatalogue,
+  TourCatalogueCard,
+  doneCount,
+  earnedPoints,
+  isTourDone,
+  isTourNew,
+  isTourReset,
+  resetTourProgress,
+  useTourCatalogueUrlState,
+  useTourProgress,
+  useTourUrlSync
+};
 //# sourceMappingURL=tour.js.map

package/dist/tour.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/tour.ts"],"sourcesContent":["// `@eifi1/ui-kit/tour` — guided tours.\n// A re-slicing of the main barrel, not a new API.\nexport * from \"./tour/tour\";\n"],"mappings":";AAEA,cAAc;","names":[]}
+{"version":3,"sources":["../src/tour.ts"],"sourcesContent":["// `@eifi1/ui-kit/tour` — guided tours.\n// A re-slicing of the main barrel, not a new API.\nexport * from \"./tour/tour\";\n// 0.43.0: the tours page (docs/tours-harmonization.md §3, §8) — keksdose's catalogue, its\n// card, the NEW and reset rules, device progress and the URL. `useTourUrlSync` and\n// `useTourCatalogueUrlState` need react-router (a peer already, for /shell).\nexport { TourCatalogue, TourCatalogueCard, DEFAULT_TOUR_CATALOGUE_LABELS } from \"./tour/tour-catalogue\";\nexport type { TourCatalogueProps, TourCatalogueCardProps, TourCatalogueLabels } from \"./tour/tour-catalogue\";\nexport { isTourNew, isTourReset, isTourDone, doneCount, earnedPoints } from \"./tour/tour-info\";\nexport type { TourInfo, TourGroup, TourUpdate, TourCompletions } from \"./tour/tour-info\";\nexport { useTourProgress, resetTourProgress } from \"./tour/use-tour-progress\";\nexport type { UseTourProgressOptions, TourProgress } from \"./tour/use-tour-progress\";\nexport { useTourUrlSync, useTourCatalogueUrlState } from \"./tour/use-tour-url-sync\";\nexport type { UseTourUrlSyncOptions, TourCatalogueFilter, TourStateFilter } from \"./tour/use-tour-url-sync\";\n"],"mappings":";AAEA,cAAc;AAId,SAAS,eAAe,mBAAmB,qCAAqC;AAEhF,SAAS,WAAW,aAAa,YAAY,WAAW,oBAAoB;AAE5E,SAAS,iBAAiB,yBAAyB;AAEnD,SAAS,gBAAgB,gCAAgC;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eifi1/ui-kit",
-  "version": "0.41.0",
+  "version": "0.43.0",
   "type": "module",
   "description": "App-agnostic shared design system: domain-free React components, theme and tokens.",
   "_sideEffects": "The barrel (src/index.ts) re-exports EVERY component, including components/chart, which statically imports recharts. Without this field a bundler must assume each of those modules has side effects, so it cannot drop the unused ones: importing a Button from '@eifi1/ui-kit' dragged all 433KB of recharts into the consumer's ENTRY chunk, and Keksdose was preloading it on every page load, login included. Nothing in src/ imports for side effects (no bare imports, no CSS imports from JS, no module-level global writes) — the token stylesheet is its own './tokens.css' export — so this is safe. CSS is still listed so any future stylesheet survives. Re-checked when `flag-icons` left `dependencies` and tsup started emitting a `\"use client\"` banner: neither touches this. The flag stylesheet was never imported from JS in the first place (that was the finding), and a directive prologue is a string literal every bundler lifts out before it decides whether a module is inert.",

package/src/admin/admin-area-labels.ts

@@ -0,0 +1,91 @@
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
+import type { SettingsGroupLabels } from "../settings/settings-labels";
+
+/**
+ * The `adminArea` namespace (0.42, docs/admin-harmonization.md §3.1): the kit's words of
+ * the admin area every app shares — the account menu's "Administration" row, the 403
+ * page, the shared sections' names and help lines, the overview's tiles and the Tools
+ * list. A module of words with no component code, like every `*-labels.ts` (0.34, KS U8).
+ * An app's own sections and tiles bring their own words.
+ */
+
+/** The sections every app's admin area shares, in the template's order (§2.3). */
+export type AdminSharedSection = "overview" | "users" | "invitations" | "billing" | "activity";
+
+/** The overview's shared tiles (§2.4, §6.1). */
+export interface AdminTileLabels {
+  /** `feedback_waiting`: OPEN reports, crash reports included (§6.1). */
+  feedbackWaiting: string;
+  /** `deletion_requests`. */
+  deletionRequests: string;
+  /** `invitations_pending`. */
+  invitationsPending: string;
+  /** `users_total`. */
+  users: string;
+  /** `users_new_7d`, the line under the users tile. */
+  usersNew: (count: number) => string;
+}
+
+export interface AdminAreaLabels {
+  /** "Administration": the account menu's row, and the admin page's heading. */
+  title: string;
+  /** The row's waiting count, for a reader ("Administration, 3 waiting"); the eye sees
+   *  the number in the badge. */
+  waiting: (count: number) => string;
+  /** The 403 page's heading (§2.2 decision 8). */
+  forbiddenTitle: string;
+  /**
+   * Under it. Says only that THIS area is closed to the account — never that the person
+   * administers nothing anywhere (§6.7: a kastlan superuser who isn't ADMIN in the acting
+   * company gets this page).
+   */
+  forbiddenBody: (appName: string) => string;
+  /** The button back to the app's start, unless the app names its own (`homeLabel`). */
+  forbiddenHome: string;
+  /** A reviewer's second way out, to the translations review. */
+  forbiddenReviewer: string;
+  /** The shared sections' names and help lines (§2.3 decision 11). */
+  sections: Record<AdminSharedSection, SettingsGroupLabels>;
+  /** The overview's tiles. */
+  tiles: AdminTileLabels;
+  /** 0.43: `AdminOverview`'s `error` — the counts could not be loaded. */
+  overviewError: string;
+  /** 0.43: its button, which calls `onRetry`. */
+  retry: string;
+  /** The Tools list's heading and name (§2.5 decision 16). */
+  tools: string;
+}
+
+export const DEFAULT_ADMIN_AREA_LABELS: AdminAreaLabels = {
+  title: "Administration",
+  waiting: (count) => `${count} waiting`,
+  forbiddenTitle: "Only for administrators",
+  forbiddenBody: (appName) => `This is where administrators run ${appName}. Your account cannot open this page.`,
+  forbiddenHome: "Go to the start page",
+  forbiddenReviewer: "Review translations",
+  sections: {
+    overview: { title: "Overview", help: "What is waiting, at a glance." },
+    users: { title: "Users", help: "Who has an account, and what each may do." },
+    invitations: { title: "Invitations", help: "Invite people by e-mail in their language; resend or revoke what’s still open." },
+    billing: { title: "Billing", help: "The plan, the payment and the invoices." },
+    activity: { title: "Activity", help: "What the admins did, newest first." },
+  },
+  tiles: {
+    feedbackWaiting: "To triage",
+    deletionRequests: "Deletion requests",
+    invitationsPending: "Pending invitations",
+    users: "Users",
+    usersNew: (count) => `${count} new in 7 days`,
+  },
+  overviewError: "The overview couldn’t be loaded.",
+  retry: "Try again",
+  tools: "Tools",
+};
+
+/**
+ * The `adminArea` namespace, resolved — English, then the provider, then `labels`. What
+ * an app reads to hand {@link adminSections} its words from inside a component.
+ */
+export function useAdminAreaLabels(labels?: LabelOverride<AdminAreaLabels>): AdminAreaLabels {
+  return useKitLabels("adminArea", DEFAULT_ADMIN_AREA_LABELS, labels);
+}

package/src/admin/admin-forbidden.tsx

@@ -0,0 +1,75 @@
+import type { ComponentPropsWithRef } from "react";
+import { ShieldAlert } from "lucide-react";
+import { cn } from "../lib/cn";
+import { Button } from "../components/button";
+import { EmptyState } from "../components/empty-state";
+import type { LabelOverride } from "../i18n/kit-labels";
+import { useAdminAreaLabels } from "./admin-area-labels";
+import type { AdminAreaLabels } from "./admin-area-labels";
+
+export interface AdminForbiddenProps extends Omit<ComponentPropsWithRef<"div">, "children" | "title"> {
+  /** The app's name, in the sentence: "This is where administrators run Kastlan." */
+  appName: string;
+  /** The button's target: the app's start page (keksdose `/budget`, kastlan `/dashboard`). */
+  homeHref: string;
+  /** The button's words, where the app names its start ("Back to the budget"). Default
+   *  `adminArea.forbiddenHome`, "Go to the start page". */
+  homeLabel?: string;
+  /** Pass it to a translation reviewer: a second button, "Review translations", to the
+   *  tool their role does have (§2.2 decision 8). */
+  reviewerHref?: string;
+  /** The heading's level. Default `h1`: the page stands alone inside the app shell. */
+  headingAs?: "h1" | "h2" | "h3";
+  /** Prop > `<UiKitProvider labels={{ adminArea }}>` > English. */
+  labels?: LabelOverride<AdminAreaLabels>;
+}
+
+/**
+ * The admin area's 403 page (0.42.0, docs/admin-harmonization.md §2.2 decision 8, §6.7),
+ * keksdose's `AdminForbidden`: "Only for administrators" / "This is where administrators
+ * run {app}. Your account cannot open this page.", and a button back to the app's start.
+ *
+ * It RENDERS, it does not redirect: the app's client gate shows it in place of the admin
+ * page, on the same admin check the account menu uses, inside the lazy route — so a
+ * bookmark keeps its address, and signing in as an admin opens the page that was asked
+ * for. The server's gate stays the rule. kastlan shows it on its admin tools (`/admin`,
+ * `/import`, `/feedback`); its work pages keep their generic 403.
+ *
+ * The words say only that this area is closed to this account, never that the person
+ * administers nothing anywhere: a kastlan superuser who isn't ADMIN in the acting company
+ * gets this page too.
+ */
+export function AdminForbidden({
+  appName,
+  homeHref,
+  homeLabel,
+  reviewerHref,
+  headingAs = "h1",
+  labels: labelsProp,
+  className,
+  ...rest
+}: AdminForbiddenProps) {
+  const labels = useAdminAreaLabels(labelsProp);
+  return (
+    <div {...rest} data-slot="admin-forbidden" className={cn("mx-auto w-full max-w-xl p-4 md:p-6", className)}>
+      <EmptyState
+        icon={<ShieldAlert />}
+        headingAs={headingAs}
+        title={labels.forbiddenTitle}
+        hint={labels.forbiddenBody(appName)}
+        action={
+          <>
+            <Button href={homeHref} variant="secondary">
+              {homeLabel ?? labels.forbiddenHome}
+            </Button>
+            {reviewerHref !== undefined && (
+              <Button href={reviewerHref} variant="secondary">
+                {labels.forbiddenReviewer}
+              </Button>
+            )}
+          </>
+        }
+      />
+    </div>
+  );
+}