trickle-observe 0.2.61 → 0.2.63

package/dist/metro-transformer.d.ts

@@ -0,0 +1,28 @@
+/**
+ * trickle/metro-transformer — Metro bundler transform for React Native observability.
+ *
+ * Drop-in Metro transformer that instruments React Native components with
+ * trickle's render tracking, useState change tracking, and hook observability —
+ * the same tracking trickle's Vite plugin provides for web React apps.
+ *
+ * Setup in metro.config.js:
+ *
+ *   const { getDefaultConfig } = require('expo/metro-config');
+ *   // or: const { getDefaultConfig } = require('@react-native/metro-config');
+ *
+ *   const config = getDefaultConfig(__dirname);
+ *   config.transformer.babelTransformerPath = require.resolve('trickle-observe/metro-transformer');
+ *   module.exports = config;
+ *
+ * Environment variables:
+ *   TRICKLE_BACKEND_URL   — URL of your trickle backend (default: http://localhost:4888)
+ *                           For real device: use your machine's LAN IP, e.g. http://192.168.1.5:4888
+ *   TRICKLE_DEBUG         — Set to "1" for debug logging
+ */
+interface MetroTransformArgs {
+    src: string;
+    filename: string;
+    options: Record<string, unknown>;
+}
+export declare function transform({ src, filename, options }: MetroTransformArgs): Promise<any>;
+export {};

package/dist/metro-transformer.js

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * trickle/metro-transformer — Metro bundler transform for React Native observability.
+ *
+ * Drop-in Metro transformer that instruments React Native components with
+ * trickle's render tracking, useState change tracking, and hook observability —
+ * the same tracking trickle's Vite plugin provides for web React apps.
+ *
+ * Setup in metro.config.js:
+ *
+ *   const { getDefaultConfig } = require('expo/metro-config');
+ *   // or: const { getDefaultConfig } = require('@react-native/metro-config');
+ *
+ *   const config = getDefaultConfig(__dirname);
+ *   config.transformer.babelTransformerPath = require.resolve('trickle-observe/metro-transformer');
+ *   module.exports = config;
+ *
+ * Environment variables:
+ *   TRICKLE_BACKEND_URL   — URL of your trickle backend (default: http://localhost:4888)
+ *                           For real device: use your machine's LAN IP, e.g. http://192.168.1.5:4888
+ *   TRICKLE_DEBUG         — Set to "1" for debug logging
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transform = transform;
+const path_1 = __importDefault(require("path"));
+const vite_plugin_1 = require("./vite-plugin");
+// The upstream Babel transformer — try Expo first, fall back to bare RN
+function getUpstreamTransformer() {
+    const candidates = [
+        '@expo/metro-config/babel-transformer',
+        'metro-react-native-babel-transformer',
+    ];
+    for (const candidate of candidates) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            return require(candidate);
+        }
+        catch {
+            // not installed, try next
+        }
+    }
+    throw new Error('[trickle/metro-transformer] Could not find a Metro Babel transformer. ' +
+        'Install either @expo/metro-config or metro-react-native-babel-transformer.');
+}
+const backendUrl = process.env.TRICKLE_BACKEND_URL ?? 'http://localhost:4888';
+const debug = process.env.TRICKLE_DEBUG === '1';
+async function transform({ src, filename, options }) {
+    const upstreamTransformer = getUpstreamTransformer();
+    // Only instrument React Native component files
+    const ext = path_1.default.extname(filename).toLowerCase();
+    const isReactFile = ext === '.tsx' || ext === '.jsx';
+    const isJsFile = ext === '.ts' || ext === '.js';
+    if ((isReactFile || isJsFile) && !filename.includes('node_modules') && !filename.includes('trickle-observe')) {
+        const moduleName = path_1.default.basename(filename).replace(/\.[jt]sx?$/, '');
+        const transformed = (0, vite_plugin_1.transformEsmSource)(src, filename, moduleName, backendUrl, debug, false);
+        if (transformed !== src) {
+            if (debug) {
+                console.log(`[trickle/metro] Instrumented ${filename}`);
+            }
+            return upstreamTransformer.transform({ src: transformed, filename, options });
+        }
+    }
+    return upstreamTransformer.transform({ src, filename, options });
+}

package/dist/vite-plugin.d.ts

@@ -37,4 +37,5 @@ export declare function tricklePlugin(options?: TricklePluginOptions): {
         map: null;
     } | null;
 };
