react-native-mcp-kit 3.0.0 → 4.0.0

package/dist/modules/fiberTree/fiberTree.js

@@ -1,643 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fiberTreeModule = void 0;
+const projectValue_1 = require("../../shared/projection/projectValue");
+const children_1 = require("./children");
+const constants_1 = require("./constants");
+const finder_1 = require("./finder");
+const hooks_1 = require("./hooks");
+const projection_1 = require("./projection");
+const query_1 = require("./query");
+const redact_1 = require("./redact");
 const utils_1 = require("./utils");
-const DEFAULT_DEPTH = 10;
-const QUERY_LIMIT_DEFAULT = 50;
-const QUERY_LIMIT_MAX = 500;
-const QUERY_DEFAULT_FIELDS = ['mcpId', 'name', 'testID'];
-const WAIT_TIMEOUT_DEFAULT = 10_000;
-const WAIT_TIMEOUT_MAX = 60_000;
-const WAIT_INTERVAL_DEFAULT = 300;
-const WAIT_INTERVAL_MIN = 100;
-// Parse a name pattern: `/regex/flags` → RegExp matcher; anything else →
-// exact-string matcher. Same convention as log_box__ignore.
-const parseNamePattern = (raw) => {
-    const m = raw.match(/^\/(.+)\/([gimsuy]*)$/);
-    if (m && m[1] !== undefined) {
-        try {
-            const rx = new RegExp(m[1], m[2] ?? '');
-            return (n) => {
-                return rx.test(n);
-            };
-        }
-        catch {
-            return (n) => {
-                return n === raw;
-            };
-        }
-    }
-    return (n) => {
-        return n === raw;
-    };
-};
-const HOOK_DEFAULT_MAX_DEPTH = 3;
-// Try to treat `current` as a React component / native view instance and
-// collapse it to a compact identifier. Native views expose
-// `_internalFiberInstanceHandleDEV` / `_reactInternals`; class instances
-// expose `_reactInternals`. If we find a fiber, we surface its mcpId /
-// testID / component name so the agent can follow up via `query` if needed.
-// If it doesn't look like a component, return null to signal "serialize
-// normally".
-const resolveComponentRef = (current) => {
-    if (current === null || current === undefined)
-        return null;
-    if (typeof current !== 'object')
-        return null;
-    const obj = current;
-    // Pick up a fiber from the typical internal fields used by RN / React.
-    const fiber = obj._reactInternals ??
-        obj._reactInternalFiber ??
-        obj._internalFiberInstanceHandleDEV ??
-        obj._internalInstanceHandle;
-    const hasNativeTag = '_nativeTag' in obj;
-    if (!fiber && !hasNativeTag)
-        return null;
-    const out = { __componentRef: true };
-    if (fiber) {
-        const props = fiber.memoizedProps;
-        const mcpId = props?.['data-mcp-id'];
-        const testID = props?.testID;
-        if (mcpId)
-            out.mcpId = mcpId;
-        if (testID)
-            out.testID = testID;
-        const typeName = fiber.type?.displayName ??
-            fiber.type?.name;
-        if (typeName)
-            out.componentName = typeName;
-    }
-    if (hasNativeTag) {
-        out.nativeTag = obj._nativeTag;
-        const viewConfig = obj.viewConfig;
-        if (viewConfig?.uiViewClassName)
-            out.viewClass = viewConfig.uiViewClassName;
-    }
-    return out;
-};
-// Recognise React's effect-record shape: `{ tag: number, create: function,
-// deps: null | unknown[] }` with optional `inst` / `destroy` / `next`.
-// useState / useReducer / useContext memoizedState values of this exact
-// shape in real user code are astronomically unlikely, so we treat this as
-// a reliable "definitely not a state slot" signal.
-const looksLikeEffectRecord = (raw) => {
-    if (!raw || typeof raw !== 'object')
-        return false;
-    const r = raw;
-    return (typeof r.tag === 'number' &&
-        typeof r.create === 'function' &&
-        (r.deps === null || r.deps === undefined || Array.isArray(r.deps)));
-};
-// Recognise the useRef shape: `{ current: X }` with NO other keys. A useState
-// value that is literally an object whose sole own-key is "current" is so
-// improbable in real code that we treat it as a reliable "this slot is a
-// ref, not a state" signal — lets State/Custom skip ref slots that leaked in
-// through custom-hook internals.
-const looksLikeRefShape = (raw) => {
-    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
-        return false;
-    const keys = Object.keys(raw);
-    return keys.length === 1 && keys[0] === 'current';
-};
-// Shape-verify a hook slot's memoizedState against its expected kind. When
-// a custom hook internally uses multiple built-in hooks, our static metadata
-// understates the number of slots — every subsequent pairing drifts. By
-// requiring a structural match before consuming a metadata entry we can
-// swallow "internal" slots and keep the rest aligned. Permissive kinds
-// (State / Reducer / Context / Custom) reject only obvious mis-matches
-// (currently: the effect-record shape).
-const shapeMatchesKind = (raw, kind) => {
-    switch (kind) {
-        case 'Ref':
-            return !!raw && typeof raw === 'object' && 'current' in raw;
-        case 'Memo':
-        case 'Callback':
-            return Array.isArray(raw) && raw.length === 2 && (raw[1] === null || Array.isArray(raw[1]));
-        case 'Effect':
-        case 'LayoutEffect':
-        case 'InsertionEffect':
-            return looksLikeEffectRecord(raw);
-        case 'Transition':
-            return Array.isArray(raw) && raw.length === 2;
-        case 'State':
-        case 'Reducer':
-        case 'Context':
-        case 'Custom':
-            // Permissive but not blind — drop obvious effect-node and ref-shape
-            // slots so State/Custom metadata doesn't swallow internals of
-            // preceding custom hooks.
-            return !looksLikeEffectRecord(raw) && !looksLikeRefShape(raw);
-        default:
-            return true;
-    }
-};
-const serializeHookValue = (raw, kind, maxDepth) => {
-    const walk = (v) => {
-        return (0, utils_1.serializeValue)(v, new WeakSet(), 0, maxDepth);
-    };
-    switch (kind) {
-        case 'Ref': {
-            if (!raw || typeof raw !== 'object' || !('current' in raw)) {
-                return walk(raw);
-            }
-            const current = raw.current;
-            const componentRef = resolveComponentRef(current);
-            if (componentRef) {
-                return { current: componentRef };
-            }
-            return { current: walk(current) };
-        }
-        case 'Memo':
-        case 'Callback':
-            if (Array.isArray(raw) && raw.length === 2) {
-                return { deps: raw[1], value: walk(raw[0]) };
-            }
-            return walk(raw);
-        case 'Effect':
-        case 'LayoutEffect':
-        case 'InsertionEffect': {
-            // React's hook slot for effects holds { tag, create, destroy, deps, next }.
-            // Only `deps` is safe and useful to surface.
-            const effect = raw;
-            return effect && typeof effect === 'object' && 'deps' in effect
-                ? { deps: effect.deps ?? null }
-                : null;
-        }
-        default:
-            return walk(raw);
-    }
-};
-// Estimate how many slots in fiber.memoizedState a hook function consumes.
-// Used by the slot-walker to advance past unannotated black-box library
-// hooks (e.g. `useSelector` from react-redux) which our babel plugin couldn't
-// expand statically — without this they'd consume only one fiber slot during
-// alignment, drifting the rest of the metadata out of sync.
-//
-// Three cascading strategies, falling through on miss:
-//   1. `fn.__mcp_hooks` recursive — accurate for any hook our plugin saw.
-//      Custom sub-entries recurse; built-in entries count as 1.
-//   2. `fn.toString()` regex — counts `useXxx(` calls in the source. Works
-//      even after Metro bundling because hook references survive as
-//      property accesses (`(0, _react.useState)(...)`) — property names
-//      aren't mangled. Underestimates when nested customs themselves expand
-//      to multiple slots, but better than 1.
-//   3. Default 1 — native functions, bound functions, or sources we can't
-//      parse. Same as the original behavior.
-//
-// Cached per-function via WeakMap so cost is paid once per hook fn per
-// session.
-const HOOK_SLOTS_CACHE = new WeakMap();
-const HOOK_NAME_RE = /\buse[A-Z]\w*\s*\(/g;
-const STRING_LITERAL_RE = /(['"`])(?:\\.|(?!\1).)*\1/g;
-const BLOCK_COMMENT_RE = /\/\*[\s\S]*?\*\//g;
-const LINE_COMMENT_RE = /\/\/[^\n]*/g;
-const countHookSlots = (fn, depth = 0, seen) => {
-    if (depth > 8)
-        return 1;
-    if (typeof fn !== 'function')
-        return 1;
-    const fnObj = fn;
-    const cached = HOOK_SLOTS_CACHE.get(fnObj);
-    if (cached !== undefined)
-        return cached;
-    const localSeen = seen ?? new WeakSet();
-    if (localSeen.has(fnObj))
-        return 1;
-    localSeen.add(fnObj);
-    // (1) Annotated metadata: recurse into sub-entries, summing their slot
-    // counts. Each built-in entry contributes 1; each Custom contributes
-    // however many its own fn does (recurse).
-    const annotated = fn.__mcp_hooks;
-    if (Array.isArray(annotated)) {
-        let total = 0;
-        for (const entry of annotated) {
-            if (entry && entry.kind === 'Custom' && typeof entry.fn === 'function') {
-                total += countHookSlots(entry.fn, depth + 1, localSeen);
-            }
-            else {
-                total += 1;
-            }
-        }
-        const result = Math.max(total, 1);
-        HOOK_SLOTS_CACHE.set(fnObj, result);
-        return result;
-    }
-    // (2) toString-based parsing. Strip strings/comments first to avoid
-    // matching `'useState'` inside literals. Each `useXxx(` occurrence in
-    // remaining source counts as one hook call (≥ 1 slot). Custom hook calls
-    // we encounter here can't be resolved further (no scope binding from the
-    // outer function), so we bottom out at 1 slot per occurrence — still
-    // beats the original constant-1 fallback when the source has multiple
-    // hook calls (e.g. `useSyncExternalStoreWithSelector` internals).
-    let src;
-    try {
-        src = Function.prototype.toString.call(fn);
-    }
-    catch {
-        HOOK_SLOTS_CACHE.set(fnObj, 1);
-        return 1;
-    }
-    if (!src || src.includes('[native code]')) {
-        HOOK_SLOTS_CACHE.set(fnObj, 1);
-        return 1;
-    }
-    const stripped = src
-        .replace(STRING_LITERAL_RE, '""')
-        .replace(BLOCK_COMMENT_RE, '')
-        .replace(LINE_COMMENT_RE, '');
-    HOOK_NAME_RE.lastIndex = 0;
-    const matches = stripped.match(HOOK_NAME_RE);
-    const result = matches ? matches.length : 1;
-    HOOK_SLOTS_CACHE.set(fnObj, result);
-    return result;
-};
-// Flatten a metadata array by recursively inlining custom-hook sub-metadata.
-// Stops on cycles (hook references itself) and on Custom entries whose `fn`
-// isn't annotated (library hooks that bypassed the babel plugin — usually
-// pre-compiled node_modules). Such unannotated entries stay as single
-// records and rely on shape-check for alignment.
-//
-// Custom entries with annotated `fn` produce TWO records: a parent (marked
-// `expanded: true`, no slot consumption) followed by all flattened
-// children. This keeps the call-site visible in the output — without it
-// the agent would see e.g. `wrapperAnimStyle.areAnimationsActive` deep
-// in `via:` but never the `wrapperAnimStyle = useAnimatedStyle(...)`
-// invocation that owns those slots.
-const flattenHookMeta = (meta, via = [], seen = new WeakSet(), maxDepth = Infinity) => {
-    const out = [];
-    for (const entry of meta) {
-        const fn = entry.fn;
-        const sub = fn && typeof fn === 'function' && Array.isArray(fn.__mcp_hooks) ? fn.__mcp_hooks : undefined;
-        // Stop expanding once `via.length` would reach the cap — at that point
-        // the current entry is treated as a leaf (Custom record without
-        // children). The slot-walker still pairs it with one slot, so output
-        // stays internally consistent.
-        if (sub && !seen.has(fn) && via.length < maxDepth) {
-            seen.add(fn);
-            out.push({ ...entry, expanded: true, via });
-            out.push(...flattenHookMeta(sub, [...via, entry.name], seen, maxDepth));
-            seen.delete(fn);
-        }
-        else {
-            out.push({ ...entry, via });
-        }
-    }
-    return out;
-};
-const flatHooksToTree = (flat) => {
-    const root = [];
-    // Stack of currently-open parents, indexed by their depth (= via.length
-    // of THEIR own entry, since their children sit at via.length + 1).
-    const parents = [];
-    for (const entry of flat) {
-        const depth = entry.via?.length ?? 0;
-        while (parents.length > depth)
-            parents.pop();
-        const node = { kind: entry.kind, name: entry.name };
-        if (entry.hook !== undefined)
-            node.hook = entry.hook;
-        if (entry.value !== undefined)
-            node.value = entry.value;
-        if (parents.length === 0) {
-            root.push(node);
-        }
-        else {
-            const parent = parents[parents.length - 1];
-            if (parent) {
-                parent.children = parent.children ?? [];
-                parent.children.push(node);
-            }
-            else {
-                root.push(node);
-            }
-        }
-        if (entry.expanded) {
-            // Push as the new active parent at this depth. Subsequent entries
-            // with via.length > depth become this node's descendants.
-            parents.push(node);
-        }
-    }
-    return root;
-};
-const extractHooks = (fiber, filter) => {
-    // React's wrapper machinery makes "where does metadata live" depend on
-    // the exact HOC chain. We try the most likely homes in order:
-    //
-    //   1. `fiber.type.__mcp_hooks` — bare components, FunctionDeclarations,
-    //      and the outer memo fiber when the chain is just memo(fn).
-    //   2. `fiber.elementType.__mcp_hooks` — memo(fn) without compare.
-    //      React converts the fiber to SimpleMemoComponent and rewrites
-    //      `fiber.type` to the inner function (see `updateMemoComponent` in
-    //      ReactFabric); our metadata sits on the outer memo wrapper, which
-    //      survives only on `elementType`.
-    //   3. `fiber.type.render.__mcp_hooks` — forwardRef wrapper. React lays
-    //      out memo(forwardRef(fn)) as three fibers (memo → forwardRef →
-    //      function). When the user queries by displayName they tend to
-    //      match the middle ForwardRef fiber (whose displayName resolves
-    //      via `render.displayName`); fiber.type there is the forwardRef
-    //      wrapper, which holds the inner fn at `.render`. The babel plugin
-    //      put plain metadata on that fn via the FunctionDecl visitor.
-    //   4. `fiber.type.type.__mcp_hooks` — memo wrapper around forwardRef
-    //      (or any non-function inner). Not the SimpleMemoComponent path,
-    //      so `fiber.type` stays as the memo wrapper and `.type` is the
-    //      inner forwardRef / class / etc. This catches getter installations
-    //      on the wrapper layer too.
-    const candidates = [
-        fiber.type,
-        fiber.elementType,
-        fiber.type?.render,
-        fiber.type?.type,
-    ];
-    let rawMeta;
-    for (const c of candidates) {
-        const m = c?.__mcp_hooks;
-        if (Array.isArray(m)) {
-            rawMeta = m;
-            break;
-        }
-    }
-    if (!Array.isArray(rawMeta))
-        return null;
-    const meta = flattenHookMeta(rawMeta, [], new WeakSet(), filter.expansionDepth);
-    const out = [];
-    let state = fiber.memoizedState;
-    let metaIdx = 0;
-    // Walk the fiber's hook chain and pair each slot with the next metadata
-    // entry whose `kind` is shape-compatible with the slot. Strongly-shaped
-    // kinds (Ref / Memo / Callback / Effect) match only the corresponding
-    // React hook shape. Permissive kinds (State / Reducer / Context / Custom)
-    // reject obvious mismatches (effect-record, ref-shape) so they don't
-    // swallow slots belonging to preceding custom hooks.
-    //
-    // For Custom-leaf entries — typically black-box library hooks
-    // (`useSelector`, `useQuery`, etc.) where flattenHookMeta couldn't expand
-    // because `fn.__mcp_hooks` was missing — we estimate slot count via
-    // `countHookSlots` and advance the fiber chain by that many slots in one
-    // step. Without this, a hook that consumes 3 internal slots only
-    // advances by 1 in the walker, drifting all trailing entries off the end
-    // of the chain.
-    const emitEntry = (entry, rawValueSlot) => {
-        const { hook, kind, name, via } = entry;
-        const passesKind = !filter.kindsSet || filter.kindsSet.has(kind);
-        const passesName = !filter.nameMatchers ||
-            filter.nameMatchers.some((m) => {
-                return m(name);
-            });
-        if (!(passesKind && passesName))
-            return;
-        const record = { kind, name };
-        // Prefer the babel-emitted hook name; fall back to fn.name for entries
-        // produced by older bundles that predate the `hook` field.
-        const resolvedHook = hook ?? (typeof entry.fn === 'function' ? entry.fn.name : undefined);
-        if (resolvedHook)
-            record.hook = resolvedHook;
-        if (filter.withValues && rawValueSlot !== undefined) {
-            // Redaction guard: mask the value (but keep kind/name/hook visible)
-            // when the entry's name OR any ancestor in `via` matches a redact
-            // pattern. Catches both direct sensitive hooks (`password` State)
-            // and leaves nested under sensitive customs (a `value` field of
-            // `useCredentials()` won't slip through).
-            const isRedacted = matchesAnyRedactPattern(name, filter.redactPatterns) ||
-                (via?.some((v) => {
-                    return matchesAnyRedactPattern(v, filter.redactPatterns);
-                }) ??
-                    false);
-            if (isRedacted) {
-                record.value = REDACTED_VALUE;
-            }
-            else {
-                let value;
-                try {
-                    value = serializeHookValue(rawValueSlot, kind, filter.maxDepth);
-                    // Final cycle / non-serialisable check — the MCP bridge will
-                    // stringify this for transport, so bail now rather than killing
-                    // the whole response if one stray value carries a cycle past our
-                    // WeakSet (e.g. Proxy, lazy getter, native-bridged object).
-                    JSON.stringify(value);
-                }
-                catch {
-                    value = '[Unserialisable value]';
-                }
-                record.value = value;
-            }
-        }
-        if (via && via.length > 0)
-            record.via = via;
-        if (entry.expanded)
-            record.expanded = true;
-        out.push(record);
-    };
-    const advanceState = (steps) => {
-        for (let i = 0; i < steps && state; i++)
-            state = state.next;
-    };
-    while (state && metaIdx < meta.length) {
-        const entry = meta[metaIdx];
-        if (!entry) {
-            metaIdx++;
-            continue;
-        }
-        // Expanded parent (synthetic, marks the call-site of a recursively
-        // expanded custom hook). Emit without consuming any fiber slot — the
-        // children that follow are the real slot-bearing entries.
-        if (entry.expanded) {
-            emitEntry(entry, undefined);
-            metaIdx++;
-            continue;
-        }
-        // Custom-leaf with a known fn → recurse into source to estimate slot
-        // count, then consume that many slots at once. The first slot's value
-        // is exposed (best approximation of "this hook's value"); the rest are
-        // skipped silently as internals of the library hook.
-        if (entry.kind === 'Custom' && typeof entry.fn === 'function') {
-            const slots = countHookSlots(entry.fn);
-            if (slots > 1) {
-                emitEntry(entry, state.memoizedState);
-                advanceState(slots);
-                metaIdx++;
-                continue;
-            }
-        }
-        if (!shapeMatchesKind(state.memoizedState, entry.kind)) {
-            state = state.next;
-            continue;
-        }
-        emitEntry(entry, state.memoizedState);
-        metaIdx++;
-        state = state.next;
-    }
-    // Any metadata entries left after the fiber chain ran dry didn't get a
-    // slot match. Emit them anyway (without value) so the agent at least
-    // sees the hook exists — this is strictly better than silently dropping,
-    // and helps debug alignment issues. Common cause: a preceding Custom
-    // hook consumed more slots than countHookSlots estimated.
-    while (metaIdx < meta.length) {
-        const entry = meta[metaIdx];
-        if (entry)
-            emitEntry(entry, undefined);
-        metaIdx++;
-    }
-    return filter.format === 'tree' ? flatHooksToTree(out) : out;
-};
-const FIND_SCHEMA = {
-    index: {
-        description: '0-based index when several components match (default: 0).',
-        type: 'number',
-    },
-    mcpId: { description: 'Stable data-mcp-id to match.', type: 'string' },
-    name: { description: 'Component name to match.', type: 'string' },
-    testID: { description: 'testID to match.', type: 'string' },
-    text: { description: 'Rendered text substring (not prop values).', type: 'string' },
-    within: {
-        description: 'Parent component path. "/" nests, ":N" picks index.',
-        examples: ['LoginForm', 'Button:1/Pressable', 'TabBar/TabBarItem:2'],
-        type: 'string',
-    },
-};
-// Default redact patterns — applied to a hook's `name` AND every entry in
-// its `via` chain so values stay masked even when nested under a sensitive
-// custom hook (e.g. a leaf `value` inside a `useAuth()` expansion). Tuned
-// to match real-world variable names without over-matching innocent ones:
-// `Pin$` is anchored so it doesn't catch "Spinner"; broad terms like
-// `auth` are deliberately omitted (would catch `isAuthenticated`).
-const DEFAULT_REDACT_HOOK_NAMES = [
-    /password/i,
-    /token/i,
-    /jwt/i,
-    /secret/i,
-    /Pin$/,
-    /credential/i,
-    /apiKey/i,
-    /authorization/i,
-];
-const REDACTED_VALUE = '[redacted]';
-const escapeRegExp = (s) => {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-};
-const compileRedactPatterns = (raw) => {
-    return raw.map((p) => {
-        return typeof p === 'string' ? new RegExp(escapeRegExp(p), 'i') : p;
-    });
-};
-const matchesAnyRedactPattern = (name, patterns) => {
-    for (const p of patterns) {
-        if (p.test(name))
-            return true;
-    }
-    return false;
-};
-const resolveScreenFiber = (runtime) => {
-    const nav = runtime.navigationRef;
-    if (!nav || typeof nav.getCurrentRoute !== 'function')
-        return null;
-    const route = nav.getCurrentRoute();
-    const key = route && typeof route.key === 'string' ? route.key : undefined;
-    if (!key)
-        return null;
-    return (0, utils_1.findScreenFiberByRouteKey)(runtime.root, key);
-};
-const collectByScope = (fiber, scope, runtime) => {
-    switch (scope) {
-        case 'self':
-            return [fiber];
-        case 'parent':
-            return fiber.return ? [fiber.return] : [];
-        case 'ancestors':
-            return (0, utils_1.getAncestors)(fiber);
-        case 'children':
-            return (0, utils_1.getDirectChildren)(fiber);
-        case 'siblings':
-            return (0, utils_1.getSiblings)(fiber);
-        case 'nearest_host': {
-            const host = (0, utils_1.findHostFiber)(fiber);
-            return host ? [host] : [];
-        }
-        case 'screen': {
-            const screen = resolveScreenFiber(runtime);
-            if (!screen)
-                return [];
-            return (0, utils_1.findAllByQuery)(screen, {}).filter((f) => {
-                return f !== screen;
-            });
-        }
-        case 'descendants':
-        default:
-            return (0, utils_1.findAllByQuery)(fiber, {}).filter((f) => {
-                return f !== fiber;
-            });
-    }
-};
-const runQueryChain = (runtime, steps) => {
-    let current = [runtime.root];
-    for (const step of steps) {
-        const scope = step.scope ?? 'descendants';
-        const seen = new Set();
-        const collected = [];
-        for (const fiber of current) {
-            for (const candidate of collectByScope(fiber, scope, runtime)) {
-                if (!seen.has(candidate)) {
-                    seen.add(candidate);
-                    collected.push(candidate);
-                }
-            }
-        }
-        const filtered = collected.filter((f) => {
-            return (0, utils_1.matchesQuery)(f, step);
-        });
-        if (typeof step.index === 'number') {
-            const picked = filtered[step.index];
-            current = picked ? [picked] : [];
-        }
-        else {
-            current = filtered;
-        }
-        if (current.length === 0)
-            return [];
-    }
-    return current;
-};
-// Keep only fibers whose ancestor chain contains no other match. Removes
-// wrapper cascades (PressableView → Pressable → View → RCTView) while keeping
-// independent siblings with overlapping bounds (e.g. absolute-positioned
-// overlays). Preserves original DFS order.
-const dedupAncestors = (matches) => {
-    if (matches.length < 2)
-        return matches;
-    const matchSet = new Set(matches);
-    return matches.filter((fiber) => {
-        let p = fiber.return;
-        while (p) {
-            if (matchSet.has(p))
-                return false;
-            p = p.return;
-        }
-        return true;
-    });
-};
-// Window dimensions → physical-pixel bounds rectangle for `onlyVisible` filter.
-const getVisibleRect = () => {
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
-        const RN = require('react-native');
-        const { Dimensions, PixelRatio } = RN;
-        const window = Dimensions?.get?.('window');
-        const ratio = PixelRatio?.get?.() ?? 1;
-        if (!window || !Number.isFinite(window.width) || !Number.isFinite(window.height))
-            return null;
-        return {
-            height: window.height * ratio,
-            width: window.width * ratio,
-        };
-    }
-    catch {
-        return null;
-    }
-};
-const intersectsRect = (bounds, rect) => {
-    return (bounds.x + bounds.width > 0 &&
-        bounds.y + bounds.height > 0 &&
-        bounds.x < rect.width &&
-        bounds.y < rect.height);
+const viewport_1 = require("./viewport");
+const waitFor_1 = require("./waitFor");
+const PROJECTION_SCHEMA = (0, projectValue_1.makeProjectionSchema)(constants_1.FIBER_DEFAULT_DEPTH);
+// Module-local 2-arg wrapper around the shared `applyProjection` so handlers
+// don't have to repeat `projectFiberValue` + default-depth on every call.
+const applyProjection = (result, args) => {
+    return (0, projectValue_1.applyProjection)(result, args, utils_1.projectFiberValue, constants_1.FIBER_DEFAULT_DEPTH);
 };
 const fiberTreeModule = (options) => {
     if (options?.rootRef) {
@@ -649,9 +28,9 @@ const fiberTreeModule = (options) => {
     //   - `additionalRedactHookNames` provided → defaults + user's.
     //   - Neither → defaults.
     // Pass `redactHookNames: []` to disable redaction entirely.
-    const redactPatterns = compileRedactPatterns(options?.redactHookNames !== undefined
+    const redactPatterns = (0, redact_1.compileRedactPatterns)(options?.redactHookNames !== undefined
         ? options.redactHookNames
-        : [...DEFAULT_REDACT_HOOK_NAMES, ...(options?.additionalRedactHookNames ?? [])]);
+        : [...redact_1.DEFAULT_REDACT_HOOK_NAMES, ...(options?.additionalRedactHookNames ?? [])]);
     // Root-version keyed cache for `runQueryChain`. When React commits, the
     // HostRoot fiber swaps — so a mismatched pointer is proof the tree changed
     // and the cached match set for the same steps is no longer valid.
@@ -660,7 +39,7 @@ const fiberTreeModule = (options) => {
     const cacheEntries = new Map();
     const runCachedQuery = (runtime, steps, useCache) => {
         if (!useCache)
-            return runQueryChain(runtime, steps);
+            return (0, query_1.runQueryChain)(runtime, steps);
         if (cacheRoot !== runtime.root) {
             cacheRoot = runtime.root;
             cacheEntries.clear();
@@ -669,78 +48,25 @@ const fiberTreeModule = (options) => {
         const hit = cacheEntries.get(key);
         if (hit)
             return hit;
-        const result = runQueryChain(runtime, steps);
+        const result = (0, query_1.runQueryChain)(runtime, steps);
         cacheEntries.set(key, result);
         return result;
     };
-    const findInRoot = (root, segment) => {
-        if (!root)
-            return null;
-        // Support "Name:index" format, e.g. "Button:1"
-        const [name, indexStr] = segment.split(':');
-        if (!name)
-            return null;
-        const idx = indexStr ? parseInt(indexStr, 10) : 0;
-        const allByMcpId = (0, utils_1.findAllByQuery)(root, { mcpId: name });
-        if (allByMcpId.length > 0)
-            return allByMcpId[idx] ?? null;
-        const allByTestID = (0, utils_1.findAllByQuery)(root, { testID: name });
-        if (allByTestID.length > 0)
-            return allByTestID[idx] ?? null;
-        const allByName = (0, utils_1.findAllByQuery)(root, { name });
-        return allByName[idx] ?? null;
-    };
-    const findComponent = (args) => {
-        let root = (0, utils_1.getFiberRoot)();
-        if (!root)
-            return null;
-        // "within" supports recursive path with index: "Parent/Child:1/GrandChild"
-        if (args.within) {
-            const path = args.within.split('/');
-            for (const segment of path) {
-                root = findInRoot(root, segment);
-                if (!root)
-                    return null;
-            }
-        }
-        const index = args.index ?? 0;
-        if (args.mcpId) {
-            const all = (0, utils_1.findAllByQuery)(root, { mcpId: args.mcpId });
-            return all[index] ?? null;
-        }
-        if (args.testID) {
-            const all = (0, utils_1.findAllByQuery)(root, { testID: args.testID });
-            return all[index] ?? null;
-        }
-        if (args.name) {
-            const all = (0, utils_1.findAllByQuery)(root, { name: args.name });
-            return all[index] ?? null;
-        }
-        if (args.text) {
-            const all = (0, utils_1.findAllByQuery)(root, { text: args.text });
-            return all[index] ?? null;
-        }
-        return null;
-    };
-    const requireRoot = () => {
-        const root = (0, utils_1.getFiberRoot)();
-        if (!root) {
-            return { error: 'Fiber root not available. The app may not have rendered yet.' };
-        }
-        return null;
-    };
     return {
         description: `React fiber tree inspection and interaction.
 
 SCOPES (query steps)
   descendants (default) / children / parent / ancestors / siblings / self
-  / screen / nearest_host.
+  / root / screen / nearest_host.
+    · root — the React fiber root, regardless of the previous step's
+      match. Use as the first step to start from the top of the tree
+      (e.g. dump the whole tree via select: [{ children: 5 }]).
     · screen — descendants of the currently focused React Navigation
       screen fiber. Available when the library was initialized with a
       navigationRef. Lets a first step skip "find current screen first".
     · nearest_host — walks down to the first mounted HOST_COMPONENT
-      fiber. Useful before call_ref (focus/blur/measure) which require
-      a host instance.
+      fiber. Useful before \`call({ method })\` (focus/blur/measure)
+      which requires a host instance.
 
 STEP CRITERIA
   name / mcpId / testID — strict equality.
@@ -759,15 +85,27 @@ STEP CRITERIA
   index — pick N-th match from this step; otherwise all matches fan out into the next step.
 
 SELECT (output fields)
-  Default ["mcpId", "name", "testID"] — props, bounds, hooks are opt-in.
+  Default ["mcpId", "name", "testID"] — props, bounds, hooks,
+  refMethods, children are opt-in.
   bounds: { x, y, width, height, centerX, centerY } in PHYSICAL pixels,
   top-left origin. null when the fiber has no mounted host view. centerX/
   centerY feed straight into host__tap.
-  props: full serialized props (heavy). Pair with propsInclude:
-  ["key1","key2"] to keep only the props you actually need and avoid
-  pulling large style maps, data arrays, or nested element trees.
-  hooks: the component's hooks. Each entry { kind, name, hook?, via?,
-  expanded?, value? }; configure via hooksInclude.
+  refMethods: list of native-ref method names (focus, blur, measure,
+  scrollTo, ...) available on the fiber's host instance. null when
+  there is no native instance (composite wrapper, unmounted,
+  virtualized). Feeds directly into fiber_tree__call({ method }).
+  props: per-field projection — \`{ props: { path?, depth?, maxBytes? } }\`.
+  hooks: filtered + projected — \`{ hooks: { kinds?, names?, withValues?,
+  expansionDepth?, format?, path?, depth?, maxBytes? } }\`. Each entry
+  { kind, name, hook?, via?, expanded?, value? }.
+  children: recursive light-only walker for tree-of-tree navigation —
+  short form { children: 5 } (treeDepth=5) or object form
+  { children: { treeDepth, select?, itemsCap? } }. select inside
+  children may include only mcpId / name / testID / bounds / nested
+  children — props/hooks throw at parse time. Use a second query against
+  a child mcpId to inspect its props/hooks. treeDepth max 16, itemsCap
+  default 50; overflow inserts a \`\${truncated}\` sentinel as the first
+  array item.
 
 RESPONSE
   { matches: [...], total, truncated? } — total is the unrestricted match
@@ -782,9 +120,9 @@ RESPONSE
 
 TIPS
   mcpId format "ComponentName:file:line" — stable across renders.
-  Use query to locate, then invoke (bypasses gesture pipeline) or host__tap
-  with bounds (real OS touch) to act. For one-shot real taps, tap_fiber
-  collapses both steps into a single call.
+  Use query to locate, then call({ prop } or { method }) (bypasses gesture
+  pipeline) or host__tap with bounds (real OS touch) to act. For one-shot
+  real taps, tap_fiber collapses both steps into a single call.
   When stepping up via scope: "ancestors", prefer filtering by name (or
   testID/mcpId) over guessing an index — ancestors count is brittle and
   varies across RN versions.
@@ -793,37 +131,54 @@ TIPS
   { contains: "Search" } }\`.`,
         name: 'fiber_tree',
         tools: {
-            call_ref: {
-                description: "Call a method on a component's native ref (focus, blur, measure, …). Use get_ref_methods first to see what's available.",
+            call: {
+                description: "Imperative action on a fiber — invoke a prop callback OR a native-ref method. Pass `prop: 'onPress'` to call a callback prop, or `method: 'focus'` to call a method on the host instance's native ref. For simulating user taps, prefer `host__tap_fiber` — it goes through the real OS gesture pipeline so Pressable feedback / gesture responders / hit-test all behave as under a real finger. `call` is for non-gesture callbacks, off-screen / virtualised components, or imperative ref methods (focus / blur / measure / scrollTo / ...). Use `query` with `select: ['refMethods']` first to see what methods are available on a fiber.",
                 handler: (args) => {
-                    const rootError = requireRoot();
+                    const rootError = (0, finder_1.requireRoot)();
                     if (rootError)
                         return rootError;
-                    const fiber = findComponent(args);
+                    const fiber = (0, finder_1.findComponent)(args);
                     if (!fiber)
                         return { error: 'Component not found' };
+                    const propName = typeof args.prop === 'string' ? args.prop : undefined;
+                    const methodName = typeof args.method === 'string' ? args.method : undefined;
+                    if ((propName && methodName) || (!propName && !methodName)) {
+                        return {
+                            error: 'call requires exactly one of `prop` (callback name) or `method` (ref method name).',
+                        };
+                    }
+                    const callArgs = args.args ?? [];
+                    // Prop-callback path: read prop from memoizedProps, call directly.
+                    if (propName) {
+                        const callback = fiber.memoizedProps?.[propName];
+                        if (typeof callback !== 'function') {
+                            const availableProps = Object.keys(fiber.memoizedProps ?? {}).filter((key) => {
+                                return typeof fiber.memoizedProps[key] === 'function';
+                            });
+                            return {
+                                availableProps,
+                                error: `Component "${(0, utils_1.getComponentName)(fiber)}" has no "${propName}" callback prop`,
+                            };
+                        }
+                        const result = callback(...callArgs);
+                        return applyProjection({ component: (0, utils_1.getComponentName)(fiber), prop: propName, result, success: true }, args);
+                    }
+                    // Ref-method path: resolve native instance, call method on it.
                     const instance = (0, utils_1.getNativeInstance)(fiber);
                     if (!instance) {
                         return { error: `Component "${(0, utils_1.getComponentName)(fiber)}" has no native instance` };
                     }
-                    const methodName = args.method;
-                    const methodArgs = args.args;
                     const method = instance[methodName];
                     if (typeof method !== 'function') {
                         return {
                             availableMethods: (0, utils_1.getAvailableMethods)(instance),
-                            error: `No method "${methodName}" on native instance`,
+                            error: `No method "${methodName}" on native instance of "${(0, utils_1.getComponentName)(fiber)}"`,
                         };
                     }
                     try {
                         const bound = method.bind(instance);
-                        const result = bound(...(methodArgs ?? []));
-                        return {
-                            component: (0, utils_1.getComponentName)(fiber),
-                            method: methodName,
-                            result,
-                            success: true,
-                        };
+                        const result = bound(...callArgs);
+                        return applyProjection({ component: (0, utils_1.getComponentName)(fiber), method: methodName, result, success: true }, args);
                     }
                     catch (e) {
                         return {
@@ -832,168 +187,21 @@ TIPS
                     }
                 },
                 inputSchema: {
-                    ...FIND_SCHEMA,
-                    args: { description: 'Arguments passed to the method.', type: 'array' },
-                    method: {
-                        description: 'Method name to call.',
-                        examples: ['focus', 'blur', 'measure'],
-                        type: 'string',
-                    },
-                },
-            },
-            get_children: {
-                description: 'Get the children subtree of a single component.',
-                handler: (args) => {
-                    const rootError = requireRoot();
-                    if (rootError)
-                        return rootError;
-                    const fiber = findComponent(args);
-                    if (!fiber)
-                        return { error: 'Component not found' };
-                    const depth = args.depth || DEFAULT_DEPTH;
-                    const serialized = (0, utils_1.serializeFiber)(fiber, depth);
-                    return serialized?.children ?? [];
-                },
-                inputSchema: {
-                    ...FIND_SCHEMA,
-                    depth: { description: 'Max traversal depth (default: 10).', type: 'number' },
-                },
-            },
-            get_component: {
-                description: 'Find one component and return its details with children subtree (deep inspection). Use `query` for a flat list of matches.',
-                handler: async (args) => {
-                    const rootError = requireRoot();
-                    if (rootError)
-                        return rootError;
-                    const root = (0, utils_1.getFiberRoot)();
-                    let fiber = null;
-                    if (args.mcpId) {
-                        fiber = (0, utils_1.findByMcpId)(root, args.mcpId);
-                    }
-                    else if (args.testID) {
-                        fiber = (0, utils_1.findByTestID)(root, args.testID);
-                    }
-                    else if (args.name) {
-                        fiber = (0, utils_1.findByName)(root, args.name);
-                    }
-                    else if (args.text) {
-                        fiber = (0, utils_1.findByText)(root, args.text);
-                    }
-                    if (!fiber)
-                        return { error: 'Component not found' };
-                    const depth = args.depth || DEFAULT_DEPTH;
-                    const serialized = (0, utils_1.serializeFiber)(fiber, depth);
-                    if (serialized && Array.isArray(args.select)) {
-                        const fields = new Set(args.select);
-                        if (fields.has('bounds')) {
-                            const bounds = await (0, utils_1.measureFiber)(fiber);
-                            if (bounds) {
-                                serialized.bounds = bounds;
-                            }
-                        }
-                        if (!fields.has('props')) {
-                            serialized.props = {};
-                        }
-                    }
-                    return serialized;
-                },
-                inputSchema: {
-                    depth: { description: 'Max child traversal depth (default: 10).', type: 'number' },
-                    mcpId: { description: 'Stable data-mcp-id to match.', type: 'string' },
-                    name: { description: 'Component name to match.', type: 'string' },
-                    select: {
-                        description: 'Fields to include on the root node. Available: name, props, bounds. Children are always included.',
-                        examples: [['name', 'bounds']],
-                        type: 'array',
-                    },
-                    testID: { description: 'testID to match.', type: 'string' },
-                    text: { description: 'Rendered text substring.', type: 'string' },
-                },
-            },
-            get_props: {
-                description: 'Get all props of one component.',
-                handler: (args) => {
-                    const rootError = requireRoot();
-                    if (rootError)
-                        return rootError;
-                    const fiber = findComponent(args);
-                    if (!fiber)
-                        return { error: 'Component not found' };
-                    return {
-                        name: (0, utils_1.getComponentName)(fiber),
-                        props: (0, utils_1.serializeProps)(fiber.memoizedProps),
-                    };
-                },
-                inputSchema: FIND_SCHEMA,
-            },
-            get_ref_methods: {
-                description: "List available methods on a component's native ref.",
-                handler: (args) => {
-                    const rootError = requireRoot();
-                    if (rootError)
-                        return rootError;
-                    const fiber = findComponent(args);
-                    if (!fiber)
-                        return { error: 'Component not found' };
-                    const instance = (0, utils_1.getNativeInstance)(fiber);
-                    if (!instance) {
-                        return { error: `Component "${(0, utils_1.getComponentName)(fiber)}" has no native instance` };
-                    }
-                    return {
-                        component: (0, utils_1.getComponentName)(fiber),
-                        methods: (0, utils_1.getAvailableMethods)(instance),
-                    };
-                },
-                inputSchema: FIND_SCHEMA,
-            },
-            get_tree: {
-                description: 'Dump the full React component tree from the root fiber.',
-                handler: (args) => {
-                    const rootError = requireRoot();
-                    if (rootError)
-                        return rootError;
-                    const root = (0, utils_1.getFiberRoot)();
-                    const depth = args.depth || DEFAULT_DEPTH;
-                    return (0, utils_1.serializeFiber)(root, depth);
-                },
-                inputSchema: {
-                    depth: { description: 'Max traversal depth (default: 10).', type: 'number' },
-                },
-            },
-            invoke: {
-                description: "Call a prop's callback function directly from JS. For simulating a user tap, prefer host__tap_fiber — it runs the real OS gesture pipeline so Pressable feedback, gesture responders, and hit-test behave as under a real finger. invoke still works for any callback when you specifically want the JS-only path (component off-screen, skipping the gesture recognizer, or driving a non-gesture prop), but it is not the default for user-behavior simulation.",
-                handler: (args) => {
-                    const rootError = requireRoot();
-                    if (rootError)
-                        return rootError;
-                    const fiber = findComponent(args);
-                    if (!fiber)
-                        return { error: 'Component not found' };
-                    const callbackName = args.callback;
-                    const callbackArgs = args.args;
-                    const callback = fiber.memoizedProps?.[callbackName];
-                    if (typeof callback !== 'function') {
-                        const availableCallbacks = Object.keys(fiber.memoizedProps ?? {}).filter((key) => {
-                            return typeof fiber.memoizedProps[key] === 'function';
-                        });
-                        return {
-                            availableCallbacks,
-                            error: `Component "${(0, utils_1.getComponentName)(fiber)}" has no "${callbackName}" callback`,
-                        };
-                    }
-                    const result = callback(...(callbackArgs ?? []));
-                    return { component: (0, utils_1.getComponentName)(fiber), result, success: true };
-                },
-                inputSchema: {
-                    ...FIND_SCHEMA,
+                    ...finder_1.FIND_SCHEMA,
+                    ...PROJECTION_SCHEMA,
                     args: {
-                        description: 'Arguments passed to the callback.',
+                        description: 'Arguments passed to the callback / method.',
                         examples: [[true], ['text']],
                         type: 'array',
                     },
-                    callback: {
-                        description: 'Callback prop name.',
-                        examples: ['onSkip', 'onUpdate', 'onCompleted'],
+                    method: {
+                        description: 'Native-ref method name. Mutually exclusive with `prop`.',
+                        examples: ['focus', 'blur', 'measure', 'scrollTo'],
+                        type: 'string',
+                    },
+                    prop: {
+                        description: 'Callback prop name. Mutually exclusive with `method`.',
+                        examples: ['onPress', 'onSkip', 'onChangeText'],
                         type: 'string',
                     },
                 },
@@ -1001,187 +209,130 @@ TIPS
             query: {
                 description: 'Chain-based fiber search. Each step narrows the result set via `scope` + criteria; multiple matches fan out into the next step. Returns { matches, total, truncated? }. Pass `waitFor` to poll until an element appears or disappears (optionally requiring stability for N ms) instead of a single-shot read. See the module description for scope, criteria, select and response reference.',
                 handler: async (args) => {
-                    const rootError = requireRoot();
-                    if (rootError)
-                        return rootError;
-                    const root = (0, utils_1.getFiberRoot)();
-                    const steps = args.steps;
-                    if (!Array.isArray(steps) || steps.length === 0) {
-                        return { error: 'query requires a non-empty `steps` array' };
-                    }
-                    const limit = typeof args.limit === 'number' && args.limit > 0
-                        ? Math.min(Math.floor(args.limit), QUERY_LIMIT_MAX)
-                        : QUERY_LIMIT_DEFAULT;
-                    const dedup = args.dedup !== false;
-                    const useCacheDefault = args.cache !== false;
-                    const onlyVisible = args.onlyVisible === true;
-                    const fields = new Set(Array.isArray(args.select) ? args.select : QUERY_DEFAULT_FIELDS);
-                    const propsInclude = Array.isArray(args.propsInclude)
-                        ? new Set(args.propsInclude)
-                        : null;
-                    const hooksIncludeRaw = args.hooksInclude;
-                    const hookKindsSet = hooksIncludeRaw && Array.isArray(hooksIncludeRaw.kinds)
-                        ? new Set(hooksIncludeRaw.kinds)
-                        : null;
-                    const hookNameMatchers = hooksIncludeRaw && Array.isArray(hooksIncludeRaw.names)
-                        ? hooksIncludeRaw.names.map(parseNamePattern)
-                        : null;
-                    const hookWithValues = hooksIncludeRaw?.withValues === true;
-                    const hookMaxDepth = typeof hooksIncludeRaw?.maxDepthInValues === 'number' &&
-                        hooksIncludeRaw.maxDepthInValues >= 0
-                        ? Math.min(Math.floor(hooksIncludeRaw.maxDepthInValues), 8)
-                        : HOOK_DEFAULT_MAX_DEPTH;
-                    const hookExpansionDepth = typeof hooksIncludeRaw?.expansionDepth === 'number' &&
-                        hooksIncludeRaw.expansionDepth >= 0
-                        ? Math.floor(hooksIncludeRaw.expansionDepth)
-                        : Infinity;
-                    const hookFormat = hooksIncludeRaw?.format === 'tree' ? 'tree' : 'flat';
-                    const runtime = { navigationRef, root };
-                    const runOnce = async (useCache) => {
-                        const rawMatches = runCachedQuery(runtime, steps, useCache);
-                        let all = dedup ? dedupAncestors(rawMatches) : rawMatches;
-                        const boundsCache = new Map();
-                        const measure = async (fiber) => {
-                            if (boundsCache.has(fiber))
-                                return boundsCache.get(fiber) ?? null;
-                            const b = await (0, utils_1.measureFiber)(fiber);
-                            boundsCache.set(fiber, b);
-                            return b;
-                        };
-                        if (onlyVisible) {
-                            const visibleRect = getVisibleRect();
-                            if (visibleRect) {
-                                const rect = visibleRect;
-                                const measured = await Promise.all(all.map(async (fiber) => {
-                                    return { bounds: await measure(fiber), fiber };
-                                }));
-                                all = measured
-                                    .filter(({ bounds }) => {
-                                    return bounds && intersectsRect(bounds, rect);
-                                })
-                                    .map(({ fiber }) => {
-                                    return fiber;
-                                });
-                            }
+                    const inner = async () => {
+                        const rootError = (0, finder_1.requireRoot)();
+                        if (rootError)
+                            return rootError;
+                        const root = (0, utils_1.getFiberRoot)();
+                        const steps = args.steps;
+                        if (!Array.isArray(steps) || steps.length === 0) {
+                            return { error: 'query requires a non-empty `steps` array' };
                         }
-                        const total = all.length;
-                        const truncated = total > limit;
-                        const picked = truncated ? all.slice(0, limit) : all;
-                        const matches = await Promise.all(picked.map(async (fiber) => {
-                            const result = {};
-                            if (fields.has('bounds')) {
-                                result.bounds = await measure(fiber);
-                            }
-                            if (fields.has('mcpId')) {
-                                result.mcpId = fiber.memoizedProps?.['data-mcp-id'];
-                            }
-                            if (fields.has('name')) {
-                                result.name = (0, utils_1.getComponentName)(fiber);
-                            }
-                            if (fields.has('props')) {
-                                const full = (0, utils_1.serializeProps)(fiber.memoizedProps);
-                                if (propsInclude) {
-                                    const filtered = {};
-                                    for (const key of propsInclude) {
-                                        if (key in full)
-                                            filtered[key] = full[key];
-                                    }
-                                    result.props = filtered;
-                                }
-                                else {
-                                    result.props = full;
-                                }
-                            }
-                            if (fields.has('testID')) {
-                                result.testID = fiber.memoizedProps?.testID;
-                            }
-                            if (fields.has('hooks')) {
-                                result.hooks = extractHooks(fiber, {
-                                    expansionDepth: hookExpansionDepth,
-                                    format: hookFormat,
-                                    kindsSet: hookKindsSet,
-                                    maxDepth: hookMaxDepth,
-                                    nameMatchers: hookNameMatchers,
-                                    redactPatterns,
-                                    withValues: hookWithValues,
-                                });
-                            }
-                            return result;
-                        }));
-                        return truncated ? { matches, total, truncated: true } : { matches, total };
-                    };
-                    const waitForRaw = args.waitFor;
-                    if (!waitForRaw || typeof waitForRaw !== 'object') {
-                        return runOnce(useCacheDefault);
-                    }
-                    const until = waitForRaw.until;
-                    if (until !== 'appear' && until !== 'disappear') {
-                        return { error: 'waitFor.until must be "appear" or "disappear"' };
-                    }
-                    const waitUntil = until;
-                    const timeout = Math.min(WAIT_TIMEOUT_MAX, Math.max(0, waitForRaw.timeout ?? WAIT_TIMEOUT_DEFAULT));
-                    const interval = Math.max(WAIT_INTERVAL_MIN, waitForRaw.interval ?? WAIT_INTERVAL_DEFAULT);
-                    const stable = Math.max(0, waitForRaw.stable ?? 0);
-                    const predicate = (total) => {
-                        return waitUntil === 'appear' ? total >= 1 : total === 0;
-                    };
-                    const startedAt = Date.now();
-                    const deadline = startedAt + timeout;
-                    let attempts = 0;
-                    let stableSince = null;
-                    let lastResult = await runOnce(false);
-                    attempts++;
-                    // eslint-disable-next-line no-constant-condition
-                    while (true) {
-                        const now = Date.now();
-                        const elapsedMs = now - startedAt;
-                        const met = predicate(lastResult.total);
-                        if (met) {
-                            if (stable === 0) {
-                                return {
-                                    ...lastResult,
-                                    attempts,
-                                    elapsedMs,
-                                    timedOut: false,
-                                    until: waitUntil,
-                                    waited: true,
-                                };
-                            }
-                            if (stableSince === null)
-                                stableSince = now;
-                            if (now - stableSince >= stable) {
-                                return {
-                                    ...lastResult,
-                                    attempts,
-                                    elapsedMs,
-                                    stableFor: now - stableSince,
-                                    timedOut: false,
-                                    until: waitUntil,
-                                    waited: true,
-                                };
-                            }
+                        const stepError = (0, query_1.validateSteps)(steps);
+                        if (stepError)
+                            return { error: stepError };
+                        const limit = typeof args.limit === 'number' && args.limit > 0
+                            ? Math.min(Math.floor(args.limit), constants_1.QUERY_LIMIT_MAX)
+                            : constants_1.QUERY_LIMIT_DEFAULT;
+                        const dedup = args.dedup !== false;
+                        const useCacheDefault = args.cache !== false;
+                        const onlyVisible = args.onlyVisible === true;
+                        let projection;
+                        try {
+                            projection = (0, projection_1.parseProjection)(args.select);
                         }
-                        else {
-                            stableSince = null;
+                        catch (e) {
+                            return { error: e instanceof Error ? e.message : String(e) };
                         }
-                        if (now >= deadline) {
-                            return {
-                                ...lastResult,
-                                attempts,
-                                elapsedMs,
-                                timedOut: true,
-                                until: waitUntil,
-                                waited: true,
+                        const { children: childrenOpts, fields, hooks: hookOpts, props: propsOpts, } = projection;
+                        const runtime = { navigationRef, root };
+                        const runOnce = async (useCache) => {
+                            const rawMatches = runCachedQuery(runtime, steps, useCache);
+                            let all = dedup ? (0, query_1.dedupAncestors)(rawMatches) : rawMatches;
+                            const boundsCache = new Map();
+                            const measure = async (fiber) => {
+                                if (boundsCache.has(fiber))
+                                    return boundsCache.get(fiber) ?? null;
+                                const b = await (0, utils_1.measureFiber)(fiber);
+                                boundsCache.set(fiber, b);
+                                return b;
                             };
+                            if (onlyVisible) {
+                                const visibleRect = (0, viewport_1.getVisibleRect)();
+                                if (visibleRect) {
+                                    const rect = visibleRect;
+                                    const measured = await Promise.all(all.map(async (fiber) => {
+                                        return { bounds: await measure(fiber), fiber };
+                                    }));
+                                    all = measured
+                                        .filter(({ bounds }) => {
+                                        return bounds && (0, viewport_1.intersectsRect)(bounds, rect);
+                                    })
+                                        .map(({ fiber }) => {
+                                        return fiber;
+                                    });
+                                }
+                            }
+                            const total = all.length;
+                            const truncated = total > limit;
+                            const picked = truncated ? all.slice(0, limit) : all;
+                            const matches = await Promise.all(picked.map(async (fiber) => {
+                                const result = {};
+                                if (fields.has('bounds')) {
+                                    result.bounds = await measure(fiber);
+                                }
+                                if (fields.has('mcpId')) {
+                                    result.mcpId = fiber.memoizedProps?.['data-mcp-id'];
+                                }
+                                if (fields.has('name')) {
+                                    result.name = (0, utils_1.getComponentName)(fiber);
+                                }
+                                if (fields.has('props')) {
+                                    // Heavy field — projected here via select.props options
+                                    // (path/depth/maxBytes). Top-level response stays raw
+                                    // so mcpId/name/etc are always visible without
+                                    // projection.
+                                    result.props = (0, utils_1.projectFiberValue)(fiber.memoizedProps ?? {}, {
+                                        depth: propsOpts.depth ?? 1,
+                                        maxBytes: propsOpts.maxBytes,
+                                        path: propsOpts.path,
+                                    });
+                                }
+                                if (fields.has('refMethods')) {
+                                    // List of native-ref methods available on the fiber's
+                                    // host instance (focus, blur, measure, scrollTo, ...).
+                                    // null when the fiber has no native instance (composite
+                                    // wrappers, unmounted, virtualized). Feeds directly into
+                                    // `fiber_tree__call({ method })`.
+                                    const instance = (0, utils_1.getNativeInstance)(fiber);
+                                    result.refMethods = instance ? (0, utils_1.getAvailableMethods)(instance) : null;
+                                }
+                                if (fields.has('testID')) {
+                                    result.testID = fiber.memoizedProps?.testID;
+                                }
+                                if (fields.has('hooks')) {
+                                    result.hooks = (0, hooks_1.extractHooks)(fiber, {
+                                        ...hookOpts,
+                                        redactPatterns,
+                                    });
+                                }
+                                if (childrenOpts) {
+                                    result.children = await (0, children_1.walkChildren)(fiber, childrenOpts, childrenOpts.treeDepth, measure);
+                                }
+                                return result;
+                            }));
+                            return truncated ? { matches, total, truncated: true } : { matches, total };
+                        };
+                        const waitForRaw = args.waitFor;
+                        if (!waitForRaw || typeof waitForRaw !== 'object') {
+                            return runOnce(useCacheDefault);
                         }
-                        const remaining = deadline - now;
-                        const sleepMs = Math.min(interval, Math.max(0, remaining));
-                        await new Promise((resolve) => {
-                            return setTimeout(resolve, sleepMs);
+                        // Cache is always bypassed inside the polling loop — `runOnce`
+                        // with cache:true would just keep returning the stale match
+                        // set the cache captured pre-mount.
+                        return (0, waitFor_1.runWaitForLoop)(waitForRaw, () => {
+                            return runOnce(false);
                         });
-                        lastResult = await runOnce(false);
-                        attempts++;
-                    }
+                    };
+                    // No top-level projection on the query response — the response
+                    // shell ({ matches, total, ... }) is light by construction;
+                    // heavy values inside `props` / `hooks` are already collapsed to
+                    // markers by per-field projection in `inner`, and the
+                    // `select.children` walker self-bounds via treeDepth/itemsCap.
+                    // Top-level path/depth/maxBytes are not exposed on `query` —
+                    // drill happens via `select.props.path` / `select.hooks.path`,
+                    // and tree-shape navigation via `select.children`.
+                    return inner();
                 },
                 inputSchema: {
                     cache: {
@@ -1192,40 +343,28 @@ TIPS
                         description: 'Drop wrapper cascades — a fiber is removed when any of its ancestors is also in the match set (PressableView → Pressable → View → RCTView collapses to the topmost). Independent siblings with overlapping bounds are kept. Default true; pass false to keep every match.',
                         type: 'boolean',
                     },
-                    hooksInclude: {
-                        description: 'When select includes "hooks": `kinds` (State | Reducer | Memo | Callback | Ref | Effect | LayoutEffect | InsertionEffect | Context | Transition | DeferredValue | Id | SyncExternalStore | ImperativeHandle | Custom) and `names` (exact or `/regex/flags`) filter the list. Each entry carries { kind, name, hook?, via?, expanded? } — `hook` is the source-level hook function (`useState`, `useAnimatedStyle`); `expanded: true` marks a parent custom-hook call whose sub-hooks follow. Pass `withValues: true` for resolved values. `maxDepthInValues` caps value recursion (default 3, max 8). `expansionDepth` caps how deep custom hooks recurse — 0 = no expansion (top-level only), 1 = one level, default Infinity. `format: "tree"` returns nested `children:` instead of flat `via:`.',
-                        examples: [
-                            { kinds: ['State', 'Memo'] },
-                            { names: ['count', 'scrollRef'], withValues: true },
-                            { kinds: ['State'], names: ['/^is/'], withValues: true },
-                            { expansionDepth: 0 },
-                            { format: 'tree', withValues: true },
-                            { expansionDepth: 1, format: 'tree' },
-                        ],
-                        type: 'object',
-                    },
                     limit: {
-                        description: `Max matches to return (default ${QUERY_LIMIT_DEFAULT}, max ${QUERY_LIMIT_MAX}). truncated: true is added when total exceeds limit.`,
+                        description: `Max matches to return (default ${constants_1.QUERY_LIMIT_DEFAULT}, max ${constants_1.QUERY_LIMIT_MAX}). truncated: true is added when total exceeds limit.`,
                         type: 'number',
                     },
                     onlyVisible: {
                         description: 'Drop matches whose measured bounds do not intersect the current window rectangle (physical pixels). Also drops fibers with no measurable host view — usually virtualized or unmounted. Halves results on long lists.',
                         type: 'boolean',
                     },
-                    propsInclude: {
-                        description: 'When select includes "props", keep only these prop names. Unknown keys are silently dropped. Omit for full serialization.',
-                        examples: [
-                            ['placeholder', 'value'],
-                            ['title', 'disabled'],
-                        ],
-                        type: 'array',
-                    },
                     select: {
-                        description: `Output fields: mcpId, name, testID, props, bounds, hooks. Default ${JSON.stringify(QUERY_DEFAULT_FIELDS)}.`,
+                        description: `Output fields: mcpId, name, testID, props, bounds, hooks, refMethods, children. Default ${JSON.stringify(projection_1.QUERY_DEFAULT_FIELDS)}. Each entry is either a string ("mcpId" — include with defaults) or an object whose keys are field names. Object values are \`true\` / \`false\` / per-field options.\n\nLight fields (mcpId, name, testID, bounds, refMethods) — no options, just toggle. refMethods is the list of native-ref methods (focus, blur, measure, scrollTo, ...) available on the fiber's host instance; null when the fiber has no native instance. Feeds directly into \`fiber_tree__call({ method })\`.\n\nHeavy fields (props, hooks) — per-field projection via shared \`projectValue\` so nested heavy values become \`\${...}\`-keyed markers. Each takes its own \`path\` / \`depth\` / \`maxBytes\`.\n\nprops options: \`{ path?, depth?, maxBytes? }\`.\n\nhooks options: \`{ kinds?, names?, withValues?, expansionDepth?, format?, path?, depth?, maxBytes? }\`. \`kinds\`: State | Reducer | Memo | Callback | Ref | Effect | LayoutEffect | InsertionEffect | Context | Transition | DeferredValue | Id | SyncExternalStore | ImperativeHandle | Custom. \`names\`: exact or \`/regex/flags\`. \`withValues:true\` adds resolved values. \`expansionDepth\` caps custom-hook recursion (default Infinity). \`format:"tree"\` returns nested children instead of flat \`via\`.\n\nchildren — recursive light-only walker for tree-of-tree dumps.\n  Short form: \`{ children: 5 }\` → treeDepth=5, default fields ['mcpId','name'].\n  Object form: \`{ children: { treeDepth?, select?, itemsCap? } }\`.\n  treeDepth max 16; itemsCap default 50; overflow inserts \`\${truncated}\` as the first item.\n  select inside children may include only mcpId / name / testID / bounds / nested children. props/hooks throw at parse time — run a second query against a child's mcpId to inspect them.\n\nEach hook entry carries \`{ kind, name, hook?, via?, expanded? }\`.`,
                         examples: [
                             ['mcpId', 'name', 'bounds'],
-                            ['mcpId', 'name', 'props'],
-                            ['mcpId', 'hooks'],
+                            ['mcpId', 'refMethods'],
+                            ['mcpId', { props: { path: 'style' } }],
+                            ['mcpId', { props: { depth: 3 } }],
+                            [{ hooks: { kinds: ['State'], withValues: true }, mcpId: true }],
+                            [{ children: 5 }],
+                            [
+                                'mcpId',
+                                'name',
+                                { children: { select: ['mcpId', 'name', 'testID'], treeDepth: 3 } },
+                            ],
                         ],
                         type: 'array',
                     },
@@ -1240,7 +379,7 @@ TIPS
                         type: 'array',
                     },
                     waitFor: {
-                        description: `Poll the query until a predicate holds, instead of reading once. \`until\` selects the target state: "appear" waits for \`total >= 1\`, "disappear" waits for \`total === 0\`. \`timeout\` (default ${WAIT_TIMEOUT_DEFAULT}ms, max ${WAIT_TIMEOUT_MAX}ms) caps the wait. \`interval\` (default ${WAIT_INTERVAL_DEFAULT}ms, min ${WAIT_INTERVAL_MIN}ms) is the gap between polls. \`stable\` (default 0) requires the predicate to hold continuously for this many ms before returning — useful to ignore transient matches during screen transitions. Cache is always bypassed while polling. On success the response carries the usual query fields plus \`{ waited: true, until, attempts, elapsedMs, timedOut: false, stableFor? }\`; on timeout \`timedOut: true\` with the last observed matches.`,
+                        description: `Poll the query until a predicate holds, instead of reading once. \`until\` selects the target state: "appear" waits for \`total >= 1\`, "disappear" waits for \`total === 0\`. \`timeout\` (default ${constants_1.WAIT_TIMEOUT_DEFAULT}ms, max ${constants_1.WAIT_TIMEOUT_MAX}ms) caps the wait. \`interval\` (default ${constants_1.WAIT_INTERVAL_DEFAULT}ms, min ${constants_1.WAIT_INTERVAL_MIN}ms) is the gap between polls. \`stable\` (default 0) requires the predicate to hold continuously for this many ms before returning — useful to ignore transient matches during screen transitions. Cache is always bypassed while polling. On success the response carries the usual query fields plus \`{ waited: true, until, attempts, elapsedMs, timedOut: false, stableFor? }\`; on timeout \`timedOut: true\` with the last observed matches.`,
                         examples: [
                             { until: 'appear' },
                             { timeout: 5000, until: 'disappear' },