@userflow-tech/react-native 0.1.0 → 0.2.0

package/babel-plugin/index.js

@@ -0,0 +1,862 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = userflowAutoStamp;
+const nodePath = __importStar(require("node:path"));
+/**
+ * @userflow-tech/react-native/babel-plugin — semantic auto-stamp + auto-register (rn-v2).
+ *
+ * Stamps allowlisted host elements with:
+ *   1. Canonical structural path where explicit IDs replace ordinals
+ *   2. Compact hints wire (v1: n/p/ct/…) expanded at runtime
+ *   3. Runtime bag (dynamic ids/labels + inherited `__ufScope` when captured)
+ *   4. Call-site `__ufScope` on first-party custom components
+ *
+ * Full mode (the default) also injects `__userflowAutoAnchor`, a `__ufRef`
+ * helper, ref wrapping, and `__ufScope` capture so scored AUTO matching can
+ * populate the auto-anchor registry. Set `stampOnly: true` to stamp only
+ * `nativeID` and `collapsable` — enough for the fiber scanner, but the
+ * in-app picker and scored AUTO matches stay empty.
+ *
+ * Existing app props are composed, never replaced: `ref` (callback, object,
+ * legacy string, or single `{...props}.ref`), `nativeID`, and `collapsable`
+ * are preserved when the developer already set them.
+ */
+const STRUCTURAL_PATH_MAX_DEPTH = 12;
+const DEFAULT_ALLOWLIST = [
+    'Pressable',
+    'TouchableOpacity',
+    'TouchableHighlight',
+    'TouchableWithoutFeedback',
+    'TouchableNativeFeedback',
+    'View',
+    'Text',
+    'TextInput',
+    'Image',
+];
+const COLLAPSABLE_NAMES = new Set([
+    'Pressable',
+    'TouchableOpacity',
+    'TouchableHighlight',
+    'TouchableWithoutFeedback',
+    'TouchableNativeFeedback',
+    'View',
+    'Text',
+]);
+const MANUAL_ID_ATTRS = ['userflowId', 'testID', 'nativeID'];
+const REF_HELPER = '__ufRef';
+const UFID_PROP = '__ufid';
+const UF_MANUAL_PROP = '__ufManual';
+const UF_SCOPE_PROP = '__ufScope';
+function hashId(input) {
+    let h = 5381;
+    for (let i = 0; i < input.length; i += 1) {
+        h = (h * 33) ^ input.charCodeAt(i);
+    }
+    return (h >>> 0).toString(36);
+}
+function stringLiteralFromJsxAttr(t, attr) {
+    if (!attr?.value)
+        return undefined;
+    if (t.isStringLiteral(attr.value))
+        return attr.value.value;
+    if (t.isJSXExpressionContainer(attr.value) && t.isStringLiteral(attr.value.expression)) {
+        return attr.value.expression.value;
+    }
+    return undefined;
+}
+function expressionFromJsxAttr(t, attr) {
+    if (!attr?.value)
+        return undefined;
+    if (t.isStringLiteral(attr.value))
+        return t.stringLiteral(attr.value.value);
+    if (t.isJSXExpressionContainer(attr.value) && t.isExpression(attr.value.expression)) {
+        return t.cloneNode(attr.value.expression);
+    }
+    return undefined;
+}
+function firstStaticStringInJsx(t, node, depth = 0) {
+    if (!node || depth > 4)
+        return undefined;
+    if (t.isStringLiteral(node)) {
+        const s = node.value.trim();
+        return s || undefined;
+    }
+    if (t.isJSXText(node)) {
+        const s = node.value.replace(/\s+/g, ' ').trim();
+        return s || undefined;
+    }
+    if (t.isJSXExpressionContainer(node) && t.isStringLiteral(node.expression)) {
+        const s = node.expression.value.trim();
+        return s || undefined;
+    }
+    if (t.isJSXFragment(node)) {
+        for (const child of node.children) {
+            const found = firstStaticStringInJsx(t, child, depth + 1);
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    if (t.isJSXElement(node)) {
+        for (const child of node.children) {
+            if (t.isJSXElement(child) || t.isJSXText(child) || t.isJSXExpressionContainer(child)) {
+                const found = firstStaticStringInJsx(t, child, depth + 1);
+                if (found)
+                    return found;
+            }
+        }
+    }
+    return undefined;
+}
+function jsxElementTypeName(t, el) {
+    const n = el.openingElement.name;
+    return t.isJSXIdentifier(n) ? n.name : undefined;
+}
+function directChildShape(t, el) {
+    const name = jsxElementTypeName(t, el);
+    if (!name)
+        return undefined;
+    const nested = el.children.filter((c) => t.isJSXElement(c));
+    const onlyChild = nested.length === 1 ? nested[0] : undefined;
+    if (onlyChild) {
+        const inner = jsxElementTypeName(t, onlyChild);
+        if (inner)
+            return `${name}>${inner}`;
+    }
+    return name;
+}
+function childShapeFromJsx(t, openingPath) {
+    const parent = openingPath.parentPath;
+    if (!parent?.isJSXElement())
+        return undefined;
+    const segments = [];
+    for (const child of parent.node.children) {
+        if (!t.isJSXElement(child))
+            continue;
+        const seg = directChildShape(t, child);
+        if (seg)
+            segments.push(seg);
+    }
+    return segments.length > 0 ? segments.join(',') : undefined;
+}
+function childTextFromJsx(t, openingPath) {
+    const parent = openingPath.parentPath;
+    if (!parent?.isJSXElement())
+        return undefined;
+    return firstStaticStringInJsx(t, parent.node);
+}
+/**
+ * Static intrinsic identity signals — position-independent and present in a
+ * release Hermes bundle (no fiber walk, no `toString`). Read from the stamped
+ * element *and its subtree* because the real icon-button pattern nests the
+ * signal: `<Pressable><Icon name="settings" /></Pressable>` /
+ * `<Pressable><Image source={{ uri: '…' }} /></Pressable>` — mirroring how
+ * `childText` descends to find a label.
+ */
+const INTRINSIC_SCAN_MAX_DEPTH = 4;
+/** Read a string-literal `name` prop off an opening element. */
+function stringNameAttr(t, opening) {
+    const attr = opening.attributes.find((a) => t.isJSXAttribute(a) && t.isJSXIdentifier(a.name) && a.name.name === 'name');
+    return attr ? stringLiteralFromJsxAttr(t, attr) : undefined;
+}
+/** Read a literal image `source` uri (string or `{ uri: '…' }`) off an opening element. */
+function imageSourceUri(t, opening) {
+    const attr = opening.attributes.find((a) => t.isJSXAttribute(a) && t.isJSXIdentifier(a.name) && a.name.name === 'source');
+    if (!attr)
+        return undefined;
+    const literal = stringLiteralFromJsxAttr(t, attr);
+    if (literal)
+        return literal;
+    const value = attr.value;
+    if (!value || !t.isJSXExpressionContainer(value) || !t.isObjectExpression(value.expression)) {
+        return undefined;
+    }
+    for (const prop of value.expression.properties) {
+        if (t.isObjectProperty(prop) &&
+            ((t.isIdentifier(prop.key) && prop.key.name === 'uri') ||
+                (t.isStringLiteral(prop.key) && prop.key.value === 'uri')) &&
+            t.isStringLiteral(prop.value)) {
+            return prop.value.value;
+        }
+    }
+    return undefined;
+}
+/** Depth-first search over the stamped element + its subtree for the first hit of `read`. */
+function scanSubtree(t, openingPath, read) {
+    const root = openingPath.parentPath;
+    if (!root?.isJSXElement())
+        return undefined;
+    const visit = (el, depth) => {
+        const hit = read(el.openingElement);
+        if (hit)
+            return hit;
+        if (depth >= INTRINSIC_SCAN_MAX_DEPTH)
+            return undefined;
+        for (const child of el.children) {
+            if (t.isJSXElement(child)) {
+                const r = visit(child, depth + 1);
+                if (r)
+                    return r;
+            }
+        }
+        return undefined;
+    };
+    return visit(root.node, 0);
+}
+function staticIconName(t, openingPath) {
+    return scanSubtree(t, openingPath, (o) => stringNameAttr(t, o));
+}
+function staticImageUri(t, openingPath) {
+    return scanSubtree(t, openingPath, (o) => imageSourceUri(t, o));
+}
+/**
+ * Normalize static text for use inside a canonical `{text=…}` segment: strip the
+ * path delimiters (` > `, `{`, `}`) and control chars, collapse whitespace, cap
+ * length. Deterministic so record-time and resolve-time paths agree.
+ */
+function pathText(raw) {
+    return raw
+        .replace(/[\r\n\t]+/g, ' ')
+        .replace(/[>{}]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 40);
+}
+/** Leaf kinds whose static text *is* their identity — safe to anchor on `{text=…}`. */
+const TEXT_ANCHOR_KINDS = new Set([
+    'Pressable',
+    'TouchableOpacity',
+    'TouchableHighlight',
+    'TouchableWithoutFeedback',
+    'TouchableNativeFeedback',
+    'Text',
+]);
+/** Canonical segment: ID replaces ordinal when present; static text anchors the leaf. */
+function formatSegment(s) {
+    if (s.userflowId)
+        return `${s.name}{userflowId=${s.userflowId}}`;
+    if (s.testID)
+        return `${s.name}{testID=${s.testID}}`;
+    if (s.nativeID && !s.nativeID.startsWith('uf_'))
+        return `${s.name}{nativeID=${s.nativeID}}`;
+    if (s.key)
+        return `${s.name}{key=${s.key}}`;
+    if (s.childText)
+        return `${s.name}{text=${s.childText}}`;
+    return `${s.name}#${s.ordinal}`;
+}
+function idsFromOpening(t, opening) {
+    const findAttr = (attrName) => opening.attributes.find((a) => t.isJSXAttribute(a) && t.isJSXIdentifier(a.name) && a.name.name === attrName);
+    const userflowId = stringLiteralFromJsxAttr(t, findAttr('userflowId'));
+    const testID = stringLiteralFromJsxAttr(t, findAttr('testID'));
+    let nativeID = stringLiteralFromJsxAttr(t, findAttr('nativeID'));
+    if (nativeID?.startsWith('uf_'))
+        nativeID = undefined;
+    const key = stringLiteralFromJsxAttr(t, findAttr('key'));
+    return {
+        ...(userflowId ? { userflowId } : {}),
+        ...(testID ? { testID } : {}),
+        ...(nativeID ? { nativeID } : {}),
+        ...(key ? { key } : {}),
+    };
+}
+/**
+ * Parent-scoped ordinal: count same-named siblings under the immediate JSX parent.
+ */
+function parentScopedOrdinal(t, openingPath, elementName) {
+    const jsxEl = openingPath.parentPath;
+    if (!jsxEl?.isJSXElement())
+        return { ordinal: 0, siblingIndex: 0 };
+    const container = jsxEl.parentPath;
+    let children = [];
+    if (container?.isJSXElement()) {
+        children = container.node.children;
+    }
+    else if (container?.isJSXFragment()) {
+        children = container.node.children;
+    }
+    else {
+        return { ordinal: 0, siblingIndex: 0 };
+    }
+    let ordinal = 0;
+    let siblingIndex = 0;
+    let seen = 0;
+    for (const child of children) {
+        if (!t.isJSXElement(child))
+            continue;
+        if (child.openingElement === openingPath.node) {
+            siblingIndex = seen;
+            return { ordinal, siblingIndex };
+        }
+        const childName = jsxElementTypeName(t, child);
+        if (childName === elementName)
+            ordinal += 1;
+        seen += 1;
+    }
+    return { ordinal: 0, siblingIndex: 0 };
+}
+/**
+ * Host allowlist elements always participate in the path. First-party custom
+ * components (PascalCase) also participate so siblings under different
+ * `<Section>` / layout wrappers do not collapse to the same `uf_<hash>`.
+ * Skipping them caused AnchorRegistry cache collisions: only one of several
+ * same-path Pressables stayed registered, and taps fell through to the parent View.
+ */
+function shouldIncludeInSemanticPath(name, allowlist) {
+    if (allowlist.includes(name))
+        return true;
+    // PascalCase / uppercase → custom component (same rule as call-site scope).
+    return /^[A-Z]/.test(name);
+}
+function buildSemanticPath(t, openingPath, moduleRel, component, allowlist, ordinals, 
+/**
+ * When false, leaf segments stay on ordinals even if static child text is
+ * present. stampOnly mode needs this: without a scored matcher, two "OK"
+ * buttons under the same parent would otherwise share one `uf_` hash and
+ * resolve as ambiguous.
+ */
+allowTextAnchor = true) {
+    const chain = [];
+    let cur = openingPath;
+    let depth = 0;
+    while (cur && depth < STRUCTURAL_PATH_MAX_DEPTH) {
+        depth += 1;
+        const nameNode = cur.node.name;
+        if (t.isJSXIdentifier(nameNode) && shouldIncludeInSemanticPath(nameNode.name, allowlist)) {
+            // Prefer the pristine-tree ordinal; fall back to a live scan when absent
+            // (e.g. a synthetic node the pre-pass never saw).
+            const { ordinal, siblingIndex } = ordinals?.get(cur.node) ?? parentScopedOrdinal(t, cur, nameNode.name);
+            const ids = idsFromOpening(t, cur.node);
+            // Anchor the leaf (first pushed = innermost) to its static text so its
+            // segment survives sibling inserts/reorders. Only for content leaves
+            // (pressables / Text) whose text *is* their identity — not containers,
+            // where `firstStaticStringInJsx` would greedily grab a descendant's label,
+            // nor ancestors (kept on ordinals; WS3 tolerates ancestor ordinal shifts).
+            const isLeaf = chain.length === 0;
+            let childText;
+            if (allowTextAnchor &&
+                isLeaf &&
+                TEXT_ANCHOR_KINDS.has(nameNode.name) &&
+                !ids.userflowId &&
+                !ids.testID &&
+                !ids.nativeID &&
+                !ids.key) {
+                const raw = childTextFromJsx(t, cur);
+                const cleaned = raw ? pathText(raw) : '';
+                if (cleaned)
+                    childText = cleaned;
+            }
+            chain.push({
+                name: nameNode.name,
+                ordinal,
+                siblingIndex,
+                ...ids,
+                ...(childText ? { childText } : {}),
+            });
+        }
+        const jsxEl = cur.parentPath;
+        if (!jsxEl?.isJSXElement())
+            break;
+        const parent = jsxEl.parentPath;
+        if (parent?.isJSXElement()) {
+            cur = parent.get('openingElement');
+        }
+        else {
+            break;
+        }
+    }
+    chain.reverse();
+    const self = chain[chain.length - 1];
+    const ancestors = chain.slice(0, -1);
+    const segments = chain.map(formatSegment);
+    const path = segments.length === 0
+        ? `${moduleRel}::${component}`
+        : `${moduleRel}::${component} > ${segments.join(' > ')}`;
+    return { path, ancestors, self };
+}
+/**
+ * Compact hints wire format (v1). Runtime expands via `expandBuildTimeHints`.
+ * Single path `p` replaces ufid/structuralPath/templatePath; role/ancestors
+ * are derived at expand time from `kind` + path.
+ */
+function buildCompactHintsObjectExpression(t, fields) {
+    const props = [
+        t.objectProperty(t.identifier('v'), t.numericLiteral(1)),
+        t.objectProperty(t.identifier('n'), t.stringLiteral(fields.nativeId)),
+        t.objectProperty(t.identifier('p'), t.stringLiteral(fields.path)),
+    ];
+    if (fields.childText) {
+        props.push(t.objectProperty(t.identifier('ct'), t.stringLiteral(fields.childText)));
+    }
+    if (fields.childShape) {
+        props.push(t.objectProperty(t.identifier('cs'), t.stringLiteral(fields.childShape)));
+    }
+    if (fields.iconName) {
+        props.push(t.objectProperty(t.identifier('icn'), t.stringLiteral(fields.iconName)));
+    }
+    if (fields.imageSrc) {
+        props.push(t.objectProperty(t.identifier('img'), t.stringLiteral(fields.imageSrc)));
+    }
+    if (fields.ordinal !== undefined && fields.ordinal !== 0) {
+        props.push(t.objectProperty(t.identifier('o'), t.numericLiteral(fields.ordinal)));
+    }
+    if (fields.siblingIndex !== undefined && fields.siblingIndex !== 0) {
+        props.push(t.objectProperty(t.identifier('si'), t.numericLiteral(fields.siblingIndex)));
+    }
+    if (fields.literalTestId) {
+        props.push(t.objectProperty(t.identifier('tid'), t.stringLiteral(fields.literalTestId)));
+    }
+    if (fields.literalUserflowId) {
+        props.push(t.objectProperty(t.identifier('uid'), t.stringLiteral(fields.literalUserflowId)));
+    }
+    if (fields.literalLabel) {
+        props.push(t.objectProperty(t.identifier('lid'), t.stringLiteral(fields.literalLabel)));
+    }
+    return t.objectExpression(props);
+}
+function functionDeclaresIncomingScope(t, fnPath) {
+    if (!fnPath)
+        return false;
+    const body = fnPath.get('body');
+    if (!body.isBlockStatement())
+        return false;
+    return body.node.body.some((s) => t.isVariableDeclaration(s) &&
+        s.declarations.some((d) => t.isIdentifier(d.id) && d.id.name === '__ufIncomingScope'));
+}
+/**
+ * Runtime bag passed to __ufRef. Only emits keys that exist; `scope` only when
+ * the enclosing function captured `__ufIncomingScope`.
+ */
+function buildRuntimeExpr(t, findAttr, includeScope) {
+    const props = [];
+    const pushAttr = (runtimeKey, attrName) => {
+        const expr = expressionFromJsxAttr(t, findAttr(attrName));
+        if (!expr)
+            return;
+        if (attrName === 'nativeID' && t.isStringLiteral(expr) && expr.value.startsWith('uf_'))
+            return;
+        props.push(t.objectProperty(t.identifier(runtimeKey), expr));
+    };
+    pushAttr('userflowId', 'userflowId');
+    pushAttr('testID', 'testID');
+    pushAttr('nativeID', 'nativeID');
+    pushAttr('accessibilityLabel', 'accessibilityLabel');
+    // Dynamic intrinsic identity: icon name (`<Icon name={x}>`) survives reorders.
+    pushAttr('iconName', 'name');
+    if (includeScope) {
+        props.push(t.objectProperty(t.identifier('scope'), t.conditionalExpression(t.binaryExpression('!==', t.unaryExpression('typeof', t.identifier('__ufIncomingScope')), t.stringLiteral('undefined')), t.identifier('__ufIncomingScope'), t.identifier('undefined'))));
+    }
+    return t.objectExpression(props);
+}
+function isStampOnly(opts) {
+    return opts.stampOnly === true;
+}
+function enclosingComponentName(t, openingPath, filename) {
+    let fn = openingPath.getFunctionParent();
+    let sawDefaultExport = false;
+    while (fn) {
+        const node = fn.node;
+        if ((t.isFunctionDeclaration(node) || t.isFunctionExpression(node)) && node.id?.name) {
+            return node.id.name;
+        }
+        if (t.isClassMethod(node) || t.isClassPrivateMethod(node)) {
+            const cls = fn.findParent((p) => t.isClassDeclaration(p.node) || t.isClassExpression(p.node));
+            const clsNode = cls?.node;
+            if (clsNode?.id?.name)
+                return clsNode.id.name;
+        }
+        if (t.isObjectMethod(node) && t.isIdentifier(node.key)) {
+            return node.key.name;
+        }
+        const declarator = fn.findParent((p) => t.isVariableDeclarator(p.node));
+        const declId = declarator?.node?.id;
+        if (declId && t.isIdentifier(declId)) {
+            return declId.name;
+        }
+        if (t.isExportDefaultDeclaration(fn.parentPath?.node)) {
+            sawDefaultExport = true;
+        }
+        fn = fn.getFunctionParent();
+    }
+    if (sawDefaultExport)
+        return 'default';
+    const base = nodePath.basename(filename);
+    return base.replace(/\.[^.]+$/, '') || 'Module';
+}
+function isCustomComponentName(name, allowlist) {
+    if (allowlist.includes(name))
+        return false;
+    // PascalCase / uppercase start → custom component
+    return /^[A-Z]/.test(name);
+}
+function formatCallSiteScope(moduleRel, component, childName, ordinal, ids) {
+    let seg = childName;
+    if (ids.userflowId)
+        seg = `${childName}{userflowId=${ids.userflowId}}`;
+    else if (ids.testID)
+        seg = `${childName}{testID=${ids.testID}}`;
+    else if (ids.key)
+        seg = `${childName}{key=${ids.key}}`;
+    else
+        seg = `${childName}#${ordinal}`;
+    return `${moduleRel}::${component} > ${seg}`;
+}
+/**
+ * Inject `const __ufIncomingScope = props?.__ufScope` at the start of a
+ * function component that has a `props` param (or first param).
+ */
+function ensureScopeCapture(t, fnPath) {
+    const body = fnPath.get('body');
+    if (!body.isBlockStatement())
+        return;
+    const already = body.node.body.some((s) => t.isVariableDeclaration(s) &&
+        s.declarations.some((d) => t.isIdentifier(d.id) && d.id.name === '__ufIncomingScope'));
+    if (already)
+        return;
+    const params = fnPath.node.params;
+    if (params.length === 0)
+        return;
+    const first = params[0];
+    let propsAccess;
+    if (t.isIdentifier(first)) {
+        // Optional: helpers like `envelope(fp)` and type predicates also match
+        // `Function` enter. A missing first arg must not throw at module init.
+        propsAccess = t.optionalMemberExpression(first, t.identifier(UF_SCOPE_PROP), false, true);
+    }
+    else if (t.isObjectPattern(first)) {
+        // Look for __ufScope in pattern or add member via rest — skip if complex
+        const hasScope = first.properties.some((p) => t.isObjectProperty(p) &&
+            ((t.isIdentifier(p.key) && p.key.name === UF_SCOPE_PROP) ||
+                (t.isStringLiteral(p.key) && p.key.value === UF_SCOPE_PROP)));
+        if (hasScope) {
+            propsAccess = t.identifier(UF_SCOPE_PROP);
+        }
+        else {
+            // Inject __ufScope into the pattern
+            first.properties.unshift(t.objectProperty(t.identifier(UF_SCOPE_PROP), t.identifier('__ufScopeProp'), false, true));
+            propsAccess = t.identifier('__ufScopeProp');
+        }
+    }
+    else {
+        return;
+    }
+    body.unshiftContainer('body', t.variableDeclaration('var', [
+        t.variableDeclarator(t.identifier('__ufIncomingScope'), propsAccess),
+    ]));
+}
+function userflowAutoStamp(api) {
+    const t = api.types;
+    const isProduction = (typeof api.env === 'function' && api.env('production')) ||
+        process.env['NODE_ENV'] === 'production';
+    return {
+        name: '@userflow-tech/react-native/babel-plugin',
+        pre() {
+            this.ufCallSiteCounters = new Map();
+        },
+        visitor: {
+            Program: {
+                enter(programPath, state) {
+                    // Precompute parent-scoped ordinals on the still-pristine JSX tree.
+                    // Running here (plugin Program.enter fires before preset-react) means
+                    // no `<El>` has been rewritten to `_jsx(El, …)` yet, so sibling counts
+                    // are accurate. Reading them lazily in the main visitor would instead
+                    // race the JSX transform and mis-count every element as `#0`.
+                    const ordinals = (state.ufOrdinals = new WeakMap());
+                    programPath.traverse({
+                        JSXOpeningElement(p) {
+                            const nameNode = p.node.name;
+                            if (!t.isJSXIdentifier(nameNode))
+                                return;
+                            ordinals.set(p.node, parentScopedOrdinal(t, p, nameNode.name));
+                        },
+                    });
+                },
+                exit(programPath, state) {
+                    if (!state.ufStamped)
+                        return;
+                    const opts = (state.opts ?? {});
+                    // stampOnly never wraps refs, so there is nothing to import or helper.
+                    if (isStampOnly(opts))
+                        return;
+                    // Bind the runtime installer into every stamped module so production
+                    // tree-shaking cannot drop `globalThis.__userflowAutoAnchor` when the
+                    // app never names the export. Falls back to globalThis for tests /
+                    // older SDK versions.
+                    const importName = '__userflowAutoAnchor';
+                    const packageName = '@userflow-tech/react-native';
+                    let hasImport = false;
+                    for (const stmt of programPath.node.body) {
+                        if (!t.isImportDeclaration(stmt))
+                            continue;
+                        if (stmt.source.value !== packageName)
+                            continue;
+                        const already = stmt.specifiers.some((s) => t.isImportSpecifier(s) &&
+                            t.isIdentifier(s.imported) &&
+                            s.imported.name === importName);
+                        if (!already) {
+                            stmt.specifiers.push(t.importSpecifier(t.identifier(importName), t.identifier(importName)));
+                        }
+                        hasImport = true;
+                        break;
+                    }
+                    if (!hasImport) {
+                        programPath.unshiftContainer('body', t.importDeclaration([t.importSpecifier(t.identifier(importName), t.identifier(importName))], t.stringLiteral(packageName)));
+                    }
+                    const helper = api.template.statement(`
+            function ${REF_HELPER}(id, hints, userRef, kind, runtime) {
+              var f = typeof ${importName} === "function"
+                ? ${importName}
+                : globalThis.__userflowAutoAnchor;
+              var resolved = (id != null && id !== "") ? id : (hints && (hints.n || hints.nativeId));
+              return f ? f(resolved, hints, userRef, kind, runtime) : userRef;
+            }
+          `)();
+                    // Place helper after imports (unshift would put it above the import).
+                    const body = programPath.get('body');
+                    let insertAt = 0;
+                    for (let i = 0; i < body.length; i += 1) {
+                        if (body[i].isImportDeclaration())
+                            insertAt = i + 1;
+                        else
+                            break;
+                    }
+                    if (insertAt < body.length) {
+                        body[insertAt].insertBefore(helper);
+                    }
+                    else if (insertAt > 0) {
+                        body[insertAt - 1].insertAfter(helper);
+                    }
+                    else {
+                        programPath.unshiftContainer('body', helper);
+                    }
+                },
+            },
+            Function: {
+                enter(fnPath, state) {
+                    const opts = (state.opts ?? {});
+                    if (isStampOnly(opts))
+                        return;
+                    const filename = state.filename ?? state.file.opts.filename ?? '';
+                    if (!filename || filename.includes('node_modules'))
+                        return;
+                    if (opts.exclude?.some((frag) => filename.includes(frag)))
+                        return;
+                    // Do not pollute the injected `__ufRef` helper (Program.exit re-visits it).
+                    if ((fnPath.isFunctionDeclaration() || fnPath.isFunctionExpression()) &&
+                        t.isIdentifier(fnPath.node.id) &&
+                        fnPath.node.id.name === REF_HELPER) {
+                        return;
+                    }
+                    // Capture incoming scope for any function that may stamp hosts.
+                    ensureScopeCapture(t, fnPath);
+                },
+            },
+            JSXOpeningElement(openingPath, state) {
+                const opts = (state.opts ?? {});
+                const nameNode = openingPath.node.name;
+                if (!t.isJSXIdentifier(nameNode))
+                    return;
+                const name = nameNode.name;
+                const allowlist = opts.allowlist ?? DEFAULT_ALLOWLIST;
+                // Default false — full mode populates the auto-anchor registry.
+                const stampOnly = isStampOnly(opts);
+                const filename = state.filename ?? state.file.opts.filename ?? '';
+                if (!filename || filename.includes('node_modules'))
+                    return;
+                if (opts.exclude?.some((frag) => filename.includes(frag)))
+                    return;
+                const rootDir = opts.rootDir ?? state.cwd ?? process.cwd();
+                const rel = nodePath.relative(rootDir, filename).split(nodePath.sep).join('/') || filename;
+                const component = enclosingComponentName(t, openingPath, filename);
+                const attrs = openingPath.node.attributes;
+                const findAttr = (attrName) => attrs.find((a) => t.isJSXAttribute(a) && t.isJSXIdentifier(a.name) && a.name.name === attrName);
+                // --- Custom component call-site scope ---
+                // stampOnly has no runtime scope consumer, so skip this entirely.
+                if (isCustomComponentName(name, allowlist)) {
+                    if (stampOnly)
+                        return;
+                    if (findAttr(UF_SCOPE_PROP))
+                        return;
+                    const counters = (state.ufCallSiteCounters ?? (state.ufCallSiteCounters = new Map()));
+                    let byComp = counters.get(component);
+                    if (!byComp) {
+                        byComp = new Map();
+                        counters.set(component, byComp);
+                    }
+                    const ordinal = byComp.get(name) ?? 0;
+                    byComp.set(name, ordinal + 1);
+                    const ufId = stringLiteralFromJsxAttr(t, findAttr('userflowId'));
+                    const tId = stringLiteralFromJsxAttr(t, findAttr('testID'));
+                    const kId = stringLiteralFromJsxAttr(t, findAttr('key'));
+                    const ids = {
+                        ...(ufId ? { userflowId: ufId } : {}),
+                        ...(tId ? { testID: tId } : {}),
+                        ...(kId ? { key: kId } : {}),
+                    };
+                    const scope = formatCallSiteScope(rel, component, name, ordinal, ids);
+                    attrs.push(t.jsxAttribute(t.jsxIdentifier(UF_SCOPE_PROP), t.stringLiteral(scope)));
+                    state.ufStamped = true;
+                    return;
+                }
+                if (!allowlist.includes(name))
+                    return;
+                // Idempotency
+                if (findAttr(UFID_PROP))
+                    return;
+                if (stampOnly && findAttr('nativeID')) {
+                    const existing = stringLiteralFromJsxAttr(t, findAttr('nativeID'));
+                    if (existing?.startsWith('uf_'))
+                        return;
+                }
+                const { path: structuralPath, self } = buildSemanticPath(t, openingPath, rel, component, allowlist, state.ufOrdinals, 
+                // stampOnly has no scored matcher — keep leaf ordinals unique even when
+                // sibling hosts share the same static label.
+                !stampOnly);
+                const hashedKey = `uf_${hashId(structuralPath)}`;
+                let manualIdExpr = null;
+                for (const attrName of MANUAL_ID_ATTRS) {
+                    const attr = findAttr(attrName);
+                    if (!attr)
+                        continue;
+                    const value = attr.value;
+                    if (t.isStringLiteral(value)) {
+                        if (attrName === 'nativeID' && value.value.startsWith('uf_'))
+                            continue;
+                        manualIdExpr = t.stringLiteral(value.value);
+                        break;
+                    }
+                    if (t.isJSXExpressionContainer(value) && t.isExpression(value.expression)) {
+                        manualIdExpr = t.cloneNode(value.expression);
+                        break;
+                    }
+                }
+                if (COLLAPSABLE_NAMES.has(name) && !findAttr('collapsable')) {
+                    attrs.push(t.jsxAttribute(t.jsxIdentifier('collapsable'), t.jsxExpressionContainer(t.booleanLiteral(false))));
+                }
+                if (stampOnly) {
+                    if (!manualIdExpr && !findAttr('nativeID')) {
+                        attrs.push(t.jsxAttribute(t.jsxIdentifier('nativeID'), t.stringLiteral(hashedKey)));
+                    }
+                    state.ufStamped = true;
+                    return;
+                }
+                const literalTestId = stringLiteralFromJsxAttr(t, findAttr('testID'));
+                const literalLabel = stringLiteralFromJsxAttr(t, findAttr('accessibilityLabel'));
+                const literalUserflowId = stringLiteralFromJsxAttr(t, findAttr('userflowId'));
+                const childText = childTextFromJsx(t, openingPath);
+                const childShape = childShapeFromJsx(t, openingPath);
+                const iconName = staticIconName(t, openingPath);
+                const imageSrc = staticImageUri(t, openingPath);
+                const hintsExpr = buildCompactHintsObjectExpression(t, {
+                    nativeId: hashedKey,
+                    path: structuralPath,
+                    ...(literalTestId ? { literalTestId } : {}),
+                    ...(literalLabel ? { literalLabel } : {}),
+                    ...(literalUserflowId ? { literalUserflowId } : {}),
+                    ...(childText ? { childText } : {}),
+                    ...(childShape ? { childShape } : {}),
+                    ...(iconName ? { iconName } : {}),
+                    ...(imageSrc ? { imageSrc } : {}),
+                    ordinal: self.ordinal,
+                    siblingIndex: self.siblingIndex,
+                });
+                // Dev: inject __ufid for fiber/debug. Production default: omit (bundle size).
+                const injectUfid = opts.injectUfidProp !== undefined ? opts.injectUfidProp : !isProduction;
+                if (injectUfid) {
+                    attrs.push(t.jsxAttribute(t.jsxIdentifier(UFID_PROP), t.stringLiteral(structuralPath)));
+                }
+                if (manualIdExpr) {
+                    attrs.push(t.jsxAttribute(t.jsxIdentifier(UF_MANUAL_PROP), t.stringLiteral('true')));
+                }
+                // Compose with whatever ref the app already has — never drop it.
+                // Supports: ref={expr}, ref="legacyString", and a single {...props}.ref.
+                const existingRefIdx = attrs.findIndex((a) => t.isJSXAttribute(a) && t.isJSXIdentifier(a.name) && a.name.name === 'ref');
+                let userRefExpr = t.nullLiteral();
+                if (existingRefIdx >= 0) {
+                    const existing = attrs[existingRefIdx];
+                    if (t.isStringLiteral(existing.value)) {
+                        // Legacy string refs: pass through so runtime can assign owner.refs[name].
+                        userRefExpr = t.stringLiteral(existing.value.value);
+                    }
+                    else if (t.isJSXExpressionContainer(existing.value)) {
+                        const inner = existing.value.expression;
+                        if (t.isExpression(inner)) {
+                            if (t.isCallExpression(inner) &&
+                                t.isIdentifier(inner.callee) &&
+                                inner.callee.name === REF_HELPER) {
+                                return;
+                            }
+                            userRefExpr = inner;
+                        }
+                    }
+                }
+                else {
+                    // No explicit ref attribute — if the element only has one object spread
+                    // (e.g. {...props}), compose with that object's `.ref` so we don't
+                    // clobber a ref that arrives via spread (JSX later-attrs-win).
+                    const spreads = attrs.filter((a) => t.isJSXSpreadAttribute(a));
+                    if (spreads.length === 1 && t.isIdentifier(spreads[0].argument)) {
+                        userRefExpr = t.memberExpression(spreads[0].argument, t.identifier('ref'));
+                    }
+                }
+                const fnParent = openingPath.getFunctionParent();
+                const includeScope = functionDeclaresIncomingScope(t, fnParent);
+                const runtimeExpr = buildRuntimeExpr(t, findAttr, includeScope);
+                const refCall = t.callExpression(t.identifier(REF_HELPER), [
+                    manualIdExpr ?? t.stringLiteral(hashedKey),
+                    hintsExpr,
+                    userRefExpr,
+                    t.stringLiteral(name),
+                    runtimeExpr,
+                ]);
+                const refAttr = t.jsxAttribute(t.jsxIdentifier('ref'), t.jsxExpressionContainer(refCall));
+                if (existingRefIdx >= 0) {
+                    attrs[existingRefIdx] = refAttr;
+                }
+                else {
+                    attrs.push(refAttr);
+                }
+                if (!manualIdExpr && !findAttr('nativeID')) {
+                    attrs.push(t.jsxAttribute(t.jsxIdentifier('nativeID'), t.stringLiteral(hashedKey)));
+                }
+                state.ufStamped = true;
+            },
+        },
+    };
+}
+module.exports = userflowAutoStamp;
+module.exports.default = userflowAutoStamp;
+//# sourceMappingURL=index.js.map