@fixback/expo 0.8.3 → 0.9.1

package/dist/client.js

@@ -13,6 +13,13 @@
  * `resolveIdentity`, then `armCapture` — rather than one long procedure, so the
  * lifecycle reads as what it is and each step is testable on its own.
  *
+ * The client is a few pieces over one shared state object (`./client-state`, #661):
+ * boot and the capture it arms (`./client-boot`), mobile replay's arming
+ * (`./client-replay`), and Connect (`./client-connect`). What stays here is the
+ * lifecycle (`start`, `destroy`) and the composer-facing surface (`present`,
+ * `submit`, `trackScreen`). The public shapes live in `./options` and are
+ * re-exported from here.
+ *
  * Every platform touchpoint is an injected adapter (`FixbackAdapters`), so the
  * whole orchestration is unit-tested without React Native. Every path is
  * defensive: a Fixback problem leaves the host app untouched — `start` resolves
@@ -23,160 +30,32 @@ exports.REPLAY_BUCKET_MS = exports.DEFAULT_REPLAY_MAX_EDGE = exports.DEFAULT_REP
 exports.createFixbackClient = createFixbackClient;
 const sdk_core_1 = require("@fixback/sdk-core");
 Object.defineProperty(exports, "DEFAULT_API_URL", { enumerable: true, get: function () { return sdk_core_1.DEFAULT_API_URL; } });
-const breadcrumbs_1 = require("./breadcrumbs");
-const connect_1 = require("./connect");
-const reporter_session_store_1 = require("./reporter-session-store");
-const error_capture_1 = require("./error-capture");
+const client_boot_1 = require("./client-boot");
+const client_connect_1 = require("./client-connect");
+const client_replay_1 = require("./client-replay");
+const client_state_1 = require("./client-state");
 const identity_1 = require("./identity");
 const origin_1 = require("./origin");
 Object.defineProperty(exports, "canonicalizeOrigin", { enumerable: true, get: function () { return origin_1.canonicalizeOrigin; } });
-const propagation_1 = require("./propagation");
 const report_1 = require("./report");
-const replay_1 = require("./replay");
-const replay_encode_1 = require("./replay-encode");
+const reporter_session_store_1 = require("./reporter-session-store");
 const shake_1 = require("./shake");
 const submit_1 = require("./submit");
 const version_1 = require("./version");
-/**
- * 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;
 var shake_2 = require("./shake");
 Object.defineProperty(exports, "DEFAULT_SHAKE_SAMPLE_INTERVAL_MS", { enumerable: true, get: function () { return shake_2.DEFAULT_SHAKE_SAMPLE_INTERVAL_MS; } });
-var replay_2 = require("./replay");
-Object.defineProperty(exports, "DEFAULT_REPLAY_FPS", { enumerable: true, get: function () { return replay_2.DEFAULT_REPLAY_FPS; } });
-Object.defineProperty(exports, "DEFAULT_REPLAY_MAX_EDGE", { enumerable: true, get: function () { return replay_2.DEFAULT_REPLAY_MAX_EDGE; } });
-Object.defineProperty(exports, "REPLAY_BUCKET_MS", { enumerable: true, get: function () { return replay_2.REPLAY_BUCKET_MS; } });
-/** Normalise a base URL: trim and drop trailing slashes. */
-function normalizeBase(value) {
-    return value.trim().replace(/\/+$/, "");
-}
-/** Turn a screen name into the path segment of the report `url`. */
-function screenPath(name) {
-    return name.trim().replace(/^\/+/, "");
-}
+var replay_1 = require("./replay");
+Object.defineProperty(exports, "DEFAULT_REPLAY_FPS", { enumerable: true, get: function () { return replay_1.DEFAULT_REPLAY_FPS; } });
+Object.defineProperty(exports, "DEFAULT_REPLAY_MAX_EDGE", { enumerable: true, get: function () { return replay_1.DEFAULT_REPLAY_MAX_EDGE; } });
+Object.defineProperty(exports, "REPLAY_BUCKET_MS", { enumerable: true, get: function () { return replay_1.REPLAY_BUCKET_MS; } });
 /** Create the headless client. See the module doc. */
 function createFixbackClient(options, adapters = {}) {
-    const key = typeof options.key === "string" ? options.key.trim() : "";
-    const origin = typeof options.origin === "string" ? (0, origin_1.canonicalizeOrigin)(options.origin) : "";
-    const apiUrl = normalizeBase(options.apiUrl || sdk_core_1.DEFAULT_API_URL) || sdk_core_1.DEFAULT_API_URL;
-    const now = adapters.now ?? Date.now;
-    const readEnvironment = adapters.environment ?? (() => ({}));
-    const warn = adapters.warn ?? (() => { });
-    // The host app's Release (#117, ADR-0024), validated once here: an invalid value
-    // is dropped with a warning rather than shipped for the server to discard — and
-    // never a reason to refuse to start (capture must not break on config).
-    const release = options.release ? (0, sdk_core_1.normaliseRelease)(options.release) : undefined;
-    if (options.release && !release) {
-        warn(`Fixback: ignoring invalid release ${JSON.stringify(options.release)} — use 1-100 ` +
-            "visible characters with no whitespace or slashes (e.g. a git SHA or semver).");
-    }
-    // `environment` is no longer an option — the key selects the Environment (ADR
-    // 2026-09-24) — but a plain-JS caller gets no type error for passing it, and would
-    // otherwise believe it was honoured. Said once, here, never per report.
-    const removedOption = (0, sdk_core_1.removedEnvironmentOptionWarning)(options);
-    if (removedOption)
-        warn(`Fixback: ${removedOption}`);
-    // The Correlation id's targets (#540) — app topology known in code, so an init option
-    // rather than a served setting, and allowlist-only on mobile. An entry that is not a
-    // bare origin is never used, and said so once, the way an invalid release is — in the
-    // words every capture SDK shares.
-    const propagation = (0, propagation_1.normalizePropagateTo)(options.propagateTo);
-    const ignoredPropagateTo = (0, sdk_core_1.ignoredPropagateToWarning)(propagation.rejected);
-    if (ignoredPropagateTo)
-        warn(`Fixback: ${ignoredPropagateTo}`);
-    const buffer = (0, sdk_core_1.createBreadcrumbBuffer)({
-        beforeBreadcrumb: options.beforeBreadcrumb,
-        now,
-    });
-    let status = "idle";
-    let boot = null;
-    /** Monotonic id of the most recently *started* boot — see {@link bootAndArm}. */
-    let bootSequence = 0;
-    let currentScreen = null;
-    let teardownTrace = null;
-    let autoCapture = 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.
-     */
-    let replayRecorder = null;
-    let pendingReplayWindow = null;
-    let identity = {};
-    // Connect state (ADR-0066): the Reporter session token held after a Connect, the
-    // signed-in Account and its live tier (for the composer's identity row), and where the
-    // SDK opens Connect — all set from the boot answer, refreshed on every boot.
-    let reporterSessionToken = null;
-    let account = null;
-    let currentTier = null;
-    let connectUrl;
-    /** Removes the inbound deep-link listener; re-armed by each `start()`. */
-    let teardownLinking = 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.
-     */
-    let lastInboundCode = 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.
-     */
-    let inboundWaiters = [];
-    /**
-     * 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.
-     */
-    let generation = 0;
-    /** Whether a start() has claimed the current generation. */
-    let running = false;
-    const statusListeners = new Set();
-    const presentListeners = new Set();
-    const identityListeners = new Set();
-    function setStatus(next) {
-        if (status === next)
-            return;
-        status = next;
-        for (const listener of statusListeners) {
-            try {
-                listener(next);
-            }
-            catch {
-                /* a listener must never break the client */
-            }
-        }
-    }
-    /**
-     * 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.
-     */
-    function currentUrl() {
-        if (!origin)
-            return currentScreen ? screenPath(currentScreen) : undefined;
-        return currentScreen ? `${origin}/${screenPath(currentScreen)}` : origin;
-    }
-    /** The transport deps every call shares: the injected seams plus this app's origin. */
-    function submitDeps() {
-        return { fetch: adapters.fetch, formData: adapters.formData, origin };
-    }
+    const s = (0, client_state_1.createClientState)(options, adapters);
+    const { warn, now, readEnvironment, key, apiUrl, release, buffer } = s;
+    const replay = (0, client_replay_1.createReplayArming)(s);
+    const { releaseReplayFile, releaseReplayWindow, encodeReplay } = replay;
+    const { bootAndArm, resolveStreams, armTrace, disarmCapture, setMaintenance, clearMaintenanceRecheck, } = (0, client_boot_1.createBoot)(s, replay);
+    const { signIn, signOut, armConnectLinking, redeemLaunchUrl, settleInboundWaiters } = (0, client_connect_1.createConnect)(s, bootAndArm);
     /**
      * Step one of `start`: settle the identity evidence this session presents — the host
      * app's own `hostIdentity`, the SDK-managed anonymous id (persisted when storage is
@@ -186,362 +65,32 @@ function createFixbackClient(options, adapters = {}) {
      */
     async function resolveIdentity() {
         const anonymousId = options.anonymousId ?? (await (0, identity_1.ensureAnonymousId)(adapters.storage));
-        reporterSessionToken = await (0, reporter_session_store_1.readReporterSession)(adapters.secureStore, key);
+        s.reporterSessionToken = await (0, reporter_session_store_1.readReporterSession)(adapters.secureStore, key);
         return {
             ...(options.hostIdentity ? { hostIdentity: options.hostIdentity } : {}),
-            ...(reporterSessionToken ? { reporterSession: reporterSessionToken } : {}),
+            ...(s.reporterSessionToken ? { reporterSession: s.reporterSessionToken } : {}),
             anonymousId,
         };
     }
-    /** The current Reporter identity for the composer's identity row and `identity()`. */
-    function reporterIdentity() {
-        return account
-            ? {
-                status: "connected",
-                name: account.name,
-                email: account.email,
-                tier: currentTier ?? null,
-            }
-            : { status: "anonymous" };
-    }
-    /** Tell identity listeners the identity may have changed (boot / sign in / sign out). */
-    function notifyIdentity() {
-        const current = reporterIdentity();
-        for (const listener of identityListeners) {
-            try {
-                listener(current);
-            }
-            catch {
-                /* a listener must never break the client */
-            }
-        }
-    }
-    /** Tear down the trace hooks (best-effort), so they can be re-armed. */
-    function disarmTrace() {
-        try {
-            teardownTrace?.();
-        }
-        catch {
-            /* teardown is best-effort */
-        }
-        teardownTrace = null;
-    }
-    /** Tear down the trace + auto-capture hooks (best-effort), so they can be re-armed. */
-    function disarmCapture() {
-        disarmTrace();
-        disarmReplay();
-        try {
-            autoCapture?.destroy();
-        }
-        catch {
-            /* teardown is best-effort */
-        }
-        autoCapture = null;
-    }
-    /**
-     * The effective per-stream capture flags: an init option overrides the served
-     * config, and an absent (or malformed) served value means **on** — the default-on
-     * rule (spec 0003 §C, ported). Called with no answer before boot has one, which is
-     * how the pre-boot arming lands on "both streams on".
-     */
-    function resolveStreams(served) {
-        return {
-            console: options.capture?.console ??
-                (typeof served?.console === "boolean" ? served.console : true),
-            network: options.capture?.network ??
-                (typeof served?.network === "boolean" ? served.network : true),
-        };
-    }
-    /**
-     * 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 replay records: this app asked for it, the Project has not turned it off
-     * (its toggle stays the master kill switch, #138), and the platform can actually
-     * capture and encode frames.
-     */
-    function replayEnabled(served) {
-        if (!replayRequested())
-            return false;
-        if (typeof served?.replay === "boolean" && !served.replay)
-            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)) {
-            if (replayRequested() && typeof served?.replay === "boolean" && !served.replay) {
-                warn("Fixback: 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() && !adapters.encodeReplaySegment) {
-                warn("Fixback: replay is enabled in init but no native encoder is linked — " +
-                    "mobile replay needs a development build (`npx expo prebuild`), not Expo Go.");
-            }
-            return;
-        }
-        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 {
-            replayRecorder?.stop();
-        }
-        catch {
-            /* teardown is best-effort */
-        }
-        replayRecorder = null;
-        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 {
-            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 = 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,
-        });
-    }
-    /**
-     * Install the trace instrumentation for the given per-stream flags, replacing
-     * whatever is installed — the teardown runs first, so a re-arm can never double-wrap
-     * `console` or `XMLHttpRequest`.
-     */
-    function armTrace(streams) {
-        disarmTrace();
-        teardownTrace = (0, breadcrumbs_1.instrumentBreadcrumbs)(buffer, {
-            consoleObj: adapters.consoleObj,
-            xhr: adapters.xhr,
-            ignoreUrl: (url) => (0, sdk_core_1.isFixbackApiRequest)(apiUrl, url),
-            now,
-            captureConsole: streams.console,
-            captureNetwork: streams.network,
-            propagateTo: propagation.origins,
-        });
-    }
-    /**
-     * Boot with the current identity and reconcile capture + the identity row. Shared by
-     * `start`, `signIn`, and `signOut`: it swaps in the refreshed Reporter session token
-     * (30-day sliding), records the Account / tier / connect URL the boot answer carries,
-     * and arms capture only while a submission would be accepted — so a gated Project's
-     * shake gesture arms exactly when the Account becomes eligible, and drops when it signs
-     * out. `gen` is the caller's lifecycle generation; every await re-checks it so a
-     * destroyed (or restarted) client abandons this in-flight boot.
-     */
-    async function bootAndArm(gen) {
-        // Boots are last-one-wins. Two can be in flight at once — a deep link redeemed
-        // while `start`'s boot is still out, a `signOut` racing a Connect — and they carry
-        // *different* identities, so an older answer landing last would undo a newer one:
-        // the shake gesture would stay withheld from a Reporter the server had just
-        // accepted, with the session sitting unused in SecureStore until the next launch.
-        const seq = ++bootSequence;
-        let failure = null;
-        const answer = await (0, sdk_core_1.requestBoot)(apiUrl, { key, ...(0, sdk_core_1.compactIdentity)(identity) }, {
-            fetch: adapters.fetch,
-            origin,
-            onFailure: (reason) => {
-                failure = reason;
-            },
-        });
-        if (gen !== generation || seq !== bootSequence)
-            return;
-        boot = answer;
-        // Swap in the refreshed session token (30-day sliding) when boot returned one.
-        if (answer?.reporterSession) {
-            reporterSessionToken = answer.reporterSession;
-            identity = { ...identity, reporterSession: reporterSessionToken };
-            await (0, reporter_session_store_1.writeReporterSession)(adapters.secureStore, key, reporterSessionToken);
-            if (gen !== generation || seq !== bootSequence)
-                return;
-        }
-        currentTier = answer?.tier ?? null;
-        account = answer?.account ?? null;
-        connectUrl = answer?.connectUrl;
-        notifyIdentity();
-        if (answer && answer.canSubmit) {
-            // Re-arm from a clean slate (the shared trace buffer persists across a re-arm, so
-            // no lead-up is lost) — a Connect that just made the Account eligible arms here.
-            disarmCapture();
-            armCapture(answer);
-            lastDormancyWarning = null;
-            setStatus("ready");
-        }
-        else {
-            // Say why, once per dormant boot, in a development build (`warn` is silent in
-            // production). A dormant SDK is otherwise indistinguishable on the device from
-            // one that was never installed — and the reason is right here in the answer the
-            // client already holds, or in the failure that stopped one arriving.
-            warnDormant(answer, failure);
-            // Not eligible (a gated Project the Account cannot yet report on, or a signed-out
-            // visitor): nothing armed, but `connectUrl` is retained so `signIn` still works.
-            // What the pre-boot arming optimistically recorded is dropped with it — this
-            // Account cannot submit, so holding its console and network lead-up in memory
-            // serves nothing. A later `signIn` re-arms and starts a fresh lead-up.
-            disarmCapture();
-            buffer.clear();
-            setStatus("disabled");
-        }
-    }
-    /**
-     * 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.
-     */
-    let lastDormancyWarning = null;
-    /** Explain a dormant boot to the developer, at most once per distinct reason. */
-    function warnDormant(answer, failure) {
-        const message = (0, sdk_core_1.explainDormancy)({
-            answer,
-            failure,
-            apiUrl,
-            origin: origin || undefined,
-            // Connect needs a door this app can actually open — an auth session it can
-            // return through, or an in-app browser plus the seam the redirect comes back
-            // on. With neither, naming `signIn()` would send the developer down a dead end.
-            signInCall: canSignIn() ? "Fixback.signIn()" : undefined,
-        });
-        if (!message || message === lastDormancyWarning)
-            return;
-        lastDormancyWarning = message;
-        warn(message);
-    }
-    /**
-     * Step two of `start`: with a boot answer that says a submission would be
-     * accepted, reconcile the trace instrumentation against the Project's served
-     * capture config and install (unless turned off) automatic error capture.
-     * Reaching here means the Gate is already satisfied, so an auto-error inherits
-     * the very tier boot derived.
-     *
-     * The trace was already armed optimistically at `start()`, so this is a
-     * **reconciliation**, not the first arming: a stream the Project turns off is both
-     * uninstrumented and **purged**, so what the optimistic window recorded for it can
-     * never ship.
-     */
-    function armCapture(answer) {
-        const streams = resolveStreams(answer.capture);
-        armTrace(streams);
-        if (!streams.console)
-            buffer.clearStream("console");
-        if (!streams.network)
-            buffer.clearStream("network");
-        // Replay arms **here and only here** — never optimistically before boot, the way
-        // the trace does. A trace that turns out to be unwanted is purged; frames already
-        // written to the cache are a recording that should not have started (ADR-0044).
-        armReplay(answer.capture);
-        if (options.autoCapture === false)
-            return;
-        autoCapture = (0, error_capture_1.installErrorCapture)({
-            apiUrl,
-            key,
-            origin,
-            identity,
-            sdkVersion: version_1.EXPO_SDK_VERSION,
-            release,
-            buffer,
-            beforeSend: options.beforeSend,
-            scrub: options.scrub,
-            environment: readEnvironment,
-            currentUrl,
-            // The replay window as it stood at the throw (ADR-0044): frozen and encoded at
-            // filing time, on the rich first report only — a flush is a count update, and
-            // re-encoding the same window for it would be pure cost.
-            captureReplay: () => freezeAndEncodeReplay(),
-            errorUtils: adapters.errorUtils,
-            appState: adapters.appState,
-            deps: {
-                submitReport: (url, input) => (0, submit_1.submitReport)(url, input, submitDeps()),
-            },
-            now,
-        });
-    }
     async function start() {
-        if (running)
+        if (s.running)
             return;
-        running = true;
-        const gen = ++generation;
-        setStatus("starting");
+        s.running = true;
+        const gen = ++s.generation;
+        (0, client_state_1.setStatus)(s, "starting");
         try {
             // The master gate (`enabled: false`) keeps the SDK completely dormant: no
             // identity, no boot call, nothing instrumented.
             if (options.enabled === false) {
-                setStatus("disabled");
+                (0, client_state_1.setStatus)(s, "disabled");
                 return;
             }
             // Only the key is required. An `origin` used to be mandatory here because
             // ingest refused a submission without one; it no longer does (ADR-0041), so an
             // app that configures none boots and reports normally.
             if (!key) {
-                warn("Fixback: init needs a publishable `key`; staying dormant.");
-                setStatus("disabled");
+                warn(`${sdk_core_1.WARN_PREFIX} init needs a publishable \`key\`; staying dormant.`);
+                (0, client_state_1.setStatus)(s, "disabled");
                 return;
             }
             // Arm the trace **before** boot. Boot is a network round trip, and reading the
@@ -554,8 +103,8 @@ function createFixbackClient(options, adapters = {}) {
             // turns out to be off. Nothing can leave the process in between: a submission
             // needs `ready`, which only a `canSubmit` boot sets.
             armTrace(resolveStreams(undefined));
-            identity = await resolveIdentity();
-            if (gen !== generation)
+            s.identity = await resolveIdentity();
+            if (gen !== s.generation)
                 return; // destroyed (or restarted) while resolving
             // Listen for Connect deep links before booting, so one delivered while the boot
             // round trip is in flight is not missed (ADR-0046).
@@ -564,7 +113,7 @@ function createFixbackClient(options, adapters = {}) {
             // invite the person claimed a moment ago is what opened the app, and the boot
             // below should already carry the Reporter session it established.
             await redeemLaunchUrl(gen);
-            if (gen !== generation)
+            if (gen !== s.generation)
                 return; // destroyed (or restarted) while redeeming
             // Boot, then arm auto-capture (and the shake gesture, via `ready`) only if a
             // submission would be accepted; sets `disabled` otherwise, keeping `connectUrl`
@@ -578,290 +127,22 @@ function createFixbackClient(options, adapters = {}) {
             warn(`Fixback is dormant: start() failed — ${error instanceof Error ? error.message : String(error)}`);
             // The optimistic pre-boot trace goes dormant with it: no submission can follow
             // a start that failed, so nothing should stay instrumented or held in memory.
-            if (gen === generation) {
+            if (gen === s.generation) {
                 disarmCapture();
                 buffer.clear();
-                setStatus("disabled");
-            }
-        }
-    }
-    /**
-     * 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 = generation;
-        if (!connectUrl)
-            return reporterIdentity(); // not booted, or an older server
-        try {
-            if (options.returnUrl && adapters.openAuthSession) {
-                const outcome = await (0, connect_1.startExpoConnect)(adapters.openAuthSession, {
-                    connectUrl,
-                    key,
-                    returnUrl: options.returnUrl,
-                });
-                if (gen !== generation)
-                    return reporterIdentity();
-                if (outcome.kind === "code")
-                    await redeemConnectCode(outcome.code, gen);
-            }
-            else if (canConnectThroughBrowser()) {
-                await connectThroughBrowser(gen);
-            }
-            else {
-                warn(explainSignInDoor());
-            }
-        }
-        catch {
-            // A Connect problem must never disturb the host app.
-        }
-        return reporterIdentity();
-    }
-    /**
-     * 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() {
-        return Boolean(adapters.openBrowser && adapters.linking);
-    }
-    /** Whether `signIn()` can open a door at all — what the dormancy hint is gated on. */
-    function canSignIn() {
-        return Boolean((options.returnUrl && adapters.openAuthSession) || canConnectThroughBrowser());
-    }
-    /** Why `signIn()` could not open a door, named by what this app is actually missing. */
-    function explainSignInDoor() {
-        if (!adapters.openBrowser && !adapters.openAuthSession) {
-            return "Fixback: signIn needs a browser to open the connect page — install expo-web-browser.";
-        }
-        if (!adapters.linking) {
-            return "Fixback: 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 "Fixback: signIn needs either an auth-session opener plus a `returnUrl` in init, or an in-app browser (install expo-web-browser).";
-    }
-    /**
-     * 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)(connectUrl, key));
-        }
-        catch {
-            settleInboundWaiters(false);
-            return;
-        }
-        if (gen !== 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);
-            inboundWaiters.push((landed) => {
-                clearTimeout(timer);
-                resolve(landed);
-            });
-        });
-    }
-    /** Resolve everyone waiting on an inbound Connect, and stop waiting. */
-    function settleInboundWaiters(landed) {
-        const waiting = inboundWaiters;
-        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: identity.anonymousId,
-            platform: "expo",
-        }, { fetch: adapters.fetch });
-        if (gen !== generation || !result)
-            return false;
-        reporterSessionToken = result.reporterSession;
-        identity = { ...identity, reporterSession: reporterSessionToken };
-        await (0, reporter_session_store_1.writeReporterSession)(adapters.secureStore, key, reporterSessionToken);
-        return gen === 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 === lastInboundCode)
-                return;
-            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);
-            });
-            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 !== 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 = generation;
-        try {
-            if (reporterSessionToken) {
-                await (0, sdk_core_1.revokeReporterSession)(apiUrl, reporterSessionToken, {
-                    fetch: adapters.fetch,
-                });
+                (0, client_state_1.setStatus)(s, "disabled");
             }
-            await (0, reporter_session_store_1.clearReporterSession)(adapters.secureStore, key);
-            reporterSessionToken = null;
-            identity = { ...identity, reporterSession: undefined };
-            if (gen === generation)
-                await bootAndArm(gen);
-        }
-        catch {
-            // A Fixback problem must never disturb the host app.
         }
     }
     async function present() {
-        if (status !== "ready")
+        if (s.status !== "ready")
             return;
         // Freeze the replay window as the composer opens (ADR-0055's posture, ported):
         // what the Reporter is reporting is what just happened, not what happens while
         // they type. A window left over from a composer they dismissed is given back
         // first, so its frames are never retained twice.
-        releaseReplayWindow(pendingReplayWindow);
-        pendingReplayWindow = replayRecorder?.snapshot() ?? null;
+        releaseReplayWindow(s.pendingReplayWindow);
+        s.pendingReplayWindow = s.replayRecorder?.snapshot() ?? null;
         let screenshot = null;
         if (options.screenshots !== false && adapters.captureScreenshot) {
             try {
@@ -872,7 +153,7 @@ function createFixbackClient(options, adapters = {}) {
             }
         }
         const context = { screenshot };
-        for (const listener of presentListeners) {
+        for (const listener of s.presentListeners) {
             try {
                 listener(context);
             }
@@ -888,7 +169,7 @@ function createFixbackClient(options, adapters = {}) {
             // (ADR-0023).
             (0, report_1.assembleContent)({
                 comment: draft.comment,
-                url: currentUrl(),
+                url: (0, client_state_1.currentUrl)(s),
                 environment: (0, report_1.collectEnvironment)(readEnvironment(), version_1.EXPO_SDK_VERSION, release),
                 trace: buffer.snapshot(),
             }), { hook: options.beforeSend, scrub: options.scrub });
@@ -898,8 +179,12 @@ function createFixbackClient(options, adapters = {}) {
             // Encode the window frozen when the composer opened (ADR-0044). This runs after
             // the Reporter pressed send, inside a flow they initiated — the one place the
             // cost of an encode is theirs to spend rather than the app's.
-            const replay = await encodeReplay(pendingReplayWindow);
-            const result = await (0, submit_1.submitReport)(apiUrl, { key, identity, content, screenshot: draft.screenshot ?? null, replay }, submitDeps());
+            const replay = await encodeReplay(s.pendingReplayWindow);
+            const result = await (0, submit_1.submitReport)(apiUrl, { key, identity: s.identity, content, screenshot: draft.screenshot ?? null, replay }, (0, client_state_1.submitDeps)(s));
+            // Held for maintenance (an app that booted before it began): show the notice and
+            // ask boot when it ends — the composer keeps the draft for the Reporter to send then.
+            if (!result.ok && result.reason === "maintenance")
+                setMaintenance(result.maintenance);
             // A delivered screenshot's tmpfile has served its purpose — release it.
             // On a failure the file is kept: the composer holds the draft for retry.
             if (result.ok)
@@ -909,8 +194,8 @@ function createFixbackClient(options, adapters = {}) {
             if (replay)
                 releaseReplayFile(replay.file.uri);
             if (result.ok) {
-                releaseReplayWindow(pendingReplayWindow);
-                pendingReplayWindow = null;
+                releaseReplayWindow(s.pendingReplayWindow);
+                s.pendingReplayWindow = null;
             }
             return result;
         }
@@ -940,17 +225,17 @@ function createFixbackClient(options, adapters = {}) {
      * session and the app's cache keeps a recording nobody reported.
      */
     function discardReplay() {
-        releaseReplayWindow(pendingReplayWindow);
-        pendingReplayWindow = null;
+        releaseReplayWindow(s.pendingReplayWindow);
+        s.pendingReplayWindow = null;
     }
     function trackScreen(name) {
         try {
             const trimmed = typeof name === "string" ? name.trim() : "";
             if (!trimmed)
                 return;
-            const from = currentUrl();
-            currentScreen = trimmed;
-            const to = currentUrl();
+            const from = (0, client_state_1.currentUrl)(s);
+            s.currentScreen = trimmed;
+            const to = (0, client_state_1.currentUrl)(s);
             if (from && to && from !== to) {
                 buffer.add((0, sdk_core_1.navigationCrumb)(from, to, now()));
             }
@@ -961,17 +246,17 @@ function createFixbackClient(options, adapters = {}) {
     }
     return {
         start,
-        getStatus: () => status,
-        getBoot: () => boot,
-        canSubmit: () => status === "ready" && boot?.canSubmit === true,
+        getStatus: () => s.status,
+        getBoot: () => s.boot,
+        canSubmit: () => s.status === "ready" && s.boot?.canSubmit === true,
         onStatus(listener) {
-            statusListeners.add(listener);
-            return () => statusListeners.delete(listener);
+            s.statusListeners.add(listener);
+            return () => s.statusListeners.delete(listener);
         },
         present,
         onPresent(listener) {
-            presentListeners.add(listener);
-            return () => presentListeners.delete(listener);
+            s.presentListeners.add(listener);
+            return () => s.presentListeners.delete(listener);
         },
         trackScreen,
         submit,
@@ -980,31 +265,39 @@ function createFixbackClient(options, adapters = {}) {
         shakeConfig: () => (0, shake_1.resolveShakeConfig)(options.shake),
         signIn,
         signOut,
-        identity: () => reporterIdentity(),
+        identity: () => (0, client_state_1.reporterIdentity)(s),
         onIdentity(listener) {
-            identityListeners.add(listener);
-            return () => identityListeners.delete(listener);
+            s.identityListeners.add(listener);
+            return () => s.identityListeners.delete(listener);
+        },
+        maintenance: () => s.maintenance,
+        onMaintenance(listener) {
+            s.maintenanceListeners.add(listener);
+            return () => s.maintenanceListeners.delete(listener);
         },
         destroy() {
             // Abandon any in-flight start and allow a later start() to re-arm —
             // React StrictMode replays the provider's effect on this same instance.
-            generation += 1;
-            running = false;
+            s.generation += 1;
+            s.running = false;
+            clearMaintenanceRecheck();
+            s.maintenance = null;
             disarmCapture();
             try {
-                teardownLinking?.();
+                s.teardownLinking?.();
             }
             catch {
                 /* teardown is best-effort */
             }
-            teardownLinking = null;
+            s.teardownLinking = null;
             // Nothing will redeem an inbound code now, so a `signIn()` still waiting on one
             // is answered rather than left pending for the life of the app.
             settleInboundWaiters(false);
-            statusListeners.clear();
-            presentListeners.clear();
-            identityListeners.clear();
-            setStatus("disabled");
+            s.statusListeners.clear();
+            s.presentListeners.clear();
+            s.identityListeners.clear();
+            s.maintenanceListeners.clear();
+            (0, client_state_1.setStatus)(s, "disabled");
         },
     };
 }