@flighthq/lifecycle 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './lifecycle';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './lifecycle';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}

package/dist/lifecycle.d.ts

@@ -0,0 +1,15 @@
+import type { AppLaunchKind, AppLifecycle, AppLifecycleState, LifecycleBackend } from '@flighthq/types';
+export declare function attachAppLifecycle(app: AppLifecycle): void;
+export declare function createAppLifecycle(): AppLifecycle;
+export declare function createWebLifecycleBackend(): LifecycleBackend;
+export declare function detachAppLifecycle(app: AppLifecycle): void;
+export declare function disposeAppLifecycle(app: AppLifecycle): void;
+export declare function getAppLaunchKind(): AppLaunchKind;
+export declare function getAppLifecycleState(): AppLifecycleState;
+export declare function getLifecycleBackend(): LifecycleBackend;
+export declare function isAppActive(): boolean;
+export declare function isAppBackground(): boolean;
+export declare function isAppInactive(): boolean;
+export declare function requestAppBack(app: AppLifecycle): boolean;
+export declare function setLifecycleBackend(backend: LifecycleBackend | null): void;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,iBAAiB,EAEjB,gBAAgB,EACjB,MAAM,iBAAiB,CAAC;AAYzB,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAqC1D;AAGD,wBAAgB,kBAAkB,IAAI,YAAY,CAUjD;AAmBD,wBAAgB,yBAAyB,IAAI,gBAAgB,CA4E5D;AAGD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAM1D;AAID,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,YAAY,GAAG,IAAI,CAG3D;AAMD,wBAAgB,gBAAgB,IAAI,aAAa,CAGhD;AAGD,wBAAgB,oBAAoB,IAAI,iBAAiB,CAExD;AAGD,wBAAgB,mBAAmB,IAAI,gBAAgB,CAGtD;AAGD,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAGD,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAID,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAOD,wBAAgB,cAAc,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAGzD;AAGD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,GAAG,IAAI,CAE1E"}

package/dist/lifecycle.js

