@buoy-gg/network 7.0.13 → 7.0.15

package/lib/typescript/network/hooks/useOverrideRules.d.ts

@@ -0,0 +1,29 @@
+import { type OverrideRuleDraft, type OverrideRulesState } from "../overrides/overrideRulesStore";
+import type { OverrideRule } from "../overrides/types";
+export interface UseOverrideRulesResult extends OverrideRulesState {
+    /** Rules that would actually fire — what the "active" banner counts. */
+    activeCount: number;
+    setEnabled: (enabled: boolean) => void;
+    /**
+     * Create or replace a rule. The ONLY write path the UI uses — see
+     * `overrideRulesStore.upsertRule`: the add/update primitives don't forward to
+     * the device, so calling them from the dashboard would silently do nothing.
+     */
+    upsertRule: (draft: OverrideRuleDraft & {
+        id?: string;
+    }) => OverrideRule | null;
+    setRuleEnabled: (id: string, enabled: boolean) => void;
+    removeRule: (id: string) => void;
+    clearRules: () => void;
+    /** Has this rule burned through its `times` budget? */
+    isRuleSpent: (rule: OverrideRule) => boolean;
+}
+/**
+ * Read + mutate the override rule list.
+ *
+ * `useSyncExternalStore` over the store's own subscribe/getState, which already
+ * hands out a stable state object per mutation (see `rebuild`) — so this can't
+ * tear and doesn't need a selector to stay cheap.
+ */
+export declare function useOverrideRules(): UseOverrideRulesResult;
+//# sourceMappingURL=useOverrideRules.d.ts.map

package/lib/typescript/network/hooks/useOverrideRules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOverrideRules.d.ts","sourceRoot":"","sources":["../../../../src/network/hooks/useOverrideRules.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACxB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACvC;;;;OAIG;IACH,UAAU,EAAE,CAAC,KAAK,EAAE,iBAAiB,GAAG;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,YAAY,GAAG,IAAI,CAAC;IAChF,cAAc,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACvD,UAAU,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,uDAAuD;IACvD,WAAW,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC;CAC9C;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,sBAAsB,CAsCzD"}

package/lib/typescript/network/overrides/__tests__/applyToFetch.test.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Unit tests for the fetch-side synthesis.
+ *
+ * This layer exists because of a finding that only showed up on a real device:
+ * Expo replaces `globalThis.fetch` with a NATIVE `expo/fetch` (see
+ * `expo/src/winter/runtime.native.ts`), so those requests never construct an
+ * XMLHttpRequest and an XHR-only override silently does nothing. Verified on
+ * Expo SDK 56 / RN 0.85.3.
+ *
+ * Same self-contained harness as the other tests — see the run command in
+ * `resolveOverride.test.ts`. Excluded from the publish build by
+ * `tsconfig.build.json`.
+ */
+declare function main(): Promise<void>;
+export { main as runApplyToFetchTests };
+//# sourceMappingURL=applyToFetch.test.d.ts.map

package/lib/typescript/network/overrides/__tests__/applyToFetch.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyToFetch.test.d.ts","sourceRoot":"","sources":["../../../../../src/network/overrides/__tests__/applyToFetch.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA2KH,iBAAe,IAAI,kBAsBlB;AAaD,OAAO,EAAE,IAAI,IAAI,oBAAoB,EAAE,CAAC"}

package/lib/typescript/network/overrides/__tests__/applyToXhr.test.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Unit tests for the XHR response synthesis, against a faithful clone of React
+ * Native's XMLHttpRequest state machine.
+ *
+ * WHY A CLONE RATHER THAN A MOCK: the interesting behaviour is not "did we set
+ * some fields", it's whether RN's own `setReadyState` / `abort` branches then
+ * do the right thing — which terminal event fires, and what `abort()` does when
+ * `_sent` is or isn't claimed. A mock that just records calls would pass while
+ * the real thing hung the app's fetch promise. `FakeRNXhr` below is transcribed
+ * from `react-native/Libraries/Network/XMLHttpRequest.js` (verified identical on
+ * RN 0.81.4 and 0.85.3), so these assertions are about real semantics.
+ *
+ * Same self-contained harness as the other tests — see the run command in
+ * `resolveOverride.test.ts`. Excluded from the publish build by
+ * `tsconfig.build.json`.
+ */
+declare function main(): Promise<void>;
+export { main as runApplyToXhrTests };
+//# sourceMappingURL=applyToXhr.test.d.ts.map

