@fixback/expo 0.8.3 → 0.9.1

package/dist/client-connect.js

@@ -0,0 +1,306 @@
+"use strict";
+/**
+ * **Connect** on the headless client (ADR-0066): the two doors `signIn()` opens
+ * (ADR-0052), the inbound deep links that finish a Connect started outside the app
+ * (ADR-0046), and `signOut()`.
+ *
+ * One piece of the headless client (`./client`), created over the state every piece
+ * shares (`./client-state`): the Reporter session token, the connect URL boot
+ * returned, the last inbound code, and the callers waiting on one. A Connect that lands
+ * re-boots as the Account through the boot it is handed (`./client-boot`), so a gated
+ * Project's shake gesture arms once the Account is eligible.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canSignIn = canSignIn;
+exports.createConnect = createConnect;
+const sdk_core_1 = require("@fixback/sdk-core");
+const client_state_1 = require("./client-state");
+const connect_1 = require("./connect");
+const reporter_session_store_1 = require("./reporter-session-store");
+/**
+ * How long the browser door's `signIn()` waits for the connect page's redirect to come
+ * back as a deep link (ADR-0052). Generous, because the round trip contains a real
+ * sign-in — the doors, an email link, a password manager — and the only cost of
+ * waiting is one pending promise. It exists so a person who abandons the page settles
+ * that promise eventually rather than never; the Connect itself is not cancelled by it
+ * and still lands through the inbound listener if they come back later.
+ */
+const CONNECT_BROWSER_WAIT_MS = 5 * 60_000;
+/**
+ * Whether the browser door is available: something to open the page with, and the
+ * `linking` seam the code comes back on. Without the seam the page would land the
+ * person back in the app with a code nothing reads, which is worse than not opening
+ * it — so both are required, not either.
+ */
+function canConnectThroughBrowser({ adapters }) {
+    return Boolean(adapters.openBrowser && adapters.linking);
+}
+/** Whether `signIn()` can open a door at all — what the dormancy hint is gated on. */
+function canSignIn(s) {
+    const { options, adapters } = s;
+    return Boolean((options.returnUrl && adapters.openAuthSession) || canConnectThroughBrowser(s));
+}
+/** Why `signIn()` could not open a door, named by what this app is actually missing. */
+function explainSignInDoor({ adapters }) {
+    if (!adapters.openBrowser && !adapters.openAuthSession) {
+        return `${sdk_core_1.WARN_PREFIX} signIn needs a browser to open the connect page — install expo-web-browser.`;
+    }
+    if (!adapters.linking) {
+        return `${sdk_core_1.WARN_PREFIX} ` + "signIn needs the Linking seam to receive the connect page's redirect — or declare a `returnUrl` in init to return through an auth session instead.";
+    }
+    return `${sdk_core_1.WARN_PREFIX} ` + "signIn needs either an auth-session opener plus a `returnUrl` in init, or an in-app browser (install expo-web-browser).";
+}
+/**
+ * Connect over the client's shared state. `bootAndArm` is the client's boot: a Connect
+ * that lands re-boots through it, as the Account.
+ */
+function createConnect(s, bootAndArm) {
+    const { options, adapters, warn, key, apiUrl } = s;
+    /**
+     * Start a **Connect** (ADR-0066): open the platform's connect page, exchange the
+     * one-time code it hands back for a Reporter session, store it in SecureStore, and
+     * re-boot as the Account — so a gated Project's shake gesture arms once the Account
+     * is eligible. Exposed so a host app can put it on its own settings screen (the way
+     * a gated Project, which shows nothing to a signed-out visitor, is entered), and
+     * behind the composer's identity row. Never throws: any failure leaves the current
+     * identity untouched.
+     *
+     * There are two doors, and which one opens depends only on what this app can offer
+     * (ADR-0052):
+     *
+     *  - **The auth session**, when `init` declared a `returnUrl` and an opener is
+     *    installed. The page returns *in place*, so the person never leaves the app.
+     *  - **The in-app browser**, otherwise. The page is opened with no return URL and
+     *    resolves where to land from the app links the *Project* lists, then redirects
+     *    to one — which re-opens this app, where the inbound listener redeems the code
+     *    (the journey a claimed Invite already travels). This is what keeps `signIn()`
+     *    from being inert on the default install, which declares no `returnUrl` at all.
+     */
+    async function signIn() {
+        const gen = s.generation;
+        if (!s.connectUrl)
+            return (0, client_state_1.reporterIdentity)(s); // not booted, or an older server
+        try {
+            if (options.returnUrl && adapters.openAuthSession) {
+                const outcome = await (0, connect_1.startExpoConnect)(adapters.openAuthSession, {
+                    connectUrl: s.connectUrl,
+                    key,
+                    returnUrl: options.returnUrl,
+                });
+                if (gen !== s.generation)
+                    return (0, client_state_1.reporterIdentity)(s);
+                if (outcome.kind === "code")
+                    await redeemConnectCode(outcome.code, gen);
+            }
+            else if (canConnectThroughBrowser(s)) {
+                await connectThroughBrowser(gen);
+            }
+            else {
+                warn(explainSignInDoor(s));
+            }
+        }
+        catch {
+            // A Connect problem must never disturb the host app.
+        }
+        return (0, client_state_1.reporterIdentity)(s);
+    }
+    /**
+     * The browser door (ADR-0052): open the connect page with no return URL and wait for
+     * the app link it redirects to, which the OS delivers back here as a deep link.
+     *
+     * The wait matters because the two halves are separated by the operating system: the
+     * page redirects, the app is foregrounded, and {@link handleInboundUrl} redeems —
+     * all after `openBrowser` has resolved (on Android it resolves as soon as the tab is
+     * shown). Without it, an awaited `signIn()` would report the anonymous identity it
+     * started from while the Connect it started was still completing. It is bounded, so
+     * a person who wandered off never leaves a promise pending for the life of the app.
+     */
+    async function connectThroughBrowser(gen) {
+        const landed = awaitInboundConnect();
+        try {
+            await adapters.openBrowser((0, connect_1.buildAppConnectUrl)(s.connectUrl, key));
+        }
+        catch {
+            settleInboundWaiters(false);
+            return;
+        }
+        if (gen !== s.generation)
+            return settleInboundWaiters(false);
+        // The redirect re-opens this app; dismiss the page it came from so the person is
+        // returned to where they tapped Sign in rather than to a finished connect page.
+        if (await landed)
+            dismissBrowser();
+    }
+    /**
+     * A promise for the next inbound Connect — `true` when one is redeemed, `false` when
+     * the wait expires or the client is destroyed. The timer is cleared on either, so a
+     * completed sign-in leaves nothing running.
+     */
+    function awaitInboundConnect() {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => settleInboundWaiters(false), CONNECT_BROWSER_WAIT_MS);
+            s.inboundWaiters.push((landed) => {
+                clearTimeout(timer);
+                resolve(landed);
+            });
+        });
+    }
+    /** Resolve everyone waiting on an inbound Connect, and stop waiting. */
+    function settleInboundWaiters(landed) {
+        const waiting = s.inboundWaiters;
+        s.inboundWaiters = [];
+        for (const resolve of waiting) {
+            try {
+                resolve(landed);
+            }
+            catch {
+                /* a waiter must never break the client */
+            }
+        }
+    }
+    /** Close the in-app browser this app opened — best-effort, like every seam here. */
+    function dismissBrowser() {
+        try {
+            adapters.dismissBrowser?.();
+        }
+        catch {
+            /* dismissing is a courtesy, never a failure */
+        }
+    }
+    /**
+     * Exchange a one-time Connect code for a Reporter session and persist it, leaving the
+     * client identified as the Account. The tail every half of Connect on mobile shares:
+     * {@link signIn}, where the app opened the connect page itself, and
+     * {@link handleInboundUrl}, where the code arrived on a deep link from an invite the
+     * person claimed elsewhere (ADR-0046). `gen` is the caller's lifecycle generation,
+     * re-checked after every await so a destroyed client abandons the redemption.
+     *
+     * Booting on the new identity is the **caller's** step, because the two callers
+     * differ: a redemption mid-run must re-boot to arm, while the one on the launch URL
+     * is followed by `start`'s own boot and would only duplicate it.
+     */
+    async function exchangeAndStore(code, gen) {
+        const result = await (0, sdk_core_1.exchangeConnectCode)(apiUrl, {
+            key,
+            code,
+            anonymousId: s.identity.anonymousId,
+            platform: "expo",
+        }, { fetch: adapters.fetch });
+        if (gen !== s.generation || !result)
+            return false;
+        s.reporterSessionToken = result.reporterSession;
+        s.identity = { ...s.identity, reporterSession: s.reporterSessionToken };
+        await (0, reporter_session_store_1.writeReporterSession)(adapters.secureStore, key, s.reporterSessionToken);
+        return gen === s.generation;
+    }
+    /**
+     * {@link exchangeAndStore} plus the re-boot that arms the client as the Account, and
+     * whether the Connect landed. A refused exchange changes no identity, so it is not
+     * re-booted on: the answer would be the one already in hand.
+     */
+    async function redeemConnectCode(code, gen) {
+        if (!(await exchangeAndStore(code, gen)))
+            return false;
+        await bootAndArm(gen);
+        return true;
+    }
+    /**
+     * Finish a Connect that started outside the app: read the one-time code off an
+     * inbound deep link and redeem it. Ignores a code it has already seen — iOS and
+     * Android both replay the launch URL in ordinary situations (a cold start whose
+     * `getInitialURL` is then re-delivered as a `url` event), and a code is single-use,
+     * so a second exchange would fail and report a Connect that in fact succeeded as one
+     * that did not. A declared `returnUrl` additionally narrows this to links on the
+     * app's own return origin; an app that declared none still redeems, because the
+     * claim page mints its code against the **Project's** app link, not against `init`.
+     */
+    async function handleInboundUrl(url, gen, { reboot = true } = {}) {
+        try {
+            const code = (0, connect_1.parseInboundConnectCode)(url, options.returnUrl);
+            if (!code || code === s.lastInboundCode)
+                return;
+            s.lastInboundCode = code;
+            const landed = reboot
+                ? await redeemConnectCode(code, gen)
+                : await exchangeAndStore(code, gen);
+            // A `signIn()` that went through the browser door is waiting on exactly this —
+            // the code it sent the person out for, arriving back on the app's own link.
+            if (landed)
+                settleInboundWaiters(true);
+        }
+        catch {
+            // A Connect problem must never disturb the host app.
+        }
+    }
+    /**
+     * Listen for Connect deep links that arrive **while the app runs** — the person was
+     * already in the app (or it was backgrounded) when they tapped the claim page's
+     * button. Armed on the `linking` seam alone: a Project's app link is allowlisted on
+     * the Project, so an app that never declared a `returnUrl` in `init` is still where
+     * a claim lands (ADR-0046). Silent on an app that provides no seam, which can never
+     * be a Connect target.
+     */
+    function armConnectLinking(gen) {
+        const linking = adapters.linking;
+        if (!linking)
+            return;
+        try {
+            const subscription = linking.addEventListener("url", (event) => {
+                void handleInboundUrl(event?.url ?? "", gen);
+            });
+            s.teardownLinking = () => subscription.remove();
+        }
+        catch {
+            // A Linking seam that refuses to subscribe is not a reason to fail a start.
+        }
+    }
+    /**
+     * Redeem the code on the URL the app was **launched** with, before the first boot —
+     * the invite journey's cold start (the person tapped the claim page's redirect and
+     * the app opened). Awaited rather than left in flight, so the one boot that follows
+     * carries the Reporter session: two concurrent boots race, and an anonymous answer
+     * landing last leaves a Connect that succeeded looking like one that never happened.
+     * The browser SDK exchanges a URL code before booting for the same reason.
+     *
+     * Best-effort throughout: a seam that throws, a launch URL that carries nothing, or
+     * an exchange the server refuses all fall through to an ordinary anonymous boot.
+     */
+    async function redeemLaunchUrl(gen) {
+        const linking = adapters.linking;
+        if (!linking)
+            return;
+        try {
+            const initial = await linking.getInitialURL();
+            if (gen !== s.generation || !initial)
+                return;
+            await handleInboundUrl(initial, gen, { reboot: false });
+        }
+        catch {
+            // Never throw into the host app.
+        }
+    }
+    /**
+     * Revoke the Reporter session, clear it from SecureStore, and re-boot as anonymous —
+     * so a gated Project's launcher (shake gesture) drops at once. Never throws.
+     */
+    async function signOut() {
+        const gen = s.generation;
+        try {
+            if (s.reporterSessionToken) {
+                await (0, sdk_core_1.revokeReporterSession)(apiUrl, s.reporterSessionToken, {
+                    fetch: adapters.fetch,
+                });
+            }
+            await (0, reporter_session_store_1.clearReporterSession)(adapters.secureStore, key);
+            s.reporterSessionToken = null;
+            s.identity = { ...s.identity, reporterSession: undefined };
+            if (gen === s.generation)
+                await bootAndArm(gen);
+        }
+        catch {
+            // A Fixback problem must never disturb the host app.
+        }
+    }
+    return { signIn, signOut, armConnectLinking, redeemLaunchUrl, settleInboundWaiters };
+}
+//# sourceMappingURL=client-connect.js.map

