@scalebun/react-native 1.10.6 → 1.11.0

package/lib/typescript/analytics/EventTracker.d.ts

@@ -125,7 +125,7 @@ export declare class EventTracker {
      * Persisted so it survives the click→install→open gap. Call BEFORE start() ideally.
      */
     setAttributionClickId(clickId: string): void;
-    track(eventName: string, properties?: Record<string, any>): void;
+    track(eventName: string, properties?: Record<string, any>, timestamp?: number): void;
     trackPurchase(input: {
         revenue: number;
         currency: string;

package/lib/typescript/analytics/automaticEvents.d.ts

@@ -18,9 +18,11 @@ export type AutomaticEventName = 'app_foregrounded' | 'app_backgrounded' | 'scre
 export interface AutomaticEvent {
     name: AutomaticEventName;
     properties: Record<string, unknown>;
+    /** Original observation time. Delivery can be delayed while native coordinates resolve. */
+    timestamp?: number;
 }
 type AutomaticEventListener = (event: AutomaticEvent) => void;
-export declare function emitAutomaticEvent(name: AutomaticEventName, properties?: Record<string, unknown>): void;
+export declare function emitAutomaticEvent(name: AutomaticEventName, properties?: Record<string, unknown>, timestamp?: number): void;
 export declare function subscribeAutomaticEvents(listener: AutomaticEventListener): () => void;
 /** Test-only reset; intentionally not exported from the package entry point. */
 export declare function resetAutomaticEventsForTests(): void;

package/lib/typescript/core/config/schema.d.ts

@@ -93,6 +93,8 @@ export interface ScaleBunConfig {
         checkOnForeground: boolean;
         channelOverride?: string;
         publicSigningKey?: string;
+        /** Additional pinned keys for rotation; unioned with publicSigningKey. */
+        publicSigningKeys?: string[];
         mandatoryBlocksUi: boolean;
     };
 }

package/lib/typescript/core/constants/version.d.ts

@@ -1,7 +1,12 @@
 /**
  * ScaleBun SDK version. Sent with the session-start envelope so the dashboard
  * can attribute telemetry to the SDK build that produced it.
- * Keep in sync with package.json "version".
+ * Keep in sync with package.json "version" — `version.test.ts` fails when they drift.
+ *
+ * Why the test matters: the 1.11.0 bump missed this line, so the build would have reported itself as
+ * 1.10.6. Every "is the release live, and on what share of traffic" question is answered from this
+ * value, so a stale one makes a rollout unobservable — which is the exact problem sending an SDK
+ * version was introduced to solve.
  */
-export declare const SDK_VERSION = "1.10.6";
+export declare const SDK_VERSION = "1.11.0";
 //# sourceMappingURL=version.d.ts.map

package/lib/typescript/features/journey/interactionProtocol.d.ts

@@ -0,0 +1,21 @@
+/** One physical interaction, shared by replay and analytics projections. */
+export declare const INTERACTION_PROTOCOL_VERSION = 1;
+export type InteractionStateStatus = 'captured_empty' | 'captured_nonempty' | 'not_captured' | 'not_instrumented';
+export interface InteractionStartContext {
+    interactionId: string;
+    occurredAt: number;
+    x: number;
+    y: number;
+    target?: string;
+    targetId?: string;
+    screenName?: string;
+    ui?: string;
+    stateStatus: InteractionStateStatus;
+    emitAutomaticAnalytics: boolean;
+}
+export declare function generateInteractionId(): string;
+/** Match a native bridge event to the JS evidence sampled at the same finger-down. */
+export declare function nearestInteractionStart<T extends InteractionStartContext>(starts: readonly T[], occurredAt: number, toleranceMs?: number): T | undefined;
+/** Analytics is a projection of the same evidence; no second click is invented. */
+export declare function automaticInteractionProperties(payload: Record<string, unknown>, screenName: string | undefined, canonicalMirror: boolean): Record<string, unknown>;
+//# sourceMappingURL=interactionProtocol.d.ts.map

package/lib/typescript/features/journey/uiState.d.ts

@@ -0,0 +1,53 @@
+/**
+ * UI STATE AT INTERACTION TIME — React Native.
+ *
+ * A screen is not just `Cart`. It is `Cart` with the filter sheet down, or up; with the address form
+ * expanded, or collapsed. Those are different interaction surfaces and a tap on one must never be
+ * counted on another — heat from the open sheet painted over the closed layout is a picture of
+ * something that never existed.
+ *
+ * HOW THIS DIFFERS FROM THE WEB, and the difference is not an omission:
+ *
+ *   The web SDK ALSO detects state automatically, by reading `aria-expanded` and open `<dialog>`
+ *   elements out of the live DOM. Those are platform-defined, so reading them is a measurement.
+ *
+ *   React Native has no equivalent. There is no queryable tree of accessibility state that says a
+ *   bottom sheet is up; a sheet is a component with a boolean in someone's store, and the only place
+ *   that boolean exists is the host's own code. Guessing at it — from a modal's presence in the tree, or
+ *   from a component name — would produce a state key that is right on some apps and silently wrong on
+ *   others, and a wrong state key partitions taps into buckets corresponding to nothing.
+ *
+ * So on RN, state is DECLARED and never inferred. `ScaleBun.setUiState('filter-sheet', 'open')` is the
+ * whole mechanism, and its absence means "not captured" rather than "nothing was open". That
+ * distinction is carried all the way to the dashboard: a tap with no declared state is NULL, not '',
+ * and cannot be selected as a state or counted as one. Reporting it as "nothing was open" would be
+ * asserting a measurement nobody took.
+ *
+ * PAIRED WITH: whatzbug-web-sdk/packages/web/src/features/journey/uiState.ts — same wire format
+ * (`name:value` pairs, sorted, `;`-joined, <= 96 chars), same separator stripping, same explicit-wins
+ * precedence, so one dashboard control queries both platforms.
+ */
+/**
+ * Declare the state of one UI dimension.
+ *
+ * Call it when the state CHANGES, not on every render: the value is read at interaction time, so it
+ * only has to be correct by the time the next tap lands.
+ */
+export declare function setUiState(name: string, value: string): void;
+/**
+ * Stop reporting a dimension — or, with no name, all of them.
+ *
+ * Later taps carry no value for it, which is not the same as carrying a value. Clearing all is what a
+ * screen unmount wants: declarations from the previous screen would otherwise follow the user onto a
+ * surface where they mean nothing, and every tap there would be filed under a state that was not on
+ * screen.
+ */
+export declare function clearUiState(name?: string): void;
+/**
+ * The signature for the interaction happening RIGHT NOW, or undefined when nothing is declared.
+ *
+ * undefined rather than '' deliberately — see the header. '' is the web's "we looked and nothing was
+ * open"; on RN there is nothing to look at, so the honest answer is silence.
+ */
+export declare function uiStateSignature(): string | undefined;
+//# sourceMappingURL=uiState.d.ts.map

package/lib/typescript/features/ota/OtaTypes.d.ts

@@ -5,6 +5,49 @@
  * Golden JSON fixtures in packages/protocol/fixtures/ota/ are the SINGLE source
  * of truth; conformance tests in both repos assert against them to prevent drift.
  */
+/**
+ * ═══════════════════════════════════════════════════════════════════════════
+ * OTA-TELEMETRY-SPEC — remaining telemetry fixes (from the 2026-08 audit)
+ * ═══════════════════════════════════════════════════════════════════════════
+ * These close the SDK half of spec §84-86. All are ADDITIVE + backward-compatible
+ * (new optional fields, new enum members, new no-throw emit calls); old installed
+ * clients omit them and the backend ingests nullable/unknown fields. Each ALTERS
+ * DEVICE RUNTIME BEHAVIOR, so land them behind a real RN build + device/kill-test
+ * (Metro cannot exercise the boot-guard) — this file only carries the contract
+ * types + this spec, not the runtime wiring.
+ *
+ * 1. releaseId end-to-end  (CRITICAL — root of the dashboard funnel mismatch)
+ *    Backend already serves it: OtaBundlePayload.releaseId (done, this file +
+ *    ota-check.service.ts). SDK TODO:
+ *      - store payload.releaseId on the downloaded/installed bundle state, and
+ *      - set `releaseId: bundle.releaseId` in the delivery mapper
+ *        OtaOrchestrator.ts deliverOtaEvents (~:105) — currently only bundleId.
+ *      Then ota_events carry releaseId and the funnel keys by release.
+ *
+ * 2. Emit CHECK + OFFERED  (funnel top is currently unmeasurable)
+ *    - CHECK: emit at the start of checkForUpdate (OtaOrchestrator.ts ~:480),
+ *      before the fetch. ('CHECK' type already exists — no emit site today.)
+ *    - OFFERED: add 'OFFERED' to OtaEventType, emit when checkRes.action ===
+ *      'DOWNLOAD' (~:619) before download begins.
+ *
+ * 3. Emit BOOT_SUCCESS  (honest activation signal)
+ *    Add 'BOOT_SUCCESS' to OtaEventType and emit it from the boot-guard
+ *    markHealthy path (OtaOrchestrator.ts ~:863). INSTALLED (~:794) is emitted
+ *    optimistically BEFORE the bundle boots; keep it (it means "staged+swapped")
+ *    but let the dashboard measure real activation on BOOT_SUCCESS. Optionally
+ *    add 'VERIFIED' after signature check (~:635).
+ *
+ * 4. Stamp the running OTA bundle onto session/crash telemetry
+ *    SessionMetadata.bundleId is the NATIVE app package id, not the OTA bundle.
+ *    Add optional otaBundleId?/otaBundleVersion? (distinct fields — do NOT
+ *    overload bundleId) sourced from otaOrchestrator.getCurrentBundle() at
+ *    session start (SessionManager.ts ~:451), so crashes attribute to the
+ *    running bundle/version (release-health crash impact).
+ *
+ * Do NOT repurpose errorCode (it already collapses failure-error vs rollback-
+ * reason); add a new optional field if the two must be distinguished.
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
 export interface OtaCheckRequest {
     appVersion: string;
     platform: 'android' | 'ios';
@@ -43,6 +86,13 @@ export interface OtaCheckResponse {
 export interface OtaBundlePayload {
     id: string;
     version: number;
+    /**
+     * The release this bundle is served AS (the backend now includes it — see
+     * ota.contracts.ts / ota-check.service.ts). Optional, for backward-compat with
+     * older backends. Carry it onto the emitted OtaEventItem.releaseId so telemetry
+     * is attributable by RELEASE, not just bundle. See OTA-TELEMETRY-SPEC below.
+     */
+    releaseId?: string;
     url: string;
     size: number;
     sha256: string;

package/lib/typescript/features/ota/crypto/builtinVerifier.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Built-in ed25519 verifier, assembled from OPTIONAL peer dependencies.
+ *
+ * WHAT THIS REPLACES. Pinning `ota.publicSigningKey` used to require the host
+ * app to write its own `verifySignature` — roughly a hundred lines of hex and
+ * base64 decoding wrapped around a crypto library. That put the single most
+ * security-critical operation in the product, the one deciding whether remote
+ * code is authentic before it executes, in code the SDK could neither test nor
+ * audit. Three failure modes all landed on the app author:
+ *
+ *   - A verifier that always returns `true` silently disables the feature, and
+ *     nothing can detect it.
+ *   - @noble's hash-provider property moved between major versions, so a
+ *     routine dependency bump made every update fail closed with no signal
+ *     pointing at the cause.
+ *   - Hand-written base64 decoders tend to omit base64url, so a signature
+ *     containing `-` or `_` is rejected as a forgery.
+ *
+ * All three are now the SDK's problem, which is where they belong. A host that
+ * installs `@noble/ed25519` and `@noble/hashes` gets verification by pinning a
+ * key and writing no code at all.
+ *
+ * WHY OPTIONAL AND NOT A HARD DEPENDENCY. Most apps never adopt bundle
+ * signing, and they should not carry curve arithmetic they will not run. The
+ * `verifySignature` hook remains supported and still WINS over this, for teams
+ * with their own crypto policy or a native implementation to delegate to.
+ *
+ * WHAT THIS DOES NOT FIX. Verification still happens in JS, inside the very
+ * bundle it protects. An attacker who lands one malicious bundle by other means
+ * can neuter the check for every update after it. Closing that needs native
+ * verification — CryptoKit on iOS (13.4+, already the deployment target) and
+ * `Signature.getInstance("Ed25519")` on Android API 33+, with a fallback below.
+ */
+import type { SignatureVerifier } from '../signature';
+/**
+ * Decode a detached signature that may arrive hex- or base64-encoded.
+ *
+ * Tries the unambiguous case first: 128 hex characters is exactly 64 bytes and
+ * cannot be anything else. Otherwise base64, then hex as a last resort. Only a
+ * result of exactly 64 bytes is accepted, so a string that decodes under the
+ * wrong scheme is rejected rather than fed to the curve code as garbage.
+ */
+export declare function decodeSignature(sig: string): Uint8Array | null;
+/**
+ * The built-in verifier, or null when the optional deps are not installed.
+ * Resolution is cached, including the negative result — a missing dependency
+ * does not become present at runtime, and retrying the require on every update
+ * check would be pure overhead.
+ */
+export declare function getBuiltinVerifier(): SignatureVerifier | null;
+/** Test seam — clears the cached resolution. */
+export declare function _resetBuiltinVerifier(): void;
+//# sourceMappingURL=builtinVerifier.d.ts.map

package/lib/typescript/features/ota/crypto/loadEd25519.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Isolated lazy loader for the OPTIONAL `@noble/ed25519` dep.
+ *
+ * WHY ITS OWN FILE: Metro's dependency collector emits a dependency map one
+ * entry short for a module containing TWO OR MORE different-string inline
+ * `require()` calls, so the require indices desync and `_dependencyMap[N]`
+ * reads `undefined` ("Requiring unknown module 'undefined'"). Exactly ONE
+ * inline require per module avoids the miscount. `loadSha512` is a sibling file
+ * for the same reason — see `push/adapters/loadNotifee.ts`, which hit this first.
+ *
+ * The string must still be STATICALLY resolvable at bundle time; hosts that do
+ * not install it stub it via `withScaleBun`.
+ */
+/** The subset of the @noble/ed25519 surface this SDK uses. */
+export interface NobleEd25519 {
+    verifyAsync?: (sig: Uint8Array, msg: Uint8Array, pub: Uint8Array) => Promise<boolean>;
+    verify?: (sig: Uint8Array, msg: Uint8Array, pub: Uint8Array) => boolean;
+    /** v3 shape: `ed.hashes.sha512` */
+    hashes?: {
+        sha512?: unknown;
+        sha512Async?: unknown;
+    };
+    /** v2 shape: `ed.etc.sha512Sync` */
+    etc?: {
+        sha512Sync?: unknown;
+        sha512Async?: unknown;
+    };
+}
+export declare function loadEd25519(): NobleEd25519 | null;
+//# sourceMappingURL=loadEd25519.d.ts.map

package/lib/typescript/features/ota/crypto/loadSha512.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Isolated lazy loader for the OPTIONAL `@noble/hashes` SHA-512.
+ *
+ * Separate file from `loadEd25519` because Metro miscounts a module holding two
+ * different-string inline `require()` calls — see the comment there.
+ *
+ * ed25519 is defined in terms of SHA-512, and React Native has no native
+ * SHA-512, so @noble/ed25519 cannot verify anything until a hash provider is
+ * wired into it. Which property it expects differs by major version, so the
+ * wiring lives in `builtinVerifier`, not here; this module only obtains the
+ * function.
+ */
+export type Sha512Fn = (msg: Uint8Array) => Uint8Array;
+export declare function loadSha512(): Sha512Fn | null;
+//# sourceMappingURL=loadSha512.d.ts.map

package/lib/typescript/features/ota/crypto/nativeVerifier.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Native ed25519 verifier — platform crypto wrapped as a SignatureVerifier.
+ *
+ * WHY IT EXISTS. The built-in @noble verifier runs in JS, inside the very
+ * bundle it protects: an attacker who lands one malicious bundle can neuter a
+ * JS check for every update after it. Platform crypto (CryptoKit on iOS,
+ * Android's conscrypt on API 33+) sits outside the bundle's reach — and using
+ * it also drops the runtime dependency on the optional @noble peers wherever
+ * the OS provides ed25519.
+ *
+ * WHAT IT DOES NOT FIX, stated plainly: the ORCHESTRATION still lives in JS.
+ * A hostile bundle can skip calling any verifier and drive the native staging
+ * methods directly. Moving the crypto native shrinks the attack surface (no
+ * more tampering with a bundled crypto lib to flip a verdict) but the full
+ * close needs native-ENFORCED staging with a natively-pinned key — an
+ * architectural change tracked separately, not smuggled into this one.
+ *
+ * VERDICT CONTRACT (mirrors the spec): the native side resolves
+ * 'valid' | 'invalid' | 'unavailable'. 'invalid' is a definitive NO.
+ * 'unavailable' (Android < 33, malformed input, machinery failure) means this
+ * source cannot answer — the composed verifier below then delegates to the
+ * @noble builtin, and when that is absent too it THROWS, which the policy
+ * layer converts to a rejection. Every path that cannot verify refuses.
+ */
+import type { SignatureVerifier } from '../signature';
+/**
+ * The native-first verifier, or null when the native module (or its
+ * verifyEd25519 method — an app running new JS against an old binary) is
+ * absent. Cached like the builtin: module availability does not change at
+ * runtime, and this is consulted on every update check.
+ */
+export declare function getNativeVerifier(): SignatureVerifier | null;
+/** Test seam — clears the cached resolution. */
+export declare function _resetNativeVerifier(): void;
+//# sourceMappingURL=nativeVerifier.d.ts.map

package/lib/typescript/features/ota/signature.d.ts

@@ -11,10 +11,17 @@
  * download and nothing else. On a platform whose entire purpose is remote code
  * delivery, that is the control that matters most.
  *
- * WHY IT IS SHAPED LIKE THIS. The SDK ships zero third-party runtime
- * dependencies, and React Native has no built-in ed25519. So verification is
- * delegated to a host-provided verifier when one is installed, and the SDK's job
- * is to decide — unambiguously — what happens when there is not one.
+ * WHY IT IS SHAPED LIKE THIS. React Native has no built-in ed25519, so the
+ * verification primitive has to come from somewhere. It is resolved in order:
+ * a host-supplied verifier, else the built-in one assembled from the OPTIONAL
+ * `@noble/ed25519` + `@noble/hashes` peers, else nothing — and the SDK's job is
+ * to decide, unambiguously, what happens in that last case.
+ *
+ * The built-in path exists because requiring every adopter to hand-write a
+ * verifier put the most security-critical operation in the product in code the
+ * SDK could neither test nor audit, and made a routine dependency bump able to
+ * silently stop all updates. See `crypto/builtinVerifier.ts`. Signing stays
+ * opt-in, and apps that never adopt it carry no curve arithmetic.
  *
  * THE POLICY, which is the important part:
  *
@@ -40,8 +47,16 @@ export type SignatureVerifier = (input: {
     publicKey: string;
 }) => boolean | Promise<boolean>;
 export interface SignatureConfig {
-    /** ed25519 public key shipped in the app binary. Absent = signing not adopted. */
-    publicKey?: string;
+    /**
+     * ed25519 public key(s) shipped in the app binary. Absent = signing not
+     * adopted. An ARRAY pins several keys at once and a bundle is accepted when
+     * ANY of them verifies — this is what makes key rotation possible without an
+     * app-store release: ship a build pinning [old, new], start signing with new,
+     * drop old from the next build. With a single pinnable key, losing the
+     * private key meant no OTA capability until a new binary cleared review —
+     * the exact emergency OTA exists to solve.
+     */
+    publicKey?: string | string[];
     /** Host-provided ed25519 verification function. */
     verifier?: SignatureVerifier;
 }
@@ -50,7 +65,7 @@ export type SignatureOutcome = {
     reason: 'verified' | 'not_configured';
 } | {
     ok: false;
-    reason: 'no_verifier' | 'invalid_signature' | 'missing_signature' | 'verifier_threw';
+    reason: 'no_verifier' | 'invalid_signature' | 'missing_signature' | 'verifier_threw' | 'no_keys';
 };
 /**
  * Decide whether a bundle may be staged.

package/lib/typescript/features/session/JourneyEventPipeline.d.ts

@@ -50,6 +50,7 @@ export declare class JourneyEventPipeline {
         journeyId?: string;
         /** Frame that was on screen when this happened. Resolved by the caller; see sessionTypes. */
         frameId?: string;
+        timestamp?: number;
     }): JourneyEvent | null;
     /**
      * Anchor a crash event — protect nearby events from eviction.

package/lib/typescript/features/session/SessionManager.d.ts

@@ -17,6 +17,7 @@ import type { DebugTransport } from '../../debug/transport';
 import type { SessionMetadata, SessionReplayConfig, JourneyEventType, JourneyEventSeverity, JourneyEventSource, CrashAnchor, NativeSyncMetadata, SyncDecisionCallback } from './sessionTypes';
 import { type NativeCaptureFn } from './ReplayCaptureManager';
 import type { BackendSessionAdapter } from './BackendSessionAdapter';
+import { type InteractionStateStatus } from '../journey/interactionProtocol';
 export interface SessionManagerConfig {
     sessionReplay?: Partial<SessionReplayConfig>;
     syncPolicy?: SyncDecisionCallback;
@@ -43,15 +44,6 @@ export declare class SessionManager {
      * lane even when no replay recording is active. Additive, opt-in (default off).
      */
     private _captureInteractionHeatmap;
-    /**
-     * Sampling cap for the analytics-lane heatmap emission. Now that capture is
-     * ON by default, an unbounded one-event-per-gesture stream could materially
-     * inflate ingest volume. We cap emitted interactions per analytics-session
-     * window (finalize-scoped per foreground): the first N gestures define the
-     * hotspot shape; the long tail is dropped. Resets when the window changes.
-     */
-    private _heatmapWindowSessionId;
-    private _heatmapWindowCount;
     private session;
     private active;
     private timeoutTimer;
@@ -207,6 +199,8 @@ export declare class SessionManager {
         traceId?: string;
         source?: JourneyEventSource;
         journeyId?: string;
+        /** Original observation time; interaction capture may resolve asynchronously. */
+        timestamp?: number;
     }): void;
     /**
      * Anchor a crash in the session context.
@@ -223,7 +217,10 @@ export declare class SessionManager {
      * Notify of a user interaction. Called by ScaleBunDebugRoot touch handlers.
      * Also triggers frame capture for desktop-initiated recordings.
      */
