nativeproof 0.1.1

package/dist/fixtures.js

@@ -0,0 +1,53 @@
+/**
+ * Playwright-style behaviour fixtures for Appium/WebdriverIO + Mocha.
+ *
+ * Gives specs the developer experience of Playwright — a typed fixture context
+ * injected into each behaviour, with provisioning and teardown owned by the
+ * framework instead of copy-pasted into every `before`/`after` — without depending
+ * on Playwright itself (which cannot drive native iOS/Android). It is a thin layer
+ * over whatever BDD runner hosts it (Mocha by default; see {@link runner}).
+ *
+ * App-agnostic by contract: nothing here may import app-specific code. A caller
+ * supplies a {@link ScenarioFixture} describing how to provision and tear down its
+ * own context (start a mock, relaunch the app, log in, join …); this module only
+ * wires that lifecycle into the runner and injects the result. It is part of the
+ * surface intended for extraction into a standalone package.
+ */
+import { runner } from "./runner.js";
+/**
+ * Define a behaviour scenario: a Mocha `describe` whose fixture context is
+ * provisioned once, injected into every behaviour, and torn down once.
+ *
+ * @param title   - the scenario description (Mocha `describe` title).
+ * @param fixture - how to provision and tear down the shared context.
+ * @param define  - registers the behaviours; receives a `test` registrar that
+ *                  injects the context.
+ *
+ * @example
+ * describeScenario("chat room", chatRoomScenario(), (test) => {
+ *   test("renders the latest message", async ({ member }) => {
+ *     await member.assertLatestMessageVisible();
+ *   });
+ * });
+ */
+export function describeScenario(title, fixture, define) {
+    const { describe, before, after, it } = runner();
+    describe(title, () => {
+        let context;
+        before(async () => {
+            context = await fixture.setup();
+        });
+        after(async () => {
+            await fixture.teardown(context);
+        });
+        const test = (behaviourTitle, body) => {
+            it(behaviourTitle, async () => {
+                if (context === undefined) {
+                    throw new Error(`Scenario "${title}" ran a behaviour before its fixture context was provisioned`);
+                }
+                await body(context);
+            });
+        };
+        define(test);
+    });
+}

package/dist/gestures.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Low-level pointer gestures.
+ *
+ * Compose / SwiftUI surfaces frequently expose accessibility nodes that Appium
+ * reports as non-clickable or `visible=false`, so coordinate taps (computed from
+ * the page source bounds) are a first-class fallback throughout the app's screen objects.
+ * These helpers are app-agnostic and form part of the reusable framework core.
+ */
+export declare function tapAt(x: number, y: number): Promise<void>;
+export declare function swipe(fromX: number, fromY: number, toX: number, toY: number, duration?: number): Promise<void>;
+export declare function pause(ms: number): Promise<void>;

package/dist/gestures.js

@@ -0,0 +1,45 @@
+import { browser } from "@wdio/globals";
+/**
+ * Low-level pointer gestures.
+ *
+ * Compose / SwiftUI surfaces frequently expose accessibility nodes that Appium
+ * reports as non-clickable or `visible=false`, so coordinate taps (computed from
+ * the page source bounds) are a first-class fallback throughout the app's screen objects.
+ * These helpers are app-agnostic and form part of the reusable framework core.
+ */
+export async function tapAt(x, y) {
+    await browser.performActions([
+        {
+            type: "pointer",
+            id: "finger1",
+            parameters: { pointerType: "touch" },
+            actions: [
+                { type: "pointerMove", duration: 0, x, y },
+                { type: "pointerDown", button: 0 },
+                { type: "pause", duration: 100 },
+                { type: "pointerUp", button: 0 },
+            ],
+        },
+    ]);
+    await browser.releaseActions();
+}
+export async function swipe(fromX, fromY, toX, toY, duration = 600) {
+    await browser.performActions([
+        {
+            type: "pointer",
+            id: "finger1",
+            parameters: { pointerType: "touch" },
+            actions: [
+                { type: "pointerMove", duration: 0, x: fromX, y: fromY },
+                { type: "pointerDown", button: 0 },
+                { type: "pause", duration: 100 },
+                { type: "pointerMove", duration, x: toX, y: toY },
+                { type: "pointerUp", button: 0 },
+            ],
+        },
+    ]);
+    await browser.releaseActions();
+}
+export async function pause(ms) {
+    await browser.pause(ms);
+}