package/lib/typescript/network/overrides/__tests__/applyToXhr.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyToXhr.test.d.ts","sourceRoot":"","sources":["../../../../../src/network/overrides/__tests__/applyToXhr.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAqYH,iBAAe,IAAI,kBAuBlB;AAaD,OAAO,EAAE,IAAI,IAAI,kBAAkB,EAAE,CAAC"}

package/lib/typescript/network/overrides/__tests__/resolveOverride.test.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Unit tests for the override matcher + resolver — the pure half of the
+ * feature, and the half worth testing without a device.
+ *
+ * The glob cases mirror Chrome DevTools' own `escapeRegex` behaviour
+ * (`NetworkPersistenceManager.ts:1051`), because these patterns are the same
+ * syntax a developer already uses in Chrome's "Override headers" `applyTo`
+ * field and must not quietly mean something different here.
+ *
+ * Same self-contained harness as the perf-monitor tests (no Jest wired up yet);
+ * renames to Jest globals later. There is no `tsx` in this repo, so run it with
+ * the esbuild that is already here, from the repo root:
+ *
+ *   node_modules/.bin/esbuild <this file> --bundle --platform=node \
+ *     --format=cjs --outfile=/tmp/t.cjs && node /tmp/t.cjs
+ *
+ * `__tests__` is excluded from the publish build via `tsconfig.build.json`,
+ * so this file ships nowhere — it's developer infrastructure.
+ */
+declare function main(): Promise<void>;
+export { main as runResolveOverrideTests };
+//# sourceMappingURL=resolveOverride.test.d.ts.map

package/lib/typescript/network/overrides/__tests__/resolveOverride.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveOverride.test.d.ts","sourceRoot":"","sources":["../../../../../src/network/overrides/__tests__/resolveOverride.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA0XH,iBAAe,IAAI,kBAuBlB;AAeD,OAAO,EAAE,IAAI,IAAI,uBAAuB,EAAE,CAAC"}

package/lib/typescript/network/overrides/applyToFetch.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Perform an override outcome against `fetch`.
+ *
+ * WHY THIS EXISTS — and why "XHR is the single choke point" is WRONG:
+ *
+ * In bare React Native, `Libraries/Network/fetch.js` is `require('whatwg-fetch')`,
+ * so `fetch` really is a polyfill over XMLHttpRequest and hooking XHR alone
+ * would cover everything. But **Expo replaces it**: `expo/src/winter/runtime.native.ts`
+ * installs `expo/fetch` — a NATIVE fetch over `ExpoFetchModule` — as
+ * `globalThis.fetch` unless `EXPO_PUBLIC_USE_RN_FETCH=1`. Those requests never
+ * construct an XMLHttpRequest, so an XHR-only override silently does nothing on
+ * the majority of real apps.
+ *
+ * Verified the hard way on Expo SDK 56 / RN 0.85.3: rule matched, engine
+ * healthy, interceptor installed, and the request still came back a real 200.
+ *
+ * So overrides hook BOTH layers. `axios` still needs the XHR path (it uses
+ * XMLHttpRequest on every platform), and this covers `fetch` on both flavours.
+ */
+import type { OverrideOutcome } from "./types";
+export declare const sleep: (ms: number) => Promise<void>;
+/**
+ * Can we build a `Response` in this runtime?
+ *
+ * React Native installs the whatwg-fetch `Response` global via `setUpXHR`, and
+ * Expo deliberately keeps it (it only swaps `fetch`). Feature-detected anyway:
+ * without it, the honest thing is to let the request run for real.
+ */
+export declare function canSynthesizeResponse(): boolean;
+/**
+ * Build the fake `Response` an overridden `fetch` resolves with.
+ *
+ * Note the status range: whatwg-fetch's `Response` constructor THROWS
+ * `RangeError` outside [200, 599], which would crash the caller instead of
+ * overriding it. `resolveOverride` clamps before we ever get here.
+ */
+export declare function synthesizeResponse(url: string, outcome: Extract<OverrideOutcome, {
+    kind: "respond";
+}>): Response;
+/**
+ * The error a failed `fetch` rejects with.
+ *
+ * These are the exact messages whatwg-fetch produces for a dead connection and
+ * a timeout, so app code that string-matches on them (plenty does) behaves the
+ * same way it would against a real failure.
+ */
+export declare function synthesizeFetchError(outcome: Extract<OverrideOutcome, {
+    kind: "fail";
+}>): Error;
+//# sourceMappingURL=applyToFetch.d.ts.map