package/dist/client-connect.js.map

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

package/dist/client-replay.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Mobile replay's arming (ADR-0044): whether the client records at all, the frame
+ * recorder it starts and stops on every boot, and turning a frozen window into the
+ * report's video.
+ *
+ * One piece of the headless client (`./client`), created over the state every piece
+ * shares (`./client-state`). The recorder and the window the composer froze live
+ * there, because the composer (`present`, `submit`) and boot (`./client-boot`) both
+ * reach them.
+ */
+import { type CaptureConfig } from "@fixback/sdk-core";
+import type { ClientState } from "./client-state";
+import { type MobileReplayWindow } from "./replay";
+import { type ReplayAttachment } from "./replay-encode";
+/** The replay half of capture arming, as {@link createReplayArming} builds it. */
+export interface ReplayArming {
+    /** Start (or stop) the frame recorder for the Project's served config. */
+    armReplay(served: CaptureConfig | undefined): void;
+    /** Stop the recorder and drop every frame it owns (best-effort). */
+    disarmReplay(): void;
+    /** Delete a replay frame or encoded window file (best-effort, repeat-safe). */
+    releaseReplayFile(uri: string): void;
+    /** Give a frozen window back to the recorder, so its frames can be reclaimed. */
+    releaseReplayWindow(window: MobileReplayWindow | null): void;
+    /** Freeze the window as it stands now and encode it — the auto-capture path's replay. */
+    freezeAndEncodeReplay(): Promise<ReplayAttachment | null>;
+    /** Encode a frozen window for transport; `null` whenever it cannot become a video. */
+    encodeReplay(window: MobileReplayWindow | null): Promise<ReplayAttachment | null>;
+}
+/** Mobile replay's arming over the client's shared state. */
+export declare function createReplayArming(s: ClientState): ReplayArming;

