@mizchi/playwright-faults 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mizchi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# @mizchi/playwright-faults
+
+Playwright fault-injection primitives at three layers, extracted from chaosbringer:
+
+| Layer | API surface | Where |
+|---|---|---|
+| Network | `FaultRule` + `faults.{status, abort, delay}` builders | Playwright `route()` |
+| Page lifecycle | `LifecycleFault` + `compileLifecycleFaults` + `PlaywrightLifecycleExecutor` | Playwright `Page` / `BrowserContext` / CDP at named stages |
+| JS runtime | `RuntimeFault` + `compileRuntimeFaults` + `buildRuntimeFaultsScript` | Playwright `addInitScript` per page nav |
+
+## Install
+
+```bash
+pnpm add @mizchi/playwright-faults
+pnpm add playwright   # peer
+```
+
+Requires Node 20+.
+
+## Network-level faults (FaultRule)
+
+```ts
+import { faults } from "@mizchi/playwright-faults";
+
+const rules = [
+  faults.status(500, { urlPattern: /\/api\// }),
+  faults.abort({ urlPattern: /tracking/ }),
+  faults.delay(2000, { urlPattern: /\/api\// }),
+];
+
+// Wire into Playwright's route() yourself, or pass to chaosbringer:
+//   new ChaosCrawler({ baseUrl, faultInjection: rules })
+```
+
+## Page-lifecycle faults
+
+```ts
+import {
+  PlaywrightLifecycleExecutor,
+  compileLifecycleFaults,
+  executeLifecycleAction,
+  lifecycleFaultsAtStage,
+  shouldFireProbability,
+} from "@mizchi/playwright-faults";
+
+const compiled = compileLifecycleFaults([
+  { when: "afterLoad", action: { kind: "clear-storage", scopes: ["localStorage"] } },
+  { when: "betweenActions", action: { kind: "cpu-throttle", rate: 4 } },
+]);
+
+const executor = new PlaywrightLifecycleExecutor(page, browserContext);
+for (const cf of lifecycleFaultsAtStage(compiled, "afterLoad", url)) {
+  if (shouldFireProbability(cf.fault.probability, rng)) {
+    await executeLifecycleAction(executor, cf.fault.action);
+  }
+}
+```
+
+## JS-runtime faults (addInitScript)
+
+```ts
+import { buildRuntimeFaultsScript, compileRuntimeFaults, mergeRuntimeStats } from "@mizchi/playwright-faults";
+
+const compiled = compileRuntimeFaults([
+  { action: { kind: "flaky-fetch", rejectionMessage: "synthetic network error" }, probability: 0.1 },
+  { action: { kind: "clock-skew", skewMs: 10 * 60 * 1000 } },
+]);
+
+await page.addInitScript(buildRuntimeFaultsScript(compiled, seed));
+
+// After navigations: drain per-page stats and merge
+const pageStats = await page.evaluate(() => globalThis.__chaosbringerRuntimeStats);
+mergeRuntimeStats(compiled, pageStats);
+```
+
+## RNG contract
+
+Functions that need randomness (`shouldFireProbability`, etc.) accept any object with `next(): number` returning `[0, 1)`. Bring your own — chaosbringer uses its seeded mulberry32; vitest tests can pass `Math.random`-flavor stubs.
+
+## License
+
+MIT