package/lib/typescript/network/overrides/applyToFetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyToFetch.d.ts","sourceRoot":"","sources":["../../../../src/network/overrides/applyToFetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,eAAO,MAAM,KAAK,GAAI,IAAI,MAAM,KAAG,OAAO,CAAC,IAAI,CAGxB,CAAC;AAExB;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,OAAO,CAAC,eAAe,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,GACrD,QAAQ,CAeV;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,CAAC,eAAe,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAClD,KAAK,CAMP"}

package/lib/typescript/network/overrides/applyToXhr.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Perform an override outcome against a React Native XMLHttpRequest.
+ *
+ * WHY THIS IS POSSIBLE AT ALL: React Native's XMLHttpRequest
+ * (`react-native/Libraries/Network/XMLHttpRequest.js`) is pure JavaScript.
+ * `readyState`, `status`, `responseHeaders` and `responseURL` are plain
+ * writable fields, and `setResponseHeaders()` / `setReadyState()` are real
+ * methods — `setReadyState(DONE)` dispatches the correct terminal event off
+ * internal flags (`_aborted` → abort, `_hasError` + `_timedOut` → timeout,
+ * `_hasError` → error, otherwise load; always loadend). So a response can be
+ * synthesized end to end without touching native code.
+ *
+ * WHY XHR IS THE ONLY PLACE WE HOOK: `react-native/Libraries/Network/fetch.js`
+ * is `require('whatwg-fetch')` — RN's `fetch` IS the polyfill over
+ * XMLHttpRequest. Overriding here therefore covers `fetch`, `axios` and raw
+ * XHR through one code path, and the fake response flows back up through the
+ * polyfill so the tool records it without any extra plumbing.
+ *
+ * Verified field-for-field on React Native 0.81.4 and 0.85.3.
+ *
+ * Four non-obvious behaviours are handled below; each one is a real bug if you
+ * skip it, and each is commented at the line that fixes it.
+ */
+import type { OverrideOutcome } from "./types";
+/**
+ * Can this XMLHttpRequest be driven by hand?
+ *
+ * The whole technique rests on RN internals, so it is feature-detected rather
+ * than assumed: on a browser XMLHttpRequest (react-native-web) these methods
+ * don't exist and `status` is a read-only getter. There, overrides no-op and
+ * the request goes out for real — degraded, but never broken.
+ */
+export declare function canSynthesize(xhr: XMLHttpRequest): boolean;
+/**
+ * Apply an outcome to a request that has NOT been sent yet.
+ *
+ * Returns `false` when this environment can't be driven by hand, in which case
+ * the caller must send the request normally.
+ *
+ * @param passThrough Sends the real request. Only used by `kind: "delay"`.
+ */
+export declare function runOverride(xhr: XMLHttpRequest, url: string, outcome: OverrideOutcome, passThrough: () => void): boolean;
+//# sourceMappingURL=applyToXhr.d.ts.map

package/lib/typescript/network/overrides/applyToXhr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyToXhr.d.ts","sourceRoot":"","sources":["../../../../src/network/overrides/applyToXhr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAkC/C;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAM1D;AA+ED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,cAAc,EACnB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,eAAe,EACxB,WAAW,EAAE,MAAM,IAAI,GACtB,OAAO,CAiET"}