package/dist/client-replay.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * Mobile replay's arming (ADR-0044): whether the client records at all, the frame
+ * recorder it starts and stops on every boot, and turning a frozen window into the
+ * report's video.
+ *
+ * One piece of the headless client (`./client`), created over the state every piece
+ * shares (`./client-state`). The recorder and the window the composer froze live
+ * there, because the composer (`present`, `submit`) and boot (`./client-boot`) both
+ * reach them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createReplayArming = createReplayArming;
+const sdk_core_1 = require("@fixback/sdk-core");
+const replay_1 = require("./replay");
+const replay_encode_1 = require("./replay-encode");
+/** Mobile replay's arming over the client's shared state. */
+function createReplayArming(s) {
+    const { options, adapters, warn, now, readEnvironment } = s;
+    /**
+     * Whether this app asked for mobile replay. Unlike every other stream, replay is
+     * **off until asked for** (ADR-0044): it records the device screen unmasked, so
+     * shipping an SDK update must never start it. Either spelling opts in —
+     * `capture: { replay: true }`, or simply passing a `replay` tuning object — and an
+     * explicit `capture: { replay: false }` always wins.
+     */
+    function replayRequested() {
+        if (typeof options.capture?.replay === "boolean")
+            return options.capture.replay;
+        return options.replay !== undefined;
+    }
+    /**
+     * Whether the server turned mobile replay off: the Project's replay toggle (the master kill
+     * switch, #138), or — on a server that sends it — `mobileReplay`, that toggle under the
+     * platform's `mobile_replay` feature flag for the workspace (#647). An older server sends only
+     * `replay`, which is then read as before.
+     */
+    function servedOff(served) {
+        if (typeof served?.replay === "boolean" && !served.replay)
+            return "project";
+        if (typeof served?.mobileReplay === "boolean" && !served.mobileReplay)
+            return "platform";
+        return null;
+    }
+    /**
+     * Whether replay records: this app asked for it, the server has not turned it off, and the
+     * platform can actually capture and encode frames.
+     */
+    function replayEnabled(served) {
+        if (!replayRequested())
+            return false;
+        if (servedOff(served) !== null)
+            return false;
+        return Boolean(adapters.captureReplayFrame && adapters.encodeReplaySegment);
+    }
+    /**
+     * Start (or stop) the frame recorder for the Project's served config. Re-armed on
+     * every boot, so a Project that turns replay off stops recording on the next boot
+     * rather than at the next launch — and the frames already buffered are deleted with
+     * the recorder, so nothing captured under the old answer can ship.
+     */
+    function armReplay(served) {
+        disarmReplay();
+        if (!replayEnabled(served)) {
+            const off = servedOff(served);
+            if (replayRequested() && off === "project") {
+                warn(`${sdk_core_1.WARN_PREFIX} replay is enabled in init but turned off for this Project — ` +
+                    "no replay will be recorded until it is enabled in the dashboard.");
+            }
+            else if (replayRequested() && off === "platform") {
+                warn(`${sdk_core_1.WARN_PREFIX} replay is enabled in init but mobile replay isn't available for this ` +
+                    "workspace yet — no replay will be recorded.");
+            }
+            else if (replayRequested() && !adapters.encodeReplaySegment) {
+                warn(`${sdk_core_1.WARN_PREFIX} replay is enabled in init but no native encoder is linked — ` +
+                    "mobile replay needs a development build (`npx expo prebuild`), not Expo Go.");
+            }
+            return;
+        }
+        s.replayRecorder = (0, replay_1.startMobileReplayRecorder)(options.replay ?? {}, {
+            captureFrame: (quality) => adapters.captureReplayFrame(quality),
+            releaseFrame: (uri) => releaseReplayFile(uri),
+            isActive: adapters.isAppActive,
+            now,
+        });
+    }
+    /** Stop the recorder and drop every frame it owns (best-effort). */
+    function disarmReplay() {
+        try {
+            s.replayRecorder?.stop();
+        }
+        catch {
+            /* teardown is best-effort */
+        }
+        s.replayRecorder = null;
+        s.pendingReplayWindow = null;
+    }
+    /** Delete a replay frame or encoded window file (best-effort, repeat-safe). */
+    function releaseReplayFile(uri) {
+        try {
+            adapters.releaseReplayFrame?.(uri);
+        }
+        catch {
+            /* release is best-effort */
+        }
+    }
+    /** Give a frozen window back to the recorder, so its frames can be reclaimed. */
+    function releaseReplayWindow(window) {
+        if (!window)
+            return;
+        try {
+            s.replayRecorder?.release(window);
+        }
+        catch {
+            /* release is best-effort */
+        }
+    }
+    /**
+     * Freeze the window as it stands **now** and encode it — the auto-capture path's
+     * whole replay step (ADR-0044): an uncaught error has no composer to open, so the
+     * throw itself is the moment the window is taken. The window is given back as soon
+     * as the encode is done, since nothing holds a draft for an auto report.
+     */
+    async function freezeAndEncodeReplay() {
+        const window = s.replayRecorder?.snapshot() ?? null;
+        if (!window)
+            return null;
+        try {
+            return await encodeReplay(window);
+        }
+        finally {
+            releaseReplayWindow(window);
+        }
+    }
+    /**
+     * Encode a frozen window for transport (ADR-0044). `null` whenever the window
+     * cannot become a video — no recorder, nothing watchable buffered, or an encoder
+     * that declined — so the report ships without replay rather than not at all.
+     */
+    async function encodeReplay(window) {
+        if (!window || !adapters.encodeReplaySegment)
+            return null;
+        return (0, replay_encode_1.encodeReplayWindow)(window, {
+            encodeSegment: adapters.encodeReplaySegment,
+            windowSize: () => {
+                const env = readEnvironment();
+                return {
+                    width: env.windowWidth ?? 0,
+                    height: env.windowHeight ?? 0,
+                };
+            },
+            maxEdge: (0, replay_1.resolvedMaxEdge)(options.replay),
+            now,
+        });
+    }
+    return {
+        armReplay,
+        disarmReplay,
+        releaseReplayFile,
+        releaseReplayWindow,
+        freezeAndEncodeReplay,
+        encodeReplay,
+    };
+}
+//# sourceMappingURL=client-replay.js.map