+export declare function transformEsmSource(source: string, filename: string, moduleName: string, backendUrl: string, debug: boolean, traceVars: boolean, originalSource?: string | null): string;
 export default tricklePlugin;

package/dist/vite-plugin.js

@@ -23,6 +23,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.tricklePlugin = tricklePlugin;
+exports.transformEsmSource = transformEsmSource;
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 function tricklePlugin(options = {}) {
@@ -496,8 +497,8 @@ function escapeRegexStr(str) {
 function transformEsmSource(source, filename, moduleName, backendUrl, debug, traceVars, originalSource) {
     // Detect React files for component render tracking
     const isReactFile = /\.(tsx|jsx)$/.test(filename);
-    // Match top-level and nested function declarations (including async, export)
-    const funcRegex = /^[ \t]*(?:export\s+)?(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm;
+    // Match top-level and nested function declarations (including async, export, export default)
+    const funcRegex = /^[ \t]*(?:export\s+(?:default\s+)?)?(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm;
     const funcInsertions = [];
     // Body insertions: insert at start of function body (for React render tracking)
     // propsExpr: JS expression to evaluate as the props object at render time
@@ -538,7 +539,8 @@ function transformEsmSource(source, filename, moduleName, backendUrl, debug, tra
         }
     }
     // Also match arrow functions assigned to const/let/var
-    const arrowRegex = /^[ \t]*(?:export\s+)?(?:const|let|var)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*=\s*(?:async\s+)?(?:\([^)]*\)|[a-zA-Z_$][a-zA-Z0-9_$]*)\s*(?::\s*[^=]+?)?\s*=>\s*\{/gm;
+    // Handles: const X = () => {}, const X: React.FC = () => {}, const X: React.FC<Props> = ({ a }) => {}
+    const arrowRegex = /^[ \t]*(?:export\s+)?(?:const|let|var)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)(?:\s*:\s*[^=]+?)?\s*=\s*(?:async\s+)?(?:\([^)]*\)|[a-zA-Z_$][a-zA-Z0-9_$]*)\s*(?::\s*[^=]+?)?\s*=>\s*\{/gm;
     while ((match = arrowRegex.exec(source)) !== null) {
         const name = match[1];
         const openBrace = source.indexOf('{', match.index + match[0].length - 1);
@@ -612,6 +614,89 @@ function transformEsmSource(source, filename, moduleName, backendUrl, debug, tra
             bodyInsertions.push({ position: openBrace + 1, name, lineNo, propsExpr });
         }
     }
+    // Match React.memo() and React.forwardRef() wrapped components
+    // Pattern: const Name = (React.)?memo(  or  const Name = (React.)?forwardRef<T,P>(
+    // Then scan forward to find the inner arrow => { body
+    if (isReactFile) {
+        const memoRefRegex = /^[ \t]*(?:export\s+)?(?:const|let|var)\s+([A-Z][a-zA-Z0-9_$]*)(?:\s*:\s*[^=]+?)?\s*=\s*(?:React\.)?(?:memo|forwardRef)\s*(?:<[^(]*>)?\s*\(/gm;
+        let memoMatch;
+        while ((memoMatch = memoRefRegex.exec(source)) !== null) {
+            const name = memoMatch[1];
+            // Position after the opening `(` of memo/forwardRef call
+            const afterMemoOpen = memoMatch.index + memoMatch[0].length;
+            // Scan forward to find `=> {` — the arrow body of the inner function.
+            // We need to skip over the inner function's parameter list (which may contain nested parens).
+            // Strategy: find the next `=>` that is followed by optional whitespace and `{`.
+            let pos = afterMemoOpen;
+            let arrowPos = -1;
+            let parenDepth = 0;
+            while (pos < source.length - 1) {
+                const ch = source[pos];
+                if (ch === '(')
+                    parenDepth++;
+                else if (ch === ')')
+                    parenDepth--;
+                else if (ch === '=' && source[pos + 1] === '>' && parenDepth <= 0) {
+                    arrowPos = pos;
+                    break;
+                }
+                pos++;
+            }
+            if (arrowPos === -1)
+                continue;
+            // Skip `=>` and whitespace to find `{`
+            let bracePos = arrowPos + 2;
+            while (bracePos < source.length && /[\s]/.test(source[bracePos]))
+                bracePos++;
+            if (source[bracePos] !== '{')
+                continue;
+            const openBrace = bracePos;
+            const closeBrace = findClosingBrace(source, openBrace);
+            if (closeBrace === -1)
+                continue;
+            // Extract the param list: everything between memo( and arrowPos
+            const innerParamStr = source.slice(afterMemoOpen, arrowPos).trim();
+            // innerParamStr is like `({ item, onSelect })` or `(props, ref)` or `props`
+            let propsExpr = 'undefined';
+            if (innerParamStr.startsWith('(')) {
+                // Peel outer parens
+                const inner = innerParamStr.slice(1, innerParamStr.lastIndexOf(')')).trim();
+                if (inner.startsWith('{')) {
+                    // Find the matching `}` of the destructuring pattern, ignoring any type annotation after it
+                    let depth3 = 0, destructEnd = -1;
+                    for (let i = 0; i < inner.length; i++) {
+                        if (inner[i] === '{')
+                            depth3++;
+                        else if (inner[i] === '}') {
+                            depth3--;
+                            if (depth3 === 0) {
+                                destructEnd = i;
+                                break;
+                            }
+                        }
+                    }
+                    const destructPart = destructEnd !== -1 ? inner.slice(0, destructEnd + 1) : inner;
+                    const fields = extractDestructuredNames(destructPart);
+                    if (fields.length > 0)
+                        propsExpr = `{ ${fields.join(', ')} }`;
+                }
+                else {
+                    const firstParam = inner.split(',')[0].trim().split(':')[0].trim();
+                    if (firstParam)
+                        propsExpr = firstParam;
+                }
+            }
+            else if (innerParamStr && /^[a-zA-Z_$]/.test(innerParamStr)) {
+                propsExpr = innerParamStr.split(/[\s,:(]/)[0];
+            }
+            let lineNo = 1;
+            for (let i = 0; i < memoMatch.index; i++) {
+                if (source[i] === '\n')
+                    lineNo++;
+            }
+            bodyInsertions.push({ position: openBrace + 1, name, lineNo, propsExpr });
+        }
+    }
     const hookInsertions = [];
     if (isReactFile) {
         // Match useEffect(, useMemo(, useCallback( — also handles React.useEffect(, etc.

package/dist-esm/vite-plugin.js

@@ -487,11 +487,11 @@ function findOriginalLineDestructured(origLines, varNames, transformedLine) {
 function escapeRegexStr(str) {
     return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-function transformEsmSource(source, filename, moduleName, backendUrl, debug, traceVars, originalSource) {
+export function transformEsmSource(source, filename, moduleName, backendUrl, debug, traceVars, originalSource) {
     // Detect React files for component render tracking
     const isReactFile = /\.(tsx|jsx)$/.test(filename);
-    // Match top-level and nested function declarations (including async, export)
-    const funcRegex = /^[ \t]*(?:export\s+)?(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm;
+    // Match top-level and nested function declarations (including async, export, export default)
+    const funcRegex = /^[ \t]*(?:export\s+(?:default\s+)?)?(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm;
     const funcInsertions = [];
     // Body insertions: insert at start of function body (for React render tracking)
     // propsExpr: JS expression to evaluate as the props object at render time
@@ -532,7 +532,8 @@ function transformEsmSource(source, filename, moduleName, backendUrl, debug, tra
         }
     }
     // Also match arrow functions assigned to const/let/var
-    const arrowRegex = /^[ \t]*(?:export\s+)?(?:const|let|var)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*=\s*(?:async\s+)?(?:\([^)]*\)|[a-zA-Z_$][a-zA-Z0-9_$]*)\s*(?::\s*[^=]+?)?\s*=>\s*\{/gm;
+    // Handles: const X = () => {}, const X: React.FC = () => {}, const X: React.FC<Props> = ({ a }) => {}
+    const arrowRegex = /^[ \t]*(?:export\s+)?(?:const|let|var)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)(?:\s*:\s*[^=]+?)?\s*=\s*(?:async\s+)?(?:\([^)]*\)|[a-zA-Z_$][a-zA-Z0-9_$]*)\s*(?::\s*[^=]+?)?\s*=>\s*\{/gm;
     while ((match = arrowRegex.exec(source)) !== null) {
         const name = match[1];
         const openBrace = source.indexOf('{', match.index + match[0].length - 1);
@@ -606,6 +607,89 @@ function transformEsmSource(source, filename, moduleName, backendUrl, debug, tra
             bodyInsertions.push({ position: openBrace + 1, name, lineNo, propsExpr });
         }
     }
+    // Match React.memo() and React.forwardRef() wrapped components
+    // Pattern: const Name = (React.)?memo(  or  const Name = (React.)?forwardRef<T,P>(
+    // Then scan forward to find the inner arrow => { body
+    if (isReactFile) {
+        const memoRefRegex = /^[ \t]*(?:export\s+)?(?:const|let|var)\s+([A-Z][a-zA-Z0-9_$]*)(?:\s*:\s*[^=]+?)?\s*=\s*(?:React\.)?(?:memo|forwardRef)\s*(?:<[^(]*>)?\s*\(/gm;
+        let memoMatch;
+        while ((memoMatch = memoRefRegex.exec(source)) !== null) {
+            const name = memoMatch[1];
+            // Position after the opening `(` of memo/forwardRef call
+            const afterMemoOpen = memoMatch.index + memoMatch[0].length;
+            // Scan forward to find `=> {` — the arrow body of the inner function.
+            // We need to skip over the inner function's parameter list (which may contain nested parens).
+            // Strategy: find the next `=>` that is followed by optional whitespace and `{`.
+            let pos = afterMemoOpen;
+            let arrowPos = -1;
+            let parenDepth = 0;
+            while (pos < source.length - 1) {
+                const ch = source[pos];
+                if (ch === '(')
+                    parenDepth++;
+                else if (ch === ')')
+                    parenDepth--;
+                else if (ch === '=' && source[pos + 1] === '>' && parenDepth <= 0) {
+                    arrowPos = pos;
+                    break;
+                }
+                pos++;
+            }
+            if (arrowPos === -1)
+                continue;
+            // Skip `=>` and whitespace to find `{`
+            let bracePos = arrowPos + 2;
+            while (bracePos < source.length && /[\s]/.test(source[bracePos]))
+                bracePos++;
+            if (source[bracePos] !== '{')
+                continue;
+            const openBrace = bracePos;
+            const closeBrace = findClosingBrace(source, openBrace);
+            if (closeBrace === -1)
+                continue;
+            // Extract the param list: everything between memo( and arrowPos
+            const innerParamStr = source.slice(afterMemoOpen, arrowPos).trim();
+            // innerParamStr is like `({ item, onSelect })` or `(props, ref)` or `props`
+            let propsExpr = 'undefined';
+            if (innerParamStr.startsWith('(')) {
+                // Peel outer parens
+                const inner = innerParamStr.slice(1, innerParamStr.lastIndexOf(')')).trim();
+                if (inner.startsWith('{')) {
+                    // Find the matching `}` of the destructuring pattern, ignoring any type annotation after it
+                    let depth3 = 0, destructEnd = -1;
+                    for (let i = 0; i < inner.length; i++) {
+                        if (inner[i] === '{')
+                            depth3++;
+                        else if (inner[i] === '}') {
+                            depth3--;
+                            if (depth3 === 0) {
+                                destructEnd = i;
+                                break;
+                            }
+                        }
+                    }
+                    const destructPart = destructEnd !== -1 ? inner.slice(0, destructEnd + 1) : inner;
+                    const fields = extractDestructuredNames(destructPart);
+                    if (fields.length > 0)
+                        propsExpr = `{ ${fields.join(', ')} }`;
+                }
+                else {
+                    const firstParam = inner.split(',')[0].trim().split(':')[0].trim();
+                    if (firstParam)
+                        propsExpr = firstParam;
+                }
+            }
+            else if (innerParamStr && /^[a-zA-Z_$]/.test(innerParamStr)) {
+                propsExpr = innerParamStr.split(/[\s,:(]/)[0];
+            }
+            let lineNo = 1;
+            for (let i = 0; i < memoMatch.index; i++) {
+                if (source[i] === '\n')
+                    lineNo++;
+            }
+            bodyInsertions.push({ position: openBrace + 1, name, lineNo, propsExpr });
+        }
+    }
     const hookInsertions = [];
     if (isReactFile) {
         // Match useEffect(, useMemo(, useCallback( — also handles React.useEffect(, etc.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trickle-observe",
-  "version": "0.2.61",
+  "version": "0.2.63",
   "description": "Runtime type observability for JavaScript applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,11 +17,12 @@
       "require": "./dist/vite-plugin.js"
     },
     "./trace-var": "./dist/trace-var.js",
-    "./lambda": "./dist/lambda.js"
+    "./lambda": "./dist/lambda.js",
+    "./metro-transformer": "./dist/metro-transformer.js"
   },
   "scripts": {
     "build": "tsc && tsc -p tsconfig.esm.json",
-    "test": "npm run build && node --experimental-strip-types --test src/vite-plugin.test.ts src/lambda.test.ts",
+    "test": "npm run build && node --experimental-strip-types --test src/vite-plugin.test.ts src/lambda.test.ts src/metro-transformer.test.ts",
     "prepublishOnly": "npm run build"
   },
   "optionalDependencies": {

package/src/metro-transformer.test.ts

@@ -0,0 +1,148 @@
+/**
+ * Unit tests for the Metro transformer (React Native observability).
+ *
+ * Tests the transformation logic independently — without needing a real Metro
+ * bundler or Babel pipeline. We test that transformEsmSource is applied correctly
+ * to React Native component source files.
+ *
+ * Run with: node --experimental-strip-types --test src/metro-transformer.test.ts
+ */
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { transformEsmSource } from '../dist/vite-plugin.js';
+
+const BACKEND_URL = 'http://localhost:4888';
+
+// Helper: transform as if coming from a .tsx React Native file
+function transformRNTsx(code: string, filename = '/app/components/MyComponent.tsx'): string {
+  return transformEsmSource(code, filename, 'MyComponent', BACKEND_URL, false, false);
+}
+
+// Helper: transform as if coming from a .ts utility file
+function transformRNTs(code: string, filename = '/app/utils/helper.ts'): string {
+  return transformEsmSource(code, filename, 'helper', BACKEND_URL, false, false);
+}
+
+// ── Metro transformer: React component detection ──────────────────────────────
+
+describe('Metro transformer: React component detection', () => {
+  it('instruments uppercase components in .tsx files', () => {
+    const code = `function OrderCard({ order }) { return null; }`;
+    const out = transformRNTsx(code);
+    assert.notEqual(out, code, 'should transform');
+    assert.ok(out.includes('__trickle_rc'), 'should inject render tracker');
+  });
+
+  it('does not inject render tracker for .ts utility files', () => {
+    const code = `function formatPrice(amount) { return '$' + amount; }`;
+    const out = transformRNTs(code);
+    assert.ok(!out.includes('__trickle_rc'), 'should not inject render tracker in .ts files');
+  });
+
+  it('instruments export default function components (common React Native screen pattern)', () => {
+    const code = `export default function HomeScreen() { return null; }`;
+    const out = transformRNTsx(code);
+    assert.ok(out.includes('__trickle_rc'), 'should inject render tracker for export default function');
+  });
+
+  it('does not instrument lowercase utility functions as components', () => {
+    const code = `function formatOrder(order) { return order.id; }`;
+    const out = transformRNTsx(code);
+    if (out !== code) {
+      assert.ok(!out.includes('__trickle_rc'), 'lowercase function should not be tracked as component');
+    }
+  });
+});
+
+// ── Metro transformer: useState tracking ─────────────────────────────────────
+
+describe('Metro transformer: useState tracking in React Native', () => {
+  it('tracks useState in a React Native functional component', () => {
+    const code = [
+      `import React, { useState } from 'react';`,
+      `function Counter() {`,
+      `  const [count, setCount] = useState(0);`,
+      `  return null;`,
+      `}`,
+    ].join('\n');
+    const out = transformRNTsx(code);
+    assert.ok(out.includes('__trickle_ss'), 'should inject state setter wrapper');
+    assert.ok(out.includes('__trickle_s_setCount'), 'should rename original setter');
+    assert.ok(out.includes('"count"'), 'should include state variable name');
+  });
+
+  it('tracks multiple useState calls in a React Native screen', () => {
+    const code = [
+      `function CheckoutScreen() {`,
+      `  const [items, setItems] = useState([]);`,
+      `  const [total, setTotal] = useState(0);`,
+      `  const [loading, setLoading] = useState(false);`,
+      `  return null;`,
+      `}`,
+    ].join('\n');
+    const out = transformRNTsx(code);
+    const count = (out.match(/const \w+=__trickle_ss/g) || []).length;
+    assert.equal(count, 3, 'should wrap all 3 useState setters');
+  });
+
+  it('handles TypeScript typed useState in React Native', () => {
+    const code = [
+      `function ProfileScreen() {`,
+      `  const [user, setUser] = useState<User | null>(null);`,
+      `  return null;`,
+      `}`,
+    ].join('\n');
+    const out = transformRNTsx(code);
+    assert.ok(out.includes('__trickle_ss'), 'should track typed useState');
+    assert.ok(out.includes('"user"'), 'should include state name');
+  });
+});
+
+// ── Metro transformer: hook observability ────────────────────────────────────
+
+describe('Metro transformer: hook observability in React Native', () => {
+  it('wraps useEffect in a React Native component', () => {
+    const code = [
+      `function DataScreen() {`,
+      `  useEffect(() => {`,
+      `    fetchData();`,
+      `  }, []);`,
+      `  return null;`,
+      `}`,
+    ].join('\n');
+    const out = transformRNTsx(code);
+    assert.ok(out.includes('__trickle_hw'), 'should inject hook wrapper for useEffect');
+    assert.ok(out.includes('"useEffect"'), 'should record hook name');
+  });
+
+  it('wraps useCallback in a React Native component', () => {
+    const code = [
+      `function ListScreen() {`,
+      `  const handlePress = useCallback(() => {`,
+      `    navigate('Detail');`,
+      `  }, []);`,
+      `  return null;`,
+      `}`,
+    ].join('\n');
+    const out = transformRNTsx(code);
+    assert.ok(out.includes('__trickle_hw'), 'should inject hook wrapper for useCallback');
+    assert.ok(out.includes('"useCallback"'), 'should record hook name');
+  });
+});
+
+// ── Metro transformer: source unchanged for non-RN files ─────────────────────
+
+describe('Metro transformer: passthrough for non-component files', () => {
+  it('does not modify a plain TypeScript utility file', () => {
+    const code = `export function add(a: number, b: number): number { return a + b; }`;
+    const out = transformRNTs(code);
+    // .ts files should not get __trickle_rc (no React components)
+    assert.ok(!out.includes('__trickle_rc'), 'should not inject React tracking in .ts files');
+  });
+
+  it('does not inject useState tracking in .ts files', () => {
+    const code = `function helper() {\n  const [x, setX] = useState(0);\n  return x;\n}`;
+    const out = transformRNTs(code);
+    assert.ok(!out.includes('__trickle_ss'), 'should not track useState in .ts files');
+  });
+});

package/src/metro-transformer.ts

@@ -0,0 +1,75 @@
+/**
+ * trickle/metro-transformer — Metro bundler transform for React Native observability.
+ *
+ * Drop-in Metro transformer that instruments React Native components with
+ * trickle's render tracking, useState change tracking, and hook observability —
+ * the same tracking trickle's Vite plugin provides for web React apps.
+ *
+ * Setup in metro.config.js:
+ *
+ *   const { getDefaultConfig } = require('expo/metro-config');
+ *   // or: const { getDefaultConfig } = require('@react-native/metro-config');
+ *
+ *   const config = getDefaultConfig(__dirname);
+ *   config.transformer.babelTransformerPath = require.resolve('trickle-observe/metro-transformer');
+ *   module.exports = config;
+ *
+ * Environment variables:
+ *   TRICKLE_BACKEND_URL   — URL of your trickle backend (default: http://localhost:4888)
+ *                           For real device: use your machine's LAN IP, e.g. http://192.168.1.5:4888
+ *   TRICKLE_DEBUG         — Set to "1" for debug logging
+ */
+
+import path from 'path';
+import { transformEsmSource } from './vite-plugin';
+
+// The upstream Babel transformer — try Expo first, fall back to bare RN
+function getUpstreamTransformer() {
+  const candidates = [
+    '@expo/metro-config/babel-transformer',
+    'metro-react-native-babel-transformer',
+  ];
+  for (const candidate of candidates) {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      return require(candidate);
+    } catch {
+      // not installed, try next
+    }
+  }
+  throw new Error(
+    '[trickle/metro-transformer] Could not find a Metro Babel transformer. ' +
+    'Install either @expo/metro-config or metro-react-native-babel-transformer.',
+  );
+}
+
+interface MetroTransformArgs {
+  src: string;
+  filename: string;
+  options: Record<string, unknown>;
+}
+
+const backendUrl = process.env.TRICKLE_BACKEND_URL ?? 'http://localhost:4888';
+const debug = process.env.TRICKLE_DEBUG === '1';
+
+export async function transform({ src, filename, options }: MetroTransformArgs) {
+  const upstreamTransformer = getUpstreamTransformer();
+
+  // Only instrument React Native component files
+  const ext = path.extname(filename).toLowerCase();
+  const isReactFile = ext === '.tsx' || ext === '.jsx';
+  const isJsFile = ext === '.ts' || ext === '.js';
+
+  if ((isReactFile || isJsFile) && !filename.includes('node_modules') && !filename.includes('trickle-observe')) {
+    const moduleName = path.basename(filename).replace(/\.[jt]sx?$/, '');
+    const transformed = transformEsmSource(src, filename, moduleName, backendUrl, debug, false);
+    if (transformed !== src) {
+      if (debug) {
+        console.log(`[trickle/metro] Instrumented ${filename}`);
+      }
+      return upstreamTransformer.transform({ src: transformed, filename, options });
+    }
+  }
+
+  return upstreamTransformer.transform({ src, filename, options });
+}

package/src/vite-plugin.test.ts

@@ -40,6 +40,48 @@ describe('React file detection', () => {
     }
   });
 
+  it('tracks export default function components', () => {
+    const code = `export default function HomeScreen() { return null; }`;
+    const out = transformTsx(code);
+    assert.ok(out, 'should transform');
+    assert.ok(out!.includes('__trickle_rc'), 'export default function should be tracked as component');
+  });
+
+  it('tracks React.FC typed arrow components', () => {
+    const code = `const UserCard: React.FC = () => { return null; }`;
+    const out = transformTsx(code);
+    assert.ok(out, 'should transform');
+    assert.ok(out!.includes('__trickle_rc'), 'React.FC arrow should be tracked');
+  });
+
+  it('tracks React.FC<Props> typed arrow components', () => {
+    const code = `const UserCard: React.FC<Props> = ({ name }) => { return null; }`;
+    const out = transformTsx(code);
+    assert.ok(out, 'should transform');
+    assert.ok(out!.includes('__trickle_rc'), 'React.FC<Props> arrow should be tracked');
+  });
+
+  it('tracks React.memo() wrapped components', () => {
+    const code = `const UserCard = React.memo(() => { return null; });`;
+    const out = transformTsx(code);
+    assert.ok(out, 'should transform');
+    assert.ok(out!.includes('__trickle_rc'), 'React.memo component should be tracked');
+  });
+
+  it('tracks memo() wrapped components with destructured props', () => {
+    const code = `const UserCard = memo(({ name, age }) => { return null; });`;
+    const out = transformTsx(code);
+    assert.ok(out, 'should transform');
+    assert.ok(out!.includes('__trickle_rc'), 'memo() component should be tracked');
+  });
+
+  it('tracks React.forwardRef() wrapped components', () => {
+    const code = `const UserCard = React.forwardRef<View, Props>((props, ref) => { return null; });`;
+    const out = transformTsx(code);
+    assert.ok(out, 'should transform');
+    assert.ok(out!.includes('__trickle_rc'), 'forwardRef component should be tracked');
+  });
+
   it('does not track lowercase functions as components', () => {
     const code = `function helper(x) { return x + 1; }`;
     const out = transformTsx(code);

package/src/vite-plugin.ts

@@ -481,7 +481,7 @@ function escapeRegexStr(str: string): string {
   return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
-function transformEsmSource(
+export function transformEsmSource(
   source: string,
   filename: string,
   moduleName: string,
@@ -493,8 +493,8 @@ function transformEsmSource(
   // Detect React files for component render tracking
   const isReactFile = /\.(tsx|jsx)$/.test(filename);
 
-  // Match top-level and nested function declarations (including async, export)
-  const funcRegex = /^[ \t]*(?:export\s+)?(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm;
+  // Match top-level and nested function declarations (including async, export, export default)
+  const funcRegex = /^[ \t]*(?:export\s+(?:default\s+)?)?(?:async\s+)?function\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*\(/gm;
   const funcInsertions: Array<{ position: number; name: string; paramNames: string[] }> = [];
   // Body insertions: insert at start of function body (for React render tracking)
   // propsExpr: JS expression to evaluate as the props object at render time
@@ -537,7 +537,8 @@ function transformEsmSource(
   }
 
   // Also match arrow functions assigned to const/let/var
-  const arrowRegex = /^[ \t]*(?:export\s+)?(?:const|let|var)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)\s*=\s*(?:async\s+)?(?:\([^)]*\)|[a-zA-Z_$][a-zA-Z0-9_$]*)\s*(?::\s*[^=]+?)?\s*=>\s*\{/gm;
+  // Handles: const X = () => {}, const X: React.FC = () => {}, const X: React.FC<Props> = ({ a }) => {}
+  const arrowRegex = /^[ \t]*(?:export\s+)?(?:const|let|var)\s+([a-zA-Z_$][a-zA-Z0-9_$]*)(?:\s*:\s*[^=]+?)?\s*=\s*(?:async\s+)?(?:\([^)]*\)|[a-zA-Z_$][a-zA-Z0-9_$]*)\s*(?::\s*[^=]+?)?\s*=>\s*\{/gm;
 
   while ((match = arrowRegex.exec(source)) !== null) {
     const name = match[1];
@@ -607,6 +608,78 @@ function transformEsmSource(
 
 
 
+  // Match React.memo() and React.forwardRef() wrapped components
+  // Pattern: const Name = (React.)?memo(  or  const Name = (React.)?forwardRef<T,P>(
+  // Then scan forward to find the inner arrow => { body
+  if (isReactFile) {
+    const memoRefRegex = /^[ \t]*(?:export\s+)?(?:const|let|var)\s+([A-Z][a-zA-Z0-9_$]*)(?:\s*:\s*[^=]+?)?\s*=\s*(?:React\.)?(?:memo|forwardRef)\s*(?:<[^(]*>)?\s*\(/gm;
+    let memoMatch;
+    while ((memoMatch = memoRefRegex.exec(source)) !== null) {
+      const name = memoMatch[1];
+      // Position after the opening `(` of memo/forwardRef call
+      const afterMemoOpen = memoMatch.index + memoMatch[0].length;
+
+      // Scan forward to find `=> {` — the arrow body of the inner function.
+      // We need to skip over the inner function's parameter list (which may contain nested parens).
+      // Strategy: find the next `=>` that is followed by optional whitespace and `{`.
+      let pos = afterMemoOpen;
+      let arrowPos = -1;
+      let parenDepth = 0;
+      while (pos < source.length - 1) {
+        const ch = source[pos];
+        if (ch === '(') parenDepth++;
+        else if (ch === ')') parenDepth--;
+        else if (ch === '=' && source[pos + 1] === '>' && parenDepth <= 0) {
+          arrowPos = pos;
+          break;
+        }
+        pos++;
+      }
+      if (arrowPos === -1) continue;
+
+      // Skip `=>` and whitespace to find `{`
+      let bracePos = arrowPos + 2;
+      while (bracePos < source.length && /[\s]/.test(source[bracePos])) bracePos++;
+      if (source[bracePos] !== '{') continue;
+      const openBrace = bracePos;
+
+      const closeBrace = findClosingBrace(source, openBrace);
+      if (closeBrace === -1) continue;
+
+      // Extract the param list: everything between memo( and arrowPos
+      const innerParamStr = source.slice(afterMemoOpen, arrowPos).trim();
+      // innerParamStr is like `({ item, onSelect })` or `(props, ref)` or `props`
+      let propsExpr = 'undefined';
+      if (innerParamStr.startsWith('(')) {
+        // Peel outer parens
+        const inner = innerParamStr.slice(1, innerParamStr.lastIndexOf(')')).trim();
+        if (inner.startsWith('{')) {
+          // Find the matching `}` of the destructuring pattern, ignoring any type annotation after it
+          let depth3 = 0, destructEnd = -1;
+          for (let i = 0; i < inner.length; i++) {
+            if (inner[i] === '{') depth3++;
+            else if (inner[i] === '}') { depth3--; if (depth3 === 0) { destructEnd = i; break; } }
+          }
+          const destructPart = destructEnd !== -1 ? inner.slice(0, destructEnd + 1) : inner;
+          const fields = extractDestructuredNames(destructPart);
+          if (fields.length > 0) propsExpr = `{ ${fields.join(', ')} }`;
+        } else {
+          const firstParam = inner.split(',')[0].trim().split(':')[0].trim();
+          if (firstParam) propsExpr = firstParam;
+        }
+      } else if (innerParamStr && /^[a-zA-Z_$]/.test(innerParamStr)) {
+        propsExpr = innerParamStr.split(/[\s,:(]/)[0];
+      }
+
+      let lineNo = 1;
+      for (let i = 0; i < memoMatch.index; i++) {
+        if (source[i] === '\n') lineNo++;
+      }
+
+      bodyInsertions.push({ position: openBrace + 1, name, lineNo, propsExpr });
+    }
+  }
+
   // React hook tracking — wrap the callback arg of useEffect/useMemo/useCallback
   // to count how many times each hook fires (effect ran, memo recomputed, callback invoked).
   // Each hook produces TWO insertions: wrapStart (before callback) and wrapEnd (after callback `}`).