-    onUserAction(subtype: string, payload?: Record<string, unknown>): void;
+    onUserAction(subtype: string, payload?: Record<string, unknown>, context?: {
+        screen?: string;
+        timestamp?: number;
+    }): void;
     /**
      * Detailed gesture detection — called by ScaleBunDebugRoot touch handlers.
      * Emits a USER_ACTION event with gesture-specific subtype and payload.
@@ -263,6 +260,14 @@ export declare class SessionManager {
         screenWidth?: number;
         screenHeight?: number;
         platform?: string;
+        interactionId?: string;
+        interactionProtocol?: number;
+        occurredAt?: number;
+        ui?: string;
+        stateStatus?: InteractionStateStatus;
+        targetId?: string;
+        screenName?: string;
+        emitAutomaticAnalytics?: boolean;
     }): void;
     /**
      * Manual frame capture — triggered by Desktop "Capture Step" button.

package/lib/typescript/public/ScaleBunFacade.d.ts

@@ -69,12 +69,17 @@ declare class ScaleBunFacade {
     /**
      * Boot the OTA orchestrator when the init config asks for it.
      *
-     * `publicSigningKey` is honoured here so signature enforcement is reachable
-     * from configuration alone. The SDK ships no ed25519 implementation, so a
-     * host that pins a key must also supply `ota.verifySignature`; pinning a key
-     * without a verifier is fail-CLOSED by design (signature.ts) — an update
-     * that cannot be verified is not installed. We say that out loud rather than
-     * letting the app discover it as a silent no-update condition.
+     * `publicSigningKey` / `publicSigningKeys` are honoured here so signature
+     * enforcement is reachable from configuration alone. The list form exists
+     * for key ROTATION: a build pinning [old, new] keeps verifying while the
+     * server moves to the new key, so replacing a key never needs an emergency
+     * store release. Both fields merge (deduplicated) into one pinned set.
+     *
+     * Verification comes from `ota.verifySignature` when supplied, else the
+     * built-in @noble-based verifier (optional peers). Pinning keys with
+     * NEITHER available is fail-CLOSED by design (signature.ts) — an update
+     * that cannot be verified is not installed. We say that out loud rather
+     * than letting the app discover it as a silent no-update condition.
      */
     private _maybeStartOta;
     private _autoEnableDebug;
