@mobileai/react-native 0.9.0 → 0.9.2

package/src/core/FiberTreeWalker.ts

@@ -48,19 +48,7 @@ const VIDEO_TYPES = new Set([
   'Video', 'ExpoVideo', 'RCTVideo', 'VideoPlayer', 'VideoView',
 ]);
 
-// Overlay component names — these render ABOVE the active screen's subtree
-// (as siblings of the navigation container), so the screen-scoped walker misses them.
-// We detect these by name and walk them in a second pass.
-const OVERLAY_COMPONENT_NAMES = new Set([
-  // Toast libraries
-  'Toast', 'ToastContainer', 'ToastRender', 'FlashMessage', 'DropdownAlert',
-  'SnackBar', 'Snackbar', 'NotificationContainer',
-  // Dialog/Alert libraries
-  'Dialog', 'DialogContainer', 'AlertDialog',
-  // Modal/BottomSheet
-  'BottomSheet', 'ActionSheet', 'RBSheet', 'BottomSheetModal',
-  'Popup', 'PopupContainer', 'Tooltip',
-]);
+
 
 // Known RN internal component names to skip when walking up for context
 const RN_INTERNAL_NAMES = new Set([
@@ -442,70 +430,10 @@ export interface WalkResult {
   interactives: InteractiveElement[];
 }
 
-// ─── Overlay Detection ─────────────────────────────────────────
-
-/**
- * Scan the root fiber tree for visible overlay nodes (toasts, dialogs, modals)
- * that render OUTSIDE the active screen's subtree.
- *
- * Toast/dialog libraries (react-native-alert-notification, react-native-flash-message, etc.)
- * typically render their overlay as a SIBLING of the navigation container:
- *   <Root>
- *     {children}       ← navigation tree (contains screens)
- *     <Toast ... />     ← overlay (outside screen subtree)
- *   </Root>
- *
- * This function finds those overlay nodes so the main walker can include them.
- */
-function findOverlayNodes(rootFiber: any, screenSubtree: any): any[] {
-  const overlays: any[] = [];
-
-  function scan(node: any): void {
-    if (!node) return;
-
-    // Skip the screen subtree itself (already walked by main pass)
-    if (node === screenSubtree) {
-      // Don't scan children, but DO scan siblings
-      if (node.sibling) scan(node.sibling);
-      return;
-    }
-
-    const name = getComponentName(node);
-    const props = node.memoizedProps || {};
-    const style = props.style || {};
-    // Flatten array styles (StyleSheet.flatten equivalent)
-    const flatStyle = Array.isArray(style)
-      ? Object.assign({}, ...style.filter(Boolean))
-      : style;
-
-    // Detection: known overlay component name
-    const isOverlayByName = name && OVERLAY_COMPONENT_NAMES.has(name);
-
-    // Detection: position absolute with content (likely a floating overlay)
-    const isOverlayByStyle = flatStyle.position === 'absolute' &&
-      (flatStyle.zIndex > 100 || flatStyle.elevation > 10);
-
-    if (isOverlayByName || isOverlayByStyle) {
-      // Only include if the overlay has visible content (not empty/hidden)
-      const hasChildren = !!node.child;
-      const isHidden = flatStyle.opacity === 0 || flatStyle.display === 'none';
-      if (hasChildren && !isHidden) {
-        logger.debug('FiberTreeWalker', `Found overlay: ${name || 'unnamed'} (byName=${isOverlayByName}, byStyle=${isOverlayByStyle})`);
-        overlays.push(node);
-        // Don't scan children of found overlays (the main walker will handle them)
-        if (node.sibling) scan(node.sibling);
-        return;
-      }
-    }
-
-    // Continue scanning children and siblings
-    if (node.child) scan(node.child);
-    if (node.sibling) scan(node.sibling);
-  }
-
-  scan(rootFiber);
-  return overlays;
-}
+// ─── Note on overlays ──────────────────────────────────────────
+// Toasts, modals, and dialogs are now captured naturally because
+// walkFiberTree starts from the root Fiber and prunes only
+// display:none nodes (inactive screens). No separate overlay scan needed.
 
 // ─── Main Tree Walker ──────────────────────────────────────────
 
@@ -520,31 +448,50 @@ export function walkFiberTree(rootRef: any, config?: WalkConfig): WalkResult {
     return { elementsText: '', interactives: [] };
   }
 
-  // Scope to active screen's subtree if screenName is provided
-  let startNode = fiber;
+  // Always walk from the root Fiber — inactive screens are pruned inside
+  // processNode by checking for display:none, which React Navigation applies
+  // to all inactive screens. This ensures navigation chrome (tab bar, header)
+  // is always included without hardcoding any component names.
+  const startNode = fiber;
   if (config?.screenName) {
-    const screenFiber = findScreenFiberNode(fiber, config.screenName);
-    if (screenFiber) {
-      startNode = screenFiber;
-      logger.debug('FiberTreeWalker', `Walk scoped to screen "${config.screenName}" (component: ${getComponentName(screenFiber)})`);
-    } else {
-      logger.debug('FiberTreeWalker', `Screen "${config.screenName}" not found in Fiber tree — searching entire tree`);
-    }
+    logger.debug('FiberTreeWalker', `Walk active for screen "${config.screenName}" (inactive screens pruned via display:none)`);
   }
 
-  // Collect overlay nodes (toasts, dialogs, modals) that render outside the screen subtree.
-  // These are siblings of the navigation container at the root fiber level.
-  const overlayNodes = config?.screenName ? findOverlayNodes(fiber, startNode) : [];
+  // Overlay detection is superseded by root-level walk — all visible nodes
+  // (toasts, modals, overlays) are included naturally since they aren't hidden.
+  const overlayNodes: any[] = [];
 
   const interactives: InteractiveElement[] = [];
   let currentIndex = 0;
   const hasWhitelist = config?.interactiveWhitelist && (config.interactiveWhitelist.length ?? 0) > 0;
 
-  function processNode(node: any, depth: number = 0, isInsideInteractive: boolean = false, ancestorOnPress: any = null): string {
+  function processNode(
+    node: any, 
+    depth: number = 0, 
+    isInsideInteractive: boolean = false, 
+    ancestorOnPress: any = null,
+    currentZoneId: string | undefined = undefined
+  ): string {
     if (!node) return '';
 
     const props = node.memoizedProps || {};
 
+    // ── Prune inactive screens ──────────────────────────────────
+    // Two mechanisms cover all React Navigation setups:
+    //
+    // 1. react-native-screens (Expo default, recommended):
+    //    React Navigation sets activityState=0 on inactive tab screens.
+    //    Stack screens retain activityState=2 even in the background (NativeStack
+    //    never decreases activityState — confirmed from react-native-screens source).
+    //    Those are kept as useful navigation history context for the agent.
+    //
+    // 2. ResourceSavingScene (React Navigation fallback without react-native-screens):
+    //    Wraps inactive screen content with pointerEvents="none". Prune any such wrapper.
+    //
+    // Both are prop-based — no component names, no CSS display property.
+    if (props.activityState === 0) return '';
+    if (props.pointerEvents === 'none') return '';
+
     // ── Security Constraints ──
     if (props.aiIgnore === true) return '';
     if (matchesRefList(node, config?.interactiveBlacklist)) {
@@ -591,6 +538,25 @@ export function walkFiberTree(rootRef: any, config?: WalkConfig): WalkResult {
     const producesOutput = shouldInclude || isTextNode || isImageNode || isVideoNode;
     const childDepth = producesOutput ? depth + 1 : depth;
 
+    const nextZoneId = componentName === 'AIZone' && props.id ? props.id : currentZoneId;
+
+    const indent = '  '.repeat(depth);
+
+    // ── Zone Header Emission ──────────────────────────────────
+    // When entering an AIZone boundary, emit a section header so the agent
+    // knows this zone exists, what its id is, and what it's allowed to do.
+    // This is what lets the agent call simplify_zone / guide_user proactively.
+    let zoneHeader = '';
+    if (componentName === 'AIZone' && props.id) {
+      const permissions: string[] = [];
+      if (props.allowSimplify) permissions.push('simplify');
+      if (props.allowHighlight) permissions.push('highlight');
+      if (props.allowInjectHint) permissions.push('hint');
+      if (props.allowInjectCard) permissions.push('card');
+      const permStr = permissions.length ? ` | permissions: ${permissions.join(', ')}` : '';
+      zoneHeader = `${indent}[zone: ${props.id}${permStr}]\n`;
+    }
+
     // Process children
     let childrenText = '';
     let currentChild = node.child;
@@ -600,11 +566,15 @@ export function walkFiberTree(rootRef: any, config?: WalkConfig): WalkResult {
         childDepth,
         isInsideInteractive || !!shouldInclude,
         nextAncestorOnPress,
+        nextZoneId,
       );
       currentChild = currentChild.sibling;
     }
 
-    const indent = '  '.repeat(depth);
+    // Prepend zone header before children if this is a zone root
+    if (zoneHeader) {
+      childrenText = zoneHeader + childrenText;
+    }
 
     if (shouldInclude) {
       const resolvedType = elementType || 'pressable';
@@ -633,13 +603,20 @@ export function walkFiberTree(rootRef: any, config?: WalkConfig): WalkResult {
         index: currentIndex,
         type: resolvedType,
         label: label || `[${resolvedType}]`,
+        aiPriority: props.aiPriority,
+        zoneId: currentZoneId,
         fiberNode: node,
         props: { ...props },
       });
 
       // Build output tag with state attributes
       const stateAttrs = extractStateAttributes(props);
-      const attrStr = stateAttrs ? ` ${stateAttrs}` : '';
+      let attrStr = stateAttrs ? ` ${stateAttrs}` : '';
+      if (props.aiPriority) {
+        attrStr += ` aiPriority="${props.aiPriority}"`;
+        if (currentZoneId) attrStr += ` zoneId="${currentZoneId}"`;
+      }
+      
       const textContent = label || '';
       const elementOutput = `${indent}[${currentIndex}]<${resolvedType}${attrStr}>${textContent} />${childrenText.trim() ? '\n' + childrenText : ''}\n`;
       currentIndex++;
@@ -651,7 +628,8 @@ export function walkFiberTree(rootRef: any, config?: WalkConfig): WalkResult {
     if (isTextNode) {
       const textContent = extractRawText(props.children);
       if (textContent && textContent.trim() !== '') {
-        return `${indent}${textContent.trim()}\n`;
+        const priorityTag = props.aiPriority ? ` (aiPriority="${props.aiPriority}"${currentZoneId ? ` zoneId="${currentZoneId}"` : ''})` : '';
+        return `${indent}${textContent.trim()}${priorityTag}\n`;
       }
     }
 

package/src/core/IdleDetector.ts

@@ -0,0 +1,72 @@
+export interface IdleDetectorConfig {
+  /** Time in ms before the agent pulses subtly (e.g. 120_000 for 2m) */
+  pulseAfterMs: number;
+  /** Time in ms before the agent shows a badge (e.g. 240_000 for 4m) */
+  badgeAfterMs: number;
+  /** Callback fired when the user is idle enough for a subtle pulse */
+  onPulse: () => void;
+  /** Callback fired when the user is idle enough for a proactive badge. Receives the context suggestion. */
+  onBadge: (suggestion: string) => void;
+  /** Callback fired when the user interacts, cancelling idle states */
+  onReset: () => void;
+  /** Dynamic context suggestion generator based on current screen */
+  generateSuggestion?: () => string;
+}
+
+export class IdleDetector {
+  private pulseTimer: ReturnType<typeof setTimeout> | null = null;
+  private badgeTimer: ReturnType<typeof setTimeout> | null = null;
+  private dismissed = false;
+  private config: IdleDetectorConfig | null = null;
+
+  start(config: IdleDetectorConfig): void {
+    this.config = config;
+    this.dismissed = false;
+    this.resetTimers();
+  }
+
+  reset(): void {
+    if (!this.config || this.dismissed) return;
+    this.config.onReset();
+    this.resetTimers();
+  }
+
+  dismiss(): void {
+    this.dismissed = true;
+    this.clearTimers();
+    if (this.config) {
+      this.config.onReset();
+    }
+  }
+
+  destroy(): void {
+    this.clearTimers();
+    this.config = null;
+  }
+
+  private resetTimers(): void {
+    this.clearTimers();
+
+    if (!this.config || this.dismissed) return;
+
+    this.pulseTimer = setTimeout(() => {
+      this.config?.onPulse();
+    }, this.config.pulseAfterMs);
+
+    this.badgeTimer = setTimeout(() => {
+      const suggestion = this.config?.generateSuggestion?.() ?? "Need help with this screen?";
+      this.config?.onBadge(suggestion);
+    }, this.config.badgeAfterMs);
+  }
+
+  private clearTimers(): void {
+    if (this.pulseTimer) {
+      clearTimeout(this.pulseTimer);
+      this.pulseTimer = null;
+    }
+    if (this.badgeTimer) {
+      clearTimeout(this.badgeTimer);
+      this.badgeTimer = null;
+    }
+  }
+}

package/src/core/ZoneRegistry.ts

@@ -0,0 +1,44 @@
+import React, { createContext } from 'react';
+import type { AIZoneConfig, RegisteredZone } from './types';
+
+export class ZoneRegistry {
+  private zones = new Map<string, RegisteredZone>();
+
+  register(config: AIZoneConfig, ref: React.RefObject<any>): void {
+    if (this.zones.has(config.id)) {
+      console.warn(`[MobileAI] Zone ID "${config.id}" is already registered on this screen. Overwriting.`);
+    }
+    this.zones.set(config.id, { ...config, ref });
+  }
+
+  unregister(id: string): void {
+    this.zones.delete(id);
+  }
+
+  get(id: string): RegisteredZone | undefined {
+    return this.zones.get(id);
+  }
+
+  getAll(): RegisteredZone[] {
+    return Array.from(this.zones.values());
+  }
+
+  isActionAllowed(zoneId: string, action: 'highlight' | 'hint' | 'simplify' | 'card'): boolean {
+    const zone = this.get(zoneId);
+    if (!zone) return false;
+
+    switch (action) {
+      case 'highlight': return !!zone.allowHighlight;
+      case 'hint': return !!zone.allowInjectHint;
+      case 'simplify': return !!zone.allowSimplify;
+      case 'card': return !!zone.allowInjectCard;
+      default: return false;
+    }
+  }
+}
+
+// Global registry instance shared across the Agent session
+export const globalZoneRegistry = new ZoneRegistry();
+
+// Export context so AIZone components can register themselves
+export const ZoneRegistryContext = createContext<ZoneRegistry>(globalZoneRegistry);

package/src/core/systemPrompt.ts

@@ -102,6 +102,7 @@ If a UI element is hidden (aiIgnore) but a matching custom action exists, use th
 - Trying too hard can be harmful. If stuck, call done() with partial results rather than repeating failed actions.
 - If you do not know how to proceed with the current screen, use ask_user to request specific instructions from the user.
 - NAVIGATION: Always use tap actions to move between screens — tap tab bar buttons, back buttons, and navigation links. This ensures all required route params (like item IDs) are passed automatically by the app. The navigate() tool is ONLY for top-level screens that require no params (e.g. Login, Settings, Cart). NEVER call navigate() on screens that require a selection or ID (e.g. DishDetail, SelectCategory, ProfileDetail) — this will crash the app. For those screens, always tap the relevant item in the parent screen.
+- UI SIMPLIFICATION: If you see elements labeled \`aiPriority="low"\` inside a specific \`zoneId=...\`, and the screen looks cluttered or overwhelming to the user's immediate goal, use the \`simplify_zone(zoneId)\` tool to hide those elements. Use \`restore_zone(zoneId)\` to bring them back if needed later!
 </rules>
 
 <task_completion_rules>
@@ -271,6 +272,7 @@ If a UI element is hidden but a matching custom action exists, use the action.
 - Do NOT ask for confirmation of actions the user explicitly requested. If they said "place my order", just do it.
 - If the user's intent is ambiguous — it could mean multiple things or lead to different screens — ask the user to clarify before navigating to the wrong place.
 - NAVIGATION: Always use tap actions to move between screens — tap tab bar buttons, back buttons, and navigation links. This ensures all required route params are passed automatically by the app. The navigate() tool is ONLY for top-level screens that require no params (e.g. Login, Settings, Cart). NEVER call navigate() on screens that require a selection or ID (e.g. DishDetail, SelectCategory, ProfileDetail) — this will crash the app. For those screens, always tap the relevant item in the parent screen.
+- UI SIMPLIFICATION: If you see elements labeled \`aiPriority="low"\` inside a specific \`zoneId=...\`, and the screen looks cluttered relative to the user's immediate goal, use the \`simplify_zone(zoneId)\` tool to hide those low-priority elements. Use \`restore_zone(zoneId)\` to bring them back if needed. The user does NOT need to explicitly ask for this — use your judgment based on their request.
 </rules>
 
 <capability>

package/src/core/types.ts

@@ -22,6 +22,10 @@ export interface InteractiveElement {
   type: ElementType;
   /** Human-readable label (extracted from Text children or accessibilityLabel) */
   label: string;
+  /** Declarative AI priority explicitly set by the developer */
+  aiPriority?: 'high' | 'low';
+  /** The nearest enclosing AIZone ID (if any) */
+  zoneId?: string;
   /** Reference to the Fiber node for execution */
   fiberNode: any;
   /**
@@ -216,6 +220,14 @@ export interface AgentConfig {
    */
   onAskUser?: (question: string) => Promise<string>;
 
+  /**
+   * Called immediately before and after each agent tool execution.
+   * Used by AIAgent to toggle isAgentActing on TelemetryService so that
+   * AI-driven taps are not double-counted as user interactions.
+   * @param active - true = agent is acting, false = agent finished acting
+   */
+  onToolExecute?: (active: boolean) => void;
+
   // ─── Expo Router Support ─────────────────────────────────────────────────
 
   /**
@@ -417,3 +429,51 @@ export interface AIProvider {
     screenshot?: string,
   ): Promise<ProviderResult>;
 }
+
+// ─── AI-Native UI (Pillar B) ───────────────────────────────────────────────────
+
+/**
+ * Configuration for an AIZone declarative boundary.
+ */
+export interface AIZoneConfig {
+  /** Unique identifier for this zone on the current screen */
+  id: string;
+  /** Whether the AI is allowed to use guide_user() to highlight elements here */
+  allowHighlight?: boolean;
+  /** Whether the AI is allowed to inject tooltip hints here */
+  allowInjectHint?: boolean;
+  /** Whether the AI is allowed to hide children marked with aiPriority="low" */
+  allowSimplify?: boolean;
+  /** Whether the AI is allowed to inject custom cards here */
+  allowInjectCard?: boolean;
+  /** 
+   * Whitelist of React component templates the AI can instantiate.
+   * Required if allowInjectCard is true.
+   * IMPORTANT: The AI receives the displayName of these components 
+   * and can only produce props for them. It cannot generate JSX.
+   */
+  templates?: React.ComponentType<any>[];
+}
+
+/**
+ * Internal representation of a registered zone.
+ */
+export interface RegisteredZone extends AIZoneConfig {
+  /** React ref to the zone's container View */
+  ref: React.RefObject<any>;
+}
+
+export interface ProactiveHelpConfig {
+  /** Enable proactive help (default: true) */
+  enabled?: boolean;
+  /** Time in minutes before a subtle pulse (default: 2) */
+  pulseAfterMinutes?: number;
+  /** Time in minutes before showing a help badge (default: 4) */
+  badgeAfterMinutes?: number;
+  /** Default text for the badge (default: "Need help with this screen?") */
+  badgeText?: string;
+  /** If true, dismissing the badge disables proactive help for the rest of the session (default: true) */
+  dismissForSession?: boolean;
+  /** Dynamic context suggestion generator based on current screen */
+  generateSuggestion?: (screenName: string) => string;
+}

package/src/index.ts

@@ -7,6 +7,11 @@
 
 // ─── Components ──────────────────────────────────────────────
 export { AIAgent } from './components/AIAgent';
+export { AIZone } from './components/AIZone';
+// Built-in card templates for AIZone injection
+// Note: displayName is set explicitly on each — required for minification-safe template lookup.
+export { InfoCard } from './components/cards/InfoCard';
+export { ReviewSummary } from './components/cards/ReviewSummary';
 
 // ─── Providers ───────────────────────────────────────────────
 export { GeminiProvider } from './providers/GeminiProvider';
@@ -22,6 +27,10 @@ export { AudioInputService } from './services/AudioInputService';
 export { AudioOutputService } from './services/AudioOutputService';
 export { KnowledgeBaseService } from './services/KnowledgeBaseService';
 
+// ─── Analytics ───────────────────────────────────────────────
+// Requires api.mobileai.dev — hidden until backend is live
+// export { MobileAI } from './services/telemetry';
+
 // ─── Utilities ───────────────────────────────────────────────
 export { logger } from './utils/logger';
 
@@ -50,3 +59,25 @@ export type {
   VoiceServiceCallbacks,
   VoiceStatus,
 } from './services/VoiceService';
+
+// Requires api.mobileai.dev — hidden until backend is live
+// export type {
+//   TelemetryConfig,
+//   TelemetryEvent,
+// } from './services/telemetry';
+
+// ─── Support Mode ────────────────────────────────────────────
+// SupportGreeting, CSATSurvey, buildSupportPrompt work standalone (no backend)
+// createEscalateTool works with provider='custom' (no backend)
+// EscalationSocket and provider='mobileai' require api.mobileai.dev — hidden
+export { SupportGreeting, CSATSurvey, buildSupportPrompt, createEscalateTool } from './support';
+
+export type {
+  SupportModeConfig,
+  QuickReply,
+  EscalationConfig,
+  EscalationContext,
+  CSATConfig,
+  CSATRating,
+  BusinessHoursConfig,
+} from './support';

package/src/services/AudioOutputService.ts

@@ -10,6 +10,7 @@
 
 import { logger } from '../utils/logger';
 import { base64ToFloat32 } from '../utils/audioUtils';
+import { NativeModules } from 'react-native';
 
 // ─── Types ─────────────────────────────────────────────────────
 
@@ -44,6 +45,18 @@ export class AudioOutputService {
     try {
       let audioApi: any;
       try {
+        // Guard: NativeModules.AudioApiModule is only present in dev/prod builds.
+        // In Expo Go it is undefined, and require() throws a native bridge error
+        // that cannot be caught by a standard try/catch.
+        if (!NativeModules.AudioApiModule) {
+          const msg =
+            '[mobileai] react-native-audio-api native module not found. '
+            + 'Voice audio output requires a development build (not Expo Go). '
+            + 'Run: npx expo run:ios';
+          logger.warn('AudioOutput', msg);
+          this.config.onError?.(msg);
+          return false;
+        }
         const audioApiModule = ['react-native', 'audio-api'].join('-');
         audioApi = require(audioApiModule);
       } catch {

package/src/services/flags/FlagService.ts

@@ -0,0 +1,137 @@
+import { logger } from '../../utils/logger';
+import { getDeviceId } from '../telemetry/device';
+
+const LOG_TAG = 'FlagService';
+
+/**
+ * MurmurHash3 (32-bit) implementation
+ */
+function murmurhash3_32_gc(key: string, seed: number = 0): number {
+  let remainder, bytes, h1, h1b, c1, c2, k1, i;
+  
+  remainder = key.length & 3; // key.length % 4
+  bytes = key.length - remainder;
+  h1 = seed;
+  c1 = 0xcc9e2d51;
+  c2 = 0x1b873593;
+  i = 0;
+  
+  while (i < bytes) {
+  	  k1 = 
+  	  	((key.charCodeAt(i) & 0xff)) |
+  	  	((key.charCodeAt(++i) & 0xff) << 8) |
+  	  	((key.charCodeAt(++i) & 0xff) << 16) |
+  	  	((key.charCodeAt(++i) & 0xff) << 24);
+  	  ++i;
+  	  
+  	  k1 = ((((k1 & 0xffff) * c1) + ((((k1 >>> 16) * c1) & 0xffff) << 16))) & 0xffffffff;
+  	  k1 = (k1 << 15) | (k1 >>> 17);
+  	  k1 = ((((k1 & 0xffff) * c2) + ((((k1 >>> 16) * c2) & 0xffff) << 16))) & 0xffffffff;
+  
+  	  h1 ^= k1;
+      h1 = (h1 << 13) | (h1 >>> 19);
+  	  h1b = ((((h1 & 0xffff) * 5) + ((((h1 >>> 16) * 5) & 0xffff) << 16))) & 0xffffffff;
+  	  h1 = (((h1b & 0xffff) + 0x6b64) + ((((h1b >>> 16) + 0xe654) & 0xffff) << 16));
+  }
+  
+  if (remainder >= 1) {
+    k1 = 0;
+    if (remainder >= 3) k1 ^= (key.charCodeAt(i + 2) & 0xff) << 16;
+    if (remainder >= 2) k1 ^= (key.charCodeAt(i + 1) & 0xff) << 8;
+    k1 ^= (key.charCodeAt(i) & 0xff);
+    k1 = (((k1 & 0xffff) * c1) + ((((k1 >>> 16) * c1) & 0xffff) << 16)) & 0xffffffff;
+    k1 = (k1 << 15) | (k1 >>> 17);
+    k1 = (((k1 & 0xffff) * c2) + ((((k1 >>> 16) * c2) & 0xffff) << 16)) & 0xffffffff;
+    h1 ^= k1;
+  }
+  
+  h1 ^= key.length;
+  
+  h1 ^= h1 >>> 16;
+  h1 = (((h1 & 0xffff) * 0x85ebca6b) + ((((h1 >>> 16) * 0x85ebca6b) & 0xffff) << 16)) & 0xffffffff;
+  h1 ^= h1 >>> 13;
+  h1 = ((((h1 & 0xffff) * 0xc2b2ae35) + ((((h1 >>> 16) * 0xc2b2ae35) & 0xffff) << 16))) & 0xffffffff;
+  h1 ^= h1 >>> 16;
+  
+  return h1 >>> 0;
+}
+
+export interface FeatureFlagPayload {
+  key: string;
+  variants: string[];
+  rollout: number[];
+}
+
+export class FlagService {
+  private assignments: Record<string, string> = {};
+  private fetched: boolean = false;
+
+  constructor(private hostUrl: string) {}
+
+  /**
+   * Fetch feature flags from the dashboard backend
+   */
+  async fetch(analyticsKey: string, userId?: string): Promise<void> {
+    try {
+      // Avoid fetching if already loaded, unless explicitly forced? 
+      // For now, allow refetching just in case.
+      const res = await fetch(`${this.hostUrl}/api/v1/flags/sync?key=${analyticsKey}`);
+      if (!res.ok) {
+        throw new Error(`Failed to fetch flags: ${res.status}`);
+      }
+
+      const data = await res.json();
+      const flags: FeatureFlagPayload[] = data.flags || [];
+      
+      this.assignAll(flags, userId);
+      this.fetched = true;
+      logger.info(LOG_TAG, `Fetched ${flags.length} flags`);
+    } catch (err: any) {
+      logger.warn(LOG_TAG, `Could not sync feature flags: ${err.message}`);
+    }
+  }
+
+  /**
+   * Deterministically assign a variant using murmurhash.
+   */
+  private assignVariant(userIdentifier: string, flagKey: string, variants: string[], rollout: number[]): string {
+    const hash = murmurhash3_32_gc(`${userIdentifier}_${flagKey}`) % 100;
+    let cumulative = 0;
+    
+    for (let i = 0; i < rollout.length; i++) {
+      cumulative += rollout[i]!;
+      if (hash < cumulative) {
+        return variants[i]!;
+      }
+    }
+    
+    // Fallback if rollout doesn't equal exactly 100 or edge case
+    return variants[0]!
+  }
+
+  private assignAll(flags: FeatureFlagPayload[], userId?: string) {
+    const identifier = userId || getDeviceId();
+    
+    const newAssignments: Record<string, string> = {};
+    for (const flag of flags) {
+      if (flag.variants.length > 0 && flag.rollout.length === flag.variants.length) {
+        newAssignments[flag.key] = this.assignVariant(identifier, flag.key, flag.variants, flag.rollout);
+      }
+    }
+    
+    this.assignments = newAssignments;
+  }
+
+  /** Get a specific flag value */
+  getFlag(key: string, defaultValue?: string): string {
+    if (!this.fetched) {
+      logger.debug(LOG_TAG, `getFlag("${key}") called before flags were fetched. Returning default.`);
+    }
+    return this.assignments[key] ?? defaultValue ?? '';
+  }
+
+  /** Get all active assignments for telemetry */
+  getAllFlags(): Record<string, string> {
+    return { ...this.assignments };
+  }
+}