@eifi1/ui-kit 0.45.0 → 0.46.0

package/src/notifications/quiet-hours-setting.tsx

@@ -3,7 +3,6 @@ import type { ComponentPropsWithRef, ReactNode } from "react";
 
 import type { LabelOverride } from "../i18n/kit-labels";
 import { cn } from "../lib/cn";
-import { Button } from "../components/button";
 import { Card } from "../components/card";
 import { TimeInput } from "../components/time-input";
 import { COMMIT_EXCEPT_BILLING } from "../components/write-lock";
@@ -13,9 +12,9 @@ import { settle, useMounted } from "../account/account-parts";
 import { describeFailure, FailureLine, useNotificationsLabels, useWriteOverlay } from "./notification-parts";
 import type { NotificationsLabels } from "./notifications-labels";
 import type { NotificationSettingsPatch } from "./notification-types";
-import { deviceTimeZone, TimeZoneSelect, zoneName } from "./time-zone-select";
+import { zoneName } from "./time-zone-select";
 
-/** The zone the server applies while the account has none (§2.6): every app's. */
+/** The zone the server applies while no device ever reported one (§10.3): every app's. */
 const DEFAULT_FALLBACK_ZONE = "Europe/Zurich";
 
 export interface QuietHoursSettingProps extends Omit<ComponentPropsWithRef<"div">, "children" | "onChange"> {
@@ -23,17 +22,29 @@ export interface QuietHoursSettingProps extends Omit<ComponentPropsWithRef<"div"
   start: string | null;
   /** The `GET`'s `quiet_hours_end`. */
   end: string | null;
-  /** The `GET`'s `timezone`, an IANA name, or `null` (the app's zone applies). */
-  timezone: string | null;
+  /** The zone the 0.36 card showed, an IANA name, or `null`.
+   *  @deprecated 0.46 — pass `zone` (§10.3: the zone is the account's, automatic only); removed in 0.47.
+   *  Shown read-only while `zone` is left out; the card no longer offers a picker. */
+  timezone?: string | null;
   /**
-   * Save one change — `PATCH /notifications/settings`: a time (`null` when cleared), with
-   * the device's zone the first time one is entered while `timezone` is `null`; or
-   * `{timezone}`. The field shows the new value while the call runs and goes back if it
+   * 0.46 (§10.3, amended 2026-10-20: automatic only): the account's zone — `/auth/me`'s
+   * `device_timezone`, the zone of the device last used; `null` while no device has
+   * reported one, and the card then names `fallbackZone`, the zone the server applies.
+   * Shown read-only once a time is set ("In your time zone (Europe / Zurich), which follows
+   * the device you last used."). No picker: the zone is never chosen.
+   */
+  zone?: string | null;
+  /** 0.46 (§10.4): the app queues a held push and sends it when the window ends (it runs
+   *  the notifications tick); the description says so. Default `false`: dropped. */
+  held?: boolean;
+  /**
+   * Save one change — `PATCH /notifications/settings`: a time, or `null` when cleared.
+   * Never a zone. The field shows the new value while the call runs and goes back if it
    * rejects.
    */
   onChange: (patch: NotificationSettingsPatch) => Promise<unknown> | void;
-  /** The zone shown, and the one the server applies, while `timezone` is `null`.
-   *  Default `"Europe/Zurich"`, every app's (decision 6). */
+  /** The zone named while neither `zone` nor `timezone` names one: the one the server
+   *  applies. Default `"Europe/Zurich"`, every app's. */
   fallbackZone?: string;
   /** The app keeps an inbox, and the description says a held push still reaches it. */
   inbox?: boolean;
@@ -43,30 +54,32 @@ export interface QuietHoursSettingProps extends Omit<ComponentPropsWithRef<"div"
   labels?: LabelOverride<NotificationsLabels>;
 }
 
