@mysuperwall/react-native 0.0.0-stage → 1.2.0

package/src/MySuperwall.ts

@@ -0,0 +1,284 @@
+import { AnonymousIdentity } from './services/anonymousIdentity';
+import { FollowUpService } from './services/followUpService';
+import { LocalRuleEngine } from './engine/localRuleEngine';
+import { ManifestService } from './services/manifestService';
+import { OfflineEventQueue } from './services/offlineEventQueue';
+import { PaywallResult, PaywallData, PaywallCallbackActions } from './models/paywall';
+
+export interface MySuperwallInitOptions {
+  appKey?: string;
+  userId?: string;
+  baseUrl?: string;
+  bundleId?: string;
+  platform?: 'ios' | 'android' | 'web';
+  locale?: string;
+  country?: string;
+  appVersion?: string;
+}
+
+export class MySuperwall {
+  private static instance: MySuperwall;
+
+  public appKey?: string;
+  public userId?: string;
+  public baseUrl: string = 'https://mysuperwall.com/';
+  public bundleId?: string;
+  public platform: string = 'ios';
+  public locale: string = 'en';
+  public country: string = '';
+  public appVersion?: string;
+  private premium = false;
+  private productData: Record<string, unknown> = {};
+  private epoch = 0;
+  private presentationSequence = 0;
+  private followUps = new FollowUpService();
+  private activeFlow?: { paywall: PaywallData; callbacks: PaywallCallbackActions; metadata?: Record<string, any>; depth: number; seen: string[]; epoch: number; outcome?: boolean };
+  public userAttributes: Record<string, any> = {};
+
+  public manifestService: ManifestService;
+  public ruleEngine: LocalRuleEngine;
+  public eventQueue: OfflineEventQueue;
+
+  private onPresentPaywallListener?: (paywall: PaywallData, callbacks: PaywallCallbackActions) => void;
+
+  private constructor() {
+    this.manifestService = new ManifestService();
+    this.ruleEngine = new LocalRuleEngine();
+    this.eventQueue = new OfflineEventQueue();
+  }
+
+  public static get shared(): MySuperwall {
+    if (!MySuperwall.instance) {
+      MySuperwall.instance = new MySuperwall();
+    }
+    return MySuperwall.instance;
+  }
+
+  /**
+   * Initializes MySuperwall with cached local rule evaluation.
+   */
+  public static async initialize(options: MySuperwallInitOptions = {}): Promise<MySuperwall> {
+    const inst = MySuperwall.shared;
+    inst.resetFlow();
+    inst.userAttributes = {};
+    inst.premium = false;
+    inst.productData = {};
+    inst.appKey = options.appKey;
+    inst.baseUrl = options.baseUrl
+      ? options.baseUrl.endsWith('/')
+        ? options.baseUrl
+        : `${options.baseUrl}/`
+      : 'https://mysuperwall.com/';
+    inst.bundleId = options.bundleId;
+    inst.platform = options.platform || 'ios';
+    let deviceLocale = 'en';
+    try { deviceLocale = Intl.DateTimeFormat().resolvedOptions().locale; } catch (_) {}
+    inst.locale = (options.locale || deviceLocale).replace(/_/g, '-').toLowerCase();
+    inst.country = (options.country || inst.locale.match(/-([a-z]{2})(?:-|$)/i)?.[1] || '').toUpperCase();
+    inst.appVersion = options.appVersion;
+    inst.manifestService.configure(inst.manifestOptions());
+    inst.eventQueue = new OfflineEventQueue(JSON.stringify([inst.baseUrl, inst.appKey, inst.bundleId, inst.platform]));
+
+    const epoch = inst.epoch;
+    const userId = options.userId?.trim() || await AnonymousIdentity.get(
+      JSON.stringify([inst.baseUrl, inst.appKey, inst.bundleId, inst.platform])
+    );
+    if (epoch !== inst.epoch) return inst;
+    inst.userId = userId;
+
+    // 1. Load this app’s cached manifest into memory
+    await inst.manifestService.loadFromDisk();
+    if (epoch !== inst.epoch) return inst;
+
+    // 2. Background non-blocking sync with ETag / 304 validation
+    void inst.manifestService.syncInBackground(inst.manifestOptions());
+
+    return inst;
+  }
+
+  public identify(userId: string): void {
+    if (!userId.trim()) throw new Error('User ID cannot be empty');
+    if (this.userId !== userId.trim()) { this.resetFlow(); this.userAttributes = {}; this.premium = false; }
+    this.userId = userId.trim();
+  }
+
+  private resetFlow(): void { this.epoch++; this.followUps.reset(); this.activeFlow = undefined; }
+  private manifestOptions() {
+    return { baseUrl: this.baseUrl, appKey: this.appKey, bundleId: this.bundleId, platform: this.platform, lang: this.locale, substitutionData: this.productData };
+  }
+  public async setLocale(locale: string): Promise<void> {
+    const normalized = locale.trim().replace(/_/g, '-').toLowerCase();
+    if (!normalized || normalized === this.locale) return;
+    this.resetFlow(); this.locale = normalized;
+    const epoch = this.epoch;
+    this.manifestService.configure(this.manifestOptions());
+    await this.manifestService.loadFromDisk();
+    if (epoch === this.epoch) await this.manifestService.syncInBackground(this.manifestOptions());
+  }
+  /** Supply localized prices from StoreKit, Play Billing or RevenueCat before presenting. */
+  public async setProductData(products: Record<string, unknown>): Promise<void> {
+    const captured = JSON.parse(JSON.stringify(products)) as Record<string, unknown>;
+    if (JSON.stringify(captured) === JSON.stringify(this.productData)) return;
+    this.productData = captured;
+    const options = this.manifestOptions();
+    this.manifestService.configure(options); // Drops old price HTML and rejects stale responses.
+    await this.manifestService.syncInBackground(options);
+  }
+
+  public setCountry(country: string): void { this.country = country.trim().toUpperCase(); }
+  public setAppVersion(version: string): void { this.appVersion = version; }
+  public setSubscriptionStatus(premium: boolean): void { this.premium = premium; }
+
+  public setUserAttributes(attributes: Record<string, any>): void {
+    Object.assign(this.userAttributes, attributes);
+  }
+
+  public registerPresenter(listener: (paywall: PaywallData, callbacks: PaywallCallbackActions) => void): () => void {
+    this.onPresentPaywallListener = listener;
+    return () => {
+      if (this.onPresentPaywallListener === listener) {
+        this.onPresentPaywallListener = undefined;
+      }
+    };
+  }
+
+  /**
+   * Evaluates rules locally in-memory in memory.
+   */
+  public resolveTrigger(triggerKey: string, metadata?: Record<string, any>): PaywallResult {
+    const manifest = this.manifestService.manifest;
+    if (!manifest) {
+      return { show: false, paywall: null, reason: 'manifest_not_cached' };
+    }
+
+    const trigger = (manifest.triggers || []).find(
+      t => t.key.trim().toLowerCase() === triggerKey.trim().toLowerCase()
+    );
+    if (!trigger) {
+      return { show: false, paywall: null, reason: 'trigger_not_found' };
+    }
+
+    const evalContext: Record<string, any> = {
+      platform: this.platform,
+      country: this.country,
+      appVersion: this.appVersion,
+      metadata: metadata || {},
+      userAttributes: this.userAttributes,
+      ...(metadata || {})
+    };
+
+    const resolution = this.ruleEngine.resolveTrigger(trigger, this.userId, evalContext);
+
+    if (resolution.isHoldout) {
+      return { show: false, paywall: null, reason: 'holdout' };
+    }
+
+    if (resolution.show && resolution.paywallId) {
+      const manifestPaywall = manifest.paywalls[resolution.paywallId];
+      if (manifestPaywall) {
+        const paywallData: PaywallData = {
+          followUpRules: manifestPaywall.contentJson?.followUpRules,
+          dismissFollowUpPaywallId: trigger.dismissAction?.type === 'follow_up_paywall' ? trigger.dismissAction.followUpPaywallId || undefined : undefined,
+          id: manifestPaywall.id,
+          name: manifestPaywall.name,
+          html: manifestPaywall.html,
+          productIds: manifestPaywall.productIds,
+          products: manifestPaywall.products,
+          triggerKey,
+          abVariant: resolution.abVariant || 'A',
+          attributionUserId: this.userId,
+          attributionScope: ManifestService.scopeKey(this.manifestOptions()),
+          experimentContext: (() => {
+            const rule = trigger.rules.find(rule => rule.id === resolution.matchedRuleId);
+            const audience = rule || trigger;
+            const matches = audience.variants.filter(variant =>
+              variant.paywallId === manifestPaywall.id && variant.variant === resolution.abVariant);
+            const variant = matches.length === 1 ? matches[0] : undefined;
+            if (!variant?.variantId || !audience.experimentId || !audience.experimentVersion ||
+                !audience.audienceId || manifestPaywall.publishedVersion == null) return undefined;
+            return { experimentId: audience.experimentId, experimentVersion: audience.experimentVersion,
+              audienceId: audience.audienceId, variantId: variant.variantId,
+              variantLabel: variant.variantLabel || variant.variant,
+              paywallId: manifestPaywall.id, paywallVersion: manifestPaywall.publishedVersion };
+          })()
+        };
+
+        return { show: true, paywall: paywallData, reason: resolution.reason };
+      }
+    }
+
+    return { show: false, paywall: null, reason: resolution.reason };
+  }
+
+  /** Attribute actions to the displayed paywall, never a new assignment. */
+  public async trackPaywallEvent(type: string, paywall: PaywallData, productId?: string): Promise<void> {
+    if (paywall.attributionScope !== undefined && paywall.attributionScope !== ManifestService.scopeKey(this.manifestOptions())) return;
+    if (paywall.attributionUserId !== undefined && paywall.attributionUserId !== this.userId) return;
+    const flow = this.activeFlow;
+    if (flow && flow.paywall.presentationId === paywall.presentationId && flow.epoch === this.epoch) {
+      const keys: Record<string, string> = { purchase: 'onPurchase', purchase_success: 'onPurchase', purchase_failed: 'onPurchaseFailed', restore: 'onRestore', restore_success: 'onRestore' };
+      if (keys[type]) { flow.outcome = true; this.scheduleFollowUp(flow, keys[type]); }
+    }
+    await this.eventQueue.enqueue({ type, paywallId: paywall.id,
+      triggerKey: paywall.triggerKey, abVariant: paywall.abVariant,
+      experimentContext: paywall.attributionUserId === this.userId ? paywall.experimentContext : undefined, userId: this.userId, productId });
+    await this.eventQueue.flush({ baseUrl: this.baseUrl, appKey: this.appKey,
+      bundleId: this.bundleId, platform: this.platform });
+  }
+
+  /**
+   * Fires a trigger, presents the paywall if resolved, and wires up callbacks.
+   */
+  public handleTrigger(
+    triggerKey: string,
+    callbacks?: PaywallCallbackActions & { metadata?: Record<string, any> }
+  ): PaywallResult {
+    this.epoch++; this.followUps.cancel(); this.activeFlow = undefined;
+    const result = this.resolveTrigger(triggerKey, callbacks?.metadata);
+    if (result.show && result.paywall) {
+      const paywall = this.present(result.paywall, callbacks || {}, callbacks?.metadata, 0, []);
+      return { ...result, paywall };
+    }
+    return result;
+  }
+
+  private present(paywall: PaywallData, callbacks: PaywallCallbackActions, metadata: Record<string, any> | undefined, depth: number, seen: string[]): PaywallData {
+    paywall = { ...paywall, presentationId: `${this.epoch}:${++this.presentationSequence}` };
+    const flow: NonNullable<MySuperwall['activeFlow']> = { paywall, callbacks, metadata, depth, seen: [...seen, paywall.id], epoch: this.epoch };
+    this.activeFlow = flow;
+    let dismissed = false;
+    this.onPresentPaywallListener?.(paywall, { ...callbacks, onDismiss: () => {
+      if (dismissed) return;
+      dismissed = true;
+      if (this.activeFlow !== flow || flow.epoch !== this.epoch) return;
+      if (!flow.outcome) this.scheduleFollowUp(flow, 'onDismiss');
+      void callbacks.onDismiss?.();
+    } });
+    return paywall;
+  }
+
+  private scheduleFollowUp(flow: NonNullable<MySuperwall['activeFlow']>, event: string): void {
+    const rule = flow.paywall.followUpRules?.[event];
+    const valid = () => this.activeFlow === flow && flow.epoch === this.epoch && flow.paywall.attributionUserId === this.userId;
+    if (!valid()) return;
+    if (rule?.enabled && (rule.actionType || 'trigger') === 'trigger' && rule.triggerKey?.trim()) {
+      this.followUps.schedule(`${flow.paywall.id}:${event}:${rule.triggerKey}`, rule, flow.depth, this.premium, () => {
+        if (!valid()) return;
+        const result = this.resolveTrigger(rule.triggerKey!, flow.metadata);
+        if (!result.show || !result.paywall || (rule.skipIfPremium && this.premium) ||
+            (rule.preventRepeatPaywall !== false && flow.seen.includes(result.paywall.id))) return;
+        this.present(result.paywall, flow.callbacks, flow.metadata, flow.depth + 1, flow.seen);
+      });
+      return;
+    }
+    // Legacy close recovery is one additional screen, never an unbounded chain.
+    const id = flow.paywall.dismissFollowUpPaywallId;
+    if (event !== 'onDismiss' || flow.depth !== 0 || !id || flow.seen.includes(id)) return;
+    const next = this.manifestService.manifest?.paywalls[id];
+    if (!next) return;
+    this.followUps.schedule(`${flow.paywall.id}:legacy`, { enabled: true, actionType: 'trigger', triggerKey: 'legacy', maxChainDepth: 1 }, 0, false, () => {
+      if (valid()) this.present({ ...next, attributionUserId: this.userId, attributionScope: ManifestService.scopeKey(this.manifestOptions()), triggerKey: flow.paywall.triggerKey,
+        followUpRules: next.contentJson?.followUpRules }, flow.callbacks, flow.metadata, 1, flow.seen);
+    });
+  }
+}

