@eifi1/ui-kit 0.54.0 → 0.55.0

package/dist/lib/focus-left.d.ts

@@ -52,9 +52,55 @@ export declare function tabStopsAround(frame: Element, limit?: number): {
 /**
  * Focus the first of `candidates` that is still in the page and takes the focus; true
  * when one did. Each is tried and checked, since `focus()` on a node that cannot hold it
- * (detached, `display: none`, disabled since) fails without a word.
+ * (detached, `display: none`, disabled since) fails without a word. An SVG element counts
+ * (a chart's tile, a slice); `<body>` and `<html>` never do — "focused" there is the
+ * focus lost, not given (0.52 code review 2026-10-31, held to 0.55).
  */
 export declare function focusFirst(candidates: Iterable<Element | null | undefined>): boolean;
+/** {@link returnFocus}'s three answers to "where was this opened from". */
+export interface FocusReturn {
+    /** The control it was opened from: the overlay's trigger when it names one, else what
+     *  held the focus as it opened. */
+    opener?: Element | null;
+    /** Where the focus goes when the opener cannot take it, nearest first — the overlay's
+     *  stated fallback. */
+    fallback?: Iterable<Element | null | undefined>;
+    /** What is closing, while it is still in the page (a panel on its way out, a list
+     *  about to unmount): a focus inside it is one to give back. */
+    closing?: Element | null;
+}
+/**
+ * Where the focus goes when an overlay closes, or a control holding it leaves the page —
+ * the kit's ONE rule for it (0.52 code review 2026-10-31, held to 0.55). The dialogs, the
+ * popovers and menus, the drawers, the phone sheets, the tour, AlertBanner's × and the
+ * Treemap's tiles each decided it themselves, and they drifted: the trap gave the focus
+ * back whenever its opener was still connected — over a focus the app had just placed —
+ * and left it on `<body>` when it was not; the date and month pickers and the floating
+ * panel moved it only when it was lost; the dropdown, the combobox and the column drawer
+ * moved it to their trigger every time, unchecked; and a Treemap tile's note of where to
+ * go once outlived the commit it was for and took the focus back, from wherever the
+ * reader was, when the map was shown again.
+ *
+ * 1. **Only a lost focus is moved** — on `<body>`, on nothing or on a removed node
+ *    ({@link focusIsLost}) — or one still inside what is `closing`. A focus that went
+ *    somewhere real is the user's (an outside press landed on a field) or the app's (its
+ *    own `focus()` in `onClose`), and stays.
+ * 2. **To the opener**, if it is still in the page and takes the focus: `focus()` is
+ *    checked, as a disabled, hidden or inert opener refuses it without a word.
+ * 3. **Else to the stated fallback**, the first of it that does — each caller names its
+ *    own: the trap the stops that stood around its opener, a banner the stops around its
+ *    ×, the map the tile that holds its tab stop.
+ * 4. **Never to `<body>`**: no `focus()` on a node that has left, none on `<body>`, no
+ *    `blur()`. When nothing can take the focus — the page under the overlay was replaced
+ *    — it is left for the page's own handling of a new page, not guessed at.
+ * 5. **Only in the closing commit**: called from the commit that closes or removes (a
+ *    handler that closes, a ref callback, a layout effect, an effect's cleanup), and
+ *    nothing handed to it is kept. A note gathered earlier, where a removed node can no
+ *    longer be measured from, is spent or dropped in that commit.
+ *
+ * True when it moved the focus.
+ */
+export declare function returnFocus({ opener, fallback, closing }: FocusReturn): boolean;
 /**
  * Focus a container that is not a tab stop of its own — a table, a list — as the place
  * the user is in, without making it one: `tabindex="-1"` for as long as it holds the

package/dist/lib/focus-left.js

@@ -42,12 +42,20 @@ function tabStopsAround(frame, limit = 5) {
 }
 function focusFirst(candidates) {
   for (const el of candidates) {
-    if (!(el instanceof HTMLElement) || !el.isConnected) continue;
+    if (!(el instanceof HTMLElement || el instanceof SVGElement) || !el.isConnected) continue;
+    if (el === el.ownerDocument.body || el === el.ownerDocument.documentElement) continue;
     el.focus();
-    if (document.activeElement === el) return true;
+    if (el.ownerDocument.activeElement === el) return true;
   }
   return false;
 }
+function returnFocus({ opener, fallback = [], closing }) {
+  if (typeof document === "undefined") return false;
+  const active = document.activeElement;
+  const inside = Boolean(closing?.isConnected && active && closing.contains(active));
+  if (!inside && !focusIsLost()) return false;
+  return focusFirst([opener, ...fallback]);
+}
 function focusContainer(el) {
   if (!el.hasAttribute("tabindex")) {
     el.setAttribute("tabindex", "-1");
@@ -60,6 +68,7 @@ export {
   focusContainer,
   focusFirst,
   focusIsLost,
+  returnFocus,
   tabStops,
   tabStopsAround,
   whenFocusLeftForNothing

package/dist/lib/focus-left.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/lib/focus-left.ts"],"sourcesContent":["// \"The focused node left\" (refactor audit 2026-10-30, Wave 1: DSP-4, DSP-15). When the\n// element holding the keyboard's focus is removed — a table row deleted, filtered out or\n// approved; a bulk bar gone with its Clear; a banner its × took away — the browser puts\n// focus on <body> and says nothing: no blur in Chromium, none in jsdom. A keyboard or\n// screen-reader user then starts again from the top of the page. The overlays give focus\n// back to their opener (use-focus-trap); these helpers are for the controls that leave\n// the page while the focus is IN them, and decide where it goes instead.\n\n/**\n * Candidate tab stops, in DOM order — narrowed by {@link isTabStop} to the ones a Tab\n * really reaches. The kit's one copy of the rule (0.52 code review, lib/focus-left.ts):\n * this file and use-focus-trap each had it, with an exported `firstTabStop` apiece that\n * disagreed about the element itself, and a combobox panel's toolbar had a third\n * selector. The trap, the focus a removed node drops (below), the tour's field ring and\n * the toolbar all read it here, so \"the next stop\" is the same stop everywhere.\n *\n * The selector is the one `Modal` used. On its own it was not enough (round 0.34\n * BUG-4): only the bare `[tabindex]` clause excluded `-1`, so a `button`, an `input` or\n * a link taken out of the tab order still counted. A panel that ends in a roving grid —\n * the calendar's days, the month grid, the picker sheet's rows, every one of them `-1`\n * but the active cell — then had a \"last\" stop no Tab ever reaches: Tab from the real\n * last stop was not wrapped and walked out of the open panel, and Shift+Tab from the\n * first landed on a cell that is not a stop at all.\n */\n// `input[type=hidden]` is no stop: a Tab never lands on it and focus() on it does nothing,\n// but its tabIndex reads 0, so a trap could take a form's hidden field for its first or last\n// stop and Shift+Tab left the dialog (0.52 code review).\nconst TAB_STOP =\n  'a[href],button:not([disabled]),textarea:not([disabled]),input:not([disabled]):not([type=\"hidden\"]),select:not([disabled]),[tabindex]:not([tabindex=\"-1\"])';\n\n/**\n * A stop the browser's own Tab would land on: in the tab order (`tabIndex` ≥ 0) and not\n * inside something `hidden` or `inert`. Removes only elements a native Tab never\n * reaches, so no correct order changes. `visibility: hidden` and closed `<details>` are\n * still not walked — they need layout, which this rule has never read.\n */\nfunction isTabStop(el: HTMLElement): boolean {\n  return el.tabIndex >= 0 && !el.closest(\"[hidden],[inert]\");\n}\n\nexport interface TabStopOptions {\n  /** Whether `el` itself counts, first, when it is a stop. Default true: the tour's\n   *  target may BE the field (refactor audit 2026-10-30, DUP-9). False for \"a control\n   *  inside it\" — a row, a drawer, a trap's container, a toolbar. */\n  includeSelf?: boolean;\n}\n\n/** The tab stops in `el`, in DOM order — `el` itself first when it is one, unless\n *  `includeSelf: false`. */\nexport function tabStops(el: Element, { includeSelf = true }: TabStopOptions = {}): HTMLElement[] {\n  const inside = Array.from(el.querySelectorAll<HTMLElement>(TAB_STOP)).filter(isTabStop);\n  const own = includeSelf && el instanceof HTMLElement && el.matches(TAB_STOP) && isTabStop(el);\n  return own ? [el, ...inside] : inside;\n}\n\n/** The first of {@link tabStops} — the control a person types into or presses — or null. */\nexport function firstTabStop(el: Element, options?: TabStopOptions): HTMLElement | null {\n  return tabStops(el, options)[0] ?? null;\n}\n\n/**\n * Whether the focus has fallen out of the page: onto `<body>`, onto nothing, or onto a\n * node no longer in the document. False on the server, where nothing has focus to lose.\n * A recovery asks this first: focus that went somewhere real (a dialog, the next field,\n * an app's own `focus()`) is the user's or the app's, and is left where it is.\n */\nexport function focusIsLost(): boolean {\n  if (typeof document === \"undefined\") return false;\n  const el = document.activeElement;\n  return !el || el === document.body || !el.isConnected;\n}\n\n/**\n * Calls `then` when a `blur`/`focusout` was the user's own move to nothing — a click on\n * the page's background, or a click Safari answers by focusing nothing (it focuses no\n * button or link on a click, and blurs what had the focus) — after which a note of where\n * the focus was is stale (0.52 code review: DataTable's row, BulkActionBar's and\n * AlertBanner's notes outlived it, and a removal much later pulled the focus, and the\n * scroll, back to them).\n *\n * No element took the focus, the document holds none, and the node that lost it could\n * still hold it. Not when it was removed, hidden, made inert or disabled: that is the page\n * taking the focus away — the very case those notes are kept for. Not a window losing the\n * focus either, which leaves the node the document's active element. Decided a microtask\n * later, once the event's own work is done: a browser that blurs a node it is removing\n * (or hiding) may do it while the node is still in place, and only after it is gone is\n * that told apart from a click.\n */\nexport function whenFocusLeftForNothing(\n  e: { target: EventTarget | null; relatedTarget: EventTarget | null },\n  then: () => void,\n): void {\n  const el = e.target;\n  if (e.relatedTarget !== null || !(el instanceof Element)) return;\n  queueMicrotask(() => {\n    if (!el.isConnected || el.matches(\":disabled\") || el.closest(\"[hidden],[inert]\")) return;\n    // `display: none`, where the browser can say (jsdom cannot).\n    if (typeof el.checkVisibility === \"function\" && !el.checkVisibility()) return;\n    if (focusIsLost()) then();\n  });\n}\n\n/**\n * The tab stops around `frame`, outside it, nearest first on each side — where focus\n * goes once `frame` is gone. Read BEFORE it goes: a removed node has no place in the\n * document to measure from. `limit` per side keeps a long page's stops out of memory.\n *\n * Walked outwards from the frame, `limit` stops each way (0.52 code review,\n * lib/focus-left.ts): read from every stop in the page, a banner under a 2000-row table\n * read all 2000 to keep the nearest five before it.\n */\nexport function tabStopsAround(frame: Element, limit = 5): { after: HTMLElement[]; before: HTMLElement[] } {\n  const doc = frame.ownerDocument;\n  const walker = doc.createTreeWalker(doc.documentElement, NodeFilter.SHOW_ELEMENT);\n  const isStop = (node: Node): node is HTMLElement =>\n    node instanceof HTMLElement && node.matches(TAB_STOP) && isTabStop(node);\n  // After: from the first element past the frame's own subtree, in document order.\n  const after: HTMLElement[] = [];\n  walker.currentNode = frame;\n  let node: Node | null = walker.nextSibling();\n  while (!node && walker.parentNode()) node = walker.nextSibling();\n  for (; node && after.length < limit; node = walker.nextNode()) if (isStop(node)) after.push(node);\n  // Before: back from the frame, nearest first (its ancestors among them, as before).\n  const before: HTMLElement[] = [];\n  walker.currentNode = frame;\n  for (node = walker.previousNode(); node && before.length < limit; node = walker.previousNode())\n    if (isStop(node)) before.push(node);\n  return { after, before };\n}\n\n/**\n * Focus the first of `candidates` that is still in the page and takes the focus; true\n * when one did. Each is tried and checked, since `focus()` on a node that cannot hold it\n * (detached, `display: none`, disabled since) fails without a word.\n */\nexport function focusFirst(candidates: Iterable<Element | null | undefined>): boolean {\n  for (const el of candidates) {\n    if (!(el instanceof HTMLElement) || !el.isConnected) continue;\n    el.focus();\n    if (document.activeElement === el) return true;\n  }\n  return false;\n}\n\n/**\n * Focus a container that is not a tab stop of its own — a table, a list — as the place\n * the user is in, without making it one: `tabindex=\"-1\"` for as long as it holds the\n * focus, unless it already carries a `tabindex` of its own.\n */\nexport function focusContainer(el: HTMLElement): void {\n  if (!el.hasAttribute(\"tabindex\")) {\n    el.setAttribute(\"tabindex\", \"-1\");\n    el.addEventListener(\"blur\", () => el.removeAttribute(\"tabindex\"), { once: true });\n  }\n  el.focus();\n}\n"],"mappings":";AA2BA,MAAM,WACJ;AAQF,SAAS,UAAU,IAA0B;AAC3C,SAAO,GAAG,YAAY,KAAK,CAAC,GAAG,QAAQ,kBAAkB;AAC3D;AAWO,SAAS,SAAS,IAAa,EAAE,cAAc,KAAK,IAAoB,CAAC,GAAkB;AAChG,QAAM,SAAS,MAAM,KAAK,GAAG,iBAA8B,QAAQ,CAAC,EAAE,OAAO,SAAS;AACtF,QAAM,MAAM,eAAe,cAAc,eAAe,GAAG,QAAQ,QAAQ,KAAK,UAAU,EAAE;AAC5F,SAAO,MAAM,CAAC,IAAI,GAAG,MAAM,IAAI;AACjC;AAGO,SAAS,aAAa,IAAa,SAA8C;AACtF,SAAO,SAAS,IAAI,OAAO,EAAE,CAAC,KAAK;AACrC;AAQO,SAAS,cAAuB;AACrC,MAAI,OAAO,aAAa,YAAa,QAAO;AAC5C,QAAM,KAAK,SAAS;AACpB,SAAO,CAAC,MAAM,OAAO,SAAS,QAAQ,CAAC,GAAG;AAC5C;AAkBO,SAAS,wBACd,GACA,MACM;AACN,QAAM,KAAK,EAAE;AACb,MAAI,EAAE,kBAAkB,QAAQ,EAAE,cAAc,SAAU;AAC1D,iBAAe,MAAM;AACnB,QAAI,CAAC,GAAG,eAAe,GAAG,QAAQ,WAAW,KAAK,GAAG,QAAQ,kBAAkB,EAAG;AAElF,QAAI,OAAO,GAAG,oBAAoB,cAAc,CAAC,GAAG,gBAAgB,EAAG;AACvE,QAAI,YAAY,EAAG,MAAK;AAAA,EAC1B,CAAC;AACH;AAWO,SAAS,eAAe,OAAgB,QAAQ,GAAoD;AACzG,QAAM,MAAM,MAAM;AAClB,QAAM,SAAS,IAAI,iBAAiB,IAAI,iBAAiB,WAAW,YAAY;AAChF,QAAM,SAAS,CAACA,UACdA,iBAAgB,eAAeA,MAAK,QAAQ,QAAQ,KAAK,UAAUA,KAAI;AAEzE,QAAM,QAAuB,CAAC;AAC9B,SAAO,cAAc;AACrB,MAAI,OAAoB,OAAO,YAAY;AAC3C,SAAO,CAAC,QAAQ,OAAO,WAAW,EAAG,QAAO,OAAO,YAAY;AAC/D,SAAO,QAAQ,MAAM,SAAS,OAAO,OAAO,OAAO,SAAS,EAAG,KAAI,OAAO,IAAI,EAAG,OAAM,KAAK,IAAI;AAEhG,QAAM,SAAwB,CAAC;AAC/B,SAAO,cAAc;AACrB,OAAK,OAAO,OAAO,aAAa,GAAG,QAAQ,OAAO,SAAS,OAAO,OAAO,OAAO,aAAa;AAC3F,QAAI,OAAO,IAAI,EAAG,QAAO,KAAK,IAAI;AACpC,SAAO,EAAE,OAAO,OAAO;AACzB;AAOO,SAAS,WAAW,YAA2D;AACpF,aAAW,MAAM,YAAY;AAC3B,QAAI,EAAE,cAAc,gBAAgB,CAAC,GAAG,YAAa;AACrD,OAAG,MAAM;AACT,QAAI,SAAS,kBAAkB,GAAI,QAAO;AAAA,EAC5C;AACA,SAAO;AACT;AAOO,SAAS,eAAe,IAAuB;AACpD,MAAI,CAAC,GAAG,aAAa,UAAU,GAAG;AAChC,OAAG,aAAa,YAAY,IAAI;AAChC,OAAG,iBAAiB,QAAQ,MAAM,GAAG,gBAAgB,UAAU,GAAG,EAAE,MAAM,KAAK,CAAC;AAAA,EAClF;AACA,KAAG,MAAM;AACX;","names":["node"]}
+{"version":3,"sources":["../../src/lib/focus-left.ts"],"sourcesContent":["// \"The focused node left\" (refactor audit 2026-10-30, Wave 1: DSP-4, DSP-15). When the\n// element holding the keyboard's focus is removed — a table row deleted, filtered out or\n// approved; a bulk bar gone with its Clear; a banner its × took away — the browser puts\n// focus on <body> and says nothing: no blur in Chromium, none in jsdom. A keyboard or\n// screen-reader user then starts again from the top of the page. These helpers are for\n// the controls that leave the page while the focus is IN them, and decide where it goes\n// instead; `returnFocus` is the one rule for that and for an overlay giving the focus\n// back as it closes (0.52 code review 2026-10-31, held to 0.55; use-focus-trap reads it).\n\n/**\n * Candidate tab stops, in DOM order — narrowed by {@link isTabStop} to the ones a Tab\n * really reaches. The kit's one copy of the rule (0.52 code review, lib/focus-left.ts):\n * this file and use-focus-trap each had it, with an exported `firstTabStop` apiece that\n * disagreed about the element itself, and a combobox panel's toolbar had a third\n * selector. The trap, the focus a removed node drops (below), the tour's field ring and\n * the toolbar all read it here, so \"the next stop\" is the same stop everywhere.\n *\n * The selector is the one `Modal` used. On its own it was not enough (round 0.34\n * BUG-4): only the bare `[tabindex]` clause excluded `-1`, so a `button`, an `input` or\n * a link taken out of the tab order still counted. A panel that ends in a roving grid —\n * the calendar's days, the month grid, the picker sheet's rows, every one of them `-1`\n * but the active cell — then had a \"last\" stop no Tab ever reaches: Tab from the real\n * last stop was not wrapped and walked out of the open panel, and Shift+Tab from the\n * first landed on a cell that is not a stop at all.\n */\n// `input[type=hidden]` is no stop: a Tab never lands on it and focus() on it does nothing,\n// but its tabIndex reads 0, so a trap could take a form's hidden field for its first or last\n// stop and Shift+Tab left the dialog (0.52 code review).\nconst TAB_STOP =\n  'a[href],button:not([disabled]),textarea:not([disabled]),input:not([disabled]):not([type=\"hidden\"]),select:not([disabled]),[tabindex]:not([tabindex=\"-1\"])';\n\n/**\n * A stop the browser's own Tab would land on: in the tab order (`tabIndex` ≥ 0) and not\n * inside something `hidden` or `inert`. Removes only elements a native Tab never\n * reaches, so no correct order changes. `visibility: hidden` and closed `<details>` are\n * still not walked — they need layout, which this rule has never read.\n */\nfunction isTabStop(el: HTMLElement): boolean {\n  return el.tabIndex >= 0 && !el.closest(\"[hidden],[inert]\");\n}\n\nexport interface TabStopOptions {\n  /** Whether `el` itself counts, first, when it is a stop. Default true: the tour's\n   *  target may BE the field (refactor audit 2026-10-30, DUP-9). False for \"a control\n   *  inside it\" — a row, a drawer, a trap's container, a toolbar. */\n  includeSelf?: boolean;\n}\n\n/** The tab stops in `el`, in DOM order — `el` itself first when it is one, unless\n *  `includeSelf: false`. */\nexport function tabStops(el: Element, { includeSelf = true }: TabStopOptions = {}): HTMLElement[] {\n  const inside = Array.from(el.querySelectorAll<HTMLElement>(TAB_STOP)).filter(isTabStop);\n  const own = includeSelf && el instanceof HTMLElement && el.matches(TAB_STOP) && isTabStop(el);\n  return own ? [el, ...inside] : inside;\n}\n\n/** The first of {@link tabStops} — the control a person types into or presses — or null. */\nexport function firstTabStop(el: Element, options?: TabStopOptions): HTMLElement | null {\n  return tabStops(el, options)[0] ?? null;\n}\n\n/**\n * Whether the focus has fallen out of the page: onto `<body>`, onto nothing, or onto a\n * node no longer in the document. False on the server, where nothing has focus to lose.\n * A recovery asks this first: focus that went somewhere real (a dialog, the next field,\n * an app's own `focus()`) is the user's or the app's, and is left where it is.\n */\nexport function focusIsLost(): boolean {\n  if (typeof document === \"undefined\") return false;\n  const el = document.activeElement;\n  return !el || el === document.body || !el.isConnected;\n}\n\n/**\n * Calls `then` when a `blur`/`focusout` was the user's own move to nothing — a click on\n * the page's background, or a click Safari answers by focusing nothing (it focuses no\n * button or link on a click, and blurs what had the focus) — after which a note of where\n * the focus was is stale (0.52 code review: DataTable's row, BulkActionBar's and\n * AlertBanner's notes outlived it, and a removal much later pulled the focus, and the\n * scroll, back to them).\n *\n * No element took the focus, the document holds none, and the node that lost it could\n * still hold it. Not when it was removed, hidden, made inert or disabled: that is the page\n * taking the focus away — the very case those notes are kept for. Not a window losing the\n * focus either, which leaves the node the document's active element. Decided a microtask\n * later, once the event's own work is done: a browser that blurs a node it is removing\n * (or hiding) may do it while the node is still in place, and only after it is gone is\n * that told apart from a click.\n */\nexport function whenFocusLeftForNothing(\n  e: { target: EventTarget | null; relatedTarget: EventTarget | null },\n  then: () => void,\n): void {\n  const el = e.target;\n  if (e.relatedTarget !== null || !(el instanceof Element)) return;\n  queueMicrotask(() => {\n    if (!el.isConnected || el.matches(\":disabled\") || el.closest(\"[hidden],[inert]\")) return;\n    // `display: none`, where the browser can say (jsdom cannot).\n    if (typeof el.checkVisibility === \"function\" && !el.checkVisibility()) return;\n    if (focusIsLost()) then();\n  });\n}\n\n/**\n * The tab stops around `frame`, outside it, nearest first on each side — where focus\n * goes once `frame` is gone. Read BEFORE it goes: a removed node has no place in the\n * document to measure from. `limit` per side keeps a long page's stops out of memory.\n *\n * Walked outwards from the frame, `limit` stops each way (0.52 code review,\n * lib/focus-left.ts): read from every stop in the page, a banner under a 2000-row table\n * read all 2000 to keep the nearest five before it.\n */\nexport function tabStopsAround(frame: Element, limit = 5): { after: HTMLElement[]; before: HTMLElement[] } {\n  const doc = frame.ownerDocument;\n  const walker = doc.createTreeWalker(doc.documentElement, NodeFilter.SHOW_ELEMENT);\n  const isStop = (node: Node): node is HTMLElement =>\n    node instanceof HTMLElement && node.matches(TAB_STOP) && isTabStop(node);\n  // After: from the first element past the frame's own subtree, in document order.\n  const after: HTMLElement[] = [];\n  walker.currentNode = frame;\n  let node: Node | null = walker.nextSibling();\n  while (!node && walker.parentNode()) node = walker.nextSibling();\n  for (; node && after.length < limit; node = walker.nextNode()) if (isStop(node)) after.push(node);\n  // Before: back from the frame, nearest first (its ancestors among them, as before).\n  const before: HTMLElement[] = [];\n  walker.currentNode = frame;\n  for (node = walker.previousNode(); node && before.length < limit; node = walker.previousNode())\n    if (isStop(node)) before.push(node);\n  return { after, before };\n}\n\n/**\n * Focus the first of `candidates` that is still in the page and takes the focus; true\n * when one did. Each is tried and checked, since `focus()` on a node that cannot hold it\n * (detached, `display: none`, disabled since) fails without a word. An SVG element counts\n * (a chart's tile, a slice); `<body>` and `<html>` never do — \"focused\" there is the\n * focus lost, not given (0.52 code review 2026-10-31, held to 0.55).\n */\nexport function focusFirst(candidates: Iterable<Element | null | undefined>): boolean {\n  for (const el of candidates) {\n    if (!(el instanceof HTMLElement || el instanceof SVGElement) || !el.isConnected) continue;\n    if (el === el.ownerDocument.body || el === el.ownerDocument.documentElement) continue;\n    el.focus();\n    if (el.ownerDocument.activeElement === el) return true;\n  }\n  return false;\n}\n\n/** {@link returnFocus}'s three answers to \"where was this opened from\". */\nexport interface FocusReturn {\n  /** The control it was opened from: the overlay's trigger when it names one, else what\n   *  held the focus as it opened. */\n  opener?: Element | null;\n  /** Where the focus goes when the opener cannot take it, nearest first — the overlay's\n   *  stated fallback. */\n  fallback?: Iterable<Element | null | undefined>;\n  /** What is closing, while it is still in the page (a panel on its way out, a list\n   *  about to unmount): a focus inside it is one to give back. */\n  closing?: Element | null;\n}\n\n/**\n * Where the focus goes when an overlay closes, or a control holding it leaves the page —\n * the kit's ONE rule for it (0.52 code review 2026-10-31, held to 0.55). The dialogs, the\n * popovers and menus, the drawers, the phone sheets, the tour, AlertBanner's × and the\n * Treemap's tiles each decided it themselves, and they drifted: the trap gave the focus\n * back whenever its opener was still connected — over a focus the app had just placed —\n * and left it on `<body>` when it was not; the date and month pickers and the floating\n * panel moved it only when it was lost; the dropdown, the combobox and the column drawer\n * moved it to their trigger every time, unchecked; and a Treemap tile's note of where to\n * go once outlived the commit it was for and took the focus back, from wherever the\n * reader was, when the map was shown again.\n *\n * 1. **Only a lost focus is moved** — on `<body>`, on nothing or on a removed node\n *    ({@link focusIsLost}) — or one still inside what is `closing`. A focus that went\n *    somewhere real is the user's (an outside press landed on a field) or the app's (its\n *    own `focus()` in `onClose`), and stays.\n * 2. **To the opener**, if it is still in the page and takes the focus: `focus()` is\n *    checked, as a disabled, hidden or inert opener refuses it without a word.\n * 3. **Else to the stated fallback**, the first of it that does — each caller names its\n *    own: the trap the stops that stood around its opener, a banner the stops around its\n *    ×, the map the tile that holds its tab stop.\n * 4. **Never to `<body>`**: no `focus()` on a node that has left, none on `<body>`, no\n *    `blur()`. When nothing can take the focus — the page under the overlay was replaced\n *    — it is left for the page's own handling of a new page, not guessed at.\n * 5. **Only in the closing commit**: called from the commit that closes or removes (a\n *    handler that closes, a ref callback, a layout effect, an effect's cleanup), and\n *    nothing handed to it is kept. A note gathered earlier, where a removed node can no\n *    longer be measured from, is spent or dropped in that commit.\n *\n * True when it moved the focus.\n */\nexport function returnFocus({ opener, fallback = [], closing }: FocusReturn): boolean {\n  if (typeof document === \"undefined\") return false;\n  const active = document.activeElement;\n  const inside = Boolean(closing?.isConnected && active && closing.contains(active));\n  if (!inside && !focusIsLost()) return false;\n  return focusFirst([opener, ...fallback]);\n}\n\n/**\n * Focus a container that is not a tab stop of its own — a table, a list — as the place\n * the user is in, without making it one: `tabindex=\"-1\"` for as long as it holds the\n * focus, unless it already carries a `tabindex` of its own.\n */\nexport function focusContainer(el: HTMLElement): void {\n  if (!el.hasAttribute(\"tabindex\")) {\n    el.setAttribute(\"tabindex\", \"-1\");\n    el.addEventListener(\"blur\", () => el.removeAttribute(\"tabindex\"), { once: true });\n  }\n  el.focus();\n}\n"],"mappings":";AA4BA,MAAM,WACJ;AAQF,SAAS,UAAU,IAA0B;AAC3C,SAAO,GAAG,YAAY,KAAK,CAAC,GAAG,QAAQ,kBAAkB;AAC3D;AAWO,SAAS,SAAS,IAAa,EAAE,cAAc,KAAK,IAAoB,CAAC,GAAkB;AAChG,QAAM,SAAS,MAAM,KAAK,GAAG,iBAA8B,QAAQ,CAAC,EAAE,OAAO,SAAS;AACtF,QAAM,MAAM,eAAe,cAAc,eAAe,GAAG,QAAQ,QAAQ,KAAK,UAAU,EAAE;AAC5F,SAAO,MAAM,CAAC,IAAI,GAAG,MAAM,IAAI;AACjC;AAGO,SAAS,aAAa,IAAa,SAA8C;AACtF,SAAO,SAAS,IAAI,OAAO,EAAE,CAAC,KAAK;AACrC;AAQO,SAAS,cAAuB;AACrC,MAAI,OAAO,aAAa,YAAa,QAAO;AAC5C,QAAM,KAAK,SAAS;AACpB,SAAO,CAAC,MAAM,OAAO,SAAS,QAAQ,CAAC,GAAG;AAC5C;AAkBO,SAAS,wBACd,GACA,MACM;AACN,QAAM,KAAK,EAAE;AACb,MAAI,EAAE,kBAAkB,QAAQ,EAAE,cAAc,SAAU;AAC1D,iBAAe,MAAM;AACnB,QAAI,CAAC,GAAG,eAAe,GAAG,QAAQ,WAAW,KAAK,GAAG,QAAQ,kBAAkB,EAAG;AAElF,QAAI,OAAO,GAAG,oBAAoB,cAAc,CAAC,GAAG,gBAAgB,EAAG;AACvE,QAAI,YAAY,EAAG,MAAK;AAAA,EAC1B,CAAC;AACH;AAWO,SAAS,eAAe,OAAgB,QAAQ,GAAoD;AACzG,QAAM,MAAM,MAAM;AAClB,QAAM,SAAS,IAAI,iBAAiB,IAAI,iBAAiB,WAAW,YAAY;AAChF,QAAM,SAAS,CAACA,UACdA,iBAAgB,eAAeA,MAAK,QAAQ,QAAQ,KAAK,UAAUA,KAAI;AAEzE,QAAM,QAAuB,CAAC;AAC9B,SAAO,cAAc;AACrB,MAAI,OAAoB,OAAO,YAAY;AAC3C,SAAO,CAAC,QAAQ,OAAO,WAAW,EAAG,QAAO,OAAO,YAAY;AAC/D,SAAO,QAAQ,MAAM,SAAS,OAAO,OAAO,OAAO,SAAS,EAAG,KAAI,OAAO,IAAI,EAAG,OAAM,KAAK,IAAI;AAEhG,QAAM,SAAwB,CAAC;AAC/B,SAAO,cAAc;AACrB,OAAK,OAAO,OAAO,aAAa,GAAG,QAAQ,OAAO,SAAS,OAAO,OAAO,OAAO,aAAa;AAC3F,QAAI,OAAO,IAAI,EAAG,QAAO,KAAK,IAAI;AACpC,SAAO,EAAE,OAAO,OAAO;AACzB;AASO,SAAS,WAAW,YAA2D;AACpF,aAAW,MAAM,YAAY;AAC3B,QAAI,EAAE,cAAc,eAAe,cAAc,eAAe,CAAC,GAAG,YAAa;AACjF,QAAI,OAAO,GAAG,cAAc,QAAQ,OAAO,GAAG,cAAc,gBAAiB;AAC7E,OAAG,MAAM;AACT,QAAI,GAAG,cAAc,kBAAkB,GAAI,QAAO;AAAA,EACpD;AACA,SAAO;AACT;AA8CO,SAAS,YAAY,EAAE,QAAQ,WAAW,CAAC,GAAG,QAAQ,GAAyB;AACpF,MAAI,OAAO,aAAa,YAAa,QAAO;AAC5C,QAAM,SAAS,SAAS;AACxB,QAAM,SAAS,QAAQ,SAAS,eAAe,UAAU,QAAQ,SAAS,MAAM,CAAC;AACjF,MAAI,CAAC,UAAU,CAAC,YAAY,EAAG,QAAO;AACtC,SAAO,WAAW,CAAC,QAAQ,GAAG,QAAQ,CAAC;AACzC;AAOO,SAAS,eAAe,IAAuB;AACpD,MAAI,CAAC,GAAG,aAAa,UAAU,GAAG;AAChC,OAAG,aAAa,YAAY,IAAI;AAChC,OAAG,iBAAiB,QAAQ,MAAM,GAAG,gBAAgB,UAAU,GAAG,EAAE,MAAM,KAAK,CAAC;AAAA,EAClF;AACA,KAAG,MAAM;AACX;","names":["node"]}

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

@@ -35,6 +35,12 @@
  * It never arms while the browser is offline, whatever `shouldWatch` says: that state
  * has its own, truthful indicator, and a request that never left the device is not
  * evidence of anything about the server.
+ *
+ * A READ THAT IS HEAVY ON PURPOSE (0.55) — a report the server computes for a few
+ * seconds — says so with `slowOk` on its request (the axios config, or `track`'s
+ * request): it is counted, but never called slow, so it shows nothing while it is under
+ * `wakingMs`. Past `wakingMs` it is the server waking like any other read. A read that
+ * can take longer than that on a warm server stays out of the watch (`shouldWatch`).
  */
 /** `slow` = longer than a warm server ever takes; `waking` = long enough that a cold
  *  start is the only sensible explanation. */
@@ -61,21 +67,53 @@ export interface ServerWakeRequest {
     /** axios's `responseType`. `"blob"`, `"arraybuffer"` and `"stream"` mark a download,
      *  which the default filter does not count. */
     responseType?: string;
+    /**
+     * This read is slow on purpose (0.55; the per-request opt-out adopt-0.51 left open): it
+     * still counts, but its own age never shows "taking longer than usual" — only past
+     * `wakingMs`, when a cold start is the likelier story, does it show the server waking.
+     * The stage then follows the other requests out beside it, as ever.
+     *
+     * ONLY for a read that is heavy but answers under `wakingMs` (7 s) on a warm server: a
+     * report computed on request, a large page of rows. A read that can take longer — an
+     * export rendered on the server, a slow third party behind the route — would say "the
+     * server is waking up" on a warm server; keep it out of the watch through `shouldWatch`
+     * instead (kastlan's advice), as a download and an upload are.
+     *
+     * On axios it rides the request config: `api.get(url, { slowOk: true })` (declare it on
+     * `AxiosRequestConfig` once, by module augmentation); through `track`, on its request.
+     */
+    slowOk?: boolean;
 }
+/**
+ * One counted request, as {@link ServerWakeWatcher.start} names it (0.55, keksdose's 0.51
+ * review N4): a positive whole number, unique for the watcher's lifetime, which
+ * {@link ServerWakeWatcher.end} takes back to end exactly that request. `start` returns
+ * `false` where it counts nothing, as before: the token is truthy where `start` returned
+ * `true` until 0.55, so code that only tests it reads as it did.
+ */
+export type ServerWakeToken = number;
 export interface ServerWakeWatcher {
     /**
      * Count a request that is going out, and arm the escalation if it is the first.
-     * Returns whether it was counted — the caller MUST call {@link end} exactly once
-     * for every `true`, or the counter never returns to zero and the notice sticks.
-     * (The axios adapter stashes it on the request config for that reason.)
+     * Returns its {@link ServerWakeToken}, or `false` when it was not counted (until 0.55
+     * `true` / `false`; the token is truthy where `true` was). The caller MUST end every
+     * counted request exactly once, or the counter never returns to zero and the notice
+     * sticks: `end(token)`, which ends that request, or a bare `end()`, as before. (The
+     * axios adapter stashes the token on the request config for that reason.)
      * `request` reaches the filter as its third argument; default `{ method, url }`.
      */
-    start(method?: string, url?: string, request?: ServerWakeRequest): boolean;
-    /** A counted request settled — either way: an error still proves the server
-     *  answered or gave up. The stage then follows the oldest request still out (0.51), so
-     *  the notice goes away when the last one does, or sooner when the rest are recent.
-     *  Never takes the counter below zero. */
-    end(): void;
+    start(method?: string, url?: string, request?: ServerWakeRequest): ServerWakeToken | false;
+    /**
+     * A counted request settled — either way: an error still proves the server answered or
+     * gave up. The stage then follows the oldest request still out (0.51), so the notice
+     * goes away when the last one does, or sooner when the rest are recent.
+     *
+     * With `token` (0.55), exactly that request is retired, so the age the stage is read
+     * from is the real one; a token that was ended already (or reset away), or `false`, is
+     * a no-op. A bare `end()` — the call before 0.55 — retires the OLDEST start, which can
+     * make a notice come late, never falsely. Never takes the counter below zero.
+     */
+    end(token?: ServerWakeToken | false): void;
     /** `start` + `end` around a promise (or a function returning one), for a request
      *  that does not go through an adapter. Resolves and rejects as the work does. */
     track<T>(work: PromiseLike<T> | (() => PromiseLike<T>), request?: ServerWakeRequest): Promise<T>;
@@ -108,6 +146,8 @@ export interface ServerWakeAxiosConfig {
     method?: string;
     url?: string;
     responseType?: string;
+    /** A read slow on purpose — see {@link ServerWakeRequest.slowOk} (0.55). */
+    slowOk?: boolean;
 }
 /** The slice of an interceptor manager the adapter uses. A method (not a function
  *  property) so axios's wider `use(onFulfilled?, onRejected?, options?)` fits it. */

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