@eifi1/ui-kit 0.33.1 → 0.35.0

package/dist/lib/session-refresh.js

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

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

@@ -0,0 +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 \"../auth/auth-errors\";\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 }\n  | { result: \"ended\" }\n  | { result: \"transient\" }\n  | { 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<C extends SessionRefreshAxiosConfig, 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":"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","names":[]}

package/dist/lib/strip-fade.d.ts

@@ -1,10 +1,9 @@
-import { CSSProperties, FocusEvent, RefObject } from 'react';
-
-declare const TAB_FADE_PX = 24;
+import type { CSSProperties, FocusEvent, RefObject } from "react";
+export declare const TAB_FADE_PX = 24;
 /**
  * What {@link useStripFade} can be asked to do beyond the strip it was written for.
  */
-interface StripFadeOptions {
+export interface StripFadeOptions {
     /**
      * Keep the strip's own SCROLLBARS out of the fade (0.25, for the kit Table's and
      * DataTable's `edgeFade`). A `mask-image` masks everything the element paints, and
@@ -22,7 +21,7 @@ interface StripFadeOptions {
     spareScrollbars?: boolean;
 }
 /** The room the classic scrollbars of a strip take, and the borders beside them. */
-interface StripScrollbars {
+export interface StripScrollbars {
     /** Vertical scrollbar on the left (RTL in Chromium and Firefox), in px. */
     left: number;
     /** Vertical scrollbar on the right, in px. */
@@ -40,7 +39,7 @@ interface StripScrollbars {
  * and its tests; `scrollbars` (see {@link StripFadeOptions.spareScrollbars}) keeps
  * those bands opaque and starts the fade at the content's edge instead of the box's.
  */
-declare function stripFadeMask(edges: {
+export declare function stripFadeMask(edges: {
     left: boolean;
     right: boolean;
 }, scrollbars?: StripScrollbars): string | undefined;
@@ -61,7 +60,7 @@ declare function stripFadeMask(edges: {
  * element, and `scrollLeft` is a magnitude here because an RTL strip counts it
  * negative from the start edge.
  */
-declare function useStripFade(ref: RefObject<HTMLElement | null>, options?: StripFadeOptions): {
+export declare function useStripFade(ref: RefObject<HTMLElement | null>, options?: StripFadeOptions): {
     mask: string | undefined;
     overflow: "start" | "end" | "both" | undefined;
 };
@@ -75,7 +74,7 @@ declare function useStripFade(ref: RefObject<HTMLElement | null>, options?: Stri
  * scrolled into, and {@link StripFadeOptions.spareScrollbars} starts the fade inside
  * the scrollbar. A Tabs strip has neither, so its edges are where they were.
  */
-declare function scrollIntoStrip(strip: HTMLElement, item: HTMLElement): void;
+export declare function scrollIntoStrip(strip: HTMLElement, item: HTMLElement): void;
 /**
  * Focus landed on `focused` inside a faded table's scroller (0.25, Table and
  * DataTable `edgeFade`): bring it clear of the fade. The browser's own focus scroll
@@ -86,9 +85,9 @@ declare function scrollIntoStrip(strip: HTMLElement, item: HTMLElement): void;
  * its end — would be brought in by its start and leave the link out, so then the
  * focused element itself is what is scrolled clear.
  */
-declare function scrollFocusIntoStrip(strip: HTMLElement, focused: HTMLElement): void;
+export declare function scrollFocusIntoStrip(strip: HTMLElement, focused: HTMLElement): void;
 /** What {@link useEdgeFade} puts on the scroller; every field `undefined` while off. */
-interface EdgeFadeProps {
+export interface EdgeFadeProps {
     "data-overflow": "start" | "end" | "both" | undefined;
     style: CSSProperties | undefined;
     onFocus: ((event: FocusEvent<HTMLElement>) => void) | undefined;
@@ -105,6 +104,4 @@ interface EdgeFadeProps {
  *
  * `style` is the mask alone; a caller with a style of its own spreads it over that.
  */
-declare function useEdgeFade(scroller: RefObject<HTMLElement | null>, on: boolean): EdgeFadeProps;
-
-export { type EdgeFadeProps, type StripFadeOptions, type StripScrollbars, TAB_FADE_PX, scrollFocusIntoStrip, scrollIntoStrip, stripFadeMask, useEdgeFade, useStripFade };
+export declare function useEdgeFade(scroller: RefObject<HTMLElement | null>, on: boolean): EdgeFadeProps;

package/dist/lib/table-text.d.ts

@@ -54,8 +54,8 @@
  */
 /** Where the decision about the comma is taken. See the module docstring: the
  *  file door decides once for the whole text, the paste door decides per line. */
-type DecimalRule = "per-line" | "whole-text";
-interface ParseTableOptions {
+export type DecimalRule = "per-line" | "whole-text";
+export interface ParseTableOptions {
     decimal: DecimalRule;
     /**
      * How many columns the caller already knows the table has. A grid with fixed
@@ -72,7 +72,7 @@ interface ParseTableOptions {
      */
     headerLines?: number;
 }
-interface ParsedTable {
+export interface ParsedTable {
     rows: number[][];
     /** The first header line's fields — the column *names*. A units line under it
      *  is absorbed and not returned: what a column is measured in is the caller's to
@@ -97,7 +97,7 @@ interface ParsedTable {
  * person who pasted it can see which column went wrong. Dropping it here would
  * shift every column after it and lose the evidence.
  */
-declare function splitRow(line: string): string[];
+export declare function splitRow(line: string): string[];
 /**
  * A pasted table, or the lines of it that are not one.
  *
@@ -105,7 +105,7 @@ declare function splitRow(line: string): string[];
  * banners, decides what separates the columns, takes the header off the top and
  * converts what is left.
  */
-declare function parseTable(text: string, options: ParseTableOptions): ParsedTable;
+export declare function parseTable(text: string, options: ParseTableOptions): ParsedTable;
 /**
  * The paste door: a fixed number of columns, and the line that stopped it.
  *
@@ -117,31 +117,31 @@ declare function parseTable(text: string, options: ParseTableOptions): ParsedTab
  * produced no row at all is an error naming its first unreadable line, never
  * `{ rows: [] }`.
  */
-declare function parseRows(text: string, columns: number): {
+export declare function parseRows(text: string, columns: number): {
     rows: number[][];
 } | {
     error: number;
 };
 /** One cell as a number. Unconditional: a cell has no columns in it, so a comma
  *  in one is a decimal mark and nothing else. */
-declare const cellNumber: (cell: string) => number;
+export declare const cellNumber: (cell: string) => number;
 /** Whether one cell holds a number yet. An empty cell is not one — it is a hole
  *  in the measurement, which is a different thing from a zero. */
-declare const isCellNumber: (cell: string) => boolean;
+export declare const isCellNumber: (cell: string) => boolean;
 /**
  * What separates the columns of a {@link TextTable}, named. `" "` is a run of
  * whitespace — one separator however many spaces or tabs it is made of — as in a
  * printed or MATLAB-dumped table.
  */
-type TableSeparator = "\t" | ";" | "," | " ";
+export type TableSeparator = "\t" | ";" | "," | " ";
 /** One line of the text as it was handed over: its 1-based number (blank lines
  *  counted, so a reader can count to it in the box they pasted into) and its text,
  *  trimmed. */
-interface TableLine {
+export interface TableLine {
     line: number;
     text: string;
 }
-interface ParseTextTableOptions {
+export interface ParseTextTableOptions {
     /** The separator, decided by the caller — a "separated by" override, a format
      *  the app already knows. Default: detected (see {@link parseTextTable}). */
     separator?: TableSeparator;
@@ -160,7 +160,7 @@ interface ParseTextTableOptions {
  * mark that were assumed, and the lines that were not read, with their number and
  * their text — because a guess nobody can see is a guess nobody can correct.
  */
-interface TextTable {
+export interface TextTable {
     /** The first line's cells, when it names the columns; `null` when it is data. */
     header: string[] | null;
     /** Each read row, `width` cells long. An empty cell is `""`, kept in its place. */
@@ -218,7 +218,7 @@ interface TextTable {
  *
  * Blank lines and `#` banners are skipped, as by the numeric lexer.
  */
-declare function parseTextTable(text: string, options?: ParseTextTableOptions): TextTable;
+export declare function parseTextTable(text: string, options?: ParseTextTableOptions): TextTable;
 /**
  * One cell of a {@link TextTable} as a number, read in the table's convention.
  *
@@ -230,6 +230,4 @@ declare function parseTextTable(text: string, options?: ParseTextTableOptions):
  * lexer does not read grouped numbers, it reports them. An empty cell is `NaN` too —
  * a hole in the table, not a zero.
  */
-declare function tableNumber(cell: string, decimalComma: boolean): number;
-
-export { type DecimalRule, type ParseTableOptions, type ParseTextTableOptions, type ParsedTable, type TableLine, type TableSeparator, type TextTable, cellNumber, isCellNumber, parseRows, parseTable, parseTextTable, splitRow, tableNumber };
+export declare function tableNumber(cell: string, decimalComma: boolean): number;

package/dist/lib/text-match.d.ts

@@ -0,0 +1,41 @@
+/**
+ * How typing into a kit list matches its rows — one rule for every list (DUP-5, refactor
+ * audit 2026-10).
+ *
+ * There were six. "zurich" found Zürich in CountrySelect and the command palette and in no
+ * EntityCombobox, Combobox, MultiSelect or DataTable text filter, where keksdose's
+ * Swiss-German payees and categories and kastlan's eighteen entity pickers live; "İ"
+ * folded by the locale in GroupedPicker and nowhere in the combobox family. The folding
+ * only ever widens a match, so moving every list onto it took nothing away.
+ */
+/**
+ * A text as search compares it: the locale's lower case, accents off, ß spelt "ss" —
+ * "Zürich" and "ZURICH" both read "zurich", "Straße" reads "strasse". Punctuation and
+ * symbols stay: a currency is found by its "€", and "c++" is not the empty query.
+ *
+ * Lower-cased by the locale FIRST, then decomposed: the Turkish "İ" lower-cases to "i"
+ * and the dotted capital's mark is then dropped like any other, so "istanbul" finds
+ * "İSTANBUL" in every locale, while "I" folds to the dotless "ı" in Turkish alone.
+ * `locale` left out is the runtime's default; a malformed tag folds as if left out.
+ */
+export declare function foldForSearch(text: string, locale?: string): string;
+/** {@link rankMatch}'s answer: lower is better, `-1` is no match. */
+export type MatchRank = -1 | 0 | 1 | 2;
+/**
+ * How well `label` answers `query` — CountrySelect's ranking, for every list that orders
+ * its hits:
+ *
+ * - `0`: the query IS the row — its `code` ("ch" means Switzerland before it means Chad)
+ *   or the whole label;
+ * - `1`: the label starts with it;
+ * - `2`: the label contains it;
+ * - `-1`: no match.
+ *
+ * Both sides are folded here ({@link foldForSearch}, by `locale`), so pass them as typed
+ * and as shown. An empty query matches every row alike (`0`). Sort by the rank with a
+ * stable sort, and rows of one rank keep the order they came in.
+ */
+export declare function rankMatch(label: string, query: string, { code, locale }?: {
+    code?: string;
+    locale?: string;
+}): MatchRank;

package/dist/lib/text-match.js

@@ -0,0 +1,23 @@
+"use client";
+function foldForSearch(text, locale) {
+  let lower;
+  try {
+    lower = text.toLocaleLowerCase(locale);
+  } catch {
+    lower = text.toLocaleLowerCase();
+  }
+  return lower.normalize("NFD").replace(/\p{M}+/gu, "").replace(/ß/g, "ss");
+}
+function rankMatch(label, query, { code, locale } = {}) {
+  const q = foldForSearch(query.trim(), locale);
+  if (!q) return 0;
+  const text = foldForSearch(label, locale);
+  if (text === q || code !== void 0 && foldForSearch(code, locale) === q) return 0;
+  if (text.startsWith(q)) return 1;
+  return text.includes(q) ? 2 : -1;
+}
+export {
+  foldForSearch,
+  rankMatch
+};
+//# sourceMappingURL=text-match.js.map

package/dist/lib/text-match.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/text-match.ts"],"sourcesContent":["/**\n * How typing into a kit list matches its rows — one rule for every list (DUP-5, refactor\n * audit 2026-10).\n *\n * There were six. \"zurich\" found Zürich in CountrySelect and the command palette and in no\n * EntityCombobox, Combobox, MultiSelect or DataTable text filter, where keksdose's\n * Swiss-German payees and categories and kastlan's eighteen entity pickers live; \"İ\"\n * folded by the locale in GroupedPicker and nowhere in the combobox family. The folding\n * only ever widens a match, so moving every list onto it took nothing away.\n */\n\n/**\n * A text as search compares it: the locale's lower case, accents off, ß spelt \"ss\" —\n * \"Zürich\" and \"ZURICH\" both read \"zurich\", \"Straße\" reads \"strasse\". Punctuation and\n * symbols stay: a currency is found by its \"€\", and \"c++\" is not the empty query.\n *\n * Lower-cased by the locale FIRST, then decomposed: the Turkish \"İ\" lower-cases to \"i\"\n * and the dotted capital's mark is then dropped like any other, so \"istanbul\" finds\n * \"İSTANBUL\" in every locale, while \"I\" folds to the dotless \"ı\" in Turkish alone.\n * `locale` left out is the runtime's default; a malformed tag folds as if left out.\n */\nexport function foldForSearch(text: string, locale?: string): string {\n  let lower: string;\n  try {\n    lower = text.toLocaleLowerCase(locale);\n  } catch {\n    lower = text.toLocaleLowerCase();\n  }\n  return lower.normalize(\"NFD\").replace(/\\p{M}+/gu, \"\").replace(/ß/g, \"ss\");\n}\n\n/** {@link rankMatch}'s answer: lower is better, `-1` is no match. */\nexport type MatchRank = -1 | 0 | 1 | 2;\n\n/**\n * How well `label` answers `query` — CountrySelect's ranking, for every list that orders\n * its hits:\n *\n * - `0`: the query IS the row — its `code` (\"ch\" means Switzerland before it means Chad)\n *   or the whole label;\n * - `1`: the label starts with it;\n * - `2`: the label contains it;\n * - `-1`: no match.\n *\n * Both sides are folded here ({@link foldForSearch}, by `locale`), so pass them as typed\n * and as shown. An empty query matches every row alike (`0`). Sort by the rank with a\n * stable sort, and rows of one rank keep the order they came in.\n */\nexport function rankMatch(\n  label: string,\n  query: string,\n  { code, locale }: { code?: string; locale?: string } = {},\n): MatchRank {\n  const q = foldForSearch(query.trim(), locale);\n  if (!q) return 0;\n  const text = foldForSearch(label, locale);\n  if (text === q || (code !== undefined && foldForSearch(code, locale) === q)) return 0;\n  if (text.startsWith(q)) return 1;\n  return text.includes(q) ? 2 : -1;\n}\n"],"mappings":";AAqBO,SAAS,cAAc,MAAc,QAAyB;AACnE,MAAI;AACJ,MAAI;AACF,YAAQ,KAAK,kBAAkB,MAAM;AAAA,EACvC,QAAQ;AACN,YAAQ,KAAK,kBAAkB;AAAA,EACjC;AACA,SAAO,MAAM,UAAU,KAAK,EAAE,QAAQ,YAAY,EAAE,EAAE,QAAQ,MAAM,IAAI;AAC1E;AAmBO,SAAS,UACd,OACA,OACA,EAAE,MAAM,OAAO,IAAwC,CAAC,GAC7C;AACX,QAAM,IAAI,cAAc,MAAM,KAAK,GAAG,MAAM;AAC5C,MAAI,CAAC,EAAG,QAAO;AACf,QAAM,OAAO,cAAc,OAAO,MAAM;AACxC,MAAI,SAAS,KAAM,SAAS,UAAa,cAAc,MAAM,MAAM,MAAM,EAAI,QAAO;AACpF,MAAI,KAAK,WAAW,CAAC,EAAG,QAAO;AAC/B,SAAO,KAAK,SAAS,CAAC,IAAI,IAAI;AAChC;","names":[]}