package/lib/typescript/network/overrides/engine.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The seam between the interceptor and the rule store.
+ *
+ * It exists to keep the import graph acyclic: `networkListener` needs rules,
+ * and the rule store needs the listener (to keep the swizzle installed while a
+ * rule is active). Rather than have them import each other, the store REGISTERS
+ * itself here and the listener asks here. Both sides import only this leaf.
+ *
+ * It's also the single place the production gate lives — see `overrideForRequest`.
+ */
+import type { OverrideOutcome, OverrideRule } from "./types";
+export interface OverrideHooks {
+    getRules: () => readonly OverrideRule[];
+    /** The rule APPLIED to a request. */
+    recordHit: (ruleId: string) => void;
+    /**
+     * The rule MATCHED a request, whether or not it applied.
+     *
+     * `alternate` needs this: a rule that only counted the requests it overrode
+     * would never advance past its off phase, so it would skip forever.
+     */
+    recordMatch: (ruleId: string) => void;
+}
+export declare function setOverrideHooks(next: OverrideHooks | null): void;
+/**
+ * Diagnostics for the sync adapter's `debugOverrides` action.
+ *
+ * Reads the engine's own view of the world — crucially `hooks`, which is
+ * MODULE state here: if the interceptor and the rule store ever ended up with
+ * separate copies of this file, this is the only place that shows it.
+ */
+export declare function inspectEngine(url: string, method: string): {
+    hooksInstalled: boolean;
+    devFlag: string | boolean;
+    ruleCount: number;
+    matches: boolean;
+};
+/**
+ * Resolve an override for one outgoing request, recording the hit.
+ *
+ * NEVER ACTIVE IN A PRODUCTION BUILD. A shipped app that synthesizes 500s or
+ * silently swallows requests is a catastrophe of a different order than a
+ * broken dev tool, so the gate is here — at the single entry point — rather
+ * than trusted to every call site.
+ */
+export declare function overrideForRequest(url: string, method: string): OverrideOutcome | null;
+//# sourceMappingURL=engine.d.ts.map

package/lib/typescript/network/overrides/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../../src/network/overrides/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE7D,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,SAAS,YAAY,EAAE,CAAC;IACxC,qCAAqC;IACrC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC;;;;;OAKG;IACH,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC;AAID,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI,CAEjE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;;;;;EAWxD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GACb,eAAe,GAAG,IAAI,CAqBxB"}

package/lib/typescript/network/overrides/matchRule.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Glob matching for override rules — a faithful port of Chrome DevTools'.
+ *
+ * Ported from `NetworkPersistenceManager.ts:1051` + `StringUtilities.ts:9` in
+ * the devtools-frontend source. Ported rather than reinvented on purpose: `*`
+ * globs are the syntax developers already have in their fingers from Chrome's
+ * "Override headers" `applyTo` field, and a pattern that behaves differently
+ * here than it does in the browser would be a quiet trap.
+ */
+import type { OverrideRule } from "./types";
+/**
+ * Escape a glob into regex source: neutralize regex metacharacters, then
+ * promote `*` to `.*`.
+ *
+ * `split`/`join` rather than `replaceAll` — same result, no reliance on how
+ * complete a given Hermes build's ES2021 surface is.
+ */
+export declare function escapeRegex(pattern: string): string;
+export declare function compilePattern(pattern: string): RegExp;
+/** Does this rule apply to this request? Ignores `enabled` — callers check it. */
+export declare function ruleMatches(rule: OverrideRule, url: string, method: string): boolean;
+//# sourceMappingURL=matchRule.d.ts.map

package/lib/typescript/network/overrides/matchRule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchRule.d.ts","sourceRoot":"","sources":["../../../../src/network/overrides/matchRule.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAU5C;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAUnD;AAWD,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAatD;AAED,kFAAkF;AAClF,wBAAgB,WAAW,CACzB,IAAI,EAAE,YAAY,EAClB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GACb,OAAO,CAWT"}

package/lib/typescript/network/overrides/overrideRulesStore.d.ts

