@mizchi/playwright-faults 0.1.0

package/dist/lifecycle-faults.js

@@ -0,0 +1,187 @@
+/**
+ * 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.
+ */
+/** Auto-derive a stats label when the user didn't set `fault.name`. */
+export function lifecycleFaultName(fault) {
+    if (fault.name)
+        return fault.name;
+    const a = fault.action;
+    switch (a.kind) {
+        case "cpu-throttle":
+            return `cpu-throttle:${a.rate}x`;
+        case "clear-storage":
+            return `clear-storage:${a.scopes.join("+")}`;
+        case "evict-cache":
+            return a.cacheNames && a.cacheNames.length > 0
+                ? `evict-cache:${a.cacheNames.join("+")}`
+                : "evict-cache";
+        case "tamper-storage":
+            return `tamper-storage:${a.scope}.${a.key}`;
+    }
+}
+function compilePattern(matcher) {
+    if (matcher === undefined)
+        return null;
+    return matcher instanceof RegExp ? matcher : new RegExp(matcher);
+}
+export function compileLifecycleFaults(faults) {
+    if (!faults || faults.length === 0)
+        return [];
+    return faults.map((fault) => ({
+        fault,
+        pattern: compilePattern(fault.urlPattern),
+        name: lifecycleFaultName(fault),
+        matched: 0,
+        fired: 0,
+        errored: 0,
+    }));
+}
+/** True when `compiled.pattern` matches `url` (or no pattern was set). */
+export function lifecycleMatchesUrl(compiled, url) {
+    return compiled.pattern === null || compiled.pattern.test(url);
+}
+/**
+ * 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 function shouldFireProbability(prob, rng) {
+    if (prob === undefined || prob >= 1)
+        return true;
+    if (prob <= 0)
+        return false;
+    return rng.next() < prob;
+}
+/** Pick the compiled faults that target a given lifecycle stage. */
+export function lifecycleFaultsAtStage(compiled, stage) {
+    return compiled.filter((c) => c.fault.when === stage);
+}
+export function lifecycleStatsFrom(compiled) {
+    return compiled.map((c) => ({
+        name: c.name,
+        matched: c.matched,
+        fired: c.fired,
+        errored: c.errored,
+    }));
+}
+/** Dispatch a single `LifecycleAction` to the right executor method. */
+export async function executeLifecycleAction(action, executor) {
+    switch (action.kind) {
+        case "cpu-throttle":
+            await executor.cpuThrottle(action.rate);
+            return;
+        case "clear-storage":
+            await executor.clearStorage(action.scopes);
+            return;
+        case "evict-cache":
+            await executor.evictCache(action.cacheNames);
+            return;
+        case "tamper-storage":
+            await executor.tamperStorage(action.scope, action.key, action.value);
+            return;
+    }
+}
+/**
+ * Real executor backed by Playwright. CPU throttle requires a CDP session;
+ * we attach lazily and reuse across calls on the same page.
+ */
+export class PlaywrightLifecycleExecutor {
+    page;
+    context;
+    cdp = null;
+    constructor(page, context) {
+        this.page = page;
+        this.context = context;
+    }
+    getCdp() {
+        if (this.cdp === null) {
+            this.cdp = this.context.newCDPSession(this.page);
+        }
+        return this.cdp;
+    }
+    async cpuThrottle(rate) {
+        const client = await this.getCdp();
+        await client.send("Emulation.setCPUThrottlingRate", { rate });
+    }
+    async clearStorage(scopes) {
+        const inPage = scopes.filter((s) => s !== "cookies");
+        if (inPage.length > 0) {
+            // page.evaluate runs in the page context; we pass the scope set so the
+            // browser side decides which storages to wipe without us injecting JS.
+            await this.page.evaluate(async (scopeList) => {
+                const s = new Set(scopeList);
+                if (s.has("localStorage")) {
+                    try {
+                        window.localStorage.clear();
+                    }
+                    catch {
+                        /* SecurityError on opaque origins */
+                    }
+                }
+                if (s.has("sessionStorage")) {
+                    try {
+                        window.sessionStorage.clear();
+                    }
+                    catch {
+                        /* SecurityError on opaque origins */
+                    }
+                }
+                if (s.has("indexedDB") && "indexedDB" in window) {
+                    // databases() is not in every browser; guard.
+                    // @ts-ignore - older lib.dom typings omit databases()
+                    const dbs = (await indexedDB.databases?.()) ?? [];
+                    await Promise.all(dbs
+                        .map((d) => d.name)
+                        .filter((n) => typeof n === "string")
+                        .map((name) => new Promise((resolve) => {
+                        const req = indexedDB.deleteDatabase(name);
+                        req.onsuccess = () => resolve();
+                        req.onerror = () => resolve();
+                        req.onblocked = () => resolve();
+                    })));
+                }
+            }, inPage);
+        }
+        if (scopes.includes("cookies")) {
+            // Context-level: drops every cookie across every page in the context.
+            await this.context.clearCookies();
+        }
+    }
+    async evictCache(cacheNames) {
+        await this.page.evaluate(async (names) => {
+            if (!("caches" in self))
+                return;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const c = self.caches;
+            const all = await c.keys();
+            const target = names && names.length > 0 ? all.filter((k) => names.includes(k)) : all;
+            await Promise.all(target.map((k) => c.delete(k)));
+        }, cacheNames);
+    }
+    async tamperStorage(scope, key, value) {
+        await this.page.evaluate(({ scope, key, value }) => {
+            try {
+                (scope === "localStorage" ? window.localStorage : window.sessionStorage).setItem(key, value);
+            }
+            catch {
+                /* SecurityError on opaque origins */
+            }
+        }, { scope, key, value });
+    }
+}
+//# sourceMappingURL=lifecycle-faults.js.map