package/dist/harness.d.ts

@@ -0,0 +1,32 @@
+import type { App, ScreenFactories, SessionContext } from "./app.js";
+import { expect } from "./expect.js";
+/**
+ * `createHarness(app)` — the Playwright `@playwright/test` pattern.
+ *
+ * Returns a `test` / `expect` pair bound to one app, so specs import them from a single
+ * project file and write module-level `test(...)` / `test.describe(...)` with the app's
+ * fixture context flowing in fully typed — no `(test) =>` registrar to thread, no
+ * per-spec wiring:
+ *
+ * ```ts
+ * // harness.ts
+ * export const { test, expect } = createHarness(app);
+ * // chat.spec.ts
+ * import { test, expect } from "./harness";
+ * test.describe("chat room", "member", () => {
+ *   test("renders the latest message", async ({ member, mock }) => { ... });  // typed
+ * });
+ * ```
+ */
+export interface HarnessTest<S extends ScreenFactories> {
+    (name: string, body: (context: SessionContext<S>) => void | Promise<void>): void;
+    /** Open a scenario block for the default role. */
+    describe(title: string, body: () => void): void;
+    /** Open a scenario block for a specific role (e.g. "member" / "guest"). */
+    describe(title: string, role: string, body: () => void): void;
+}
+export interface Harness<S extends ScreenFactories> {
+    test: HarnessTest<S>;
+    expect: typeof expect;
+}
+export declare function createHarness<S extends ScreenFactories>(app: App<S>): Harness<S>;

package/dist/harness.js

@@ -0,0 +1,29 @@
+import { expect } from "./expect.js";
+import { describeScenario } from "./fixtures.js";
+export function createHarness(app) {
+    let active = null;
+    const test = ((name, body) => {
+        if (!active) {
+            throw new Error(`test(${JSON.stringify(name)}) must be called inside test.describe(...)`);
+        }
+        active(name, body);
+    });
+    test.describe = ((title, roleOrBody, maybeBody) => {
+        const role = typeof roleOrBody === "string" ? roleOrBody : undefined;
+        const body = typeof roleOrBody === "function" ? roleOrBody : maybeBody;
+        if (!body) {
+            throw new Error(`test.describe(${JSON.stringify(title)}) requires a body function`);
+        }
+        describeScenario(title, app.session(role), (register) => {
+            const previous = active;
+            active = register;
+            try {
+                body();
+            }
+            finally {
+                active = previous;
+            }
+        });
+    });
+    return { test, expect };
+}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * NativeProof — a Native Mobile E2E test framework inspired by Playwright.
+ *
+ * Playwright's developer experience (fixtures, locators, expect, route-style mocking,
+ * evidence) layered on Appium/WebdriverIO, which can drive the native iOS/Android
+ * surfaces Playwright cannot. App-agnostic: consumers wire all app-specifics (selectors,
+ * secret patterns, login/join flows, mock backend) in by injection; nothing in this
+ * package imports app-specific code.
+ */
+export * from "./adb.js";
+export * from "./app.js";
+export * from "./config.js";
+export * from "./driver.js";
+export * from "./evidence.js";
+export * from "./expect.js";
+export * from "./fixtures.js";
+export * from "./gestures.js";
+export * from "./harness.js";
+export * from "./ios.js";
+export * from "./locator.js";
+export * from "./log.js";
+export * from "./mock.js";
+export * from "./mock-server.js";
+export * from "./page.js";
+export * from "./runner.js";
+export * from "./screen.js";
+export * from "./source.js";
+export * from "./test.js";
+export * from "./text.js";
+export * from "./wait.js";

package/dist/index.js

@@ -0,0 +1,30 @@
+/**
+ * NativeProof — a Native Mobile E2E test framework inspired by Playwright.
+ *
+ * Playwright's developer experience (fixtures, locators, expect, route-style mocking,
+ * evidence) layered on Appium/WebdriverIO, which can drive the native iOS/Android
+ * surfaces Playwright cannot. App-agnostic: consumers wire all app-specifics (selectors,
+ * secret patterns, login/join flows, mock backend) in by injection; nothing in this
+ * package imports app-specific code.
+ */
+export * from "./adb.js";
+export * from "./app.js";
+export * from "./config.js";
+export * from "./driver.js";
+export * from "./evidence.js";
+export * from "./expect.js";
+export * from "./fixtures.js";
+export * from "./gestures.js";
+export * from "./harness.js";
+export * from "./ios.js";
+export * from "./locator.js";
+export * from "./log.js";
+export * from "./mock.js";
+export * from "./mock-server.js";
+export * from "./page.js";
+export * from "./runner.js";
+export * from "./screen.js";
+export * from "./source.js";
+export * from "./test.js";
+export * from "./text.js";
+export * from "./wait.js";