@@ -0,0 +1,205 @@
+/**
+ * The override rule list — persisted, and the source of truth for the engine.
+ *
+ * Shape and persistence follow `networkSavedStore` / `ignoredPatternsStore`:
+ * lazy hydrate on first use, a `dirty` flag so a slow read can't clobber a
+ * mutation the user just made, and commit = set + emit + persist.
+ *
+ * Two things here are specific to overrides and worth reading:
+ *
+ *  - `getRules()` is on the HOT PATH. It is called inside the app's own
+ *    `XMLHttpRequest.send()`, for every request, so it does no work: the master
+ *    switch collapses to returning a frozen empty array.
+ *
+ *  - `syncKeepAlive()` keeps the interceptor installed while any rule is
+ *    active. Without it a rule would stop firing the moment the Network tool
+ *    closed, because the swizzle is reference-counted off capture subscribers.
+ */
+import { type OverrideRule } from "./types";
+export interface OverrideRulesState {
+    /** Master switch. Off disables every rule without losing any of them. */
+    enabled: boolean;
+    rules: OverrideRule[];
+    /**
+     * Set when the launch-safety guard turned overrides off by itself.
+     *
+     * Cleared the moment the developer turns them back on or touches a rule. The
+     * UI uses it to explain the state rather than leave it looking like a bug.
+     */
+    autoPaused: boolean;
+}
+/**
+ * A rule as authored. `id`/`createdAt` and the runtime counters (`hits`,
+ * `seen`) are the store's business, never the caller's.
+ */
+export type OverrideRuleDraft = Omit<OverrideRule, "id" | "hits" | "seen" | "createdAt">;
+/**
+ * Handlers the desktop dashboard installs to forward mutations to the device.
+ *
+ * Rules only DO anything on the device — a rule is applied inside the app's own
+ * `fetch`/`XMLHttpRequest`, which the dashboard doesn't have. So in remote mode
+ * this store becomes a MIRROR: it renders the device's rules and forwards every
+ * edit, writing nothing to this machine's storage. Same seam
+ * `networkSavedStore` uses for pins.
+ */
+export interface OverrideRulesRemote {
+    setEnabled: (enabled: boolean) => void;
+    upsertRule: (draft: OverrideRuleDraft & {
+        id?: string;
+    }) => void;
+    setRuleEnabled: (id: string, enabled: boolean) => void;
+    removeRule: (id: string) => void;
+    clearRules: () => void;
+    /**
+     * Fetch the body the snapshot withheld (see `OverrideRule.bodyOmitted`).
+     * Optional so an older dashboard still mirrors rules — it just shows an empty
+     * body for the large ones.
+     */
+    getRuleBody?: (id: string) => Promise<string | null>;
+}
+type Listener = () => void;
+declare class OverrideRulesStore {
+    private rules;
+    private enabled;
+    private readonly listeners;
+    private loaded;
+    private loadPromise;
+    /** Set once a mutation happens so a slow initial load can't clobber it. */
+    private dirty;
+    private idCounter;
+    private state;
+    /** Consecutive launches that began with rules armed and nobody touching them. */
+    private launchStreak;
+    private autoPaused;
+    /** Held while any rule is active — see `syncKeepAlive`. */
+    private keepAlive;
+    private hitEmitTimer;
+    /** Set on the desktop dashboard — see `disableEngine`. */
+    private engineDisabled;
+    /** Set on the desktop dashboard — see `OverrideRulesRemote`. */
+    private remote;
+    private remoteEchoUntil;
+    /**
+     * Turn this store into a mirror of a connected device's rules. Edits are
+     * applied locally for immediate feedback AND forwarded to the device, which
+     * is the source of truth; nothing is persisted to this machine.
+     */
+    enableRemoteMode(remote: OverrideRulesRemote): void;
+    disableRemoteMode(): void;
+    /**
+     * Feed the device's rules in (mirror mode only). `force` bypasses the echo
+     * guard — used when tearing the mirror down, where there is no later snapshot
+     * to converge on.
+     */
+    replaceRules(state: OverrideRulesState, force?: boolean): void;
+    /** Mark a local optimistic write so the next in-flight mirror is ignored. */
+    private markLocalEdit;
+    /**
+     * Never intercept traffic in this runtime.
+     *
+     * The desktop dashboard renders the real tool (`NetworkToolView`), so this
+     * module is imported there too — but the dashboard is a VIEWER. Its job is to
+     * drive rules on the connected device, never to swizzle its own `fetch` and
+     * override its own requests. The same seam `networkEventStore.disableCapture()`
+     * uses, for the same reason.
+     */
+    disableEngine(): void;
+    getState(): OverrideRulesState;
+    /**
+     * The hot path — called inside `send()` for every request the app makes.
+     * Returns a frozen empty array when the master switch is off so the caller
+     * needs no second check.
+     */
+    getRules(): readonly OverrideRule[];
+    /**
+     * The rule's real body, fetching it from the device when this surface only
+     * has the stripped copy (see `OverrideRule.bodyOmitted`).
+     *
+     * On the device itself every body is already here, so this resolves
+     * immediately and the editor never notices the difference.
+     */
+    fetchRuleBody(id: string): Promise<string | null>;
+    /** Rules that would actually fire — drives the "overrides active" banner. */
+    activeCount(): number;
+    subscribe(listener: Listener): () => void;
+    setEnabled(enabled: boolean): void;
+    addRule(draft: OverrideRuleDraft): OverrideRule | null;
+    /**
+     * Create or replace a rule in one call.
+     *
+     * THE ONLY WRITE PATH THE UI SHOULD USE. `addRule`/`updateRule` are the
+     * primitives underneath and deliberately do NOT forward to the device — if
+     * the UI called them directly, an edit made on the dashboard would apply to
+     * the mirror and never reach the phone, which looks exactly like it worked.
+     *
+     * Returns the rule, or null when the list is full.
+     */
+    upsertRule(draft: OverrideRuleDraft & {
+        id?: string;
+    }): OverrideRule | null;
+    updateRule(id: string, patch: Partial<OverrideRuleDraft>): void;
+    setRuleEnabled(id: string, enabled: boolean): void;
+    removeRule(id: string): void;
+    clearRules(): void;
+    /**
+     * One rule matched one request.
+     *
+     * Replaces the rule object rather than mutating it so memoized rows actually
+     * re-render, and coalesces the notification — this runs at request rate.
+     */
+    /**
+     * One rule matched one request, applied or not.
+     *
+     * Deliberately silent — this fires on requests an alternating rule lets
+     * through, where nothing visible changed. `recordHit` owns the notification.
+     */
+    recordMatch(ruleId: string): void;
+    recordHit(ruleId: string): void;
+    /**
+     * Hydrate from storage. Safe to call repeatedly; only the first call reads.
+     *
+     * Called at package import (see `preset.tsx`) rather than on first subscribe,
+     * because a rule has to fire from app boot — with the Network tool closed and
+     * nothing capturing.
+     */
+    ensureLoaded(): Promise<void>;
+    /**
+     * Count this launch, and pause overrides if they've been armed and untouched
+     * for too many in a row. See MAX_UNTOUCHED_LAUNCHES for why.
+     */
+    private applyLaunchGuard;
+    /**
+     * Keep the interceptor installed for as long as a rule could fire.
+     *
+     * The swizzle is reference-counted off `networkListener`'s listener count
+     * (the event store adds one while capturing). Holding a no-op listener reuses
+     * that existing lifecycle instead of inventing a second one.
+     */
+    private syncKeepAlive;
+    private scheduleHitEmit;
+    private commit;
+    /** Rebuild the derived view once per mutation so renders get stable refs. */
+    private rebuild;
+    /**
+     * The developer is actively working with the rules, so the launch guard has
+     * nothing to protect them from — reset it and clear any auto-pause notice.
+     */
+    private markTouched;
+    /**
+     * The developer reached the override UI, which is proof the app still runs.
+     *
+     * The launch guard exists to escape a WEDGE — a body the app can't render,
+     * where the controls are unreachable because nothing draws. If this call
+     * happens, that isn't the situation, so the streak has nothing to protect
+     * against. Without it the guard nags anyone who legitimately keeps a rule
+     * armed for days, which is a real workflow ("force /checkout to 500 every
+     * morning") and not the failure mode it was built for.
+     */
+    noteHealthyLaunch(): void;
+    private persist;
+    private emit;
+}
+/** Singleton — one rule list per JS runtime. */
+export declare const overrideRulesStore: OverrideRulesStore;
+export {};
+//# sourceMappingURL=overrideRulesStore.d.ts.map

