@scalebun/react-native 1.10.6 → 1.10.7

package/lib/module/public/ScaleBunFacade.js

@@ -209,12 +209,17 @@ 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.
    */
   _maybeStartOta(rawConfig) {
     const ota = rawConfig?.ota;
@@ -226,15 +231,34 @@ class ScaleBunFacade {
       const {
         otaOrchestrator
       } = require('../features/ota/OtaOrchestrator');
-      const publicKey = ota.publicSigningKey;
+      const rawSingle = ota.publicSigningKey;
+      const rawList = ota.publicSigningKeys;
+      const publicKeys = Array.from(new Set([...(typeof rawSingle === 'string' && rawSingle ? [rawSingle] : []), ...(Array.isArray(rawList) ? rawList : [])].filter(k => typeof k === 'string' && k.trim().length > 0)));
+      // Signing was REQUESTED if a usable key exists, or the host passed a
+      // keys array at all — an empty one included. `publicSigningKeys: []`
+      // is a broken attempt to enable signing, and it must flow through to
+      // signature.ts's fail-closed handling, not silently disable signing.
+      const signingRequested = publicKeys.length > 0 || Array.isArray(rawList);
       const verifier = ota.verifySignature;
-      if (publicKey && typeof verifier !== 'function') {
-        logger.warn('[ScaleBun] ota.publicSigningKey is set but ota.verifySignature is not a function. ' + 'Signature checking is fail-closed: updates will be REJECTED until a verifier is supplied.');
+      if (signingRequested && typeof verifier !== 'function') {
+        // A host verifier is optional since the built-in one landed — the
+        // old unconditional warning here told every correctly-configured
+        // app that its updates would be rejected. Warn only when neither
+        // verifier can actually be resolved.
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const {
+          getBuiltinVerifier
+        } = require('../features/ota/crypto/builtinVerifier');
+        if (!getBuiltinVerifier()) {
+          logger.warn('[ScaleBun] A signing key is pinned but no signature verifier is available. ' + 'Signature checking is fail-closed: updates will be REJECTED until one exists. ' + 'Install the optional peers `@noble/ed25519` + `@noble/hashes` (no further ' + 'code needed), or supply `ota.verifySignature`.');
+        }
       }
       otaOrchestrator.init({
-        ...(publicKey ? {
+        ...(signingRequested ? {
           signature: {
-            publicKey,
+            // Single key stays a plain string — the shape every
+            // existing consumer and test already handles.
+            publicKey: publicKeys.length === 1 ? publicKeys[0] : publicKeys,
             verifier
           }
         } : {}),
@@ -471,6 +495,45 @@ class ScaleBunFacade {
   }
 
   /** 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, value) {
+    try {
+      const {
+        setUiState
+      } = require('../features/journey/uiState');
+      setUiState(name, value);
+    } catch {/* no-throw: a state declaration must never break the host */}
+  }
+
+  /**
+   * 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) {
+    try {
+      const {
+        clearUiState
+      } = require('../features/journey/uiState');
+      clearUiState(name);
+    } catch {/* no-throw */}
+  }
   trackPurchase(input) {
     noThrow(() => this._eventTracker?.trackPurchase(input));
   }

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

@@ -3,5 +3,5 @@
  * can attribute telemetry to the SDK build that produced it.
  * Keep in sync with package.json "version".
  */
-export declare const SDK_VERSION = "1.10.6";
+export declare const SDK_VERSION = "1.10.7";
 //# sourceMappingURL=version.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/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.10.7",
   "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,9 @@
     "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"
   }
 }

package/src/core/config/schema.ts

@@ -85,6 +85,10 @@ type Field =
     | { kind: 'bool'; def?: boolean; opt?: true }
     | { kind: 'num'; min?: number; max?: number; int?: true; def?: number; opt?: true }
     | { kind: 'str'; min?: number; opt?: true }
+    // Array of strings. Message parity target is the vendored z's
+    // `z.array(z.string())`: "Expected array, received X" at the field path,
+    // "Expected string, received X" at [...path, index] per bad element.
+    | { kind: 'strArr'; opt?: true }
     | { kind: 'enum'; values: readonly string[]; opt?: true }
     | { kind: 'any'; def: () => unknown }
     | { kind: 'obj'; shape: Record<string, Field>; def?: true; opt?: true };
@@ -198,6 +202,11 @@ const SHAPE: Record<string, Field> = {
             checkOnForeground: bool(true),
             channelOverride: { kind: 'str', opt: true },
             publicSigningKey: { kind: 'str', opt: true },
+            // Rotation support: several pinned keys, any of which may verify a
+            // bundle. Ship a build pinning [old, new], re-sign server-side with
+            // new, drop old next release — no emergency store submission when a
+            // key must be replaced. Merged with publicSigningKey by the facade.
+            publicSigningKeys: { kind: 'strArr', opt: true },
             mandatoryBlocksUi: bool(false),
         },
     },
@@ -232,9 +241,11 @@ function parseField(
                   ? 'Expected number, received undefined'
                   : field.kind === 'str'
                     ? 'Expected string, received undefined'
-                    : field.kind === 'enum'
-                      ? "Invalid enum value. Expected " + field.values.map((v) => `'${v}'`).join(' | ')
-                      : 'Expected object, received undefined',
+                    : field.kind === 'strArr'
+                      ? 'Expected array, received undefined'
+                      : field.kind === 'enum'
+                        ? "Invalid enum value. Expected " + field.values.map((v) => `'${v}'`).join(' | ')
+                        : 'Expected object, received undefined',
         );
     }
 
@@ -250,6 +261,20 @@ function parseField(
                 return fail(`String must contain at least ${field.min} character(s)`);
             }
             return { ok: true, value: input, present: true };
+        case 'strArr': {
+            // Mirrors the vendored ArraySchema exactly: element failures are
+            // reported at their index and fail the whole field (no partial
+            // arrays reach the output).
+            if (!Array.isArray(input)) return fail(`Expected array, received ${typeofName(input)}`);
+            let allOk = true;
+            for (let i = 0; i < input.length; i++) {
+                if (typeof input[i] !== 'string') {
+                    issues.push({ path: [...path, i], message: `Expected string, received ${typeofName(input[i])}` });
+                    allOk = false;
+                }
+            }
+            return allOk ? { ok: true, value: [...input], present: true } : { ok: false, present: true };
+        }
         case 'num':
             if (typeof input !== 'number' || Number.isNaN(input)) {
                 return fail(`Expected number, received ${typeofName(input)}`);
@@ -381,6 +406,8 @@ export interface ScaleBunConfig {
         checkOnForeground: boolean;
         channelOverride?: string;
         publicSigningKey?: string;
+        /** Additional pinned keys for rotation; unioned with publicSigningKey. */
+        publicSigningKeys?: string[];
         mandatoryBlocksUi: boolean;
     };
 }