-type QuietField = "quiet_hours_start" | "quiet_hours_end" | "timezone";
+type QuietField = "quiet_hours_start" | "quiet_hours_end";
 
 /**
  * Quiet hours (docs/notifications-harmonization.md §2.4, §2.6, §4.2): a window of local
  * times in the account's zone, which may cross midnight, when no push of a machine-sent
- * type is sent. A held push is dropped, not delayed; the inbox row and the mail go as
- * usual. keksdose's block, as a card of its own.
+ * type is sent. A held push is dropped — or, with `held` (0.46, §10.4), sent when the
+ * window ends; the inbox row and the mail go as usual. keksdose's block, as a card of its
+ * own.
+ *
+ * **0.46 (§10.3, amended 2026-10-20, Marcel): the zone is the account's, automatic
+ * only** — the zone of the device last used, else `Europe/Zurich`. The card names it
+ * read-only and never sends one; there is no picker and no "Use it".
  *
  * - **Two times**, each saved as it is entered; a cleared time sends `null`. While only
  *   one is set the card says so: the window fails open until both are.
- * - **The zone** shows while a time is set. The first time entered while the account has
- *   none sends this device's zone with it, so "22:00" means the person's 22:00
- *   (keksdose `notifications-card.tsx:288-292`). With none stored, the card shows
- *   `fallbackZone` — the zone the server then applies — never the device's (keksdose's
- *   card showed the device's zone while its server applied UTC).
- * - **"This device is in …"** with "Use it" when the device's zone is not the one in
- *   effect. Never written on its own: a zone is written by a person's pick (§2.6).
+ * - **The zone** shows while a time is set: `zone`, else the deprecated `timezone`, else
+ *   `fallbackZone`.
  *
  * Under a write lock the fields are `commit` controls exempt from billing.
  */
 export function QuietHoursSetting({
   start,
   end,
-  timezone,
+  timezone = null,
+  zone,
+  held = false,
   onChange,
   fallbackZone = DEFAULT_FALLBACK_ZONE,
   inbox = false,
@@ -77,7 +90,7 @@ export function QuietHoursSetting({
   ...rest
 }: QuietHoursSettingProps) {
   const labels = useNotificationsLabels(labelsProp);
-  const overlay = useWriteOverlay<string | null>(`${start}|${end}|${timezone}`);
+  const overlay = useWriteOverlay<string | null>(`${start}|${end}`);
   const [failure, setFailure] = useState<ReactNode>(null);
   const mounted = useMounted();
   const id = useId();
@@ -86,9 +99,7 @@ export function QuietHoursSetting({
     overlay.has(field) ? (overlay.get(field) ?? null) : server;
   const startShown = shown("quiet_hours_start", start);
   const endShown = shown("quiet_hours_end", end);
-  const zoneShown = shown("timezone", timezone);
-  const effectiveZone = zoneShown ?? fallbackZone;
-  const device = deviceTimeZone();
+  const accountZone = (zone === undefined ? timezone : zone) ?? fallbackZone;
 
   const save = (patch: NotificationSettingsPatch) => {
     const fields = Object.keys(patch) as QuietField[];
@@ -109,9 +120,7 @@ export function QuietHoursSetting({
   const saveTime = (field: "quiet_hours_start" | "quiet_hours_end", value: string) => {
     const next = value || null;
     if (next === shown(field, field === "quiet_hours_start" ? start : end)) return;
-    const patch: NotificationSettingsPatch = { [field]: next };
-    if (next && zoneShown === null) patch.timezone = device;
-    save(patch);
+    save({ [field]: next });
   };
 
   const anySet = Boolean(startShown || endShown);
@@ -121,7 +130,7 @@ export function QuietHoursSetting({
     <Card {...rest} className={cn("p-4 space-y-3", className)}>
       <div>
         <SettingsCardTitle>{labels.quietTitle}</SettingsCardTitle>
-        <div className={CARD_DESCRIPTION_CLASS}>{labels.quietDescription(inbox)}</div>
+        <div className={CARD_DESCRIPTION_CLASS}>{labels.quietDescription(inbox, held)}</div>
       </div>
       <div className="flex flex-wrap items-end gap-3">
         <TimeInput
@@ -149,35 +158,9 @@ export function QuietHoursSetting({
         </p>
       )}
       {anySet && (
-        <div className="space-y-2">
-          <TimeZoneSelect
-            id={`${id}-zone`}
-            value={effectiveZone}
-            disabled={disabled}
-            commit={COMMIT_EXCEPT_BILLING}
-            onChange={(zone) => save({ timezone: zone })}
-            className="max-w-72"
-            labels={labelsProp}
-          />
-          {device !== effectiveZone && (
-            <div className="flex flex-wrap items-center gap-x-2 gap-y-1">
-              <span id={`${id}-device`} className={CARD_DESCRIPTION_CLASS}>
-                {labels.deviceZone(zoneName(device, labels.regions))}
-              </span>
-              <Button
-                type="button"
-                size="sm"
-                variant="link"
-                disabled={disabled}
-                commit={COMMIT_EXCEPT_BILLING}
-                aria-describedby={`${id}-device`}
-                onClick={() => save({ timezone: device })}
-              >
-                {labels.useDeviceZone}
-              </Button>
-            </div>
-          )}
-        </div>
+        <p className={CARD_DESCRIPTION_CLASS} data-quiet-zone="">
+          {labels.quietZone(zoneName(accountZone, labels.regions))}
+        </p>
       )}
       <FailureLine>{failure}</FailureLine>
     </Card>

package/src/notifications/time-zone-select.tsx

@@ -10,8 +10,8 @@ import type { NotificationRegionLabels, NotificationsLabels } from "./notificati
 
 /**
  * This device's IANA zone ("Europe/Zurich"), or `"UTC"` where the runtime names none —
- * the zone quiet hours are entered in the first time (§2.6), and the one the card offers
- * when it differs from the account's.
+ * the zone `useDeviceZoneReport` reports, which becomes the account's (§10.3, automatic
+ * only).
  */
 export function deviceTimeZone(): string {
   try {
@@ -40,6 +40,7 @@ function cityOf(rest: string): string {
  * rather than trailing the last group as if it were Pacific. `current` is kept even when
  * the runtime does not list it (an old alias such as "Europe/Kiev"): a picker without its
  * own value would show an empty field.
+ * @deprecated 0.46 — the zone is automatic (§10.3, amended 2026-10-20), no app picks one; removed in 0.47.
  */
 export function timeZoneOptions(
   current: string,
@@ -73,6 +74,7 @@ export function zoneName(zone: string, regions: NotificationRegionLabels): strin
   return `${regionName(regions, region) ?? region} / ${cityOf(zone.slice(slash + 1))}`;
 }
 
+/** @deprecated 0.46 — the zone is automatic (§10.3, amended 2026-10-20), no app picks one; removed in 0.47. */
 export interface TimeZoneSelectProps {
   /** The IANA zone. Not clearable: a zone can be changed, never emptied. */
   value: string;
@@ -95,6 +97,7 @@ export interface TimeZoneSelectProps {
  * a search box instead of a 400-row wheel. Rows are the city under its region, the region
  * in the kit's words (`labels.regions`); a zone with no region first; a stored zone the
  * runtime does not list is kept. On the kit's {@link InlineEntityCombobox}.
+ * @deprecated 0.46 — the zone is automatic (§10.3, amended 2026-10-20), no app picks one; removed in 0.47.
  */
 export function TimeZoneSelect({
   value,

package/src/notifications/use-push-device.ts

@@ -2,6 +2,11 @@ import { useCallback, useEffect, useRef, useState } from "react";
 
 import { useMediaQuery } from "../hooks/use-media-query";
 import { httpStatusOf } from "../auth/auth-errors";
+import { PUSH_SUBSCRIPTION_CHANGED, keyBytes, pushSubscriptionInput as inputOf } from "./push-worker";
+import type { PushSubscriptionInput } from "./push-worker";
+
+export { PUSH_SUBSCRIPTION_CHANGED };
+export type { PushSubscriptionInput };
 
 /**
  * This browser's Web Push subscription for the signed-in account
@@ -34,13 +39,6 @@ export class PushDeviceError extends Error {
   }
 }
 
-/** What `register` sends: `POST /notifications/devices` (§3.5). */
-export interface PushSubscriptionInput {
-  endpoint: string;
-  keys: { p256dh: string; auth: string };
-  user_agent: string | null;
-}
-
 export interface UsePushDeviceOptions {
   /** `GET /notifications/push-key` → its `key`; `""` when push is off on the server. */
   pushKey: () => Promise<string>;
@@ -92,14 +90,15 @@ export interface PushDevice {
   sendTest: () => Promise<{ sent: number }>;
 }
 
-/**
- * The window event every mounted {@link usePushDevice} re-reads its state on. Fired by
- * every enable and disable, and by `PushDevicesSetting` when it removes this device — so
- * an app's own card on the same hook (keksdose's check-up) stays in step. The hook that
- * fires it does not re-read: it knows what it changed. Namespaced for the kit;
- * keksdose's was `"keksdose:push-subscription-changed"`.
+/*
+ * PUSH_SUBSCRIPTION_CHANGED (push-worker.ts): the window event every mounted
+ * {@link usePushDevice} re-reads its state on. Fired by every enable and disable, and by
+ * `PushDevicesSetting` when it removes this device — so an app's own card on the same
+ * hook (keksdose's check-up) stays in step. The hook that fires it does not re-read: it
+ * knows what it changed. Since 0.46 also the message a service worker posts after a
+ * rotated subscription was re-registered (`handlePushSubscriptionChange`). Namespaced
+ * for the kit; keksdose's was `"keksdose:push-subscription-changed"`.
  */
-export const PUSH_SUBSCRIPTION_CHANGED = "eifi1:push-subscription-changed";
 
 /** Tell every {@link usePushDevice} that this browser's subscription changed. */
 export function notifyPushSubscriptionChanged(): void {
@@ -151,25 +150,6 @@ async function activeRegistration(): Promise<ServiceWorkerRegistration> {
   return within(navigator.serviceWorker.ready, READY_TIMEOUT_MS, "no_service_worker");
 }
 
-/** A VAPID public key (base64url) as the bytes `PushManager.subscribe` wants. */
-function keyBytes(key: string): Uint8Array<ArrayBuffer> {
-  const base64 = key.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (key.length % 4)) % 4);
-  const raw = atob(base64);
-  const bytes = new Uint8Array(new ArrayBuffer(raw.length));
-  for (let i = 0; i < raw.length; i++) bytes[i] = raw.charCodeAt(i);
-  return bytes;
-}
-
-/** A subscription's register body, or `null` when the browser handed back an incomplete
- *  one. */
-function inputOf(subscription: PushSubscription): PushSubscriptionInput | null {
-  const json = subscription.toJSON();
-  const p256dh = json.keys?.p256dh;
-  const auth = json.keys?.auth;
-  if (!json.endpoint || !p256dh || !auth) return null;
-  return { endpoint: json.endpoint, keys: { p256dh, auth }, user_agent: navigator.userAgent || null };
-}
-
 const defaultEndpointTaken = (error: unknown) => httpStatusOf(error) === 409;
 
 /**
@@ -289,11 +269,18 @@ export function usePushDevice(options: UsePushDeviceOptions): PushDevice {
     const heard = () => {
       if (!announcing.current) void sync();
     };
+    // The worker's word after it re-registered a rotated subscription (0.46).
+    const fromWorker = (event: MessageEvent) => {
+      if ((event.data as { type?: unknown } | null)?.type === PUSH_SUBSCRIPTION_CHANGED) void sync();
+    };
+    const worker = navigator.serviceWorker as ServiceWorkerContainer | undefined;
     void sync();
     window.addEventListener(PUSH_SUBSCRIPTION_CHANGED, heard);
+    worker?.addEventListener?.("message", fromWorker);
     return () => {
       cancelled = true;
       window.removeEventListener(PUSH_SUBSCRIPTION_CHANGED, heard);
+      worker?.removeEventListener?.("message", fromWorker);
     };
   }, [supported]);
 

package/src/offline/local-first.ts

@@ -0,0 +1,76 @@
+import { isTransientRefreshFailure } from "../lib/session-refresh";
+
+/*
+ * The leaf utilities of local-first (docs/local-first-harmonization.md §2.3, 0.46): what a
+ * page and a sync engine both need, with no store behind them. One module that both
+ * `@eifi1/ui-kit/offline` and `@eifi1/ui-kit/sync` export, so `/sync` never loads
+ * `/offline`'s TanStack and idb-keyval peers, and `/offline` never loads Dexie. It imports
+ * no package at all (packaging-contract.test.ts holds that).
+ */
+
+/**
+ * An `updated_at` that wins Last-Write-Wins over `previous`: now, or one millisecond past
+ * `previous` when that is not behind this clock (keksdose's sync-client.ts:639-643).
+ *
+ * `/sync` keeps the server's row when it is STRICTLY newer, comparing this device's clock
+ * with the server's. A row the server just wrote carries the server's time, so an edit
+ * stamped by a clock a second slow would lose and come straight back. The millisecond is
+ * enough although the server keeps microseconds: `Date.parse` truncates them.
+ */
+export function stampAfter(previous: unknown): string {
+  const now = Date.now();
+  const prior = typeof previous === "string" ? Date.parse(previous) : Number.NaN;
+  return new Date(Number.isFinite(prior) && prior >= now ? prior + 1 : now).toISOString();
+}
+
+/**
+ * The connection, not the server, failed: the request had no answer (an axios-like error
+ * without `response`, or `fetch`'s `TypeError`), or the session refresh marked a 401 as
+ * passing because the server was out of reach ({@link isTransientRefreshFailure}). A real
+ * HTTP answer — a 4xx or a 5xx — is never offline: the caller must see it.
+ */
+export function isOfflineError(err: unknown): boolean {
+  if (isTransientRefreshFailure(err)) return true;
+  if (typeof err !== "object" || err === null) return false;
+  const bag = err as { isAxiosError?: unknown; response?: unknown };
+  if (bag.isAxiosError === true || "response" in bag) return bag.response == null;
+  return err instanceof TypeError;
+}
+
+/**
+ * Read from the server, and from the device's copy only when the connection failed
+ * ({@link isOfflineError}); a 4xx or 5xx still throws. `onOnline` gets the server's answer
+ * before it is returned (to refresh the copy, say); a throw from it counts as a failure of
+ * the online path. The plain form of keksdose's net.ts:58, without its sealed-household
+ * and cold-start branches (those stay keksdose's).
+ */
+export async function readLocalFirst<T>(
+  online: () => Promise<T>,
+  offline: () => Promise<T>,
+  onOnline?: (result: T) => void | Promise<void>,
+): Promise<T> {
+  try {
+    const result = await online();
+    await onOnline?.(result);
+    return result;
+  } catch (err) {
+    if (!isOfflineError(err)) throw err;
+    return offline();
+  }
+}
+
+/**
+ * Write through the server first (`rest`), and queue the change on the device (`queue`)
+ * only when the connection failed; any other failure throws, nothing queued. Online writes
+ * stay server-stamped (D2). A create mints its id BEFORE calling this and sends it on both
+ * paths, so a REST create that timed out after the server applied it is not created twice
+ * (D16).
+ */
+export async function writeLocalFirst<T>(rest: () => Promise<T>, queue: () => Promise<T>): Promise<T> {
+  try {
+    return await rest();
+  } catch (err) {
+    if (!isOfflineError(err)) throw err;
+    return queue();
+  }
+}

package/src/offline/query-persistence.ts

@@ -71,6 +71,14 @@ export interface QueryPersistenceOptions {
   storage?: QueryPersistenceStorage;
   /** Default 1000 ms, as keksdose. */
   throttleTime?: number;
+  /**
+   * 0.46 (kastlan K1): whether paused mutations are written with the cache. Default `true`
+   * (keksdose: an offline write waits in TanStack's queue and is sent after a reload).
+   * `false` keeps every mutation off the disk, and drops any an older build wrote on
+   * restore — for an app that queues offline writes in its own outbox (kastlan's Dexie
+   * outbox), instead of overriding `dehydrateOptions` by hand.
+   */
+  persistMutations?: boolean;
 }
 
 /**
@@ -112,6 +120,50 @@ const idbStorage: QueryPersistenceStorage = {
   keys: () => keys(),
 };
 
+export interface RemoveStaleQueryCopiesOptions {
+  /** Default: IndexedDB (idb-keyval), the store {@link createQueryPersistence} writes to. */
+  storage?: QueryPersistenceStorage;
+  /** One key to spare whatever its age — the signed-in account's own
+   *  (`QueryPersistence.removeStale` passes its key). */
+  keep?: string;
+}
+
+/**
+ * 0.46 (kastlan K2): deletes this app's persisted query caches (`<app>-query-cache-…`)
+ * older than `maxAge`, with no persistence at hand — for the sign-in page, where no
+ * account is known. A session that ended with no user known (a refresh token refused at
+ * boot) cannot name its key for `clear`; this sweeps its copy once it is stale, without
+ * waiting for someone's next sign-in. Other apps' keys, other stores' keys and fresh
+ * caches stay; an unreadable one is stale. Never throws.
+ * {@link QueryPersistence.removeStale} is this with `keep` = its own key.
+ */
+export async function removeStaleQueryCopies(
+  app: string,
+  maxAge: number,
+  { storage = idbStorage, keep }: RemoveStaleQueryCopiesOptions = {},
+): Promise<void> {
+  const prefix = `${app}-query-cache-`;
+  try {
+    const now = Date.now();
+    for (const k of await storage.keys()) {
+      if (typeof k !== "string" || !k.startsWith(prefix) || k === keep) continue;
+      let timestamp = 0;
+      try {
+        const raw = await storage.getItem(k);
+        const parsed: unknown = raw ? JSON.parse(raw) : null;
+        if (parsed && typeof parsed === "object" && typeof (parsed as PersistedClient).timestamp === "number") {
+          timestamp = (parsed as PersistedClient).timestamp;
+        }
+      } catch {
+        /* unreadable: stale */
+      }
+      if (now - timestamp > maxAge) await storage.removeItem(k);
+    }
+  } catch {
+    /* best-effort */
+  }
+}
+
 /**
  * True when `data` still means the same thing after JSON.stringify and JSON.parse —
  * keksdose's `isCacheSafe` (query-client.ts:165). Class instances, Map/Set/Date/Blob, a
@@ -162,6 +214,7 @@ export function createQueryPersistence({
   maxAge,
   storage = idbStorage,
   throttleTime = 1000,
+  persistMutations = true,
 }: QueryPersistenceOptions): QueryPersistence {
   const prefix = `${app}-query-cache-`;
   const key = `${prefix}${user}${company === undefined || company === null || company === "" ? "" : `-${company}`}`;
@@ -204,9 +257,9 @@ export function createQueryPersistence({
   };
 
   /** The write side for mutations: TanStack's default (paused ones), minus any whose
-   *  variables carry a scrubbed field (S6). */
+   *  variables carry a scrubbed field (S6); none at all with `persistMutations: false`. */
   const shouldDehydrateMutation = (mutation: { state: { isPaused: boolean; variables?: unknown } }): boolean =>
-    mutation.state.isPaused && !carriesScrubbed(mutation.state.variables);
+    persistMutations && mutation.state.isPaused && !carriesScrubbed(mutation.state.variables);
 
   const withScrubbedData = (entry: unknown): unknown => {
     const query = entry as { state?: { data?: unknown } };
@@ -239,7 +292,7 @@ export function createQueryPersistence({
         timestamp,
         buster: stored,
         clientState: {
-          mutations: Array.isArray(clientState.mutations)
+          mutations: persistMutations && Array.isArray(clientState.mutations)
             ? clientState.mutations.filter(
                 (m) => !carriesScrubbed((m as { state?: { variables?: unknown } } | null)?.state?.variables),
               )
@@ -291,27 +344,7 @@ export function createQueryPersistence({
     }
   };
 
-  const removeStale = async () => {
-    try {
-      const now = Date.now();
-      for (const k of await storage.keys()) {
-        if (typeof k !== "string" || !k.startsWith(prefix) || k === key) continue;
-        let timestamp = 0;
-        try {
-          const raw = await storage.getItem(k);
-          const parsed: unknown = raw ? JSON.parse(raw) : null;
-          if (parsed && typeof parsed === "object" && typeof (parsed as PersistedClient).timestamp === "number") {
-            timestamp = (parsed as PersistedClient).timestamp;
-          }
-        } catch {
-          /* unreadable: stale */
-        }
-        if (now - timestamp > maxAge) await storage.removeItem(k);
-      }
-    } catch {
-      /* best-effort */
-    }
-  };
+  const removeStale = () => removeStaleQueryCopies(app, maxAge, { storage, keep: key });
 
   return {
     key,

package/src/offline/service-worker-updates.ts

@@ -0,0 +1,81 @@
+import { useSyncExternalStore } from "react";
+
+/**
+ * vite-plugin-pwa's `registerSW` from `virtual:pwa-register` (`registerType: "prompt"`) —
+ * the app passes it in, since a virtual module is the app's build's, not the kit's. It
+ * answers the `updateSW(reloadPage)` function.
+ */
+export type RegisterServiceWorker = (options: {
+  onNeedRefresh?: () => void;
+  onOfflineReady?: () => void;
+}) => (reloadPage?: boolean) => Promise<void>;
+
+/** What {@link createServiceWorkerUpdates} answers: one store per app, a module constant. */
+export interface ServiceWorkerUpdates {
+  /** Registers the service worker — once, however often it is called. Call it at start,
+   *  before the router renders, so the sign-in pages get the offline shell too. */
+  start: () => void;
+  /** Whether a new version waits. */
+  needRefresh: () => boolean;
+  /** For `useSyncExternalStore`. */
+  subscribe: (listener: () => void) => () => void;
+  /** Activates the waiting version and reloads (`updateSW(true)`). Before `start`, nothing. */
+  reload: () => void;
+  /** The person closed the prompt: the version keeps waiting, the prompt stays down. */
+  dismiss: () => void;
+}
+
+/**
+ * 0.46 (kastlan K3, docs/local-first-harmonization.md §1.5 D8): the service worker
+ * registered ONCE AT START, and its "a new version waits" state as a small store the
+ * prompt reads wherever it lives. vite-plugin-pwa's `useRegisterSW` registers when the
+ * component that calls it mounts: an app whose {@link PwaUpdatePrompt} sits in its
+ * signed-in shell (it reads the tour state, the route) would register only after sign-in,
+ * and the sign-in pages would lose the offline shell on a first visit.
+ *
+ * ```ts
+ * // shared/pwa/sw-updates.ts
+ * import { registerSW } from "virtual:pwa-register";
+ * export const swUpdates = createServiceWorkerUpdates(registerSW);
+ * // main.tsx, before render:   swUpdates.start();
+ * // the shell:                 <PwaUpdatePrompt {...useServiceWorkerUpdate(swUpdates)} hold={tourRunning} />
+ * ```
+ */
+export function createServiceWorkerUpdates(register: RegisterServiceWorker): ServiceWorkerUpdates {
+  let waiting = false;
+  let update: ((reloadPage?: boolean) => Promise<void>) | null = null;
+  const listeners = new Set<() => void>();
+  const emit = () => listeners.forEach((listener) => listener());
+  const set = (value: boolean) => {
+    if (waiting === value) return;
+    waiting = value;
+    emit();
+  };
+  return {
+    start: () => {
+      if (update) return;
+      update = register({ onNeedRefresh: () => set(true) });
+    },
+    needRefresh: () => waiting,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    reload: () => {
+      void update?.(true);
+    },
+    dismiss: () => set(false),
+  };
+}
+
+/** {@link PwaUpdatePrompt}'s props from the store: `needRefresh`, `onReload`, `onDismiss`. */
+export function useServiceWorkerUpdate(updates: ServiceWorkerUpdates): {
+  needRefresh: boolean;
+  onReload: () => void;
+  onDismiss: () => void;
+} {
+  const needRefresh = useSyncExternalStore(updates.subscribe, updates.needRefresh, () => false);
+  return { needRefresh, onReload: updates.reload, onDismiss: updates.dismiss };
+}

package/src/offline.ts

@@ -6,17 +6,21 @@
 // `@tanstack/react-query-persist-client`, `@tanstack/query-async-storage-persister` and
 // `idb-keyval` — optional peers for that reason. NOT re-exported from the main barrel, which
 // would make them everyone's install; the packaging contract test holds that line.
-export { createQueryPersistence, DEFAULT_SCRUB_FIELDS, isCacheSafe } from "./offline/query-persistence";
+export { createQueryPersistence, DEFAULT_SCRUB_FIELDS, isCacheSafe, removeStaleQueryCopies } from "./offline/query-persistence";
 export type {
   QueryPersistence,
   QueryPersistenceOptions,
   QueryPersistenceStorage,
+  RemoveStaleQueryCopiesOptions,
   ScrubField,
 } from "./offline/query-persistence";
 export { SignOutPendingDialog, DEFAULT_SIGN_OUT_PENDING_DIALOG_LABELS } from "./offline/sign-out-pending-dialog";
 export type { SignOutPendingDialogProps, SignOutPendingDialogLabels } from "./offline/sign-out-pending-dialog";
 export { PwaUpdatePrompt, DEFAULT_PWA_UPDATE_PROMPT_LABELS } from "./offline/pwa-update-prompt";
 export type { PwaUpdatePromptProps, PwaUpdatePromptLabels } from "./offline/pwa-update-prompt";
+// 0.46 (kastlan K3): the service worker registered once at start, its update state as a store.
+export { createServiceWorkerUpdates, useServiceWorkerUpdate } from "./offline/service-worker-updates";
+export type { RegisterServiceWorker, ServiceWorkerUpdates } from "./offline/service-worker-updates";
 export {
   SharedComputerChoice,
   DEFAULT_SHARED_COMPUTER_LABELS,
@@ -24,3 +28,5 @@ export {
   setSharedComputer,
 } from "./offline/shared-computer";
 export type { SharedComputerChoiceProps, SharedComputerLabels, SharedComputerStorage } from "./offline/shared-computer";
+// 0.46 (§2.3): the leaf utilities, shared with `@eifi1/ui-kit/sync` from one module that imports no peer.
+export { isOfflineError, readLocalFirst, stampAfter, writeLocalFirst } from "./offline/local-first";

package/src/push-worker.ts

@@ -0,0 +1,25 @@
+// `@eifi1/ui-kit/push-worker` — the service worker's half of Web Push (0.46,
+// docs/notifications-harmonization.md §10.6 rule 5): re-registering a subscription the browser
+// rotated. A worker bundle imports from here, never from the main barrel, which reaches React
+// and the DOM components:
+//
+//     // sw.ts
+//     import { handlePushSubscriptionChange } from "@eifi1/ui-kit/push-worker";
+//
+// Worker-safe: this entry reaches no package and no module but src/notifications/push-worker.ts
+// (packaging-contract.test.ts, scripts/check-module-graph.mjs, scripts/verify-package.mjs).
+// The main barrel keeps re-exporting the same names, so an existing import keeps working.
+export {
+  PUSH_SUBSCRIPTION_CHANGED,
+  handlePushSubscriptionChange,
+  pushSubscriptionInput,
+  resubscribeAfterChange,
+} from "./notifications/push-worker";
+export type {
+  PushReplaceInput,
+  PushResubscribeOutcome,
+  PushSubscriptionChangeEventLike,
+  PushSubscriptionChangeOptions,
+  PushSubscriptionInput,
+  PushWorkerScope,
+} from "./notifications/push-worker";