package/src/engine/localRuleEngine.ts

@@ -0,0 +1,375 @@
+import { ManifestCondition, ManifestRule, ManifestTrigger, ManifestVariant } from '../models/manifest';
+
+/**
+ * Pure TypeScript SHA-256 hash to ensure 0-dependency, 0-native-bridge execution on Hermes & JSC.
+ */
+function sha256Bytes(ascii: string): Uint8Array {
+  function rightRotate(value: number, amount: number) {
+    return (value >>> amount) | (value << (32 - amount));
+  }
+
+  const mathPow = Math.pow;
+  const maxWord = mathPow(2, 32);
+  const lengthProperty = 'length';
+  let i = 0, j = 0;
+  let result = '';
+
+  const words: number[] = [];
+  const asciiBitLength = ascii[lengthProperty] * 8;
+
+  const hash: number[] = [];
+  const k: number[] = [];
+  let primeCounter = 0;
+
+  const isComposite: Record<number, boolean> = {};
+  for (let candidate = 2; primeCounter < 64; candidate++) {
+    if (!isComposite[candidate]) {
+      for (i = 0; i < 313; i += candidate) {
+        isComposite[i] = true;
+      }
+      hash[primeCounter] = (mathPow(candidate, 0.5) * maxWord) | 0;
+      k[primeCounter++] = (mathPow(candidate, 1 / 3) * maxWord) | 0;
+    }
+  }
+
+  ascii += '\x80';
+  while ((ascii[lengthProperty] % 64) - 56) ascii += '\x00';
+  for (i = 0; i < ascii[lengthProperty]; i++) {
+    j = ascii.charCodeAt(i);
+    words[i >> 2] |= j << (((3 - i) % 4) * 8);
+  }
+  words[words[lengthProperty]] = (asciiBitLength / maxWord) | 0;
+  words[words[lengthProperty]] = asciiBitLength;
+
+  for (j = 0; j < words[lengthProperty]; ) {
+    const w = words.slice(j, (j += 16));
+    const oldHash = hash.slice(0);
+
+    for (i = 0; i < 64; i++) {
+      const w15 = w[i - 15], w2 = w[i - 2];
+      const s0 = rightRotate(w15, 7) ^ rightRotate(w15, 18) ^ (w15 >>> 3);
+      const s1 = rightRotate(w2, 17) ^ rightRotate(w2, 19) ^ (w2 >>> 10);
+      w[i] = i < 16 ? w[i] : (w[i - 16] + s0 + w[i - 7] + s1) | 0;
+
+      const s1_maj = rightRotate(hash[0], 2) ^ rightRotate(hash[0], 13) ^ rightRotate(hash[0], 22);
+      const maj = (hash[0] & hash[1]) ^ (hash[0] & hash[2]) ^ (hash[1] & hash[2]);
+      const t2 = (s1_maj + maj) | 0;
+
+      const s1_ch = rightRotate(hash[4], 6) ^ rightRotate(hash[4], 11) ^ rightRotate(hash[4], 25);
+      const ch = (hash[4] & hash[5]) ^ (~hash[4] & hash[6]);
+      const t1 = (hash[7] + s1_ch + ch + k[i] + w[i]) | 0;
+
+      hash[7] = hash[6];
+      hash[6] = hash[5];
+      hash[5] = hash[4];
+      hash[4] = (hash[3] + t1) | 0;
+      hash[3] = hash[2];
+      hash[2] = hash[1];
+      hash[1] = hash[0];
+      hash[0] = (t1 + t2) | 0;
+    }
+
+    for (i = 0; i < 8; i++) {
+      hash[i] = (hash[i] + oldHash[i]) | 0;
+    }
+  }
+
+  const out = new Uint8Array(32);
+  for (i = 0; i < 8; i++) {
+    out[i * 4] = (hash[i] >>> 24) & 255;
+    out[i * 4 + 1] = (hash[i] >>> 16) & 255;
+    out[i * 4 + 2] = (hash[i] >>> 8) & 255;
+    out[i * 4 + 3] = hash[i] & 255;
+  }
+  return out;
+}
+
+export interface RuleEngineResolution {
+  matchedRuleId?: string;
+  show: boolean;
+  paywallId: string | null;
+  abVariant: string | null;
+  matchedRuleName: string | null;
+  isHoldout: boolean;
+  reason: string;
+}
+
+export class LocalRuleEngine {
+  /**
+   * Deterministic bucket from 0 to 99 matching backend SHA-256 logic.
+   */
+  getDeterministicBucket(userId?: string | null, salt: string = ''): number {
+    if (!userId) {
+      return Math.floor(Math.random() * 100);
+    }
+    const input = `${userId}:${salt}`;
+    // Match backend/native SHA-256 over UTF-8, including non-ASCII user IDs.
+    const utf8 = encodeURIComponent(input).replace(/%([0-9A-F]{2})/g,
+      (_, hex: string) => String.fromCharCode(parseInt(hex, 16)));
+    const bytes = sha256Bytes(utf8);
+    const u32 =
+      ((bytes[0] << 24) >>> 0) +
+      ((bytes[1] << 16) >>> 0) +
+      ((bytes[2] << 8) >>> 0) +
+      (bytes[3] >>> 0);
+    return (u32 % 100) >>> 0;
+  }
+
+  /**
+   * Compares two semantic version strings.
+   */
+  compareVersions(v1?: string | null, v2?: string | null): number {
+    const clean1 = (v1 || '').replace(/[^0-9.]/g, '');
+    const clean2 = (v2 || '').replace(/[^0-9.]/g, '');
+    const p1 = clean1.split('.').map(n => parseInt(n, 10) || 0);
+    const p2 = clean2.split('.').map(n => parseInt(n, 10) || 0);
+    const maxLen = Math.max(p1.length, p2.length);
+
+    for (let i = 0; i < maxLen; i++) {
+      const n1 = p1[i] ?? 0;
+      const n2 = p2[i] ?? 0;
+      if (n1 > n2) return 1;
+      if (n1 < n2) return -1;
+    }
+    return 0;
+  }
+
+  /**
+   * Resolves nested field access like "metadata.tier".
+   */
+  resolveContextValue(field: string, context: Record<string, any>): any {
+    if (field in context) return context[field];
+    const parts = field.split('.');
+    let current: any = context;
+    for (const part of parts) {
+      if (current && typeof current === 'object' && part in current) {
+        current = current[part];
+      } else {
+        return undefined;
+      }
+    }
+    return current;
+  }
+
+  /**
+   * Evaluates a single condition.
+   */
+  evaluateCondition(condition: ManifestCondition, context: Record<string, any>): boolean {
+    const actual = this.resolveContextValue(condition.field, context);
+    const op = (condition.operator || 'equals').toLowerCase();
+    const target = condition.value;
+
+    switch (op) {
+      case 'equals':
+      case 'eq':
+        if (actual !== undefined && actual !== null && target !== undefined && target !== null) {
+          return String(actual).trim().toLowerCase() === String(target).trim().toLowerCase();
+        }
+        return actual == target;
+
+      case 'not_equals':
+      case 'neq':
+        if (actual !== undefined && actual !== null && target !== undefined && target !== null) {
+          return String(actual).trim().toLowerCase() !== String(target).trim().toLowerCase();
+        }
+        return actual != target;
+
+      case 'contains':
+        if (actual === undefined || actual === null || target === undefined || target === null) return false;
+        return String(actual).toLowerCase().includes(String(target).toLowerCase());
+
+      case 'not_contains':
+        if (actual === undefined || actual === null || target === undefined || target === null) return true;
+        return !String(actual).toLowerCase().includes(String(target).toLowerCase());
+
+      case 'gt':
+      case 'gte':
+      case 'lt':
+      case 'lte': {
+        const aNum = Number(actual);
+        const tNum = Number(target);
+        if (isNaN(aNum) || isNaN(tNum)) return false;
+        if (op === 'gt') return aNum > tNum;
+        if (op === 'gte') return aNum >= tNum;
+        if (op === 'lt') return aNum < tNum;
+        if (op === 'lte') return aNum <= tNum;
+        return false;
+      }
+
+      case 'in_list':
+      case 'in': {
+        if (actual === undefined || actual === null) return false;
+        const aStr = String(actual).trim().toLowerCase();
+        if (Array.isArray(target)) {
+          return target.some(elem => String(elem).trim().toLowerCase() === aStr);
+        }
+        const parts = String(target).split(',').map(s => s.trim().toLowerCase());
+        return parts.includes(aStr);
+      }
+
+      case 'not_in_list':
+      case 'not_in': {
+        if (actual === undefined || actual === null) return true;
+        const aStr = String(actual).trim().toLowerCase();
+        if (Array.isArray(target)) {
+          return !target.some(elem => String(elem).trim().toLowerCase() === aStr);
+        }
+        const parts = String(target).split(',').map(s => s.trim().toLowerCase());
+        return !parts.includes(aStr);
+      }
+
+      case 'version_gt':
+        return this.compareVersions(actual, target) > 0;
+      case 'version_gte':
+        return this.compareVersions(actual, target) >= 0;
+      case 'version_lt':
+        return this.compareVersions(actual, target) < 0;
+      case 'version_lte':
+        return this.compareVersions(actual, target) <= 0;
+
+      default:
+        return false;
+    }
+  }
+
+  /**
+   * Checks if a rule matches given context.
+   */
+  matchesRule(rule: ManifestRule, context: Record<string, any>): boolean {
+    if (!rule.conditions || rule.conditions.length === 0) return true;
+    const isAny = rule.matchType === 'any';
+    return isAny
+      ? rule.conditions.some(c => this.evaluateCondition(c, context))
+      : rule.conditions.every(c => this.evaluateCondition(c, context));
+  }
+
+  /**
+   * Deterministically selects a variant respecting holdout.
+   */
+  selectDeterministicVariant(
+    userId: string | null | undefined,
+    salt: string,
+    variants: ManifestVariant[],
+    fallbackPaywallId: string | null,
+    holdoutPercentage: number = 0
+  ): { paywallId: string | null; abVariant: string | null; isHoldout: boolean } {
+    if (holdoutPercentage > 0) {
+      const holdoutBucket = this.getDeterministicBucket(userId, `${salt}:holdout`);
+      if (holdoutBucket < holdoutPercentage) {
+        return { paywallId: null, abVariant: null, isHoldout: true };
+      }
+    }
+
+    const validVariants = (variants || []).filter(v => Boolean(v.paywallId));
+    if (validVariants.length === 0) {
+      return { paywallId: fallbackPaywallId, abVariant: 'A', isHoldout: false };
+    }
+
+    const totalWeight = validVariants.reduce((sum, v) => sum + Math.max(1, v.weight ?? 50), 0);
+    if (totalWeight <= 0) {
+      const first = validVariants[0];
+      return { paywallId: first.paywallId, abVariant: first.variant, isHoldout: false };
+    }
+
+    const bucket = this.getDeterministicBucket(userId, `${salt}:variant`);
+    const target = Math.floor((bucket * totalWeight) / 100);
+    let cumulative = 0;
+
+    for (const v of validVariants) {
+      cumulative += Math.max(1, v.weight ?? 50);
+      if (target < cumulative) {
+        return { paywallId: v.paywallId, abVariant: v.variant, isHoldout: false };
+      }
+    }
+
+    const last = validVariants[validVariants.length - 1];
+    return { paywallId: last.paywallId, abVariant: last.variant, isHoldout: false };
+  }
+
+  /**
+   * Resolves a trigger in-memory with 0 ms latency.
+   */
+  resolveTrigger(
+    trigger: ManifestTrigger,
+    userId: string | null | undefined,
+    context: Record<string, any>
+  ): RuleEngineResolution {
+    // 1. Check priority-ordered audience rules
+    const activeRules = [...(trigger.rules || [])].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+    for (const rule of activeRules) {
+      if (this.matchesRule(rule, context)) {
+        const { paywallId, abVariant, isHoldout } = this.selectDeterministicVariant(
+          userId,
+          rule.id,
+          rule.variants,
+          rule.paywallId || trigger.paywallId,
+          rule.holdoutPercentage || 0
+        );
+
+        if (isHoldout) {
+          return {
+            show: false,
+            paywallId: null,
+            abVariant: null,
+            matchedRuleName: rule.name,
+            matchedRuleId: rule.id,
+            isHoldout: true,
+            reason: 'rule_holdout'
+          };
+        }
+
+        if (paywallId) {
+          return {
+            show: true,
+            paywallId,
+            abVariant: abVariant || 'A',
+            matchedRuleName: rule.name,
+            matchedRuleId: rule.id,
+            isHoldout: false,
+            reason: 'rule_matched'
+          };
+        }
+      }
+    }
+
+    // 2. Fall back to root trigger variants & holdout
+    const { paywallId, abVariant, isHoldout } = this.selectDeterministicVariant(
+      userId,
+      trigger.key,
+      trigger.variants,
+      trigger.paywallId,
+      trigger.holdoutPercentage || 0
+    );
+
+    if (isHoldout) {
+      return {
+        show: false,
+        paywallId: null,
+        abVariant: null,
+        matchedRuleName: null,
+        isHoldout: true,
+        reason: 'root_holdout'
+      };
+    }
+
+    if (paywallId) {
+      return {
+        show: true,
+        paywallId,
+        abVariant: abVariant || 'A',
+        matchedRuleName: null,
+        isHoldout: false,
+        reason: 'root_variant'
+      };
+    }
+
+    return {
+      show: false,
+      paywallId: null,
+      abVariant: null,
+      matchedRuleName: null,
+      isHoldout: false,
+      reason: 'no_paywall_mapped'
+    };
+  }
+}