package/dist/lifecycle-faults.js.map

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

package/dist/random.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tiny seeded RNG used by the package's own unit tests so they don't have
+ * to depend on chaosbringer. Not part of the public surface — only re-export
+ * from `index.ts` if a downstream legitimately needs the same generator
+ * function (most won't; they'll bring their own RNG).
+ */
+import type { Rng } from "./types.js";
+export interface SeededRng extends Rng {
+    readonly seed: number;
+}
+export declare function createRng(seed: number): SeededRng;
+//# sourceMappingURL=random.d.ts.map

package/dist/random.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"random.d.ts","sourceRoot":"","sources":["../src/random.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAEtC,MAAM,WAAW,SAAU,SAAQ,GAAG;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAYjD"}

package/dist/random.js

@@ -0,0 +1,20 @@
+/**
+ * Tiny seeded RNG used by the package's own unit tests so they don't have
+ * to depend on chaosbringer. Not part of the public surface — only re-export
+ * from `index.ts` if a downstream legitimately needs the same generator
+ * function (most won't; they'll bring their own RNG).
+ */
+export function createRng(seed) {
+    let state = seed >>> 0;
+    return {
+        seed,
+        next() {
+            state = (state + 0x6d2b79f5) >>> 0;
+            let t = state;
+            t = Math.imul(t ^ (t >>> 15), t | 1);
+            t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+            return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+        },
+    };
+}
+//# sourceMappingURL=random.js.map