@@ -148,6 +153,30 @@ declare class ScaleBunFacade {
         variant: (key: string) => string | null;
     };
     /** Convenience: emit a Phase 1 purchase event (revenue + currency + transaction_id). */
+    /**
+     * Declare which UI state the user is looking at, so taps are attributed to the surface they
+     * happened on rather than averaged across every variant of the screen.
+     *
+     *     ScaleBun.setUiState('filter-sheet', 'open');
+     *     ScaleBun.setUiState('checkout-step', 'payment');
+     *
+     * Call it when the state CHANGES — the value is read at tap time, so it only has to be right by
+     * the time the next tap lands. On React Native this is the ONLY source of UI state: unlike the web,
+     * there is no queryable accessibility tree that says a sheet is up, and guessing would produce a
+     * state key that is right on some apps and silently wrong on others.
+     *
+     * Names and values are identifiers, not content: they become query keys in the dashboard, so a
+     * person's name or a cart total does not belong in one. `;`, `:` and `|` are stripped and both
+     * halves are capped at 32 characters.
+     */
+    setUiState(name: string, value: string): void;
+    /**
+     * Stop reporting a UI state dimension — or, with no argument, all of them.
+     *
+     * Clear on screen unmount. A declaration left behind follows the user onto a surface where it means
+     * nothing, and every tap there is filed under a state that was not on screen.
+     */
+    clearUiState(name?: string): void;
     trackPurchase(input: {
         revenue: number;
         currency: string;

package/lib/typescript/specs/NativeScaleBunOta.d.ts

@@ -76,6 +76,29 @@ export interface Spec extends TurboModule {
      * `recreateReactContextInBackground()` (bridge). iOS: RCTReloadCommand.
      */
     restartApp(): void;
+    /**
+     * Verify a detached ed25519 signature in NATIVE code.
+     *
+     * Exists because the JS verifier runs inside the very bundle it protects —
+     * an attacker who lands one malicious bundle can neuter a JS check for every
+     * update after it. Platform crypto is outside the bundle's reach, and it also
+     * removes the runtime dependency on the optional @noble peers wherever the OS
+     * provides ed25519 (iOS 13+ CryptoKit everywhere; Android API 33+).
+     *
+     * All three arguments are lowercase hex, pre-validated by the JS caller:
+     * the 32-byte bundle SHA-256 (the signature is over its RAW BYTES, matching
+     * the CLI's signing contract), the 64-byte signature, the 32-byte public key.
+     *
+     * Resolves a verdict STRING, not a boolean, because "the signature is wrong"
+     * and "this OS cannot check" must never collapse into one value:
+     *   'valid'       — signature verifies under the key
+     *   'invalid'     — it does not; the caller must refuse the bundle
+     *   'unavailable' — this OS level has no ed25519 (Android < 33); the caller
+     *                   falls back to the JS verifier
+     * A rejected promise is machinery failure and the caller treats it as
+     * 'unavailable' — never as 'valid'.
+     */
+    verifyEd25519(messageHex: string, signatureHex: string, publicKeyHex: string): Promise<string>;
 }
 /**
  * Resolved via `get` (not `getEnforcing`) so the SDK degrades gracefully when

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalebun/react-native",
-  "version": "1.10.6",
+  "version": "1.11.0",
   "description": "React Native SDK for ScaleBun",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",
@@ -69,11 +69,15 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
+    "@babel/preset-env": "^8.0.2",
+    "@noble/ed25519": "^3.1.0",
+    "@noble/hashes": "^2.3.0",
     "@react-native-community/eslint-config": "^3.2.0",
     "@types/jest": "^29.5.12",
     "@types/node": "^25.3.3",
     "@types/react": "^18.2.0",
     "@types/react-native": "^0.73.0",
+    "babel-jest": "^30.4.1",
     "del-cli": "^5.1.0",
     "esbuild": "0.25.0",
     "eslint": "^8.57.0",
@@ -92,7 +96,9 @@
     "expo-router": ">=1.0.0",
     "react": ">=18.0.0",
     "react-native": ">=0.74.0",
-    "react-native-view-shot": ">=3.0.0"
+    "react-native-view-shot": ">=3.0.0",
+    "@noble/ed25519": ">=2.0.0",
+    "@noble/hashes": ">=2.0.0"
   },
   "peerDependenciesMeta": {
     "react-native-view-shot": {
@@ -103,6 +109,12 @@
     },
     "expo-router": {
       "optional": true
+    },
+    "@noble/ed25519": {
+      "optional": true
+    },
+    "@noble/hashes": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -139,6 +151,10 @@
     "lint": "eslint \"**/*.{js,ts,tsx}\"",
     "clean": "del-cli lib dist",
     "build": "bob build && node scripts/build-dist.mjs",
-    "watch": "bob build --watch"
+    "watch": "bob build --watch",
+    "test:screens": "node --experimental-transform-types --import ./scripts/rn-globals.mjs --import ./scripts/register-ts-ext.mjs --test scripts/screen-detection.test.ts",
+    "test:uistate": "node --experimental-transform-types --import ./scripts/rn-globals.mjs --import ./scripts/register-ts-ext.mjs --test scripts/ui-state.test.ts",
+    "typecheck:scripts": "tsc --noEmit -p tsconfig.scripts.json",
+    "test:protocol": "node --experimental-transform-types --import ./scripts/rn-globals.mjs --import ./scripts/register-ts-ext.mjs --test scripts/interaction-protocol.test.ts"
   }
 }

