@codeyam/codeyam-cli 0.1.0-staging.8aea589 → 0.1.0-staging.8df382d

package/background/src/lib/virtualized/project/constructMockCode.js

@@ -1,4 +1,116 @@
-import { joinParenthesesAndArrays, splitOutsideParenthesesAndArrays, functionArguments, cleanOutBoundary, fillInDirectSchemaGapsAndUnknowns, } from "../../../../../packages/ai/index.js";
+import { joinParenthesesAndArrays, splitOutsideParenthesesAndArrays, functionArguments, cleanOutBoundary, fillInDirectSchemaGapsAndUnknowns, removeDuplicateFunctionCalls, } from "../../../../../packages/ai/index.js";
+/**
+ * Converts a call signature to a valid JavaScript identifier (function name).
+ * The original signature is preserved for data access - this only creates the function name.
+ *
+ * Examples:
+ * - "useAuth()" → "useAuth"
+ * - "db.select(usersQuery)" → "db_select_usersQuery"
+ * - "db.select(postsQuery)" → "db_select_postsQuery"
+ * - "useFetcher<User>()" → "useFetcher_User"
+ * - "useFetcher<{ data: UserData | null }>()" → "useFetcher_data_UserData_null"
+ * - "eq('user_id', value)" → "eq_user_id_value"
+ * - "from('workouts')" → "from_workouts"
+ */
+function callSignatureToFunctionName(signature) {
+    // Extract components from the signature
+    const components = [];
+    // 1. Extract function path (parts separated by dots outside parens/brackets)
+    const pathMatch = signature.match(/^([^<(]+)/);
+    if (pathMatch) {
+        const path = pathMatch[1];
+        // Split on dots but preserve the parts
+        components.push(...path.split('.').filter(Boolean));
+    }
+    // 2. Extract generic type parameters (content between < and >)
+    const genericMatch = signature.match(/<([^>]+)>/);
+    if (genericMatch) {
+        const genericContent = genericMatch[1];
+        // Extract meaningful identifiers from generic type
+        // Handle complex types like "{ data: UserData | null }"
+        const typeIdentifiers = genericContent
+            .replace(/[{}:;,]/g, ' ') // Remove structural chars
+            .replace(/\|/g, ' ') // Handle union types
+            .split(/\s+/)
+            .filter(Boolean)
+            .filter((s) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(s)) // Only valid identifiers
+            .filter((s) => ![
+            'null',
+            'undefined',
+            'void',
+            'never',
+            'any',
+            'unknown',
+            'data',
+            'typeof',
+        ].includes(s)); // Skip common non-meaningful keywords
+        if (typeIdentifiers.length > 0) {
+            components.push(...typeIdentifiers.slice(0, 2)); // Limit to first 2 for reasonable length
+        }
+    }
+    // 3. Extract function arguments (first 2 for disambiguation)
+    const argsMatch = signature.match(/\(([^)]*)\)/);
+    if (argsMatch && argsMatch[1]) {
+        const argsContent = argsMatch[1].trim();
+        if (argsContent) {
+            const args = argsContent.split(',').map((arg) => arg.trim());
+            for (const arg of args.slice(0, 2)) {
+                // For quoted strings, extract the content
+                const stringMatch = arg.match(/^['"`](.+)['"`]$/);
+                if (stringMatch) {
+                    // Split on dots for string paths like 'users.id'
+                    const parts = stringMatch[1].split('.').filter(Boolean);
+                    components.push(...parts);
+                }
+                else if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(arg)) {
+                    // Valid identifier - use as-is
+                    components.push(arg);
+                }
+                else if (/^\d+$/.test(arg)) {
+                    // Number - use as-is
+                    components.push(arg);
+                }
+                // Skip complex expressions
+            }
+        }
+    }
+    // Build the function name from components
+    const functionName = components
+        .join('_')
+        .replace(/[^a-zA-Z0-9_]/g, '_') // Sanitize special chars
+        .replace(/_+/g, '_') // Collapse multiple underscores
+        .replace(/^_|_$/g, ''); // Trim underscores
+    return functionName || 'mock';
+}
+/**
+ * Check if a mock name is a call signature (e.g., "useFetcher<User>()", "db.select(query)")
+ */
+function isCallSignature(mockName) {
+    // Call signatures contain parentheses (function calls)
+    return mockName.includes('(');
+}
+/**
+ * Extract property names that are jsx-components and should be preserved from original.
+ * These are paths like "MockName.Provider()" where the value or functionCallReturnValue is 'jsx-component'.
+ */
+function getJsxComponentProperties(mockName, schema) {
+    const jsxProperties = [];
+    for (const [path, value] of Object.entries(schema ?? {})) {
+        // Look for paths like "MockName.PropertyName()" that are jsx-components
+        // Skip paths that have deeper nesting (e.g., "MockName.Foo.Bar()")
+        const match = path.match(new RegExp(`^${mockName}\\.([^.()]+)\\(\\)$`));
+        if (!match)
+            continue;
+        const propertyName = match[1];
+        // Check if this is a jsx-component (either directly or via functionCallReturnValue)
+        const isJsxComponent = value === 'jsx-component' ||
+            schema[path + '.functionCallReturnValue'] === 'jsx-component';
+        if (isJsxComponent && !jsxProperties.includes(propertyName)) {
+            jsxProperties.push(propertyName);
+        }
+    }
+    return jsxProperties;
+}
 /**
  * Check if a string is a literal (quoted string or number).
  * Returns the unquoted value if it's a literal, null otherwise.
@@ -103,21 +215,62 @@ function funcArgs(functionSignature) {
 }
 // isValidKey ensures that the key does not contain any characters that would make it invalid in a JavaScript object.
 // For example, it should not contain spaces, special characters, or start with a number.
+// Also rejects keys that are pure function calls like "()" or "(args)" - these aren't property names.
 function isValidKey(key) {
     if (!key || key.length === 0)
         return false;
     const keyWithOutArguments = key.split('(')[0];
+    // Reject empty keys (happens when key is "()" or "(args)") - these are function calls, not property names
+    if (!keyWithOutArguments || keyWithOutArguments.length === 0)
+        return false;
     return !/\s/.test(keyWithOutArguments);
 }
-export default function constructMockCode(mockName, dependencySchemas) {
-    const mockNameParts = splitOutsideParenthesesAndArrays(mockName);
+/**
+ * Known hooks that return tuples [value, setter] instead of arrays.
+ * These should NOT use the .map() pattern even when the schema has generic array access ([]).
+ * Instead, they should return [data, () => {}] where data is from scenarios().
+ */
+const TUPLE_RETURNING_HOOKS = new Set([
+    'useAtom', // Jotai
+    'useState', // React
+    'useReducer', // React
+    'useRecoilState', // Recoil
+    'useImmerAtom', // Jotai with Immer
+]);
+export default function constructMockCode(mockName, dependencySchemas, entityType, _canonicalKey, // DEPRECATED: No longer used, kept for API compatibility
+options) {
+    // Check if mockName is a call signature (e.g., "useFetcher<User>()", "db.select(query)")
+    const mockNameIsCallSignature = isCallSignature(mockName);
+    // For call signatures, use the original signature for data access but generate
+    // a valid JS function name from it
+    const derivedFunctionName = mockNameIsCallSignature
+        ? callSignatureToFunctionName(mockName)
+        : null;
+    // The baseMockName is the function name without type params and args
+    // e.g., "useFetcher<User>()" -> "useFetcher", "db.select(query)" -> "db"
+    const baseMockName = mockName.split(/[<(]/)[0];
+    // The data key is the mockName (call signature) for data access
+    let dataKey;
+    const mockNameParts = splitOutsideParenthesesAndArrays(baseMockName);
     let relevantReturnValueSchema;
     let dataStructurePath;
     let dataStructureValue;
-    for (const filePath in dependencySchemas) {
+    let foundEntityWithSignature = false;
+    let signatureSchema;
+    entitySearch: for (const filePath in dependencySchemas) {
         for (const entityName in dependencySchemas[filePath]) {
-            if (entityName !== mockNameParts[0])
+            // Match entity by base name (without generics/args)
+            const entityBaseName = entityName.split(/[<(]/)[0];
+            const matches = entityBaseName === baseMockName || entityName === mockNameParts[0];
+            if (!matches)
                 continue;
+            // Track if we found the entity and it has a signature (is a function)
+            const entitySchema = dependencySchemas[filePath][entityName];
+            if (entitySchema?.signatureSchema &&
+                Object.keys(entitySchema.signatureSchema).length > 0) {
+                foundEntityWithSignature = true;
+                signatureSchema = entitySchema.signatureSchema;
+            }
             dataStructurePath = Object.keys(dependencySchemas[filePath][entityName]?.returnValueSchema ?? {}).find((path) => {
                 if (path === 'returnValue')
                     return true;
@@ -131,16 +284,122 @@ export default function constructMockCode(mockName, dependencySchemas) {
                 relevantReturnValueSchema = fillInDirectSchemaGapsAndUnknowns({
                     schema: dependencySchemas[filePath][entityName]?.returnValueSchema,
                 });
-                // NOTE: Temporarily disabled clearAttributesFromMapping as it deletes
+                // NOTE: clearAttributesFromMapping is disabled because it deletes
                 // method calls on arrays (like .eq() after functionCallReturnValue: 'array')
-                // clearAttributesFromMapping(relevantReturnValueSchema)
+                // However, we still need to remove duplicate function calls that create invalid syntax
+                removeDuplicateFunctionCalls(relevantReturnValueSchema);
                 dataStructureValue = relevantReturnValueSchema?.[dataStructurePath];
-                break;
+                break entitySearch;
             }
         }
     }
-    if (!relevantReturnValueSchema || !dataStructurePath)
+    // Check if the entity is used as a function (called with ()) vs an object/namespace.
+    // Look for paths in the schema that start with "baseMockName(" or "baseMockName<" indicating function calls.
+    // The "<" handles generic type parameters like useLoaderData<T>().
+    // Also check dataStructurePath === 'returnValue' which indicates a function return value.
+    const entityIsFunction = foundEntityWithSignature ||
+        dataStructurePath === 'returnValue' ||
+        Object.keys(relevantReturnValueSchema ?? {}).some((key) => key.startsWith(`${baseMockName}(`) ||
+            key.startsWith(`${baseMockName}<`));
+    // Calculate the data key - use the call signature (mockName) for data access
+    // For simple names without parentheses:
+    // - Append () ONLY if the entity is a function/hook (detected above)
+    // - Don't append () for object/namespace mocks like "supabase"
+    if (mockNameIsCallSignature || mockName.includes('(')) {
+        dataKey = mockName;
+    }
+    else if (entityIsFunction) {
+        // Entity is a function/hook - append () to match call signature format
+        dataKey = `${mockName}()`;
+    }
+    else {
+        // Entity is an object/namespace - use bare name as key
+        dataKey = mockName;
+    }
+    // Helper to wrap key in appropriate quotes for computed property access
+    // Use single quotes when key contains double quotes to avoid syntax errors
+    const quotePropertyKey = (key) => {
+        const escaped = key.replace(/\n/g, '\\n');
+        if (escaped.includes('"')) {
+            // Use single quotes, escaping any single quotes in the key
+            return `['${escaped.replace(/'/g, "\\'")}']`;
+        }
+        return `["${escaped}"]`;
+    };
+    // Check if the return value schema only contains function type markers
+    // (e.g., "validateInputs()": "function") without actual return data
+    // (no functionCallReturnValue entries)
+    const hasMeaningfulReturnData = (schema) => {
+        if (!schema)
+            return false;
+        const keys = Object.keys(schema);
+        // Check if there are any functionCallReturnValue entries
+        // which indicate actual mock data, not just type markers
+        return keys.some((key) => key.includes('functionCallReturnValue') || key === 'returnValue');
+    };
+    // If we found the entity with a signature but no return value schema,
+    // OR the schema only has function type markers without actual return data,
+    // generate an empty mock function. This handles validation functions like
+    // validateInputs that are marked for mocking but have no meaningful return value.
+    // EXCEPTION: If entityType is 'class', we still need to generate the class.
+    // EXCEPTION: If no signature was found, let the normal code path handle it.
+    if (!relevantReturnValueSchema || !dataStructurePath) {
+        if (foundEntityWithSignature && signatureSchema) {
+            // Count the number of arguments from signature schema
+            const argCount = Object.keys(signatureSchema).filter((key) => key.startsWith('signature[')).length;
+            const args = Array.from({ length: argCount }, (_, i) => `arg${i + 1}`);
+            // Always add ...rest to accept extra arguments beyond the signature
+            args.push('...rest');
+            const argsString = args.join(', ');
+            // Generate empty mock function
+            return `function ${mockName}(${argsString}) {
+  // Empty mock - original function mocked out
+}`;
+        }
         return;
+    }
+    // Check if the schema only has function type markers without actual return data.
+    // Only apply this when we have a signature (i.e., it's explicitly a function)
+    // and it's not a class. This handles validation functions that should be
+    // empty mocks rather than returning meaningless "function" strings.
+    if (foundEntityWithSignature &&
+        signatureSchema &&
+        entityType !== 'class' &&
+        !hasMeaningfulReturnData(relevantReturnValueSchema)) {
+        const argCount = Object.keys(signatureSchema).filter((key) => key.startsWith('signature[')).length;
+        const args = Array.from({ length: argCount }, (_, i) => `arg${i + 1}`);
+        // Always add ...rest to accept extra arguments beyond the signature
+        args.push('...rest');
+        const argsString = args.join(', ');
+        // Check for Higher-Order Component (HOC) pattern:
+        // - First argument is a function (component) or unknown (couldn't trace type)
+        // - Returns a function
+        // HOCs like memo, forwardRef, createContext should return their first argument
+        //
+        // The return value key can be either:
+        // - 'memo()' (clean format)
+        // - 'memo(({ value, width }: Props) => { ... })' (full component code format)
+        const firstArgIsFunctionOrUnknown = signatureSchema['signature[0]'] === 'function' ||
+            signatureSchema['signature[0]'] === 'unknown';
+        const returnsFunction = relevantReturnValueSchema
+            ? Object.entries(relevantReturnValueSchema).some(([key, value]) => {
+                // Check if key represents a function call that returns a function
+                // Key should start with the mock name, contain '(', end with ')', and have value 'function'
+                const isFunctionCall = key.startsWith(mockName + '(') && key.endsWith(')');
+                return isFunctionCall && value === 'function';
+            })
+            : false;
+        if (firstArgIsFunctionOrUnknown && returnsFunction) {
+            // HOC pattern detected - return the first argument
+            return `function ${mockName}(${argsString}) {
+  return arg1;
+}`;
+        }
+        // Generate empty mock function
+        return `function ${mockName}(${argsString}) {
+  // Empty mock - original function mocked out
+}`;
+    }
     const dataStructureName = dataStructurePath === 'returnValue'
         ? mockName
         : joinParenthesesAndArrays(splitOutsideParenthesesAndArrays(dataStructurePath).slice(0, mockNameParts.length));
@@ -152,6 +411,87 @@ export default function constructMockCode(mockName, dependencySchemas) {
     const pathDepth = splitOutsideParenthesesAndArrays(dataStructurePath).length;
     const isRootArray = dataStructureValue === 'array' &&
         (dataStructurePath === 'returnValue' || pathDepth <= mockNameParts.length);
+    // OPTIMIZATION: Early return for tuple-returning hooks (useAtom, useState, etc.)
+    // These hooks have simple [value, setter] return patterns that don't need the full
+    // 9216-key schema processing. Check if this is a tuple-returning hook and generate
+    // the mock code directly without iterating over all schema keys.
+    if (TUPLE_RETURNING_HOOKS.has(baseMockName) && isFunction) {
+        // Check if schema has generic array pattern (indicates tuple return like [value, setter])
+        const schemaKeys = Object.keys(relevantReturnValueSchema ?? {});
+        const hasGenericArrayInSchema = schemaKeys.some((k) => k.includes('.functionCallReturnValue[]') ||
+            k === `${dataKey}.functionCallReturnValue[]` ||
+            k === 'returnValue[]');
+        // Check for differentiated tuple indices (e.g., functionCallReturnValue[2], [3]) which would NOT be a standard tuple
+        // We only check indices immediately after functionCallReturnValue, not nested indices like signature[2]
+        const tupleHasDifferentiatedIndices = schemaKeys.some((k) => {
+            // Look for .functionCallReturnValue[N] where N >= 2
+            const match = k.match(/\.functionCallReturnValue\[(\d+)\]/);
+            if (!match)
+                return false;
+            const idx = parseInt(match[1], 10);
+            return idx >= 2;
+        });
+        const isTupleReturningHook = hasGenericArrayInSchema && !tupleHasDifferentiatedIndices;
+        if (isTupleReturningHook) {
+            // Find all call patterns for this hook (e.g., useAtom(quoteFilterAtom), useAtom(supplierAtom))
+            const hookCallPatterns = Object.keys(relevantReturnValueSchema ?? {})
+                .filter((k) => {
+                const regex = new RegExp(`^${baseMockName}\\([^)]+\\)$`);
+                return regex.test(k);
+            })
+                .map((k) => {
+                const match = k.match(/\(([^)]+)\)/);
+                return { key: k, arg: match?.[1] ?? '' };
+            });
+            let tupleReturnCode;
+            if (hookCallPatterns.length > 1) {
+                // Multiple patterns - generate conditional dispatch
+                const conditions = hookCallPatterns
+                    .map(({ key, arg }) => `if (argLabel === '${arg}' || argStr.includes('${arg}')) {\n    return [scenarios().data()?.["${key}"]?.[0] ?? [], () => {}];\n  }`)
+                    .join('\n  ');
+                const fallbackKey = hookCallPatterns[0]?.key ?? dataKey;
+                tupleReturnCode = `(() => {
+  // Dynamic dispatch for tuple-returning hook with multiple argument patterns
+  const argLabel = args[0]?.debugLabel ?? '';
+  const argStr = args[0]?.toString?.() ?? String(args[0] ?? '');
+  ${conditions}
+  return [scenarios().data()?.["${fallbackKey}"]?.[0] ?? [], () => {}];
+})()`;
+            }
+            else {
+                // Single or no patterns - use dynamic dispatch
+                const fallbackKey = hookCallPatterns[0]?.key ?? `${baseMockName}()`;
+                tupleReturnCode = `(() => {
+  // Dynamic dispatch for tuple-returning hook
+  const argLabel = args[0]?.debugLabel ?? '';
+  const argStr = args[0]?.toString?.() ?? '';
+  const allData = scenarios().data() ?? {};
+  if (argLabel) {
+    const labelKey = '${baseMockName}(' + argLabel + ')';
+    if (allData[labelKey]) {
+      return [allData[labelKey]?.[0] ?? [], () => {}];
+    }
+  }
+  const keys = Object.keys(allData).filter(k => k.startsWith('${baseMockName}('));
+  for (const key of keys) {
+    const keyArg = key.slice(${baseMockName.length + 1}, -1);
+    if (argStr.includes(keyArg)) {
+      return [allData[key]?.[0] ?? [], () => {}];
+    }
+  }
+  return [allData[keys[0] ?? '${fallbackKey}']?.[0] ?? [], () => {}];
+})()`;
+            }
+            const safeFunctionName = options?.uniqueFunctionSuffix
+                ? `${baseMockName}_${options.uniqueFunctionSuffix}`
+                : options?.keepOriginalFunctionName
+                    ? baseMockName
+                    : mockNameIsCallSignature && derivedFunctionName
+                        ? derivedFunctionName
+                        : baseMockName;
+            return `function ${safeFunctionName}(...args) {\n  return ${tupleReturnCode};\n}`;
+        }
+    }
     const returnValueParts = {
         name: dataStructureName,
         isArray: isRootArray,
@@ -165,17 +505,26 @@ export default function constructMockCode(mockName, dependencySchemas) {
         if (root) {
             basePaths[0] = 'scenarios().data()';
         }
-        const optionalAccess = (name, stripArguments = false) => {
+        const optionalAccess = (name, stripArguments = false, isRootAccess = false) => {
             if (stripArguments && name.includes('(')) {
                 name = name.split('(')[0] + '()';
             }
             // Strip type parameters like <typeof loader> from function names
             // so "useLoaderData<typeof loader>()" becomes "useLoaderData()"
             name = cleanOutTypes(name);
-            if (name.match(/\[\d+\]/)) {
+            // For root data access, use the dataKey (original call signature or canonical key)
+            // This preserves the original call signature for LLM clarity
+            if (isRootAccess) {
+                // For call signature format, use the original mockName as the data key
+                // e.g., scenarios().data()?.["useFetcher<User>()"]
+                // e.g., scenarios().data()?.["db.select(usersQuery)"]
+                return `?.${quotePropertyKey(dataKey)}`;
+            }
+            // Only use unquoted array access syntax for pure array indices like [0], [1]
+            if (name.match(/^\[\d+\]$/)) {
                 return `?.${name}`;
             }
-            return `?.["${name.replace(/\n/g, '\\n')}"]`;
+            return `?.${quotePropertyKey(name)}`;
         };
         const constructDataPaths = () => {
             // For structural elements, return modified base paths for children
@@ -187,7 +536,13 @@ export default function constructMockCode(mockName, dependencySchemas) {
                 return [];
             }
             const addReturnValueFunctionAccessor = (dataPath) => {
-                if (returnValue.returnsFunctionArgs) {
+                // Add function call accessor if:
+                // - There are actual arguments, OR
+                // - This is a callable (not a method that returns an array directly)
+                // For methods like getAll() that return arrays, the data is at ["getAll()"] not ["getAll()"]["()"]
+                if (returnValue.returnsFunctionArgs &&
+                    (returnValue.returnsFunctionArgs.length > 0 ||
+                        !returnValue.returnsFunctionArray)) {
                     if (returnValue.isArray) {
                         dataPath = `${dataPath}${optionalAccess('[0]')}`;
                     }
@@ -198,7 +553,8 @@ export default function constructMockCode(mockName, dependencySchemas) {
             return basePaths
                 .flatMap((basePath) => {
                 if (!returnValue.args) {
-                    let dataPath = `${basePath}${optionalAccess(safeString(returnValue.name))}`;
+                    // Pass root as both stripArguments and isRootAccess for non-function paths
+                    let dataPath = `${basePath}${optionalAccess(safeString(returnValue.name), false, root)}`;
                     dataPath = addReturnValueFunctionAccessor(dataPath);
                     return dataPath;
                 }
@@ -206,7 +562,8 @@ export default function constructMockCode(mockName, dependencySchemas) {
                     const signature = returnValue.name.match(/\[\d*\]$/)
                         ? returnValue.name
                         : `${returnValue.name}(${argSet.join(', ')})`;
-                    let dataPath = `${basePath}${optionalAccess(safeString(signature), root)}`;
+                    // Pass root as both stripArguments and isRootAccess
+                    let dataPath = `${basePath}${optionalAccess(safeString(signature), root, root)}`;
                     dataPath = addReturnValueFunctionAccessor(dataPath);
                     return dataPath;
                 });
@@ -214,14 +571,67 @@ export default function constructMockCode(mockName, dependencySchemas) {
                 .filter(Boolean);
         };
         const constructContent = (dataPaths) => {
-            const { name, args, nested, isArray, isGenericArray, returnsFunctionArgs, returnsFunctionArray, isAsyncFunction, } = returnValue;
-            const nestedContent = (nested ?? []).map((nestedItem) => {
+            const { name, args, nested, isArray, isGenericArray, returnsFunctionArgs, returnsFunctionArray, isAsyncFunction, hasNoReturnData, } = returnValue;
+            // When an array has differentiated indices ([0], [1], etc.), filter out any
+            // non-index items from nested. These non-index items come from generic [] paths
+            // like [].filter or [].sort, which describe element properties, not array elements.
+            // Including them would generate invalid syntax like "sort: ..." inside an array literal.
+            const hasDifferentiatedIndices = isArray &&
+                nested &&
+                nested.some((n) => n.name.match(/^\[\d+\]$/) && n.name !== '[0]');
+            const filteredNested = hasDifferentiatedIndices && nested
+                ? nested.filter((n) => n.name.match(/^\[\d+\]$/))
+                : nested;
+            const nestedContent = (filteredNested ?? []).map((nestedItem) => {
                 const nestedContent = constructReturnValueString(nestedItem, dataPaths);
                 return nestedContent;
             });
+            // Array prototype methods that should be ignored when building mocks
+            // (these work on any array - we don't need to mock them)
+            const ARRAY_PROTOTYPE_METHODS = new Set([
+                'at',
+                'concat',
+                'copyWithin',
+                'entries',
+                'every',
+                'fill',
+                'filter',
+                'find',
+                'findIndex',
+                'findLast',
+                'findLastIndex',
+                'flat',
+                'flatMap',
+                'forEach',
+                'includes',
+                'indexOf',
+                'join',
+                'keys',
+                'lastIndexOf',
+                'map',
+                'pop',
+                'push',
+                'reduce',
+                'reduceRight',
+                'reverse',
+                'shift',
+                'slice',
+                'some',
+                'sort',
+                'splice',
+                'toLocaleString',
+                'toReversed',
+                'toSorted',
+                'toSpliced',
+                'toString',
+                'unshift',
+                'values',
+                'with',
+                'length',
+            ]);
             const levelContentItems = [];
             // Add spread for data paths when:
-            // - Not a function returning an array
+            // - Not a function returning an array, OR function returns array with custom methods
             // - Has function args OR not an array
             // - Not structural, OR is a structural [0] element with nested content
             //   (array elements with nested functions need their other properties spread)
@@ -229,64 +639,615 @@ export default function constructMockCode(mockName, dependencySchemas) {
                 returnValue.name === '[0]' &&
                 nested &&
                 nested.length > 0;
-            if (!returnsFunctionArray &&
+            // Check if function returns array but has custom methods (not just array prototype methods)
+            // Excludes array indices like [0], [1], [] which are not methods
+            const hasCustomMethodsOnArrayReturn = returnsFunctionArray &&
+                nested &&
+                nested.length > 0 &&
+                nested.some((n) => {
+                    // Skip array indices - they're not methods
+                    if (n.name.match(/^\[\d*\]$/))
+                        return false;
+                    const methodName = n.name.replace(/[<(].*$/, '');
+                    return !ARRAY_PROTOTYPE_METHODS.has(methodName);
+                });
+            if ((!returnsFunctionArray || hasCustomMethodsOnArrayReturn) &&
                 (returnsFunctionArgs || !isArray) &&
                 (!returnValue.isStructural || isStructuralArrayElementWithNested)) {
                 levelContentItems.push(...dataPaths.map((path) => `...${path}`));
             }
-            levelContentItems.push(...nestedContent);
+            // Filter out nested content that would be invalid as object properties
+            // (e.g., bare arrow functions like "() => {...}" without a property name)
+            // Only apply this filter when building object content, not array content.
+            // Bare arrow functions ARE valid as array elements (like [0] = {...}, [1] = () => {...})
+            // Check both isArray (item IS an array) and returnsFunctionArray (item returns an array)
+            const inArrayContext = isArray || returnsFunctionArray;
+            const validNestedContent = nestedContent.filter((content) => {
+                if (!content)
+                    return false;
+                // Only filter bare arrow functions when NOT in array context
+                // In arrays, bare arrow functions are valid elements
+                if (!inArrayContext && content.match(/^\s*\([^)]*\)\s*=>/)) {
+                    return false;
+                }
+                return true;
+            });
+            levelContentItems.push(...validNestedContent);
             let levelContents = levelContentItems.filter(Boolean).join(',\n');
             if (returnsFunctionArgs) {
-                const argsString = returnsFunctionArgs
-                    .map((_, index) => `arg${index + 1}`)
-                    .join(', ');
-                let funcContents = '';
-                if (returnsFunctionArray) {
-                    if (levelContents.length === 0) {
-                        funcContents = 'return []';
-                    }
-                    else {
-                        funcContents = `return [\n${indent(levelContents)}\n]`;
+                // When returnsFunctionArgs is empty [] OR has a single literal string argument,
+                // the function returns a callable function (e.g., getTranslate() returns t,
+                // where t('key') looks up translations)
+                // Generate a dispatch function that looks up keys based on the argument
+                //
+                // Detect translation-like pattern:
+                // - Data path ends with ["('some.literal')"] - a literal string key
+                // - This means the mock data has keys like "('common.surveys')": "Surveys"
+                // - Exclude ["()"] which is an empty function call (not a translation pattern)
+                const dataPath = dataPaths[0];
+                // Pattern matches ?.["('...')"] at end of path, but NOT ?.["()"] (empty args)
+                const literalKeyPattern = dataPath?.match(/\?\.\["\('.+'\)"\]$/);
+                if (!returnsFunctionArray &&
+                    dataPaths.length === 1 &&
+                    literalKeyPattern // Only dispatch when there's a literal key pattern
+                ) {
+                    // Function returns a function - generate dispatch function
+                    // Strip the literal key from the path and use dynamic lookup
+                    const dataPathBase = literalKeyPattern
+                        ? dataPath.replace(/\?\.\["\('.+'\)"\]$/, '')
+                        : dataPath;
+                    const funcContents = `return ${dataPathBase}?.[\`('\${arg1}')\`]`;
+                    levelContents = `(arg1) => {\n${indent(funcContents)}\n}`;
+                    if (!isArray) {
+                        return levelContents;
                     }
                 }
                 else {
-                    if (levelContentItems.length === 1 && dataPaths.length === 1) {
-                        funcContents = `return ${dataPaths[0]}`;
+                    const argsString = returnsFunctionArgs
+                        .map((_, index) => `arg${index + 1}`)
+                        .join(', ');
+                    let funcContents = '';
+                    if (returnsFunctionArray) {
+                        if (hasNoReturnData) {
+                            // Function has no return data (only signatures) - return empty array
+                            funcContents = 'return []';
+                        }
+                        else if (levelContents.length === 0 && dataPaths.length === 1) {
+                            // When returning an array with no nested content, return the data path directly
+                            // (the data path points to the array in scenario data)
+                            funcContents = `return ${dataPaths[0]}`;
+                        }
+                        else if (levelContents.length === 0) {
+                            funcContents = 'return []';
+                        }
+                        else {
+                            funcContents = `return [\n${indent(levelContents)}\n]`;
+                        }
                     }
                     else {
-                        funcContents = `return {\n${indent(levelContents)}\n}`;
+                        // Check if function has no actual return data (only signatures)
+                        const hasNestedItems = nested && nested.length > 0;
+                        const hasActualNestedContent = nestedContent.filter(Boolean).length > 0;
+                        if (levelContentItems.length === 1 && dataPaths.length === 1) {
+                            if (hasNoReturnData ||
+                                (hasNestedItems && !hasActualNestedContent)) {
+                                // Function has no return data (only signatures) - return empty array
+                                funcContents = 'return []';
+                            }
+                            else {
+                                // Has return data - return data path
+                                funcContents = `return ${dataPaths[0]}`;
+                            }
+                        }
+                        else {
+                            funcContents = `return {\n${indent(levelContents)}\n}`;
+                        }
+                    }
+                    levelContents = `(${argsString}) => {\n${indent(funcContents)}\n}`;
+                    if (!isArray) {
+                        return levelContents;
                     }
                 }
-                levelContents = `(${argsString}) => {\n${indent(funcContents)}\n}`;
-                if (!isArray) {
-                    return levelContents;
+                // For generic arrays of functions WITH nested properties (e.g., functionCallReturnValue[] = "function"
+                // with nested .filter, .sort, etc.), the levelContents would be a bare arrow function "() => {...}"
+                // that wraps object content. Using this in a .map(({...})) creates invalid syntax like "({ () => {...} })".
+                // When isGenericArray is true AND there are nested properties, we're accessing data from the elements,
+                // not calling them - so skip the function wrapping.
+                // But if there are NO nested properties, keep the wrapper because callers may want to call the elements.
+                const hasNonStructuralNestedItems = nested &&
+                    nested.length > 0 &&
+                    nested.some((n) => !n.name.match(/^\[\d*\]$/));
+                if (isGenericArray && hasNonStructuralNestedItems) {
+                    // Skip the arrow function wrapper - just use the nested content directly
+                    levelContents = levelContentItems.filter(Boolean).join(',\n');
                 }
             }
+            // Check if all nested items are array prototype methods
+            const hasOnlyArrayPrototypeMethods = returnsFunctionArray &&
+                nested &&
+                nested.length > 0 &&
+                nested.every((n) => {
+                    // Extract method name before type params and args (e.g., "reduce<...>(...)" -> "reduce")
+                    const methodName = n.name.replace(/[<(].*$/, '');
+                    return ARRAY_PROTOTYPE_METHODS.has(methodName);
+                });
             let returnValueContents = '';
-            if (!returnsFunctionArgs &&
+            // Check if this is a known tuple-returning hook (useAtom, useState, etc.)
+            // These should return [value, setter] tuples, not arrays or data paths
+            // Check isGenericArray from current context OR from schema for root level calls
+            // (at root level, isGenericArray might not be set yet but the schema contains [] pattern)
+            const hasGenericArrayInSchema = root &&
+                TUPLE_RETURNING_HOOKS.has(baseMockName) &&
+                Object.keys(relevantReturnValueSchema ?? {}).some((k) => k.includes('.functionCallReturnValue[]'));
+            // Check if there are array indices beyond what a standard 2-element tuple would have
+            // For tuple-returning hooks, [0] and [1] are expected (value and setter)
+            // Only consider it "differentiated" if there are indices >= 2 (e.g., [2], [3])
+            const tupleHasDifferentiatedIndices = nested?.some((n) => {
+                const indexMatch = n.name.match(/^\[(\d+)\]$/);
+                if (!indexMatch)
+                    return false;
+                const index = parseInt(indexMatch[1], 10);
+                return index >= 2;
+            });
+            const isTupleReturningHook = TUPLE_RETURNING_HOOKS.has(baseMockName) &&
+                (isGenericArray || hasGenericArrayInSchema) &&
+                !tupleHasDifferentiatedIndices;
+            // Debug logging for tuple-returning hooks
+            if (TUPLE_RETURNING_HOOKS.has(baseMockName) && root) {
+                const schemaKeys = Object.keys(relevantReturnValueSchema ?? {});
+                const hasArrayPattern = schemaKeys.some((k) => k.includes('.functionCallReturnValue[]'));
+                console.log(`CodeYam: Tuple hook check for ${baseMockName} (root):`, `hasGenericArrayInSchema=${hasGenericArrayInSchema}`, `hasArrayPattern=${hasArrayPattern}`, `tupleHasDifferentiatedIndices=${tupleHasDifferentiatedIndices}`, `isTupleReturningHook=${isTupleReturningHook}`, `schemaKeysSample=${schemaKeys.slice(0, 5).join(', ')}`);
+            }
+            if (isTupleReturningHook) {
+                // Tuple-returning hooks should return [value, setter] tuple
+                // The value is the first element from scenarios data, setter is a no-op
+                // Default to [] when data is undefined to prevent errors like ".includes is not a function"
+                // Check if there are multiple call patterns for this hook in the schema
+                // (e.g., useAtom(quoteFilterAtom) and useAtom(supplierAtom))
+                const hookCallPatterns = Object.keys(relevantReturnValueSchema ?? {})
+                    .filter((k) => {
+                    // Match patterns like "useAtom(someArg)" but not nested paths like "useAtom(x).foo"
+                    const regex = new RegExp(`^${baseMockName}\\([^)]+\\)$`);
+                    return regex.test(k);
+                })
+                    .map((k) => {
+                    // Extract the argument from the key like "useAtom(quoteFilterAtom)" -> "quoteFilterAtom"
+                    const match = k.match(/\(([^)]+)\)/);
+                    return { key: k, arg: match?.[1] ?? '' };
+                });
+                if (hookCallPatterns.length > 1) {
+                    // Multiple patterns - generate conditional dispatch based on first argument
+                    // For Jotai atoms, we use debugLabel; for others, we try to match the argument string
+                    const conditions = hookCallPatterns
+                        .map(({ key, arg }) => `if (argLabel === '${arg}' || argStr.includes('${arg}')) {\n    return [scenarios().data()?.["${key}"]?.[0] ?? [], () => {}];\n  }`)
+                        .join('\n  ');
+                    // Use the first pattern as fallback
+                    const fallbackKey = hookCallPatterns[0]?.key ?? dataKey;
+                    returnValueContents = `(() => {
+  // Dynamic dispatch for tuple-returning hook with multiple argument patterns
+  const argLabel = args[0]?.debugLabel ?? '';
+  const argStr = args[0]?.toString?.() ?? String(args[0] ?? '');
+  ${conditions}
+  // Fallback to first pattern
+  return [scenarios().data()?.["${fallbackKey}"]?.[0] ?? [], () => {}];
+})()`;
+                }
+                else {
+                    // Single pattern or no patterns - use dynamic dispatch to handle case where
+                    // the mock is used with different atoms than what was captured in the schema.
+                    // Use the first argument to construct the data key dynamically.
+                    const fallbackKey = hookCallPatterns[0]?.key ?? `${baseMockName}()`;
+                    returnValueContents = `(() => {
+  // Dynamic dispatch for tuple-returning hook
+  // Try to construct key from argument's debugLabel (Jotai atoms) or toString
+  const argLabel = args[0]?.debugLabel ?? '';
+  const argStr = args[0]?.toString?.() ?? '';
+  const allData = scenarios().data() ?? {};
+
+  // Try to find a matching key using debugLabel first
+  if (argLabel) {
+    const labelKey = '${baseMockName}(' + argLabel + ')';
+    if (allData[labelKey]) {
+      return [allData[labelKey]?.[0] ?? [], () => {}];
+    }
+  }
+
+  // Try to find any matching key that contains part of the argument string
+  const keys = Object.keys(allData).filter(k => k.startsWith('${baseMockName}('));
+  for (const key of keys) {
+    const keyArg = key.slice(${baseMockName.length + 1}, -1);
+    if (argStr.includes(keyArg)) {
+      return [allData[key]?.[0] ?? [], () => {}];
+    }
+  }
+
+  // Fallback to first matching key or default
+  const fallback = keys[0] ?? '${fallbackKey}';
+  return [allData[fallback]?.[0] ?? [], () => {}];
+})()`;
+                }
+            }
+            else if (!returnsFunctionArgs &&
                 nestedContent.length === 0 &&
                 dataPaths.length === 1) {
                 returnValueContents = dataPaths[0];
             }
+            else if (returnsFunctionArray &&
+                dataPaths.length === 1 &&
+                !root &&
+                (!nested || nested.length === 0 || hasOnlyArrayPrototypeMethods)) {
+                // Nested method returns an array - return the data path directly
+                // Only if nested content is empty or only contains array prototype methods
+                // (like .reduce() which work on any array - we don't need to mock them)
+                returnValueContents = dataPaths[0];
+            }
             else {
                 if (isArray) {
                     // When GENERIC array (using []) has nested content (like functions that need wrapping),
                     // use .map() to transform ALL elements instead of just creating [0]
                     // For DIFFERENTIATED arrays (using [0], [1], etc.), keep the static array structure
+                    //
+                    // IMPORTANT: If the nested content contains differentiated indices like [0], [1],
+                    // we MUST use static array pattern, not .map(). The presence of differentiated
+                    // indices means the array elements have different types/structures, so .map()
+                    // would generate invalid code trying to treat them uniformly.
+                    const hasDifferentiatedIndices = nested &&
+                        nested.some((n) => n.name.match(/^\[\d+\]$/) && n.name !== '[0]');
                     if (isGenericArray &&
                         nestedContent.length > 0 &&
-                        dataPaths.length > 0) {
+                        dataPaths.length > 0 &&
+                        !hasDifferentiatedIndices) {
                         // Get the array base path (without the [0])
                         const arrayBasePath = dataPaths[0].replace(/\?\.\[0\]$/, '');
                         // Replace [0] references with [__idx__] in level contents
-                        const mappedContents = levelContents.replace(/\?\.\[0\]/g, '?.[__idx__]');
+                        let mappedContents = levelContents.replace(/\?\.\[0\]/g, '?.[__idx__]');
                         // levelContents may already be wrapped in {...} from structural [0] element,
                         // so check if we need to add the wrapper or not
                         const needsWrapper = !mappedContents.trim().startsWith('{');
+                        // Helper to check if a position is inside a string literal
+                        // Returns the end position of the string if inside one, -1 otherwise
+                        // Defined here so it's accessible in both needsWrapper branches
+                        const skipStringLiteral = (content, pos) => {
+                            const char = content[pos];
+                            if (char !== '"' && char !== "'" && char !== '`')
+                                return -1;
+                            // Find the matching closing quote
+                            let j = pos + 1;
+                            while (j < content.length) {
+                                if (content[j] === '\\') {
+                                    j += 2; // Skip escaped character
+                                    continue;
+                                }
+                                if (content[j] === char) {
+                                    return j + 1; // Return position after closing quote
+                                }
+                                j++;
+                            }
+                            return content.length; // Unclosed string, skip to end
+                        };
+                        // Filter out bare arrow functions which are invalid as object properties.
+                        // Arrow functions can be multi-line, so we need to match the entire function body, not just the first line.
+                        // Pattern: starts with "(args) =>", followed by either:
+                        //   - A single-line body: "() => expression"
+                        //   - A multi-line body: "() => { ... }" (with matching braces)
+                        // IMPORTANT: Only filter BARE arrow functions (without property names).
+                        // "() => {...}" is invalid, but "get: (arg1) => {...}" is valid.
+                        // We use a function to properly handle nested braces.
+                        // Defined here so it's accessible in both needsWrapper branches
+                        const filterOutArrowFunctions = (content) => {
+                            const result = [];
+                            let i = 0;
+                            while (i < content.length) {
+                                // Skip over string literals entirely
+                                const stringEnd = skipStringLiteral(content, i);
+                                if (stringEnd !== -1) {
+                                    result.push(content.slice(i, stringEnd));
+                                    i = stringEnd;
+                                    continue;
+                                }
+                                // Check if we're at the start of an arrow function (with optional leading whitespace)
+                                const arrowMatch = content
+                                    .slice(i)
+                                    .match(/^(\s*)\([^)]*\)\s*=>\s*/);
+                                if (arrowMatch) {
+                                    // Check if this is a bare arrow function or a named property with arrow function value
+                                    // Look back to see if there's a "key:" pattern before this position
+                                    const before = content.slice(0, i);
+                                    const beforeTrimmed = before.trim();
+                                    // Valid patterns where arrow function is NOT bare:
+                                    // 1. Property value: "key: (arg) => ..." - ends with ':'
+                                    // 2. Function argument: ".map((arg) => ..." - ends with '('
+                                    // 3. Method call: "?.map" followed directly by the arrow function
+                                    //    In this case, the '(' is consumed by the arrow function regex match,
+                                    //    so beforeTrimmed ends with the method name (e.g., 'map'), not '('.
+                                    //    We detect this by checking if beforeTrimmed ends with an identifier
+                                    //    that could be a method name (preceded by '.' or '?.').
+                                    // NOTE: We don't include ',' because "{ prop, () => {} }" is invalid
+                                    // (can't distinguish function argument from object property context)
+                                    const isPropertyValue = beforeTrimmed.endsWith(':');
+                                    const isFunctionArg = beforeTrimmed.endsWith('(');
+                                    // Check if before ends with a method call pattern like ".map" or "?.map"
+                                    // The '(' after the method name is consumed by the arrow function regex
+                                    const isMethodCallArg = /\??\.\w+$/.test(beforeTrimmed);
+                                    const hasPropertyName = isPropertyValue || isFunctionArg || isMethodCallArg;
+                                    if (!hasPropertyName) {
+                                        // This is a bare arrow function - filter it out
+                                        // Found arrow function start, need to find its end
+                                        const afterArrow = i + arrowMatch[0].length;
+                                        if (content[afterArrow] === '{') {
+                                            // Multi-line arrow function - find matching closing brace
+                                            // Must respect string literals when counting braces
+                                            let braceCount = 1;
+                                            let j = afterArrow + 1;
+                                            while (j < content.length && braceCount > 0) {
+                                                const strEnd = skipStringLiteral(content, j);
+                                                if (strEnd !== -1) {
+                                                    j = strEnd;
+                                                    continue;
+                                                }
+                                                if (content[j] === '{')
+                                                    braceCount++;
+                                                if (content[j] === '}')
+                                                    braceCount--;
+                                                j++;
+                                            }
+                                            // Skip past the arrow function
+                                            i = j;
+                                            // Only skip trailing comma, keep newlines
+                                            while (i < content.length && content[i] === ' ') {
+                                                i++;
+                                            }
+                                            if (content[i] === ',') {
+                                                i++; // Skip the comma after the arrow function
+                                            }
+                                        }
+                                        else {
+                                            // Single expression arrow function - skip to next comma or newline
+                                            let j = afterArrow;
+                                            while (j < content.length &&
+                                                content[j] !== ',' &&
+                                                content[j] !== '\n') {
+                                                j++;
+                                            }
+                                            i = j;
+                                            if (content[i] === ',')
+                                                i++; // Skip the comma
+                                        }
+                                        continue;
+                                    }
+                                }
+                                // Not a bare arrow function, keep this character
+                                result.push(content[i]);
+                                i++;
+                            }
+                            return result.join('');
+                        };
+                        // Filter out bare object blocks (e.g., "{ ...spread, props }," without a property name)
+                        // These are invalid in object literal context - you need "key: { ... }" not just "{ ... }"
+                        // Defined here so it's accessible in both needsWrapper branches
+                        // The skipFirstBrace parameter allows the else branch to preserve the outer object
+                        const filterOutBareObjects = (content, skipFirstBrace = false) => {
+                            const result = [];
+                            let i = 0;
+                            let firstBraceSkipped = false;
+                            while (i < content.length) {
+                                // Skip over string literals entirely - braces inside strings should not be processed
+                                const stringEnd = skipStringLiteral(content, i);
+                                if (stringEnd !== -1) {
+                                    result.push(content.slice(i, stringEnd));
+                                    i = stringEnd;
+                                    continue;
+                                }
+                                // Check if we're at a bare object start (newline/comma followed by { without : before it)
+                                // Look back to see if there's a colon (property assignment) before this brace
+                                const isStartOfLine = i === 0 ||
+                                    content[i - 1] === '\n' ||
+                                    content.slice(0, i).trim().endsWith(',');
+                                if (content[i] === '{' && isStartOfLine) {
+                                    // Check if this is actually a bare object (not "key: {")
+                                    const beforeTrimmed = content.slice(0, i).trim();
+                                    const isBareObject = beforeTrimmed.endsWith(',') ||
+                                        beforeTrimmed === '' ||
+                                        beforeTrimmed.endsWith('(');
+                                    if (isBareObject) {
+                                        // If skipFirstBrace is true and this is the first bare brace at position 0,
+                                        // don't filter it - it's the intentional outer object wrapper
+                                        if (skipFirstBrace && !firstBraceSkipped && i === 0) {
+                                            firstBraceSkipped = true;
+                                            result.push(content[i]);
+                                            i++;
+                                            continue;
+                                        }
+                                        // Find matching closing brace, respecting string literals
+                                        let braceCount = 1;
+                                        let j = i + 1;
+                                        while (j < content.length && braceCount > 0) {
+                                            const strEnd = skipStringLiteral(content, j);
+                                            if (strEnd !== -1) {
+                                                j = strEnd;
+                                                continue;
+                                            }
+                                            if (content[j] === '{')
+                                                braceCount++;
+                                            if (content[j] === '}')
+                                                braceCount--;
+                                            j++;
+                                        }
+                                        // Skip past the object
+                                        i = j;
+                                        // Skip trailing comma
+                                        while (i < content.length && content[i] === ' ') {
+                                            i++;
+                                        }
+                                        if (content[i] === ',') {
+                                            i++;
+                                        }
+                                        continue;
+                                    }
+                                }
+                                result.push(content[i]);
+                                i++;
+                            }
+                            return result.join('');
+                        };
+                        // Helper to clean up formatting issues after filtering
+                        const cleanupContent = (content) => {
+                            return (content
+                                .replace(/,\s*,/g, ',') // Double commas
+                                .replace(/,(\s*\n\s*\})/g, '$1') // Trailing comma before closing brace
+                                .replace(/\{\s*\n\s*,/g, '{\n') // Leading comma after opening brace
+                                // Remove incomplete .map calls where callback was filtered out
+                                // Pattern: ".map" followed by newline/whitespace without "(" for args
+                                .replace(/\?\.map(?=\s*[\n\r,}\]])/g, '')
+                                .replace(/\.map(?=\s*[\n\r,}\]])/g, '')
+                                // Clean up orphan })) sequences (from nested filtered map callbacks)
+                                .replace(/\s*\}\)\)\s*\n\s*\}/g, '\n}')
+                                .replace(/^\s*\n/gm, '') // Empty lines
+                                .trim());
+                        };
                         if (needsWrapper) {
-                            returnValueContents = `${arrayBasePath}?.map((__item__, __idx__) => ({\n${indent(mappedContents)}\n}))`;
+                            // Apply filters to remove invalid content
+                            mappedContents = filterOutArrowFunctions(mappedContents);
+                            mappedContents = filterOutBareObjects(mappedContents);
+                            mappedContents = cleanupContent(mappedContents);
+                            // If mappedContents is empty after filtering, don't generate .map() at all
+                            // Just use the array path directly with spread or as-is
+                            // This prevents orphan )) from empty .map() callbacks
+                            const cleanedForEmptyCheck = mappedContents
+                                .replace(/\s+/g, '')
+                                .replace(/,+/g, '');
+                            if (cleanedForEmptyCheck.length === 0) {
+                                // Content is empty - just return the array directly
+                                returnValueContents = arrayBasePath;
+                            }
+                            else {
+                                // Check if mappedContents is just a bare expression (no property names)
+                                // A bare expression like "scenarios().data()?.["key"]?.[__idx__]," cannot be
+                                // wrapped in ({ }) because it's not a valid object property.
+                                // Pattern: content has no ":" that's not inside brackets/parens/strings
+                                const hasBareExpression = (() => {
+                                    const trimmed = mappedContents.trim().replace(/,\s*$/, ''); // Remove trailing comma
+                                    let depth = 0;
+                                    let inString = false;
+                                    let stringChar = '';
+                                    for (let i = 0; i < trimmed.length; i++) {
+                                        const char = trimmed[i];
+                                        if (inString) {
+                                            if (char === '\\') {
+                                                i++; // Skip escaped char
+                                                continue;
+                                            }
+                                            if (char === stringChar) {
+                                                inString = false;
+                                            }
+                                            continue;
+                                        }
+                                        if (char === '"' || char === "'" || char === '`') {
+                                            inString = true;
+                                            stringChar = char;
+                                            continue;
+                                        }
+                                        if (char === '(' || char === '[' || char === '{') {
+                                            depth++;
+                                            continue;
+                                        }
+                                        if (char === ')' || char === ']' || char === '}') {
+                                            depth--;
+                                            continue;
+                                        }
+                                        // Found a colon at depth 0 = has property name
+                                        if (char === ':' && depth === 0) {
+                                            return false;
+                                        }
+                                    }
+                                    return true;
+                                })();
+                                if (hasBareExpression) {
+                                    // Content is just an expression - return it directly without object wrapper
+                                    const trimmedContent = mappedContents
+                                        .trim()
+                                        .replace(/,\s*$/, '');
+                                    returnValueContents = `${arrayBasePath}?.map((__item__, __idx__) => (\n${indent(trimmedContent)}\n))`;
+                                }
+                                else {
+                                    // When generating object-wrapped .map(), ensure original item data is preserved.
+                                    // If no data spread was included (e.g., because this is a plain array property,
+                                    // not a function return), add ...__item__ to spread the original item properties.
+                                    // Without this, the .map() would create new objects with only nested function
+                                    // properties, losing data like filePath, frontmatter, body, etc.
+                                    const hasDataSpread = mappedContents.includes('...scenarios()') ||
+                                        mappedContents.includes('...__item__');
+                                    if (!hasDataSpread) {
+                                        mappedContents = `...__item__,\n${mappedContents}`;
+                                    }
+                                    returnValueContents = `${arrayBasePath}?.map((__item__, __idx__) => ({\n${indent(mappedContents)}\n}))`;
+                                }
+                            } // Close the empty content check else block
                         }
                         else {
+                            // Content already starts with '{'. Check if there are additional properties after the inner object.
+                            // If so, we need to merge them INTO the object, not leave them outside.
+                            // Pattern: "{ ...spread, props },\nfilter: ...,\nsort: ..."
+                            // Should become: "{ ...spread, props, filter: ..., sort: ... }"
+                            const trimmed = mappedContents.trim();
+                            // Find first }, at depth 0 that is NOT inside a string literal
+                            // This prevents splitting keys like ?.["useQuery({ id }, { enabled })"]
+                            // and also prevents finding }, inside nested arrow functions
+                            const findBraceCommaOutsideStrings = (content) => {
+                                let i = 0;
+                                let depth = 0; // Track brace depth to find the outer object's },
+                                while (i < content.length - 1) {
+                                    // Skip over string literals
+                                    const strEnd = skipStringLiteral(content, i);
+                                    if (strEnd !== -1) {
+                                        i = strEnd;
+                                        continue;
+                                    }
+                                    // Track brace depth
+                                    if (content[i] === '{') {
+                                        depth++;
+                                        i++;
+                                        continue;
+                                    }
+                                    // Check for }, pattern at depth 1 (the outer object level)
+                                    // We're looking for the outer object's closing brace, which is at depth 1
+                                    // (we started at depth 0, opened { at depth 0 -> 1)
+                                    if (content[i] === '}') {
+                                        depth--;
+                                        if (depth === 0 &&
+                                            i + 1 < content.length &&
+                                            content[i + 1] === ',') {
+                                            return i;
+                                        }
+                                    }
+                                    i++;
+                                }
+                                return -1;
+                            };
+                            const firstBraceEnd = findBraceCommaOutsideStrings(trimmed);
+                            if (firstBraceEnd !== -1) {
+                                // Found pattern "{ ... }," followed by more content
+                                // Extract the inner object and the trailing properties
+                                const innerObject = trimmed.slice(0, firstBraceEnd);
+                                const trailingContent = trimmed.slice(firstBraceEnd + 2).trim();
+                                if (trailingContent) {
+                                    // Merge trailing properties into the inner object
+                                    mappedContents = `${innerObject},\n${trailingContent}\n}`;
+                                }
+                            }
+                            // Even when content starts with {, we need to filter out invalid properties inside
+                            // (arrow functions and bare objects that were generated from the schema)
+                            // Pass skipFirstBrace=true because the content's outer { is the intentional wrapper
+                            mappedContents = filterOutArrowFunctions(mappedContents);
+                            mappedContents = filterOutBareObjects(mappedContents, true);
+                            mappedContents = cleanupContent(mappedContents);
+                            // Same as needsWrapper branch: ensure item data is preserved in .map()
+                            const hasDataSpreadInner = mappedContents.includes('...scenarios()') ||
+                                mappedContents.includes('...__item__');
+                            if (!hasDataSpreadInner && mappedContents.trim().length > 0) {
+                                // Insert ...__item__ after the opening brace
+                                mappedContents = mappedContents.replace(/^\s*\{/, '{\n...__item__,');
+                            }
                             returnValueContents = `${arrayBasePath}?.map((__item__, __idx__) => (\n${indent(mappedContents)}\n))`;
                         }
                     }
@@ -295,7 +1256,36 @@ export default function constructMockCode(mockName, dependencySchemas) {
                     }
                 }
                 else {
-                    returnValueContents = `{\n${indent(levelContents)}\n}`;
+                    // When we have a single data path and nested content that creates an object structure,
+                    // and we're NOT at the root level, we need to handle the case where the parent data
+                    // value is null or undefined. Without this check, `{ ...null, prop: null?.["prop"] }`
+                    // creates `{ prop: undefined }` instead of `null`, causing errors like
+                    // "Cannot read properties of undefined (reading 'some')" when code does
+                    // data?.prop.some(...) because data is an object with prop: undefined, not null.
+                    // We only apply this to non-root cases because root-level mocks are expected to exist.
+                    // We also skip structural elements (like [0] inside arrays) because the null check
+                    // syntax doesn't work inside .map() callbacks where structural elements are used.
+                    // We also skip array index elements ([0], [1], etc.) because they represent tuple/array
+                    // elements, not properties that could be null.
+                    // We also only apply this when we're inside a function return value context - i.e.,
+                    // when the data path contains a function call pattern like ?.["someFunction(...)"].
+                    // This prevents adding null checks to intermediate objects in chains like supabase.auth.
+                    const hasNestedContent = nestedContent.filter(Boolean).length > 0;
+                    const isArrayIndexElement = name.match(/^\[\d*\]$/);
+                    // Check if data path contains a function call pattern, indicating we're inside a function return value
+                    const isInsideFunctionReturnValue = dataPaths.length === 1 &&
+                        dataPaths[0].match(/\?\.\["\w+\([^"]*\)"\]/);
+                    if (!root &&
+                        !returnValue.isStructural &&
+                        !isArrayIndexElement &&
+                        isInsideFunctionReturnValue &&
+                        hasNestedContent) {
+                        // Wrap with null check: if parent is null/undefined, return it directly; otherwise create object
+                        returnValueContents = `${dataPaths[0]} == null ? ${dataPaths[0]} : {\n${indent(levelContents)}\n}`;
+                    }
+                    else {
+                        returnValueContents = `{\n${indent(levelContents)}\n}`;
+                    }
                 }
             }
             if (root) {
@@ -305,6 +1295,12 @@ export default function constructMockCode(mockName, dependencySchemas) {
             if (args && args.length > 0) {
                 if (!isValidKey(name))
                     return;
+                // Skip array index patterns like [], [0], [1] when they have args
+                // These represent function calls on array elements, not property keys
+                // e.g., customSizes[].(args) means each array element is callable, not a property named "[]"
+                if (name.match(/^\[\d*\]$/)) {
+                    return;
+                }
                 const mostArgs = args.sort((a, b) => b.length - a.length)[0];
                 const argsString = mostArgs
                     .map((_, index) => `arg${index + 1}`)
@@ -344,8 +1340,19 @@ export default function constructMockCode(mockName, dependencySchemas) {
                         fallbackContent = `return ${returnValueContents}`;
                     }
                     else {
-                        // Use all paths as fallback for unknown arguments
-                        fallbackContent = `return ${returnValueContents}`;
+                        // No explicit fallback paths - return the first literal's value as default
+                        // Returning spread of all values is dangerous because if values are primitives (strings),
+                        // spreading them creates objects with numeric keys like {0:'a', 1:'b', ...}
+                        // which causes "Objects are not valid as React child" errors
+                        const firstLiteralValue = literalKeys[0];
+                        const firstGroupPaths = argGroups.get(firstLiteralValue);
+                        if (firstGroupPaths && firstGroupPaths.length === 1) {
+                            fallbackContent = `return ${firstGroupPaths[0]}`;
+                        }
+                        else {
+                            // Multiple paths for first literal - return undefined as safe fallback
+                            fallbackContent = `return undefined`;
+                        }
                     }
                     const funcContents = conditionalBranches.join('\n') +
                         '\n// Fallback for unmatched arguments\n' +
@@ -354,7 +1361,18 @@ export default function constructMockCode(mockName, dependencySchemas) {
                 }
                 else {
                     // No argument variants - use existing behavior
-                    const funcContents = `return ${returnValueContents}`;
+                    // But if there's nested content, we need to include it in the return object
+                    // (similar to how argument variant branches handle this at line 1070-1072)
+                    const hasNestedContent = validNestedContent.length > 0;
+                    let funcReturnContents;
+                    if (hasNestedContent && levelContentItems.length > 1) {
+                        // Include both spread and nested content in the return
+                        funcReturnContents = `{\n${indent(levelContents)}\n}`;
+                    }
+                    else {
+                        funcReturnContents = returnValueContents;
+                    }
+                    const funcContents = `return ${funcReturnContents}`;
                     content = `${cleanOutTypes(name)}: ${isAsyncFunction ? 'async ' : ''}(${argsString}) => {\n${indent(funcContents)}\n}`;
                 }
             }
@@ -363,8 +1381,14 @@ export default function constructMockCode(mockName, dependencySchemas) {
                     return;
                 }
                 else if (name.match(/\[\d*\]/)) {
+                    // Numeric array index like [0], [1] - can be used as computed property
                     content = returnValueContents;
                 }
+                else if (name.match(/^\[[a-zA-Z_]\w*\]$/)) {
+                    // Variable-based index like [currentItemIndex] - must be quoted string key
+                    // Otherwise JavaScript would try to evaluate the variable name
+                    content = `"${safeString(name)}": ${returnValueContents}`;
+                }
                 else {
                     content = `${safeString(name)}: ${returnValueContents}`;
                 }
@@ -376,7 +1400,31 @@ export default function constructMockCode(mockName, dependencySchemas) {
         return content;
     };
     // Create the return value structure
-    const sortedKeys = Object.keys(relevantReturnValueSchema ?? {}).sort((a, b) => {
+    // OPTIMIZATION: Filter keys to only those starting with baseMockName before sorting.
+    // This dramatically reduces processing time for large schemas (e.g., 9216 keys -> ~100 relevant keys).
+    // Without this filter, the loop would call splitOutsideParenthesesAndArrays on every key
+    // even though most are filtered out later by the baseMockName check.
+    const allSchemaKeys = Object.keys(relevantReturnValueSchema ?? {});
+    const relevantKeys = allSchemaKeys.filter((key) => {
+        // Fast prefix check - key must start with baseMockName followed by ( or < or .
+        // This matches: "useAtom()", "useAtom<T>()", "useAtom.something", but not "useAtomValue()"
+        if (key === baseMockName)
+            return true;
+        if (key.startsWith(baseMockName + '('))
+            return true;
+        if (key.startsWith(baseMockName + '<'))
+            return true;
+        if (key.startsWith(baseMockName + '.'))
+            return true;
+        // Also include 'returnValue' paths which are normalized later
+        if (key === 'returnValue' ||
+            key.startsWith('returnValue.') ||
+            key.startsWith('returnValue['))
+            return true;
+        return false;
+    });
+    const schemaKeyCount = relevantKeys.length;
+    const sortedKeys = relevantKeys.sort((a, b) => {
         const aParts = splitOutsideParenthesesAndArrays(a);
         const bParts = splitOutsideParenthesesAndArrays(b);
         const maxLength = Math.max(aParts.length, bParts.length);
@@ -400,6 +1448,36 @@ export default function constructMockCode(mockName, dependencySchemas) {
         }
         return 0;
     });
+    // OPTIMIZATION: Pre-compute prefix indexes for O(1) lookups instead of O(n) scans.
+    // This reduces complexity from O(n²) to O(n) for large schemas (9k+ keys).
+    //
+    // 1. extendedReturnValuePrefixes: Set of all path prefixes that have a .functionCallReturnValue extension
+    //    Used by hasExtendedFunctionCallReturnValue check at line ~1754
+    // 2. functionCallsWithReturnValue: Set of function call paths where .functionCallReturnValue IMMEDIATELY follows
+    //    Used by hasProperFunctionCallPath check at line ~1787
+    //    IMPORTANT: Only includes paths where the function call is directly followed by .functionCallReturnValue
+    //    e.g., "a.b().functionCallReturnValue" -> adds "a.b()" but NOT "a" even if "a" ends with ")"
+    const extendedReturnValuePrefixes = new Set();
+    const functionCallsWithReturnValue = new Set();
+    for (const k of relevantKeys) {
+        const parts = splitOutsideParenthesesAndArrays(k);
+        const returnValueIndex = parts.findIndex((part) => part.startsWith(RETURN_VALUE));
+        if (returnValueIndex !== -1) {
+            // Add all prefixes of k up to (but not including) functionCallReturnValue
+            const prefix = joinParenthesesAndArrays(parts.slice(0, returnValueIndex));
+            extendedReturnValuePrefixes.add(prefix);
+            // ONLY add to functionCallsWithReturnValue if functionCallReturnValue IMMEDIATELY follows
+            if (prefix.endsWith(')')) {
+                functionCallsWithReturnValue.add(prefix);
+            }
+            // Also add intermediate prefixes for nested paths to extendedReturnValuePrefixes
+            // This helps hasExtendedFunctionCallReturnValue which checks key + '.'
+            for (let i = 1; i < returnValueIndex; i++) {
+                const partialPrefix = joinParenthesesAndArrays(parts.slice(0, i));
+                extendedReturnValuePrefixes.add(partialPrefix);
+            }
+        }
+    }
     for (const key of sortedKeys) {
         const value = relevantReturnValueSchema[key];
         const parts = splitOutsideParenthesesAndArrays(key);
@@ -427,7 +1505,9 @@ export default function constructMockCode(mockName, dependencySchemas) {
                 parts.splice(i, 1);
             }
         }
-        if (parts[0].split('(')[0] !== mockName)
+        // Compare against baseMockName (without generics/args), not the full mockName
+        // e.g., for "useFetcher<User>()", baseMockName is "useFetcher"
+        if (parts[0].split('(')[0] !== baseMockName)
             continue;
         // Include paths with functionCallReturnValue OR function-typed paths that need mocking
         const hasFunctionCallReturnValue = parts.some((p) => isFunctionCallReturnValue(p));
@@ -438,10 +1518,53 @@ export default function constructMockCode(mockName, dependencySchemas) {
         // Exclude paths with functionCallReturnValue - those are handled by existing logic
         // Also check if there's a functionCallReturnValue path that extends this path
         const hasSignaturePath = parts.some((p) => p.startsWith('signature['));
-        const hasExtendedFunctionCallReturnValue = Object.keys(relevantReturnValueSchema).some((k) => k.startsWith(key + '.') && k.includes(`.${RETURN_VALUE}`));
+        // Skip signature paths entirely - they describe INPUT structure (function arguments),
+        // not OUTPUT (return values). This applies even if they contain functionCallReturnValue
+        // nested inside (e.g., methods on array elements passed as arguments).
+        if (hasSignaturePath)
+            continue;
+        // OPTIMIZATION: Use pre-computed index instead of O(n) scan
+        // Old code: Object.keys(relevantReturnValueSchema).some((k) => k.startsWith(key + '.') && k.includes('.functionCallReturnValue'))
+        const hasExtendedFunctionCallReturnValue = extendedReturnValuePrefixes.has(key);
+        // Skip JSX components - they look like function calls (e.g., Context.Provider())
+        // but they're React components used in JSX, not functions that need mocking
+        // Check both the value type and whether the functionCallReturnValue is jsx-component
+        const isJsxComponent = value === 'jsx-component' ||
+            relevantReturnValueSchema[key + '.functionCallReturnValue'] ===
+                'jsx-component';
+        if (isJsxComponent)
+            continue;
+        // Skip paths that bypass .functionCallReturnValue when there's a corresponding path with it.
+        // Example: If we have both:
+        //   - trpc.customer.useQuery(...).data (incorrect - no .functionCallReturnValue)
+        //   - trpc.customer.useQuery(...).functionCallReturnValue.data (correct)
+        // We should skip the first path because the second one properly captures the return value.
+        // This can happen when the analyzer sees both the raw property access and the return value structure.
+        if (!hasFunctionCallReturnValue) {
+            // This path has no .functionCallReturnValue. Check if any function call in this path
+            // has a corresponding .functionCallReturnValue path in the schema.
+            let shouldSkipKey = false;
+            for (let i = 0; i < parts.length - 1; i++) {
+                const part = parts[i];
+                if (part.endsWith(')') && !isFunctionCallReturnValue(parts[i + 1])) {
+                    // This part is a function call, and the next part is NOT .functionCallReturnValue
+                    // Check if there's any path with .functionCallReturnValue for this function call
+                    const functionCallPath = joinParenthesesAndArrays(parts.slice(0, i + 1));
+                    // OPTIMIZATION: Use pre-computed index instead of O(n) scan
+                    // Old code: Object.keys(relevantReturnValueSchema).some((k) => k.startsWith(functionCallPath + '.functionCallReturnValue'))
+                    const hasProperFunctionCallPath = functionCallsWithReturnValue.has(functionCallPath);
+                    if (hasProperFunctionCallPath) {
+                        // Skip this path - the .functionCallReturnValue path will handle it correctly
+                        shouldSkipKey = true;
+                        break;
+                    }
+                }
+            }
+            if (shouldSkipKey)
+                continue;
+        }
         const isFunctionPath = ['function', 'async-function'].includes(value) &&
             parts[parts.length - 1].endsWith(')') &&
-            !hasSignaturePath &&
             !hasAnyFunctionCallReturnValue &&
             !hasExtendedFunctionCallReturnValue;
         if (!hasFunctionCallReturnValue && !isFunctionPath)
@@ -483,6 +1606,16 @@ export default function constructMockCode(mockName, dependencySchemas) {
             const nextIsArray = !!nextPart?.match(/^\[\d*\]/);
             const isDifferentiatedArray = !!part?.match(/^\[\d+\]/);
             const nextIsDifferentiatedArray = !!nextPart?.match(/^\[\d+\]/);
+            // Variable index patterns like [currentItemIndex] or [targetIndex] indicate array access
+            // but don't represent actual data structure - they're markers from variable-based index tracking.
+            // Skip them AND all remaining parts to avoid creating spurious nested structure that breaks array iteration.
+            // The remaining parts (e.g., .missing_attributes) describe properties of array elements, which are
+            // already handled by the generic [] accessor path.
+            const isVariableIndex = !!part?.match(/^\[[a-zA-Z_]\w*\]$/);
+            if (isVariableIndex) {
+                // Break out of the loop entirely - don't process any remaining parts
+                break;
+            }
             // Find the correct value for the current part being processed
             let partValue = value; // default to the final value
             if (isFunctionCallReturnValue(part) && nextIsArray) {
@@ -523,6 +1656,23 @@ export default function constructMockCode(mockName, dependencySchemas) {
                     if (returnValueSection.returnsFunctionArgs && value === 'array') {
                         returnValueSection.returnsFunctionArray = true;
                     }
+                    // Check if this function call has actual return data in the schema
+                    // If the path only has .signature entries (no .functionCallReturnValue), mark as no return data
+                    // Use parts[i] (original part) instead of modified 'part' to include array indices like [1]
+                    const functionCallPath = joinParenthesesAndArrays([
+                        ...parts.slice(0, i),
+                        parts[i], // Use original part which may include [1](args) together
+                    ]);
+                    // Check if there's a .functionCallReturnValue AFTER this function call path
+                    const hasFunctionCallReturnValue = Object.keys(relevantReturnValueSchema).some((k) => {
+                        if (!k.startsWith(functionCallPath))
+                            return false;
+                        const afterPath = k.slice(functionCallPath.length);
+                        return afterPath.startsWith('.functionCallReturnValue');
+                    });
+                    if (!hasFunctionCallReturnValue) {
+                        returnValueSection.hasNoReturnData = true;
+                    }
                 }
                 if (nextIsDifferentiatedArray || hasNestedFunction) {
                     continue;
@@ -557,7 +1707,35 @@ export default function constructMockCode(mockName, dependencySchemas) {
                             }
                         }
                         else {
-                            returnValueSection.returnsFunctionArgs = [];
+                            // Before setting returnsFunctionArgs on the parent (for generic [] = function),
+                            // check if there are specific array indices (like [0], [1]) that are NOT functions.
+                            // If so, don't set returnsFunctionArgs because those specific indices take precedence.
+                            // This prevents adding ["()"] to paths like [0] when [0] is 'unknown' but [] is 'function'.
+                            //
+                            // Use parts.slice(0, i + 1) to get the current path INCLUDING functionCallReturnValue.
+                            // For example, if parts = ['useAtom()','functionCallReturnValue','[]']
+                            // and i = 1, we want to check 'useAtom().functionCallReturnValue[0]' etc.
+                            const arrayContainerPath = joinParenthesesAndArrays(parts.slice(0, i + 1));
+                            const hasNonFunctionSpecificIndices = Object.entries(relevantReturnValueSchema).some(([k, v]) => {
+                                // Look for paths like "arrayContainerPath[0]", "arrayContainerPath[1]" etc.
+                                const indexMatch = k.match(new RegExp(`^${arrayContainerPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\[(\\d+)\\]$`));
+                                // If found and it's NOT a function type, we have a conflict
+                                return (indexMatch &&
+                                    !['function', 'async-function'].includes(v));
+                            });
+                            // Also check if [] has nested object properties (like [].filter, [].name)
+                            // If so, [] items are objects with properties, not pure functions to be called
+                            // This handles cases where the schema shows [].filter = object but doesn't
+                            // have explicit [0] entries
+                            const genericArrayPath = `${arrayContainerPath}[]`;
+                            const hasNestedProperties = Object.keys(relevantReturnValueSchema).some((k) => {
+                                // Check for paths like "arrayContainerPath[].propertyName" (not [].())
+                                return (k.startsWith(genericArrayPath + '.') &&
+                                    !k.startsWith(genericArrayPath + '.('));
+                            });
+                            if (!hasNonFunctionSpecificIndices && !hasNestedProperties) {
+                                returnValueSection.returnsFunctionArgs = [];
+                            }
                         }
                     }
                 }
@@ -576,6 +1754,12 @@ export default function constructMockCode(mockName, dependencySchemas) {
                         if (['function', 'async-function'].includes(nextValue)) {
                             continue; // Continue to process the function property
                         }
+                        // If the next part is an object with nested content, continue processing
+                        // This handles paths like functionCallReturnValue.selectedOptions.elementOptions[]
+                        // Also handles union types like 'array | undefined' or 'object | undefined'
+                        if (nextValue?.includes('object') || nextValue?.includes('array')) {
+                            continue;
+                        }
                     }
                     break;
                 }
@@ -583,8 +1767,29 @@ export default function constructMockCode(mockName, dependencySchemas) {
             else if (isKeyWord) {
                 continue;
             }
+            // Handle parts that end with [] (e.g., "elementOptions[]")
+            // These should be treated as the base part + array accessor
+            const endsWithArrayAccessor = part.endsWith('[]') && part !== '[]';
+            const basePart = endsWithArrayAccessor ? part.slice(0, -2) : part;
             const withoutArgs = (p) => p.name.split('(')[0];
-            let relevantPart = returnValueSection.nested?.find((p) => withoutArgs(p) === withoutArgs({ name: part }));
+            let relevantPart = returnValueSection.nested?.find((p) => withoutArgs(p) === withoutArgs({ name: basePart }));
+            // If part ends with [], update the existing part to be an array
+            if (endsWithArrayAccessor && relevantPart) {
+                relevantPart.isArray = true;
+                relevantPart.isGenericArray = true;
+                // Create structural [0] element for nested content
+                relevantPart.nested || (relevantPart.nested = []);
+                if (!relevantPart.nested.find((p) => p.name === '[0]')) {
+                    relevantPart.nested.push({
+                        name: '[0]',
+                        nested: [],
+                        isStructural: true,
+                    });
+                }
+                // Move to the [0] element for processing subsequent parts
+                returnValueSection = relevantPart.nested.find((p) => p.name === '[0]');
+                continue;
+            }
             if (!relevantPart) {
                 const hasArguments = part.includes('(') && part.endsWith(')');
                 if (part === '[]') {
@@ -605,6 +1810,29 @@ export default function constructMockCode(mockName, dependencySchemas) {
                     }
                     continue;
                 }
+                // Handle parts that end with [] (e.g., "elementOptions[]") when base part doesn't exist
+                if (endsWithArrayAccessor) {
+                    // Create the base part with array properties
+                    relevantPart = {
+                        name: basePart,
+                        isArray: true,
+                        isGenericArray: true,
+                        nested: [],
+                    };
+                    returnValueSection.nested || (returnValueSection.nested = []);
+                    returnValueSection.nested.push(relevantPart);
+                    // Create structural [0] element for nested content
+                    if (partValue === 'object' && !isLastPart) {
+                        relevantPart.nested.push({
+                            name: '[0]',
+                            nested: [],
+                            isStructural: true,
+                        });
+                        // Move to the [0] element for processing subsequent parts
+                        returnValueSection = relevantPart.nested.find((p) => p.name === '[0]');
+                    }
+                    continue;
+                }
                 if (isLastPart &&
                     ['function', 'async-function'].includes(value) &&
                     !hasArguments) {
@@ -640,22 +1868,73 @@ export default function constructMockCode(mockName, dependencySchemas) {
                     returnValueSection.nested.push(relevantPart);
                 }
             }
-            else if (funcArgs(part).join(',') !== funcArgs(relevantPart.name).join(',')) {
-                const existingArgs = relevantPart.args.find((args) => args.join(',') === funcArgs(part).join(','));
-                if (!existingArgs) {
-                    relevantPart.args || (relevantPart.args = []);
-                    relevantPart.args.push(funcArgs(part));
+            else {
+                // Add args to existing entry if current part has function arguments
+                // This handles the case where bare `t` is processed first (creating {name: 't', args: undefined})
+                // and then `t("common.close")` is processed - we need to add its args to the existing entry
+                const currentArgs = funcArgs(part);
+                const hasNewArgs = currentArgs.length > 0 || part.includes('(');
+                if (hasNewArgs) {
+                    const existingArgs = relevantPart.args?.find((args) => args.join(',') === currentArgs.join(','));
+                    if (!existingArgs) {
+                        relevantPart.args || (relevantPart.args = []);
+                        relevantPart.args.push(currentArgs);
+                    }
                 }
             }
-            if (!hasNestedFunction) {
+            // If nextPart is [], update existing part to be a generic array
+            if (relevantPart && nextPart === '[]') {
+                relevantPart.isArray = true;
+                relevantPart.isGenericArray = true;
+            }
+            // Check if there are remaining parts after functionCallReturnValue that need processing
+            // (e.g., data properties like useQuery().functionCallReturnValue.data)
+            const hasRemainingPartsAfterReturnValue = nextPart &&
+                (isFunctionCallReturnValue(nextPart) ||
+                    (isFunctionCallReturnValue(parts[i]) && i < parts.length - 1));
+            if (!hasNestedFunction && !hasRemainingPartsAfterReturnValue) {
+                // Before breaking, check if this function returns an array
+                // by looking for a functionCallReturnValue: 'array' entry in the schema
+                if (relevantPart && part.endsWith(')')) {
+                    const functionReturnPath = joinParenthesesAndArrays([
+                        ...parts.slice(0, i + 1),
+                        RETURN_VALUE,
+                    ]);
+                    const returnType = relevantReturnValueSchema[functionReturnPath];
+                    if (returnType === 'array') {
+                        // Only set returnsFunctionArray if the array contains plain data,
+                        // NOT if it contains functions (which need wrapping)
+                        const arrayElementPath = `${functionReturnPath}[]`;
+                        const arrayElementType = relevantReturnValueSchema[arrayElementPath];
+                        // If array element is a function, we need to wrap it - don't set returnsFunctionArray
+                        if (arrayElementType !== 'function') {
+                            relevantPart.returnsFunctionArray = true;
+                        }
+                    }
+                }
                 break;
             }
             returnValueSection = relevantPart;
         }
     }
+    // Post-processing: When the root functionCallReturnValue is typed as "function" but the
+    // return value also has nested properties (methods like .from(), .auth, etc.), it's actually
+    // an object, not a function to be called. Clear returnsFunctionArgs to prevent double-wrapping
+    // (adding an extra () => { return { ... } } wrapper and ["()"] data paths).
+    // This handles cases like Supabase's createClient() which returns an object with methods.
+    // Only applied to the root level - nested parts that are functions with methods (like
+    // useSearchParams()[1] which is a setter function with .set() and .delete()) should keep
+    // their returnsFunctionArgs since they genuinely ARE functions.
+    if (returnValueParts.returnsFunctionArgs &&
+        returnValueParts.returnsFunctionArgs.length === 0 &&
+        returnValueParts.nested &&
+        returnValueParts.nested.length > 0) {
+        returnValueParts.returnsFunctionArgs = undefined;
+    }
     const contents = constructReturnValueString(returnValueParts);
     if (mockNameParts.length > 1) {
         const originalLib = `${mockNameParts[0]}__cyOriginal`;
+        const skipOriginalSpread = options?.skipOriginalSpread;
         const subPart = (parts, originalLib) => {
             const part = parts.shift();
             if (!isValidKey(part))
@@ -663,7 +1942,9 @@ export default function constructMockCode(mockName, dependencySchemas) {
             const isLast = parts.length === 0;
             const partContents = isLast
                 ? contents
-                : `...${originalLib}.${part},\n${subPart(parts, originalLib)}`;
+                : skipOriginalSpread
+                    ? subPart(parts, originalLib)
+                    : `...${originalLib}.${part},\n${subPart(parts, originalLib)}`;
             let code = `${part}: {\n${indent(partContents)}\n}`;
             if (part.includes('(') || (isFunction && isLast)) {
                 const args = funcArgs(part)
@@ -673,17 +1954,190 @@ export default function constructMockCode(mockName, dependencySchemas) {
             }
             return code;
         };
-        const returnParts = [
-            `...${mockNameParts[0]}__cyOriginal`,
-            subPart(mockNameParts.slice(1), originalLib),
-        ].filter(Boolean);
-        return `const ${mockNameParts[0]} = {\n${indent(returnParts.join(',\n'))}\n};`;
+        const returnParts = skipOriginalSpread
+            ? [subPart(mockNameParts.slice(1), originalLib)]
+            : [
+                `...${mockNameParts[0]}__cyOriginal`,
+                subPart(mockNameParts.slice(1), originalLib),
+            ];
+        return `const ${mockNameParts[0]} = {\n${indent(returnParts.filter(Boolean).join(',\n'))}\n};`;
     }
     else if (isFunction) {
-        return `const ${mockName}ReturnValue = ${contents};\n\n${isRootAsyncFunction ? 'async ' : ''}function ${mockName}() {\n${indent(`return ${mockName}ReturnValue;`)}\n}`;
+        // For headers() and cookies() from next/headers, add common iterator methods
+        // These are needed when the mock is passed to functions that use .entries(), .keys(), etc.
+        // (e.g., Object.fromEntries(headers.entries()) in buildLegacyHeaders)
+        const needsIteratorMethods = baseMockName === 'headers' || baseMockName === 'cookies';
+        let enhancedContents = contents;
+        if (needsIteratorMethods && contents.trim().startsWith('{')) {
+            // Add iterator methods that operate on the scenario data
+            // Use the dataKey (original call signature or canonical key)
+            const quotedDataKey = quotePropertyKey(dataKey);
+            const iteratorMethods = `,
+  entries: () => Object.entries(scenarios().data()?.${quotedDataKey} || {}),
+  keys: () => Object.keys(scenarios().data()?.${quotedDataKey} || {}),
+  values: () => Object.values(scenarios().data()?.${quotedDataKey} || {}),
+  forEach: (fn) => Object.entries(scenarios().data()?.${quotedDataKey} || {}).forEach(([k, v]) => fn(v, k)),
+  has: (key) => Object.prototype.hasOwnProperty.call(scenarios().data()?.${quotedDataKey} || {}, key)`;
+            // Insert before the closing brace (handle trailing whitespace)
+            enhancedContents = contents.replace(/\}\s*$/, iteratorMethods + '\n}');
+        }
+        // Classes need to be mocked as classes, not functions.
+        // They're used with `new ClassName(args)` which requires a proper constructor.
+        // A function mock like `function ClassName() { return value; }` doesn't work because
+        // `new ClassName("arg")` wouldn't create the expected instance.
+        // For Error subclasses (detected by name ending in "Error"), extend Error for proper error handling.
+        if (entityType === 'class') {
+            const isErrorSubclass = baseMockName.endsWith('Error');
+            const superCall = isErrorSubclass ? 'super(message);' : '';
+            const nameAssignment = isErrorSubclass
+                ? `this.name = '${baseMockName}';`
+                : '';
+            // Use the base class name for the class definition, not the call-signature-derived name.
+            // When mockName is "StatsCalculator(supabase)", baseMockName is "StatsCalculator"
+            // and derivedFunctionName would be "StatsCalculator_supabase" which is wrong.
+            // Classes are instantiated with `new ClassName(args)` so the name must match the original.
+            const className = baseMockName;
+            // Use the already-generated contents (which has proper function wrappers for methods)
+            // instead of raw scenarios().data() which would create non-callable string-keyed properties.
+            // For classes with methods like calculateStats(), the contents will have:
+            //   { calculateStats: (...args) => scenarios().data()?.["key"]?.["calculateStats(...)"], ... }
+            // which makes methods callable on the instance.
+            const classContents = enhancedContents.trim().startsWith('{')
+                ? enhancedContents
+                : `scenarios().data()?.${quotePropertyKey(dataKey)} || {}`;
+            return `class ${className}${isErrorSubclass ? ' extends Error' : ''} {
+  constructor(message) {
+    ${superCall}
+    ${nameAssignment}
+    Object.assign(this, ${classContents});
+  }
+}`;
+        }
+        // Generate safe function name:
+        // 1. For call signatures: use derivedFunctionName
+        //    e.g., "useFetcher<User>()" becomes "useFetcher_User"
+        //    e.g., "db.select(usersQuery)" becomes "db_select_usersQuery"
+        // 2. With uniqueFunctionSuffix option: append suffix for unique naming
+        //    e.g., baseMockName = "useFetcher", suffix = "entityDiffFetcher" -> "useFetcher_entityDiffFetcher"
+        // 3. EXCEPTION: When keepOriginalFunctionName is true (for single-call cases), use the base name
+        let safeFunctionName;
+        if (options?.keepOriginalFunctionName) {
+            safeFunctionName = baseMockName;
+        }
+        else if (options?.uniqueFunctionSuffix) {
+            safeFunctionName = `${baseMockName}_${options.uniqueFunctionSuffix}`;
+        }
+        else if (mockNameIsCallSignature && derivedFunctionName) {
+            safeFunctionName = derivedFunctionName;
+        }
+        else {
+            safeFunctionName = baseMockName;
+        }
+        // Check if this function returns a function (detected by double-call pattern: mockName(args)())
+        // This happens when the schema has keys like "wrapThrows(() => JSON.parse(savedFilters))()"
+        // where the function call is immediately followed by another call.
+        // Example usage: const result = wrapThrows(() => JSON.parse(x))(); // double call
+        const isHigherOrderFunction = Object.keys(relevantReturnValueSchema ?? {}).some((key) => {
+            if (!key.startsWith(baseMockName))
+                return false;
+            // Find the first ( after baseMockName (the start of the function call)
+            const firstOpenParen = key.indexOf('(', baseMockName.length);
+            if (firstOpenParen === -1)
+                return false;
+            // Skip if the ( is not immediately after the mock name
+            // (there might be type params like func<T>() - handle by checking for < or ()
+            const between = key.slice(baseMockName.length, firstOpenParen);
+            if (between.length > 0 && !between.startsWith('<'))
+                return false;
+            // Find the matching ) for the first ( using depth counting
+            let depth = 1;
+            let i = firstOpenParen + 1;
+            while (i < key.length && depth > 0) {
+                if (key[i] === '(')
+                    depth++;
+                if (key[i] === ')')
+                    depth--;
+                i++;
+            }
+            if (depth !== 0)
+                return false; // Unbalanced parentheses
+            // Now i points just after the matching )
+            // Check if there's another ( immediately (indicating double call)
+            const remaining = key.slice(i);
+            if (remaining.startsWith('('))
+                return true;
+            return false;
+        });
+        // Use ...args to accept any number of arguments - prevents TypeScript errors
+        // like "Expected 0 arguments, but got X" when caller passes arguments
+        // For higher-order functions, wrap the return in an arrow function
+        // so that mockFunc(arg)() works correctly (outer call returns a function, inner call gets the data)
+        const returnValue = isHigherOrderFunction
+            ? `() => (${enhancedContents})`
+            : enhancedContents;
+        // Inline the return value directly in the function to avoid module-level const
+        // that would be evaluated before scenario context is ready
+        // Add fallback for simple data path returns to prevent undefined errors (e.g., createTheme)
+        // Only add fallback if returnValue is a simple data accessor (starts with scenarios().data())
+        // and doesn't already have nested structure (object literal, array, or method chains like .map())
+        const isSimpleDataPath = returnValue.startsWith('scenarios().data()') &&
+            !returnValue.trim().startsWith('{') &&
+            !returnValue.trim().startsWith('[') &&
+            !returnValue.includes('.map('); // Exclude method chains
+        const safeReturnValue = isSimpleDataPath
+            ? `${returnValue} ?? {}`
+            : returnValue;
+        const refName = `_${safeFunctionName}Ref`;
+        const assignment = `${refName}.current = ${safeReturnValue};`;
+        const ifBlock = `if (!${refName}.current) {\n${indent(assignment)}\n}`;
+        const body = `${ifBlock}\nreturn ${refName}.current;`;
+        return [
+            `// PATCHED: memoize to return stable reference (prevents infinite useEffect re-triggers)`,
+            `const ${refName} = {`,
+            `  current: null,`,
+            `};`,
+            `${isRootAsyncFunction ? 'async ' : ''}function ${safeFunctionName}(...args) {`,
+            indent(body),
+            `}`,
+        ].join('\n');
     }
     else {
-        return `const ${mockName} = ${contents}`;
+        // Generate safe const name:
+        // 1. For call signatures: use derivedFunctionName
+        // 2. With uniqueFunctionSuffix option: append suffix for unique naming
+        // 3. EXCEPTION: When keepOriginalFunctionName is true (for single-call cases), use the base name
+        let safeName;
+        if (options?.keepOriginalFunctionName) {
+            safeName = baseMockName;
+        }
+        else if (options?.uniqueFunctionSuffix) {
+            safeName = `${baseMockName}_${options.uniqueFunctionSuffix}`;
+        }
+        else if (mockNameIsCallSignature && derivedFunctionName) {
+            safeName = derivedFunctionName;
+        }
+        else {
+            safeName = baseMockName;
+        }
+        // Get any jsx-component properties that need to be preserved from the original
+        const jsxProperties = getJsxComponentProperties(mockName, relevantReturnValueSchema);
+        // If there are jsx-component properties, add them as references to the original
+        if (jsxProperties.length > 0) {
+            const jsxPreservations = jsxProperties
+                .map((prop) => `${prop}: ${mockName}__cyOriginal.${prop}`)
+                .join(',\n');
+            if (contents.trim().startsWith('{')) {
+                // Contents is already an object - insert jsx preservations before the closing brace
+                const enhancedContents = contents.replace(/\}\s*$/, `,\n${indent(jsxPreservations)}\n}`);
+                return `const ${safeName} = ${enhancedContents}`;
+            }
+            else {
+                // Contents is a simple accessor (e.g., scenarios().data()?.["MockName"])
+                // Wrap it in an object with the jsx preservations
+                return `const ${safeName} = {\n${indent(`...${contents}`)},\n${indent(jsxPreservations)}\n}`;
+            }
+        }
+        return `const ${safeName} = ${contents}`;
     }
 }
 //# sourceMappingURL=constructMockCode.js.map