package/dist/random.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"random.js","sourceRoot":"","sources":["../src/random.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,IAAI,KAAK,GAAG,IAAI,KAAK,CAAC,CAAC;IACvB,OAAO;QACL,IAAI;QACJ,IAAI;YACF,KAAK,GAAG,CAAC,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;YACnC,IAAI,CAAC,GAAG,KAAK,CAAC;YACd,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;YACrC,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;YAC1C,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,UAAU,CAAC;QAC/C,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/runtime-faults.d.ts

@@ -0,0 +1,71 @@
+/**
+ * JS-runtime fault injection.
+ *
+ * Distinct from `FaultRule` (request-scoped, applied via Playwright `route()`)
+ * and `LifecycleFault` (one-shot at named stages of a page visit). These are
+ * persistent monkey-patches injected into every page via `addInitScript`,
+ * subverting in-page JS APIs (fetch / Date / storage / addEventListener) so
+ * the app sees client-side failures that no network mock would expose.
+ *
+ * Examples:
+ *   - `flaky-fetch`: `window.fetch` rejects with a TypeError before any
+ *     network round-trip — simulates "Failed to fetch" / DNS down / Service
+ *     Worker reject. Different from `faults.status(500)`, which still
+ *     resolves the promise.
+ *   - `clock-skew`: `Date.now` / `performance.now` are shifted forward by N
+ *     ms — exposes token-expiry / cache-bust bugs on long sessions.
+ *
+ * Pure helpers (`buildRuntimeFaultsScript`, `runtimeFaultName`,
+ * `compileRuntimeFaults`) generate / serialize the init script and roll
+ * probability — unit-testable without a browser. Stats are reported by the
+ * in-page script via a known `window.__chaosbringerRuntimeStats` global; the
+ * crawler reads it after each page visit.
+ */
+import type { Rng, RuntimeFault, RuntimeFaultStats } from "./types.js";
+/** Compiled form: regex pre-compiled, name pre-derived. */
+export interface CompiledRuntimeFault {
+    fault: RuntimeFault;
+    /** null when `fault.urlPattern` was omitted. */
+    pattern: RegExp | null;
+    name: string;
+    matched: number;
+    fired: number;
+}
+/** Auto-derive a stats label when the user didn't set `fault.name`. */
+export declare function runtimeFaultName(fault: RuntimeFault): string;
+export declare function compileRuntimeFaults(faults: RuntimeFault[] | undefined): CompiledRuntimeFault[];
+/** True when `compiled.pattern` matches `url` (or no pattern was set). */
+export declare function runtimeMatchesUrl(compiled: Pick<CompiledRuntimeFault, "pattern">, url: string): boolean;
+/**
+ * Decide whether a probabilistic fault fires this time. Mirrors the
+ * lifecycle / network helpers so all three layers share a deterministic
+ * roll behaviour given the same RNG.
+ */
+export declare function shouldFireProbability(probability: number | undefined, rng: Rng): boolean;
+/**
+ * Build the init script body. Self-contained IIFE — no closure over the
+ * caller's scope, no external imports — because Playwright serializes init
+ * scripts as plain text and runs them in a fresh frame on every navigation.
+ *
+ * `seed` lets each page roll deterministic probabilities. Pass the
+ * crawler's seed so a `(seed, runtimeFaults)` pair always produces the same
+ * pattern of injections.
+ */
+export declare function buildRuntimeFaultsScript(faults: ReadonlyArray<RuntimeFault>, seed: number): string;
+/**
+ * Read the in-page stats counter and merge into the compiled-fault counters
+ * (`matched` and `fired`). Returns the merged stats; the compiled-fault
+ * objects are mutated in place so the next page picks up where this one
+ * left off.
+ *
+ * Stats keys are array indices so two faults with the same name don't
+ * collide their counters. Both legacy name-keyed snapshots and the
+ * current index-keyed shape are accepted: name-keyed entries are applied
+ * to the first compiled fault with that name (the safe, non-collapsing
+ * fallback used when reading older traces).
+ */
+export declare function mergeRuntimeStats(compiled: CompiledRuntimeFault[], pageStats: Record<string, {
+    matched: number;
+    fired: number;
+}>): RuntimeFaultStats[];
+//# sourceMappingURL=runtime-faults.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-faults.d.ts","sourceRoot":"","sources":["../src/runtime-faults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,YAAY,EAAE,iBAAiB,EAAc,MAAM,YAAY,CAAC;AAEnF,2DAA2D;AAC3D,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,YAAY,CAAC;IACpB,gDAAgD;IAChD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,uEAAuE;AACvE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAS5D;AAOD,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,YAAY,EAAE,GAAG,SAAS,GACjC,oBAAoB,EAAE,CASxB;AAED,0EAA0E;AAC1E,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,IAAI,CAAC,oBAAoB,EAAE,SAAS,CAAC,EAC/C,GAAG,EAAE,MAAM,GACV,OAAO,CAET;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAKxF;AAYD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,aAAa,CAAC,YAAY,CAAC,EACnC,IAAI,EAAE,MAAM,GACX,MAAM,CA0GR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,oBAAoB,EAAE,EAChC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,GAC5D,iBAAiB,EAAE,CAuBrB"}

package/dist/runtime-faults.js

@@ -0,0 +1,231 @@
+/**
+ * JS-runtime fault injection.
+ *
+ * Distinct from `FaultRule` (request-scoped, applied via Playwright `route()`)
+ * and `LifecycleFault` (one-shot at named stages of a page visit). These are
+ * persistent monkey-patches injected into every page via `addInitScript`,
+ * subverting in-page JS APIs (fetch / Date / storage / addEventListener) so
+ * the app sees client-side failures that no network mock would expose.
+ *
+ * Examples:
+ *   - `flaky-fetch`: `window.fetch` rejects with a TypeError before any
+ *     network round-trip — simulates "Failed to fetch" / DNS down / Service
+ *     Worker reject. Different from `faults.status(500)`, which still
+ *     resolves the promise.
+ *   - `clock-skew`: `Date.now` / `performance.now` are shifted forward by N
+ *     ms — exposes token-expiry / cache-bust bugs on long sessions.
+ *
+ * Pure helpers (`buildRuntimeFaultsScript`, `runtimeFaultName`,
+ * `compileRuntimeFaults`) generate / serialize the init script and roll
+ * probability — unit-testable without a browser. Stats are reported by the
+ * in-page script via a known `window.__chaosbringerRuntimeStats` global; the
+ * crawler reads it after each page visit.
+ */
+/** Auto-derive a stats label when the user didn't set `fault.name`. */
+export function runtimeFaultName(fault) {
+    if (fault.name)
+        return fault.name;
+    const a = fault.action;
+    switch (a.kind) {
+        case "flaky-fetch":
+            return "flaky-fetch";
+        case "clock-skew":
+            return `clock-skew:${a.skewMs}ms`;
+    }
+}
+function compilePattern(matcher) {
+    if (matcher === undefined)
+        return null;
+    return matcher instanceof RegExp ? matcher : new RegExp(matcher);
+}
+export function compileRuntimeFaults(faults) {
+    if (!faults || faults.length === 0)
+        return [];
+    return faults.map((fault) => ({
+        fault,
+        pattern: compilePattern(fault.urlPattern),
+        name: runtimeFaultName(fault),
+        matched: 0,
+        fired: 0,
+    }));
+}
+/** True when `compiled.pattern` matches `url` (or no pattern was set). */
+export function runtimeMatchesUrl(compiled, url) {
+    return compiled.pattern === null || compiled.pattern.test(url);
+}
+/**
+ * Decide whether a probabilistic fault fires this time. Mirrors the
+ * lifecycle / network helpers so all three layers share a deterministic
+ * roll behaviour given the same RNG.
+ */
+export function shouldFireProbability(probability, rng) {
+    const p = probability ?? 1;
+    if (p >= 1)
+        return true;
+    if (p <= 0)
+        return false;
+    return rng.next() < p;
+}
+/**
+ * Serialize a UrlMatcher into a structure the in-page script can rebuild
+ * without `eval`. Strings stay strings; RegExp becomes `{ source, flags }`.
+ */
+function serializeMatcher(m) {
+    if (m === undefined)
+        return null;
+    if (m instanceof RegExp)
+        return { source: m.source, flags: m.flags };
+    return { source: m, flags: "" };
+}
+/**
+ * Build the init script body. Self-contained IIFE — no closure over the
+ * caller's scope, no external imports — because Playwright serializes init
+ * scripts as plain text and runs them in a fresh frame on every navigation.
+ *
+ * `seed` lets each page roll deterministic probabilities. Pass the
+ * crawler's seed so a `(seed, runtimeFaults)` pair always produces the same
+ * pattern of injections.
+ */
+export function buildRuntimeFaultsScript(faults, seed) {
+    // Stats keys are indices, not names — two faults can legitimately share
+    // a name (`flaky-fetch` x2 with different urlPatterns) and we mustn't
+    // collapse their counters.
+    const serialized = faults.map((f, i) => ({
+        id: i,
+        name: runtimeFaultName(f),
+        pattern: serializeMatcher(f.urlPattern),
+        probability: typeof f.probability === "number" ? f.probability : 1,
+        action: f.action,
+    }));
+    // Body of the init script. Indented for readability; whitespace is fine
+    // because Playwright won't minify it.
+    return `(() => {
+  if (typeof window === "undefined") return;
+  if (window.__chaosbringerRuntimeFaultsInstalled) return;
+  window.__chaosbringerRuntimeFaultsInstalled = true;
+  window.__chaosbringerRuntimeStats = {};
+
+  // Park-Miller LCG — small, deterministic, good enough for fault rolls.
+  let __rng = ${seed >>> 0} || 1;
+  const __nextRoll = () => {
+    __rng = ((__rng * 16807) % 2147483647) | 0;
+    if (__rng <= 0) __rng += 2147483647;
+    return (__rng - 1) / 2147483646;
+  };
+
+  const faults = ${JSON.stringify(serialized)};
+  const stats = window.__chaosbringerRuntimeStats;
+  for (const f of faults) stats[String(f.id)] = { matched: 0, fired: 0 };
+
+  const matchUrl = (pattern, url) => {
+    if (!pattern) return true;
+    try {
+      return new RegExp(pattern.source, pattern.flags).test(url);
+    } catch {
+      return false;
+    }
+  };
+
+  const roll = (f) => {
+    const slot = stats[String(f.id)];
+    slot.matched++;
+    if (f.probability >= 1) {
+      slot.fired++;
+      return true;
+    }
+    if (f.probability <= 0) return false;
+    const fired = __nextRoll() < f.probability;
+    if (fired) slot.fired++;
+    return fired;
+  };
+
+  // --- flaky-fetch ---
+  const fetchFaults = faults.filter((f) => f.action.kind === "flaky-fetch");
+  if (fetchFaults.length > 0 && typeof window.fetch === "function") {
+    const realFetch = window.fetch.bind(window);
+    window.fetch = function chaosFetch(input, init) {
+      const url =
+        typeof input === "string" ? input :
+        input instanceof URL ? input.toString() :
+        (input && typeof input.url === "string") ? input.url :
+        "";
+      for (const f of fetchFaults) {
+        if (matchUrl(f.pattern, url) && roll(f)) {
+          const msg = f.action.rejectionMessage || "chaosbringer: simulated fetch failure";
+          return Promise.reject(new TypeError(msg));
+        }
+      }
+      return realFetch(input, init);
+    };
+  }
+
+  // --- clock-skew ---
+  const skewFaults = faults.filter((f) => f.action.kind === "clock-skew");
+  if (skewFaults.length > 0) {
+    // Use a plain accumulator. Multi-day skews (e.g. 30 days ~ 2.6e9 ms)
+    // exceed int32 max, so any '| 0' truncation here would flip them negative.
+    let totalSkew = 0;
+    for (const f of skewFaults) {
+      if (matchUrl(f.pattern, location.href) && roll(f)) {
+        totalSkew += Number(f.action.skewMs);
+      }
+    }
+    if (totalSkew !== 0) {
+      const realDateNow = Date.now.bind(Date);
+      Date.now = () => realDateNow() + totalSkew;
+      const realPerfNow = performance.now.bind(performance);
+      performance.now = () => realPerfNow() + totalSkew;
+      // Patch the Date constructor so \`new Date()\` (no args) also skews.
+      const RealDate = Date;
+      const SkewedDate = function (...args) {
+        if (args.length === 0) return new RealDate(realDateNow() + totalSkew);
+        // @ts-ignore
+        return new RealDate(...args);
+      };
+      SkewedDate.now = Date.now;
+      SkewedDate.UTC = RealDate.UTC;
+      SkewedDate.parse = RealDate.parse;
+      SkewedDate.prototype = RealDate.prototype;
+      // @ts-ignore
+      window.Date = SkewedDate;
+    }
+  }
+})();`;
+}
+/**
+ * Read the in-page stats counter and merge into the compiled-fault counters
+ * (`matched` and `fired`). Returns the merged stats; the compiled-fault
+ * objects are mutated in place so the next page picks up where this one
+ * left off.
+ *
+ * Stats keys are array indices so two faults with the same name don't
+ * collide their counters. Both legacy name-keyed snapshots and the
+ * current index-keyed shape are accepted: name-keyed entries are applied
+ * to the first compiled fault with that name (the safe, non-collapsing
+ * fallback used when reading older traces).
+ */
+export function mergeRuntimeStats(compiled, pageStats) {
+    for (let i = 0; i < compiled.length; i++) {
+        const c = compiled[i];
+        // Index-keyed (current shape).
+        const ps = pageStats[String(i)];
+        if (ps) {
+            c.matched += ps.matched;
+            c.fired += ps.fired;
+            continue;
+        }
+        // Backwards-compat: name-keyed (one slot per distinct name only;
+        // applied to the first compiled fault that wears that name).
+        const byName = pageStats[c.name];
+        if (byName && !compiled.slice(0, i).some((c2) => c2.name === c.name)) {
+            c.matched += byName.matched;
+            c.fired += byName.fired;
+        }
+    }
+    return compiled.map((c) => ({
+        rule: c.name,
+        matched: c.matched,
+        fired: c.fired,
+    }));
+}
+//# sourceMappingURL=runtime-faults.js.map

package/dist/runtime-faults.js.map

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