@@ -0,0 +1,223 @@
+import { createSignal, emitSignal } from '@flighthq/signals';
+// Begins delivering lifecycle changes to `app`'s signals by subscribing to the active backend. On
+// each change it reads the current state and emits onStateChange plus onResume when transitioning
+// to 'active' and onPause when leaving 'active'. The web backend drives onBackButton only in
+// environments that support it; native hosts emit it through their own backend. Idempotent: a prior
+// subscription is torn down first. Pair with detachAppLifecycle/disposeAppLifecycle.
+//
+// onStateChange is "raw, not deduped" — it fires on every backend notification regardless of
+// whether the derived state changed. onResume/onPause are deduped edges: 'active'→non-'active'
+// fires onPause (including the interruption edge 'active'→'inactive'); non-'active'→'active' fires
+// onResume. The 'inactive'→'background' and reverse transitions do not fire onPause/onResume again.
+export function attachAppLifecycle(app) {
+    detachAppLifecycle(app);
+    const backend = getLifecycleBackend();
+    let previous = backend.getState();
+    const unsubscribeState = backend.subscribe(() => {
+        const state = backend.getState();
+        emitSignal(app.onStateChange, state);
+        if (state === 'active' && previous !== 'active') {
+            emitSignal(app.onResume);
+            // Warm resume: restore saved state.
+            const saved = _savedState.get(app);
+            if (saved !== undefined) {
+                emitSignal(app.onRestoreState, saved);
+            }
+        }
+        else if (state !== 'active' && previous === 'active') {
+            emitSignal(app.onPause);
+            // Collect transient UI state for potential restore on next resume.
+            const stateBag = {};
+            emitSignal(app.onSaveState, stateBag);
+            _savedState.set(app, stateBag);
+        }
+        previous = state;
+    });
+    let unsubscribeMemory;
+    const memSub = backend.subscribeMemoryWarning;
+    if (memSub !== undefined) {
+        unsubscribeMemory = memSub.call(backend, (level) => {
+            emitSignal(app.onMemoryWarning, level);
+        });
+    }
+    _subscriptions.set(app, () => {
+        unsubscribeState();
+        unsubscribeMemory?.();
+    });
+}
+// Allocates an AppLifecycle event entity with inert signals; call attachAppLifecycle to start delivery.
+export function createAppLifecycle() {
+    return {
+        onStateChange: createSignal(),
+        onResume: createSignal(),
+        onPause: createSignal(),
+        onBackButton: createSignal(),
+        onMemoryWarning: createSignal(),
+        onSaveState: createSignal(),
+        onRestoreState: createSignal(),
+    };
+}
+// Builds the default web backend over document visibility, window focus/blur, and pagehide/pageshow
+// events. Produces three states:
+//   'active'     — document visible and window focused
+//   'inactive'   — document visible but window not focused (app switcher, control-center, other window)
+//   'background' — document.hidden (tab hidden or page unloading)
+// Degrades to state 'active' and a no-op subscription where document/window are absent (SSR/jsdom).
+//
+// getLaunchKind() approximates cold vs. warm using PerformanceNavigationTiming.type:
+//   'back_forward' → 'warm'  — page was restored from the bfcache (JS heap was frozen and thawed;
+//                              the closest web equivalent of a process warm-resume)
+//   all others     → 'cold'  — 'navigate', 'reload', 'prerender' are each a fresh page lifecycle
+// Falls back to 'cold' when the Performance Navigation Timing API is unavailable (SSR/jsdom).
+//
+// subscribeMemoryWarning() wires the experimental 'memory-pressure' window event (Chrome origin
+// trial / behind flags). The event detail carries a 'critical' pressure string; this backend maps
+// it to 'critical' and fires 'normal' on the subsequent resolution event when present. Falls back to
+// no-op unsubscribe when the event is not supported (no standard API is widely deployed as of 2026).
+export function createWebLifecycleBackend() {
+    let _windowFocused = typeof document !== 'undefined';
+    return {
+        getState() {
+            if (typeof document === 'undefined')
+                return 'active';
+            if (document.hidden)
+                return 'background';
+            return _windowFocused ? 'active' : 'inactive';
+        },
+        subscribe(listener) {
+            if (typeof document === 'undefined' || typeof window === 'undefined')
+                return () => { };
+            // Initialize focus state at subscribe time.
+            _windowFocused = document.hasFocus();
+            const onFocus = () => {
+                _windowFocused = true;
+                listener();
+            };
+            const onBlur = () => {
+                _windowFocused = false;
+                listener();
+            };
+            document.addEventListener('visibilitychange', listener);
+            window.addEventListener('pagehide', listener);
+            window.addEventListener('pageshow', listener);
+            window.addEventListener('focus', onFocus);
+            window.addEventListener('blur', onBlur);
+            return () => {
+                document.removeEventListener('visibilitychange', listener);
+                window.removeEventListener('pagehide', listener);
+                window.removeEventListener('pageshow', listener);
+                window.removeEventListener('focus', onFocus);
+                window.removeEventListener('blur', onBlur);
+            };
+        },
+        getLaunchKind() {
+            // PerformanceNavigationTiming.type === 'back_forward' indicates the page was restored from the
+            // browser's back/forward cache (bfcache). The JS heap was frozen and thawed without a fresh
+            // process start — the closest analog to a mobile warm-resume. All other navigation types
+            // ('navigate', 'reload', 'prerender') are a fresh page lifecycle, i.e. cold.
+            if (typeof performance === 'undefined')
+                return 'cold';
+            const entries = performance.getEntriesByType('navigation');
+            if (entries.length > 0 && entries[0].type === 'back_forward')
+                return 'warm';
+            return 'cold';
+        },
+        subscribeMemoryWarning(listener) {
+            // The 'memory-pressure' window event is an experimental Chrome API (origin trial / behind
+            // flags as of 2026). The event carries a detail object with a 'pressure' string. This backend
+            // maps 'critical' pressure to AppMemoryPressure 'critical'; a pressure-resolved / 'moderate'
+            // event maps to 'moderate'. Falls back to no-op unsubscribe when the event is not supported
+            // (no cross-browser API for memory pressure is widely deployed yet).
+            if (typeof window === 'undefined')
+                return () => { };
+            // Feature-detect: attempt to register and immediately remove a passive listener to check
+            // whether the event is supported. If addEventListener silently ignores the event type there
+            // is nothing we can do — we just return no-op without pretending to be subscribed.
+            const onPressure = (e) => {
+                const detail = e.detail;
+                const pressure = detail?.pressure;
+                if (pressure === 'critical') {
+                    listener('critical');
+                }
+                else if (pressure === 'moderate') {
+                    listener('moderate');
+                }
+                else {
+                    // Unknown pressure level — treat as moderate rather than silently dropping.
+                    listener('moderate');
+                }
+            };
+            const onPressureRelieved = () => {
+                listener('normal');
+            };
+            window.addEventListener('memory-pressure', onPressure);
+            window.addEventListener('memory-pressure-relieved', onPressureRelieved);
+            return () => {
+                window.removeEventListener('memory-pressure', onPressure);
+                window.removeEventListener('memory-pressure-relieved', onPressureRelieved);
+            };
+        },
+    };
+}
+// Stops delivery to `app` and forgets its subscription. Safe to call when not attached.
+export function detachAppLifecycle(app) {
+    const unsubscribe = _subscriptions.get(app);
+    if (unsubscribe !== undefined) {
+        unsubscribe();
+        _subscriptions.delete(app);
+    }
+}
+// Releases `app` for garbage collection by detaching its backend subscription. The signals remain
+// plain GC-managed memory afterward.
+export function disposeAppLifecycle(app) {
+    detachAppLifecycle(app);
+    _savedState.delete(app);
+}
+// Returns the kind of launch — 'cold' (fresh process) or 'warm' (resumed from background). The web
+// backend approximates this via PerformanceNavigationTiming.type ('back_forward' → 'warm', all
+// others → 'cold'). Returns 'warm' as a safe fallback when the backend does not implement
+// getLaunchKind (legacy or minimal backends that pre-date the optional method).
+export function getAppLaunchKind() {
+    const backend = getLifecycleBackend();
+    return backend.getLaunchKind !== undefined ? backend.getLaunchKind() : 'warm';
+}
+// Returns the current application lifecycle state from the active backend.
+export function getAppLifecycleState() {
+    return getLifecycleBackend().getState();
+}
+// The active lifecycle backend, or a lazily-created web default. There is always a backend.
+export function getLifecycleBackend() {
+    if (_backend === null)
+        _backend = createWebLifecycleBackend();
+    return _backend;
+}
+// Returns true when the application is in the 'active' state (visible and focused).
+export function isAppActive() {
+    return getLifecycleBackend().getState() === 'active';
+}
+// Returns true when the application is in the 'background' state (hidden/suspended).
+export function isAppBackground() {
+    return getLifecycleBackend().getState() === 'background';
+}
+// Returns true when the application is in the 'inactive' state (visible but not focused —
+// e.g. app switcher, control-center overlay, incoming call).
+export function isAppInactive() {
+    return getLifecycleBackend().getState() === 'inactive';
+}
+// Emits app.onBackButton and returns whether the back action may proceed. Returns false when a
+// listener vetoed by calling cancelSignal(app.onBackButton), meaning the listener handled
+// navigation itself. Returns true when no listener consumed the event and the host should perform
+// the default back action (navigate up or exit). Mirrors the onCloseRequest/requestCloseWindow
+// veto contract from @flighthq/application.
+export function requestAppBack(app) {
+    emitSignal(app.onBackButton);
+    return app.onBackButton.data?.cancelled !== true;
+}
+// Installs a native host lifecycle backend; pass null to fall back to the web default.
+export function setLifecycleBackend(backend) {
+    _backend = backend;
+}
+let _backend = null;
+const _savedState = new WeakMap();
+const _subscriptions = new WeakMap();
+//# sourceMappingURL=lifecycle.js.map