package/dist/ios.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Thin, best-effort wrappers around `xcrun simctl` — the iOS-simulator counterpart
+ * to {@link file://./adb.ts}. They control app + simulator lifecycle (terminate, launch,
+ * install, uninstall, boot, shutdown, reset) so a consuming app can reset state between
+ * scenarios on iOS the way `adb` does on Android.
+ *
+ * The device defaults to `"booted"` (the currently-booted simulator), the simctl analogue
+ * of adb's single-device default. Note there is no iOS equivalent of `adbDump`: iOS exposes
+ * the element tree only through the Appium (XCUITest) page source, so screens fall back to
+ * that, not to an out-of-band dump.
+ */
+/** A command runner; injectable so the command mapping is unit-testable without a simulator. */
+export type SimctlRunner = (args: string[]) => string;
+/** Build the argv for an `xcrun simctl <action> <udid> [...]` invocation (pure). */
+export declare function simctlArgv(action: string, udid: string, ...rest: string[]): string[];
+/** Stop a running app (best-effort) — the iOS analogue of `adbForceStop`. */
+export declare function iosTerminate(bundleId: string, udid?: string, run?: SimctlRunner): void;
+/** Launch an installed app (best-effort). */
+export declare function iosLaunch(bundleId: string, udid?: string, run?: SimctlRunner): void;
+/** Install a `.app`/`.ipa` build (best-effort). */
+export declare function iosInstall(appPath: string, udid?: string, run?: SimctlRunner): void;
+/** Uninstall an app, clearing its data + sandbox (best-effort). */
+export declare function iosUninstall(bundleId: string, udid?: string, run?: SimctlRunner): void;
+/** Boot a simulator by udid (best-effort; no-op if already booted). */
+export declare function iosBoot(udid: string, run?: SimctlRunner): void;
+/** Shut a simulator down (best-effort). */
+export declare function iosShutdown(udid?: string, run?: SimctlRunner): void;
+/**
+ * Reset an app to a clean state before a fresh login — the iOS analogue of
+ * `resetAppAndBrowserState`. Terminates then uninstalls the app (which clears its data and
+ * sandbox); reinstalls from `appPath` when given so the next launch starts signed-out.
+ */
+export declare function resetAppState(bundleId: string, options?: {
+    udid?: string;
+    appPath?: string;
+    run?: SimctlRunner;
+}): void;
+/** Recent simulator logs (best-effort supporting evidence) — the analogue of `adbLogcatDump`. */
+export declare function iosLogShow(udid?: string, since?: string, run?: SimctlRunner): string;

package/dist/ios.js

