@eifi1/ui-kit 0.53.0 → 0.55.0

package/dist/lib/server-wake.js

@@ -12,6 +12,7 @@ function createServerWake({
   shouldWatch = watchReadsAnd()
 } = {}) {
   const starts = [];
+  let lastToken = 0;
   let stage = "idle";
   let slowTimer = null;
   let wakingTimer = null;
@@ -27,41 +28,50 @@ function createServerWake({
     slowTimer = null;
     wakingTimer = null;
   };
+  const raise = (next) => {
+    if (stage !== "waking" && next !== stage) setStage(next);
+  };
   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 now = Date.now();
+    const age = now - starts[0].at;
+    const slowFrom = starts.find((s) => !s.slowOk);
+    const slowAge = slowFrom && now - slowFrom.at;
+    setStage(age >= wakingMs ? "waking" : slowAge !== void 0 && slowAge >= slowMs ? "slow" : "idle");
+    if (slowAge !== void 0 && slowAge < slowMs) slowTimer = setTimeout(() => raise("slow"), slowMs - slowAge);
+    if (age < wakingMs) wakingTimer = setTimeout(() => raise("waking"), wakingMs - age);
   };
   const start = (method, url, request = { method, url }) => {
     if (isOffline()) return false;
     if (!shouldWatch((method ?? "get").toLowerCase(), url ?? "", request)) return false;
-    starts.push(Date.now());
-    if (starts.length === 1) arm();
-    return true;
+    lastToken += 1;
+    const slowOk = request.slowOk === true;
+    starts.push({ token: lastToken, at: Date.now(), slowOk });
+    if (starts.length === 1 || !slowOk && starts.every((s, i) => s.slowOk || i === starts.length - 1)) arm();
+    return lastToken;
   };
-  const end = () => {
-    if (starts.length === 0) return;
-    starts.shift();
+  const end = (token) => {
+    const index = token === void 0 ? 0 : starts.findIndex((s) => s.token === token);
+    if (index < 0 || index >= starts.length) return;
+    starts.splice(index, 1);
     arm();
   };
   return {
     start,
     end,
     track(work, request = {}) {
-      const counted = start(request.method, request.url, request);
+      const token = start(request.method, request.url, request);
       let promise;
       try {
         promise = Promise.resolve(typeof work === "function" ? work() : work);
       } catch (error) {
         promise = Promise.reject(error);
       }
-      return counted ? promise.finally(end) : promise;
+      return token ? promise.finally(() => end(token)) : promise;
     },
     reset() {
       starts.length = 0;
@@ -83,9 +93,10 @@ const COUNTED = "_serverWake";
 function attachServerWake(instance, watcher = serverWake) {
   const settle = (config) => {
     const marked = config;
-    if (marked?.[COUNTED]) {
+    const token = marked?.[COUNTED];
+    if (marked && token) {
       marked[COUNTED] = false;
-      watcher.end();
+      watcher.end(token);
     }
   };
   const request = instance.interceptors.request.use(

package/dist/lib/server-wake.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/lib/server-wake.ts"],"sourcesContent":["/**\n * \"Is the server asleep, or is the app broken?\" — the cold-start watchdog, lifted\n * from keksdose (feedback #199) so kastlan and Kurvenschmiede get it too.\n *\n * All three backends run on Cloud Run with `--min-instances=0`: after an idle\n * period the container is gone and the first request has to start it, which takes\n * several seconds and occasionally more. Nothing in the UI said so, and none of the\n * axios instances has a timeout, so the honest experience was a spinner that looked\n * stuck. This counts the in-flight requests a cold start would actually delay and\n * escalates in two steps, so a merely slow response says \"still loading\" and only a\n * genuinely long wait blames the sleeping server.\n *\n * Framework-free on purpose (no zustand, no axios, no React): a counter, two timers\n * and a listener set, read by `useServerWakeStage` through `useSyncExternalStore`.\n * The adapters below take the app's axios instance / fetch as an ARGUMENT, so the\n * kit never imports either.\n *\n * WHAT ARMS IT, and why the default is narrow:\n *   - reads (GET) — what every page does on open — always;\n *   - writes only when the app says so (`watchReadsAnd(/\\/auth\\/login\\b/)`): the\n *     auth POSTs that gate the app are the only writes a user waits on before the\n *     app exists at all, so a cold start there looks exactly like a broken login.\n * An UPLOAD must never be watched — a statement PDF or a photo takes seconds on a\n * perfectly warm server, and \"the server is waking up\" during a 4 s upload would\n * simply be false. With the default that holds by itself (an upload is a POST);\n * an app widening `shouldWatch` keeps its upload routes out of it.\n *\n * Nor a DOWNLOAD, for the same reason (kastlan 0.18): axios answers only once the\n * whole body is in, so a generated PDF or a large photo — a GET — ran past both\n * thresholds on a warm server, and held the count for every read beside it. The\n * default filter skips a request whose `responseType` is `\"blob\"`, `\"arraybuffer\"` or\n * `\"stream\"`; a custom filter gets the request as its third argument to do the same.\n * (`wrapFetch` ends the wait at the headers, so a download through it is harmless.)\n *\n * It never arms while the browser is offline, whatever `shouldWatch` says: that state\n * has its own, truthful indicator, and a request that never left the device is not\n * evidence of anything about the server.\n */\n\n/** `slow` = longer than a warm server ever takes; `waking` = long enough that a cold\n *  start is the only sensible explanation. */\nexport type ServerWakeStage = \"idle\" | \"slow\" | \"waking\";\n\n/** Decides which requests count. `method` arrives lower-cased (`\"get\"` when the\n *  request named none — axios's and fetch's default); `url` as the client had it;\n *  `request` is what the adapter saw — for axios the request config itself, so\n *  `responseType` or the app's own fields can decide. */\nexport type ServerWakeFilter = (method: string, url: string, request: ServerWakeRequest) => boolean;\n\nexport interface ServerWakeOptions {\n  /** Past this, a warm round trip is out of the question (a cold database query on a\n   *  free tier can still take a second, so it is not tighter). Default 2000 ms. */\n  slowMs?: number;\n  /** Past this, the container was almost certainly scaled to zero. Default 7000 ms. */\n  wakingMs?: number;\n  /** Which requests count. Default {@link watchReadsAnd}`()` — GETs only, downloads\n   *  excluded. The offline guard runs before it and cannot be overridden. */\n  shouldWatch?: ServerWakeFilter;\n}\n\n/** What a request is, for {@link ServerWakeWatcher.track} and a {@link ServerWakeFilter}. */\nexport interface ServerWakeRequest {\n  method?: string;\n  url?: string;\n  /** axios's `responseType`. `\"blob\"`, `\"arraybuffer\"` and `\"stream\"` mark a download,\n   *  which the default filter does not count. */\n  responseType?: string;\n}\n\nexport interface ServerWakeWatcher {\n  /**\n   * Count a request that is going out, and arm the escalation if it is the first.\n   * Returns whether it was counted — the caller MUST call {@link end} exactly once\n   * for every `true`, or the counter never returns to zero and the notice sticks.\n   * (The axios adapter stashes it on the request config for that reason.)\n   * `request` reaches the filter as its third argument; default `{ method, url }`.\n   */\n  start(method?: string, url?: string, request?: ServerWakeRequest): boolean;\n  /** A counted request settled — either way: an error still proves the server\n   *  answered or gave up. The stage then follows the oldest request still out (0.51), so\n   *  the notice goes away when the last one does, or sooner when the rest are recent.\n   *  Never takes the counter below zero. */\n  end(): void;\n  /** `start` + `end` around a promise (or a function returning one), for a request\n   *  that does not go through an adapter. Resolves and rejects as the work does. */\n  track<T>(work: PromiseLike<T> | (() => PromiseLike<T>), request?: ServerWakeRequest): Promise<T>;\n  /** Back to a pristine watchdog — for tests, which share an instance across cases. */\n  reset(): void;\n  /** `useSyncExternalStore`'s pair. Listeners hear stage changes only. */\n  subscribe(listener: () => void): () => void;\n  getStage(): ServerWakeStage;\n  /** Counted requests currently outstanding. */\n  getInFlight(): number;\n}\n\n/** Response types that make a request a download — see the module comment. */\nconst DOWNLOAD_RESPONSE_TYPES = new Set([\"blob\", \"arraybuffer\", \"stream\"]);\n\n/**\n * The usual filter: every GET, plus any other request whose URL matches `writes` —\n * keksdose's `/\\/auth\\/(login|register|demo-session)\\b/` — but never a download\n * (`responseType` `\"blob\"`, `\"arraybuffer\"` or `\"stream\"`). Keep upload routes out of\n * the pattern (see the module comment).\n */\nexport function watchReadsAnd(writes?: RegExp): ServerWakeFilter {\n  return (method, url, request) =>\n    !DOWNLOAD_RESPONSE_TYPES.has(request?.responseType ?? \"\") &&\n    (method === \"get\" || (writes !== undefined && writes.test(url)));\n}\n\nfunction isOffline(): boolean {\n  return typeof navigator !== \"undefined\" && navigator.onLine === false;\n}\n\nexport function createServerWake({\n  slowMs = 2000,\n  wakingMs = 7000,\n  shouldWatch = watchReadsAnd(),\n}: ServerWakeOptions = {}): ServerWakeWatcher {\n  // When each counted request went out, oldest first; its length is the count.\n  //\n  // The stage is the age of the OLDEST outstanding request (0.51). It used to be the age of\n  // the first request since the count was last zero, so overlapping reads that were each\n  // fast — one going out before the last came back, on a busy page — chained past 2 s and\n  // showed \"taking longer than usual\" with nothing slow at all (keksdose live #454, found\n  // there while chasing a read that really was slow).\n  //\n  // `end()` names no request, so it retires the OLDEST start. When a newer request comes\n  // back first, the start left standing for the older one is later than its own, so the\n  // age read is never MORE than the oldest request's real age: a notice can come late,\n  // never falsely.\n  const starts: number[] = [];\n  let stage: ServerWakeStage = \"idle\";\n  let slowTimer: ReturnType<typeof setTimeout> | null = null;\n  let wakingTimer: ReturnType<typeof setTimeout> | null = null;\n  const listeners = new Set<() => void>();\n\n  const setStage = (next: ServerWakeStage) => {\n    if (next === stage) return;\n    stage = next;\n    for (const listener of listeners) listener();\n  };\n\n  const clearTimers = () => {\n    if (slowTimer !== null) clearTimeout(slowTimer);\n    if (wakingTimer !== null) clearTimeout(wakingTimer);\n    slowTimer = null;\n    wakingTimer = null;\n  };\n\n  // The stage for the oldest outstanding request's age, and timers for what is still to\n  // come. With none outstanding: idle.\n  const arm = () => {\n    clearTimers();\n    if (starts.length === 0) {\n      setStage(\"idle\");\n      return;\n    }\n    const age = Date.now() - starts[0];\n    setStage(age >= wakingMs ? \"waking\" : age >= slowMs ? \"slow\" : \"idle\");\n    if (age < slowMs) slowTimer = setTimeout(() => setStage(\"slow\"), slowMs - age);\n    if (age < wakingMs) wakingTimer = setTimeout(() => setStage(\"waking\"), wakingMs - age);\n  };\n\n  const start = (method?: string, url?: string, request: ServerWakeRequest = { method, url }): boolean => {\n    if (isOffline()) return false;\n    if (!shouldWatch((method ?? \"get\").toLowerCase(), url ?? \"\", request)) return false;\n    starts.push(Date.now());\n    // A request joining others does not move the clock: a page firing a second read at\n    // 1.9 s is still waiting on the same sleeping server, not starting afresh.\n    if (starts.length === 1) arm();\n    return true;\n  };\n\n  const end = () => {\n    if (starts.length === 0) return;\n    // The server answered (or gave up on) one of them, so the oldest's clock is over; the\n    // next oldest's age decides, which may well put the notice away again.\n    starts.shift();\n    arm();\n  };\n\n  return {\n    start,\n    end,\n    track<T>(work: PromiseLike<T> | (() => PromiseLike<T>), request: ServerWakeRequest = {}) {\n      const counted = start(request.method, request.url, request);\n      let promise: Promise<T>;\n      try {\n        promise = Promise.resolve(typeof work === \"function\" ? work() : work);\n      } catch (error) {\n        // A thunk that throws before it returns a promise settled too.\n        promise = Promise.reject(error);\n      }\n      return counted ? promise.finally(end) : promise;\n    },\n    reset() {\n      starts.length = 0;\n      clearTimers();\n      setStage(\"idle\");\n    },\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    getStage: () => stage,\n    getInFlight: () => starts.length,\n  };\n}\n\n/**\n * The shared instance: what `<ServerWakeNotice />`, `useServerWakeStage()`,\n * {@link attachServerWake} and {@link wrapFetch} use when no watcher is passed. GETs\n * only, default timings — an app that also watches its login POST creates its own\n * with {@link createServerWake} and passes it to both ends.\n */\nexport const serverWake: ServerWakeWatcher = createServerWake();\n\n// ── axios ─────────────────────────────────────────────────────────────────────\n\n/** The config fields the watchdog reads — what axios's request config has. The whole\n *  config reaches the filter, so an app's filter can read the rest of it. */\nexport interface ServerWakeAxiosConfig {\n  method?: string;\n  url?: string;\n  responseType?: string;\n}\n\n/** The slice of an interceptor manager the adapter uses. A method (not a function\n *  property) so axios's wider `use(onFulfilled?, onRejected?, options?)` fits it. */\ninterface InterceptorManagerLike<V> {\n  use(onFulfilled: (value: V) => V | Promise<V>, onRejected: (error: unknown) => unknown): number;\n  eject(id: number): void;\n}\n\n/** An axios instance, structurally — so the kit types the adapter without importing\n *  axios. `axios.create()`'s result fits it as is. */\nexport interface AxiosLikeInstance<C extends ServerWakeAxiosConfig, R extends { config: C }> {\n  interceptors: {\n    request: InterceptorManagerLike<C>;\n    response: InterceptorManagerLike<R>;\n  };\n}\n\n/** Whether the watchdog counted this request — the response side owes a matching\n *  `end()` only then. On the config, as keksdose's `_wake` was: it travels with the\n *  request onto the response and onto an error. Cleared once settled, so a 401 replay\n *  of the same config re-enters the request interceptor and is counted afresh — the\n *  pairing stays balanced. */\nconst COUNTED = \"_serverWake\";\ntype Marked = { [COUNTED]?: boolean };\n\n/**\n * Drive a watcher from an axios instance's interceptors: `attachServerWake(api)`.\n * Returns a function that ejects both interceptors again.\n *\n * Attach it BEFORE the app's own response interceptors: axios runs those in the order\n * they were added, so the wake one ends the wait before a 401 handler awaits a token\n * refresh — otherwise the notice would keep counting a request that has already been\n * answered. (Request-side order does not matter.)\n */\nexport function attachServerWake<C extends ServerWakeAxiosConfig, R extends { config: C }>(\n  instance: AxiosLikeInstance<C, R>,\n  watcher: ServerWakeWatcher = serverWake,\n): () => void {\n  const settle = (config: unknown) => {\n    const marked = config as Marked | undefined;\n    if (marked?.[COUNTED]) {\n      marked[COUNTED] = false;\n      watcher.end();\n    }\n  };\n  const request = instance.interceptors.request.use(\n    (config) => {\n      (config as C & Marked)[COUNTED] = watcher.start(config.method, config.url, config);\n      return config;\n    },\n    (error) => Promise.reject(error),\n  );\n  const response = instance.interceptors.response.use(\n    (res) => {\n      settle(res.config);\n      return res;\n    },\n    (error) => {\n      settle((error as { config?: unknown } | null)?.config);\n      return Promise.reject(error);\n    },\n  );\n  return () => {\n    instance.interceptors.request.eject(request);\n    instance.interceptors.response.eject(response);\n  };\n}\n\n// ── fetch ─────────────────────────────────────────────────────────────────────\n\n/**\n * A `fetch` that drives a watcher: `const apiFetch = wrapFetch(fetch)`. The wait ends\n * when the response's HEADERS arrive (or the call fails) — the server is awake by then,\n * however long the body takes.\n */\nexport function wrapFetch(\n  fetchImpl: typeof fetch = globalThis.fetch,\n  watcher: ServerWakeWatcher = serverWake,\n): typeof fetch {\n  return (input, init) => {\n    const request = typeof Request !== \"undefined\" && input instanceof Request ? input : undefined;\n    const method = init?.method ?? request?.method;\n    const url = typeof input === \"string\" ? input : input instanceof URL ? input.href : (request?.url ?? \"\");\n    return watcher.track(() => fetchImpl(input, init), { method, url });\n  };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/lib/server-wake.ts"],"sourcesContent":["/**\n * \"Is the server asleep, or is the app broken?\" — the cold-start watchdog, lifted\n * from keksdose (feedback #199) so kastlan and Kurvenschmiede get it too.\n *\n * All three backends run on Cloud Run with `--min-instances=0`: after an idle\n * period the container is gone and the first request has to start it, which takes\n * several seconds and occasionally more. Nothing in the UI said so, and none of the\n * axios instances has a timeout, so the honest experience was a spinner that looked\n * stuck. This counts the in-flight requests a cold start would actually delay and\n * escalates in two steps, so a merely slow response says \"still loading\" and only a\n * genuinely long wait blames the sleeping server.\n *\n * Framework-free on purpose (no zustand, no axios, no React): a counter, two timers\n * and a listener set, read by `useServerWakeStage` through `useSyncExternalStore`.\n * The adapters below take the app's axios instance / fetch as an ARGUMENT, so the\n * kit never imports either.\n *\n * WHAT ARMS IT, and why the default is narrow:\n *   - reads (GET) — what every page does on open — always;\n *   - writes only when the app says so (`watchReadsAnd(/\\/auth\\/login\\b/)`): the\n *     auth POSTs that gate the app are the only writes a user waits on before the\n *     app exists at all, so a cold start there looks exactly like a broken login.\n * An UPLOAD must never be watched — a statement PDF or a photo takes seconds on a\n * perfectly warm server, and \"the server is waking up\" during a 4 s upload would\n * simply be false. With the default that holds by itself (an upload is a POST);\n * an app widening `shouldWatch` keeps its upload routes out of it.\n *\n * Nor a DOWNLOAD, for the same reason (kastlan 0.18): axios answers only once the\n * whole body is in, so a generated PDF or a large photo — a GET — ran past both\n * thresholds on a warm server, and held the count for every read beside it. The\n * default filter skips a request whose `responseType` is `\"blob\"`, `\"arraybuffer\"` or\n * `\"stream\"`; a custom filter gets the request as its third argument to do the same.\n * (`wrapFetch` ends the wait at the headers, so a download through it is harmless.)\n *\n * It never arms while the browser is offline, whatever `shouldWatch` says: that state\n * has its own, truthful indicator, and a request that never left the device is not\n * evidence of anything about the server.\n *\n * A READ THAT IS HEAVY ON PURPOSE (0.55) — a report the server computes for a few\n * seconds — says so with `slowOk` on its request (the axios config, or `track`'s\n * request): it is counted, but never called slow, so it shows nothing while it is under\n * `wakingMs`. Past `wakingMs` it is the server waking like any other read. A read that\n * can take longer than that on a warm server stays out of the watch (`shouldWatch`).\n */\n\n/** `slow` = longer than a warm server ever takes; `waking` = long enough that a cold\n *  start is the only sensible explanation. */\nexport type ServerWakeStage = \"idle\" | \"slow\" | \"waking\";\n\n/** Decides which requests count. `method` arrives lower-cased (`\"get\"` when the\n *  request named none — axios's and fetch's default); `url` as the client had it;\n *  `request` is what the adapter saw — for axios the request config itself, so\n *  `responseType` or the app's own fields can decide. */\nexport type ServerWakeFilter = (method: string, url: string, request: ServerWakeRequest) => boolean;\n\nexport interface ServerWakeOptions {\n  /** Past this, a warm round trip is out of the question (a cold database query on a\n   *  free tier can still take a second, so it is not tighter). Default 2000 ms. */\n  slowMs?: number;\n  /** Past this, the container was almost certainly scaled to zero. Default 7000 ms. */\n  wakingMs?: number;\n  /** Which requests count. Default {@link watchReadsAnd}`()` — GETs only, downloads\n   *  excluded. The offline guard runs before it and cannot be overridden. */\n  shouldWatch?: ServerWakeFilter;\n}\n\n/** What a request is, for {@link ServerWakeWatcher.track} and a {@link ServerWakeFilter}. */\nexport interface ServerWakeRequest {\n  method?: string;\n  url?: string;\n  /** axios's `responseType`. `\"blob\"`, `\"arraybuffer\"` and `\"stream\"` mark a download,\n   *  which the default filter does not count. */\n  responseType?: string;\n  /**\n   * This read is slow on purpose (0.55; the per-request opt-out adopt-0.51 left open): it\n   * still counts, but its own age never shows \"taking longer than usual\" — only past\n   * `wakingMs`, when a cold start is the likelier story, does it show the server waking.\n   * The stage then follows the other requests out beside it, as ever.\n   *\n   * ONLY for a read that is heavy but answers under `wakingMs` (7 s) on a warm server: a\n   * report computed on request, a large page of rows. A read that can take longer — an\n   * export rendered on the server, a slow third party behind the route — would say \"the\n   * server is waking up\" on a warm server; keep it out of the watch through `shouldWatch`\n   * instead (kastlan's advice), as a download and an upload are.\n   *\n   * On axios it rides the request config: `api.get(url, { slowOk: true })` (declare it on\n   * `AxiosRequestConfig` once, by module augmentation); through `track`, on its request.\n   */\n  slowOk?: boolean;\n}\n\n/**\n * One counted request, as {@link ServerWakeWatcher.start} names it (0.55, keksdose's 0.51\n * review N4): a positive whole number, unique for the watcher's lifetime, which\n * {@link ServerWakeWatcher.end} takes back to end exactly that request. `start` returns\n * `false` where it counts nothing, as before: the token is truthy where `start` returned\n * `true` until 0.55, so code that only tests it reads as it did.\n */\nexport type ServerWakeToken = number;\n\nexport interface ServerWakeWatcher {\n  /**\n   * Count a request that is going out, and arm the escalation if it is the first.\n   * Returns its {@link ServerWakeToken}, or `false` when it was not counted (until 0.55\n   * `true` / `false`; the token is truthy where `true` was). The caller MUST end every\n   * counted request exactly once, or the counter never returns to zero and the notice\n   * sticks: `end(token)`, which ends that request, or a bare `end()`, as before. (The\n   * axios adapter stashes the token on the request config for that reason.)\n   * `request` reaches the filter as its third argument; default `{ method, url }`.\n   */\n  start(method?: string, url?: string, request?: ServerWakeRequest): ServerWakeToken | false;\n  /**\n   * A counted request settled — either way: an error still proves the server answered or\n   * gave up. The stage then follows the oldest request still out (0.51), so the notice\n   * goes away when the last one does, or sooner when the rest are recent.\n   *\n   * With `token` (0.55), exactly that request is retired, so the age the stage is read\n   * from is the real one; a token that was ended already (or reset away), or `false`, is\n   * a no-op. A bare `end()` — the call before 0.55 — retires the OLDEST start, which can\n   * make a notice come late, never falsely. Never takes the counter below zero.\n   */\n  end(token?: ServerWakeToken | false): void;\n  /** `start` + `end` around a promise (or a function returning one), for a request\n   *  that does not go through an adapter. Resolves and rejects as the work does. */\n  track<T>(work: PromiseLike<T> | (() => PromiseLike<T>), request?: ServerWakeRequest): Promise<T>;\n  /** Back to a pristine watchdog — for tests, which share an instance across cases. */\n  reset(): void;\n  /** `useSyncExternalStore`'s pair. Listeners hear stage changes only. */\n  subscribe(listener: () => void): () => void;\n  getStage(): ServerWakeStage;\n  /** Counted requests currently outstanding. */\n  getInFlight(): number;\n}\n\n/** Response types that make a request a download — see the module comment. */\nconst DOWNLOAD_RESPONSE_TYPES = new Set([\"blob\", \"arraybuffer\", \"stream\"]);\n\n/**\n * The usual filter: every GET, plus any other request whose URL matches `writes` —\n * keksdose's `/\\/auth\\/(login|register|demo-session)\\b/` — but never a download\n * (`responseType` `\"blob\"`, `\"arraybuffer\"` or `\"stream\"`). Keep upload routes out of\n * the pattern (see the module comment).\n */\nexport function watchReadsAnd(writes?: RegExp): ServerWakeFilter {\n  return (method, url, request) =>\n    !DOWNLOAD_RESPONSE_TYPES.has(request?.responseType ?? \"\") &&\n    (method === \"get\" || (writes !== undefined && writes.test(url)));\n}\n\nfunction isOffline(): boolean {\n  return typeof navigator !== \"undefined\" && navigator.onLine === false;\n}\n\nexport function createServerWake({\n  slowMs = 2000,\n  wakingMs = 7000,\n  shouldWatch = watchReadsAnd(),\n}: ServerWakeOptions = {}): ServerWakeWatcher {\n  // Each counted request still out — its token and when it went out — oldest first; its\n  // length is the count.\n  //\n  // The stage is the age of the OLDEST outstanding request (0.51). It used to be the age of\n  // the first request since the count was last zero, so overlapping reads that were each\n  // fast — one going out before the last came back, on a busy page — chained past 2 s and\n  // showed \"taking longer than usual\" with nothing slow at all (keksdose live #454, found\n  // there while chasing a read that really was slow).\n  //\n  // `end(token)` (0.55, keksdose's 0.51 review N4) retires exactly the request that\n  // settled. A bare `end()` names none, so it retires the OLDEST start: when a newer\n  // request came back first, the start left standing for the older one is later than its\n  // own, so the age read is never MORE than the oldest request's real age — a notice can\n  // come late, never falsely. The token makes it exact.\n  //\n  // A `slowOk` request (0.55) is timed for \"waking\" like the rest, never for \"slow\": the\n  // slow stage reads the oldest request out that is NOT slowOk.\n  const starts: Array<{ token: ServerWakeToken; at: number; slowOk: boolean }> = [];\n  // The last token handed out. Never reset, not even by `reset()`: a token from before a\n  // reset must not name a request after it.\n  let lastToken = 0;\n  let stage: ServerWakeStage = \"idle\";\n  let slowTimer: ReturnType<typeof setTimeout> | null = null;\n  let wakingTimer: ReturnType<typeof setTimeout> | null = null;\n  const listeners = new Set<() => void>();\n\n  const setStage = (next: ServerWakeStage) => {\n    if (next === stage) return;\n    stage = next;\n    for (const listener of listeners) listener();\n  };\n\n  const clearTimers = () => {\n    if (slowTimer !== null) clearTimeout(slowTimer);\n    if (wakingTimer !== null) clearTimeout(wakingTimer);\n    slowTimer = null;\n    wakingTimer = null;\n  };\n\n  // A timer only ever raises the stage: with a slowOk request oldest, the waking timer\n  // (its) can fire before the slow one (a newer read's), which must not take it back.\n  const raise = (next: \"slow\" | \"waking\") => {\n    if (stage !== \"waking\" && next !== stage) setStage(next);\n  };\n\n  // The stage for the outstanding requests' ages — \"waking\" from the oldest of all,\n  // \"slow\" from the oldest that is not slowOk — and timers for what is still to come.\n  // With none outstanding: idle.\n  const arm = () => {\n    clearTimers();\n    if (starts.length === 0) {\n      setStage(\"idle\");\n      return;\n    }\n    const now = Date.now();\n    const age = now - starts[0].at;\n    const slowFrom = starts.find((s) => !s.slowOk);\n    // `undefined` while every request out is slowOk: nothing to call slow.\n    const slowAge = slowFrom && now - slowFrom.at;\n    setStage(age >= wakingMs ? \"waking\" : slowAge !== undefined && slowAge >= slowMs ? \"slow\" : \"idle\");\n    if (slowAge !== undefined && slowAge < slowMs) slowTimer = setTimeout(() => raise(\"slow\"), slowMs - slowAge);\n    if (age < wakingMs) wakingTimer = setTimeout(() => raise(\"waking\"), wakingMs - age);\n  };\n\n  const start = (\n    method?: string,\n    url?: string,\n    request: ServerWakeRequest = { method, url },\n  ): ServerWakeToken | false => {\n    if (isOffline()) return false;\n    if (!shouldWatch((method ?? \"get\").toLowerCase(), url ?? \"\", request)) return false;\n    lastToken += 1;\n    const slowOk = request.slowOk === true;\n    starts.push({ token: lastToken, at: Date.now(), slowOk });\n    // A request joining others does not move the clock: a page firing a second read at\n    // 1.9 s is still waiting on the same sleeping server, not starting afresh. Only the\n    // first request out, or the first that may be called slow, starts one.\n    if (starts.length === 1 || (!slowOk && starts.every((s, i) => s.slowOk || i === starts.length - 1))) arm();\n    return lastToken;\n  };\n\n  const end = (token?: ServerWakeToken | false) => {\n    // Bare: the oldest. Named: that one, or nothing when it is not out (ended already, from\n    // before a reset, or `false`, never counted) — never another request in its place.\n    const index = token === undefined ? 0 : starts.findIndex((s) => s.token === token);\n    if (index < 0 || index >= starts.length) return;\n    // The server answered (or gave up on) it, so its clock is over; the oldest still out\n    // decides, which may well put the notice away again.\n    starts.splice(index, 1);\n    arm();\n  };\n\n  return {\n    start,\n    end,\n    track<T>(work: PromiseLike<T> | (() => PromiseLike<T>), request: ServerWakeRequest = {}) {\n      const token = start(request.method, request.url, request);\n      let promise: Promise<T>;\n      try {\n        promise = Promise.resolve(typeof work === \"function\" ? work() : work);\n      } catch (error) {\n        // A thunk that throws before it returns a promise settled too.\n        promise = Promise.reject(error);\n      }\n      // Its own token, so a tracked request ends exactly itself (0.55).\n      return token ? promise.finally(() => end(token)) : promise;\n    },\n    reset() {\n      starts.length = 0;\n      clearTimers();\n      setStage(\"idle\");\n    },\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    getStage: () => stage,\n    getInFlight: () => starts.length,\n  };\n}\n\n/**\n * The shared instance: what `<ServerWakeNotice />`, `useServerWakeStage()`,\n * {@link attachServerWake} and {@link wrapFetch} use when no watcher is passed. GETs\n * only, default timings — an app that also watches its login POST creates its own\n * with {@link createServerWake} and passes it to both ends.\n */\nexport const serverWake: ServerWakeWatcher = createServerWake();\n\n// ── axios ─────────────────────────────────────────────────────────────────────\n\n/** The config fields the watchdog reads — what axios's request config has. The whole\n *  config reaches the filter, so an app's filter can read the rest of it. */\nexport interface ServerWakeAxiosConfig {\n  method?: string;\n  url?: string;\n  responseType?: string;\n  /** A read slow on purpose — see {@link ServerWakeRequest.slowOk} (0.55). */\n  slowOk?: boolean;\n}\n\n/** The slice of an interceptor manager the adapter uses. A method (not a function\n *  property) so axios's wider `use(onFulfilled?, onRejected?, options?)` fits it. */\ninterface InterceptorManagerLike<V> {\n  use(onFulfilled: (value: V) => V | Promise<V>, onRejected: (error: unknown) => unknown): number;\n  eject(id: number): void;\n}\n\n/** An axios instance, structurally — so the kit types the adapter without importing\n *  axios. `axios.create()`'s result fits it as is. */\nexport interface AxiosLikeInstance<C extends ServerWakeAxiosConfig, R extends { config: C }> {\n  interceptors: {\n    request: InterceptorManagerLike<C>;\n    response: InterceptorManagerLike<R>;\n  };\n}\n\n/** The token the watchdog gave this request, when it counted it — the response side owes\n *  a matching `end(token)` only then, and ends exactly this request (0.55; a `true` and\n *  a bare `end()` until then). On the config, as keksdose's `_wake` was: it travels with\n *  the request onto the response and onto an error. Cleared once settled, so a 401 replay\n *  of the same config re-enters the request interceptor and is counted afresh — the\n *  pairing stays balanced. */\nconst COUNTED = \"_serverWake\";\ntype Marked = { [COUNTED]?: ServerWakeToken | false };\n\n/**\n * Drive a watcher from an axios instance's interceptors: `attachServerWake(api)`.\n * Returns a function that ejects both interceptors again.\n *\n * Attach it BEFORE the app's own response interceptors: axios runs those in the order\n * they were added, so the wake one ends the wait before a 401 handler awaits a token\n * refresh — otherwise the notice would keep counting a request that has already been\n * answered. (Request-side order does not matter.)\n */\nexport function attachServerWake<C extends ServerWakeAxiosConfig, R extends { config: C }>(\n  instance: AxiosLikeInstance<C, R>,\n  watcher: ServerWakeWatcher = serverWake,\n): () => void {\n  const settle = (config: unknown) => {\n    const marked = config as Marked | undefined;\n    const token = marked?.[COUNTED];\n    if (marked && token) {\n      marked[COUNTED] = false;\n      watcher.end(token);\n    }\n  };\n  const request = instance.interceptors.request.use(\n    (config) => {\n      (config as C & Marked)[COUNTED] = watcher.start(config.method, config.url, config);\n      return config;\n    },\n    (error) => Promise.reject(error),\n  );\n  const response = instance.interceptors.response.use(\n    (res) => {\n      settle(res.config);\n      return res;\n    },\n    (error) => {\n      settle((error as { config?: unknown } | null)?.config);\n      return Promise.reject(error);\n    },\n  );\n  return () => {\n    instance.interceptors.request.eject(request);\n    instance.interceptors.response.eject(response);\n  };\n}\n\n// ── fetch ─────────────────────────────────────────────────────────────────────\n\n/**\n * A `fetch` that drives a watcher: `const apiFetch = wrapFetch(fetch)`. The wait ends\n * when the response's HEADERS arrive (or the call fails) — the server is awake by then,\n * however long the body takes.\n */\nexport function wrapFetch(\n  fetchImpl: typeof fetch = globalThis.fetch,\n  watcher: ServerWakeWatcher = serverWake,\n): typeof fetch {\n  return (input, init) => {\n    const request = typeof Request !== \"undefined\" && input instanceof Request ? input : undefined;\n    const method = init?.method ?? request?.method;\n    const url = typeof input === \"string\" ? input : input instanceof URL ? input.href : (request?.url ?? \"\");\n    return watcher.track(() => fetchImpl(input, init), { method, url });\n  };\n}\n"],"mappings":"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","names":[]}

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

@@ -33,6 +33,10 @@
  *
  * 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.
+ *
+ * Since 0.55, {@link watchSessionElsewhere} beside it: the session ending in ANOTHER tab,
+ * or while this page sat in the back/forward cache (kastlan reuse audit 2026-11-02,
+ * proposal 6).
  */
 import type { AxiosLikeInstance, ServerWakeAxiosConfig } from "./server-wake.js";
 /** What the app's `refresh` resolves: the new access token, plus whatever its `store`
@@ -197,4 +201,53 @@ interface SessionRefreshInstance<C extends SessionRefreshAxiosConfig, R extends
 export declare function attachSessionRefresh<C extends SessionRefreshAxiosConfig, R extends {
     config: C;
 }>(instance: SessionRefreshInstance<C, R>, session: SessionRefresh<SessionRenewal>): () => void;
+/** What the app hands {@link watchSessionElsewhere}. */
+export interface SessionElsewhereOptions {
+    /**
+     * Whether this tab's session is over: this tab holds one, and the storage every tab
+     * shares no longer does — its token removed by a sign-out elsewhere, the storage
+     * cleared — or holds another account's. Read where the app's request interceptor reads
+     * the token (`readStored`), against what this tab keeps in memory. A renewal elsewhere
+     * rewrites the token and is no end; a tab with no session has nothing to end.
+     */
+    ended: () => boolean;
+    /**
+     * The session is over in this tab: drop what this tab holds of it (the user, the query
+     * cache, the unlocked keys), then leave with a full load, of the sign-in or the demo's
+     * end. Not the app's whole sign-out: the other tab has already removed what the device
+     * kept, and may since have stored a session that is not this tab's to delete.
+     *
+     * Called once per session: further `storage` events while `ended` still reads `true`
+     * call nothing, until it has read `false` again. A restored page is asked afresh.
+     */
+    onEnded: () => void;
+    /** Also check a page the browser brings back from its back/forward cache (`pageshow`
+     *  with `persisted`). Default `true`. */
+    checkRestored?: boolean;
+}
+/**
+ * Watch for this tab's session ending in another tab (kastlan reuse audit 2026-11-02,
+ * proposal 6): `const stop = watchSessionElsewhere({ ended, onEnded })`, once per tab,
+ * beside the app's session store. Returns the function that stops watching.
+ *
+ * The session belongs to the device — its tokens sit in localStorage, which every tab
+ * shares — and the account on screen to the tab: the user, the query cache and the
+ * unlocked keys sit in this tab's memory. A sign-out in another tab changed the first and
+ * left the second, so this tab kept the previous account on screen and wrote its data
+ * back into the offline copy the other tab had just wiped (refactor audit 2026-10-30:
+ * keksdose FS-2, kastlan FLW-1). Two moments tell it:
+ *
+ *  - a `storage` event: another tab wrote or removed a key. `ended` is read after every
+ *    one, whatever its key — it reads the state, so it needs no list of keys, and a
+ *    cleared storage (`key` null) counts like any removal;
+ *  - a page restored from the back/forward cache (`pageshow` with `persisted`). Frozen
+ *    there, it heard no `storage` event and came back on the previous account, where it
+ *    could renew the old session and store its tokens again over the sign-out (keksdose
+ *    F-31; kastlan listened to `storage` alone). A fresh load reads the storage anyway,
+ *    so nothing is checked when the watch starts, nor on a `pageshow` that is no restore.
+ *
+ * Framework-free and storage-free: `ended` is the app's read, guarded where it reads
+ * (the kit's `readStored` never throws). Nothing is watched where there is no `window`.
+ */
+export declare function watchSessionElsewhere(options: SessionElsewhereOptions): () => void;
 export {};

package/dist/lib/session-refresh.js

@@ -178,10 +178,36 @@ function attachSessionRefresh(instance, session) {
     instance.interceptors.response.eject(response);
   };
 }
+function watchSessionElsewhere(options) {
+  if (typeof window === "undefined") return () => void 0;
+  let told = false;
+  const check = () => {
+    if (!options.ended()) {
+      told = false;
+      return;
+    }
+    if (told) return;
+    told = true;
+    options.onEnded();
+  };
+  const onStorage = () => check();
+  const onPageShow = (event) => {
+    if (!event.persisted) return;
+    told = false;
+    check();
+  };
+  window.addEventListener("storage", onStorage);
+  if (options.checkRestored !== false) window.addEventListener("pageshow", onPageShow);
+  return () => {
+    window.removeEventListener("storage", onStorage);
+    window.removeEventListener("pageshow", onPageShow);
+  };
+}
 export {
   attachSessionRefresh,
   createSessionRefresh,
   isSignedOutStep,
-  isTransientRefreshFailure
+  isTransientRefreshFailure,
+  watchSessionElsewhere
 };
 //# sourceMappingURL=session-refresh.js.map

package/dist/lib/session-refresh.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/lib/session-refresh.ts"],"sourcesContent":["/**\n * Renewing a session when the access token runs out: the client half of\n * docs/auth-harmonization.md §11 (round 0.34 C7, KS U6), lifted from keksdose's\n * `refreshOnce` (Kurvenschmiede's is the same, line for line) and corrected where the\n * three apps' reviews found it wrong. It ends kastlan's sign-out over a network blip (B3).\n *\n * THE KIT OWNS THE RULE, THE APP OWNS THE CALL (§11.2, decision 1). The kit decides when\n * to refresh, who waits, what a failure means, when the session is over and whether a\n * renewal may still be stored. The app keeps its endpoint, its token storage, its\n * sign-out and where it navigates, and hands them in as {@link SessionRefreshOptions}.\n *\n *  - **One flight per tab** (decision 2): every 401 that arrives while a refresh runs\n *    waits for it, and so does `session.refresh()` (kastlan's boot).\n *  - **Definitive** (decision 3): the device holds no refresh token (`refresh` resolves\n *    `null`), the refresh answers 401 or 403, or the request replayed with the fresh\n *    token gets a 401 again. Only then does the app sign out (`onEnded`), and only while\n *    that session is still the app's.\n *  - **Transient** (decision 4): everything else. The session stays: nothing is signed\n *    out, stored or redirected, and the kit shows nothing. The request rejects with its\n *    OWN 401, marked ({@link isTransientRefreshFailure}), so the app's message can say\n *    \"can't reach the server\" instead of \"not signed in\".\n *  - **Retries only where waiting helps** (decision 5, KS 7): no answer, the kit's own\n *    timeout, 408, 429 and 5xx get up to three attempts, 1 s and then 3 s apart, each cut\n *    off after 15 s; none while the browser reports itself offline. Any other answer, and\n *    anything that is not an HTTP error, ends the flight at the first attempt.\n *  - **A stale session is never written back** (§11.7, ka 3, KS 3, KS 4): every request\n *    is stamped with `currentToken()` when it goes out, and every flight notes it when it\n *    starts. A 401 to a request sent with an older token replays it with the app's token\n *    now, without a refresh; a flight whose session changed while it ran stores nothing\n *    and ends nothing. The access token is the session's identity because every change\n *    the apps make replaces it — a refresh, another tab, a company switch, a password\n *    change, a sign-in, a demo start, a sign-out.\n *\n * Framework-free like `server-wake.ts`: {@link attachSessionRefresh} takes the app's\n * axios instance as an ARGUMENT, typed structurally, so the kit never imports axios.\n */\n\nimport type { AxiosLikeInstance, ServerWakeAxiosConfig } from \"./server-wake\";\nimport { httpStatusOf } from \"./http-status\";\n\n/** What the app's `refresh` resolves: the new access token, plus whatever its `store`\n *  needs (its refresh token, the user). */\nexport interface SessionRenewal {\n  /** The new access token; the waiting requests are replayed with it. */\n  token: string;\n  /**\n   * `false`: store the renewal, but replay nothing — each waiting request rejects with\n   * its 401, unmarked. kastlan's refresh can land in another company (§11.5, ka 3): a\n   * waiting write, such as the handover's `POST /sync`, must not be replayed into it.\n   */\n  replay?: false;\n}\n\n/** What the app hands {@link createSessionRefresh} (§11.4). */\nexport interface SessionRefreshOptions<R extends SessionRenewal> {\n  /**\n   * The app's own `POST /auth/refresh`, on a BARE client — never the instance the kit is\n   * attached to, so the refresh cannot re-enter the interceptor. It **writes nothing**:\n   * the kit hands the answer to `store`, and only while the session is unchanged.\n   *\n   * Resolves the answer as a renewal, or `null` when the device holds no refresh token.\n   * Throws on failure, and the kit classifies the throw: a 401 or 403 is definitive; no\n   * answer (an axios error without a `response`), the kit's own timeout, 408, 429 and\n   * 5xx are transient and retried; any other answer, and anything that is not an HTTP\n   * error (a bug in this function), is transient and not retried. The status is read\n   * from `err.response.status` (axios), `err.status` or `err.statusCode`.\n   *\n   * `signal` aborts when the attempt runs past `timeoutMs`; pass it to the request.\n   */\n  refresh: (signal: AbortSignal) => Promise<R | null>;\n  /** Writes the renewal: the tokens and the user (a missing refresh token keeps the\n   *  stored one). Called only while the session the flight renews is still the app's,\n   *  and before the waiting requests are replayed — so it writes the token SYNCHRONOUSLY\n   *  where `currentToken` reads it: the replay goes through the app's own request\n   *  interceptor again, and is stamped then. A throw is the app's bug: the waiting\n   *  requests and `session.refresh()` reject with it. */\n  store: (renewal: R) => void;\n  /** The access token the app sends NOW, read where its request interceptor reads it;\n   *  `null` when there is none. */\n  currentToken: () => string | null;\n  /** Whether the session is a demo: a demo's 401 ends it, with no refresh tried\n   *  (landing-demo §5.5). */\n  isDemo: () => boolean;\n  /**\n   * The session is over: drop the tokens and the user, then navigate — `/demo/ended` for\n   * a demo, else the sign-in with the page it came from (auth §5.2). Called once per\n   * session, however many requests found out (KS 8), and never by `session.refresh()`.\n   */\n  onEnded: (ended: { demo: boolean }) => void;\n  /** Whether a URL is a signed-out step, whose 401 judges the form and never the\n   *  session. Replaces the default list, {@link isSignedOutStep}. */\n  isSignedOutStep?: (url: string) => boolean;\n  /** Attempts for a refresh that got no answer, timed out, or got a 408, 429 or 5xx.\n   *  Default 3. */\n  attempts?: number;\n  /** The waits before the second and later attempts; the last one repeats. Default\n   *  `[1000, 3000]`. */\n  backoffMs?: readonly number[];\n  /** Each attempt is cut off after this, and its `signal` aborted. Default 15 000. */\n  timeoutMs?: number;\n}\n\n/** What `session.refresh()` resolves (§11.4), by `result`:\n *\n * | `result` | When | What the kit has done |\n * |---|---|---|\n * | `\"renewed\"` | a renewal while the session was unchanged | `store(renewal)` |\n * | `\"ended\"` | definitive | nothing; `onEnded` only for requests that waited on the same flight |\n * | `\"transient\"` | transient | nothing |\n * | `\"changed\"` | the session changed while it ran | nothing; read the app's own state |\n */\nexport type SessionRefreshOutcome<R extends SessionRenewal = SessionRenewal> =\n  { result: \"renewed\"; renewal: R } | { result: \"ended\" } | { result: \"transient\" } | { result: \"changed\" };\n\n/** The flight {@link createSessionRefresh} makes; {@link attachSessionRefresh} hooks it\n *  to an axios instance. */\nexport interface SessionRefresh<R extends SessionRenewal = SessionRenewal> {\n  /**\n   * The same flight, for a caller outside the interceptor — kastlan's boot. Joins a\n   * running flight, or starts one. Never calls `onEnded`: the caller decides what an\n   * `\"ended\"` means for it.\n   */\n  refresh(): Promise<SessionRefreshOutcome<R>>;\n}\n\n// ── The signed-out steps ──────────────────────────────────────────────────────\n\n/**\n * Every `/auth/` call made without a session, the union of the three apps' lists\n * (§11.3): signing in (with its `2fa` and `set-password` steps, and a passkey's), up,\n * into a demo, a password reset, the verification link, the invitation check, the email\n * change's confirmation link, and the refresh itself. NOT `resend-verification` (KS 1):\n * in keksdose and Kurvenschmiede it needs a session; in kastlan it never answers 401.\n */\nconst SIGNED_OUT_STEPS = [\n  \"login\",\n  \"passkey/login\",\n  \"register\",\n  \"demo-session\",\n  \"password-reset\",\n  \"verify-email\",\n  \"invitations/check\",\n  \"me/email/confirm\",\n  \"refresh\",\n] as const;\n\n/**\n * Whether a request's URL is a signed-out step — the kit's default list (§11.3), exported\n * for an app's tests and for an app's own `isSignedOutStep` that adds to it.\n *\n * **Whole steps only** (KS 2): the part of the path after its `auth/` segment, without\n * the query string, is the entry itself or starts with the entry and a `/`. So\n * `login/2fa` is `login`'s, but `register` never catches `/auth/passkey/register/begin`\n * (adding a passkey, which needs a session), `invitations/check` never\n * `/auth/invitations/accept`, and `me/email/confirm` never `/auth/me/email`. Relative and\n * absolute URLs alike; a URL with no `auth` segment is no step.\n */\nexport function isSignedOutStep(url: string): boolean {\n  const path = url.replace(/[?#].*$/s, \"\").replace(/^([a-z][a-z\\d+.-]*:)?\\/\\/[^/]*/i, \"\");\n  const segments = path.split(\"/\");\n  const at = segments.indexOf(\"auth\");\n  if (at < 0) return false;\n  const step = segments.slice(at + 1).join(\"/\");\n  return SIGNED_OUT_STEPS.some((entry) => step === entry || step.startsWith(`${entry}/`));\n}\n\n// ── The marker ────────────────────────────────────────────────────────────────\n\n/** On the request's own axios error, after a transient failure (decision 8). A\n *  `Symbol.for` key: shared by every copy of the kit in a page, and left out of\n *  `JSON.stringify`, so a log that serialises the error doesn't print it (kk 2). */\nconst TRANSIENT = Symbol.for(\"@eifi1/ui-kit:session-refresh.transient\");\n\n/**\n * Whether a request was refused because the refresh behind it failed TRANSIENTLY —\n * offline, a timeout, a 5xx — and not because the session is over (decision 8). The\n * error is the request's own 401, `err.response?.status` and every check an app already\n * has keep working; this reads the mark the kit put on it, so the app's message can say\n * \"can't reach the server\" instead of \"not signed in\". Read it FIRST: keksdose's sync\n * chip, kastlan's handover sync and Kurvenschmiede's `apiErrorMessage` count it as\n * offline (§11.5).\n *\n * Not the refresh's own error: its config carries the refresh token in its body, into any\n * log or crash report that keeps the error.\n */\nexport function isTransientRefreshFailure(error: unknown): boolean {\n  return typeof error === \"object\" && error !== null && (error as Record<symbol, unknown>)[TRANSIENT] === true;\n}\n\n// ── The flight ────────────────────────────────────────────────────────────────\n\n/** A flight's result, as the interceptor needs it: `\"ended\"` keeps the session it ended. */\ntype Flight<R extends SessionRenewal> =\n  | { result: \"renewed\"; renewal: R }\n  | { result: \"ended\"; token: string | null }\n  | { result: \"transient\" }\n  | { result: \"changed\" };\n\n/** What one attempt came to. */\ntype Attempt<R> = { renewal: R } | \"definitive\" | \"retry\" | \"transient\";\n\n/** What {@link attachSessionRefresh} needs of a session. Kept off the public interface:\n *  only what {@link createSessionRefresh} made can be attached. */\ninterface Engine {\n  token(): string | null;\n  isDemo(): boolean;\n  isSignedOutStep(url: string): boolean;\n  join(): Promise<Flight<SessionRenewal>>;\n  end(token: string | null, demo: boolean): void;\n}\n\nconst engines = new WeakMap<SessionRefresh<SessionRenewal>, Engine>();\n\n/** The kit's own timeout, told apart from anything the app's `refresh` throws. */\nconst TIMED_OUT = Symbol(\"timed out\");\n\nfunction isOffline(): boolean {\n  return typeof navigator !== \"undefined\" && navigator.onLine === false;\n}\n\n/** A refresh's throw, classified (§11.4). The status is read where `isRateLimited` reads\n *  it — `httpStatusOf`, one probe for axios, ofetch and Node errors (DUP-11). */\nfunction classify(error: unknown): \"definitive\" | \"retry\" | \"transient\" {\n  if (error === TIMED_OUT) return \"retry\";\n  if (typeof error !== \"object\" || error === null) return \"transient\";\n  const status = httpStatusOf(error);\n  if (status === undefined) {\n    // No answer: axios marks its own errors, and one without a response never reached a\n    // server (offline, DNS, CORS, its own timeout). Anything else is a bug in `refresh`.\n    return (error as { isAxiosError?: unknown }).isAxiosError === true ? \"retry\" : \"transient\";\n  }\n  if (status === 401 || status === 403) return \"definitive\";\n  if (status === 408 || status === 429 || status >= 500) return \"retry\";\n  return \"transient\";\n}\n\nconst sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));\n\n/**\n * Make the flight: `const session = createSessionRefresh({ refresh, store, currentToken,\n * isDemo, onEnded })`, then {@link attachSessionRefresh}`(api, session)`. One per tab.\n */\nexport function createSessionRefresh<R extends SessionRenewal>(options: SessionRefreshOptions<R>): SessionRefresh<R> {\n  const { attempts = 3, backoffMs = [1000, 3000], timeoutMs = 15_000 } = options;\n  // An empty string is no token: the stamp and the flight compare tokens, and \"\" against\n  // `null` must not read as a change of session.\n  const token = () => options.currentToken() || null;\n\n  /** One call of the app's `refresh`, cut off after `timeoutMs` even if it ignores the\n   *  signal. */\n  const attempt = async (): Promise<Attempt<R>> => {\n    const controller = new AbortController();\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    const timeout = new Promise<never>((_, reject) => {\n      timer = setTimeout(() => {\n        reject(TIMED_OUT);\n        controller.abort();\n      }, timeoutMs);\n    });\n    try {\n      // Through `then`, so a `refresh` that throws before it returns a promise is\n      // classified like one that rejects.\n      const renewal = await Promise.race([Promise.resolve().then(() => options.refresh(controller.signal)), timeout]);\n      return renewal ? { renewal } : \"definitive\";\n    } catch (error) {\n      return classify(error);\n    } finally {\n      clearTimeout(timer);\n    }\n  };\n\n  const run = async (): Promise<Flight<R>> => {\n    // The session this flight renews (§11.3 step 5).\n    const noted = token();\n    const changed = () => token() !== noted;\n    let outcome = await attempt();\n    for (let made = 1; outcome === \"retry\"; made += 1) {\n      // No further attempt while the browser says it is offline, nor for a session that\n      // is no longer the app's: whatever the answer, it would be \"changed\".\n      if (made >= attempts || isOffline() || changed()) break;\n      await sleep(backoffMs[made - 1] ?? backoffMs[backoffMs.length - 1] ?? 0);\n      if (isOffline() || changed()) break;\n      outcome = await attempt();\n    }\n    // A late answer never writes the old session back over a sign-out, a demo start or a\n    // password change, and the old session's refusal never signs anyone out (KS 3).\n    if (changed()) return { result: \"changed\" };\n    if (outcome === \"definitive\") return { result: \"ended\", token: noted };\n    if (outcome === \"retry\" || outcome === \"transient\") return { result: \"transient\" };\n    options.store(outcome.renewal);\n    return { result: \"renewed\", renewal: outcome.renewal };\n  };\n\n  let flight: Promise<Flight<R>> | null = null;\n  const join = () => {\n    // Cleared before any waiter resumes (`finally` settles first), so a waiter that\n    // needs another flight starts a new one.\n    flight ??= run().finally(() => {\n      flight = null;\n    });\n    return flight;\n  };\n\n  /** The session `onEnded` was last called for: once per session (KS 8). */\n  let ended: { token: string | null } | undefined;\n\n  const session: SessionRefresh<R> = {\n    async refresh() {\n      const outcome = await join();\n      return outcome.result === \"ended\" ? { result: \"ended\" } : outcome;\n    },\n  };\n  engines.set(session, {\n    token,\n    isDemo: () => options.isDemo(),\n    isSignedOutStep: options.isSignedOutStep ?? isSignedOutStep,\n    join,\n    end(endedToken, demo) {\n      if (ended && ended.token === endedToken) return;\n      ended = { token: endedToken };\n      options.onEnded({ demo });\n    },\n  });\n  return session;\n}\n\n// ── axios ─────────────────────────────────────────────────────────────────────\n\n/** The config fields the kit reads and writes — what axios's request config has. */\ninterface SessionRefreshAxiosConfig extends ServerWakeAxiosConfig {\n  /** axios's `AxiosHeaders` (written through its `set`), or a plain record. */\n  headers?: unknown;\n}\n\n/** An axios instance, structurally: {@link AxiosLikeInstance}, plus `request(config)` for\n *  the replay. `axios.create()`'s result fits it as is. `NoInfer`, because axios's\n *  `request` takes the WIDER `AxiosRequestConfig`: inferred from there, the config type\n *  no longer fits the interceptors, which hand out `InternalAxiosRequestConfig`. */\ninterface SessionRefreshInstance<\n  C extends SessionRefreshAxiosConfig,\n  R extends { config: C },\n> extends AxiosLikeInstance<C, R> {\n  request(config: NoInfer<C>): Promise<unknown>;\n}\n\n/** The keys the kit keeps on a request's config, as `attachServerWake` keeps\n *  `_serverWake`: never a header. Plain string keys holding primitives, because axios\n *  copies the config on a replay (`mergeConfig`) and a symbol key would be dropped. */\nconst STAMP = \"_sessionStamp\";\nconst REFRESHED = \"_sessionRefreshed\";\nconst RESTAMPED = \"_sessionRestamped\";\ntype Marked = {\n  /** `currentToken()` when the request went out. */\n  [STAMP]?: string | null;\n  /** Replayed after a refresh: a 401 now is definitive (decision 3). */\n  [REFRESHED]?: boolean;\n  /** Replayed because it was sent with an older token: once for this reason. */\n  [RESTAMPED]?: boolean;\n};\n\n/** `Authorization: Bearer <token>` on a config about to be replayed. The app's own\n *  request interceptor runs again on the replay and writes the same, from the same\n *  source. */\nfunction authorize(config: SessionRefreshAxiosConfig, token: string): void {\n  const value = `Bearer ${token}`;\n  const headers = config.headers;\n  if (typeof headers !== \"object\" || headers === null) {\n    config.headers = { Authorization: value };\n  } else if (typeof (headers as { set?: unknown }).set === \"function\") {\n    (headers as { set(name: string, value: string): unknown }).set(\"Authorization\", value);\n  } else {\n    (headers as Record<string, unknown>).Authorization = value;\n  }\n}\n\n/**\n * Hook a session to an axios instance: `attachSessionRefresh(api, session)`. Adds a\n * request interceptor (the stamp) and a response interceptor (the 401), and returns a\n * function that ejects both.\n *\n * Attach it LAST (§11.3, kk 4): after `attachServerWake`, which asks to be first, and\n * after the app's own response interceptors (logging, a watchdog of its own). axios runs\n * response interceptors in the order they were added, and each of those must see the 401\n * settle before the refresh is awaited. The request side's order does not matter.\n *\n * On a 401, in this order (§11.3):\n *\n *  1. a signed-out step → reject, nothing else;\n *  2. sent with an older token → replayed with the app's token now, with no refresh, once\n *     for this reason; with no token now, reject;\n *  3. a demo → `onEnded({ demo: true })`, reject;\n *  4. already replayed after a refresh → definitive: `onEnded({ demo: false })`, reject;\n *  5. otherwise it joins the flight, or starts it. A renewal replays it once with the\n *     renewal's token (`replay: false`: rejects, unmarked); definitive ends the session;\n *     transient rejects, marked; a session that changed meanwhile sends it through step\n *     2 again.\n *\n * Every rejection is the request's OWN error. Any other status passes through untouched.\n */\nexport function attachSessionRefresh<C extends SessionRefreshAxiosConfig, R extends { config: C }>(\n  instance: SessionRefreshInstance<C, R>,\n  session: SessionRefresh<SessionRenewal>,\n): () => void {\n  const engine = engines.get(session);\n  if (!engine) throw new TypeError(\"attachSessionRefresh takes the session createSessionRefresh made\");\n\n  const onUnauthorized = async (error: object, config: C & Marked): Promise<unknown> => {\n    if (engine.isSignedOutStep(config.url ?? \"\")) throw error;\n    // A config the kit never stamped (sent before it was attached) counts as current.\n    const stamp = config[STAMP] === undefined ? engine.token() : config[STAMP];\n    const replay = (token: string) => {\n      authorize(config, token);\n      return instance.request(config);\n    };\n    for (;;) {\n      const now = engine.token();\n      // 2. The session it was sent for is gone, and whatever ended it has already done\n      // what follows (ka 3, KS 3, KS 4).\n      if (stamp !== now) {\n        if (now === null || config[RESTAMPED]) throw error;\n        config[RESTAMPED] = true;\n        return replay(now);\n      }\n      // 3. A demo has nothing to refresh: its token lives as long as its account\n      // (landing-demo §5.5).\n      if (engine.isDemo()) {\n        engine.end(now, true);\n        throw error;\n      }\n      // 4. A replay for an older token doesn't count here: the app's current token may\n      // simply have expired too, which needs a refresh, not a sign-out.\n      if (config[REFRESHED]) {\n        engine.end(now, false);\n        throw error;\n      }\n      // 5. The flight.\n      const flight = await engine.join();\n      if (flight.result === \"changed\") continue;\n      if (flight.result === \"ended\") {\n        engine.end(flight.token, false);\n        throw error;\n      }\n      if (flight.result === \"transient\") {\n        (error as Record<symbol, unknown>)[TRANSIENT] = true;\n        throw error;\n      }\n      if (flight.renewal.replay === false) throw error;\n      config[REFRESHED] = true;\n      return replay(flight.renewal.token);\n    }\n  };\n\n  const request = instance.interceptors.request.use(\n    (config) => {\n      (config as C & Marked)[STAMP] = engine.token();\n      return config;\n    },\n    (error) => Promise.reject(error),\n  );\n  const response = instance.interceptors.response.use(\n    (res) => res,\n    (error) => {\n      const failed = error as { config?: C & Marked; response?: { status?: unknown } } | null;\n      if (failed?.response?.status !== 401 || !failed.config) return Promise.reject(error);\n      return onUnauthorized(failed, failed.config);\n    },\n  );\n  return () => {\n    instance.interceptors.request.eject(request);\n    instance.interceptors.response.eject(response);\n  };\n}\n"],"mappings":";AAsCA,SAAS,oBAAoB;AAgG7B,MAAM,mBAAmB;AAAA,EACvB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAaO,SAAS,gBAAgB,KAAsB;AACpD,QAAM,OAAO,IAAI,QAAQ,YAAY,EAAE,EAAE,QAAQ,mCAAmC,EAAE;AACtF,QAAM,WAAW,KAAK,MAAM,GAAG;AAC/B,QAAM,KAAK,SAAS,QAAQ,MAAM;AAClC,MAAI,KAAK,EAAG,QAAO;AACnB,QAAM,OAAO,SAAS,MAAM,KAAK,CAAC,EAAE,KAAK,GAAG;AAC5C,SAAO,iBAAiB,KAAK,CAAC,UAAU,SAAS,SAAS,KAAK,WAAW,GAAG,KAAK,GAAG,CAAC;AACxF;AAOA,MAAM,YAAY,uBAAO,IAAI,yCAAyC;AAc/D,SAAS,0BAA0B,OAAyB;AACjE,SAAO,OAAO,UAAU,YAAY,UAAU,QAAS,MAAkC,SAAS,MAAM;AAC1G;AAwBA,MAAM,UAAU,oBAAI,QAAgD;AAGpE,MAAM,YAAY,uBAAO,WAAW;AAEpC,SAAS,YAAqB;AAC5B,SAAO,OAAO,cAAc,eAAe,UAAU,WAAW;AAClE;AAIA,SAAS,SAAS,OAAsD;AACtE,MAAI,UAAU,UAAW,QAAO;AAChC,MAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,QAAM,SAAS,aAAa,KAAK;AACjC,MAAI,WAAW,QAAW;AAGxB,WAAQ,MAAqC,iBAAiB,OAAO,UAAU;AAAA,EACjF;AACA,MAAI,WAAW,OAAO,WAAW,IAAK,QAAO;AAC7C,MAAI,WAAW,OAAO,WAAW,OAAO,UAAU,IAAK,QAAO;AAC9D,SAAO;AACT;AAEA,MAAM,QAAQ,CAAC,OAAe,IAAI,QAAc,CAAC,YAAY,WAAW,SAAS,EAAE,CAAC;AAM7E,SAAS,qBAA+C,SAAsD;AACnH,QAAM,EAAE,WAAW,GAAG,YAAY,CAAC,KAAM,GAAI,GAAG,YAAY,KAAO,IAAI;AAGvE,QAAM,QAAQ,MAAM,QAAQ,aAAa,KAAK;AAI9C,QAAM,UAAU,YAAiC;AAC/C,UAAM,aAAa,IAAI,gBAAgB;AACvC,QAAI;AACJ,UAAM,UAAU,IAAI,QAAe,CAAC,GAAG,WAAW;AAChD,cAAQ,WAAW,MAAM;AACvB,eAAO,SAAS;AAChB,mBAAW,MAAM;AAAA,MACnB,GAAG,SAAS;AAAA,IACd,CAAC;AACD,QAAI;AAGF,YAAM,UAAU,MAAM,QAAQ,KAAK,CAAC,QAAQ,QAAQ,EAAE,KAAK,MAAM,QAAQ,QAAQ,WAAW,MAAM,CAAC,GAAG,OAAO,CAAC;AAC9G,aAAO,UAAU,EAAE,QAAQ,IAAI;AAAA,IACjC,SAAS,OAAO;AACd,aAAO,SAAS,KAAK;AAAA,IACvB,UAAE;AACA,mBAAa,KAAK;AAAA,IACpB;AAAA,EACF;AAEA,QAAM,MAAM,YAAgC;AAE1C,UAAM,QAAQ,MAAM;AACpB,UAAM,UAAU,MAAM,MAAM,MAAM;AAClC,QAAI,UAAU,MAAM,QAAQ;AAC5B,aAAS,OAAO,GAAG,YAAY,SAAS,QAAQ,GAAG;AAGjD,UAAI,QAAQ,YAAY,UAAU,KAAK,QAAQ,EAAG;AAClD,YAAM,MAAM,UAAU,OAAO,CAAC,KAAK,UAAU,UAAU,SAAS,CAAC,KAAK,CAAC;AACvE,UAAI,UAAU,KAAK,QAAQ,EAAG;AAC9B,gBAAU,MAAM,QAAQ;AAAA,IAC1B;AAGA,QAAI,QAAQ,EAAG,QAAO,EAAE,QAAQ,UAAU;AAC1C,QAAI,YAAY,aAAc,QAAO,EAAE,QAAQ,SAAS,OAAO,MAAM;AACrE,QAAI,YAAY,WAAW,YAAY,YAAa,QAAO,EAAE,QAAQ,YAAY;AACjF,YAAQ,MAAM,QAAQ,OAAO;AAC7B,WAAO,EAAE,QAAQ,WAAW,SAAS,QAAQ,QAAQ;AAAA,EACvD;AAEA,MAAI,SAAoC;AACxC,QAAM,OAAO,MAAM;AAGjB,eAAW,IAAI,EAAE,QAAQ,MAAM;AAC7B,eAAS;AAAA,IACX,CAAC;AACD,WAAO;AAAA,EACT;AAGA,MAAI;AAEJ,QAAM,UAA6B;AAAA,IACjC,MAAM,UAAU;AACd,YAAM,UAAU,MAAM,KAAK;AAC3B,aAAO,QAAQ,WAAW,UAAU,EAAE,QAAQ,QAAQ,IAAI;AAAA,IAC5D;AAAA,EACF;AACA,UAAQ,IAAI,SAAS;AAAA,IACnB;AAAA,IACA,QAAQ,MAAM,QAAQ,OAAO;AAAA,IAC7B,iBAAiB,QAAQ,mBAAmB;AAAA,IAC5C;AAAA,IACA,IAAI,YAAY,MAAM;AACpB,UAAI,SAAS,MAAM,UAAU,WAAY;AACzC,cAAQ,EAAE,OAAO,WAAW;AAC5B,cAAQ,QAAQ,EAAE,KAAK,CAAC;AAAA,IAC1B;AAAA,EACF,CAAC;AACD,SAAO;AACT;AAwBA,MAAM,QAAQ;AACd,MAAM,YAAY;AAClB,MAAM,YAAY;AAalB,SAAS,UAAU,QAAmC,OAAqB;AACzE,QAAM,QAAQ,UAAU,KAAK;AAC7B,QAAM,UAAU,OAAO;AACvB,MAAI,OAAO,YAAY,YAAY,YAAY,MAAM;AACnD,WAAO,UAAU,EAAE,eAAe,MAAM;AAAA,EAC1C,WAAW,OAAQ,QAA8B,QAAQ,YAAY;AACnE,IAAC,QAA0D,IAAI,iBAAiB,KAAK;AAAA,EACvF,OAAO;AACL,IAAC,QAAoC,gBAAgB;AAAA,EACvD;AACF;AA0BO,SAAS,qBACd,UACA,SACY;AACZ,QAAM,SAAS,QAAQ,IAAI,OAAO;AAClC,MAAI,CAAC,OAAQ,OAAM,IAAI,UAAU,kEAAkE;AAEnG,QAAM,iBAAiB,OAAO,OAAe,WAAyC;AACpF,QAAI,OAAO,gBAAgB,OAAO,OAAO,EAAE,EAAG,OAAM;AAEpD,UAAM,QAAQ,OAAO,KAAK,MAAM,SAAY,OAAO,MAAM,IAAI,OAAO,KAAK;AACzE,UAAM,SAAS,CAAC,UAAkB;AAChC,gBAAU,QAAQ,KAAK;AACvB,aAAO,SAAS,QAAQ,MAAM;AAAA,IAChC;AACA,eAAS;AACP,YAAM,MAAM,OAAO,MAAM;AAGzB,UAAI,UAAU,KAAK;AACjB,YAAI,QAAQ,QAAQ,OAAO,SAAS,EAAG,OAAM;AAC7C,eAAO,SAAS,IAAI;AACpB,eAAO,OAAO,GAAG;AAAA,MACnB;AAGA,UAAI,OAAO,OAAO,GAAG;AACnB,eAAO,IAAI,KAAK,IAAI;AACpB,cAAM;AAAA,MACR;AAGA,UAAI,OAAO,SAAS,GAAG;AACrB,eAAO,IAAI,KAAK,KAAK;AACrB,cAAM;AAAA,MACR;AAEA,YAAM,SAAS,MAAM,OAAO,KAAK;AACjC,UAAI,OAAO,WAAW,UAAW;AACjC,UAAI,OAAO,WAAW,SAAS;AAC7B,eAAO,IAAI,OAAO,OAAO,KAAK;AAC9B,cAAM;AAAA,MACR;AACA,UAAI,OAAO,WAAW,aAAa;AACjC,QAAC,MAAkC,SAAS,IAAI;AAChD,cAAM;AAAA,MACR;AACA,UAAI,OAAO,QAAQ,WAAW,MAAO,OAAM;AAC3C,aAAO,SAAS,IAAI;AACpB,aAAO,OAAO,OAAO,QAAQ,KAAK;AAAA,IACpC;AAAA,EACF;AAEA,QAAM,UAAU,SAAS,aAAa,QAAQ;AAAA,IAC5C,CAAC,WAAW;AACV,MAAC,OAAsB,KAAK,IAAI,OAAO,MAAM;AAC7C,aAAO;AAAA,IACT;AAAA,IACA,CAAC,UAAU,QAAQ,OAAO,KAAK;AAAA,EACjC;AACA,QAAM,WAAW,SAAS,aAAa,SAAS;AAAA,IAC9C,CAAC,QAAQ;AAAA,IACT,CAAC,UAAU;AACT,YAAM,SAAS;AACf,UAAI,QAAQ,UAAU,WAAW,OAAO,CAAC,OAAO,OAAQ,QAAO,QAAQ,OAAO,KAAK;AACnF,aAAO,eAAe,QAAQ,OAAO,MAAM;AAAA,IAC7C;AAAA,EACF;AACA,SAAO,MAAM;AACX,aAAS,aAAa,QAAQ,MAAM,OAAO;AAC3C,aAAS,aAAa,SAAS,MAAM,QAAQ;AAAA,EAC/C;AACF;","names":[]}
+{"version":3,"sources":["../../src/lib/session-refresh.ts"],"sourcesContent":["/**\n * Renewing a session when the access token runs out: the client half of\n * docs/auth-harmonization.md §11 (round 0.34 C7, KS U6), lifted from keksdose's\n * `refreshOnce` (Kurvenschmiede's is the same, line for line) and corrected where the\n * three apps' reviews found it wrong. It ends kastlan's sign-out over a network blip (B3).\n *\n * THE KIT OWNS THE RULE, THE APP OWNS THE CALL (§11.2, decision 1). The kit decides when\n * to refresh, who waits, what a failure means, when the session is over and whether a\n * renewal may still be stored. The app keeps its endpoint, its token storage, its\n * sign-out and where it navigates, and hands them in as {@link SessionRefreshOptions}.\n *\n *  - **One flight per tab** (decision 2): every 401 that arrives while a refresh runs\n *    waits for it, and so does `session.refresh()` (kastlan's boot).\n *  - **Definitive** (decision 3): the device holds no refresh token (`refresh` resolves\n *    `null`), the refresh answers 401 or 403, or the request replayed with the fresh\n *    token gets a 401 again. Only then does the app sign out (`onEnded`), and only while\n *    that session is still the app's.\n *  - **Transient** (decision 4): everything else. The session stays: nothing is signed\n *    out, stored or redirected, and the kit shows nothing. The request rejects with its\n *    OWN 401, marked ({@link isTransientRefreshFailure}), so the app's message can say\n *    \"can't reach the server\" instead of \"not signed in\".\n *  - **Retries only where waiting helps** (decision 5, KS 7): no answer, the kit's own\n *    timeout, 408, 429 and 5xx get up to three attempts, 1 s and then 3 s apart, each cut\n *    off after 15 s; none while the browser reports itself offline. Any other answer, and\n *    anything that is not an HTTP error, ends the flight at the first attempt.\n *  - **A stale session is never written back** (§11.7, ka 3, KS 3, KS 4): every request\n *    is stamped with `currentToken()` when it goes out, and every flight notes it when it\n *    starts. A 401 to a request sent with an older token replays it with the app's token\n *    now, without a refresh; a flight whose session changed while it ran stores nothing\n *    and ends nothing. The access token is the session's identity because every change\n *    the apps make replaces it — a refresh, another tab, a company switch, a password\n *    change, a sign-in, a demo start, a sign-out.\n *\n * Framework-free like `server-wake.ts`: {@link attachSessionRefresh} takes the app's\n * axios instance as an ARGUMENT, typed structurally, so the kit never imports axios.\n *\n * Since 0.55, {@link watchSessionElsewhere} beside it: the session ending in ANOTHER tab,\n * or while this page sat in the back/forward cache (kastlan reuse audit 2026-11-02,\n * proposal 6).\n */\n\nimport type { AxiosLikeInstance, ServerWakeAxiosConfig } from \"./server-wake\";\nimport { httpStatusOf } from \"./http-status\";\n\n/** What the app's `refresh` resolves: the new access token, plus whatever its `store`\n *  needs (its refresh token, the user). */\nexport interface SessionRenewal {\n  /** The new access token; the waiting requests are replayed with it. */\n  token: string;\n  /**\n   * `false`: store the renewal, but replay nothing — each waiting request rejects with\n   * its 401, unmarked. kastlan's refresh can land in another company (§11.5, ka 3): a\n   * waiting write, such as the handover's `POST /sync`, must not be replayed into it.\n   */\n  replay?: false;\n}\n\n/** What the app hands {@link createSessionRefresh} (§11.4). */\nexport interface SessionRefreshOptions<R extends SessionRenewal> {\n  /**\n   * The app's own `POST /auth/refresh`, on a BARE client — never the instance the kit is\n   * attached to, so the refresh cannot re-enter the interceptor. It **writes nothing**:\n   * the kit hands the answer to `store`, and only while the session is unchanged.\n   *\n   * Resolves the answer as a renewal, or `null` when the device holds no refresh token.\n   * Throws on failure, and the kit classifies the throw: a 401 or 403 is definitive; no\n   * answer (an axios error without a `response`), the kit's own timeout, 408, 429 and\n   * 5xx are transient and retried; any other answer, and anything that is not an HTTP\n   * error (a bug in this function), is transient and not retried. The status is read\n   * from `err.response.status` (axios), `err.status` or `err.statusCode`.\n   *\n   * `signal` aborts when the attempt runs past `timeoutMs`; pass it to the request.\n   */\n  refresh: (signal: AbortSignal) => Promise<R | null>;\n  /** Writes the renewal: the tokens and the user (a missing refresh token keeps the\n   *  stored one). Called only while the session the flight renews is still the app's,\n   *  and before the waiting requests are replayed — so it writes the token SYNCHRONOUSLY\n   *  where `currentToken` reads it: the replay goes through the app's own request\n   *  interceptor again, and is stamped then. A throw is the app's bug: the waiting\n   *  requests and `session.refresh()` reject with it. */\n  store: (renewal: R) => void;\n  /** The access token the app sends NOW, read where its request interceptor reads it;\n   *  `null` when there is none. */\n  currentToken: () => string | null;\n  /** Whether the session is a demo: a demo's 401 ends it, with no refresh tried\n   *  (landing-demo §5.5). */\n  isDemo: () => boolean;\n  /**\n   * The session is over: drop the tokens and the user, then navigate — `/demo/ended` for\n   * a demo, else the sign-in with the page it came from (auth §5.2). Called once per\n   * session, however many requests found out (KS 8), and never by `session.refresh()`.\n   */\n  onEnded: (ended: { demo: boolean }) => void;\n  /** Whether a URL is a signed-out step, whose 401 judges the form and never the\n   *  session. Replaces the default list, {@link isSignedOutStep}. */\n  isSignedOutStep?: (url: string) => boolean;\n  /** Attempts for a refresh that got no answer, timed out, or got a 408, 429 or 5xx.\n   *  Default 3. */\n  attempts?: number;\n  /** The waits before the second and later attempts; the last one repeats. Default\n   *  `[1000, 3000]`. */\n  backoffMs?: readonly number[];\n  /** Each attempt is cut off after this, and its `signal` aborted. Default 15 000. */\n  timeoutMs?: number;\n}\n\n/** What `session.refresh()` resolves (§11.4), by `result`:\n *\n * | `result` | When | What the kit has done |\n * |---|---|---|\n * | `\"renewed\"` | a renewal while the session was unchanged | `store(renewal)` |\n * | `\"ended\"` | definitive | nothing; `onEnded` only for requests that waited on the same flight |\n * | `\"transient\"` | transient | nothing |\n * | `\"changed\"` | the session changed while it ran | nothing; read the app's own state |\n */\nexport type SessionRefreshOutcome<R extends SessionRenewal = SessionRenewal> =\n  { result: \"renewed\"; renewal: R } | { result: \"ended\" } | { result: \"transient\" } | { result: \"changed\" };\n\n/** The flight {@link createSessionRefresh} makes; {@link attachSessionRefresh} hooks it\n *  to an axios instance. */\nexport interface SessionRefresh<R extends SessionRenewal = SessionRenewal> {\n  /**\n   * The same flight, for a caller outside the interceptor — kastlan's boot. Joins a\n   * running flight, or starts one. Never calls `onEnded`: the caller decides what an\n   * `\"ended\"` means for it.\n   */\n  refresh(): Promise<SessionRefreshOutcome<R>>;\n}\n\n// ── The signed-out steps ──────────────────────────────────────────────────────\n\n/**\n * Every `/auth/` call made without a session, the union of the three apps' lists\n * (§11.3): signing in (with its `2fa` and `set-password` steps, and a passkey's), up,\n * into a demo, a password reset, the verification link, the invitation check, the email\n * change's confirmation link, and the refresh itself. NOT `resend-verification` (KS 1):\n * in keksdose and Kurvenschmiede it needs a session; in kastlan it never answers 401.\n */\nconst SIGNED_OUT_STEPS = [\n  \"login\",\n  \"passkey/login\",\n  \"register\",\n  \"demo-session\",\n  \"password-reset\",\n  \"verify-email\",\n  \"invitations/check\",\n  \"me/email/confirm\",\n  \"refresh\",\n] as const;\n\n/**\n * Whether a request's URL is a signed-out step — the kit's default list (§11.3), exported\n * for an app's tests and for an app's own `isSignedOutStep` that adds to it.\n *\n * **Whole steps only** (KS 2): the part of the path after its `auth/` segment, without\n * the query string, is the entry itself or starts with the entry and a `/`. So\n * `login/2fa` is `login`'s, but `register` never catches `/auth/passkey/register/begin`\n * (adding a passkey, which needs a session), `invitations/check` never\n * `/auth/invitations/accept`, and `me/email/confirm` never `/auth/me/email`. Relative and\n * absolute URLs alike; a URL with no `auth` segment is no step.\n */\nexport function isSignedOutStep(url: string): boolean {\n  const path = url.replace(/[?#].*$/s, \"\").replace(/^([a-z][a-z\\d+.-]*:)?\\/\\/[^/]*/i, \"\");\n  const segments = path.split(\"/\");\n  const at = segments.indexOf(\"auth\");\n  if (at < 0) return false;\n  const step = segments.slice(at + 1).join(\"/\");\n  return SIGNED_OUT_STEPS.some((entry) => step === entry || step.startsWith(`${entry}/`));\n}\n\n// ── The marker ────────────────────────────────────────────────────────────────\n\n/** On the request's own axios error, after a transient failure (decision 8). A\n *  `Symbol.for` key: shared by every copy of the kit in a page, and left out of\n *  `JSON.stringify`, so a log that serialises the error doesn't print it (kk 2). */\nconst TRANSIENT = Symbol.for(\"@eifi1/ui-kit:session-refresh.transient\");\n\n/**\n * Whether a request was refused because the refresh behind it failed TRANSIENTLY —\n * offline, a timeout, a 5xx — and not because the session is over (decision 8). The\n * error is the request's own 401, `err.response?.status` and every check an app already\n * has keep working; this reads the mark the kit put on it, so the app's message can say\n * \"can't reach the server\" instead of \"not signed in\". Read it FIRST: keksdose's sync\n * chip, kastlan's handover sync and Kurvenschmiede's `apiErrorMessage` count it as\n * offline (§11.5).\n *\n * Not the refresh's own error: its config carries the refresh token in its body, into any\n * log or crash report that keeps the error.\n */\nexport function isTransientRefreshFailure(error: unknown): boolean {\n  return typeof error === \"object\" && error !== null && (error as Record<symbol, unknown>)[TRANSIENT] === true;\n}\n\n// ── The flight ────────────────────────────────────────────────────────────────\n\n/** A flight's result, as the interceptor needs it: `\"ended\"` keeps the session it ended. */\ntype Flight<R extends SessionRenewal> =\n  | { result: \"renewed\"; renewal: R }\n  | { result: \"ended\"; token: string | null }\n  | { result: \"transient\" }\n  | { result: \"changed\" };\n\n/** What one attempt came to. */\ntype Attempt<R> = { renewal: R } | \"definitive\" | \"retry\" | \"transient\";\n\n/** What {@link attachSessionRefresh} needs of a session. Kept off the public interface:\n *  only what {@link createSessionRefresh} made can be attached. */\ninterface Engine {\n  token(): string | null;\n  isDemo(): boolean;\n  isSignedOutStep(url: string): boolean;\n  join(): Promise<Flight<SessionRenewal>>;\n  end(token: string | null, demo: boolean): void;\n}\n\nconst engines = new WeakMap<SessionRefresh<SessionRenewal>, Engine>();\n\n/** The kit's own timeout, told apart from anything the app's `refresh` throws. */\nconst TIMED_OUT = Symbol(\"timed out\");\n\nfunction isOffline(): boolean {\n  return typeof navigator !== \"undefined\" && navigator.onLine === false;\n}\n\n/** A refresh's throw, classified (§11.4). The status is read where `isRateLimited` reads\n *  it — `httpStatusOf`, one probe for axios, ofetch and Node errors (DUP-11). */\nfunction classify(error: unknown): \"definitive\" | \"retry\" | \"transient\" {\n  if (error === TIMED_OUT) return \"retry\";\n  if (typeof error !== \"object\" || error === null) return \"transient\";\n  const status = httpStatusOf(error);\n  if (status === undefined) {\n    // No answer: axios marks its own errors, and one without a response never reached a\n    // server (offline, DNS, CORS, its own timeout). Anything else is a bug in `refresh`.\n    return (error as { isAxiosError?: unknown }).isAxiosError === true ? \"retry\" : \"transient\";\n  }\n  if (status === 401 || status === 403) return \"definitive\";\n  if (status === 408 || status === 429 || status >= 500) return \"retry\";\n  return \"transient\";\n}\n\nconst sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));\n\n/**\n * Make the flight: `const session = createSessionRefresh({ refresh, store, currentToken,\n * isDemo, onEnded })`, then {@link attachSessionRefresh}`(api, session)`. One per tab.\n */\nexport function createSessionRefresh<R extends SessionRenewal>(options: SessionRefreshOptions<R>): SessionRefresh<R> {\n  const { attempts = 3, backoffMs = [1000, 3000], timeoutMs = 15_000 } = options;\n  // An empty string is no token: the stamp and the flight compare tokens, and \"\" against\n  // `null` must not read as a change of session.\n  const token = () => options.currentToken() || null;\n\n  /** One call of the app's `refresh`, cut off after `timeoutMs` even if it ignores the\n   *  signal. */\n  const attempt = async (): Promise<Attempt<R>> => {\n    const controller = new AbortController();\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    const timeout = new Promise<never>((_, reject) => {\n      timer = setTimeout(() => {\n        reject(TIMED_OUT);\n        controller.abort();\n      }, timeoutMs);\n    });\n    try {\n      // Through `then`, so a `refresh` that throws before it returns a promise is\n      // classified like one that rejects.\n      const renewal = await Promise.race([Promise.resolve().then(() => options.refresh(controller.signal)), timeout]);\n      return renewal ? { renewal } : \"definitive\";\n    } catch (error) {\n      return classify(error);\n    } finally {\n      clearTimeout(timer);\n    }\n  };\n\n  const run = async (): Promise<Flight<R>> => {\n    // The session this flight renews (§11.3 step 5).\n    const noted = token();\n    const changed = () => token() !== noted;\n    let outcome = await attempt();\n    for (let made = 1; outcome === \"retry\"; made += 1) {\n      // No further attempt while the browser says it is offline, nor for a session that\n      // is no longer the app's: whatever the answer, it would be \"changed\".\n      if (made >= attempts || isOffline() || changed()) break;\n      await sleep(backoffMs[made - 1] ?? backoffMs[backoffMs.length - 1] ?? 0);\n      if (isOffline() || changed()) break;\n      outcome = await attempt();\n    }\n    // A late answer never writes the old session back over a sign-out, a demo start or a\n    // password change, and the old session's refusal never signs anyone out (KS 3).\n    if (changed()) return { result: \"changed\" };\n    if (outcome === \"definitive\") return { result: \"ended\", token: noted };\n    if (outcome === \"retry\" || outcome === \"transient\") return { result: \"transient\" };\n    options.store(outcome.renewal);\n    return { result: \"renewed\", renewal: outcome.renewal };\n  };\n\n  let flight: Promise<Flight<R>> | null = null;\n  const join = () => {\n    // Cleared before any waiter resumes (`finally` settles first), so a waiter that\n    // needs another flight starts a new one.\n    flight ??= run().finally(() => {\n      flight = null;\n    });\n    return flight;\n  };\n\n  /** The session `onEnded` was last called for: once per session (KS 8). */\n  let ended: { token: string | null } | undefined;\n\n  const session: SessionRefresh<R> = {\n    async refresh() {\n      const outcome = await join();\n      return outcome.result === \"ended\" ? { result: \"ended\" } : outcome;\n    },\n  };\n  engines.set(session, {\n    token,\n    isDemo: () => options.isDemo(),\n    isSignedOutStep: options.isSignedOutStep ?? isSignedOutStep,\n    join,\n    end(endedToken, demo) {\n      if (ended && ended.token === endedToken) return;\n      ended = { token: endedToken };\n      options.onEnded({ demo });\n    },\n  });\n  return session;\n}\n\n// ── axios ─────────────────────────────────────────────────────────────────────\n\n/** The config fields the kit reads and writes — what axios's request config has. */\ninterface SessionRefreshAxiosConfig extends ServerWakeAxiosConfig {\n  /** axios's `AxiosHeaders` (written through its `set`), or a plain record. */\n  headers?: unknown;\n}\n\n/** An axios instance, structurally: {@link AxiosLikeInstance}, plus `request(config)` for\n *  the replay. `axios.create()`'s result fits it as is. `NoInfer`, because axios's\n *  `request` takes the WIDER `AxiosRequestConfig`: inferred from there, the config type\n *  no longer fits the interceptors, which hand out `InternalAxiosRequestConfig`. */\ninterface SessionRefreshInstance<\n  C extends SessionRefreshAxiosConfig,\n  R extends { config: C },\n> extends AxiosLikeInstance<C, R> {\n  request(config: NoInfer<C>): Promise<unknown>;\n}\n\n/** The keys the kit keeps on a request's config, as `attachServerWake` keeps\n *  `_serverWake`: never a header. Plain string keys holding primitives, because axios\n *  copies the config on a replay (`mergeConfig`) and a symbol key would be dropped. */\nconst STAMP = \"_sessionStamp\";\nconst REFRESHED = \"_sessionRefreshed\";\nconst RESTAMPED = \"_sessionRestamped\";\ntype Marked = {\n  /** `currentToken()` when the request went out. */\n  [STAMP]?: string | null;\n  /** Replayed after a refresh: a 401 now is definitive (decision 3). */\n  [REFRESHED]?: boolean;\n  /** Replayed because it was sent with an older token: once for this reason. */\n  [RESTAMPED]?: boolean;\n};\n\n/** `Authorization: Bearer <token>` on a config about to be replayed. The app's own\n *  request interceptor runs again on the replay and writes the same, from the same\n *  source. */\nfunction authorize(config: SessionRefreshAxiosConfig, token: string): void {\n  const value = `Bearer ${token}`;\n  const headers = config.headers;\n  if (typeof headers !== \"object\" || headers === null) {\n    config.headers = { Authorization: value };\n  } else if (typeof (headers as { set?: unknown }).set === \"function\") {\n    (headers as { set(name: string, value: string): unknown }).set(\"Authorization\", value);\n  } else {\n    (headers as Record<string, unknown>).Authorization = value;\n  }\n}\n\n/**\n * Hook a session to an axios instance: `attachSessionRefresh(api, session)`. Adds a\n * request interceptor (the stamp) and a response interceptor (the 401), and returns a\n * function that ejects both.\n *\n * Attach it LAST (§11.3, kk 4): after `attachServerWake`, which asks to be first, and\n * after the app's own response interceptors (logging, a watchdog of its own). axios runs\n * response interceptors in the order they were added, and each of those must see the 401\n * settle before the refresh is awaited. The request side's order does not matter.\n *\n * On a 401, in this order (§11.3):\n *\n *  1. a signed-out step → reject, nothing else;\n *  2. sent with an older token → replayed with the app's token now, with no refresh, once\n *     for this reason; with no token now, reject;\n *  3. a demo → `onEnded({ demo: true })`, reject;\n *  4. already replayed after a refresh → definitive: `onEnded({ demo: false })`, reject;\n *  5. otherwise it joins the flight, or starts it. A renewal replays it once with the\n *     renewal's token (`replay: false`: rejects, unmarked); definitive ends the session;\n *     transient rejects, marked; a session that changed meanwhile sends it through step\n *     2 again.\n *\n * Every rejection is the request's OWN error. Any other status passes through untouched.\n */\nexport function attachSessionRefresh<C extends SessionRefreshAxiosConfig, R extends { config: C }>(\n  instance: SessionRefreshInstance<C, R>,\n  session: SessionRefresh<SessionRenewal>,\n): () => void {\n  const engine = engines.get(session);\n  if (!engine) throw new TypeError(\"attachSessionRefresh takes the session createSessionRefresh made\");\n\n  const onUnauthorized = async (error: object, config: C & Marked): Promise<unknown> => {\n    if (engine.isSignedOutStep(config.url ?? \"\")) throw error;\n    // A config the kit never stamped (sent before it was attached) counts as current.\n    const stamp = config[STAMP] === undefined ? engine.token() : config[STAMP];\n    const replay = (token: string) => {\n      authorize(config, token);\n      return instance.request(config);\n    };\n    for (;;) {\n      const now = engine.token();\n      // 2. The session it was sent for is gone, and whatever ended it has already done\n      // what follows (ka 3, KS 3, KS 4).\n      if (stamp !== now) {\n        if (now === null || config[RESTAMPED]) throw error;\n        config[RESTAMPED] = true;\n        return replay(now);\n      }\n      // 3. A demo has nothing to refresh: its token lives as long as its account\n      // (landing-demo §5.5).\n      if (engine.isDemo()) {\n        engine.end(now, true);\n        throw error;\n      }\n      // 4. A replay for an older token doesn't count here: the app's current token may\n      // simply have expired too, which needs a refresh, not a sign-out.\n      if (config[REFRESHED]) {\n        engine.end(now, false);\n        throw error;\n      }\n      // 5. The flight.\n      const flight = await engine.join();\n      if (flight.result === \"changed\") continue;\n      if (flight.result === \"ended\") {\n        engine.end(flight.token, false);\n        throw error;\n      }\n      if (flight.result === \"transient\") {\n        (error as Record<symbol, unknown>)[TRANSIENT] = true;\n        throw error;\n      }\n      if (flight.renewal.replay === false) throw error;\n      config[REFRESHED] = true;\n      return replay(flight.renewal.token);\n    }\n  };\n\n  const request = instance.interceptors.request.use(\n    (config) => {\n      (config as C & Marked)[STAMP] = engine.token();\n      return config;\n    },\n    (error) => Promise.reject(error),\n  );\n  const response = instance.interceptors.response.use(\n    (res) => res,\n    (error) => {\n      const failed = error as { config?: C & Marked; response?: { status?: unknown } } | null;\n      if (failed?.response?.status !== 401 || !failed.config) return Promise.reject(error);\n      return onUnauthorized(failed, failed.config);\n    },\n  );\n  return () => {\n    instance.interceptors.request.eject(request);\n    instance.interceptors.response.eject(response);\n  };\n}\n\n// ── Another tab ───────────────────────────────────────────────────────────────\n\n/** What the app hands {@link watchSessionElsewhere}. */\nexport interface SessionElsewhereOptions {\n  /**\n   * Whether this tab's session is over: this tab holds one, and the storage every tab\n   * shares no longer does — its token removed by a sign-out elsewhere, the storage\n   * cleared — or holds another account's. Read where the app's request interceptor reads\n   * the token (`readStored`), against what this tab keeps in memory. A renewal elsewhere\n   * rewrites the token and is no end; a tab with no session has nothing to end.\n   */\n  ended: () => boolean;\n  /**\n   * The session is over in this tab: drop what this tab holds of it (the user, the query\n   * cache, the unlocked keys), then leave with a full load, of the sign-in or the demo's\n   * end. Not the app's whole sign-out: the other tab has already removed what the device\n   * kept, and may since have stored a session that is not this tab's to delete.\n   *\n   * Called once per session: further `storage` events while `ended` still reads `true`\n   * call nothing, until it has read `false` again. A restored page is asked afresh.\n   */\n  onEnded: () => void;\n  /** Also check a page the browser brings back from its back/forward cache (`pageshow`\n   *  with `persisted`). Default `true`. */\n  checkRestored?: boolean;\n}\n\n/**\n * Watch for this tab's session ending in another tab (kastlan reuse audit 2026-11-02,\n * proposal 6): `const stop = watchSessionElsewhere({ ended, onEnded })`, once per tab,\n * beside the app's session store. Returns the function that stops watching.\n *\n * The session belongs to the device — its tokens sit in localStorage, which every tab\n * shares — and the account on screen to the tab: the user, the query cache and the\n * unlocked keys sit in this tab's memory. A sign-out in another tab changed the first and\n * left the second, so this tab kept the previous account on screen and wrote its data\n * back into the offline copy the other tab had just wiped (refactor audit 2026-10-30:\n * keksdose FS-2, kastlan FLW-1). Two moments tell it:\n *\n *  - a `storage` event: another tab wrote or removed a key. `ended` is read after every\n *    one, whatever its key — it reads the state, so it needs no list of keys, and a\n *    cleared storage (`key` null) counts like any removal;\n *  - a page restored from the back/forward cache (`pageshow` with `persisted`). Frozen\n *    there, it heard no `storage` event and came back on the previous account, where it\n *    could renew the old session and store its tokens again over the sign-out (keksdose\n *    F-31; kastlan listened to `storage` alone). A fresh load reads the storage anyway,\n *    so nothing is checked when the watch starts, nor on a `pageshow` that is no restore.\n *\n * Framework-free and storage-free: `ended` is the app's read, guarded where it reads\n * (the kit's `readStored` never throws). Nothing is watched where there is no `window`.\n */\nexport function watchSessionElsewhere(options: SessionElsewhereOptions): () => void {\n  if (typeof window === \"undefined\") return () => undefined;\n  /** `onEnded` was called, and `ended` has not read `false` since. */\n  let told = false;\n  const check = () => {\n    if (!options.ended()) {\n      told = false;\n      return;\n    }\n    if (told) return;\n    told = true;\n    options.onEnded();\n  };\n  const onStorage = () => check();\n  const onPageShow = (event: PageTransitionEvent) => {\n    if (!event.persisted) return;\n    // A page shown again is asked again, told or not: its `onEnded` left with a full load,\n    // the browser kept the page, and Back brought it back on the previous account.\n    told = false;\n    check();\n  };\n  window.addEventListener(\"storage\", onStorage);\n  if (options.checkRestored !== false) window.addEventListener(\"pageshow\", onPageShow);\n  return () => {\n    window.removeEventListener(\"storage\", onStorage);\n    window.removeEventListener(\"pageshow\", onPageShow);\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/lib/translation-review.d.ts

@@ -293,6 +293,32 @@ export declare function reviewUndo(rows: readonly TranslationRow[]): Translation
 export declare function mergeReviews<T extends TranslationReviewKey>(prev: readonly T[], written: readonly T[]): T[];
 /** The cached list without the verdicts on `cleared`. */
 export declare function dropReviews<T extends TranslationReviewKey>(prev: readonly T[], cleared: readonly TranslationReviewKey[]): T[];
+/**
+ * A save of any size under server-kit's cap: `writes` in chunks of 1000, one request
+ * after the other, in their order, and every verdict the server answered with, in that
+ * order — to patch the page's cached list with {@link mergeReviews} once. `save` is the
+ * app's own request (`PUT /translations/reviews`), answering with the verdicts it wrote,
+ * in either spelling. No writes, no request: the server refuses an empty batch.
+ *
+ * A chunk that fails rejects with its error, and the chunks after it are not sent. What
+ * the chunks before it wrote stays written — the server has it — but is not handed back,
+ * so the page leaves its cache as it was and the panel shows the error; a second try
+ * writes those verdicts again, which changes nothing but the time on them.
+ *
+ * All three apps wrote this loop, with a `chunks` helper and `SAVE_CHUNK = 1000` of
+ * their own (kastlan reuse audit 2026-11-02, proposal 5):
+ *
+ *     const written = await saveReviewsInChunks(writes.map(toApiWrite), (part) => translationsApi.save(part));
+ *     patchCache((reviews) => mergeReviews(reviews, written));
+ */
+export declare function saveReviewsInChunks<W extends TranslationReviewKey, R extends TranslationReviewKey>(writes: readonly W[], save: (chunk: W[]) => Promise<readonly R[]>): Promise<R[]>;
+/**
+ * {@link saveReviewsInChunks} for a reset (`POST /translations/reviews/clear`): `keys` in
+ * chunks of 1000, one request after the other, and the keys themselves once every chunk
+ * is through — to drop from the cached list with {@link dropReviews} once. A failing
+ * chunk rejects as a save's does, and what the chunks before it cleared stays cleared.
+ */
+export declare function clearReviewsInChunks<K extends TranslationReviewKey>(keys: readonly K[], clear: (chunk: K[]) => Promise<unknown>): Promise<K[]>;
 /**
  * What a phone card's swipe can be bound to in `TranslationReviewPanel`'s `swipe`
  * (keksdose — Marcel's live #377 rework, 2026-10-03: *"Add the swipe options to be shown

package/dist/lib/translation-review.js

@@ -200,6 +200,18 @@ function dropReviews(prev, cleared) {
   const gone = new Set(cleared.map((r) => `${r.locale}|${r.key}`));
   return prev.filter((r) => !gone.has(`${r.locale}|${r.key}`));
 }
+const REVIEW_CHUNK = 1e3;
+async function saveReviewsInChunks(writes, save) {
+  const written = [];
+  for (let at = 0; at < writes.length; at += REVIEW_CHUNK) {
+    written.push(...await save(writes.slice(at, at + REVIEW_CHUNK)));
+  }
+  return written;
+}
+async function clearReviewsInChunks(keys, clear) {
+  for (let at = 0; at < keys.length; at += REVIEW_CHUNK) await clear(keys.slice(at, at + REVIEW_CHUNK));
+  return [...keys];
+}
 const TRANSLATION_REVIEW_SWIPE_ACTIONS = ["approve", "edit", "clear"];
 const DEFAULT_TRANSLATION_REVIEW_SWIPE = Object.freeze({
   start: Object.freeze(["edit"]),
@@ -245,6 +257,7 @@ export {
   DEFAULT_TRANSLATION_REVIEW_SWIPE,
   REVIEW_STATUSES,
   TRANSLATION_REVIEW_SWIPE_ACTIONS,
+  clearReviewsInChunks,
   dropReviews,
   filterTranslationRows,
   flattenStrings,
@@ -260,6 +273,7 @@ export {
   reviewStatus,
   reviewUndo,
   reviewWrite,
+  saveReviewsInChunks,
   summariseRows,
   toApiWrite,
   translationCorrections,