@eifi1/ui-kit 0.33.1 → 0.34.0

package/dist/lib/reduced-motion.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Whether the user has asked for no motion (`prefers-reduced-motion: reduce`), read NOW —
+ * not at mount: the setting can change under a long-lived page. The kit's one copy
+ * (DUP-11, refactor audit 2026-10: the settings focus and the exit timers each had their
+ * own, with opposite answers where `matchMedia` is missing).
+ *
+ * Where there is no `matchMedia` to ask (SSR, jsdom) the answer is `whereUnknown`,
+ * default `false`: motion allowed — the platform's own default, `no-preference`, which
+ * is what a browser that cannot say otherwise has. A smooth scroll there is harmless.
+ *
+ * An exit animation passes `true` (`skipsExitAnimation` in `hooks/use-close-transition`):
+ * without `matchMedia` nothing is painting, and a timer that holds an unpainted panel on
+ * screen only delays its `onClose` — every test suite, the kit's and the apps', reads a
+ * closed overlay as gone at once.
+ *
+ * Package-private — not re-exported from the barrel.
+ */
+export declare function prefersReducedMotion(whereUnknown?: boolean): boolean;

package/dist/lib/reduced-motion.js

@@ -0,0 +1,9 @@
+"use client";
+function prefersReducedMotion(whereUnknown = false) {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return whereUnknown;
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+export {
+  prefersReducedMotion
+};
+//# sourceMappingURL=reduced-motion.js.map

package/dist/lib/reduced-motion.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/reduced-motion.ts"],"sourcesContent":["/**\n * Whether the user has asked for no motion (`prefers-reduced-motion: reduce`), read NOW —\n * not at mount: the setting can change under a long-lived page. The kit's one copy\n * (DUP-11, refactor audit 2026-10: the settings focus and the exit timers each had their\n * own, with opposite answers where `matchMedia` is missing).\n *\n * Where there is no `matchMedia` to ask (SSR, jsdom) the answer is `whereUnknown`,\n * default `false`: motion allowed — the platform's own default, `no-preference`, which\n * is what a browser that cannot say otherwise has. A smooth scroll there is harmless.\n *\n * An exit animation passes `true` (`skipsExitAnimation` in `hooks/use-close-transition`):\n * without `matchMedia` nothing is painting, and a timer that holds an unpainted panel on\n * screen only delays its `onClose` — every test suite, the kit's and the apps', reads a\n * closed overlay as gone at once.\n *\n * Package-private — not re-exported from the barrel.\n */\nexport function prefersReducedMotion(whereUnknown = false): boolean {\n  if (typeof window === \"undefined\" || typeof window.matchMedia !== \"function\") return whereUnknown;\n  return window.matchMedia(\"(prefers-reduced-motion: reduce)\").matches;\n}\n"],"mappings":";AAiBO,SAAS,qBAAqB,eAAe,OAAgB;AAClE,MAAI,OAAO,WAAW,eAAe,OAAO,OAAO,eAAe,WAAY,QAAO;AACrF,SAAO,OAAO,WAAW,kCAAkC,EAAE;AAC/D;","names":[]}

package/dist/lib/round.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Decimal rounding, half away from zero — the one copy behind {@link roundToCurrency}
+ * and AmountInput's settle (BUG-11, refactor audit 2026-10).
+ *
+ * Package-private — not re-exported from the barrel; `format.ts` and `calc.ts` are
+ * re-exported wholesale, so a helper there would become API.
+ *
+ * WHY THE STRING SHIFT. `Math.round(1.005 * 100)` is 100, because 1.005 is 1.00499…
+ * in binary. Shifting the decimal point in the number's SHORTEST spelling instead
+ * ("1.005e2" is exactly 100.5) rounds the figure a person typed. Both helpers did that
+ * by gluing `e${digits}` onto `String(n)` — but `String(n)` is itself in exponent form
+ * below 1e-6 and at or above 1e21, and "5.55e-17e2" is NaN: `roundToCurrency(0.1 + 0.2
+ * - 0.3, "EUR")` was NaN, and AmountInput blanked a typed "0.0000001" on blur (U-2's
+ * class, 2026-08-24). {@link shiftDecimal} moves the exponent the string already has.
+ */
+/**
+ * `n` rounded to `digits` decimals, half away from zero, in decimal arithmetic:
+ * 1.005 → 1.01, -2.5 at 0 → -3. Never NaN for a finite `n`, and never -0 — `formatMoney`
+ * prints -0 as "-0,00 €", so a negative that rounds away comes back as 0. A non-finite
+ * `n` comes back unchanged.
+ */
+export declare function roundHalfAway(n: number, digits: number): number;

package/dist/lib/round.js

@@ -0,0 +1,15 @@
+"use client";
+function shiftDecimal(value, by) {
+  const [mantissa, exponent = "0"] = String(value).split("e");
+  return Number(`${mantissa}e${Number(exponent) + by}`);
+}
+function roundHalfAway(n, digits) {
+  if (!Number.isFinite(n)) return n;
+  const abs = Math.abs(n);
+  const magnitude = abs >= 2 ** 53 ? abs : shiftDecimal(Math.round(shiftDecimal(abs, digits)), -digits);
+  return (n < 0 ? -magnitude : magnitude) || 0;
+}
+export {
+  roundHalfAway
+};
+//# sourceMappingURL=round.js.map

package/dist/lib/round.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/round.ts"],"sourcesContent":["/**\n * Decimal rounding, half away from zero — the one copy behind {@link roundToCurrency}\n * and AmountInput's settle (BUG-11, refactor audit 2026-10).\n *\n * Package-private — not re-exported from the barrel; `format.ts` and `calc.ts` are\n * re-exported wholesale, so a helper there would become API.\n *\n * WHY THE STRING SHIFT. `Math.round(1.005 * 100)` is 100, because 1.005 is 1.00499…\n * in binary. Shifting the decimal point in the number's SHORTEST spelling instead\n * (\"1.005e2\" is exactly 100.5) rounds the figure a person typed. Both helpers did that\n * by gluing `e${digits}` onto `String(n)` — but `String(n)` is itself in exponent form\n * below 1e-6 and at or above 1e21, and \"5.55e-17e2\" is NaN: `roundToCurrency(0.1 + 0.2\n * - 0.3, \"EUR\")` was NaN, and AmountInput blanked a typed \"0.0000001\" on blur (U-2's\n * class, 2026-08-24). {@link shiftDecimal} moves the exponent the string already has.\n */\n\n/** `value × 10^by`, by moving the exponent of its shortest spelling (\"1.005\" → \"1.005e2\",\n *  \"5.55e-17\" → \"5.55e-15\"), so no binary multiplication creeps in. */\nfunction shiftDecimal(value: number, by: number): number {\n  const [mantissa, exponent = \"0\"] = String(value).split(\"e\");\n  return Number(`${mantissa}e${Number(exponent) + by}`);\n}\n\n/**\n * `n` rounded to `digits` decimals, half away from zero, in decimal arithmetic:\n * 1.005 → 1.01, -2.5 at 0 → -3. Never NaN for a finite `n`, and never -0 — `formatMoney`\n * prints -0 as \"-0,00 €\", so a negative that rounds away comes back as 0. A non-finite\n * `n` comes back unchanged.\n */\nexport function roundHalfAway(n: number, digits: number): number {\n  if (!Number.isFinite(n)) return n;\n  const abs = Math.abs(n);\n  // Every double from 2^53 up is a whole number already, and scaling one near\n  // Number.MAX_VALUE up would overflow to Infinity.\n  const magnitude = abs >= 2 ** 53 ? abs : shiftDecimal(Math.round(shiftDecimal(abs, digits)), -digits);\n  // The sign goes back on after rounding, so `|| 0` must see the signed result.\n  return (n < 0 ? -magnitude : magnitude) || 0;\n}\n"],"mappings":";AAkBA,SAAS,aAAa,OAAe,IAAoB;AACvD,QAAM,CAAC,UAAU,WAAW,GAAG,IAAI,OAAO,KAAK,EAAE,MAAM,GAAG;AAC1D,SAAO,OAAO,GAAG,QAAQ,IAAI,OAAO,QAAQ,IAAI,EAAE,EAAE;AACtD;AAQO,SAAS,cAAc,GAAW,QAAwB;AAC/D,MAAI,CAAC,OAAO,SAAS,CAAC,EAAG,QAAO;AAChC,QAAM,MAAM,KAAK,IAAI,CAAC;AAGtB,QAAM,YAAY,OAAO,KAAK,KAAK,MAAM,aAAa,KAAK,MAAM,aAAa,KAAK,MAAM,CAAC,GAAG,CAAC,MAAM;AAEpG,UAAQ,IAAI,IAAI,CAAC,YAAY,cAAc;AAC7C;","names":[]}

package/dist/lib/safe-storage.d.ts

@@ -13,11 +13,21 @@
  * So the guard lives here, once, and the next storage-backed preference cannot
  * forget it. A read that cannot happen is indistinguishable from a key that was
  * never set, which is the right answer for every caller: the default.
+ *
+ * Since 0.34 (DUP-11, refactor audit 2026-10) it also removes, and guards
+ * `sessionStorage` the same way: `landing/routing`, `billing/checkout-processing` and
+ * the demo banner each wrote that guard again by hand. `removeStored` and the session
+ * pair are package-private — the barrel exports `readStored` / `writeStored` only.
  */
 /** The stored string for `key`, or null when absent, unreadable, or blocked. */
-declare function readStored(key: string): string | null;
+export declare function readStored(key: string): string | null;
 /** Store `value` under `key`, silently doing nothing when storage is unavailable
  *  or full. A preference that cannot be persisted is not worth an exception. */
-declare function writeStored(key: string, value: string): void;
-
-export { readStored, writeStored };
+export declare function writeStored(key: string, value: string): void;
+/** Forget `key`, silently doing nothing when storage is blocked — there is nothing to
+ *  forget then. */
+export declare function removeStored(key: string): void;
+/** {@link readStored} for `sessionStorage`: this tab's value, or null. */
+export declare function readSessionStored(key: string): string | null;
+/** {@link writeStored} for `sessionStorage`; `null` removes the key. */
+export declare function writeSessionStored(key: string, value: string | null): void;

package/dist/lib/safe-storage.js

@@ -1,21 +1,36 @@
 "use client";
-function readStored(key) {
-  if (typeof window === "undefined") return null;
+function guarded(area, fallback, access) {
+  if (typeof window === "undefined") return fallback;
   try {
-    return window.localStorage.getItem(key);
+    return access(window[area]);
   } catch {
-    return null;
+    return fallback;
   }
 }
+function readStored(key) {
+  return guarded("localStorage", null, (storage) => storage.getItem(key));
+}
 function writeStored(key, value) {
-  if (typeof window === "undefined") return;
-  try {
-    window.localStorage.setItem(key, value);
-  } catch {
-  }
+  guarded("localStorage", void 0, (storage) => storage.setItem(key, value));
+}
+function removeStored(key) {
+  guarded("localStorage", void 0, (storage) => storage.removeItem(key));
+}
+function readSessionStored(key) {
+  return guarded("sessionStorage", null, (storage) => storage.getItem(key));
+}
+function writeSessionStored(key, value) {
+  guarded(
+    "sessionStorage",
+    void 0,
+    (storage) => value === null ? storage.removeItem(key) : storage.setItem(key, value)
+  );
 }
 export {
+  readSessionStored,
   readStored,
+  removeStored,
+  writeSessionStored,
   writeStored
 };
 //# sourceMappingURL=safe-storage.js.map

package/dist/lib/safe-storage.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/lib/safe-storage.ts"],"sourcesContent":["/**\n * `localStorage` that cannot take the page down with it.\n *\n * Accessing `window.localStorage` **throws** — rather than returning null — when a\n * browser has site data blocked: Safari private browsing, Chrome with third-party\n * site data disabled, a partitioned webview. Three places in this package already\n * knew that and wrapped their calls in try/catch (`logger.ts`, and the DataTable's\n * `loadPersisted`/`savePersisted`). One did not: `AppShell` read the sidebar's\n * collapse flag straight out of a `useState` initialiser, so the throw happened\n * during render of the application's top-level shell. That is not a lost preference\n * — nothing mounts, in every consumer of this package at once.\n *\n * So the guard lives here, once, and the next storage-backed preference cannot\n * forget it. A read that cannot happen is indistinguishable from a key that was\n * never set, which is the right answer for every caller: the default.\n */\n\n/** The stored string for `key`, or null when absent, unreadable, or blocked. */\nexport function readStored(key: string): string | null {\n  if (typeof window === \"undefined\") return null;\n  try {\n    return window.localStorage.getItem(key);\n  } catch {\n    return null;\n  }\n}\n\n/** Store `value` under `key`, silently doing nothing when storage is unavailable\n *  or full. A preference that cannot be persisted is not worth an exception. */\nexport function writeStored(key: string, value: string): void {\n  if (typeof window === \"undefined\") return;\n  try {\n    window.localStorage.setItem(key, value);\n  } catch {\n    // ignore (private mode, quota, partitioned storage)\n  }\n}\n"],"mappings":";AAkBO,SAAS,WAAW,KAA4B;AACrD,MAAI,OAAO,WAAW,YAAa,QAAO;AAC1C,MAAI;AACF,WAAO,OAAO,aAAa,QAAQ,GAAG;AAAA,EACxC,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAIO,SAAS,YAAY,KAAa,OAAqB;AAC5D,MAAI,OAAO,WAAW,YAAa;AACnC,MAAI;AACF,WAAO,aAAa,QAAQ,KAAK,KAAK;AAAA,EACxC,QAAQ;AAAA,EAER;AACF;","names":[]}
+{"version":3,"sources":["../../src/lib/safe-storage.ts"],"sourcesContent":["/**\n * `localStorage` that cannot take the page down with it.\n *\n * Accessing `window.localStorage` **throws** — rather than returning null — when a\n * browser has site data blocked: Safari private browsing, Chrome with third-party\n * site data disabled, a partitioned webview. Three places in this package already\n * knew that and wrapped their calls in try/catch (`logger.ts`, and the DataTable's\n * `loadPersisted`/`savePersisted`). One did not: `AppShell` read the sidebar's\n * collapse flag straight out of a `useState` initialiser, so the throw happened\n * during render of the application's top-level shell. That is not a lost preference\n * — nothing mounts, in every consumer of this package at once.\n *\n * So the guard lives here, once, and the next storage-backed preference cannot\n * forget it. A read that cannot happen is indistinguishable from a key that was\n * never set, which is the right answer for every caller: the default.\n *\n * Since 0.34 (DUP-11, refactor audit 2026-10) it also removes, and guards\n * `sessionStorage` the same way: `landing/routing`, `billing/checkout-processing` and\n * the demo banner each wrote that guard again by hand. `removeStored` and the session\n * pair are package-private — the barrel exports `readStored` / `writeStored` only.\n */\n\n/** `access` on the storage area, or `fallback` where there is none (SSR) or it throws. */\nfunction guarded<T>(area: \"localStorage\" | \"sessionStorage\", fallback: T, access: (storage: Storage) => T): T {\n  if (typeof window === \"undefined\") return fallback;\n  try {\n    return access(window[area]);\n  } catch {\n    // private mode, quota, partitioned or blocked storage\n    return fallback;\n  }\n}\n\n/** The stored string for `key`, or null when absent, unreadable, or blocked. */\nexport function readStored(key: string): string | null {\n  return guarded(\"localStorage\", null, (storage) => storage.getItem(key));\n}\n\n/** Store `value` under `key`, silently doing nothing when storage is unavailable\n *  or full. A preference that cannot be persisted is not worth an exception. */\nexport function writeStored(key: string, value: string): void {\n  guarded(\"localStorage\", undefined, (storage) => storage.setItem(key, value));\n}\n\n/** Forget `key`, silently doing nothing when storage is blocked — there is nothing to\n *  forget then. */\nexport function removeStored(key: string): void {\n  guarded(\"localStorage\", undefined, (storage) => storage.removeItem(key));\n}\n\n/** {@link readStored} for `sessionStorage`: this tab's value, or null. */\nexport function readSessionStored(key: string): string | null {\n  return guarded(\"sessionStorage\", null, (storage) => storage.getItem(key));\n}\n\n/** {@link writeStored} for `sessionStorage`; `null` removes the key. */\nexport function writeSessionStored(key: string, value: string | null): void {\n  guarded(\"sessionStorage\", undefined, (storage) =>\n    value === null ? storage.removeItem(key) : storage.setItem(key, value),\n  );\n}\n"],"mappings":";AAuBA,SAAS,QAAW,MAAyC,UAAa,QAAoC;AAC5G,MAAI,OAAO,WAAW,YAAa,QAAO;AAC1C,MAAI;AACF,WAAO,OAAO,OAAO,IAAI,CAAC;AAAA,EAC5B,QAAQ;AAEN,WAAO;AAAA,EACT;AACF;AAGO,SAAS,WAAW,KAA4B;AACrD,SAAO,QAAQ,gBAAgB,MAAM,CAAC,YAAY,QAAQ,QAAQ,GAAG,CAAC;AACxE;AAIO,SAAS,YAAY,KAAa,OAAqB;AAC5D,UAAQ,gBAAgB,QAAW,CAAC,YAAY,QAAQ,QAAQ,KAAK,KAAK,CAAC;AAC7E;AAIO,SAAS,aAAa,KAAmB;AAC9C,UAAQ,gBAAgB,QAAW,CAAC,YAAY,QAAQ,WAAW,GAAG,CAAC;AACzE;AAGO,SAAS,kBAAkB,KAA4B;AAC5D,SAAO,QAAQ,kBAAkB,MAAM,CAAC,YAAY,QAAQ,QAAQ,GAAG,CAAC;AAC1E;AAGO,SAAS,mBAAmB,KAAa,OAA4B;AAC1E;AAAA,IAAQ;AAAA,IAAkB;AAAA,IAAW,CAAC,YACpC,UAAU,OAAO,QAAQ,WAAW,GAAG,IAAI,QAAQ,QAAQ,KAAK,KAAK;AAAA,EACvE;AACF;","names":[]}

package/dist/lib/server-wake.d.ts

@@ -38,13 +38,13 @@
  */
 /** `slow` = longer than a warm server ever takes; `waking` = long enough that a cold
  *  start is the only sensible explanation. */
-type ServerWakeStage = "idle" | "slow" | "waking";
+export type ServerWakeStage = "idle" | "slow" | "waking";
 /** Decides which requests count. `method` arrives lower-cased (`"get"` when the
  *  request named none — axios's and fetch's default); `url` as the client had it;
  *  `request` is what the adapter saw — for axios the request config itself, so
  *  `responseType` or the app's own fields can decide. */
-type ServerWakeFilter = (method: string, url: string, request: ServerWakeRequest) => boolean;
-interface ServerWakeOptions {
+export type ServerWakeFilter = (method: string, url: string, request: ServerWakeRequest) => boolean;
+export interface ServerWakeOptions {
     /** Past this, a warm round trip is out of the question (a cold database query on a
      *  free tier can still take a second, so it is not tighter). Default 2000 ms. */
     slowMs?: number;
@@ -55,14 +55,14 @@ interface ServerWakeOptions {
     shouldWatch?: ServerWakeFilter;
 }
 /** What a request is, for {@link ServerWakeWatcher.track} and a {@link ServerWakeFilter}. */
-interface ServerWakeRequest {
+export interface ServerWakeRequest {
     method?: string;
     url?: string;
     /** axios's `responseType`. `"blob"`, `"arraybuffer"` and `"stream"` mark a download,
      *  which the default filter does not count. */
     responseType?: string;
 }
-interface ServerWakeWatcher {
+export interface ServerWakeWatcher {
     /**
      * Count a request that is going out, and arm the escalation if it is the first.
      * Returns whether it was counted — the caller MUST call {@link end} exactly once
@@ -92,18 +92,18 @@ interface ServerWakeWatcher {
  * (`responseType` `"blob"`, `"arraybuffer"` or `"stream"`). Keep upload routes out of
  * the pattern (see the module comment).
  */
-declare function watchReadsAnd(writes?: RegExp): ServerWakeFilter;
-declare function createServerWake({ slowMs, wakingMs, shouldWatch, }?: ServerWakeOptions): ServerWakeWatcher;
+export declare function watchReadsAnd(writes?: RegExp): ServerWakeFilter;
+export declare function createServerWake({ slowMs, wakingMs, shouldWatch, }?: ServerWakeOptions): ServerWakeWatcher;
 /**
  * The shared instance: what `<ServerWakeNotice />`, `useServerWakeStage()`,
  * {@link attachServerWake} and {@link wrapFetch} use when no watcher is passed. GETs
  * only, default timings — an app that also watches its login POST creates its own
  * with {@link createServerWake} and passes it to both ends.
  */
-declare const serverWake: ServerWakeWatcher;
+export declare const serverWake: ServerWakeWatcher;
 /** The config fields the watchdog reads — what axios's request config has. The whole
  *  config reaches the filter, so an app's filter can read the rest of it. */
-interface ServerWakeAxiosConfig {
+export interface ServerWakeAxiosConfig {
     method?: string;
     url?: string;
     responseType?: string;
@@ -116,7 +116,7 @@ interface InterceptorManagerLike<V> {
 }
 /** An axios instance, structurally — so the kit types the adapter without importing
  *  axios. `axios.create()`'s result fits it as is. */
-interface AxiosLikeInstance<C extends ServerWakeAxiosConfig, R extends {
+export interface AxiosLikeInstance<C extends ServerWakeAxiosConfig, R extends {
     config: C;
 }> {
     interceptors: {
@@ -133,7 +133,7 @@ interface AxiosLikeInstance<C extends ServerWakeAxiosConfig, R extends {
  * refresh — otherwise the notice would keep counting a request that has already been
  * answered. (Request-side order does not matter.)
  */
-declare function attachServerWake<C extends ServerWakeAxiosConfig, R extends {
+export declare function attachServerWake<C extends ServerWakeAxiosConfig, R extends {
     config: C;
 }>(instance: AxiosLikeInstance<C, R>, watcher?: ServerWakeWatcher): () => void;
 /**
@@ -141,6 +141,5 @@ declare function attachServerWake<C extends ServerWakeAxiosConfig, R extends {
  * when the response's HEADERS arrive (or the call fails) — the server is awake by then,
  * however long the body takes.
  */
-declare function wrapFetch(fetchImpl?: typeof fetch, watcher?: ServerWakeWatcher): typeof fetch;
-
-export { type AxiosLikeInstance, type ServerWakeAxiosConfig, type ServerWakeFilter, type ServerWakeOptions, type ServerWakeRequest, type ServerWakeStage, type ServerWakeWatcher, attachServerWake, createServerWake, serverWake, watchReadsAnd, wrapFetch };
+export declare function wrapFetch(fetchImpl?: typeof fetch, watcher?: ServerWakeWatcher): typeof fetch;
+export {};

package/dist/lib/session-refresh.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Renewing a session when the access token runs out: the client half of
+ * docs/auth-harmonization.md §11 (round 0.34 C7, KS U6), lifted from keksdose's
+ * `refreshOnce` (Kurvenschmiede's is the same, line for line) and corrected where the
+ * three apps' reviews found it wrong. It ends kastlan's sign-out over a network blip (B3).
+ *
+ * THE KIT OWNS THE RULE, THE APP OWNS THE CALL (§11.2, decision 1). The kit decides when
+ * to refresh, who waits, what a failure means, when the session is over and whether a
+ * renewal may still be stored. The app keeps its endpoint, its token storage, its
+ * sign-out and where it navigates, and hands them in as {@link SessionRefreshOptions}.
+ *
+ *  - **One flight per tab** (decision 2): every 401 that arrives while a refresh runs
+ *    waits for it, and so does `session.refresh()` (kastlan's boot).
+ *  - **Definitive** (decision 3): the device holds no refresh token (`refresh` resolves
+ *    `null`), the refresh answers 401 or 403, or the request replayed with the fresh
+ *    token gets a 401 again. Only then does the app sign out (`onEnded`), and only while
+ *    that session is still the app's.
+ *  - **Transient** (decision 4): everything else. The session stays: nothing is signed
+ *    out, stored or redirected, and the kit shows nothing. The request rejects with its
+ *    OWN 401, marked ({@link isTransientRefreshFailure}), so the app's message can say
+ *    "can't reach the server" instead of "not signed in".
+ *  - **Retries only where waiting helps** (decision 5, KS 7): no answer, the kit's own
+ *    timeout, 408, 429 and 5xx get up to three attempts, 1 s and then 3 s apart, each cut
+ *    off after 15 s; none while the browser reports itself offline. Any other answer, and
+ *    anything that is not an HTTP error, ends the flight at the first attempt.
+ *  - **A stale session is never written back** (§11.7, ka 3, KS 3, KS 4): every request
+ *    is stamped with `currentToken()` when it goes out, and every flight notes it when it
+ *    starts. A 401 to a request sent with an older token replays it with the app's token
+ *    now, without a refresh; a flight whose session changed while it ran stores nothing
+ *    and ends nothing. The access token is the session's identity because every change
+ *    the apps make replaces it — a refresh, another tab, a company switch, a password
+ *    change, a sign-in, a demo start, a sign-out.
+ *
+ * Framework-free like `server-wake.ts`: {@link attachSessionRefresh} takes the app's
+ * axios instance as an ARGUMENT, typed structurally, so the kit never imports axios.
+ */
+import type { AxiosLikeInstance, ServerWakeAxiosConfig } from "./server-wake.js";
+/** What the app's `refresh` resolves: the new access token, plus whatever its `store`
+ *  needs (its refresh token, the user). */
+export interface SessionRenewal {
+    /** The new access token; the waiting requests are replayed with it. */
+    token: string;
+    /**
+     * `false`: store the renewal, but replay nothing — each waiting request rejects with
+     * its 401, unmarked. kastlan's refresh can land in another company (§11.5, ka 3): a
+     * waiting write, such as the handover's `POST /sync`, must not be replayed into it.
+     */
+    replay?: false;
+}
+/** What the app hands {@link createSessionRefresh} (§11.4). */
+export interface SessionRefreshOptions<R extends SessionRenewal> {
+    /**
+     * The app's own `POST /auth/refresh`, on a BARE client — never the instance the kit is
+     * attached to, so the refresh cannot re-enter the interceptor. It **writes nothing**:
+     * the kit hands the answer to `store`, and only while the session is unchanged.
+     *
+     * Resolves the answer as a renewal, or `null` when the device holds no refresh token.
+     * Throws on failure, and the kit classifies the throw: a 401 or 403 is definitive; no
+     * answer (an axios error without a `response`), the kit's own timeout, 408, 429 and
+     * 5xx are transient and retried; any other answer, and anything that is not an HTTP
+     * error (a bug in this function), is transient and not retried. The status is read
+     * from `err.response.status` (axios), `err.status` or `err.statusCode`.
+     *
+     * `signal` aborts when the attempt runs past `timeoutMs`; pass it to the request.
+     */
+    refresh: (signal: AbortSignal) => Promise<R | null>;
+    /** Writes the renewal: the tokens and the user (a missing refresh token keeps the
+     *  stored one). Called only while the session the flight renews is still the app's,
+     *  and before the waiting requests are replayed — so it writes the token SYNCHRONOUSLY
+     *  where `currentToken` reads it: the replay goes through the app's own request
+     *  interceptor again, and is stamped then. A throw is the app's bug: the waiting
+     *  requests and `session.refresh()` reject with it. */
+    store: (renewal: R) => void;
+    /** The access token the app sends NOW, read where its request interceptor reads it;
+     *  `null` when there is none. */
+    currentToken: () => string | null;
+    /** Whether the session is a demo: a demo's 401 ends it, with no refresh tried
+     *  (landing-demo §5.5). */
+    isDemo: () => boolean;
+    /**
+     * The session is over: drop the tokens and the user, then navigate — `/demo/ended` for
+     * a demo, else the sign-in with the page it came from (auth §5.2). Called once per
+     * session, however many requests found out (KS 8), and never by `session.refresh()`.
+     */
+    onEnded: (ended: {
+        demo: boolean;
+    }) => void;
+    /** Whether a URL is a signed-out step, whose 401 judges the form and never the
+     *  session. Replaces the default list, {@link isSignedOutStep}. */
+    isSignedOutStep?: (url: string) => boolean;
+    /** Attempts for a refresh that got no answer, timed out, or got a 408, 429 or 5xx.
+     *  Default 3. */
+    attempts?: number;
+    /** The waits before the second and later attempts; the last one repeats. Default
+     *  `[1000, 3000]`. */
+    backoffMs?: readonly number[];
+    /** Each attempt is cut off after this, and its `signal` aborted. Default 15 000. */
+    timeoutMs?: number;
+}
+/** What `session.refresh()` resolves (§11.4), by `result`:
+ *
+ * | `result` | When | What the kit has done |
+ * |---|---|---|
+ * | `"renewed"` | a renewal while the session was unchanged | `store(renewal)` |
+ * | `"ended"` | definitive | nothing; `onEnded` only for requests that waited on the same flight |
+ * | `"transient"` | transient | nothing |
+ * | `"changed"` | the session changed while it ran | nothing; read the app's own state |
+ */
+export type SessionRefreshOutcome<R extends SessionRenewal = SessionRenewal> = {
+    result: "renewed";
+    renewal: R;
+} | {
+    result: "ended";
+} | {
+    result: "transient";
+} | {
+    result: "changed";
+};
+/** The flight {@link createSessionRefresh} makes; {@link attachSessionRefresh} hooks it
+ *  to an axios instance. */
+export interface SessionRefresh<R extends SessionRenewal = SessionRenewal> {
+    /**
+     * The same flight, for a caller outside the interceptor — kastlan's boot. Joins a
+     * running flight, or starts one. Never calls `onEnded`: the caller decides what an
+     * `"ended"` means for it.
+     */
+    refresh(): Promise<SessionRefreshOutcome<R>>;
+}
+/**
+ * Whether a request's URL is a signed-out step — the kit's default list (§11.3), exported
+ * for an app's tests and for an app's own `isSignedOutStep` that adds to it.
+ *
+ * **Whole steps only** (KS 2): the part of the path after its `auth/` segment, without
+ * the query string, is the entry itself or starts with the entry and a `/`. So
+ * `login/2fa` is `login`'s, but `register` never catches `/auth/passkey/register/begin`
+ * (adding a passkey, which needs a session), `invitations/check` never
+ * `/auth/invitations/accept`, and `me/email/confirm` never `/auth/me/email`. Relative and
+ * absolute URLs alike; a URL with no `auth` segment is no step.
+ */
+export declare function isSignedOutStep(url: string): boolean;
+/**
+ * Whether a request was refused because the refresh behind it failed TRANSIENTLY —
+ * offline, a timeout, a 5xx — and not because the session is over (decision 8). The
+ * error is the request's own 401, `err.response?.status` and every check an app already
+ * has keep working; this reads the mark the kit put on it, so the app's message can say
+ * "can't reach the server" instead of "not signed in". Read it FIRST: keksdose's sync
+ * chip, kastlan's handover sync and Kurvenschmiede's `apiErrorMessage` count it as
+ * offline (§11.5).
+ *
+ * Not the refresh's own error: its config carries the refresh token in its body, into any
+ * log or crash report that keeps the error.
+ */
+export declare function isTransientRefreshFailure(error: unknown): boolean;
+/**
+ * Make the flight: `const session = createSessionRefresh({ refresh, store, currentToken,
+ * isDemo, onEnded })`, then {@link attachSessionRefresh}`(api, session)`. One per tab.
+ */
+export declare function createSessionRefresh<R extends SessionRenewal>(options: SessionRefreshOptions<R>): SessionRefresh<R>;
+/** The config fields the kit reads and writes — what axios's request config has. */
+interface SessionRefreshAxiosConfig extends ServerWakeAxiosConfig {
+    /** axios's `AxiosHeaders` (written through its `set`), or a plain record. */
+    headers?: unknown;
+}
+/** An axios instance, structurally: {@link AxiosLikeInstance}, plus `request(config)` for
+ *  the replay. `axios.create()`'s result fits it as is. `NoInfer`, because axios's
+ *  `request` takes the WIDER `AxiosRequestConfig`: inferred from there, the config type
+ *  no longer fits the interceptors, which hand out `InternalAxiosRequestConfig`. */
+interface SessionRefreshInstance<C extends SessionRefreshAxiosConfig, R extends {
+    config: C;
+}> extends AxiosLikeInstance<C, R> {
+    request(config: NoInfer<C>): Promise<unknown>;
+}
+/**
+ * Hook a session to an axios instance: `attachSessionRefresh(api, session)`. Adds a
+ * request interceptor (the stamp) and a response interceptor (the 401), and returns a
+ * function that ejects both.
+ *
+ * Attach it LAST (§11.3, kk 4): after `attachServerWake`, which asks to be first, and
+ * after the app's own response interceptors (logging, a watchdog of its own). axios runs
+ * response interceptors in the order they were added, and each of those must see the 401
+ * settle before the refresh is awaited. The request side's order does not matter.
+ *
+ * On a 401, in this order (§11.3):
+ *
+ *  1. a signed-out step → reject, nothing else;
+ *  2. sent with an older token → replayed with the app's token now, with no refresh, once
+ *     for this reason; with no token now, reject;
+ *  3. a demo → `onEnded({ demo: true })`, reject;
+ *  4. already replayed after a refresh → definitive: `onEnded({ demo: false })`, reject;
+ *  5. otherwise it joins the flight, or starts it. A renewal replays it once with the
+ *     renewal's token (`replay: false`: rejects, unmarked); definitive ends the session;
+ *     transient rejects, marked; a session that changed meanwhile sends it through step
+ *     2 again.
+ *
+ * Every rejection is the request's OWN error. Any other status passes through untouched.
+ */
+export declare function attachSessionRefresh<C extends SessionRefreshAxiosConfig, R extends {
+    config: C;
+}>(instance: SessionRefreshInstance<C, R>, session: SessionRefresh<SessionRenewal>): () => void;
+export {};

package/dist/lib/session-refresh.js

@@ -0,0 +1,187 @@
+"use client";
+import { httpStatusOf } from "../auth/auth-errors.js";
+const SIGNED_OUT_STEPS = [
+  "login",
+  "passkey/login",
+  "register",
+  "demo-session",
+  "password-reset",
+  "verify-email",
+  "invitations/check",
+  "me/email/confirm",
+  "refresh"
+];
+function isSignedOutStep(url) {
+  const path = url.replace(/[?#].*$/s, "").replace(/^([a-z][a-z\d+.-]*:)?\/\/[^/]*/i, "");
+  const segments = path.split("/");
+  const at = segments.indexOf("auth");
+  if (at < 0) return false;
+  const step = segments.slice(at + 1).join("/");
+  return SIGNED_OUT_STEPS.some((entry) => step === entry || step.startsWith(`${entry}/`));
+}
+const TRANSIENT = /* @__PURE__ */ Symbol.for("@eifi1/ui-kit:session-refresh.transient");
+function isTransientRefreshFailure(error) {
+  return typeof error === "object" && error !== null && error[TRANSIENT] === true;
+}
+const engines = /* @__PURE__ */ new WeakMap();
+const TIMED_OUT = /* @__PURE__ */ Symbol("timed out");
+function isOffline() {
+  return typeof navigator !== "undefined" && navigator.onLine === false;
+}
+function classify(error) {
+  if (error === TIMED_OUT) return "retry";
+  if (typeof error !== "object" || error === null) return "transient";
+  const status = httpStatusOf(error);
+  if (status === void 0) {
+    return error.isAxiosError === true ? "retry" : "transient";
+  }
+  if (status === 401 || status === 403) return "definitive";
+  if (status === 408 || status === 429 || status >= 500) return "retry";
+  return "transient";
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function createSessionRefresh(options) {
+  const { attempts = 3, backoffMs = [1e3, 3e3], timeoutMs = 15e3 } = options;
+  const token = () => options.currentToken() || null;
+  const attempt = async () => {
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        reject(TIMED_OUT);
+        controller.abort();
+      }, timeoutMs);
+    });
+    try {
+      const renewal = await Promise.race([Promise.resolve().then(() => options.refresh(controller.signal)), timeout]);
+      return renewal ? { renewal } : "definitive";
+    } catch (error) {
+      return classify(error);
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+  const run = async () => {
+    const noted = token();
+    const changed = () => token() !== noted;
+    let outcome = await attempt();
+    for (let made = 1; outcome === "retry"; made += 1) {
+      if (made >= attempts || isOffline() || changed()) break;
+      await sleep(backoffMs[made - 1] ?? backoffMs[backoffMs.length - 1] ?? 0);
+      if (isOffline() || changed()) break;
+      outcome = await attempt();
+    }
+    if (changed()) return { result: "changed" };
+    if (outcome === "definitive") return { result: "ended", token: noted };
+    if (outcome === "retry" || outcome === "transient") return { result: "transient" };
+    options.store(outcome.renewal);
+    return { result: "renewed", renewal: outcome.renewal };
+  };
+  let flight = null;
+  const join = () => {
+    flight ??= run().finally(() => {
+      flight = null;
+    });
+    return flight;
+  };
+  let ended;
+  const session = {
+    async refresh() {
+      const outcome = await join();
+      return outcome.result === "ended" ? { result: "ended" } : outcome;
+    }
+  };
+  engines.set(session, {
+    token,
+    isDemo: () => options.isDemo(),
+    isSignedOutStep: options.isSignedOutStep ?? isSignedOutStep,
+    join,
+    end(endedToken, demo) {
+      if (ended && ended.token === endedToken) return;
+      ended = { token: endedToken };
+      options.onEnded({ demo });
+    }
+  });
+  return session;
+}
+const STAMP = "_sessionStamp";
+const REFRESHED = "_sessionRefreshed";
+const RESTAMPED = "_sessionRestamped";
+function authorize(config, token) {
+  const value = `Bearer ${token}`;
+  const headers = config.headers;
+  if (typeof headers !== "object" || headers === null) {
+    config.headers = { Authorization: value };
+  } else if (typeof headers.set === "function") {
+    headers.set("Authorization", value);
+  } else {
+    headers.Authorization = value;
+  }
+}
+function attachSessionRefresh(instance, session) {
+  const engine = engines.get(session);
+  if (!engine) throw new TypeError("attachSessionRefresh takes the session createSessionRefresh made");
+  const onUnauthorized = async (error, config) => {
+    if (engine.isSignedOutStep(config.url ?? "")) throw error;
+    const stamp = config[STAMP] === void 0 ? engine.token() : config[STAMP];
+    const replay = (token) => {
+      authorize(config, token);
+      return instance.request(config);
+    };
+    for (; ; ) {
+      const now = engine.token();
+      if (stamp !== now) {
+        if (now === null || config[RESTAMPED]) throw error;
+        config[RESTAMPED] = true;
+        return replay(now);
+      }
+      if (engine.isDemo()) {
+        engine.end(now, true);
+        throw error;
+      }
+      if (config[REFRESHED]) {
+        engine.end(now, false);
+        throw error;
+      }
+      const flight = await engine.join();
+      if (flight.result === "changed") continue;
+      if (flight.result === "ended") {
+        engine.end(flight.token, false);
+        throw error;
+      }
+      if (flight.result === "transient") {
+        error[TRANSIENT] = true;
+        throw error;
+      }
+      if (flight.renewal.replay === false) throw error;
+      config[REFRESHED] = true;
+      return replay(flight.renewal.token);
+    }
+  };
+  const request = instance.interceptors.request.use(
+    (config) => {
+      config[STAMP] = engine.token();
+      return config;
+    },
+    (error) => Promise.reject(error)
+  );
+  const response = instance.interceptors.response.use(
+    (res) => res,
+    (error) => {
+      const failed = error;
+      if (failed?.response?.status !== 401 || !failed.config) return Promise.reject(error);
+      return onUnauthorized(failed, failed.config);
+    }
+  );
+  return () => {
+    instance.interceptors.request.eject(request);
+    instance.interceptors.response.eject(response);
+  };
+}
+export {
+  attachSessionRefresh,
+  createSessionRefresh,
+  isSignedOutStep,
+  isTransientRefreshFailure
+};
+//# sourceMappingURL=session-refresh.js.map