@@ -0,0 +1,92 @@
+import { execFileSync } from "node:child_process";
+const realRunner = (args) => execFileSync("xcrun", args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+/** Build the argv for an `xcrun simctl <action> <udid> [...]` invocation (pure). */
+export function simctlArgv(action, udid, ...rest) {
+    return ["simctl", action, udid, ...rest];
+}
+/** Stop a running app (best-effort) — the iOS analogue of `adbForceStop`. */
+export function iosTerminate(bundleId, udid = "booted", run = realRunner) {
+    try {
+        run(simctlArgv("terminate", udid, bundleId));
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Launch an installed app (best-effort). */
+export function iosLaunch(bundleId, udid = "booted", run = realRunner) {
+    try {
+        run(simctlArgv("launch", udid, bundleId));
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Install a `.app`/`.ipa` build (best-effort). */
+export function iosInstall(appPath, udid = "booted", run = realRunner) {
+    try {
+        run(simctlArgv("install", udid, appPath));
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Uninstall an app, clearing its data + sandbox (best-effort). */
+export function iosUninstall(bundleId, udid = "booted", run = realRunner) {
+    try {
+        run(simctlArgv("uninstall", udid, bundleId));
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Boot a simulator by udid (best-effort; no-op if already booted). */
+export function iosBoot(udid, run = realRunner) {
+    try {
+        run(simctlArgv("boot", udid));
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Shut a simulator down (best-effort). */
+export function iosShutdown(udid = "booted", run = realRunner) {
+    try {
+        run(simctlArgv("shutdown", udid));
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/**
+ * Reset an app to a clean state before a fresh login — the iOS analogue of
+ * `resetAppAndBrowserState`. Terminates then uninstalls the app (which clears its data and
+ * sandbox); reinstalls from `appPath` when given so the next launch starts signed-out.
+ */
+export function resetAppState(bundleId, options = {}) {
+    const udid = options.udid ?? "booted";
+    const run = options.run ?? realRunner;
+    const steps = [
+        simctlArgv("terminate", udid, bundleId),
+        simctlArgv("uninstall", udid, bundleId),
+    ];
+    if (options.appPath)
+        steps.push(simctlArgv("install", udid, options.appPath));
+    for (const step of steps) {
+        try {
+            run(step);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
+/** Recent simulator logs (best-effort supporting evidence) — the analogue of `adbLogcatDump`. */
+export function iosLogShow(udid = "booted", since = "1m", run = realRunner) {
+    try {
+        return run(simctlArgv("spawn", udid, "log", "show", "--style", "compact", "--last", since));
+    }
+    catch {
+        return "";
+    }
+}

package/dist/locator.d.ts

@@ -0,0 +1,78 @@
+import type { Driver } from "./driver.js";
+import { type Bounds } from "./source.js";
+/**
+ * Cross-platform locators — the reusable heart of the framework.
+ *
+ * A {@link Locator} is a lazy, awaitable handle to an element addressed by a
+ * platform-agnostic selector (`by.text` / `by.desc` / `by.id`), with built-in
+ * waiting and a source-bounds coordinate-tap fallback. It is the Playwright
+ * `Locator` equivalent and the thing that lets `expect(locator).toShow(...)` exist.
+ */
+/** A cross-platform element selector. */
+export type Selector = {
+    readonly by: "text";
+    readonly value: string;
+} | {
+    readonly by: "desc";
+    readonly value: string;
+} | {
+    readonly by: "id";
+    readonly value: string;
+} | {
+    readonly by: "testId";
+    readonly value: string;
+} | {
+    readonly by: "label";
+    readonly value: string;
+};
+/**
+ * Build selectors Playwright-style. The cross-platform attribute each maps to is resolved
+ * per platform (see {@link attributeFor}), so you never have to know whether it's a
+ * `content-desc` or a `name`: `by.text("Submit")`, `by.testId("login-button")`,
+ * `by.label("Sign out")`, `by.id("message-list")`.
+ */
+export declare const by: {
+    readonly text: (value: string) => Selector;
+    readonly desc: (value: string) => Selector;
+    readonly id: (value: string) => Selector;
+    /** The app's test id (Android `resource-id` / Compose testTag, iOS accessibilityIdentifier). */
+    readonly testId: (value: string) => Selector;
+    /** The accessibility label (Android `content-desc`, iOS `label`). */
+    readonly label: (value: string) => Selector;
+};
+export declare function describeSelector(selector: Selector): string;
+export interface WaitOptions {
+    timeout?: number;
+    interval?: number;
+    /** Sleep awaited between polls; defaults to a real timer. The locator injects the driver's pause. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Poll `produce` until `done(value)` holds or the timeout elapses, returning the
+ * last value either way (callers decide what an unmet condition means). The interval
+ * is awaited via `options.sleep` — a real timer by default, the driver's `pause` when
+ * a locator drives it — so a fake clock can control test timing. No device required.
+ */
+export declare function waitUntil<T>(produce: () => Promise<T>, done: (value: T) => boolean, options?: WaitOptions): Promise<T>;
+export declare class Locator {
+    readonly driver: Driver;
+    readonly selector: Selector;
+    private readonly options;
+    constructor(driver: Driver, selector: Selector, options?: WaitOptions);
+    private attribute;
+    private presencePattern;
+    /** True if the selector matches a node in the current source. */
+    isVisible(): Promise<boolean>;
+    /** Bounds of the matched node in the current source, or null if absent. */
+    bounds(): Promise<Bounds | null>;
+    /** The matched node's own visible text, or null if the node is absent. */
+    textContent(): Promise<string | null>;
+    /** True if the selector is present AND `text` appears in the source. */
+    shows(text: string | RegExp): Promise<boolean>;
+    /** Wait until the selector is visible; throws on timeout. */
+    waitFor(options?: WaitOptions): Promise<void>;
+    /** Wait for the element, then tap its centre (a source-bounds coordinate tap). */
+    tap(options?: WaitOptions): Promise<void>;
+}
+/** Convenience factory: `locator(driver, by.text("Submit"))`. */
+export declare function locator(driver: Driver, selector: Selector, options?: WaitOptions): Locator;

package/dist/locator.js

@@ -0,0 +1,116 @@
+import { boundsForAttribute } from "./source.js";
+/**
+ * Build selectors Playwright-style. The cross-platform attribute each maps to is resolved
+ * per platform (see {@link attributeFor}), so you never have to know whether it's a
+ * `content-desc` or a `name`: `by.text("Submit")`, `by.testId("login-button")`,
+ * `by.label("Sign out")`, `by.id("message-list")`.
+ */
+export const by = {
+    text: (value) => ({ by: "text", value }),
+    desc: (value) => ({ by: "desc", value }),
+    id: (value) => ({ by: "id", value }),
+    /** The app's test id (Android `resource-id` / Compose testTag, iOS accessibilityIdentifier). */
+    testId: (value) => ({ by: "testId", value }),
+    /** The accessibility label (Android `content-desc`, iOS `label`). */
+    label: (value) => ({ by: "label", value }),
+};
+export function describeSelector(selector) {
+    return `by.${selector.by}(${JSON.stringify(selector.value)})`;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** The page-source attribute a selector resolves to on each platform. */
+function attributeFor(selector, platform) {
+    const android = {
+        text: "text",
+        desc: "content-desc",
+        id: "resource-id",
+        testId: "resource-id",
+        label: "content-desc",
+    };
+    const ios = { text: "label", desc: "name", id: "name", testId: "name", label: "label" };
+    return (platform === "ios" ? ios : android)[selector.by];
+}
+const DEFAULTS = { timeout: 10_000, interval: 250 };
+const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Poll `produce` until `done(value)` holds or the timeout elapses, returning the
+ * last value either way (callers decide what an unmet condition means). The interval
+ * is awaited via `options.sleep` — a real timer by default, the driver's `pause` when
+ * a locator drives it — so a fake clock can control test timing. No device required.
+ */
+export async function waitUntil(produce, done, options = {}) {
+    const timeout = options.timeout ?? DEFAULTS.timeout;
+    const interval = options.interval ?? DEFAULTS.interval;
+    const sleep = options.sleep ?? realSleep;
+    const deadline = Date.now() + timeout;
+    let value = await produce();
+    while (!done(value) && Date.now() < deadline) {
+        await sleep(interval);
+        value = await produce();
+    }
+    return value;
+}
+export class Locator {
+    driver;
+    selector;
+    options;
+    constructor(driver, selector, options = {}) {
+        this.driver = driver;
+        this.selector = selector;
+        this.options = options;
+    }
+    attribute() {
+        return attributeFor(this.selector, this.driver.platform);
+    }
+    presencePattern() {
+        return new RegExp(`${this.attribute()}="${escapeRegExp(this.selector.value)}"`);
+    }
+    /** True if the selector matches a node in the current source. */
+    async isVisible() {
+        return this.presencePattern().test(await this.driver.source());
+    }
+    /** Bounds of the matched node in the current source, or null if absent. */
+    async bounds() {
+        return boundsForAttribute(await this.driver.source(), this.attribute(), this.selector.value);
+    }
+    /** The matched node's own visible text, or null if the node is absent. */
+    async textContent() {
+        const source = await this.driver.source();
+        const node = new RegExp(`<[^>]*${this.attribute()}="${escapeRegExp(this.selector.value)}"[^>]*>`).exec(source)?.[0];
+        if (!node)
+            return null;
+        const textAttr = this.driver.platform === "ios" ? "value|label" : "text";
+        return new RegExp(`(?:${textAttr})="([^"]*)"`).exec(node)?.[1] ?? null;
+    }
+    /** True if the selector is present AND `text` appears in the source. */
+    async shows(text) {
+        const source = await this.driver.source();
+        if (!this.presencePattern().test(source))
+            return false;
+        const pattern = typeof text === "string" ? new RegExp(escapeRegExp(text)) : text;
+        return pattern.test(source);
+    }
+    /** Wait until the selector is visible; throws on timeout. */
+    async waitFor(options = {}) {
+        const opts = { ...this.options, ...options, sleep: (ms) => this.driver.pause(ms) };
+        const visible = await waitUntil(() => this.isVisible(), (v) => v, opts);
+        if (!visible) {
+            throw new Error(`${describeSelector(this.selector)} did not become visible within ${opts.timeout ?? DEFAULTS.timeout}ms`);
+        }
+    }
+    /** Wait for the element, then tap its centre (a source-bounds coordinate tap). */
+    async tap(options = {}) {
+        const opts = { ...this.options, ...options, sleep: (ms) => this.driver.pause(ms) };
+        const bounds = await waitUntil(() => this.bounds(), (b) => b !== null, opts);
+        if (!bounds) {
+            throw new Error(`${describeSelector(this.selector)} was not found to tap within ${opts.timeout ?? DEFAULTS.timeout}ms`);
+        }
+        await this.driver.tapAt(bounds.centerX, bounds.centerY);
+    }
+}
+/** Convenience factory: `locator(driver, by.text("Submit"))`. */
+export function locator(driver, selector, options = {}) {
+    return new Locator(driver, selector, options);
+}

package/dist/log.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Network-evidence log helpers.
+ *
+ * The mock backend writes request and socket activity as JSONL. These pure
+ * helpers let assertions reason about app-originated network behaviour — the
+ * Playwright-`page.route()` equivalent that native Appium otherwise lacks.
+ * App-agnostic; app-specific frame semantics live in the consumer's assertions.
+ */
+export declare function readLog(logPath: string): Promise<string>;
+export declare function countMatches(text: string, pattern: RegExp): number;
+/**
+ * Tokens that must never appear in captured evidence. App-agnostic by default
+ * (non-fake Bearer tokens); a consumer composes in its own app-specific secrets
+ * (e.g. a passcode literal) — destined to become injected config.
+ */
+export declare const LEAKED_SECRET_PATTERN: RegExp;
+export declare function containsLeakedSecret(text: string): boolean;

package/dist/log.js

@@ -0,0 +1,25 @@
+import fs from "node:fs/promises";
+/**
+ * Network-evidence log helpers.
+ *
+ * The mock backend writes request and socket activity as JSONL. These pure
+ * helpers let assertions reason about app-originated network behaviour — the
+ * Playwright-`page.route()` equivalent that native Appium otherwise lacks.
+ * App-agnostic; app-specific frame semantics live in the consumer's assertions.
+ */
+export async function readLog(logPath) {
+    return fs.readFile(logPath, "utf8").catch(() => "");
+}
+export function countMatches(text, pattern) {
+    const flags = pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`;
+    return (text.match(new RegExp(pattern.source, flags)) ?? []).length;
+}
+/**
+ * Tokens that must never appear in captured evidence. App-agnostic by default
+ * (non-fake Bearer tokens); a consumer composes in its own app-specific secrets
+ * (e.g. a passcode literal) — destined to become injected config.
+ */
+export const LEAKED_SECRET_PATTERN = /Bearer\s+(?!fake-e2e)[A-Za-z0-9._-]+/i;
+export function containsLeakedSecret(text) {
+    return LEAKED_SECRET_PATTERN.test(text);
+}

package/dist/mock-server.d.ts

@@ -0,0 +1,17 @@
+import type { MockBackend } from "./mock.js";
+export interface MockServerOptions {
+    /** Port to listen on; 0 (the default) picks a free ephemeral port. */
+    port?: number;
+    /** Interface to bind; default 127.0.0.1. Use 0.0.0.0 to reach it from an emulator. */
+    host?: string;
+}
+export interface MockServer extends MockBackend {
+    /** HTTP base URL the app points at, e.g. `http://127.0.0.1:18113`. */
+    readonly url: string;
+    /** WebSocket base URL, e.g. `ws://127.0.0.1:18113`. */
+    readonly wsUrl: string;
+    readonly port: number;
+    /** Push a server-initiated frame to every socket open on `path` (recorded as received). */
+    send(path: string, frame: Record<string, unknown>): void;
+}
+export declare function startMockServer(options?: MockServerOptions): Promise<MockServer>;