@forgeroute/ui 0.4.78 → 0.4.79

package/types/forgeroute-ui-offline.d.ts

@@ -0,0 +1,887 @@
+import * as i0 from "@angular/core";
+import { EnvironmentProviders, InjectionToken } from "@angular/core";
+import { Subject } from "rxjs";
+import { HttpContextToken, HttpInterceptorFn } from "@angular/common/http";
+import { UiLabelsService } from "@forgeroute/ui";
+export type MutationStatus = 'pending' | 'syncing' | 'failed' | 'conflict';
+export type MutationErrorKind = 'conflict' | 'rejected' | 'auth' | 'server' | 'network' | 'timeout' | 'dependency';
+export interface MutationError {
+  kind: MutationErrorKind;
+  status?: number;
+  message: string;
+}
+export interface OfflineMutation {
+  id: string;
+  seq: number;
+  userId: string;
+  /** The Idempotency-Key header of the original request; re-sent unchanged on every replay. */
+  key: string;
+  method: string;
+  url: string;
+  body: unknown;
+  headers?: Record<string, string>;
+  label: string;
+  entityType?: string;
+  entityId?: string;
+  createdAt: number;
+  status: MutationStatus;
+  claimOwner?: string;
+  claimAt?: number;
+  attempts: number;
+  nextAttemptAt?: number;
+  lastError?: MutationError;
+  /**
+   * Set on a queued POST to a collection whose body had no id of its own: the client-made id handed out in the synthetic 202 (equals `id`).
+   * Later saved changes may refer to it; after this row is delivered it is mapped to the server's real id (store `idmap`).
+   */
+  tempId?: string;
+  /** Ids of the queued create rows whose temp id this change refers to (URL, query or body), set when the change was saved. */
+  dependsOn?: string[];
+  /** The temp ids behind `dependsOn`, same order (needed after the create row is gone to find its `idmap` entry). */
+  dependsOnTempIds?: string[];
+}
+export type NewMutation = Omit<OfflineMutation, 'seq'>;
+export interface CachedEntry {
+  /** Composite primary key: `<userId>::<url key>`. */
+  key: string;
+  urlKey: string;
+  userId: string;
+  data: unknown;
+  cachedAt: number;
+  expiresAt: number;
+}
+/** Maps a temp id to the real id the server gave the record. Key `<userId>:<tempId>`; kept 7 days. */
+export interface IdMapEntry {
+  key: string;
+  userId: string;
+  tempId: string;
+  /** Always text; `numeric` tells that the server's id was a number (so a JSON body gets a number back). */
+  realId: string;
+  numeric?: boolean;
+  createdAt: number;
+  expiresAt: number;
+}
+export declare const IDMAP_TTL_MS: number;
+export interface MutationCounts {
+  pending: number;
+  syncing: number;
+  failed: number;
+  conflict: number;
+}
+/** A claim older than this in status `syncing` belongs to a tab that died mid-send and may be taken over. */
+export declare const STALE_CLAIM_MS = 60000;
+/** IndexedDB, or null when the browser has none / refuses access (some privacy modes throw on the property read). */
+export declare const OFFLINE_IDB_FACTORY: InjectionToken<IDBFactory | null>;
+/** IndexedDB is missing, blocked or failed to open: nothing can be saved on this device. */
+export declare class StorageUnavailableError extends Error {
+  constructor(message?: string);
+}
+/** The user already has `maxQueue` saved changes. */
+export declare class QueueFullError extends Error {
+  readonly limit: number;
+  constructor(limit: number);
+}
+export declare function isQuotaError(e: unknown): boolean;
+/** True when `claim` may take the row: pending, a failed row whose failure was transient, or a `syncing` row whose claim went stale. */
+export declare function isClaimable(row: OfflineMutation, now: number): boolean;
+/**
+ * Thin promise wrapper over IndexedDB: the queued writes (`mutations`) and the per-user device copy of GET answers (`responses`).
+ * Every row and cache entry carries its `userId`; reads and deletes are always scoped to a user. If IndexedDB cannot be used,
+ * `available()` is false and callers must refuse to queue (never a fake success).
+ */
+export declare class OfflineStore {
+  private readonly cfg;
+  private readonly factory;
+  /** Emits after every write to the saved changes (add, claim, update, delete, clear); other tabs are told by OfflineSupportService. */
+  readonly mutated$: Subject<void>;
+  private db;
+  private opening;
+  private initPromise;
+  private ready;
+  available(): boolean;
+  /** Opens the database. Never rejects: on failure `available()` stays false (and a later `init()` tries again). */
+  init(): Promise<void>;
+  private doInit;
+  /**
+   * Saves a new change. If this user already has a row with the same idempotency `key` that row is returned instead (a double click that
+   * re-used the key must not queue twice). Rejects with QueueFullError, StorageUnavailableError or the storage error (e.g. QuotaExceededError).
+   */
+  addMutation(row: NewMutation): Promise<OfflineMutation>;
+  /**
+   * Atomically takes a row for sending: only if it is pending, failed with a transient error, or `syncing` with a claim older than 60 s.
+   * Returns the claimed row, or null when it is gone or somebody else holds a live claim.
+   */
+  claim(id: string, owner: string, now?: number): Promise<OfflineMutation | null>;
+  /** Merges `patch` into the row (an `undefined` value removes the field). With `ifOwner` it only applies while that owner still holds the claim. */
+  update(id: string, patch: Partial<OfflineMutation>, opts?: {
+    ifOwner?: string;
+  }): Promise<OfflineMutation | null>;
+  /**
+   * The user's "Retry": puts one row (any status) back to pending with 0 attempts, in ONE transaction so a claim taken in between cannot be overwritten.
+   * Returns the reset row, or null when the row is missing, belongs to another user, or is being sent right now (live claim).
+   */
+  resetForRetry(id: string, userId: string, now?: number): Promise<OfflineMutation | null>;
+  get(id: string): Promise<OfflineMutation | null>;
+  /** Deletes the row; with `ifOwner` only while that owner still holds the claim. Returns whether a row was deleted. */
+  delete(id: string, opts?: {
+    ifOwner?: string;
+  }): Promise<boolean>;
+  /** The user's rows in send order (seq, then createdAt). */
+  list(userId: string): Promise<OfflineMutation[]>;
+  count(userId: string): Promise<number>;
+  countsByStatus(userId: string): Promise<MutationCounts>;
+  /** Deletes only the saved changes of this user (their device copy of GET answers stays). */
+  deleteMutations(userId: string): Promise<number>;
+  /** Deletes this user's saved changes AND device copy. Never touches another user's data. */
+  clearUser(userId: string): Promise<void>;
+  /** Deletes everything for every user (rows, device copy). Only for an explicit, confirmed full reset. */
+  clearAll(): Promise<void>;
+  /** Saves (or overwrites: a replayed create gives the same answer) the real id for a temp id. Rejects when the write fails. */
+  putIdMapping(userId: string, tempId: string, realId: string | number, now?: number): Promise<IdMapEntry>;
+  /** The user's real id for `tempId`, or null (missing, expired, or somebody else's). */
+  getIdMapping(userId: string, tempId: string, now?: number): Promise<IdMapEntry | null>;
+  /** All of the user's unexpired temp id mappings. */
+  listIdMap(userId: string, now?: number): Promise<IdMapEntry[]>;
+  /** Deletes this user's temp id mappings only. */
+  deleteIdMap(userId: string): Promise<number>;
+  /** Removes mappings whose 7 days are over (every user). Returns how many. */
+  purgeExpiredIdMap(now?: number): Promise<number>;
+  /** Stores a GET answer for this user. Returns false when it could not be stored (never throws: the copy is optional). */
+  cacheResponse(key: string, userId: string, data: unknown, ttlMs: number, now?: number): Promise<boolean>;
+  /** The user's stored answer for `key`, or null (missing, expired or belonging to somebody else). */
+  getCached(key: string, userId: string, now?: number): Promise<CachedEntry | null>;
+  /** Removes this user's stored answers whose URL key starts with `prefix`. */
+  invalidatePrefix(prefix: string, userId: string): Promise<number>;
+  /** Deletes the device copy of one user, or of everybody when `userId` is omitted. Saved changes are never touched. */
+  clearCache(userId?: string): Promise<void>;
+  purgeExpired(now?: number): Promise<number>;
+  private evictOldest;
+  private enforceCacheLimit;
+  private ensureReady;
+  private getDb;
+  private openWithRetry;
+  private openOnce;
+  private runTx;
+  static ɵfac: i0.ɵɵFactoryDeclaration<OfflineStore, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/** string = path prefix or substring after the origin is stripped; RegExp is tested on path + query. */
+export type UrlMatcher = string | RegExp;
+export interface QueueRule {
+  pattern: RegExp;
+  methods: readonly string[];
+  /** Plain-words name of the change shown in the pending-changes list (e.g. "Add lot 12"). */
+  label?: (method: string, url: string, body: unknown) => string;
+  entityType?: (url: string) => string | undefined;
+}
+export interface OfflineSupportConfig {
+  /** Only URLs containing this are intercepted. Default '/api/'. */
+  apiPrefix?: string;
+  /** Never touched (auth, public, uploads...). */
+  skip?: readonly UrlMatcher[];
+  /** The signed-in user's id; null = nobody (nothing is queued/cached). Scopes the store. */
+  getUserId: () => string | null;
+  /** ALLOW-LIST mode: only requests matching a rule may be queued offline. Omit for BLOCK-LIST mode (everything may be queued except `blockOffline`). */
+  allowQueue?: readonly QueueRule[];
+  /** Writes that must NEVER be queued (payments, sends...). While offline/unreachable they fail with OfflineBlockedError. */
+  blockOffline?: readonly {
+    pattern: UrlMatcher;
+    message?: string;
+  }[];
+  /** GET endpoints that must never be stored or served from the device copy. */
+  neverCache?: readonly UrlMatcher[];
+  /** Safe extra headers copied onto the queued row and re-sent on replay (never Authorization). */
+  replayHeaders?: readonly string[];
+  /** Cheap authenticated/unauthenticated GET used ONLY while the connection is suspect. null/omitted = no probe. */
+  probe?: {
+    url: string;
+    intervalMs?: number;
+  } | null;
+  /** Client timeouts in ms. Defaults: read 30000, write 60000, long 180000. `long` applies to blob/arraybuffer, FormData, and matchers in `longRequests`. */
+  timeouts?: {
+    read?: number;
+    write?: number;
+    long?: number;
+  };
+  longRequests?: readonly UrlMatcher[];
+  /** Slow detection thresholds. Defaults: slowMs 5000, slowCount 2 within windowMs 60000; single in-flight > stuckMs 8000; recover after quietMs 30000 of fast requests. */
+  slow?: {
+    slowMs?: number;
+    slowCount?: number;
+    windowMs?: number;
+    stuckMs?: number;
+    quietMs?: number;
+  };
+  /** IndexedDB database name. Default 'forgeroute-offline'. */
+  dbName?: string;
+  /** Cache TTLs in ms (default 10 min lists / 30 min details); `ttl(url)` overrides. */
+  cacheTtl?: (url: string) => number;
+  maxQueue?: number;
+  maxAttempts?: number;
+  /**
+   * Reads the id the server gave a record that was created offline, from the 2xx answer of the replayed POST (`body` is the parsed JSON answer,
+   * `undefined` when the answer was empty / not JSON). Used to rewrite later saved changes that point at the client-made temporary id.
+   * Default: `body.id`, else `body.data.id`; a string or a finite number. Return `undefined` when the answer has no id (dependent changes then fail
+   * with kind `dependency` instead of being sent with a wrong id).
+   */
+  createdId?: (body: unknown, row: OfflineMutation) => string | number | undefined;
+}
+export declare const OFFLINE_SUPPORT_CONFIG: InjectionToken<OfflineSupportConfig>;
+/** Header the replayer sets on every replayed request; the idempotency and offline interceptors let such requests through untouched. */
+export declare const OFFLINE_REPLAY_HEADER = "X-Offline-Replay";
+export declare const IDEMPOTENCY_HEADER = "Idempotency-Key";
+/** Response header on an answer served from the device copy; the value is the `cachedAt` time in ms. */
+export declare const FROM_CACHE_HEADER = "X-From-Offline-Cache";
+export interface ResolvedSlowConfig {
+  slowMs: number;
+  slowCount: number;
+  windowMs: number;
+  stuckMs: number;
+  quietMs: number;
+}
+/** The config with every default filled in. */
+export interface ResolvedOfflineConfig {
+  apiPrefix: string;
+  skip: readonly UrlMatcher[];
+  getUserId: () => string | null;
+  allowQueue: readonly QueueRule[] | null;
+  blockOffline: readonly {
+    pattern: UrlMatcher;
+    message?: string;
+  }[];
+  neverCache: readonly UrlMatcher[];
+  replayHeaders: readonly string[];
+  probe: {
+    url: string;
+    intervalMs: number;
+  } | null;
+  timeouts: {
+    read: number;
+    write: number;
+    long: number;
+  };
+  longRequests: readonly UrlMatcher[];
+  slow: ResolvedSlowConfig;
+  dbName: string;
+  cacheTtl: ((url: string) => number) | null;
+  maxQueue: number;
+  maxAttempts: number;
+  createdId: (body: unknown, row: OfflineMutation) => string | number | undefined;
+}
+/** Default for `createdId`: `body.id`, else `body.data.id` (string or finite number), otherwise undefined. */
+export declare function defaultCreatedId(body: unknown): string | number | undefined;
+export declare const DEFAULT_LIST_TTL_MS: number;
+export declare const DEFAULT_DETAIL_TTL_MS: number;
+export declare function resolveConfig(cfg: OfflineSupportConfig): ResolvedOfflineConfig;
+/** Path + query of a URL with the origin removed ('https://x.test/api/a?b=1' -> '/api/a?b=1'). Relative URLs are returned as they are. */
+export declare function pathAndQuery(url: string): string;
+/** Path only (no query) of a URL with the origin removed. */
+export declare function pathOnly(url: string): string;
+/** True when `matcher` matches `url`: a string anywhere in the path + query, a RegExp tested on path + query (a global/sticky RegExp is not made stateful). */
+export declare function matchesUrl(url: string, matcher: UrlMatcher): boolean;
+export declare function matchesAny(url: string, matchers: readonly UrlMatcher[]): boolean;
+export declare function isMutationMethod(method: string): boolean;
+/** First id-looking path segment (digits or UUID) with the segment before it as the entity type: '/api/lots/42/notes' -> { entityType: 'lots', entityId: '42' }. */
+export declare function deriveEntity(url: string): {
+  entityType?: string;
+  entityId?: string;
+};
+/** The path prefix whose stored GET copies a successful write may have made stale: the path without trailing id segments ('/api/contacts/12' -> '/api/contacts'). */
+export declare function invalidationPrefix(url: string): string;
+/** `resolveConfig` memoised per config object (interceptors run on every request). */
+export declare function resolveConfigCached(cfg: OfflineSupportConfig): ResolvedOfflineConfig;
+/** True when the request is one the offline layer looks at: under `apiPrefix` and not matched by `skip`. */
+export declare function isInScope(url: string, cfg: ResolvedOfflineConfig): boolean;
+export declare function lastSegmentIsId(url: string): boolean;
+/**
+ * A v4 UUID. Uses `crypto.randomUUID` when the browser has it (Safari < 15.4 and insecure contexts do not),
+ * then `crypto.getRandomValues`, then `Math.random` as the last resort. Always 36 characters.
+ */
+export declare function generateUuid(): string;
+export type ConnectionState = 'online' | 'slow' | 'unreachable' | 'offline';
+export interface RecordRequestInfo {
+  durationMs: number;
+  ok: boolean;
+  status: number;
+  timedOut?: boolean;
+  method: string;
+  /** Long requests (blob / FormData / `longRequests`) never count as slow. Additive to the documented shape. */
+  long?: boolean;
+}
+/** What made the connection usable again: the browser `online` event / a normal request that got an answer, or the probe. */
+export type RecoveryTrigger = 'online' | 'probe';
+/** Debounce for the browser `online` event (flapping wifi). `offline` is applied at once: queueing is always the safe side. */
+export declare const ONLINE_DEBOUNCE_MS = 300;
+/**
+ * The one answer to "can this device reach the server?": online | slow | unreachable | offline.
+ * Measured from real request timings (works in Safari/Firefox, which have no `navigator.connection`), the browser online/offline events and an
+ * optional probe GET that runs only while the connection is suspect.
+ */
+export declare class ConnectionStateService {
+  private readonly cfg;
+  private readonly win;
+  private readonly browserOnline;
+  private readonly unreachable;
+  private readonly slowFlag;
+  private readonly _slowRequestActive;
+  private readonly _inFlightCount;
+  private readonly _state;
+  private readonly _lastChangeAt;
+  readonly state: import("@angular/core").Signal<ConnectionState>;
+  readonly isOnline: import("@angular/core").Signal<boolean>;
+  readonly isOffline: import("@angular/core").Signal<boolean>;
+  /** Some request has been in flight longer than `slow.stuckMs`. */
+  readonly slowRequestActive: import("@angular/core").Signal<boolean>;
+  readonly inFlightCount: import("@angular/core").Signal<number>;
+  readonly lastChangeAt: import("@angular/core").Signal<number>;
+  /** True while the user should be told "this is taking a while" (a request is stuck or the connection is slow). */
+  readonly slowRequestHint: import("@angular/core").Signal<boolean>;
+  /** Emits when the connection became usable again; the replayer listens to it. */
+  readonly recovered$: Subject<RecoveryTrigger>;
+  private failures;
+  private slowTimes;
+  private quietTimer;
+  private onlineTimer;
+  private probeTimer;
+  private optimisticTimer;
+  private probeInFlight;
+  private readonly inFlight;
+  private nextRequestId;
+  private readonly onWindowOnline;
+  private readonly onWindowOffline;
+  private readonly onFocus;
+  constructor();
+  /** Called by `connectionInterceptor` when a request finished (or failed / timed out). */
+  recordRequest(info: RecordRequestInfo): void;
+  /**
+   * Starts tracking one request; call the returned function when it ends (success, error, timeout or cancel; calling it twice is harmless).
+   * A non-long request still in flight after `slow.stuckMs` turns `slowRequestActive` and the state to `slow`.
+   */
+  beginRequest(options?: {
+    long?: boolean;
+  }): () => void;
+  /**
+   * Asks the probe URL once. Resolves true when it answered with ANY HTTP status (a 401 still proves the server is reachable).
+   * Without a configured probe there is nothing to ask: the answer is what the browser says.
+   */
+  probeNow(): Promise<boolean>;
+  private runProbe;
+  private onProbeSuccess;
+  private handleFailure;
+  private setUnreachable;
+  private clearUnreachable;
+  private stopRecoveryTimers;
+  private markSlow;
+  private scheduleOnline;
+  private cancelOnlineTimer;
+  private setBrowserOnline;
+  private syncFromNavigator;
+  private readNavigatorOnline;
+  private recompute;
+  private teardown;
+  static ɵfac: i0.ɵɵFactoryDeclaration<ConnectionStateService, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/** Tells the UI when what the user sees came from the device copy instead of the server. Tracked per request key (the cache key of the GET). */
+export declare class StaleDataService {
+  private readonly _staleAt;
+  private readonly entries;
+  /** `cachedAt` of the most recent cache-served GET that has not been replaced by a live answer for the same request; null = everything shown is live. */
+  readonly staleAt: import("@angular/core").Signal<number | null>;
+  markStale(cachedAt: number, key?: string): void;
+  /** A live answer arrived for this request: only its own stale mark goes away. */
+  clearKey(key: string): void;
+  /** Forgets every stale mark. */
+  clear(): void;
+  private publish;
+  static ɵfac: i0.ɵɵFactoryDeclaration<StaleDataService, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+export type ReplayTrigger = 'start' | 'online' | 'probe' | 'manual';
+export interface ReplayResult {
+  synced: number;
+  failed: number;
+  conflicts: number;
+  blockedByAuth: boolean;
+}
+/** `navigator.locks`, or null when the browser has none (older Safari) - the replayer then falls back to an in-tab mutex plus a localStorage lease. */
+export declare const OFFLINE_LOCK_MANAGER: InjectionToken<LockManager | null>;
+export type LeaseStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+/** Storage for the lock-less fallback lease: ONE small key holding `{ owner, until }`, never any data. */
+export declare const OFFLINE_LEASE_STORAGE: InjectionToken<LeaseStorage | null>;
+export declare const LEASE_TTL_MS = 30000;
+/** Wait before the next automatic try after `attempts` failed sends: 2 s, 4 s, 8 s ... capped at 5 minutes. */
+export declare function backoffMs(attempts: number): number;
+type Outcome = {
+  action: 'ok';
+  text?: string;
+} | {
+  action: 'dependency';
+} | {
+  action: 'conflict';
+  status: number;
+} | {
+  action: 'rejected';
+  status: number;
+} | {
+  action: 'auth';
+  status: number;
+} | {
+  action: 'retry';
+  kind: Extract<MutationErrorKind, 'server' | 'network' | 'timeout'>;
+  status: number;
+};
+/** Maps what a replayed request ended with to what happens to its row. Anything unknown stays retryable: only a real 4xx answer is final. */
+export declare function classifyReplay(err: unknown): Outcome;
+/**
+ * Sends the signed-in user's saved changes, oldest first, when the connection is back. Safe by construction:
+ * - one run at a time per browser (navigator.locks, or in-tab mutex + localStorage lease), and every row is `claim`ed atomically in IndexedDB;
+ * - the row's own Idempotency-Key is re-sent unchanged, so even a crash after the server answered cannot create a second record;
+ * - 401/403 never touch a row, a permanent 4xx marks the row failed (only the user's Retry sends it again), nothing is ever deleted except
+ *   after a 2xx or the user's own Discard.
+ */
+export declare class OfflineReplayer {
+  private readonly cfg;
+  private readonly store;
+  private readonly http;
+  private readonly connection;
+  private readonly toast;
+  private readonly labels;
+  private readonly locks;
+  private readonly leaseStorage;
+  private readonly owner;
+  private running;
+  private readonly _syncing;
+  private readonly _pendingCount;
+  private readonly _failedCount;
+  private readonly _conflictCount;
+  private readonly _lastSyncAt;
+  private readonly _syncTick;
+  private readonly _authBlocked;
+  private readonly _lastResult;
+  readonly syncing: import("@angular/core").Signal<boolean>;
+  /** Rows waiting to be sent (pending + being sent right now). */
+  readonly pendingCount: import("@angular/core").Signal<number>;
+  readonly failedCount: import("@angular/core").Signal<number>;
+  readonly conflictCount: import("@angular/core").Signal<number>;
+  readonly lastSyncAt: import("@angular/core").Signal<number | null>;
+  /** Bumped when a run changed server data (a row was delivered): open pages refresh on it. */
+  readonly syncTick: import("@angular/core").Signal<number>;
+  /** True after a 401/403 stopped a run: the rows are safe and wait for the user to sign in again. */
+  readonly authBlocked: import("@angular/core").Signal<boolean>;
+  readonly lastResult: import("@angular/core").Signal<ReplayResult | null>;
+  /** Emits at the end of every run that did something. */
+  readonly runCompleted$: Subject<{
+    trigger: ReplayTrigger;
+    result: ReplayResult;
+    changed: boolean;
+  }>;
+  /** Sends everything that is due. Concurrent calls in this tab share one run; another tab's run makes this resolve null. */
+  replayAll(trigger: ReplayTrigger): Promise<ReplayResult | null>;
+  /** Puts one row (any status, conflict and failed included) back to pending with 0 attempts and sends only that row. */
+  retryOne(id: string): Promise<ReplayResult | null>;
+  /** Deletes one row of the signed-in user (the user chose to discard it). */
+  discard(id: string): Promise<void>;
+  /** Deletes all rows of the signed-in user (the user chose to discard everything). */
+  discardAll(): Promise<void>;
+  /** Re-reads the counts for the signed-in user (zeros when nobody is signed in or storage is unavailable). */
+  refreshCounts(): Promise<void>;
+  clearAuthBlocked(): void;
+  /** Another tab delivered rows: open pages in this tab must refresh too. */
+  noteRemoteSync(): void;
+  /** Forgets everything about the previous user (counts, last result); the stored rows are not touched. */
+  resetView(): void;
+  private start;
+  private exclusive;
+  private leaseKey;
+  private readLease;
+  private tryAcquireLease;
+  private releaseLease;
+  private withLease;
+  private run;
+  /**
+   * 'hold': a create this change points at is still pending / being sent (or waiting out a backoff): do not send it yet.
+   * 'fail': a create it points at failed / conflicted, was discarded, or answered without a readable id: it can never be sent correctly.
+   * Reads the store fresh for every create that has no mapping yet, so a run in another tab that just finished the create is seen.
+   */
+  private checkDependencies;
+  private send;
+  /** Stores the outcome on the row (only while we still own the claim). Returns true when the run must stop. */
+  private apply;
+  /** The server's id for a created record: the answer text parsed as JSON (undefined when empty / not JSON) run through `config.createdId`. */
+  private readCreatedId;
+  private announce;
+  static ɵfac: i0.ɵɵFactoryDeclaration<OfflineReplayer, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/** Why an offline write was refused. */
+export type OfflineBlockedReason = 'blocked' | 'upload' | 'storage' | 'not-allowed';
+/**
+ * A write that cannot be saved on the device while offline. `message` is plain words for the user (from UiLabelsService or the app's
+ * `blockOffline[].message`). Nothing was queued and nothing was sent.
+ */
+export declare class OfflineBlockedError extends Error {
+  readonly offlineBlocked = true;
+  readonly status = 0;
+  readonly reason: OfflineBlockedReason;
+  constructor(message: string, reason?: OfflineBlockedReason);
+}
+/** The client gave up waiting. For a write `outcomeUnknown` is true: the server may still have handled it. */
+export declare class RequestTimeoutError extends Error {
+  readonly timeout = true;
+  readonly status = 0;
+  readonly method: string;
+  readonly url: string;
+  readonly outcomeUnknown: boolean;
+  constructor(message: string, method: string, url: string, outcomeUnknown: boolean);
+}
+export declare function isOfflineBlockedError(e: unknown): e is OfflineBlockedError;
+export declare function isRequestTimeoutError(e: unknown): e is RequestTimeoutError;
+/**
+ * Per-request client timeout in ms, set through `HttpContext`: `http.get(url, { context: new HttpContext().set(REQUEST_TIMEOUT_MS, 120000) })`.
+ * `null` (default) = the configured read / write / long timeout. A value of 0 or less switches the timeout off for that request.
+ */
+export declare const REQUEST_TIMEOUT_MS: HttpContextToken<number | null>;
+/**
+ * Gives every write under `apiPrefix` an `Idempotency-Key: <uuid>` unless the caller already set one (callers that must keep ONE key across
+ * user retries set it themselves). The same key goes on the queued row and on every replay, so the server can recognise a repeat.
+ * Left alone: reads, skipped URLs, FormData bodies, and replays (`X-Offline-Replay`, which already carry the row's key).
+ */
+export declare const idempotencyInterceptor: HttpInterceptorFn;
+/** Pause before the single automatic retry of a read that failed without an answer. */
+declare const READ_RETRY_DELAY_MS = 1000;
+declare function isNetworkFailure(err: unknown): boolean;
+/**
+ * Measures every API request (feeds ConnectionStateService), applies the client timeout and retries a failed READ once.
+ * A write is never retried here: after a timeout or status 0 its outcome is unknown, so the user decides (the same Idempotency-Key makes
+ * a retry safe). Sits closest to the network so the offline interceptor sees timeouts and failures as errors.
+ */
+export declare const connectionInterceptor: HttpInterceptorFn;
+/**
+ * Reads: network first; the answer is also stored (per user) unless excluded; while offline/unreachable, or when the request fails with no
+ * answer, the stored copy is served (header `X-From-Offline-Cache: <cachedAt>`, StaleDataService told) and otherwise the error is rethrown.
+ * Writes while offline/unreachable: blocked (OfflineBlockedError) or saved on the device with the request's Idempotency-Key and answered with a
+ * typed synthetic 202. Writes while online pass through; a write with an unknown outcome (timeout / status 0 while the browser is online) is
+ * never queued automatically.
+ */
+export declare const offlineInterceptor: HttpInterceptorFn;
+/**
+ * Register LAST in `withInterceptors([... ,...offlineHttpInterceptors])` (after errorContext and the app's own auth interceptor; replays carry
+ * `X-Offline-Replay`, so an app whose auth interceptor sits after these still gets the live token on replays).
+ *
+ * Array order is outermost first: idempotency (adds the key) -> offline (queue / device copy) -> connection (timeout, timing, GET retry, closest
+ * to the network). The offline interceptor must be OUTSIDE the connection one: it has to see timeouts and status-0 failures as errors to fall back
+ * to the device copy, and answers it makes itself (queued 202, device copy) must not be measured as network successes.
+ */
+export declare const offlineHttpInterceptors: readonly HttpInterceptorFn[];
+/** What tabs tell each other: `changed` = the saved changes changed (re-read them), `synced` = rows were delivered (refresh open pages). */
+export type CrossTabMessage = {
+  type: 'changed';
+} | {
+  type: 'synced';
+};
+/** Creates the cross-tab channel; null when the browser has no BroadcastChannel (the focus / visibility poll still keeps tabs in step). */
+export declare function createChannel(name: string): BroadcastChannel | null;
+/**
+ * What the app talks to: counts, the list for the pending-changes drawer, Sync now / Retry / Discard, and the session helpers.
+ * Everything is scoped to `config.getUserId()`; nothing here ever deletes saved changes unless the user chose it
+ * (`discard`, `discardAll`, `endSession({ discardPending: true })` after the app asked the user).
+ */
+export declare class OfflineSupportService {
+  private readonly cfg;
+  private readonly store;
+  private readonly replayer;
+  private readonly connection;
+  private readonly stale;
+  private readonly toast;
+  private readonly labels;
+  private readonly doc;
+  private readonly destroyRef;
+  private readonly _rows;
+  private readonly _lastQueued;
+  private readonly _storageAvailable;
+  readonly pendingCount: import("@angular/core").Signal<number>;
+  readonly failedCount: import("@angular/core").Signal<number>;
+  readonly conflictCount: import("@angular/core").Signal<number>;
+  readonly syncing: import("@angular/core").Signal<boolean>;
+  readonly lastSyncAt: import("@angular/core").Signal<number | null>;
+  readonly syncTick: import("@angular/core").Signal<number>;
+  readonly authBlocked: import("@angular/core").Signal<boolean>;
+  readonly lastResult: import("@angular/core").Signal<ReplayResult | null>;
+  /** The signed-in user's saved changes, oldest first, for the drawer. Updates when another tab changes them. */
+  readonly rows: import("@angular/core").Signal<readonly OfflineMutation[]>;
+  /** The most recent change saved on this device while offline ({ label, at }). */
+  readonly lastQueued: import("@angular/core").Signal<{
+    label: string;
+    at: number;
+  } | null>;
+  /** False when IndexedDB could not be opened on this device (set after the store initialised): the drawer then must not say "all synced". */
+  readonly storageAvailable: import("@angular/core").Signal<boolean>;
+  private started;
+  private channel;
+  private refreshing;
+  private dirty;
+  private lastKnownUserId;
+  private cleanups;
+  private retryTimer;
+  private destroyed;
+  /** Wires the triggers (called by `provideOfflineSupport`'s initializer; calling it again does nothing). Resolves when the first read is done. */
+  start(): Promise<void>;
+  /** Starts a replay run without ever leaving an unhandled rejection behind. */
+  private replay;
+  private clearRetryTimer;
+  /**
+   * Rows that failed with a transient error wait for `nextAttemptAt`. Nothing else triggers a run while the connection stays `online`, so a timer
+   * fires one replay when the earliest of them is due.
+   */
+  private scheduleRetry;
+  private post;
+  private onRemote;
+  /** Called by the offline interceptor after a write was saved on the device. */
+  onQueued(row: OfflineMutation): void;
+  /** Re-reads the rows and counts. Calls that overlap are merged into one extra read. */
+  refresh(): Promise<void>;
+  private doRefresh;
+  /** "Sync now": sends everything due, even rows waiting out a backoff. */
+  syncNow(): Promise<ReplayResult | null>;
+  retry(id: string): Promise<void>;
+  discard(id: string): Promise<void>;
+  discardAll(): Promise<void>;
+  /**
+   * Call in logout BEFORE signing out. `pending` = changes not yet delivered (waiting or being sent), `failed` = changes that need attention
+   * (failed or conflict). When `pending + failed > 0` show a ConfirmService dialog with `connection.logoutPending.one` / `connection.logoutPending.other`; then call
+   * `endSession({ discardPending })` with the user's choice. Nothing is deleted here.
+   */
+  beforeSessionEnd(): Promise<{
+    pending: number;
+    failed: number;
+  }>;
+  /** The signed-in user changed (sign-in, switch): re-scope the view to them and send what they have waiting. */
+  onSessionStart(userId: string): Promise<void>;
+  /**
+   * Called by the offline interceptor for every in-scope request: when the signed-in user is not the one the view was built for (the app never
+   * called `onSessionStart`), forget the previous user's rows and counts and re-read for the new one.
+   */
+  ensureScope(): void;
+  /**
+   * The user signed out. By default NOTHING is deleted: the saved changes and the device copy stay for that user and are sent when they sign in again.
+   * Only `discardPending: true` (the app asked the user first) deletes that one user's changes and device copy. Other users' data is never touched.
+   * `userId` names the user who is leaving; pass it when the app already switched to somebody else (impersonation, portal logout), otherwise the
+   * user the view was last built for is used.
+   */
+  endSession(options: {
+    discardPending: boolean;
+    userId?: string;
+  }): Promise<void>;
+  /**
+   * Empties the device copy of every user's GET answers and the in-memory view. Saved changes are kept unless `discardPending` is true, which wipes
+   * them for EVERY user: only for a deliberate full reset the user confirmed, never at logout.
+   */
+  clearAll(options?: {
+    discardPending?: boolean;
+  }): Promise<void>;
+  static ɵfac: i0.ɵɵFactoryDeclaration<OfflineSupportService, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/**
+ * Provides the config and starts the offline layer with the app: opens the store, then wires the replay triggers (app start when online, browser
+ * `online`, connection back to `online`, probe success) and the cross-tab sync. Pair it with
+ * `provideHttpClient(withInterceptors([..., ...offlineHttpInterceptors]))`.
+ */
+export declare function provideOfflineSupport(config: OfflineSupportConfig): EnvironmentProviders;
+/** How long the green "All changes synced" bar stays after a sync. */
+export declare const SYNCED_FLASH_MS = 3000;
+export type ConnectionBannerKind = 'auth' | 'offline' | 'unreachable' | 'syncing' | 'attention' | 'slow' | 'synced';
+interface BannerView {
+  kind: ConnectionBannerKind;
+  title: string;
+  message: string;
+  detail: string;
+  /** Spoken text: exactly what the sighted user reads. */
+  announcement: string;
+}
+/**
+ * THE connection banner. Put ONE near the root of the app, above the routed content (inside the scrolling page, not fixed):
+ *
+ *   <ui-connection-banner (viewChanges)="drawerOpen.set(true)" />
+ *
+ * One plain-words message per situation, by priority: sign-in needed for saved changes > offline > server unreachable >
+ * sending saved changes > changes need attention > slow connection > "All changes synced" (3 s, also after automatic syncs) > nothing.
+ *
+ * Accessibility: two live regions (polite status, assertive alert for the sign-in message) exist from the first render and only their text
+ * changes, so screen readers announce every change; the visible bar is ordinary content that mirrors the same words. The bar is
+ * `position: sticky; top: 0` inside the page flow, so it never covers content, and sits below modals / side panels.
+ *
+ * Test ids: connection-banner, connection-banner-live, connection-banner-live-alert, connection-banner-title, connection-banner-message,
+ * connection-banner-detail, connection-banner-sync-now, connection-banner-view, connection-banner-info-toggle, connection-banner-info-panel,
+ * connection-banner-info-hide.
+ */
+export declare class ConnectionBannerComponent {
+  protected readonly labels: UiLabelsService;
+  private readonly connection;
+  private readonly support;
+  private readonly cdr;
+  /** What the user can still do while offline (app specific). Default: a generic list. */
+  readonly infoOffline: import("@angular/core").InputSignal<readonly string[] | null>;
+  /** What needs a connection (app specific, should match what the app really blocks). Default: a generic list. */
+  readonly infoNeedsConnection: import("@angular/core").InputSignal<readonly string[] | null>;
+  /** The user pressed "View changes" - the app opens `<ui-pending-changes-drawer>`. */
+  readonly viewChanges: import("@angular/core").OutputEmitterRef<void>;
+  protected readonly panelId: string;
+  protected readonly infoOpen: import("@angular/core").WritableSignal<boolean>;
+  private readonly infoToggleRef;
+  private readonly infoHideRef;
+  private readonly syncTotal;
+  private readonly showSynced;
+  private syncedTimer;
+  private seenTick;
+  private flashPending;
+  private wasSyncing;
+  protected readonly canDoItems: import("@angular/core").Signal<readonly string[]>;
+  protected readonly needsItems: import("@angular/core").Signal<readonly string[]>;
+  private count;
+  protected readonly view: import("@angular/core").Signal<BannerView | null>;
+  /** Set when a "Sync now" call was rejected: said politely in the status region (nothing is lost, the changes stay saved). */
+  private readonly actionFailure;
+  protected readonly politeText: import("@angular/core").Signal<string>;
+  protected readonly alertText: import("@angular/core").Signal<string>;
+  protected readonly infoAllowed: import("@angular/core").Signal<boolean>;
+  protected readonly showSyncNow: import("@angular/core").Signal<boolean>;
+  protected readonly showView: import("@angular/core").Signal<boolean>;
+  private readonly rowsTotal;
+  constructor();
+  private flashSynced;
+  protected syncNow(): void;
+  protected toggleInfo(): void;
+  protected closeInfo(returnFocus: boolean): void;
+  protected onEscape(event: Event): void;
+  static ɵfac: i0.ɵɵFactoryDeclaration<ConnectionBannerComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<ConnectionBannerComponent, "ui-connection-banner", never, {
+    "infoOffline": {
+      "alias": "infoOffline";
+      "required": false;
+      "isSignal": true;
+    };
+    "infoNeedsConnection": {
+      "alias": "infoNeedsConnection";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "viewChanges": "viewChanges";
+  }, never, never, true, never>;
+}
+/** One saved change as the drawer shows it (derived from `OfflineSupportService.rows`, i.e. the OfflineStore row shape). */
+type PendingRow = ReturnType<OfflineSupportService['rows']>[number];
+/**
+ * Side panel that lists every change saved on this device and not yet accepted by the server, with plain-words reasons and
+ * the actions Retry / Discard per change, Sync all and Discard all. Open it from `(viewChanges)` of `<ui-connection-banner>`:
+ *
+ *   <ui-pending-changes-drawer [open]="drawerOpen()" (closed)="drawerOpen.set(false)" />
+ *
+ * Raw server text is never shown: the wording comes from `lastError.kind`. Discards ask first (ConfirmService). Results are announced
+ * in a polite live region that exists from the first render. Test ids: pending-drawer-live, pending-drawer-auth, pending-drawer-list,
+ * pending-drawer-empty, pending-row-<id>, pending-row-status-<id>, pending-row-error-<id>, pending-row-time-<id>, pending-row-retry-<id>,
+ * pending-row-discard-<id>, pending-drawer-sync-all, pending-drawer-discard-all.
+ */
+export declare class PendingChangesDrawerComponent {
+  protected readonly labels: UiLabelsService;
+  protected readonly support: OfflineSupportService;
+  private readonly confirmService;
+  private readonly cdr;
+  private readonly host;
+  private readonly doc;
+  readonly open: import("@angular/core").InputSignal<boolean>;
+  readonly closed: import("@angular/core").OutputEmitterRef<void>;
+  protected readonly rows: import("@angular/core").Signal<readonly import("@forgeroute/ui/offline").OfflineMutation[]>;
+  protected readonly announcement: import("@angular/core").WritableSignal<string>;
+  private readonly now;
+  constructor();
+  protected statusText(row: PendingRow): string;
+  /** Plain words from the error KIND; the server's own text (`lastError.message`) is never shown. */
+  protected errorText(row: PendingRow): string;
+  protected canRetry(row: PendingRow): boolean;
+  protected iso(row: PendingRow): string;
+  protected absolute(row: PendingRow): string;
+  protected savedText(row: PendingRow): string;
+  protected retry(row: PendingRow): Promise<void>;
+  protected syncAll(): Promise<void>;
+  protected discard(row: PendingRow): Promise<void>;
+  protected discardAll(): Promise<void>;
+  /** A rejected service call must not become an unhandled rejection; tell the user politely (nothing was lost). */
+  private announceFailure;
+  /** The row the user acted on is gone: move focus to the row now at that position (or the previous one, or the empty message). */
+  private focusAfterRemoval;
+  static ɵfac: i0.ɵɵFactoryDeclaration<PendingChangesDrawerComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<PendingChangesDrawerComponent, "ui-pending-changes-drawer", never, {
+    "open": {
+      "alias": "open";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "closed": "closed";
+  }, never, never, true, never>;
+}
+/**
+ * "Showing saved data from 5 minutes ago  [Refresh]" while `StaleDataService.staleAt()` is set (a GET was answered from the
+ * device copy). Put it at the top of the page area that shows the data; the app reloads the data on `(refresh)`:
+ *
+ *   <ui-stale-data-chip (refresh)="reload()" />
+ *
+ * A polite live region exists from the first render (visually hidden) and mirrors the sentence. Test ids: stale-data-chip,
+ * stale-data-chip-live, stale-data-chip-time, stale-data-chip-refresh.
+ */
+export declare class StaleDataChipComponent {
+  protected readonly labels: UiLabelsService;
+  private readonly stale;
+  private readonly doc;
+  /** The user pressed Refresh - reload the data from the server. */
+  readonly refresh: import("@angular/core").OutputEmitterRef<void>;
+  private readonly now;
+  protected readonly parts: import("@angular/core").Signal<{
+    before: string;
+    after: string;
+    relative: string;
+    iso: string;
+    absolute: string;
+  } | null>;
+  protected readonly announcement: import("@angular/core").Signal<string>;
+  constructor();
+  static ɵfac: i0.ɵɵFactoryDeclaration<StaleDataChipComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<StaleDataChipComponent, "ui-stale-data-chip", never, {}, {
+    "refresh": "refresh";
+  }, never, never, true, never>;
+}
+/**
+ * "Still working… please don't tap again." for a button or panel whose request has been running for a while.
+ *
+ *   <ui-still-working [active]="saving()" />
+ *
+ * The host keeps its own button disabled while `active`. The text appears only after `delayMs` (default 4 s) of continuous
+ * `active`, disappears at once when `active` turns false, and sits in a polite live region that exists from the first render
+ * (so screen readers announce the text when it appears). Test id: still-working.
+ */
+export declare class StillWorkingComponent {
+  private readonly labels;
+  /** True while the request runs. */
+  readonly active: import("@angular/core").InputSignal<boolean>;
+  /** Milliseconds of continuous `active` before the text appears. */
+  readonly delayMs: import("@angular/core").InputSignal<number>;
+  private readonly elapsed;
+  protected readonly text: import("@angular/core").Signal<string>;
+  constructor();
+  static ɵfac: i0.ɵɵFactoryDeclaration<StillWorkingComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<StillWorkingComponent, "ui-still-working", never, {
+    "active": {
+      "alias": "active";
+      "required": false;
+      "isSignal": true;
+    };
+    "delayMs": {
+      "alias": "delayMs";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}