package/dist/client-replay.js.map

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

package/dist/client-state.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The state the headless client's pieces share (#661): one explicit object, where
+ * `createFixbackClient` used to be a single closure whose parts reached into each
+ * other's variables.
+ *
+ * It holds what the client resolves from its options once, at creation — the trimmed
+ * key, the canonical origin, the API base, the validated Release, the Correlation id's
+ * targets, the trace buffer, the listener sets — and every value that changes over the
+ * client's life: the status and the boot answer, the lifecycle generation, the Connect
+ * state, the armed capture, and maintenance mode's notice. Every piece is created over
+ * the same object — boot and capture arming (`./client-boot`), mobile replay
+ * (`./client-replay`), Connect (`./client-connect`), and the composer-facing surface
+ * (`./client`) — so what one piece writes is what the next one reads.
+ */
+import { type BootAnswer, type BreadcrumbBuffer, type FetchLike, type IdentityInputs, type MaintenanceNotice, type MaintenanceRecheck, type ReporterIdentity, type ReporterTier, type Teardown } from "@fixback/sdk-core";
+import type { AutoCaptureHandle } from "./error-capture";
+import type { FormDataFactory } from "./http";
+import type { ComposerContext, FixbackAdapters, FixbackOptions, FixbackStatus } from "./options";
+import type { EnvironmentInputs } from "./report";
+import type { MobileReplayRecorder, MobileReplayWindow } from "./replay";
+/** Everything a client knows and holds — see the module doc. */
+export interface ClientState {
+    readonly options: FixbackOptions;
+    readonly adapters: FixbackAdapters;
+    /** The publishable key, trimmed; `""` when there is none, which keeps the client dormant. */
+    readonly key: string;
+    /** The canonical `origin` the app reports as, or `""` when it declared none (ADR-0041). */
+    readonly origin: string;
+    /** The Fixback API base: trimmed, with no trailing slash. */
+    readonly apiUrl: string;
+    readonly now: () => number;
+    readonly readEnvironment: () => EnvironmentInputs;
+    /** The development-only warning sink (silent unless the adapters provide one). */
+    readonly warn: (message: string) => void;
+    /** The host app's Release (#117, ADR-0024), validated; `undefined` when unset or invalid. */
+    readonly release: string | undefined;
+    /** The Correlation id's targets (#540): the `propagateTo` entries that are bare origins. */
+    readonly propagateTo: readonly string[];
+    /** The trace buffer. It outlives every re-arm, so no lead-up is lost to one. */
+    readonly buffer: BreadcrumbBuffer;
+    readonly statusListeners: Set<(status: FixbackStatus) => void>;
+    readonly presentListeners: Set<(context: ComposerContext) => void>;
+    readonly identityListeners: Set<(identity: ReporterIdentity) => void>;
+    readonly maintenanceListeners: Set<(notice: MaintenanceNotice | null) => void>;
+    status: FixbackStatus;
+    boot: BootAnswer | null;
+    /** Monotonic id of the most recently *started* boot — see `bootAndArm` (`./client-boot`). */
+    bootSequence: number;
+    currentScreen: string | null;
+    teardownTrace: Teardown | null;
+    autoCapture: AutoCaptureHandle | null;
+    /**
+     * The mobile replay recorder, and the window frozen when the composer opened
+     * (ADR-0044). Both are null unless the Project enabled replay *and* this app asked
+     * for it — recording an unmasked screen is never something the SDK starts on its own.
+     */
+    replayRecorder: MobileReplayRecorder | null;
+    pendingReplayWindow: MobileReplayWindow | null;
+    identity: IdentityInputs;
+    reporterSessionToken: string | null;
+    account: {
+        name: string;
+        email: string;
+    } | null;
+    currentTier: ReporterTier | null;
+    connectUrl: string | undefined;
+    /** Removes the inbound deep-link listener; re-armed by each `start()`. */
+    teardownLinking: Teardown | null;
+    /**
+     * The last inbound Connect code redeemed, so a replayed launch URL is not exchanged
+     * twice. A code is single-use: the second attempt would fail, and a failed exchange
+     * is indistinguishable from a Connect that never worked.
+     */
+    lastInboundCode: string | null;
+    /**
+     * Callers waiting for the next inbound Connect to land — the browser door's
+     * `signIn()` (ADR-0052), which hands control to the connect page and gets it back as
+     * a deep link the inbound listener redeems. Resolved with `true` by a successful
+     * redemption, `false` when the wait gives up or the client is destroyed, so an
+     * awaited `signIn()` reports the identity the round trip actually produced instead
+     * of the anonymous one it started from.
+     */
+    inboundWaiters: Array<(landed: boolean) => void>;
+    /**
+     * The lifecycle generation. Each `start()` claims a new generation and every
+     * await inside it re-checks that it is still current; `destroy()` bumps the
+     * generation so an in-flight start abandons itself. A destroyed client can be
+     * started again — React 18+ StrictMode (and Fast Refresh) replay the
+     * provider's effect as mount → cleanup → re-mount on the same client
+     * instance, so destroy must not be terminal.
+     */
+    generation: number;
+    /** Whether a start() has claimed the current generation. */
+    running: boolean;
+    /** Maintenance mode's notice — boot's, or a held report's — else `null`. */
+    maintenance: MaintenanceNotice | null;
+    /** The next boot while the notice shows. */
+    readonly maintenanceRecheck: MaintenanceRecheck;
+    /**
+     * The last dormancy line printed, so a re-boot that changes nothing (a `signOut`
+     * back to the same refusal, an app resumed) does not repeat itself. Reset whenever
+     * the client becomes able to submit, so a *later* relapse is reported again.
+     */
+    lastDormancyWarning: string | null;
+}
+/**
+ * Resolve a client's options once, saying what it cannot use as it goes, and set up its
+ * state at rest: `idle`, nothing armed, no boot answer yet.
+ */
+export declare function createClientState(options: FixbackOptions, adapters: FixbackAdapters): ClientState;
+/** Move the client to `next`, telling every status listener once. */
+export declare function setStatus(s: ClientState, next: FixbackStatus): void;
+/**
+ * The `url` a report carries right now (spec 0004 §D). With an `origin` configured
+ * it reads `<origin>/<screen>`; without one — the default since ADR-0041 — the
+ * screen stands alone, so the Evidence still says *where* the reporter was rather
+ * than losing it to a setting nobody has to fill in. Ingest takes `url` as a free
+ * string and the dashboard renders it as text, so a bare screen name is honest
+ * here where a synthesised origin would be fiction.
+ */
+export declare function currentUrl(s: ClientState): string | undefined;
+/** The transport deps every call shares: the injected seams plus this app's origin. */
+export declare function submitDeps(s: ClientState): {
+    fetch?: FetchLike;
+    formData?: FormDataFactory;
+    origin: string;
+};
+/** The current Reporter identity for the composer's identity row and `identity()`. */
+export declare function reporterIdentity(s: ClientState): ReporterIdentity;
+/** Tell identity listeners the identity may have changed (boot / sign in / sign out). */
+export declare function notifyIdentity(s: ClientState): void;