package/lib/typescript/network/overrides/overrideRulesStore.d.ts.map

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

package/lib/typescript/network/overrides/presets.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Turning a captured request into a rule draft.
+ *
+ * Chrome's flow assumes a keyboard, a file tree and a second monitor. On a
+ * phone the equivalent has to start from the request you're already looking at,
+ * which is what this file is for — the editor never opens on a blank field.
+ *
+ * There used to be a list of one-tap presets here (Force 500, Empty list,
+ * Offline…) rendered as chips. They're gone: the editor's outcome grid says the
+ * same things in the same words, so keeping both meant two lists to maintain
+ * and two places to look for the same choice.
+ */
+import type { NetworkEvent } from "../types";
+import type { OverrideRuleDraft } from "./overrideRulesStore";
+/**
+ * Turn a captured URL into a pattern that will match the request AGAIN.
+ *
+ * The query string is dropped and replaced with `*`, which is not a
+ * simplification — it's the difference between a rule that works and one that
+ * silently never fires. Plenty of clients cache-bust
+ * (`?timestamp=1785783081234`), carry a request id, or page; pinning the exact
+ * URL means the next call to the same endpoint doesn't match. Found exactly
+ * that way: an "Offline" preset on a Pokémon request sat at 0 hits because the
+ * app appends a timestamp to every call.
+ *
+ * The path stays exact, so this still means "this endpoint" and not "this
+ * host" — and the editor shows the pattern, so narrowing it back down is one
+ * edit away.
+ */
+export declare function patternForUrl(url: string): string;
+/**
+ * Prefill the rule editor from a captured request.
+ *
+ * Seeds the REAL response as the body so the common edit — change two fields of
+ * a payload you just saw — starts from something true rather than from nothing.
+ */
+export declare function draftFromEvent(event: NetworkEvent): OverrideRuleDraft;
+//# sourceMappingURL=presets.d.ts.map

