@everframe/react-native 0.9.0

package/dist/index.d.ts

@@ -0,0 +1,1006 @@
+import * as React from 'react';
+import { EverframeUserSpec, ConfigOpts } from './NativeEverframe.js';
+export { Rect, Spec } from './NativeEverframe.js';
+import { E as EverframeIntegration } from './types-D5e4kWaw.js';
+import { z } from 'zod';
+import { ViewProps, EventSubscription } from 'react-native';
+
+type JsonScalar = string | number | boolean | null;
+type JsonValue = JsonScalar | JsonValue[] | JsonObject;
+type JsonObject = {
+    [key: string]: JsonValue;
+};
+
+declare const ReportEnvelope: z.ZodObject<{
+    protocolVersion: z.ZodLiteral<"1.0">;
+    reportId: z.ZodString;
+    submittedAt: z.ZodString;
+    source: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        manual: "manual";
+        crash: "crash";
+    }>>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    sdk: z.ZodObject<{
+        name: z.ZodEnum<{
+            "everframe-react": "everframe-react";
+            "everframe-web": "everframe-web";
+            "everframe-react-native": "everframe-react-native";
+            "everframe-ios": "everframe-ios";
+            "everframe-android": "everframe-android";
+        }>;
+        version: z.ZodString;
+        platform: z.ZodEnum<{
+            web: "web";
+            ios: "ios";
+            android: "android";
+            tvos: "tvos";
+            tizen: "tizen";
+            webos: "webos";
+            androidtv: "androidtv";
+        }>;
+        formFactor: z.ZodEnum<{
+            phone: "phone";
+            tablet: "tablet";
+            desktop: "desktop";
+            tv: "tv";
+        }>;
+    }, z.core.$loose>;
+    reporter: z.ZodObject<{
+        title: z.ZodString;
+        description: z.ZodString;
+        user: z.ZodOptional<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            email: z.ZodOptional<z.ZodString>;
+            displayName: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>;
+    captures: z.ZodObject<{
+        screenshot: z.ZodBoolean;
+        uiTree: z.ZodBoolean;
+        focus: z.ZodBoolean;
+        logs: z.ZodBoolean;
+        network: z.ZodBoolean;
+        breadcrumbs: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$loose>;
+    captureControl: z.ZodObject<{
+        included: z.ZodArray<z.ZodString>;
+        excluded: z.ZodArray<z.ZodString>;
+        degradedReason: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    payload: z.ZodObject<{
+        focus: z.ZodOptional<z.ZodObject<{
+            path: z.ZodArray<z.ZodNumber>;
+            componentPath: z.ZodString;
+            source: z.ZodEnum<{
+                mouse: "mouse";
+                keyboard: "keyboard";
+                remote: "remote";
+                touch: "touch";
+                programmatic: "programmatic";
+            }>;
+            cursor: z.ZodOptional<z.ZodObject<{
+                x: z.ZodNumber;
+                y: z.ZodNumber;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        logs: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        network: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        breadcrumbs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            t: z.ZodNumber;
+            seq: z.ZodNumber;
+            kind: z.ZodEnum<{
+                custom: "custom";
+                error: "error";
+                navigation: "navigation";
+                tap: "tap";
+                console: "console";
+                network: "network";
+                lifecycle: "lifecycle";
+            }>;
+            level: z.ZodOptional<z.ZodEnum<{
+                error: "error";
+                debug: "debug";
+                info: "info";
+                warn: "warn";
+            }>>;
+            message: z.ZodString;
+            data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            truncated: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$loose>>>;
+        networkBodies: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            ref: z.ZodNumber;
+            t: z.ZodNumber;
+            reqBody: z.ZodOptional<z.ZodString>;
+            resBody: z.ZodOptional<z.ZodString>;
+            reqBodyTruncated: z.ZodOptional<z.ZodBoolean>;
+            resBodyTruncated: z.ZodOptional<z.ZodBoolean>;
+            reqBodyBytes: z.ZodOptional<z.ZodNumber>;
+            resBodyBytes: z.ZodOptional<z.ZodNumber>;
+            reqHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            resHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            reqBodySkipped: z.ZodOptional<z.ZodEnum<{
+                error: "error";
+                "content-type": "content-type";
+                unsupported: "unsupported";
+            }>>;
+            resBodySkipped: z.ZodOptional<z.ZodEnum<{
+                error: "error";
+                "content-type": "content-type";
+                unsupported: "unsupported";
+            }>>;
+        }, z.core.$loose>>>;
+        vitals: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"sample">;
+            t: z.ZodNumber;
+            cpu: z.ZodOptional<z.ZodNumber>;
+            mem: z.ZodNumber;
+            extras: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"player">;
+            t: z.ZodNumber;
+            type: z.ZodEnum<{
+                error: "error";
+                play: "play";
+                pause: "pause";
+                seek: "seek";
+                buffer_start: "buffer_start";
+                buffer_end: "buffer_end";
+                bitrate_change: "bitrate_change";
+                rate_change: "rate_change";
+                startup: "startup";
+                dropped_frames: "dropped_frames";
+                source_change: "source_change";
+                player_attach: "player_attach";
+                player_detach: "player_detach";
+                drm: "drm";
+                quality_change: "quality_change";
+                stats: "stats";
+            }>;
+            playerId: z.ZodOptional<z.ZodString>;
+            data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            truncated: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"custom">;
+            t: z.ZodNumber;
+            name: z.ZodString;
+            data: z.ZodOptional<z.ZodUnknown>;
+            truncated: z.ZodOptional<z.ZodBoolean>;
+            playerId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>], "kind">>>;
+        resources: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            t: z.ZodNumber;
+            cpu: z.ZodOptional<z.ZodNumber>;
+            mem: z.ZodNumber;
+            extras: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+        }, z.core.$strip>>>;
+        annotations: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        redactions: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        extra: z.ZodOptional<z.ZodString>;
+        crash: z.ZodOptional<z.ZodObject<{
+            causeChain: z.ZodOptional<z.ZodObject<{
+                causes: z.ZodArray<z.ZodObject<{
+                    exceptionType: z.ZodString;
+                    message: z.ZodString;
+                    frames: z.ZodArray<z.ZodObject<{
+                        raw: z.ZodString;
+                        file: z.ZodOptional<z.ZodString>;
+                        function: z.ZodOptional<z.ZodString>;
+                        line: z.ZodOptional<z.ZodNumber>;
+                        col: z.ZodOptional<z.ZodNumber>;
+                    }, z.core.$strip>>;
+                    framesTruncated: z.ZodBoolean;
+                }, z.core.$strip>>;
+                truncated: z.ZodBoolean;
+            }, z.core.$strip>>;
+            details: z.ZodOptional<z.ZodObject<{
+                severity: z.ZodOptional<z.ZodEnum<{
+                    error: "error";
+                    info: "info";
+                    warning: "warning";
+                }>>;
+                context: z.ZodOptional<z.ZodString>;
+                metadata: z.ZodOptional<z.ZodType<JsonObject, unknown, z.core.$ZodTypeInternals<JsonObject, unknown>>>;
+                truncated: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>>;
+            jsBundle: z.ZodOptional<z.ZodObject<{
+                engine: z.ZodLiteral<"hermes">;
+                platform: z.ZodEnum<{
+                    ios: "ios";
+                    android: "android";
+                }>;
+                buildId: z.ZodString;
+                bundleName: z.ZodString;
+            }, z.core.$strip>>;
+            jvm: z.ZodOptional<z.ZodObject<{
+                mappingId: z.ZodOptional<z.ZodString>;
+                causes: z.ZodArray<z.ZodObject<{
+                    exceptionType: z.ZodString;
+                    message: z.ZodString;
+                    frames: z.ZodArray<z.ZodObject<{
+                        raw: z.ZodString;
+                        file: z.ZodOptional<z.ZodString>;
+                        function: z.ZodOptional<z.ZodString>;
+                        line: z.ZodOptional<z.ZodNumber>;
+                        col: z.ZodOptional<z.ZodNumber>;
+                    }, z.core.$loose>>;
+                    framesTruncated: z.ZodBoolean;
+                }, z.core.$strip>>;
+                causesTruncated: z.ZodBoolean;
+            }, z.core.$strip>>;
+            exceptionType: z.ZodString;
+            message: z.ZodString;
+            frames: z.ZodArray<z.ZodObject<{
+                raw: z.ZodString;
+                file: z.ZodOptional<z.ZodString>;
+                function: z.ZodOptional<z.ZodString>;
+                line: z.ZodOptional<z.ZodNumber>;
+                col: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$loose>>;
+            threadName: z.ZodOptional<z.ZodString>;
+            mechanism: z.ZodString;
+            handled: z.ZodBoolean;
+            fatal: z.ZodOptional<z.ZodBoolean>;
+            occurredAt: z.ZodString;
+            fingerprint: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>;
+    context: z.ZodObject<{
+        app: z.ZodObject<{
+            name: z.ZodString;
+            version: z.ZodString;
+            build: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>;
+        device: z.ZodObject<{
+            os: z.ZodString;
+            osVersion: z.ZodString;
+            model: z.ZodOptional<z.ZodString>;
+            screenSize: z.ZodObject<{
+                width: z.ZodNumber;
+                height: z.ZodNumber;
+            }, z.core.$strip>;
+            pixelRatio: z.ZodNumber;
+            locale: z.ZodString;
+            timezone: z.ZodString;
+            userAgent: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>;
+        route: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>;
+    attachments: z.ZodArray<z.ZodObject<{
+        partName: z.ZodString;
+        kind: z.ZodEnum<{
+            screenshot: "screenshot";
+            "annotated-screenshot": "annotated-screenshot";
+            video: "video";
+            audio: "audio";
+            "session-replay": "session-replay";
+            other: "other";
+        }>;
+        contentType: z.ZodString;
+        byteLength: z.ZodNumber;
+        sha256: z.ZodString;
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        format: z.ZodOptional<z.ZodEnum<{
+            rrweb: "rrweb";
+            "everframe-vtree-v1": "everframe-vtree-v1";
+            "everframe-video-v1": "everframe-video-v1";
+            "traceitx-vtree-v1": "traceitx-vtree-v1";
+            "traceitx-video-v1": "traceitx-video-v1";
+        }>>;
+        durationMs: z.ZodOptional<z.ZodNumber>;
+        replayStartEpochMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$loose>;
+type ReportEnvelope = z.infer<typeof ReportEnvelope>;
+
+interface UINode {
+    componentType: string;
+    componentName?: string | undefined;
+    identifiers: Record<string, string>;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    safeProps: Record<string, string | number | boolean>;
+    children: UINode[];
+    sensitive?: boolean | undefined;
+    nodeKind?: 'compose' | 'view' | 'dom' | undefined;
+}
+declare const UINode: z.ZodType<UINode>;
+declare const UITree: z.ZodObject<{
+    root: z.ZodType<UINode, unknown, z.core.$ZodTypeInternals<UINode, unknown>>;
+    capturedAt: z.ZodString;
+    rendererHint: z.ZodEnum<{
+        android: "android";
+        dom: "dom";
+        "rn-paper": "rn-paper";
+        "rn-fabric": "rn-fabric";
+        uikit: "uikit";
+    }>;
+    truncated: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type UITree = z.infer<typeof UITree>;
+declare const AttachmentRef: z.ZodObject<{
+    partName: z.ZodString;
+    kind: z.ZodEnum<{
+        screenshot: "screenshot";
+        "annotated-screenshot": "annotated-screenshot";
+        video: "video";
+        audio: "audio";
+        "session-replay": "session-replay";
+        other: "other";
+    }>;
+    contentType: z.ZodString;
+    byteLength: z.ZodNumber;
+    sha256: z.ZodString;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    format: z.ZodOptional<z.ZodEnum<{
+        rrweb: "rrweb";
+        "everframe-vtree-v1": "everframe-vtree-v1";
+        "everframe-video-v1": "everframe-video-v1";
+        "traceitx-vtree-v1": "traceitx-vtree-v1";
+        "traceitx-video-v1": "traceitx-video-v1";
+    }>>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    replayStartEpochMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type AttachmentRef = z.infer<typeof AttachmentRef>;
+declare const VitalsPlayerEventType: z.ZodEnum<{
+    error: "error";
+    play: "play";
+    pause: "pause";
+    seek: "seek";
+    buffer_start: "buffer_start";
+    buffer_end: "buffer_end";
+    bitrate_change: "bitrate_change";
+    rate_change: "rate_change";
+    startup: "startup";
+    dropped_frames: "dropped_frames";
+    source_change: "source_change";
+    player_attach: "player_attach";
+    player_detach: "player_detach";
+    drm: "drm";
+    quality_change: "quality_change";
+    stats: "stats";
+}>;
+type VitalsPlayerEventType = z.infer<typeof VitalsPlayerEventType>;
+
+interface JsBundleConfig {
+    buildId: string;
+    bundleName: string;
+}
+
+/**
+ * Resolved by `useEverframe().open()` / top-level `open()`.
+ * Mirrors the native NSDictionary / WritableMap shape produced by the iOS
+ * (`EverframeBridge.openReporter`) and Android (`EverframeModule.openReporter`)
+ * bridges. The `status` field is one of:
+ *   - 'submitted' — envelope shipped successfully (reportId populated)
+ *   - 'queued'    — envelope persisted for retry (reportId populated)
+ *   - 'cancelled' — user dismissed the reporter without submitting
+ */
+type ReporterResult = {
+    status: 'submitted';
+    reportId: string;
+} | {
+    status: 'queued';
+    reportId: string;
+} | {
+    status: 'cancelled';
+    reason?: string;
+};
+/**
+ * Thrown when `open()` is called from a top-level (non-component) site
+ * before a `<EverframeProvider>` has mounted. Components reading via
+ * `useEverframe()` see a same-class error.
+ */
+declare class EverframeNotMountedError extends Error {
+    readonly name = "EverframeNotMountedError";
+    constructor(message?: string);
+}
+
+declare const ErrorSeverity: z.ZodEnum<{
+    error: "error";
+    info: "info";
+    warning: "warning";
+}>;
+type ErrorSeverity = z.infer<typeof ErrorSeverity>;
+
+/** Optional per-occurrence details captured with a handled exception. */
+interface CaptureExceptionOptions {
+    severity?: ErrorSeverity;
+    context?: string;
+    metadata?: Record<string, unknown>;
+}
+interface DeviceMetadata {
+    os: string;
+    osVersion: string;
+    model?: string;
+    screenSize: {
+        width: number;
+        height: number;
+    };
+    pixelRatio: number;
+    locale: string;
+    timezone: string;
+    network?: string;
+    /**
+     * Raw User-Agent string from `navigator.userAgent`. Surfaced to triagers so
+     * they can disambiguate things our OS/version parser doesn't capture
+     * (browser engine + version, in-app webviews, bot signatures, accessibility
+     * UA overrides). Web SDK only — native SDKs leave this undefined.
+     */
+    userAgent?: string;
+}
+interface ReportDraft {
+    title: string;
+    description: string;
+    excludedArtifacts: string[];
+    annotations: unknown[];
+    redactions: unknown[];
+    /** Host-supplied free-form metadata (from `setExtra`). Opaque string, ≤2000 chars. */
+    extra?: string;
+}
+/**
+ * A host-supplied function that produces the next report's `extra` payload
+ * on demand. Registered via `setExtra(resolve)`; invoked once per report
+ * assembly (see `resolveClientExtra`), never at registration time.
+ */
+type ExtraResolver = () => string | Record<string, unknown>;
+
+/** Protocol ceiling — `packages/protocol/src/envelope.ts`. */
+declare const EXTRA_MAX_CHARS = 16384;
+
+/** Shape exposed via `useEverframe()` and the top-level `open` re-export. */
+interface EverframeContextValue {
+    /** Capture a handled exception without opening the reporter. No-op outside the owning mount. */
+    captureException(error: unknown, options?: CaptureExceptionOptions): void;
+    /**
+     * Open the native reporter modal. Resolves with the user-facing outcome
+     * (`submitted` / `queued` / `cancelled`). Replaces the pre-0.3 nested
+     * `report.open()` — the `.report` namespace held only `.open` so flattening
+     * matches sdk-react.
+     */
+    open(): Promise<ReporterResult>;
+    sensitive: {
+        register(tag: number, rect: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        }): void;
+        unregister(tag: number): void;
+    };
+    /**
+     * Attach host-supplied free-form metadata to the next report. Each call
+     * REPLACES the previous value. Auto-cleared after the next `open()`
+     * resolves.
+     *
+     * Prefer the OBJECT form so the SDK serializes it for you before crossing
+     * the bridge. Either form is capped at `EXTRA_MAX_CHARS` (16 KiB): an
+     * over-budget object is omitted (a warning is logged), because slicing
+     * serialized JSON yields a fragment nothing can parse; an over-budget
+     * string is still forwarded to the native side as-is, which applies its
+     * own 16 KiB ceiling as a raw character cut, not JSON-aware. Pass an empty
+     * string to detach.
+     */
+    setExtra(value: string): void;
+    setExtra(value: Record<string, unknown>): void;
+    /**
+     * Resolver form (spec 2026-09-17 setExtra-resolver) — matches
+     * `@everframe/sdk-core`'s `setExtra(resolve: ExtraResolver)` signature
+     * exactly. PREFER THIS over the string/object forms above: triggers the
+     * SDK owns (native shake on mobile) open the reporter DIRECTLY, with no
+     * chance for the host to refresh a pushed snapshot first — see the fuller
+     * rationale on `@everframe/sdk-core`'s `EverframeClient.setExtra`. The
+     * resolver is stored, never called at registration time; native ASKS for
+     * it (a bounded round trip to JS, mirroring the companion
+     * `reportRequested` handshake) right before it drains pending attachments
+     * for a report, so it always sees current values with no effect to write
+     * or keep in sync. A throwing resolver never breaks the report: it is
+     * caught, warned, and `extra` is simply omitted from that report — same
+     * budgeting as the object form (`budgetExtra`), applied to the resolver's
+     * return value at resolve time instead of at registration time.
+     */
+    setExtra(resolve: ExtraResolver): void;
+    /**
+     * Manual escape hatch (Plan 4 / Task 14): drop a host-supplied marker into
+     * the native breadcrumb chain — object-form, matching the web SDK
+     * signature. RN apps already inherit ALL native auto-capture underneath RN
+     * (lifecycle/error/console/network-opt-in/tap/nav); JS-side auto-capture
+     * (fetch/react-navigation/touch patches) is an explicit non-goal of this
+     * plan. `addBreadcrumb` and `recordScreen` (spec 2026-07-14) are the only
+     * JS-initiated crumb paths.
+     *
+     * NO validation/coercion happens here or on the bridge — the call is
+     * forwarded positionally to the native TurboModule spec method, which
+     * forwards straight to the platform singleton (`Everframe.shared
+     * .addBreadcrumb` on iOS / `Everframe.addBreadcrumb` on Android). That
+     * singleton owns ALL coercion (unknown `kind` → `custom`, invalid `level`
+     * dropped rather than defaulted, `data` JSON-coerced) and gating (no-op
+     * pre-start / while killed).
+     */
+    addBreadcrumb(input: {
+        message: string;
+        kind?: string;
+        level?: string;
+        data?: object;
+    }): void;
+    /**
+     * Navigation screen marker (spec 2026-07-14): record "this screen is now
+     * visible". The native side derives the `from → to` transition (global
+     * chain shared with native auto-capture), gates, and coerces — nothing
+     * happens JS-side. Prefer the `useEverframeScreen` hook / `<EverframeScreen>` component;
+     * this raw form suits onStateChange-style whole-app wiring.
+     */
+    recordScreen(name: string, data?: Record<string, unknown>): void;
+    /**
+     * Set or clear the active user for self-declared recognition. Call with no
+     * argument to clear. Unverified: a label, never a credential.
+     */
+    setUser(user?: EverframeUserSpec): void;
+}
+/**
+ * Top-level imperative `open` re-export. Inside the React tree, prefer
+ * `useEverframe().open()`. This re-export exists for non-component call
+ * sites (global error handlers, deep-link handlers, native event bridges).
+ */
+declare function open(): Promise<ReporterResult>;
+/** Top-level `setExtra` for non-component call sites. No-op if no provider mounted. */
+declare function setExtra(value: string): void;
+declare function setExtra(value: Record<string, unknown>): void;
+declare function setExtra(resolve: ExtraResolver): void;
+/**
+ * Top-level `addBreadcrumb` for non-component call sites (global error
+ * handlers, deep-link handlers, native event bridges). No-op if no provider
+ * mounted — matches `setExtra` above. See
+ * `EverframeContextValue.addBreadcrumb` for the full contract.
+ */
+declare function addBreadcrumb(input: {
+    message: string;
+    kind?: string;
+    level?: string;
+    data?: object;
+}): void;
+/**
+ * Top-level `recordScreen` for non-component call sites (e.g. a
+ * react-navigation `onStateChange` handler). No-op if no provider mounted —
+ * matches `setExtra`/`addBreadcrumb` above.
+ */
+declare function recordScreen(name: string, data?: Record<string, unknown>): void;
+/** Top-level `setUser` for non-component call sites. No-op if no provider mounted. */
+declare function setUser(user?: EverframeUserSpec): void;
+/** Capture a handled exception from any call site. No-op without a mounted provider. */
+declare function captureException(error: unknown, options?: CaptureExceptionOptions): void;
+
+/**
+ * Runtime configuration — the host-facing `EverframeProvider config` shape.
+ *
+ * Extends the bridge ConfigOpts but OMITS `sdkVersion`: the SDK version is not
+ * host-defined, it's owned by the SDK and stamped per release on the native
+ * side (`Everframe.SDK_VERSION`). See extractBridgeConfig.
+ *
+ * External review, finding NN4 — also OMITS `companionBadgeEnabled` /
+ * `companionBadgePosition`, the FLAT wire-shaped fields `ConfigOpts` declares
+ * for codegen (RN codegen cannot express the nested `{ enabled, position }`
+ * object at all — see `companionBadge` below). Without this, `RuntimeConfig`
+ * structurally inherited BOTH the flat wire fields AND the nested
+ * `companionBadge` declared below, so `{ companionBadgeEnabled: false }`
+ * type-checked as a valid host config and silently no-opped: `extractBridge
+ * Config` only ever reads the nested `companionBadge` object, never the flat
+ * keys, so a host reaching for the (also-valid-looking) flat shape got no
+ * error and no effect. Omitting them here makes `companionBadge` the ONLY
+ * public surface for this option — passing the flat form is now a
+ * compile-time error, matching the runtime's actual (nested-only) behavior.
+ * Deliberately NOT applied to `networkBodiesDisabled`, even though the same
+ * shape of gap arguably exists there too (`RuntimeConfig` also declares its
+ * own nested `networkBodies?: { disabled? }` below, alongside the inherited
+ * flat `networkBodiesDisabled?`): out of scope for this fix by explicit
+ * review instruction, left as pre-existing behavior rather than folded in
+ * here.
+ */
+interface RuntimeConfig extends Omit<ConfigOpts, "sdkVersion" | "installIdentifierDisabled" | "companionBadgeEnabled" | "companionBadgePosition" | "shakeToReportEnabled" | "themeBackground" | "themeSurface" | "themeBorder" | "themeText" | "themeTextMuted" | "themeAccent" | "themeAccentForeground" | "themeDestructive" | "vitalsEnabled" | "vitalsSampleRate" | "vitalsCaptureSourceQuery"> {
+    /**
+     * Per-app SDK key (publishable, not secret). Required on the host-facing
+     * config — narrows the bridge `ConfigOpts.apiKey?` to required so a missing
+     * key is a compile-time error, matching the React SDK. The bridge type stays
+     * optional (extractBridgeConfig builds `{}`); only this host surface requires it.
+     */
+    apiKey: string;
+    appName?: string;
+    appVersion?: string;
+    appBuild?: string;
+    /** Exact loaded Hermes bundle identity, independent of the native app build. */
+    jsBundle?: JsBundleConfig;
+    /**
+     * Opt-in JS-side capture integrations (spec 2026-07-14 RN-iOS parity).
+     * Import from '@everframe/react-native/integrations/*'; nothing
+     * auto-installs. Setups run after configure-on-mount, teardowns on unmount.
+     */
+    integrations?: EverframeIntegration[];
+    /**
+     * Crash/error reporting (spec 2026-07-18). Installs a default-on global
+     * ErrorUtils handler on mount — deliberately NOT gated behind
+     * `integrations` (deviation from the RN integrations doctrine, recorded in
+     * the spec): crash capture is a safety net, not an opt-in enrichment. Set
+     * `disabled: true` to veto it entirely.
+     */
+    crashReporting?: {
+        disabled?: boolean;
+    };
+    /**
+     * Network request/response body capture (spec 2026-08-12). CLIENT VETO
+     * only: `disabled: true` turns bodies off locally; it can never force them
+     * on — the server's per-app `captureBodies` gate is authoritative.
+     *
+     * NOTE: RN does not currently attach Everframe network capture to its own
+     * HTTP clients, so this option is correct but inert until that lands.
+     */
+    networkBodies?: {
+        disabled?: boolean;
+    };
+    /**
+     * Install identifier (MAI meter spec 2026-08-27). ON by default: the SDK
+     * sends a value derived from a locally-minted, non-secret per-install seed
+     * at most once a day, so distinct installs can be counted toward your
+     * plan. Nothing about the person using the app is derived or stored, and
+     * the seed never leaves the device.
+     *
+     * CLIENT VETO only: `disabled: true` stops this app sending one from that
+     * point on; it can never force it on. Nested host-facing shape flattened
+     * onto `ConfigOpts.installIdentifierDisabled` by `extractBridgeConfig` —
+     * same idiom, and the same codegen reason, as `networkBodies` above.
+     *
+     * NOT retroactive and NOT org-wide: installs already recorded earlier this
+     * calendar month stay counted, and the number shown is per ORGANIZATION.
+     */
+    installIdentifier?: {
+        disabled?: boolean;
+    };
+    /**
+     * Built-in attach-PIN surface mode (spec 2026-08-19). Narrows the bridge
+     * `ConfigOpts.attachPinUi?: string` to a literal union here — the flat
+     * `string` on `ConfigOpts` is a codegen constraint on the WIRE type only
+     * (RN codegen can't express a string-literal union in a struct field, see
+     * `NativeEverframe.ts`'s D-decision header note); this host-facing surface
+     * doesn't cross codegen and gets normal DX. `extractBridgeConfig` passes
+     * it through unchanged — the union is a subtype of `string`, so no
+     * conversion is needed, same as `captureScreenshot` above.
+     */
+    attachPinUi?: "builtin" | "custom" | "off";
+    /**
+     * Companion on-screen name-badge visibility/position (naming spec
+     * 2026-08-24, controller ruling / Task 6b) — lets a host that finds the
+     * badge intrusive turn it off in one line: `companionBadge: { enabled:
+     * false }`. Nested host-facing shape, unlike `attachPinUi` above: RN
+     * codegen cannot express a nested object in a struct field at all (not
+     * even a flat one with a narrowed literal-union member), so
+     * `extractBridgeConfig` flattens both fields onto the wire `ConfigOpts`
+     * (`companionBadgeEnabled`/`companionBadgePosition`) — the same
+     * flattening idiom `networkBodies.disabled` → `networkBodiesDisabled`
+     * above already uses for the same reason.
+     */
+    companionBadge?: {
+        enabled?: boolean;
+        position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
+    };
+    /**
+     * Native mobile shake gesture. Enabled by default; the dashboard remains
+     * authoritative. React Native/Expo development builds should normally use
+     * `{ enabled: !__DEV__ }` to avoid overlapping with the development menu.
+     */
+    shakeToReport?: {
+        enabled?: boolean;
+    };
+    /**
+     * Inline reporter theme (reporter branding spec 2026-08-25, RN slice) —
+     * 8 optional `#rrggbb` role strings for the NATIVE report dialogs the RN
+     * SDK presents (`open()`); RN itself renders no reporter UI. Nested
+     * host-facing shape, flattened onto the 8 flat `ConfigOpts.theme*` wire
+     * fields by `extractBridgeConfig` — the same idiom (and codegen reason) as
+     * `companionBadge` above.
+     *
+     * Rendering is entitlement-gated NATIVELY per the branding contract
+     * (precedence server → inline → default): the theme applies only when the
+     * server says `watermark: false` (paid plan); a free plan ignores it and
+     * keeps the watermark — fail closed, never bypassable from RN. Invalid hex
+     * values are ignored per-field by each native ThemeResolver; the RN side
+     * is pure passthrough by design.
+     */
+    theme?: {
+        background?: string;
+        surface?: string;
+        border?: string;
+        text?: string;
+        textMuted?: string;
+        accent?: string;
+        accentForeground?: string;
+        destructive?: string;
+    };
+    /**
+     * Session Vitals local config (spec 2026-09-06). `enabled`: absent =
+     * follow the dashboard toggle, `false` = opt out locally, `true` never
+     * forces it on. `sampleRate`: [0, 1], min()'d with the server rate.
+     * `captureSourceQuery`: keep query strings on `source_change.src`
+     * (default false — signed CDN URLs carry tokens). Flattened onto three
+     * flat `ConfigOpts.vitals*` wire fields by `extractBridgeConfig`.
+     */
+    vitals?: {
+        enabled?: boolean;
+        sampleRate?: number;
+        captureSourceQuery?: boolean;
+    };
+}
+
+interface EverframeProviderProps {
+    config: RuntimeConfig;
+    children: React.ReactNode;
+}
+declare function EverframeProvider(props: EverframeProviderProps): React.ReactElement;
+/**
+ * Read the active runtime from React context. Throws if no provider is
+ * mounted above the call site.
+ */
+declare function useEverframe(): EverframeContextValue;
+
+type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * Wrap any subtree to mark its bounding box as sensitive. The native screenshot
+ * pipeline blurs / blackboxes the rect before the image leaves the device
+ * (PRIV-02 / PRIV-03).
+ */
+declare function EverframeSensitive(props: ViewProps): React.ReactElement;
+/**
+ * Imperatively mark an already-instantiated host (e.g., a third-party
+ * <TextInput> wrapper). Pass a ref and a rect; the hook registers on each
+ * rect change (RESEARCH §5.3). This effect runs after mounting and cannot protect
+ * first paint. Use EverframeSensitive for mount-time Android video privacy.
+ */
+declare function useEverframeSensitiveRef<T>(ref: React.RefObject<T | null>, rect: Rect | null): void;
+
+/**
+ * Emit a navigation marker when this screen appears: on mount, on [name]
+ * change, and whenever `opts.focused` flips to true.
+ *
+ * `focused` defaults to true (mount = appearance — correct when your
+ * navigator unmounts hidden screens). Pass it for navigators that keep
+ * screens mounted (react-navigation stacks/tabs: `useIsFocused()`). The
+ * native `A → A` suppression absorbs StrictMode double-mounts and refocus
+ * re-emits. [name] should be a route identifier, never user content (PII).
+ */
+declare function useEverframeScreen(name: string, opts?: {
+    focused?: boolean;
+}): void;
+interface EverframeScreenProps {
+    name: string;
+    focused?: boolean;
+}
+/**
+ * Declarative form of [useEverframeScreen] for class components / JSX-only
+ * placement. Renders nothing.
+ */
+declare function EverframeScreen(props: EverframeScreenProps): null;
+
+interface PlayerStats {
+    bufferAheadMs: number;
+    bandwidthEstimate?: number;
+    bitrate?: number;
+    width?: number;
+    height?: number;
+    /** CUMULATIVE; native derives the per-tick delta. */
+    droppedFrames?: number;
+}
+interface TrackPlayerOptions {
+    /** ≤ 32 chars, free string ('react-native-video', 'theoplayer', …). */
+    library: string;
+    libraryVersion?: string;
+    name?: string;
+}
+/**
+ * The event types a HOST may emit. `player_attach` / `player_detach` are
+ * reserved for the native registry's own lifecycle markers — native drops
+ * them if they arrive from JS, so the type excludes them up front.
+ */
+type HostPlayerEventType = Exclude<VitalsPlayerEventType, 'player_attach' | 'player_detach'>;
+interface PlayerHandle {
+    readonly token: string;
+    readonly detached: boolean;
+    emit(type: HostPlayerEventType, data?: Record<string, unknown>, t?: number): void;
+    updateStats(stats: PlayerStats): void;
+    track(name: string, data?: unknown): void;
+    detach(): void;
+}
+declare function trackPlayer(opts: TrackPlayerOptions): PlayerHandle;
+declare function trackVitals(name: string, data?: unknown, player?: PlayerHandle): void;
+/**
+ * Bind a player registration to a component's lifetime: track on mount,
+ * detach on unmount, fresh token when an option changes. The returned
+ * handle is STABLE (same identity every render) and forwards to the live
+ * inner handle — inert before mount and after unmount — so Fast Refresh and
+ * StrictMode's effect double-run cannot leak a registration.
+ */
+declare function useTrackPlayer(opts: TrackPlayerOptions): PlayerHandle;
+
+/**
+ * SDK-facing listener surface. React Native 0.87 intentionally types raw
+ * native payloads as `Object[]`; each Everframe event has a narrower bridge
+ * contract, so the unchecked native boundary is centralized here instead of
+ * repeated at every listener.
+ */
+type EverframeNativeEventEmitter = {
+    addListener<Args extends readonly unknown[]>(eventType: string, listener: (...args: Args) => unknown): EventSubscription;
+};
+/**
+ * Resolve the platform's RN event emitter source. iOS hands listeners to a
+ * dedicated `RCTEventEmitter` subclass (`EverframeEventEmitter`); Android
+ * uses the default `RCTDeviceEventEmitter` which `NativeEventEmitter`
+ * routes to when constructed with no argument.
+ */
+declare function getEmitter(): EverframeNativeEventEmitter;
+
+/**
+ * Companion runtime state — mirrors `CompanionState` in iOS (rawValue) +
+ * Android (mapped from the enum via `toRnString`). Keep this union in
+ * lock-step with both native sides.
+ */
+type CompanionState = 'unpaired' | 'paired' | 'report_in_progress' | 'phone_disconnected';
+/**
+ * A pending dashboard-initiated attach-PIN challenge (spec 2026-08-19).
+ * Mirrors iOS `CompanionAttachChallenge` / Android `AttachChallengeInfo`.
+ * The natives forward this event in every `attachPinUi` mode, including
+ * `'builtin'` (which renders the PIN natively AND still fires the event) —
+ * it's only NEEDED by hosts configured with `'custom'`, which must read it
+ * to build their own surface.
+ */
+interface CompanionAttachChallenge {
+    code: string;
+    requestedByName: string;
+    /** Display lifetime — custom UIs should hide the code after this. */
+    ttlMs: number;
+}
+/**
+ * Open the relay WS connection. The native bridge owns at most one client
+ * per process and `start()` is idempotent: calling it again while the
+ * companion is already running is a no-op — the socket is NOT recreated.
+ * Call `stop()` first, then `start()`, to tear the connection down and open
+ * a fresh one.
+ *
+ * The ingest URL is no longer a JS-side argument — the native SDKs bake it
+ * at compile time (Release: https://everframe.dev; Debug: optionally
+ * overridden via EVERFRAME_DEV_INGEST_URL on each native build).
+ */
+declare function start(): void;
+/**
+ * Close the relay WS. The observable state retains its last value — hosts
+ * can still read `useCompanion().state` afterwards to render a "paused"
+ * indicator. Re-call `start(...)` to reconnect.
+ */
+declare function stop(): void;
+/**
+ * Subscribe to the "is a session wanted" intent flag (see `_running` above).
+ * Returns an unsubscribe function. Use this directly from imperative code;
+ * React components should prefer `useCompanion().running`.
+ */
+declare function onRunning(handler: (running: boolean) => void): () => void;
+/**
+ * Subscribe to companion-state changes. Returns an unsubscribe function.
+ * Use this directly from imperative code (e.g. an Activity-lifecycle hook);
+ * React components should prefer `useCompanion()`.
+ */
+declare function onState(handler: (state: CompanionState) => void): () => void;
+/**
+ * Subscribe to pairUrl changes. The URL is set on `pair.created` and retained
+ * for the life of the relay socket — it's nulled only when the socket closes
+ * (terminal/permanent close). It does NOT flip to null on bond or expiry; drive
+ * QR teardown off `state` (e.g. hide once `state === 'paired'`) instead, since
+ * `state` is the reliably-delivered signal across the native bridge.
+ */
+declare function onPairUrl(handler: (url: string | null) => void): () => void;
+/**
+ * Subscribe to the announce display code — the short string the dashboard
+ * shows next to this device in the project's Companion list, so a team member
+ * can match what they read on the TV screen to a row in the list.
+ *
+ * `null` when companion discovery was never attempted (no SDK key configured
+ * on the native side), when the announce call failed, and after the relay
+ * socket closes terminally. A null code costs discovery only — pairing by QR
+ * and report submission are unaffected, so never gate the QR on it.
+ */
+declare function onCode(handler: (code: string | null) => void): () => void;
+/**
+ * Subscribe to the attached dashboard member's display name. Populated only
+ * when someone attached to this device FROM the dashboard; an ordinary QR
+ * bond carries no such name and leaves this `null`. Render it as e.g.
+ * "Paired with <name>" — but drive the paired/unpaired chrome itself off
+ * `state`, which is the reliably-delivered signal.
+ */
+declare function onAttachedUserName(handler: (name: string | null) => void): () => void;
+/**
+ * Subscribe to the server-resolved device display name (naming spec
+ * 2026-08-24) — e.g. an org-configured friendly name for this device.
+ * `null` before the first successful announce, and when discovery never ran
+ * (no SDK key configured on the native side).
+ *
+ * REPLAY SEMANTIC (external review, finding N5): RN events don't replay to
+ * listeners attached after they fired, so a name resolved by an announce
+ * that ran before this call would otherwise be invisible to it until the
+ * NEXT announce. If `start()` has already cached a resolved name, `handler`
+ * is invoked synchronously, immediately, with that cached value — before
+ * this function returns, in addition to firing on every later event. Mirrors
+ * `onAttachChallenge`'s replay idiom exactly, minus the ttlMs
+ * recomputation (a resolved name has no lifetime to recompute).
+ */
+declare function onResolvedName(handler: (name: string | null) => void): () => void;
+/**
+ * Subscribe to attach-PIN challenges (spec 2026-08-19). Fires with the live
+ * challenge when a dashboard member requests attach, and null when it
+ * clears (redeemed, expired, burned, superseded, socket closed). The
+ * natives fire this event in every `attachPinUi` mode, including
+ * `'builtin'` (which renders the PIN natively AND still fires the event) —
+ * it's only NEEDED for `'custom'` hosts, which must read it to build their
+ * own surface.
+ *
+ * REPLAY SEMANTIC: RN events don't replay to listeners attached after they
+ * fired, so a challenge that arrived before this call would otherwise be
+ * invisible to it. If `start()` has already cached a still-live challenge,
+ * `handler` is invoked synchronously, immediately, with that cached value —
+ * `ttlMs` recomputed as the time REMAINING until its deadline, never the
+ * original duration (review finding 4) — before this function returns, in
+ * addition to firing on every later event. A cached challenge whose deadline
+ * has already passed replays nothing (`attachChallengeReplayValue()` returns
+ * null), matching the semantics of a challenge that was never cached at all.
+ */
+declare function onAttachChallenge(handler: (challenge: CompanionAttachChallenge | null) => void): () => void;
+/**
+ * React hook returning the latest `{ state, pairUrl, code, attachedUserName, attachChallenge }`
+ * snapshot. Mounts one NativeEventEmitter subscription per value and tears
+ * them all down on unmount.
+ *
+ * Subscribing is safe to tie to a component; the SESSION is not. Binding
+ * `stop()` to unmount means the device stops advertising the moment the
+ * screen goes away — including when the user navigates off to the dashboard
+ * to attach to it — so prefer starting on mount and ending on an explicit
+ * user action. `examples/react-native/src/screens/Companion.tsx` shows that
+ * shape, with a module-scoped flag carrying the user's intent across mounts.
+ *
+ * Note that `stop()` retains the last `state` and `pairUrl` rather than
+ * clearing them, so a stopped session must be rendered from your own flag —
+ * rendering off `state` alone leaves a dead QR on screen.
+ */
+declare function useCompanion(): {
+    state: CompanionState;
+    pairUrl: string | null;
+    code: string | null;
+    attachedUserName: string | null;
+    resolvedName: string | null;
+    attachChallenge: CompanionAttachChallenge | null;
+    running: boolean;
+};
+
+type companion_CompanionAttachChallenge = CompanionAttachChallenge;
+type companion_CompanionState = CompanionState;
+declare const companion_getEmitter: typeof getEmitter;
+declare const companion_onAttachChallenge: typeof onAttachChallenge;
+declare const companion_onAttachedUserName: typeof onAttachedUserName;
+declare const companion_onCode: typeof onCode;
+declare const companion_onPairUrl: typeof onPairUrl;
+declare const companion_onResolvedName: typeof onResolvedName;
+declare const companion_onRunning: typeof onRunning;
+declare const companion_onState: typeof onState;
+declare const companion_start: typeof start;
+declare const companion_stop: typeof stop;
+declare const companion_useCompanion: typeof useCompanion;
+declare namespace companion {
+  export { type companion_CompanionAttachChallenge as CompanionAttachChallenge, type companion_CompanionState as CompanionState, companion_getEmitter as getEmitter, companion_onAttachChallenge as onAttachChallenge, companion_onAttachedUserName as onAttachedUserName, companion_onCode as onCode, companion_onPairUrl as onPairUrl, companion_onResolvedName as onResolvedName, companion_onRunning as onRunning, companion_onState as onState, companion_start as start, companion_stop as stop, companion_useCompanion as useCompanion };
+}
+
+export { AttachmentRef, type CaptureExceptionOptions, type CompanionState, ConfigOpts, type DeviceMetadata, EXTRA_MAX_CHARS, type EverframeContextValue, EverframeIntegration, EverframeNotMountedError, EverframeProvider, type EverframeProviderProps, EverframeScreen, type EverframeScreenProps, EverframeSensitive, EverframeUserSpec, type HostPlayerEventType, type PlayerHandle, type PlayerStats, type ReportDraft, ReportEnvelope, type ReporterResult, type TrackPlayerOptions, UINode, UITree, VitalsPlayerEventType, addBreadcrumb, captureException, companion, open, recordScreen, setExtra, setUser, trackPlayer, trackVitals, useCompanion, useEverframe, useEverframeScreen, useEverframeSensitiveRef, useTrackPlayer };