package/src/hooks/usePaywall.ts

@@ -0,0 +1,27 @@
+import { useState, useEffect, useCallback } from 'react';
+import { MySuperwall } from '../MySuperwall';
+import { PaywallData, PaywallCallbackActions } from '../models/paywall';
+
+export function usePaywall() {
+  const [activePaywall, setActivePaywall] = useState<PaywallData | null>(null);
+  const [callbacks, setCallbacks] = useState<PaywallCallbackActions>({});
+
+  useEffect(() => {
+    const unregister = MySuperwall.shared.registerPresenter((paywall, actions) => {
+      setActivePaywall(paywall);
+      setCallbacks(actions);
+    });
+    return unregister;
+  }, []);
+
+  const dismiss = useCallback(() => {
+    setActivePaywall(null);
+  }, []);
+
+  return {
+    activePaywall,
+    isVisible: Boolean(activePaywall),
+    callbacks,
+    dismiss
+  };
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export * from './models/manifest';
+export * from './models/paywall';
+export * from './engine/localRuleEngine';
+export * from './services/manifestService';
+export * from './services/offlineEventQueue';
+export * from './ui/PaywallModal';
+export * from './hooks/usePaywall';
+import { MySuperwall } from './MySuperwall';
+export { MySuperwall };
+export default MySuperwall;
+
+export type { MySuperwallInitOptions } from './MySuperwall';