package/lib/typescript/network/overrides/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../../../../src/network/overrides/presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGjD;AAaD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,iBAAiB,CAYrE"}

package/lib/typescript/network/overrides/resolveOverride.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Decide whether a request is overridden — the whole decision, in one pure
+ * function.
+ *
+ * Pure on purpose: this is the piece worth unit-testing, and it runs inside the
+ * app's own `XMLHttpRequest.send()`, so it must be cheap, total, and incapable
+ * of throwing. Everything that could surprise (defaults, clamping, content-type
+ * inference) is resolved HERE, so `applyToXhr` never makes a decision — it just
+ * performs the outcome.
+ */
+import { type OverrideOutcome, type OverrideRule } from "./types";
+/** Normalize a matched rule into the exact instructions the interceptor needs. */
+declare function toOutcome(rule: OverrideRule): OverrideOutcome;
+/** A rule that has burned through its `times` budget no longer applies. */
+export declare function isSpent(rule: OverrideRule): boolean;
+/**
+ * Is this rule in a phase where it should actually fire?
+ *
+ * Only `alternate` can answer no. It reads the CURRENT `seen` count, before
+ * this match is recorded, so an untouched rule (`seen === 0`) lets the first
+ * request through and overrides the second.
+ */
+export declare function shouldApply(rule: OverrideRule): boolean;
+/**
+ * The first enabled rule whose pattern covers this request, phase ignored.
+ *
+ * Separate from `resolveOverride` because an alternating rule has to advance
+ * its phase on the requests it deliberately skips — the caller needs the rule
+ * back even when the answer is "not this time".
+ */
+export declare function findMatchingRule(url: string, method: string, rules: readonly OverrideRule[]): OverrideRule | null;
+/**
+ * First ENABLED matching rule wins outright — no merging across rules.
+ *
+ * Chrome cascades header overrides from the most general path segment to the
+ * most specific, but that only exists because its rules are directory-nested
+ * files. A flat list with a cascade would be a rule whose effect you cannot see
+ * by reading it, which is exactly the wrong trade on a phone screen.
+ *
+ * @param url    Full request URL, query string included.
+ * @param method HTTP method as the caller sent it (case-insensitive).
+ * @param rules  Ordered rule list; earlier entries win.
+ */
+export declare function resolveOverride(url: string, method: string, rules: readonly OverrideRule[]): OverrideOutcome | null;
+export { toOutcome };
+//# sourceMappingURL=resolveOverride.d.ts.map

package/lib/typescript/network/overrides/resolveOverride.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveOverride.d.ts","sourceRoot":"","sources":["../../../../src/network/overrides/resolveOverride.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,YAAY,EAClB,MAAM,SAAS,CAAC;AA4CjB,kFAAkF;AAClF,iBAAS,SAAS,CAAC,IAAI,EAAE,YAAY,GAAG,eAAe,CA6BtD;AAED,2EAA2E;AAC3E,wBAAgB,OAAO,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAEnD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAGvD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,SAAS,YAAY,EAAE,GAC7B,YAAY,GAAG,IAAI,CAcrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,SAAS,YAAY,EAAE,GAC7B,eAAe,GAAG,IAAI,CAIxB;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}