package/dist/faults.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Small helper functions that build FaultRule objects without the
+ * discriminated-union ceremony. Exported from the package root.
+ *
+ *   import { faults } from "chaosbringer";
+ *   const rules = [
+ *     faults.status(500, { urlPattern: /\/api\// }),
+ *     faults.abort({ urlPattern: /tracking/ }),
+ *     faults.delay(2000, { urlPattern: /\/api\// }),
+ *   ];
+ */
+import type { FaultRule, LifecycleFault, LifecycleStage, RuntimeFault, StorageScope, UrlMatcher } from "./types.js";
+export interface FaultHelperOptions {
+    urlPattern: UrlMatcher;
+    methods?: string[];
+    probability?: number;
+    name?: string;
+}
+/** Common options accepted by every lifecycle fault helper. */
+export interface LifecycleHelperOptions {
+    /** Override the helper's default lifecycle stage. */
+    when?: LifecycleStage;
+    /** Restrict the fault to URLs matching this matcher. */
+    urlPattern?: UrlMatcher;
+    /** 0..1, default 1.0. Uses the crawler's seeded RNG. */
+    probability?: number;
+    /** Override the auto-derived stats name. */
+    name?: string;
+}
+export declare const faults: {
+    /** Respond with `status` (and optional body / content-type). */
+    status(status: number, opts: FaultHelperOptions & {
+        body?: string;
+        contentType?: string;
+    }): FaultRule;
+    /** Abort the request (e.g. to simulate a blocked third-party or transport failure). */
+    abort(opts: FaultHelperOptions & {
+        errorCode?: string;
+    }): FaultRule;
+    /** Wait `ms` milliseconds, then continue the request unchanged. */
+    delay(ms: number, opts: FaultHelperOptions): FaultRule;
+    /**
+     * Apply CDP CPU throttling. `rate` is a multiplier ≥ 1 (1 = no throttle,
+     * 4 = ~4× slower). Default stage is `beforeNavigation` so the load itself
+     * is slowed.
+     */
+    cpu(rate: number, opts?: LifecycleHelperOptions): LifecycleFault;
+    /**
+     * Wipe the listed storage scopes. Cookies are cleared at the BrowserContext
+     * level; `localStorage` / `sessionStorage` / `indexedDB` are cleared in-page.
+     * Default stage is `afterLoad` so the page exists when the wipe runs.
+     */
+    clearStorage(opts: LifecycleHelperOptions & {
+        scopes: StorageScope[];
+    }): LifecycleFault;
+    /**
+     * Drop entries from the Service Worker `caches` API. With no `cacheNames`,
+     * every cache is dropped. Default stage is `beforeActions` so the wipe
+     * happens after invariants but before chaos clicks.
+     */
+    evictCache(opts?: LifecycleHelperOptions & {
+        cacheNames?: string[];
+    }): LifecycleFault;
+    /**
+     * Set a single key/value in `localStorage` or `sessionStorage`. Empty value
+     * mimics a logged-out / token-cleared state without dropping unrelated keys.
+     */
+    tamperStorage(opts: LifecycleHelperOptions & {
+        scope: "localStorage" | "sessionStorage";
+        key: string;
+        value: string;
+    }): LifecycleFault;
+    /**
+     * Reject `window.fetch` calls before any network round-trip. Different
+     * from `faults.abort()` (request-scoped, applied via Playwright `route`):
+     * `flakyFetch` rejects the Promise client-side with a TypeError, so any
+     * `try/catch` and Service-Worker fallbacks downstream of `fetch` engage
+     * just like a real "Failed to fetch" event.
+     */
+    flakyFetch(opts?: RuntimeHelperOptions & {
+        rejectionMessage?: string;
+    }): RuntimeFault;
+    /**
+     * Skew `Date.now()`, `performance.now()`, and the no-arg `Date`
+     * constructor forward by `skewMs`. Use to surface token-expiry,
+     * cache-bust, and "clock drift" code paths without waiting real time.
+     */
+    clockSkew(skewMs: number, opts?: RuntimeHelperOptions): RuntimeFault;
+};
+export interface RuntimeHelperOptions {
+    /** Restrict the fault to pages whose URL matches this matcher. */
+    urlPattern?: UrlMatcher;
+    /** 0..1, default 1.0. Rolled per call against the in-page seeded RNG. */
+    probability?: number;
+    /** Override the auto-derived stats name. */
+    name?: string;
+}
+//# sourceMappingURL=faults.d.ts.map

package/dist/faults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"faults.d.ts","sourceRoot":"","sources":["../src/faults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,cAAc,EACd,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAUD,+DAA+D;AAC/D,MAAM,WAAW,sBAAsB;IACrC,qDAAqD;IACrD,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,wDAAwD;IACxD,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAcD,eAAO,MAAM,MAAM;IACjB,gEAAgE;mBAEtD,MAAM,QACR,kBAAkB,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GACjE,SAAS;IAaZ,uFAAuF;gBAC3E,kBAAkB,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS;IAWnE,mEAAmE;cACzD,MAAM,QAAQ,kBAAkB,GAAG,SAAS;IAQtD;;;;OAIG;cACO,MAAM,SAAS,sBAAsB,GAAG,cAAc;IAWhE;;;;OAIG;uBAEK,sBAAsB,GAAG;QAAE,MAAM,EAAE,YAAY,EAAE,CAAA;KAAE,GACxD,cAAc;IAWjB;;;;OAIG;sBAEM,sBAAsB,GAAG;QAAE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GACxD,cAAc;IAWjB;;;OAGG;wBAEK,sBAAsB,GAAG;QAC7B,KAAK,EAAE,cAAc,GAAG,gBAAgB,CAAC;QACzC,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,EAAE,MAAM,CAAC;KACf,GACA,cAAc;IAajB;;;;;;OAMG;sBACe,oBAAoB,GAAG;QAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,YAAY;IAYrF;;;;OAIG;sBACe,MAAM,SAAS,oBAAoB,GAAG,YAAY;CAOrE,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,kEAAkE;IAClE,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf"}

package/dist/faults.js

@@ -0,0 +1,165 @@
+/**
+ * Small helper functions that build FaultRule objects without the
+ * discriminated-union ceremony. Exported from the package root.
+ *
+ *   import { faults } from "chaosbringer";
+ *   const rules = [
+ *     faults.status(500, { urlPattern: /\/api\// }),
+ *     faults.abort({ urlPattern: /tracking/ }),
+ *     faults.delay(2000, { urlPattern: /\/api\// }),
+ *   ];
+ */
+function applyCommon(rule, opts) {
+    rule.urlPattern = opts.urlPattern;
+    if (opts.methods !== undefined)
+        rule.methods = opts.methods;
+    if (opts.probability !== undefined)
+        rule.probability = opts.probability;
+    if (opts.name !== undefined)
+        rule.name = opts.name;
+    return rule;
+}
+function applyLifecycleCommon(fault, opts, defaultStage) {
+    fault.when = opts?.when ?? defaultStage;
+    if (opts?.urlPattern !== undefined)
+        fault.urlPattern = opts.urlPattern;
+    if (opts?.probability !== undefined)
+        fault.probability = opts.probability;
+    if (opts?.name !== undefined)
+        fault.name = opts.name;
+    return fault;
+}
+export const faults = {
+    /** Respond with `status` (and optional body / content-type). */
+    status(status, opts) {
+        const rule = {
+            urlPattern: opts.urlPattern,
+            fault: {
+                kind: "status",
+                status,
+                ...(opts.body !== undefined ? { body: opts.body } : {}),
+                ...(opts.contentType !== undefined ? { contentType: opts.contentType } : {}),
+            },
+        };
+        return applyCommon(rule, opts);
+    },
+    /** Abort the request (e.g. to simulate a blocked third-party or transport failure). */
+    abort(opts) {
+        const rule = {
+            urlPattern: opts.urlPattern,
+            fault: {
+                kind: "abort",
+                ...(opts.errorCode !== undefined ? { errorCode: opts.errorCode } : {}),
+            },
+        };
+        return applyCommon(rule, opts);
+    },
+    /** Wait `ms` milliseconds, then continue the request unchanged. */
+    delay(ms, opts) {
+        const rule = {
+            urlPattern: opts.urlPattern,
+            fault: { kind: "delay", ms },
+        };
+        return applyCommon(rule, opts);
+    },
+    /**
+     * Apply CDP CPU throttling. `rate` is a multiplier ≥ 1 (1 = no throttle,
+     * 4 = ~4× slower). Default stage is `beforeNavigation` so the load itself
+     * is slowed.
+     */
+    cpu(rate, opts) {
+        if (!Number.isFinite(rate) || rate < 1) {
+            throw new Error(`faults.cpu: rate must be a finite number >= 1 (got ${rate})`);
+        }
+        const fault = {
+            when: "beforeNavigation",
+            action: { kind: "cpu-throttle", rate },
+        };
+        return applyLifecycleCommon(fault, opts, "beforeNavigation");
+    },
+    /**
+     * Wipe the listed storage scopes. Cookies are cleared at the BrowserContext
+     * level; `localStorage` / `sessionStorage` / `indexedDB` are cleared in-page.
+     * Default stage is `afterLoad` so the page exists when the wipe runs.
+     */
+    clearStorage(opts) {
+        if (!opts.scopes || opts.scopes.length === 0) {
+            throw new Error("faults.clearStorage: at least one scope is required");
+        }
+        const fault = {
+            when: "afterLoad",
+            action: { kind: "clear-storage", scopes: [...opts.scopes] },
+        };
+        return applyLifecycleCommon(fault, opts, "afterLoad");
+    },
+    /**
+     * Drop entries from the Service Worker `caches` API. With no `cacheNames`,
+     * every cache is dropped. Default stage is `beforeActions` so the wipe
+     * happens after invariants but before chaos clicks.
+     */
+    evictCache(opts) {
+        const fault = {
+            when: "beforeActions",
+            action: opts?.cacheNames !== undefined
+                ? { kind: "evict-cache", cacheNames: [...opts.cacheNames] }
+                : { kind: "evict-cache" },
+        };
+        return applyLifecycleCommon(fault, opts, "beforeActions");
+    },
+    /**
+     * Set a single key/value in `localStorage` or `sessionStorage`. Empty value
+     * mimics a logged-out / token-cleared state without dropping unrelated keys.
+     */
+    tamperStorage(opts) {
+        const fault = {
+            when: "afterLoad",
+            action: {
+                kind: "tamper-storage",
+                scope: opts.scope,
+                key: opts.key,
+                value: opts.value,
+            },
+        };
+        return applyLifecycleCommon(fault, opts, "afterLoad");
+    },
+    /**
+     * Reject `window.fetch` calls before any network round-trip. Different
+     * from `faults.abort()` (request-scoped, applied via Playwright `route`):
+     * `flakyFetch` rejects the Promise client-side with a TypeError, so any
+     * `try/catch` and Service-Worker fallbacks downstream of `fetch` engage
+     * just like a real "Failed to fetch" event.
+     */
+    flakyFetch(opts) {
+        const fault = {
+            action: {
+                kind: "flaky-fetch",
+                ...(opts?.rejectionMessage !== undefined
+                    ? { rejectionMessage: opts.rejectionMessage }
+                    : {}),
+            },
+        };
+        return applyRuntimeCommon(fault, opts);
+    },
+    /**
+     * Skew `Date.now()`, `performance.now()`, and the no-arg `Date`
+     * constructor forward by `skewMs`. Use to surface token-expiry,
+     * cache-bust, and "clock drift" code paths without waiting real time.
+     */
+    clockSkew(skewMs, opts) {
+        if (!Number.isFinite(skewMs) || !Number.isInteger(skewMs)) {
+            throw new Error(`faults.clockSkew: skewMs must be a finite integer (got ${skewMs})`);
+        }
+        const fault = { action: { kind: "clock-skew", skewMs } };
+        return applyRuntimeCommon(fault, opts);
+    },
+};
+function applyRuntimeCommon(fault, opts) {
+    if (opts?.urlPattern !== undefined)
+        fault.urlPattern = opts.urlPattern;
+    if (opts?.probability !== undefined)
+        fault.probability = opts.probability;
+    if (opts?.name !== undefined)
+        fault.name = opts.name;
+    return fault;
+}
+//# sourceMappingURL=faults.js.map

package/dist/faults.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { Fault, FaultInjectionStats, FaultRule, LifecycleAction, LifecycleFault, LifecycleFaultStats, LifecycleStage, Rng, RuntimeAction, RuntimeFault, RuntimeFaultStats, StorageScope, UrlMatcher, } from "./types.js";
+export { faults, type FaultHelperOptions, type LifecycleHelperOptions, type RuntimeHelperOptions, } from "./faults.js";
+export { buildRuntimeFaultsScript, compileRuntimeFaults, mergeRuntimeStats, runtimeFaultName, runtimeMatchesUrl, type CompiledRuntimeFault, } from "./runtime-faults.js";
+export { compileLifecycleFaults, executeLifecycleAction, lifecycleFaultName, lifecycleFaultsAtStage, lifecycleMatchesUrl, lifecycleStatsFrom, PlaywrightLifecycleExecutor, shouldFireProbability, type CompiledLifecycleFault, type LifecycleActionExecutor, } from "./lifecycle-faults.js";
+//# 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":"AACA,YAAY,EACV,KAAK,EACL,mBAAmB,EACnB,SAAS,EACT,eAAe,EACf,cAAc,EACd,mBAAmB,EACnB,cAAc,EACd,GAAG,EACH,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,UAAU,GACX,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,MAAM,EACN,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,oBAAoB,GAC1B,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,oBAAoB,GAC1B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,kBAAkB,EAClB,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EAClB,2BAA2B,EAC3B,qBAAqB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,GAC7B,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+// Network-level (FaultRule helpers + builders)
+export { faults, } from "./faults.js";
+// Runtime-level (addInitScript-based monkey patches)
+export { buildRuntimeFaultsScript, compileRuntimeFaults, mergeRuntimeStats, runtimeFaultName, runtimeMatchesUrl, } from "./runtime-faults.js";
+// Page lifecycle (Playwright Page / BrowserContext at named stages)
+export { compileLifecycleFaults, executeLifecycleAction, lifecycleFaultName, lifecycleFaultsAtStage, lifecycleMatchesUrl, lifecycleStatsFrom, PlaywrightLifecycleExecutor, shouldFireProbability, } from "./lifecycle-faults.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiBA,+CAA+C;AAC/C,OAAO,EACL,MAAM,GAIP,MAAM,aAAa,CAAC;AAErB,qDAAqD;AACrD,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,GAElB,MAAM,qBAAqB,CAAC;AAE7B,oEAAoE;AACpE,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,kBAAkB,EAClB,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EAClB,2BAA2B,EAC3B,qBAAqB,GAGtB,MAAM,uBAAuB,CAAC"}

package/dist/lifecycle-faults.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Page-lifecycle fault injection.
+ *
+ * Distinct from network-side `FaultRule` (request-scoped, applied via
+ * Playwright `route()`). These are page-scoped client-side perturbations
+ * applied at well-defined stages of a page visit — CPU throttle, storage
+ * wipe, Service Worker cache eviction, key/value tampering. The crawler
+ * decides when to call into the executor; the executor decides how to
+ * realise each `LifecycleAction` against the browser.
+ *
+ * Pure helpers (compile / match / probability roll / name derivation) live
+ * here so the routing logic is unit-testable without a real browser. The
+ * Playwright-backed executor lives at the bottom of this file.
+ */
+import type { BrowserContext, Page } from "playwright";
+import type { LifecycleAction, LifecycleFault, LifecycleFaultStats, LifecycleStage } from "./types.js";
+/** Compiled form: regex pre-compiled, name pre-derived. */
+export interface CompiledLifecycleFault {
+    fault: LifecycleFault;
+    /** null when `fault.urlPattern` was omitted (matches every URL). */
+    pattern: RegExp | null;
+    name: string;
+    matched: number;
+    fired: number;
+    errored: number;
+}
+/** Auto-derive a stats label when the user didn't set `fault.name`. */
+export declare function lifecycleFaultName(fault: LifecycleFault): string;
+export declare function compileLifecycleFaults(faults: LifecycleFault[] | undefined): CompiledLifecycleFault[];
+/** True when `compiled.pattern` matches `url` (or no pattern was set). */
+export declare function lifecycleMatchesUrl(compiled: Pick<CompiledLifecycleFault, "pattern">, url: string): boolean;
+/**
+ * Roll the seeded RNG against `probability`. Returns true when the fault
+ * should fire. `prob >= 1` (or undefined) always fires; `prob <= 0` never
+ * fires; anything in between samples one number from `rng`.
+ *
+ * RNG consumption is deliberately conditional on `prob < 1` so that adding
+ * a probability-1 fault to a config doesn't shift the seed sequence for
+ * existing chaos action selection.
+ */
+export declare function shouldFireProbability(prob: number | undefined, rng: {
+    next(): number;
+}): boolean;
+/** Pick the compiled faults that target a given lifecycle stage. */
+export declare function lifecycleFaultsAtStage(compiled: readonly CompiledLifecycleFault[], stage: LifecycleStage): CompiledLifecycleFault[];
+export declare function lifecycleStatsFrom(compiled: readonly CompiledLifecycleFault[]): LifecycleFaultStats[];
+/**
+ * Browser-side primitives needed to realise each `LifecycleAction`. One
+ * method per action kind so tests can fake exactly what they exercise
+ * without standing up Playwright.
+ */
+export interface LifecycleActionExecutor {
+    cpuThrottle(rate: number): Promise<void>;
+    clearStorage(scopes: readonly ("localStorage" | "sessionStorage" | "cookies" | "indexedDB")[]): Promise<void>;
+    evictCache(cacheNames?: readonly string[]): Promise<void>;
+    tamperStorage(scope: "localStorage" | "sessionStorage", key: string, value: string): Promise<void>;
+}
+/** Dispatch a single `LifecycleAction` to the right executor method. */
+export declare function executeLifecycleAction(action: LifecycleAction, executor: LifecycleActionExecutor): Promise<void>;
+/**
+ * Real executor backed by Playwright. CPU throttle requires a CDP session;
+ * we attach lazily and reuse across calls on the same page.
+ */
+export declare class PlaywrightLifecycleExecutor implements LifecycleActionExecutor {
+    private readonly page;
+    private readonly context;
+    private cdp;
+    constructor(page: Page, context: BrowserContext);
+    private getCdp;
+    cpuThrottle(rate: number): Promise<void>;
+    clearStorage(scopes: readonly ("localStorage" | "sessionStorage" | "cookies" | "indexedDB")[]): Promise<void>;
+    evictCache(cacheNames?: readonly string[]): Promise<void>;
+    tamperStorage(scope: "localStorage" | "sessionStorage", key: string, value: string): Promise<void>;
+}
+//# sourceMappingURL=lifecycle-faults.d.ts.map

package/dist/lifecycle-faults.d.ts.map

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