package/dist/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../src/lifecycle.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@flighthq/lifecycle",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/signals": "0.1.0",
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Application foreground/background lifecycle state and resume/pause/back signals over a swappable web/native backend",
+  "sideEffects": false
+}

package/src/lifecycle.test.ts

@@ -0,0 +1,550 @@
+import { cancelSignal, connectSignal } from '@flighthq/signals';
+import type { AppLifecycleState, AppMemoryPressure, LifecycleBackend } from '@flighthq/types';
+
+import {
+  attachAppLifecycle,
+  createAppLifecycle,
+  createWebLifecycleBackend,
+  detachAppLifecycle,
+  disposeAppLifecycle,
+  getAppLaunchKind,
+  getAppLifecycleState,
+  getLifecycleBackend,
+  isAppActive,
+  isAppBackground,
+  isAppInactive,
+  requestAppBack,
+  setLifecycleBackend,
+} from './lifecycle';
+
+type FakeBackend = LifecycleBackend & {
+  state: AppLifecycleState;
+  fire: () => void;
+  fireMemory: (level: AppMemoryPressure) => void;
+};
+
+function fakeBackend(): FakeBackend {
+  let stateListener: (() => void) | null = null;
+  let memoryListener: ((level: AppMemoryPressure) => void) | null = null;
+  return {
+    state: 'active',
+    getState() {
+      return this.state;
+    },
+    subscribe(l) {
+      stateListener = l;
+      return () => {
+        stateListener = null;
+      };
+    },
+    subscribeMemoryWarning(l) {
+      memoryListener = l;
+      return () => {
+        memoryListener = null;
+      };
+    },
+    fire() {
+      stateListener?.();
+    },
+    fireMemory(level: AppMemoryPressure) {
+      memoryListener?.(level);
+    },
+  };
+}
+
+afterEach(() => setLifecycleBackend(null));
+
+describe('attachAppLifecycle', () => {
+  it('emits onPause and onStateChange when leaving active for background', () => {
+    const backend = fakeBackend();
+    setLifecycleBackend(backend);
+    const app = createAppLifecycle();
+    let changes = 0;
+    let pauses = 0;
+    connectSignal(app.onStateChange, () => changes++);
+    connectSignal(app.onPause, () => pauses++);
+    attachAppLifecycle(app);
+    backend.state = 'background';
+    backend.fire();
+    expect(changes).toBe(1);
+    expect(pauses).toBe(1);
+  });
+
+  it('emits onPause when leaving active for inactive', () => {
+    const backend = fakeBackend();
+    setLifecycleBackend(backend);
+    const app = createAppLifecycle();
+    let pauses = 0;
+    connectSignal(app.onPause, () => pauses++);
+    attachAppLifecycle(app);
+    backend.state = 'inactive';
+    backend.fire();
+    expect(pauses).toBe(1);
+  });
+
+  it('does not double-fire onPause for inactive → background', () => {
+    const backend = fakeBackend();
+    backend.state = 'inactive';
+    setLifecycleBackend(backend);
+    const app = createAppLifecycle();
+    let pauses = 0;
+    connectSignal(app.onPause, () => pauses++);
+    attachAppLifecycle(app);
+    backend.state = 'background';
+    backend.fire();
+    // inactive → background should not re-fire onPause (already paused)
+    expect(pauses).toBe(0);
+  });
+
+  it('emits onResume when returning to active from background', () => {
+    const backend = fakeBackend();
+    backend.state = 'background';
+    setLifecycleBackend(backend);
+    const app = createAppLifecycle();
+    let resumes = 0;
+    connectSignal(app.onResume, () => resumes++);
+    attachAppLifecycle(app);
+    backend.state = 'active';
+    backend.fire();
+    expect(resumes).toBe(1);
+  });
+
+  it('emits onResume when returning to active from inactive', () => {
+    const backend = fakeBackend();
+    backend.state = 'inactive';
+    setLifecycleBackend(backend);
+    const app = createAppLifecycle();
+    let resumes = 0;
+    connectSignal(app.onResume, () => resumes++);
+    attachAppLifecycle(app);
+    backend.state = 'active';
+    backend.fire();
+    expect(resumes).toBe(1);
+  });
+
+  it('is idempotent — re-attaching tears down the prior subscription', () => {
+    const backend = fakeBackend();
+    setLifecycleBackend(backend);
+    const app = createAppLifecycle();
+    let changes = 0;
+    connectSignal(app.onStateChange, () => changes++);
+    attachAppLifecycle(app);
+    attachAppLifecycle(app);
+    backend.state = 'background';
+    backend.fire();
+    // Only one subscription should be active.
+    expect(changes).toBe(1);
+  });
+
+  it('emits onSaveState when leaving active', () => {
+    const backend = fakeBackend();
+    setLifecycleBackend(backend);
+    const app = createAppLifecycle();
+    let saved = false;
+    connectSignal(app.onSaveState, (bag) => {
+      bag['key'] = 'value';
+      saved = true;
+    });
+    attachAppLifecycle(app);
+    backend.state = 'background';
+    backend.fire();
+    expect(saved).toBe(true);
+  });
+
+  it('emits onRestoreState with saved bag when returning to active', () => {
+    const backend = fakeBackend();
+    setLifecycleBackend(backend);
+    const app = createAppLifecycle();
+    connectSignal(app.onSaveState, (bag) => {
+      bag['x'] = 42;
+    });
+    let restored: Readonly<Record<string, unknown>> | null = null;
+    connectSignal(app.onRestoreState, (state) => {
+      restored = state;
+    });
+    attachAppLifecycle(app);
+    // Transition away to trigger save.
+    backend.state = 'background';
+    backend.fire();
+    // Transition back to trigger restore.
+    backend.state = 'active';
+    backend.fire();
+    expect(restored).not.toBeNull();
+    expect(restored?.['x']).toBe(42);
+  });
+
+  it('subscribes to memory warnings when backend supports it', () => {
+    const backend = fakeBackend();
+    setLifecycleBackend(backend);
+    const app = createAppLifecycle();
+    const levels: AppMemoryPressure[] = [];
+    connectSignal(app.onMemoryWarning, (level) => levels.push(level));
+    attachAppLifecycle(app);
+    backend.fireMemory('critical');
+    expect(levels).toEqual(['critical']);
+  });
+
+  // Property/fuzz coverage over transition storms. These validate the already-documented edge
+  // contract — onStateChange is raw (one emit per backend notification), while onResume/onPause are
+  // deduped 'active'↔non-'active' boundary edges — against random sequences of the three states,
+  // rather than a single hand-picked path. The invariants are derived independently from the same
+  // model the implementation describes, so a regression in the dedup logic surfaces as a mismatch.
+  it('property: onStateChange fires exactly once per backend notification across random storms', () => {
+    const states: AppLifecycleState[] = ['active', 'inactive', 'background'];
+    for (let trial = 0; trial < 200; trial++) {
+      const backend = fakeBackend();
+      setLifecycleBackend(backend);
+      const app = createAppLifecycle();
+      let changes = 0;
+      connectSignal(app.onStateChange, () => changes++);
+      attachAppLifecycle(app);
+      const fireCount = 1 + Math.floor(Math.random() * 30);
+      for (let i = 0; i < fireCount; i++) {
+        backend.state = states[Math.floor(Math.random() * states.length)];
+        backend.fire();
+      }
+      // Raw, not deduped: every notification emits, even when the derived state is unchanged.
+      expect(changes).toBe(fireCount);
+      detachAppLifecycle(app);
+    }
+  });
+
+  it('property: onResume/onPause collapse a random storm to the minimal active-boundary edge set', () => {
+    const states: AppLifecycleState[] = ['active', 'inactive', 'background'];
+    for (let trial = 0; trial < 200; trial++) {
+      const backend = fakeBackend();
+      const start = states[Math.floor(Math.random() * states.length)];
+      backend.state = start;
+      setLifecycleBackend(backend);
+      const app = createAppLifecycle();
+      let pauses = 0;
+      let resumes = 0;
+      connectSignal(app.onPause, () => pauses++);
+      connectSignal(app.onResume, () => resumes++);
+      attachAppLifecycle(app);
+
+      // Drive a random storm while computing the expected edge counts from an independent model:
+      // a pause edge is every 'active' → non-'active' transition, a resume edge every
+      // non-'active' → 'active' transition. inactive↔background never fires either.
+      let previous = start;
+      let expectedPauses = 0;
+      let expectedResumes = 0;
+      const fireCount = 1 + Math.floor(Math.random() * 30);
+      for (let i = 0; i < fireCount; i++) {
+        const next = states[Math.floor(Math.random() * states.length)];
+        backend.state = next;
+        backend.fire();
+        if (previous === 'active' && next !== 'active') expectedPauses++;
+        else if (previous !== 'active' && next === 'active') expectedResumes++;
+        previous = next;
+      }
+      expect(pauses).toBe(expectedPauses);
+      expect(resumes).toBe(expectedResumes);
+      detachAppLifecycle(app);
+    }
+  });
+
+  it('property: a focus/blur flutter that never leaves active emits no pause or resume', () => {
+    // A common real storm: rapid blur→focus while the document stays visible. Every notification
+    // re-reads 'active' (the fake holds 'active'), so onStateChange fires each time but the deduped
+    // edges stay silent — there is no active-boundary crossing.
+    for (let trial = 0; trial < 100; trial++) {
+      const backend = fakeBackend();
+      backend.state = 'active';
+      setLifecycleBackend(backend);
+      const app = createAppLifecycle();
+      let changes = 0;
+      let pauses = 0;
+      let resumes = 0;
+      connectSignal(app.onStateChange, () => changes++);
+      connectSignal(app.onPause, () => pauses++);
+      connectSignal(app.onResume, () => resumes++);
+      attachAppLifecycle(app);
+      const fireCount = 1 + Math.floor(Math.random() * 30);
+      for (let i = 0; i < fireCount; i++) backend.fire();
+      expect(changes).toBe(fireCount);
+      expect(pauses).toBe(0);
+      expect(resumes).toBe(0);
+      detachAppLifecycle(app);
+    }
+  });
+
+  it('property: pause and resume counts stay balanced within one across any storm', () => {
+    // Across a full storm the deduped edges alternate (pause then resume then pause …) starting
+    // from whichever side of the active boundary the storm began on, so the running counts can
+    // never differ by more than one — the structural guarantee a state machine of one boolean
+    // ('was active') provides.
+    const states: AppLifecycleState[] = ['active', 'inactive', 'background'];
+    for (let trial = 0; trial < 200; trial++) {
+      const backend = fakeBackend();
+      backend.state = states[Math.floor(Math.random() * states.length)];
+      setLifecycleBackend(backend);
+      const app = createAppLifecycle();
+      let pauses = 0;
+      let resumes = 0;
+      connectSignal(app.onPause, () => pauses++);
+      connectSignal(app.onResume, () => resumes++);
+      attachAppLifecycle(app);
+      const fireCount = 1 + Math.floor(Math.random() * 30);
+      for (let i = 0; i < fireCount; i++) {
+        backend.state = states[Math.floor(Math.random() * states.length)];
+        backend.fire();
+      }
+      expect(Math.abs(pauses - resumes)).toBeLessThanOrEqual(1);
+      detachAppLifecycle(app);
+    }
+  });
+});
+
+describe('createAppLifecycle', () => {
+  it('creates an entity with all seven signals', () => {
+    const app = createAppLifecycle();
+    expect(app.onStateChange).toBeDefined();
+    expect(app.onResume).toBeDefined();
+    expect(app.onPause).toBeDefined();
+    expect(app.onBackButton).toBeDefined();
+    expect(app.onMemoryWarning).toBeDefined();
+    expect(app.onSaveState).toBeDefined();
+    expect(app.onRestoreState).toBeDefined();
+  });
+});
+
+describe('createWebLifecycleBackend', () => {
+  it("getLaunchKind returns 'cold' when no performance navigation entries", () => {
+    vi.spyOn(performance, 'getEntriesByType').mockReturnValue([]);
+    const backend = createWebLifecycleBackend();
+    expect(backend.getLaunchKind?.()).toBe('cold');
+    vi.restoreAllMocks();
+  });
+
+  it("getLaunchKind returns 'warm' for back_forward navigation type", () => {
+    vi.spyOn(performance, 'getEntriesByType').mockReturnValue([
+      { type: 'back_forward' } as PerformanceNavigationTiming,
+    ]);
+    const backend = createWebLifecycleBackend();
+    expect(backend.getLaunchKind?.()).toBe('warm');
+    vi.restoreAllMocks();
+  });
+
+  it("getLaunchKind returns 'cold' for reload navigation type", () => {
+    vi.spyOn(performance, 'getEntriesByType').mockReturnValue([{ type: 'reload' } as PerformanceNavigationTiming]);
+    const backend = createWebLifecycleBackend();
+    expect(backend.getLaunchKind?.()).toBe('cold');
+    vi.restoreAllMocks();
+  });
+
+  it("getLaunchKind returns 'cold' for navigate navigation type", () => {
+    vi.spyOn(performance, 'getEntriesByType').mockReturnValue([{ type: 'navigate' } as PerformanceNavigationTiming]);
+    const backend = createWebLifecycleBackend();
+    expect(backend.getLaunchKind?.()).toBe('cold');
+    vi.restoreAllMocks();
+  });
+
+  it('reads a state without throwing', () => {
+    expect(typeof createWebLifecycleBackend().getState()).toBe('string');
+  });
+
+  it('subscribeMemoryWarning fires critical when memory-pressure event fires', () => {
+    const backend = createWebLifecycleBackend();
+    const levels: AppMemoryPressure[] = [];
+    const unsubscribe = backend.subscribeMemoryWarning?.((level) => levels.push(level));
+    // Simulate a memory-pressure event with 'critical' pressure detail.
+    const event = new CustomEvent('memory-pressure', { detail: { pressure: 'critical' } });
+    window.dispatchEvent(event);
+    expect(levels).toEqual(['critical']);
+    unsubscribe?.();
+  });
+
+  it('subscribeMemoryWarning fires moderate when memory-pressure event fires with moderate pressure', () => {
+    const backend = createWebLifecycleBackend();
+    const levels: AppMemoryPressure[] = [];
+    const unsubscribe = backend.subscribeMemoryWarning?.((level) => levels.push(level));
+    const event = new CustomEvent('memory-pressure', { detail: { pressure: 'moderate' } });
+    window.dispatchEvent(event);
+    expect(levels).toEqual(['moderate']);
+    unsubscribe?.();
+  });
+
+  it('subscribeMemoryWarning fires normal when memory-pressure-relieved event fires', () => {
+    const backend = createWebLifecycleBackend();
+    const levels: AppMemoryPressure[] = [];
+    const unsubscribe = backend.subscribeMemoryWarning?.((level) => levels.push(level));
+    const event = new CustomEvent('memory-pressure-relieved');
+    window.dispatchEvent(event);
+    expect(levels).toEqual(['normal']);
+    unsubscribe?.();
+  });
+
+  it('subscribeMemoryWarning stops delivering after unsubscribe', () => {
+    const backend = createWebLifecycleBackend();
+    const levels: AppMemoryPressure[] = [];
+    const unsubscribe = backend.subscribeMemoryWarning?.((level) => levels.push(level));
+    unsubscribe?.();
+    const event = new CustomEvent('memory-pressure', { detail: { pressure: 'critical' } });
+    window.dispatchEvent(event);
+    expect(levels).toHaveLength(0);
+  });
+
+  it('subscribes and unsubscribes without throwing', () => {
+    const unsubscribe = createWebLifecycleBackend().subscribe(() => {});
+    expect(() => unsubscribe()).not.toThrow();
+  });
+});
+
+describe('detachAppLifecycle', () => {
+  it('stops further delivery', () => {
+    const backend = fakeBackend();
+    setLifecycleBackend(backend);
+    const app = createAppLifecycle();
+    let changes = 0;
+    connectSignal(app.onStateChange, () => changes++);
+    attachAppLifecycle(app);
+    detachAppLifecycle(app);
+    backend.fire();
+    expect(changes).toBe(0);
+  });
+
+  it('is safe to call when not attached', () => {
+    const app = createAppLifecycle();
+    expect(() => detachAppLifecycle(app)).not.toThrow();
+  });
+});
+
+describe('disposeAppLifecycle', () => {
+  it('detaches the subscription', () => {
+    const backend = fakeBackend();
+    setLifecycleBackend(backend);
+    const app = createAppLifecycle();
+    attachAppLifecycle(app);
+    expect(() => disposeAppLifecycle(app)).not.toThrow();
+  });
+
+  it('stops delivery after dispose', () => {
+    const backend = fakeBackend();
+    setLifecycleBackend(backend);
+    const app = createAppLifecycle();
+    let changes = 0;
+    connectSignal(app.onStateChange, () => changes++);
+    attachAppLifecycle(app);
+    disposeAppLifecycle(app);
+    backend.fire();
+    expect(changes).toBe(0);
+  });
+});
+
+describe('getAppLaunchKind', () => {
+  it("returns 'warm' when backend does not implement getLaunchKind", () => {
+    const backend = fakeBackend();
+    setLifecycleBackend(backend);
+    expect(getAppLaunchKind()).toBe('warm');
+  });
+
+  it('delegates to backend.getLaunchKind when present', () => {
+    const backend: LifecycleBackend = {
+      getState: () => 'active',
+      subscribe: () => () => {},
+      getLaunchKind: () => 'cold',
+    };
+    setLifecycleBackend(backend);
+    expect(getAppLaunchKind()).toBe('cold');
+  });
+});
+
+describe('getAppLifecycleState', () => {
+  it('reads from the active backend', () => {
+    const backend = fakeBackend();
+    backend.state = 'inactive';
+    setLifecycleBackend(backend);
+    expect(getAppLifecycleState()).toBe('inactive');
+  });
+});
+
+describe('getLifecycleBackend', () => {
+  it('falls back to a web backend', () => {
+    expect(getLifecycleBackend()).not.toBeNull();
+  });
+});
+
+describe('isAppActive', () => {
+  it("returns true when state is 'active'", () => {
+    const backend = fakeBackend();
+    backend.state = 'active';
+    setLifecycleBackend(backend);
+    expect(isAppActive()).toBe(true);
+  });
+
+  it("returns false when state is 'background'", () => {
+    const backend = fakeBackend();
+    backend.state = 'background';
+    setLifecycleBackend(backend);
+    expect(isAppActive()).toBe(false);
+  });
+
+  it("returns false when state is 'inactive'", () => {
+    const backend = fakeBackend();
+    backend.state = 'inactive';
+    setLifecycleBackend(backend);
+    expect(isAppActive()).toBe(false);
+  });
+});
+
+describe('isAppBackground', () => {
+  it("returns true when state is 'background'", () => {
+    const backend = fakeBackend();
+    backend.state = 'background';
+    setLifecycleBackend(backend);
+    expect(isAppBackground()).toBe(true);
+  });
+
+  it("returns false when state is 'active'", () => {
+    const backend = fakeBackend();
+    backend.state = 'active';
+    setLifecycleBackend(backend);
+    expect(isAppBackground()).toBe(false);
+  });
+});
+
+describe('isAppInactive', () => {
+  it("returns true when state is 'inactive'", () => {
+    const backend = fakeBackend();
+    backend.state = 'inactive';
+    setLifecycleBackend(backend);
+    expect(isAppInactive()).toBe(true);
+  });
+
+  it("returns false when state is 'active'", () => {
+    const backend = fakeBackend();
+    backend.state = 'active';
+    setLifecycleBackend(backend);
+    expect(isAppInactive()).toBe(false);
+  });
+});
+
+describe('requestAppBack', () => {
+  it('returns true when no listener vetoes', () => {
+    const app = createAppLifecycle();
+    expect(requestAppBack(app)).toBe(true);
+  });
+
+  it('returns false when a listener calls cancelSignal', () => {
+    const app = createAppLifecycle();
+    connectSignal(app.onBackButton, () => cancelSignal(app.onBackButton));
+    expect(requestAppBack(app)).toBe(false);
+  });
+
+  it('emits onBackButton', () => {
+    const app = createAppLifecycle();
+    let fired = 0;
+    connectSignal(app.onBackButton, () => fired++);
+    requestAppBack(app);
+    expect(fired).toBe(1);
+  });
+});
+
+describe('setLifecycleBackend', () => {
+  it('clears back to the web fallback when passed null', () => {
+    setLifecycleBackend(fakeBackend());
+    setLifecycleBackend(null);
+    expect(getLifecycleBackend()).not.toBeNull();
+  });
+});