package/src/analytics/EventTracker.ts

@@ -172,7 +172,7 @@ export class EventTracker {
         this.started = true;
         if (this.cfg.automaticEventTracking) {
             this.automaticEventsUnsubscribe = subscribeAutomaticEvents((event) => {
-                this.track(event.name, event.properties);
+                this.track(event.name, event.properties, event.timestamp);
             });
         }
         if (this.cfg.autoLifecycleEvents) {
@@ -284,9 +284,9 @@ export class EventTracker {
 
     // ─── tracking ────────────────────────────────────────────────────────────
 
-    track(eventName: string, properties?: Record<string, any>): void {
+    track(eventName: string, properties?: Record<string, any>, timestamp?: number): void {
         try {
-            this.enqueue(this.buildEnvelope(eventName, properties));
+            this.enqueue(this.buildEnvelope(eventName, properties, timestamp));
             try { this.cfg.onEvent?.(eventName); } catch { /* no-throw */ }
         } catch (err) {
             logger.warn(`[ScaleBun.events] track failed: ${(err as Error)?.message}`);
@@ -408,7 +408,7 @@ export class EventTracker {
 
     // ─── internals ─────────────────────────────────────────────────────────────
 
-    private buildEnvelope(eventName: string, properties?: Record<string, any>): Envelope {
+    private buildEnvelope(eventName: string, properties?: Record<string, any>, timestamp?: number): Envelope {
         const ctx = this.cfg.context ?? {};
         let canonicalSessionId: string | null | undefined;
         try {
@@ -419,7 +419,7 @@ export class EventTracker {
         const env: Envelope = {
             event_id: uuid(),
             event_name: eventName,
-            event_time: Date.now(),
+            event_time: timestamp ?? Date.now(),
             app_id: this.cfg.appId,
             platform: this.cfg.platform ?? resolveEventPlatform(),
             installation_id: this.installationId,