react-native-mcp-kit 2.3.1 → 3.0.1

package/dist/modules/fiberTree/fiberTree.js

@@ -10,6 +10,475 @@ 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).',
@@ -25,6 +494,38 @@ const FIND_SCHEMA = {
         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')
@@ -143,6 +644,14 @@ const fiberTreeModule = (options) => {
         (0, utils_1.setRootRef)(options.rootRef);
     }
     const navigationRef = options?.navigationRef;
+    // Compile the redact pattern list once at module init. Precedence:
+    //   - `redactHookNames` provided → use it verbatim (replace mode).
+    //   - `additionalRedactHookNames` provided → defaults + user's.
+    //   - Neither → defaults.
+    // Pass `redactHookNames: []` to disable redaction entirely.
+    const redactPatterns = compileRedactPatterns(options?.redactHookNames !== undefined
+        ? options.redactHookNames
+        : [...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.
@@ -250,13 +759,15 @@ 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 and bounds are opt-in.
+  Default ["mcpId", "name", "testID"] — props, bounds, hooks 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.
 
 RESPONSE
   { matches: [...], total, truncated? } — total is the unrestricted match
@@ -508,6 +1019,23 @@ TIPS
                     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);
@@ -567,6 +1095,17 @@ TIPS
                             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 };
@@ -653,6 +1192,18 @@ 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.`,
                         type: 'number',
@@ -670,10 +1221,11 @@ TIPS
                         type: 'array',
                     },
                     select: {
-                        description: `Output fields: mcpId, name, testID, props, bounds. Default ${JSON.stringify(QUERY_DEFAULT_FIELDS)}.`,
+                        description: `Output fields: mcpId, name, testID, props, bounds, hooks. Default ${JSON.stringify(QUERY_DEFAULT_FIELDS)}.`,
                         examples: [
                             ['mcpId', 'name', 'bounds'],
                             ['mcpId', 'name', 'props'],
+                            ['mcpId', 'hooks'],
                         ],
                         type: 'array',
                     },