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

package/analyzer-template/project/constructMockCode.ts

@@ -4,8 +4,9 @@ import {
   functionArguments,
   cleanOutBoundary,
   fillInDirectSchemaGapsAndUnknowns,
+  removeDuplicateFunctionCalls,
 } from '~codeyam/ai';
-import { DataStructure, DeepReadonly } from '~codeyam/types';
+import { DataStructure, DeepReadonly, EntityType } from '~codeyam/types';
 
 interface ReturnValuePart {
   name: string;
@@ -18,10 +19,141 @@ interface ReturnValuePart {
   nested?: ReturnValuePart[];
   isAsyncFunction?: boolean;
   isStructural?: boolean;
+  hasNoReturnData?: boolean; // true when function has only signature entries, no functionCallReturnValue
   // Maps literal argument values to their specific nested structures for conditional dispatch
   argVariants?: Map<string, ReturnValuePart[]>;
 }
 
+/**
+ * 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: string): string {
+  // Extract components from the signature
+  const components: string[] = [];
+
+  // 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: string): boolean {
+  // 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: string,
+  schema: Record<string, string>,
+): string[] {
+  const jsxProperties: string[] = [];
+
+  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.
@@ -153,25 +285,81 @@ function funcArgs(functionSignature: string): string[] {
 
 // 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: string) {
   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);
 }
 
+/**
+ * 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: string,
   dependencySchemas: DeepReadonly<DataStructure['dependencySchemas']>,
+  entityType?: EntityType,
+  _canonicalKey?: string, // DEPRECATED: No longer used, kept for API compatibility
+  options?: {
+    keepOriginalFunctionName?: boolean;
+    uniqueFunctionSuffix?: string;
+    skipOriginalSpread?: boolean; // Skip spreading from __cyOriginal when it won't be defined
+  },
 ) {
-  const mockNameParts = splitOutsideParenthesesAndArrays(mockName);
+  // 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: string;
+
+  const mockNameParts = splitOutsideParenthesesAndArrays(baseMockName);
 
   let relevantReturnValueSchema: DataStructure['returnValueSchema'] | undefined;
   let dataStructurePath: string | undefined;
   let dataStructureValue: string | undefined;
+  let foundEntityWithSignature = false;
+  let signatureSchema: DataStructure['signatureSchema'] | undefined;
 
-  for (const filePath in dependencySchemas) {
+  entitySearch: for (const filePath in dependencySchemas) {
     for (const entityName in dependencySchemas[filePath]) {
-      if (entityName !== mockNameParts[0]) continue;
+      // 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 ?? {},
@@ -193,16 +381,145 @@ export default function constructMockCode(
         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) return;
+  // 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: string): string => {
+    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: DataStructure['returnValueSchema'] | undefined,
+  ): boolean => {
+    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'
@@ -226,6 +543,99 @@ export default function constructMockCode(
     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: string;
+      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: ReturnValuePart = {
     name: dataStructureName,
     isArray: isRootArray,
@@ -245,7 +655,11 @@ export default function constructMockCode(
       basePaths[0] = 'scenarios().data()';
     }
 
-    const optionalAccess = (name: string, stripArguments = false) => {
+    const optionalAccess = (
+      name: string,
+      stripArguments = false,
+      isRootAccess = false,
+    ) => {
       if (stripArguments && name.includes('(')) {
         name = name.split('(')[0] + '()';
       }
@@ -254,11 +668,21 @@ export default function constructMockCode(
       // 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 = () => {
@@ -273,7 +697,15 @@ export default function constructMockCode(
       }
 
       const addReturnValueFunctionAccessor = (dataPath: string) => {
-        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]')}`;
           }
@@ -285,7 +717,8 @@ export default function constructMockCode(
       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;
           }
@@ -294,7 +727,8 @@ export default function constructMockCode(
               ? 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;
@@ -313,9 +747,23 @@ export default function constructMockCode(
         returnsFunctionArgs,
         returnsFunctionArray,
         isAsyncFunction,
+        hasNoReturnData,
       } = returnValue;
 
-      const nestedContent: (string | undefined)[] = (nested ?? []).map(
+      // 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: (string | undefined)[] = (filteredNested ?? []).map(
         (nestedItem) => {
           const nestedContent = constructReturnValueString(
             nestedItem,
@@ -325,9 +773,53 @@ export default function constructMockCode(
         },
       );
 
+      // 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)
@@ -336,79 +828,717 @@ export default function constructMockCode(
         returnValue.name === '[0]' &&
         nested &&
         nested.length > 0;
+      // 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 &&
+        (!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: string = 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}`;
+          levelContents = `(${argsString}) => {\n${indent(funcContents)}\n}`;
 
-        if (!isArray) {
-          return levelContents;
+          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 (
+
+      // 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(
+            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: string,
+              pos: number,
+            ): number => {
+              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: string): string => {
+              const result: string[] = [];
+              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: string,
+              skipFirstBrace = false,
+            ): string => {
+              const result: string[] = [];
+              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: string): string => {
+              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: string,
+              ): number => {
+                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))`;
             }
           } else {
             returnValueContents = `[\n${indent(levelContents)}\n]`;
           }
         } 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}`;
+          }
         }
       }
 
@@ -420,6 +1550,13 @@ export default function constructMockCode(
       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: string[], b: string[]) => b.length - a.length,
         )[0];
@@ -479,8 +1616,18 @@ export default function constructMockCode(
             // Use all paths for fallback (existing behavior)
             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 =
@@ -490,14 +1637,29 @@ export default function constructMockCode(
           content = `${cleanOutTypes(name)}: ${isAsyncFunction ? 'async ' : ''}(${argsString}) => {\n${indent(funcContents)}\n}`;
         } 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: string;
+          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}`;
         }
       } else {
         if (!isValidKey(name)) {
           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}`;
         }
@@ -512,34 +1674,91 @@ export default function constructMockCode(
   };
 
   // Create the return value structure
-  const sortedKeys = Object.keys(relevantReturnValueSchema ?? {}).sort(
-    (a: string, b: string) => {
-      const aParts = splitOutsideParenthesesAndArrays(a);
-      const bParts = splitOutsideParenthesesAndArrays(b);
-
-      const maxLength = Math.max(aParts.length, bParts.length);
-      for (let i = 0; i < maxLength; ++i) {
-        const aPart = aParts[i];
-        const bPart = bParts[i];
-
-        if (!aPart) return -1;
-        if (!bPart) return 1;
-
-        if (aPart === bPart) continue;
-
-        const aName = aPart.split('(')[0];
-        const bName = bPart.split('(')[0];
+  // 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: string, b: string) => {
+    const aParts = splitOutsideParenthesesAndArrays(a);
+    const bParts = splitOutsideParenthesesAndArrays(b);
+
+    const maxLength = Math.max(aParts.length, bParts.length);
+    for (let i = 0; i < maxLength; ++i) {
+      const aPart = aParts[i];
+      const bPart = bParts[i];
+
+      if (!aPart) return -1;
+      if (!bPart) return 1;
+
+      if (aPart === bPart) continue;
+
+      const aName = aPart.split('(')[0];
+      const bName = bPart.split('(')[0];
+
+      if (aName !== bName) {
+        return aName.localeCompare(bName);
+      } else {
+        return aPart.localeCompare(bPart);
+      }
+    }
 
-        if (aName !== bName) {
-          return aName.localeCompare(bName);
-        } else {
-          return aPart.localeCompare(bPart);
-        }
+    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<string>();
+  const functionCallsWithReturnValue = new Set<string>();
+
+  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);
       }
 
-      return 0;
-    },
-  );
+      // 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];
@@ -574,7 +1793,9 @@ export default function constructMockCode(
       }
     }
 
-    if (parts[0].split('(')[0] !== mockName) continue;
+    // 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) =>
@@ -589,13 +1810,61 @@ export default function constructMockCode(
     // 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) continue;
@@ -641,6 +1910,17 @@ export default function constructMockCode(
       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) {
@@ -687,6 +1967,25 @@ export default function constructMockCode(
           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) {
@@ -729,7 +2028,52 @@ export default function constructMockCode(
                 }
               }
             } 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 as string)
+                );
+              });
+
+              // 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 = [];
+              }
             }
           }
         }
@@ -752,6 +2096,12 @@ export default function constructMockCode(
             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;
         }
@@ -759,11 +2109,35 @@ export default function constructMockCode(
         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: ReturnValuePart) => p.name.split('(')[0];
       let relevantPart = returnValueSection.nested?.find(
         (p: ReturnValuePart) =>
-          withoutArgs(p) === withoutArgs({ name: part } as ReturnValuePart),
+          withoutArgs(p) === withoutArgs({ name: basePart } as ReturnValuePart),
       );
+
+      // 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 ||= [];
+        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 === '[]') {
@@ -787,6 +2161,33 @@ export default function constructMockCode(
           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.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) &&
@@ -827,20 +2228,59 @@ export default function constructMockCode(
         ) {
           returnValueSection.nested.push(relevantPart);
         }
-      } else if (
-        funcArgs(part).join(',') !== funcArgs(relevantPart.name).join(',')
-      ) {
-        const existingArgs = relevantPart.args.find(
-          (args) => args.join(',') === funcArgs(part).join(','),
-        );
+      } 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.push(funcArgs(part));
+          if (!existingArgs) {
+            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;
       }
 
@@ -848,10 +2288,28 @@ export default function constructMockCode(
     }
   }
 
+  // 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: string[],
@@ -863,7 +2321,9 @@ export default function constructMockCode(
 
       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}`;
 
@@ -877,15 +2337,202 @@ export default function constructMockCode(
       return code;
     };
 
-    const returnParts = [
-      `...${mockNameParts[0]}__cyOriginal`,
-      subPart(mockNameParts.slice(1), originalLib),
-    ].filter(Boolean);
+    const returnParts = skipOriginalSpread
+      ? [subPart(mockNameParts.slice(1), originalLib)]
+      : [
+          `...${mockNameParts[0]}__cyOriginal`,
+          subPart(mockNameParts.slice(1), originalLib),
+        ];
 
-    return `const ${mockNameParts[0]} = {\n${indent(returnParts.join(',\n'))}\n};`;
+    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: string;
+    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: string;
+    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}`;
   }
 }