added self repair and removed player ai

app/actions/ai.actions.ts

@@ -1,19 +1,30 @@
 "use server";
 
-import {
-  expertYouTubePrompt,
-  heroCoderPrompt,
-  heroCreativePrompt,
-} from "@/lib/AiPrompts";
-import { revalidatePath } from "next/cache";
-import { GoogleGenAI, Modality, Type } from "@google/genai";
-import { BattleReport, HeroData } from "@/types"; // Assuming HeroData type will be updated in "@/types"
+import { GoogleGenAI, Modality } from "@google/genai";
 import { v2 as cloudinary } from "cloudinary";
-import wav from "wav";
+import { revalidatePath } from "next/cache";
 import { Readable } from "stream";
-import { extractAndCleanCode, sanitizePowerLogicCode } from "@/lib/utils";
+import wav from "wav";
+
+import { expertYouTubePrompt, heroCoderPrompt, heroCreativePrompt } from "@/lib/AiPrompts";
 import { connectToDatabase } from "@/lib/database";
+import { extractAndCleanCode, sanitizePowerLogicCode } from "@/lib/utils";
 import Hero from "@/model/hero.model";
+import { BattleReport, HeroData } from "@/types";
+import { heroDataSchema } from "@/lib/validators";
+
+// --- Defensive Environmental Variable Checks ---
+// Ensure all required environment variables are present at startup.
+if (
+  !process.env.GEMINI_API_KEY ||
+  !process.env.CLOUDINARY_CLOUD_NAME ||
+  !process.env.CLOUDINARY_API_KEY ||
+  !process.env.CLOUDINARY_API_SECRET
+) {
+  throw new Error(
+    "FATAL: Missing critical environment variables for AI or Cloudinary. Application cannot start."
+  );
+}
 
 // --- Cloudinary Configuration ---
 cloudinary.config({
@@ -23,71 +34,39 @@ cloudinary.config({
   secure: true,
 });
 
-// Male voice options based on common naming conventions and user's list
-const MALE_VOICES = [
-  "Puck",
-  "Charon",
-  "Fenrir",
-  "Orus",
-  "Enceladus",
-  "Iapetus",
-  "Umbriel",
-  "Algieba",
-  "Algenib",
-  "Rasalgethi",
-
-  "Alnilam",
-  "Schedar",
-  "Achird",
-  "Pulcherrima",
-  "Zubenelgenubi",
-  "Sadaltager",
-
-  "Sadachbia",
-];
-
-// Female voice options based on common naming conventions and user's list
-const FEMALE_VOICES = [
-  "Zephyr",
-  "Kore",
-  "Leda",
-  "Aoede",
-  "Callirrhoe",
-  "Autonoe",
-  "Despina",
-  "Erinome",
-  "Achernar",
-  "Gacrux",
-  "Laomedeia",
-  "Sulafat",
-  "Vindemiatrix",
-];
-
-// Helper to get a random voice of a specific gender
+// --- Voice Options (unchanged) ---
+const MALE_VOICES = ["Puck", "Charon", "Fenrir", "Orus", "Enceladus", "Iapetus", "Umbriel", "Algieba", "Algenib", "Rasalgethi", "Alnilam", "Schedar", "Achird", "Pulcherrima", "Zubenelgenubi", "Sadaltager", "Sadachbia"];
+const FEMALE_VOICES = ["Zephyr", "Kore", "Leda", "Aoede", "Callirrhoe", "Autonoe", "Despina", "Erinome", "Achernar", "Gacrux", "Laomedeia", "Sulafat", "Vindemiatrix"];
+
 function getRandomVoice(gender: "Male" | "Female"): string {
+  // DEFENSIVE: Handle potential invalid gender input gracefully.
   const voices = gender === "Male" ? MALE_VOICES : FEMALE_VOICES;
+  if (!voices || voices.length === 0) {
+    console.error(`[getRandomVoice] No voices available for gender: ${gender}.`);
+    return MALE_VOICES[0]; // Return a guaranteed safe default.
+  }
   return voices[Math.floor(Math.random() * voices.length)];
 }
 
-// We can place this type definition in a shared file or at the top of the AI utility file.
-
-export const generateYouTubeMetadata = async (report: BattleReport) => {
-  console.log("Generating YouTube metadata with expert AI prompt...");
-
-  const apiKey = process.env.GEMINI_API_KEY;
-  if (!apiKey) {
-    throw new Error("GEMINI_API_KEY is not configured.");
+// --- generateYouTubeMetadata (Refactored for Resilience) ---
+export const generateYouTubeMetadata = async (report: BattleReport | null) => {
+  // DEFENSIVE: Create a safe fallback metadata object.
+  const fallbackMetadata = {
+    title: `Square Battles: ${report?.winner?.name || "An Epic Draw"}`,
+    description: "An intense battle in Square Battles! Who will emerge victorious? Like and subscribe for more computer-generated chaos!",
+    tags: "Square Battles, indie game, physics game, simulation, auto battler",
+  };
+
+  // DEFENSIVE: Check for valid input.
+  if (!report) {
+    console.warn("[AI] generateYouTubeMetadata called with null report. Returning fallback.");
+    return fallbackMetadata;
   }
 
   try {
-    const ai = new GoogleGenAI({ apiKey });
-
-    // This is the specific battle data we're sending for this request
-    const userPromptForThisBattle = `Here is the BattleReport for the video:\n${JSON.stringify(
-      report,
-      null,
-      2
-    )}`;
+    const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY as string });
+    const userPromptForThisBattle = `Here is the BattleReport for the video:\n${JSON.stringify(report, null, 2)}`;
+
     const response = await ai.models.generateContent({
       model: "gemini-2.5-flash",
       contents: userPromptForThisBattle,
@@ -97,195 +76,101 @@ export const generateYouTubeMetadata = async (report: BattleReport) => {
       },
     });
 
-    console.log(response.text);
-
     const aiResponseText = response.text;
     if (!aiResponseText) {
-      throw new Error("AI response is empty.");
+      console.warn("[AI] YouTube metadata response was empty. Using fallback.");
+      return fallbackMetadata;
     }
 
-    // The AI response is a JSON string, so we parse it into an object
-    const metadata = JSON.parse(aiResponseText);
+    // DEFENSIVE: Wrap JSON.parse in a try-catch to prevent crashes from malformed AI responses.
+    let metadata;
+    try {
+      metadata = JSON.parse(aiResponseText);
+    } catch (parseError) {
+      console.error("[AI] Failed to parse YouTube metadata JSON from AI. Using fallback.", parseError);
+      return fallbackMetadata;
+    }
 
-    // You could add validation here to ensure it has title, description, tags
+    // DEFENSIVE: Validate the parsed object's structure.
     if (!metadata.title || !metadata.description || !metadata.tags) {
-      throw new Error("AI returned malformed JSON.");
+      console.warn("[AI] YouTube metadata from AI was missing required keys. Using fallback.");
+      return fallbackMetadata;
     }
 
-    // revalidatePath("/"); // This might not be necessary depending on your app flow
-
     return metadata;
   } catch (error) {
-    console.error("Error generating metadata with AI:", error);
-    // Return a fallback or re-throw the error
-    return {
-      title: `Square Battles: ${report.winner?.name || "Draw"}`,
-      description:
-        "An epic battle in Square Battles! Like and subscribe for more!",
-      tags: "Square Battles, indie game, physics game",
-    };
+    console.error("[AI] Error generating YouTube metadata:", error);
+    return fallbackMetadata; // Return the safe fallback on any error.
   }
 };
 
-const heroDataSchema = {
-  type: Type.OBJECT,
-  properties: {
-    heroName: { type: Type.STRING },
-    heroGender: { type: Type.STRING },
-    heroDescription: { type: Type.STRING },
-    heroColor: { type: Type.STRING },
-    heroHealth: { type: Type.NUMBER },
-    heroSpeed: { type: Type.NUMBER },
-    basicAttack: {
-      type: Type.OBJECT,
-      properties: {
-        type: { type: Type.STRING }, // e.g., "RANGED", "MELEE", "CONTACT"
-        damage: { type: Type.NUMBER },
-        cooldown: { type: Type.NUMBER },
-        range: { type: Type.NUMBER },
-        knockback: { type: Type.NUMBER },
-      },
-      required: ["type", "damage", "cooldown", "range", "knockback"],
-    },
-    powerName: { type: Type.STRING },
-    powerDescription: { type: Type.STRING },
-    powerLogicDescription: { type: Type.STRING },
-    introLine: { type: Type.STRING },
-    superpowerActivationLine: { type: Type.STRING },
-    avatarPrompt: { type: Type.STRING },
-    iconPrompt: { type: Type.STRING },
-    tags: { type: Type.ARRAY, items: { type: Type.STRING } },
-  },
-  required: [
-    "heroName",
-    "heroGender",
-    "heroDescription",
-    "heroColor",
-    "heroHealth",
-    "heroSpeed",
-    "basicAttack",
-    "powerName",
-    "powerDescription",
-    "powerLogicDescription",
-    "introLine",
-    "superpowerActivationLine",
-    "avatarPrompt",
-    "iconPrompt",
-    "tags",
-  ],
-};
-
-// --- NEW, COMPLETELY REWRITTEN 'heroGenerationPrompt' ---
-
-export const generateAndSaveHero = async (
-  theme: string,
-  path?: string
-): Promise<HeroData | null> => {
-  console.log(`Generating two hero concepts for theme: ${theme}...`);
-
-  const apiKey = process.env.GEMINI_API_KEY;
-  if (!apiKey) {
-    console.error("GEMINI_API_KEY is not configured.");
-    return null;
-  }
-
+// --- generateAndSaveHero (Refactored for Resilience) ---
+export const generateAndSaveHero = async (theme: string, path?: string): Promise<HeroData | null> => {
   try {
     await connectToDatabase();
 
-    // --- STEP 1: PRE-EMPTIVE CHECK ---
-    // Fetch all existing hero names first.
-    const existingHeroes = await Hero.find().select("heroName");
+    const existingHeroes = await Hero.find().select("heroName").lean();
     const existingNames = existingHeroes.map((h) => h.heroName);
-
     let userPromptForThisTheme = `Generate a unique hero concept for the theme: "${theme}".`;
-
     if (existingNames.length > 0) {
-      const exclusionList = existingNames.join(", ");
-      userPromptForThisTheme += ` \n\nIMPORTANT: You MUST NOT generate a hero whose name is on this list of already existing heroes: ${exclusionList}.`;
-      console.log(`Injecting exclusion list into prompt: ${exclusionList}`);
+      userPromptForThisTheme += ` \n\nIMPORTANT: You MUST NOT generate a hero whose name is on this list of already existing heroes: ${existingNames.join(", ")}.`;
     }
 
-    const ai = new GoogleGenAI({ apiKey });
+    const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY as string });
 
-    // FIX: Make the prompt for the second hero explicitly unique
     console.log("Calling Creative Director AI...");
-
     const creativeResponse = await ai.models.generateContent({
       model: "gemini-2.5-pro",
       contents: userPromptForThisTheme,
       config: {
         systemInstruction: heroCreativePrompt,
         responseMimeType: "application/json",
-        responseSchema: heroDataSchema,
+        responseSchema: heroDataSchema
       },
     });
 
     const creativeText = creativeResponse.text;
-    if (!creativeText) throw new Error(`AI response for hero was empty.`);
+    if (!creativeText) throw new Error("AI creative response was empty.");
+    
+    let partialHeroData;
+    try {
+      partialHeroData = JSON.parse(creativeText);
+    } catch{
+      throw new Error("AI returned malformed JSON for hero data.");
+    }
 
-    const partialHeroData = JSON.parse(creativeText);
+    // DEFENSIVE: Check if the generated name already exists (a race condition or AI mistake)
+    if (existingNames.includes(partialHeroData.heroName)) {
+        console.warn(`[AI] Generated a duplicate hero name: ${partialHeroData.heroName}. Aborting.`);
+        return null; // Gracefully fail
+    }
 
-    // --- STEP 2: Call the Logic Coder AI ---
     console.log("Calling Logic Coder AI to translate description...");
-    const finalSanitizedCode = await generatePowerLogicCode(
-      partialHeroData.powerLogicDescription
-    );
-    // --- STEP 4: Generate Assets (your existing logic) ---
+    const finalSanitizedCode = await generatePowerLogicCode(partialHeroData.powerLogicDescription);
+    if (!finalSanitizedCode) {
+      throw new Error("Failed to generate valid power logic code after multiple attempts.");
+    }
+    
     console.log("Generating assets for", partialHeroData.heroName);
-
-    // --- Generate and Upload Assets ---
     const [avatarBuffer, iconBuffer] = await Promise.all([
       generateImageWithGemini(partialHeroData.avatarPrompt),
       generateImageWithGemini(partialHeroData.iconPrompt),
     ]);
-    if (!avatarBuffer || !iconBuffer)
-      throw new Error(
-        `Failed to generate image buffers for ${partialHeroData.heroName}.`
-      );
-
-    const publicIdBase = partialHeroData.heroName
-      .toLowerCase()
-      .replace(/ /g, "_");
+    if (!avatarBuffer || !iconBuffer) throw new Error("Failed to generate one or more image buffers.");
+    
+    const publicIdBase = partialHeroData.heroName.toLowerCase().replace(/ /g, "_");
     const [avatarUrl, iconUrl] = await Promise.all([
       uploadToCloudinary(avatarBuffer, `${publicIdBase}_avatar`, "image"),
       uploadToCloudinary(iconBuffer, `${publicIdBase}_icon`, "image"),
     ]);
-    if (!avatarUrl || !iconUrl)
-      throw new Error(
-        `Failed to upload images for ${partialHeroData.heroName}.`
-      );
-
-    partialHeroData.avatarUrl = avatarUrl;
-    partialHeroData.iconUrl = iconUrl;
-
-    const selectedVoice = getRandomVoice(
-      partialHeroData.heroGender as "Male" | "Female"
-    );
-    const [introLineAudioUrl, superpowerActivationLineAudioUrl] =
-      await Promise.all([
-        generateAudio(
-          partialHeroData.introLine,
-          partialHeroData.heroName,
-          selectedVoice,
-          "intro"
-        ),
-        generateAudio(
-          partialHeroData.superpowerActivationLine,
-          partialHeroData.heroName,
-          selectedVoice,
-          "superpower"
-        ),
-      ]);
-
-    partialHeroData.introLineAudioUrl = introLineAudioUrl || undefined;
-    partialHeroData.superpowerActivationLineAudioUrl =
-      superpowerActivationLineAudioUrl || undefined;
-
-    console.log(
-      `Successfully generated and processed hero:`,
-      partialHeroData.heroName
-    );
+    if (!avatarUrl || !iconUrl) throw new Error("Failed to upload one or more images to Cloudinary.");
 
+    const selectedVoice = getRandomVoice(partialHeroData.heroGender as "Male" | "Female");
+    const [introLineAudioUrl, superpowerActivationLineAudioUrl] = await Promise.all([
+      generateAudio(partialHeroData.introLine, partialHeroData.heroName, selectedVoice, "intro"),
+      generateAudio(partialHeroData.superpowerActivationLine, partialHeroData.heroName, selectedVoice, "superpower"),
+    ]);
+    
     const finalHeroData: HeroData = {
       ...partialHeroData,
       powerLogic: finalSanitizedCode,
@@ -293,75 +178,76 @@ export const generateAndSaveHero = async (
       iconUrl,
       aiVoicer: selectedVoice,
       introLineAudioUrl: introLineAudioUrl || undefined,
-      superpowerActivationLineAudioUrl:
-        superpowerActivationLineAudioUrl || undefined,
+      superpowerActivationLineAudioUrl: superpowerActivationLineAudioUrl || undefined,
     };
+    
     const newHero = new Hero(finalHeroData);
     await newHero.save();
 
     console.log(`Successfully generated and saved hero: ${newHero.heroName}`);
-
     if (path) revalidatePath(path);
-
     return JSON.parse(JSON.stringify(newHero));
+
   } catch (error) {
-    console.error("Error generating hero concepts with AI:", error);
-    return null;
+    console.error("⛔️ Top-Level Error in generateAndSaveHero:", error);
+    return null; // Gracefully return null on any failure.
   }
 };
 
-export const generatePowerLogicCode = async (
-  powerLogicDescription: string
-): Promise<string> => {
-  // Call Gemini to generate code
-
-  try {
-    const apiKey = process.env.GEMINI_API_KEY;
-    if (!apiKey) {
-      console.error("GEMINI_API_KEY is not configured.");
-      throw new Error("GEMINI_API_KEY is not configured.");
-    }
-    const ai = new GoogleGenAI({ apiKey });
-
-    const coderResponse = await ai.models.generateContent({
-      model: "gemini-2.5-pro",
-      contents: powerLogicDescription,
-      config: {
-        systemInstruction: heroCoderPrompt,
-      },
-    });
-
-    const rawPowerLogicCode = coderResponse.text;
-    console.log("Raw response from AI:", rawPowerLogicCode);
-
-    if (!rawPowerLogicCode) {
-      throw new Error("Coder AI did not return a powerLogic string.");
-    }
-
-    // Clean the AI's response to remove markdown and other artifacts.
-    const extractedCode = extractAndCleanCode(rawPowerLogicCode);
-    console.log("Cleaned powerLogic code:", extractedCode);
-
-    if (!extractedCode) {
-      throw new Error("After cleaning, the AI-generated code was empty.");
+// --- generatePowerLogicCode (Refactored with Self-Healing Retry Loop) ---
+export const generatePowerLogicCode = async (powerLogicDescription: string): Promise<string | null> => {
+  const MAX_ATTEMPTS = 3;
+  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+    try {
+      console.log(`[AI Logic] Attempt ${attempt}/${MAX_ATTEMPTS} for: "${powerLogicDescription.substring(0, 50)}..."`);
+      
+      const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY! });
+      const coderResponse = await ai.models.generateContent({
+        model: "gemini-2.5-pro",
+        contents: powerLogicDescription,
+        config: { systemInstruction: heroCoderPrompt },
+      });
+
+      const rawPowerLogicCode = coderResponse.text;
+      if (!rawPowerLogicCode) {
+        throw new Error("Coder AI returned an empty response.");
+      }
+      
+      const extractedCode = extractAndCleanCode(rawPowerLogicCode);
+      if (!extractedCode) {
+        throw new Error("After cleaning, the AI-generated code was empty.");
+      }
+      
+      // The sanitization function will throw if the code is syntactically invalid.
+      const sanitizedCode = sanitizePowerLogicCode(extractedCode);
+      
+      console.log("[AI Logic] Successfully generated and validated code.");
+      return sanitizedCode; // Success! Exit the loop and return the code.
+
+    } catch (error) {
+      console.warn(`[AI Logic] Attempt ${attempt} failed.`, error);
+      if (attempt === MAX_ATTEMPTS) {
+        console.error("[AI Logic] All attempts to generate valid code failed.");
+        return null; // Return null after all retries have failed.
+      }
+      // Optional: wait a moment before retrying
+      await new Promise(res => setTimeout(res, 1000)); 
     }
-
-    console.log("Successfully generated and cleaned powerLogic code.");
-
-    // Sanitize and validate the code
-    return sanitizePowerLogicCode(extractedCode);
-  } catch (error) {
-    console.error("Error generating or sanitizing powerLogic code:", error);
-    throw new Error("Failed to generate valid powerLogic code from AI.");
   }
+  return null; // Should be unreachable, but acts as a final fallback.
 };
 
-// --- Helper function to call Gemini for Image Generation ---
+
+// --- Helper Functions (Refactored for Resilience) ---
+
 export async function generateImageWithGemini(prompt: string): Promise<Buffer | null> {
-  const apiKey = process.env.GEMINI_API_KEY;
-  if (!apiKey) return null;
+  // DEFENSIVE: check prompt
+  if (!prompt || typeof prompt !== 'string' || prompt.trim() === '') {
+    console.error("[Gemini Image] Called with invalid prompt.");
+    return null;
+  }
   try {
-    const ai = new GoogleGenAI({ apiKey });
+    const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY! });
     const imagePrompt = `High-quality, detailed, vibrant image. Painterly 2D style, square format, epic lighting, strong character focus. No text/borders. PROMPT: ${prompt}`;
     const response = await ai.models.generateContent({
       model: "gemini-2.0-flash-preview-image-generation",
@@ -369,17 +255,11 @@ export async function generateImageWithGemini(prompt: string): Promise<Buffer |
       config: { responseModalities: [Modality.TEXT, Modality.IMAGE] },
     });
 
-    const imagePart = response.candidates?.[0]?.content?.parts?.find(
-      (p) => "inlineData" in p
-    );
-    if (
-      imagePart &&
-      "inlineData" in imagePart &&
-      imagePart.inlineData &&
-      typeof imagePart.inlineData.data === "string"
-    ) {
+    const imagePart = response.candidates?.[0]?.content?.parts?.find((p) => "inlineData" in p);
+    if (imagePart && "inlineData" in imagePart && imagePart.inlineData?.data) {
       return Buffer.from(imagePart.inlineData.data, "base64");
     }
+    console.warn("[Gemini Image] No image data found in AI response.");
     return null;
   } catch (error) {
     console.error("[Gemini Image] Error:", error);
@@ -387,110 +267,77 @@ export async function generateImageWithGemini(prompt: string): Promise<Buffer |
   }
 }
 
-// --- Helper function to upload any buffer to Cloudinary ---
-export const uploadToCloudinary =  async (
-  buffer: Buffer,
-  publicId: string,
-  resourceType: "image" | "video"
-): Promise<string> => {
-  return new Promise((resolve, reject) => {
-    const stream = cloudinary.uploader.upload_stream(
-      {
-        public_id: publicId,
-        folder: "square-battles-heroes",
-        resource_type: resourceType,
-        overwrite: true,
-        format: resourceType === "video" ? "wav" : undefined,
-      },
-      (error, result) => {
-        if (result) resolve(result.secure_url);
-        else reject(error);
-      }
-    );
-    stream.end(buffer);
-  });
+export const uploadToCloudinary = async (buffer: Buffer, publicId: string, resourceType: "image" | "video"): Promise<string | null> => {
+  // DEFENSIVE: Check inputs
+  if (!buffer || buffer.length === 0 || !publicId) {
+    console.error("[Cloudinary] Invalid buffer or publicId provided for upload.");
+    return null;
+  }
+  try {
+    return new Promise((resolve, reject) => {
+      const stream = cloudinary.uploader.upload_stream(
+        {
+          public_id: publicId,
+          folder: "square-battles-heroes",
+          resource_type: resourceType,
+          overwrite: true,
+          format: resourceType === "video" ? "wav" : undefined,
+        },
+        (error, result) => {
+          if (error) return reject(error);
+          if (result) return resolve(result.secure_url);
+          // DEFENSIVE: Handle case where there's no error but no result
+          reject(new Error("Cloudinary upload returned no result and no error."));
+        }
+      );
+      stream.end(buffer);
+    });
+  } catch (error) {
+    console.error(`[Cloudinary] Failed to upload ${publicId}:`, error);
+    return null;
+  }
 };
 
-// Helper function to convert PCM data to WAV format
-const convertToWav = async (
-  pcmData: Buffer,
-  channels = 1,
-  sampleRate = 24000,
-  bitDepth = 16
-): Promise<Buffer> => {
+const convertToWav = (pcmData: Buffer): Promise<Buffer> => {
   return new Promise((resolve, reject) => {
+    // DEFENSIVE: Check input buffer
+    if (!pcmData || pcmData.length === 0) {
+      return reject(new Error("PCM data buffer is empty or invalid."));
+    }
     const chunks: Buffer[] = [];
-
-    // Create a readable stream from the PCM data
-    const readable = new Readable({
-      read() {
-        this.push(pcmData);
-        this.push(null); // End the stream
-      },
-    });
-
-    // Create WAV writer
-    const writer = new wav.Writer({
-      channels,
-      sampleRate,
-      bitDepth,
-    });
-
-    writer.on("data", (chunk) => {
-      chunks.push(chunk);
-    });
-
-    writer.on("end", () => {
-      const wavBuffer = Buffer.concat(chunks);
-      resolve(wavBuffer);
-    });
-
-    writer.on("error", reject);
-
-    // Pipe the PCM data through the WAV writer
+    const readable = new Readable({ read() { this.push(pcmData); this.push(null); } });
+    const writer = new wav.Writer({ channels: 1, sampleRate: 24000, bitDepth: 16 });
+    writer.on("data", (chunk) => chunks.push(chunk));
+    writer.on("end", () => resolve(Buffer.concat(chunks)));
+    writer.on("error", reject); // This will propagate errors to the Promise's catch block.
     readable.pipe(writer);
   });
 };
 
-// --- NEW: Function to generate and upload audio ---
-export const generateAudio = async (
-  textToSpeak: string,
-  heroName: string,
-  selectedVoice: string,
-  lineType: "intro" | "superpower"
-): Promise<string | null> => {
-  console.log(
-    `[Audio] Requesting for "${heroName}" (${lineType}): "${textToSpeak}"`
-  );
-
-  const apiKey = process.env.GEMINI_API_KEY;
-  if (!apiKey) return null;
-
+export const generateAudio = async (textToSpeak: string, heroName: string, selectedVoice: string, lineType: "intro" | "superpower"): Promise<string | null> => {
+  // DEFENSIVE: Check inputs
+  if (!textToSpeak || !heroName || !selectedVoice) {
+    console.error("[Audio Gen] Called with missing parameters.");
+    return null;
+  }
   try {
-    const ai = new GoogleGenAI({ apiKey });
-
+    const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY! });
     const response = await ai.models.generateContent({
       model: "gemini-2.5-flash-preview-tts",
       contents: [{ parts: [{ text: textToSpeak }] }],
       config: {
         responseModalities: ["AUDIO"],
-        speechConfig: {
-          voiceConfig: { prebuiltVoiceConfig: { voiceName: selectedVoice } },
-        },
+        speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: selectedVoice } } },
       },
     });
 
-    const data =
-      response.candidates?.[0]?.content?.parts?.[0]?.inlineData?.data;
+    const data = response.candidates?.[0]?.content?.parts?.[0]?.inlineData?.data;
     if (!data) throw new Error("No audio data from AI.");
-
+    
     const pcmBuffer = Buffer.from(data, "base64");
     const wavBuffer = await convertToWav(pcmBuffer);
-
-    // FIX: Make public_id unique for each line type to prevent overwriting
     const publicId = `${heroName.toLowerCase().replace(/ /g, "_")}_${lineType}`;
-
-    // Use 'video' resource type for audio files on Cloudinary
+    
     return await uploadToCloudinary(wavBuffer, publicId, "video");
   } catch (error) {
     console.error(`[Audio Generation Error for ${heroName}]:`, error);
@@ -498,44 +345,27 @@ export const generateAudio = async (
   }
 };
 
-/**
- * Updates one or more fields of a hero in the database by hero ID.
- * @param _id The ID of the hero to update.
- * @param update An object with any fields to update.
- * @returns The updated hero document, or null if not found.
- *
- * Example usage:
- *
- * await updateHero("665b1e2c7f8a2a0012a3c456", {
- *   heroName: "New Name",
- *   heroHealth: 120,
- *   tags: ["tank", "fire", "legendary"]
- * });
- *
- * // You can update as many or as few fields as you want.
- * // Only the fields you include in the `update` object will be changed.
- */
-export const updateHero = async (
-  _id: string,
-  update: Partial<HeroData>
-): Promise<HeroData | null> => {
+export const updateHero = async (_id: string, update: Partial<HeroData>): Promise<HeroData | null> => {
+  // DEFENSIVE: Check inputs
+  if (!_id || !update || Object.keys(update).length === 0) {
+    console.error("[updateHero] Invalid ID or empty update object provided.");
+    return null;
+  }
   try {
     await connectToDatabase();
-
-    // Prevent empty update
-    if (Object.keys(update).length === 0) {
-      throw new Error("You must provide at least one field to update.");
-    }
-
     const updatedHero = await Hero.findByIdAndUpdate(
       _id,
       { $set: update },
-      { new: true }
-    );
+      { new: true, runValidators: true } // runValidators ensures schema rules are checked
+    ).lean(); // Use .lean() for a plain JS object, slightly faster.
+    
+    if (!updatedHero) return null;
 
-    return updatedHero ? JSON.parse(JSON.stringify(updatedHero)) : null;
+    // The result from .lean() is a plain object, no need for JSON parsing tricks.
+    return updatedHero as unknown as HeroData;
   } catch (error) {
-    console.error("Error updating hero:", error);
+    console.error(`[updateHero] Error updating hero ${_id}:`, error);
     return null;
   }
 };
+

app/actions/db.actions.ts

@@ -1,5 +1,4 @@
 "use server"
-import BattleSetup from "@/model/battleSetup.model";
 import fs from 'fs/promises';
 import path from 'path';
 import { connectToDatabase } from "@/lib/database";
@@ -14,31 +13,36 @@ import {
   generateAudio,
   uploadToCloudinary, // Assuming you have these helpers
 } from "./ai.actions"; // Assuming your AI actions are here
+import BattleSetupModel from "@/model/battleSetup.model";
 
 export async function saveBattleSetup(setup: BattleSetupType): Promise<string | null> {
+  // DEFENSIVE: Validate the structure before saving.
+  if (!setup || !setup.type || !setup.config) {
+    console.error("[saveBattleSetup] Attempted to save invalid or null setup object.");
+    return null;
+  }
+  // DEFENSIVE: Specifically check the new heroIds structure.
+  if (setup.type === "HERO_BATTLE" && (!Array.isArray(setup.config.heroIds) || setup.config.heroIds.length < 2)) {
+      console.error("[saveBattleSetup] Hero battle setup must contain at least two hero IDs.");
+      return null;
+  }
+
   try {
     await connectToDatabase();
-
-    const newBattle = await BattleSetup.create({
-      setupData: JSON.stringify(setup)
-    });
-
-    // Return the unique MongoDB document ID as a string
-    return newBattle._id.toString();
-
+    const newBattle = await BattleSetupModel.create(setup);
+    return (newBattle._id as { toString: () => string }).toString();
   } catch (error) {
-    console.error("Failed to save battle setup to DB:", error);
+    console.error("⛔️ Failed to save battle setup to DB:", error);
     return null;
   }
 }
 
-
 export async function getBattleSetup(id: string): Promise<BattleSetupType | null> {
   try {
     await connectToDatabase();
-    const battle = await BattleSetup.findById(id);
+    const battle = await BattleSetupModel.findById(id);
     if (!battle) return null;
-    return JSON.parse(battle.setupData) as BattleSetupType;
+    return JSON.parse(JSON.stringify(battle)) as BattleSetupType;
   } catch (error) {
     console.error("Failed to fetch battle setup:", error);
     return null;
@@ -46,6 +50,42 @@ export async function getBattleSetup(id: string): Promise<BattleSetupType | null
 }
 
 
+// --- NEW ACTION: getHeroesByIds ---
+// This action efficiently fetches multiple hero documents in a single database call.
+export async function getHeroesByIds(ids: string[]): Promise<HeroData[]> {
+    // DEFENSIVE: Check for valid, non-empty array of IDs.
+    if (!Array.isArray(ids) || ids.length === 0) {
+        return [];
+    }
+
+    try {
+        await connectToDatabase();
+        // Use the $in operator to find all documents where _id is in the provided array.
+        // .lean() is critical for performance here.
+        const heroes = await Hero.find({ '_id': { $in: ids } }).lean();
+        
+        // IMPORTANT: The database does not guarantee the order of the returned documents.
+        // We must re-order them to match the original `ids` array to ensure consistent
+        // player placement in the arena (e.g., Player 1 vs Player 2).
+        const heroMap = new Map(heroes.map(h => [h._id && h._id.toString(), h]));
+        const orderedHeroes = ids
+            .map(id => heroMap.get(id))
+            .filter(Boolean)
+            .map(h => JSON.parse(JSON.stringify(h)) as HeroData);
+
+        // DEFENSIVE: Log if some heroes were not found (e.g., deleted after setup creation)
+        if (orderedHeroes.length !== ids.length) {
+            console.warn(`[getHeroesByIds] Mismatch: Requested ${ids.length} heroes, but only found ${orderedHeroes.length}. Some may have been deleted.`);
+        }
+        
+        return orderedHeroes;
+
+    } catch (error) {
+        console.error("⛔️ Failed to fetch heroes by IDs:", error);
+        return []; // Return an empty array on any failure.
+    }
+}
+
 export async function getAllHeroes(): Promise<HeroData[]> {
     try {
         await connectToDatabase();
@@ -183,4 +223,51 @@ export async function saveBattleRecording(
     const message = error instanceof Error ? error.message : "Unknown error saving recording.";
     return { success: false, message };
   }
+}
+
+
+
+export async function reportHeroRuntimeError(
+  heroId: string,
+  errorMessage: string,
+  faultyCode: string
+): Promise<{ success: boolean }> {
+  // DEFENSIVE: Validate inputs
+  if (!heroId || !errorMessage || !faultyCode) {
+    console.error("[reportHeroRuntimeError] Missing required arguments.");
+    return { success: false };
+  }
+
+  try {
+    await connectToDatabase();
+    
+    // Find the hero and update it with the error details.
+    // We use $inc to atomically increment the errorCount.
+    const result = await Hero.updateOne(
+      { _id: heroId },
+      {
+        $inc: { errorCount: 1 },
+        $set: {
+          lastError: {
+            message: errorMessage,
+            faultyCode: faultyCode,
+            reportedAt: new Date(),
+          },
+        },
+      }
+    );
+
+    // DEFENSIVE: Check if the update operation actually found and modified a document.
+    if (result.modifiedCount === 0) {
+        console.warn(`[reportHeroRuntimeError] Hero with ID ${heroId} not found or no changes made.`);
+        return { success: false };
+    }
+
+    console.log(`[reportHeroRuntimeError] Successfully logged error for hero ${heroId}.`);
+    return { success: true };
+
+  } catch (error) {
+    console.error(`⛔️ Failed to report runtime error for hero ${heroId}:`, error);
+    return { success: false };
+  }
 }

app/battle/[battleId]/page.tsx

@@ -1,7 +1,8 @@
-import { getBattleSetup } from "@/app/actions/db.actions";
+import { getBattleSetup, getHeroesByIds } from "@/app/actions/db.actions";
 import { auth } from "@/auth";
 import BattleArena from "@/components/BattleArena"; // The component itself
-import { redirect } from "next/navigation";
+import { HeroData } from "@/types";
+import { notFound, redirect } from "next/navigation";
 
 // The page becomes a server component that fetches data and passes it down
 
@@ -23,13 +24,34 @@ const BattlePage = async ({ params, searchParams  }: { params: Params, searchPar
     }
   }
   
+ 
+  // DEFENSIVE: If no setup is found for the ID, render a 404 page.
   if (!battleSetup) {
-      return <div>Battle not found or has expired.</div>;
-    }
+    notFound();
+  }
     // console.log(battleSetup.config.heros);
+  let initialHeroes: HeroData[] = [];
+  // 2. If it's a hero battle, fetch the full hero data using the new action.
+  if (battleSetup.type === 'HERO_BATTLE') {
+    initialHeroes = await getHeroesByIds(battleSetup.config.heroIds);
+
+    // DEFENSIVE: Handle the critical case where the heroes for the battle couldn't be found.
+    // This could happen if they were deleted between setup creation and the battle start.
+    if (initialHeroes.length !== battleSetup.config.heroIds.length) {
+        return (
+            <div className="flex h-screen w-full items-center justify-center bg-gray-900 text-white">
+                <div className="text-center">
+                    <h1 className="text-2xl font-bold text-red-500">Battle Data Error</h1>
+                    <p className="text-gray-400 mt-2">Could not load all required heroes for this battle. They may have been deleted.</p>
+                </div>
+            </div>
+        );
+    }
+  }
 
-  // Pass the fetched object as a prop to your client component
-  return <BattleArena battleSetup={battleSetup} />;
-};
+  // 3. Pass all the prepared data as props to the client component.
+  // The client component no longer fetches its own data.
+  return <BattleArena battleSetup={battleSetup} initialHeroes={initialHeroes} />
+}
 
 export default BattlePage;

components/BattleArena.tsx

@@ -70,9 +70,15 @@ import { Badge } from "./ui/badge";
 import { Square } from "@/lib/game/Square";
 import { Camera } from "@/lib/game/Camera";
 import { drawBroadcastUI } from "@/lib/BroadcastUI";
+import { reportHeroRuntimeError } from "@/app/actions/db.actions";
 
 // BATTLE ARENA COMPONENT
-const BattleArena = ({ battleSetup }: { battleSetup: BattleSetup }) => {
+const BattleArena = ({  battleSetup,
+  initialHeroes, // Receive the pre-fetched hero data
+}: {
+  battleSetup: BattleSetup;
+  initialHeroes: HeroData[];
+}) => {
   const canvasRef = useRef<HTMLCanvasElement>(null);
   const searchParams = useSearchParams();
   const router = useRouter();
@@ -101,7 +107,7 @@ const BattleArena = ({ battleSetup }: { battleSetup: BattleSetup }) => {
     const sources: AssetSource[] = [];
 
     if (fullSetup.type === "HERO_BATTLE") {
-      fullSetup.config.heroes.forEach((hero, i) => {
+      initialHeroes.forEach((hero, i) => {
         if (hero.avatarUrl)
           sources.push({
             id: `hero_${i}_avatar`,
@@ -129,7 +135,7 @@ const BattleArena = ({ battleSetup }: { battleSetup: BattleSetup }) => {
     });
 
     return sources;
-  }, [battleSetup]);
+  }, [battleSetup,initialHeroes]);
 
   const { loadedImages, isLoading } = useAssetLoader(assetSources); // Assuming this is defined correctly
 
@@ -419,7 +425,7 @@ const BattleArena = ({ battleSetup }: { battleSetup: BattleSetup }) => {
       ];
 
       if (battleSetup.type === "HERO_BATTLE") {
-        battleSetup.config.heroes.forEach((heroData) => {
+       initialHeroes.forEach((heroData) => {
           if (heroData.introLineAudioUrl) {
             audioLoadPromises.push(
               audioManager.loadSound(
@@ -835,467 +841,497 @@ const BattleArena = ({ battleSetup }: { battleSetup: BattleSetup }) => {
     };
 
     // --- OMNIPOTENT SANDBOX API IMPLEMENTATION ---
-    const sandboxExecutor = (
-      logic: string, // This 'logic' is the AST string from the DB
-      caster: Hero,
-      additionalContext: object = {}
-    ) => {
-      // We create the full API object once.
-      const sandboxAPI = createSandboxAPI(gameState, caster);
-      const fullContext = { ...sandboxAPI, ...additionalContext };
-
-      try {
-        // --- NEW SIMPLIFIED PIPELINE ---
-
-        // The 'logic' from the DB is an arrow function string like:
-        // `async ({ getSelf, dealDamage }) => { ... }`
-
-        // We can use the Function constructor to safely evaluate this string
-        // into a real function within the current scope.
-        // It's safer than a direct `eval()` because it doesn't leak local variables
-        // unless you explicitly pass them.
-        const abilityFn = new Function("return " + logic)();
-
-        // Now, call the function with the sandbox API as its argument.
-        abilityFn(fullContext);
-      } catch (e) {
-        console.error("Sandbox Execution Error:", e, "Logic Code:", logic);
-      }
-    };
-
-    // in BattleArena.tsx
+   // --- REFACTORED & BULLETPROOF SANDBOX EXECUTOR ---
+  const sandboxExecutor = (
+    logic: string,
+    caster: Hero,
+    additionalContext: object = {}
+  ) => {
+    // DEFENSIVE: Do not execute if caster or logic is invalid.
+    if (!caster || !logic || typeof logic !== "string") {
+      console.error("[Sandbox] Executor called with invalid caster or logic.");
+      return;
+    }
+    
+    // Create the full API object for the AI code to use.
+    const sandboxAPI = createSandboxAPI(gameState, caster);
+    const fullContext = { ...sandboxAPI, ...additionalContext };
 
-    const createSandboxAPI = (
-      gameCtx: typeof gameState,
-      currentHero: Hero | null
-    ): GameAPI => {
-      const self = currentHero;
+    try {
+      // Safely construct the function from the AI's code string.
+      const abilityFn = new Function("return " + logic)();
+
+      // Attempt to execute the AI's superpower function.
+      // This is the most dangerous line of code in the component.
+      abilityFn(fullContext);
+
+    } catch (e: unknown) {
+      // --- CRASH PREVENTION & ERROR REPORTING ---
+      const error = e instanceof Error ? e : new Error(String(e));
+      
+      // 1. Log the error to the browser console for immediate debugging.
+      console.error("⛔️ SANDBOX EXECUTION CRASH CAUGHT ⛔️");
+      console.error(`Hero: ${caster.name} (ID: ${caster.id})`);
+      console.error(`Error: ${error.message}`);
+      console.error("Faulty Code:", logic);
+      
+      // 2. Display a non-intrusive toast notification to the user.
+      toast.error(`"${caster.name}" superpower failed!`, {
+        description: "A runtime error occurred in the hero's logic.",
+      });
 
-      const getOpponents = () => {
-        if (!self) return [];
-        return gameCtx.fighters.filter(
-          (f) => f.health > 0 && f.id !== self.id
-        ) as Hero[];
-      };
-      const getAllies = () => {
-        if (!self) return [];
-        // An ally is any fighter (excluding self) whose teamId IS the same as our own.
-        return gameCtx.fighters.filter(
-          (f) =>
-            f instanceof Hero && f.id !== self.id && f.teamId === self.teamId
-        ) as Hero[];
+      // 3. Trigger a visual "fizzle" effect in-game to provide feedback.
+      // This makes the failure feel like part of the game, not a bug.
+      const fizzleEffect = () => {
+          const centerX = caster.x + caster.width / 2;
+          const centerY = caster.y + caster.height / 2;
+          // Use the sandbox API to create the effect.
+          sandboxAPI.playSound('powerup_fail'); // A sad trombone or dud sound.
+          // Smoke puff particle effect
+          for (let i = 0; i < 20; i++) {
+              sandboxAPI.spawnParticle(
+                  caster.id,
+                  centerX, centerY,
+                  30 + Math.random() * 20,
+                  (p) => { // updateFn
+                      p.x += (Math.random() - 0.5) * 2;
+                      p.y += (Math.random() - 0.5) * 2 - 0.5; // slow rise
+                  },
+                  (p, ctx) => { // drawFn
+                      ctx.fillStyle = `rgba(100, 100, 100, ${p.progress * 0.5})`;
+                      ctx.beginPath();
+                      ctx.arc(p.x, p.y, p.progress * 20, 0, Math.PI * 2);
+                      ctx.fill();
+                  },
+                  2 // Draw layer
+              );
+          }
       };
+      fizzleEffect();
+
+      // 4. Asynchronously report the error to the database.
+      // We do not `await` this. It's a fire-and-forget operation.
+      // The battle should not pause while we report an error.
+      reportHeroRuntimeError(caster.superpower._id!, error.message, logic)
+        .catch(reportError => {
+          // DEFENSIVE: Catch potential errors in the reporting process itself.
+          console.error("CRITICAL: Failed to report hero error to the server.", reportError);
+        });
+    }
+  };
 
-      const getDistance = (
-        p1: { x: number; y: number },
-        p2: { x: number; y: number }
-      ) => {
-        return Math.sqrt(Math.pow(p2.x - p1.x, 2) + Math.pow(p2.y - p1.y, 2));
-      };
+    // in BattleArena.tsx
 
-      const getHeroById = (id: number): Hero | null => {
-        return (gameCtx.fighters.find((f) => f.id === id) as Hero) || null;
-      };
+const createSandboxAPI = (
+  gameCtx: typeof gameState,
+  currentHero: Hero | null
+): GameAPI => {
+  const self = currentHero;
+
+  // --- SHIELD WRAPPER ---
+  // This is the core of our defense. It's a higher-order function
+  // that takes an AI-provided callback and returns a new, "shielded" version.
+  const shieldCallback = <T extends (...args: never[]) => unknown>(
+    aiCallback: T | undefined,
+    callbackName: string // For logging purposes
+  ): T | undefined => {
+    // If the AI didn't provide a callback, do nothing.
+    if (!aiCallback || typeof aiCallback !== 'function') {
+      return undefined;
+    }
 
-      return {
-        // --- Core Reference & Targeting ---
-        getSelf: () => self,
-        getOpponents,
-        getAllies,
-        getHeroById,
-        findNearestOpponent: () => {
-          if (!self) return null;
-          const opponents = getOpponents();
-          if (opponents.length === 0) return null;
-          return opponents.sort(
-            (a, b) => getDistance(self, a) - getDistance(self, b)
-          )[0];
-        },
-        getMapBoundaries: () => {
-        // Access gameBounds from the passed gameCtx
-        return {
-          top: gameCtx.gameBounds.y,
-          bottom: gameCtx.gameBounds.y + gameCtx.gameBounds.height,
-          left: gameCtx.gameBounds.x,
-          right: gameCtx.gameBounds.x + gameCtx.gameBounds.width,
-        };
-      },
-        findFarthestOpponent: () => {
-          if (!self) return null;
-          const opponents = getOpponents();
-          if (opponents.length === 0) return null;
-          return opponents.sort(
-            (a, b) => getDistance(self, b) - getDistance(self, a)
-          )[0];
-        },
-        findLowestHealthOpponent: () => {
-          if (!self) return null;
-          return getOpponents().sort((a, b) => a.health - b.health)[0] || null;
-        },
+    // Return a new function that wraps the original AI code in a try-catch.
+    return ((...args: Parameters<T>): ReturnType<T> | void => {
+      try {
+        // Attempt to execute the original AI-provided code.
+        return aiCallback(...args) as void | ReturnType<T>;
+      } catch (e: unknown) {
+        // If a crash happens inside the callback, we catch it here.
+        const error = e instanceof Error ? e : new Error(String(e));
+        
+        // Prevent log spam: only report the error once per hero's superpower activation.
+        if (self && !self.getData('hasReportedError')) {
+          console.error(`⛔️ RUNTIME CRASH IN SANDBOX CALLBACK: ${callbackName} ⛔️`);
+          console.error(`Hero: ${self.name} (ID: ${self.id})`);
+          console.error(`Error: ${error.message}`);
+          console.error("Originating Power Logic:", self.superpower.powerLogic);
+
+          toast.error(`"${self.name}" superpower failed mid-effect!`, {
+            description: `Error in ${callbackName}: ${error.message.substring(0, 50)}...`,
+          });
 
-        // --- Core Actions ---
-        dealDamage: (
-          target,
-          amount,
-          sourceType: "basic" | "superpower" | "other" = "superpower"
-        ) => {
-          // Defaulting to 'superpower' is a smart choice because the sandbox API
-          // is primarily used by superpower logic. This avoids breaking existing abilities.
-          console.log(target);
-
-          target.takeDamage(amount, sourceType);
-        },
+          // Report the error to the database for the asynchronous repair pipeline.
+          // Note the use of `self.superpower._id!` which is the permanent database ID.
+          reportHeroRuntimeError(self.superpower._id!, error.message, self.superpower.powerLogic)
+            .catch(reportError => console.error("CRITICAL: Failed to report hero error to server.", reportError));
 
-        heal: (target, amount) => target.heal(amount),
-        applyForce: (target, angle, magnitude) => {
-          target.dx += Math.cos(angle) * magnitude * 0.1;
-          target.dy += Math.sin(angle) * magnitude * 0.1;
-        },
-        modifyHero: (target, modifications, duration) => {
-          if (modifications.stunDuration)
-            target.stunTimer = Math.max(
-              target.stunTimer,
-              modifications.stunDuration
-            );
-          if (modifications.isGhost)
-            target.ghostTimer = Math.max(target.ghostTimer, duration);
-          if (modifications.speedFactor)
-            target.speedBoostTimer = Math.max(target.speedBoostTimer, duration);
-        },
-        teleport: (target, x, y) => {
-          target.x = x;
-          target.y = y;
-        },
+          // Set a flag on the hero's runtime instance to prevent this error report from firing again.
+          self.setData('hasReportedError', true);
+        }
+        // We return `void` to stop execution flow after a crash.
+      }
+    }) as T;
+  };
 
-        spawnClone: (caster: Hero, duration: number): number | null => {
-          if (!caster) return null;
-
-          const newId = gameCtx.nextObjectId++;
-
-          // Create a new Hero instance using the caster's own data
-          const clone = new Hero(
-            caster.superpower, // This holds the original HeroData
-            newId,
-            caster.x, // Spawn at the caster's position
-            caster.y,
-            //@ts-expect-error: Hero constructor expects a sandboxExecutor, but type system does not recognize this property on fighters array elements.
-            gameCtx.fighters.find((f) => f.id === caster.id)!.sandboxExecutor, // Use the same executor
-            {
-              isSummon: true,
-              ownerId: caster.id,
-              lifetime: duration, // Duration in frames
-              teamId: caster.teamId, // <<< NEW: The clone inherits the caster's teamId
-            }
-          );
+  // --- Helper Functions (for clarity and re-use) ---
+  const getOpponents = () => {
+    if (!self) return [];
+    return gameCtx.fighters.filter(f => f.health > 0 && f.id !== self.id && f instanceof Hero) as Hero[];
+  };
 
-          // Copy over the visual assets
-          clone.avatarImage = caster.avatarImage;
-          clone.iconImage = caster.iconImage;
+  const getAllies = () => {
+    if (!self) return [];
+    return gameCtx.fighters.filter(f => f instanceof Hero && f.id !== self.id && f.teamId === self.teamId) as Hero[];
+  };
 
-          // Add the new clone to the main fighters array!
-          gameCtx.fighters.push(clone);
+  const getHeroById = (id: number): Hero | null => {
+    return (gameCtx.fighters.find((f) => f.id === id) as Hero) || null;
+  };
+  
+  const getDistance = (p1: { x: number; y: number }, p2: { x: number; y: number }) => {
+      return Math.hypot(p2.x - p1.x, p2.y - p1.y);
+  };
 
-          return newId; // Return the ID so the ability can track it
-        },
-        spawnBasicProjectile: (from, to, damage, knockback) => {
-          if (!self || !currentHero) return;
-          const startX = from.x + from.width / 2;
-          const startY = from.y + from.height / 2;
-          const endX = to.x + to.width / 2;
-          const endY = to.y + to.height / 2;
-          const angle = Math.atan2(endY - startY, endX - startX);
-
-          const projectile = new Projectile({
-            id: gameCtx.nextObjectId++,
-            owner: self,
-            startX,
-            startY,
-            velocityX: Math.cos(angle) * 15, // Standard speed
-            velocityY: Math.sin(angle) * 15,
-            size: 15,
-            lifetime: 120, // 2 seconds
-            // Default onHit for basic attacks
-            onHit: (context) => {
-              const { target, applyForce, dealDamage } = context;
-              dealDamage(target, damage, "basic");
-              if (knockback) {
-                const angle = context.getAngle(context.projectile, target);
-                applyForce(target, angle, knockback);
-              }
-            },
-            // Default drawLogic using hero's color
-            drawLogic: (p, ctx) => {
-              ctx.fillStyle = p.owner.color;
-              ctx.shadowColor = p.owner.color;
-              ctx.shadowBlur = 15;
-              ctx.beginPath();
-              ctx.arc(
-                p.x + p.size / 2,
-                p.y + p.size / 2,
-                p.size / 2,
-                0,
-                Math.PI * 2
-              );
-              ctx.fill();
-            },
-          });
-          gameCtx.projectiles.push(projectile);
-        },
-        // --- Object Spawning ---
-        spawnProjectile: (options: ProjectileAIOptions) => {
-          if (!self) return;
-          const startX = options.from.x + options.from.width / 2;
-          const startY = options.from.y + options.from.height / 2;
-          const endX = options.to.x + options.to.width / 2;
-          const endY = options.to.y + options.to.height / 2;
-
-          getDistance({ x: startX, y: startY }, { x: endX, y: endY });
-          const angle = Math.atan2(endY - startY, endX - startX);
-          // Normalize the AI's "speed" value into something reasonable.
-          // Let's assume a "speed" of 20 is standard.
-          // A higher AI speed means a faster projectile.
-          const normalizedSpeed = options.speed / 100; // AI's 2200 becomes 22. This is a reasonable velocity.
-
-          const constructorOptions: ProjectileConstructorOptions = {
-            id: gameCtx.nextObjectId++,
-            owner: self,
-            startX,
-            startY,
-            velocityX: Math.cos(angle) * normalizedSpeed,
-            velocityY: Math.sin(angle) * normalizedSpeed,
-            size: options.size,
-            lifetime: options.lifetime,
-            onHit: options.onHit,
-            drawLogic: options.drawLogic,
-          };
-          gameCtx.projectiles.push(new Projectile(constructorOptions));
-        },
-        spawnZone: (options: ZoneAIOptions) => {
-          if (!self) return;
-          const parentObject = options.parent;
-          const isAttachedToHero =
-            "id" in parentObject && typeof parentObject.id === "number";
-
-          const constructorOptions: ZoneConstructorOptions = {
-            id: gameCtx.nextObjectId++,
-            owner: self,
-            parent: parentObject,
-            shape: "circle",
-            x:
-              parentObject.x +
-              (isAttachedToHero ? (parentObject as Hero).width / 2 : 0),
-            y:
-              parentObject.y +
-              (isAttachedToHero ? (parentObject as Hero).height / 2 : 0),
-            radius: options.radius,
-            width: options.radius * 2,
-            height: options.radius * 2,
-            lifetime: options.duration,
-            maxDuration: options.duration, // Added property
-            progress: 0, // Added property, initialize as needed
-            onStay: options.onStay,
-            drawLogic: options.drawLogic,
+  // --- THE FULL, SHIELDED GAME API ---
+  return {
+    // --- Core Reference & Targeting (No Callbacks - Intrinsically Safe) ---
+    getSelf: () => self,
+    getOpponents,
+    getAllies,
+    getHeroById,
+    findNearestOpponent: () => {
+      if (!self) return null;
+      const opponents = getOpponents();
+      if (opponents.length === 0) return null;
+      return opponents.sort((a, b) => getDistance(self, a) - getDistance(self, b))[0];
+    },
+    findFarthestOpponent: () => {
+      if (!self) return null;
+      const opponents = getOpponents();
+      if (opponents.length === 0) return null;
+      return opponents.sort((a, b) => getDistance(self, b) - getDistance(self, a))[0];
+    },
+    findLowestHealthOpponent: () => {
+      if (!self) return null;
+      const opponents = getOpponents();
+      return opponents.sort((a, b) => a.health - b.health)[0] || null;
+    },
+    getMapBoundaries: () => ({
+      top: gameCtx.gameBounds.y,
+      bottom: gameCtx.gameBounds.y + gameCtx.gameBounds.height,
+      left: gameCtx.gameBounds.x,
+      right: gameCtx.gameBounds.x + gameCtx.gameBounds.width,
+    }),
+
+    // --- Core Actions (No Callbacks - Intrinsically Safe) ---
+    dealDamage: (target, amount, sourceType: "basic" | "superpower" | "other" = "superpower") => {
+      if(target) target.takeDamage(amount, sourceType);
+    },
+    heal: (target, amount) => {
+      if(target) target.heal(amount);
+    },
+    applyForce: (target, angle, magnitude) => {
+      if(target) {
+        target.dx += Math.cos(angle) * magnitude * 0.1;
+        target.dy += Math.sin(angle) * magnitude * 0.1;
+      }
+    },
+    modifyHero: (target, modifications, duration) => {
+      if(!target) return;
+      if (modifications.stunDuration) target.stunTimer = Math.max(target.stunTimer, modifications.stunDuration);
+      if (modifications.isGhost) target.ghostTimer = Math.max(target.ghostTimer, duration);
+      if (modifications.speedFactor) target.speedBoostTimer = Math.max(target.speedBoostTimer, duration);
+    },
+    teleport: (target, x, y) => {
+      if(target) {
+        target.x = x;
+        target.y = y;
+      }
+    },
+    
+    // --- Object Spawning (Callbacks MUST be shielded) ---
+    spawnProjectile: (options: ProjectileAIOptions) => {
+      if (!self || !options) return;
+      const startX = options.from.x + options.from.width / 2;
+      const startY = options.from.y + options.from.height / 2;
+      const endX = options.to.x + options.to.width / 2;
+      const endY = options.to.y + options.to.height / 2;
+      const angle = Math.atan2(endY - startY, endX - startX);
+      const normalizedSpeed = (options.speed || 1500) / 100;
+
+      const constructorOptions: ProjectileConstructorOptions = {
+        id: gameCtx.nextObjectId++, owner: self, startX, startY,
+        velocityX: Math.cos(angle) * normalizedSpeed,
+        velocityY: Math.sin(angle) * normalizedSpeed,
+        size: options.size, lifetime: options.lifetime,
+        onHit: shieldCallback(options.onHit, 'projectile.onHit')!,
+        drawLogic: shieldCallback(options.drawLogic, 'projectile.drawLogic'),
+      };
+      gameCtx.projectiles.push(new Projectile(constructorOptions));
+    },
+    spawnClone: (caster: Hero, duration: number): number | null => {
+        if (!caster) return null;
+        const newId = gameCtx.nextObjectId++;
+        const clone = new Hero(caster.superpower, newId, caster.x, caster.y, (logic, hero) => sandboxExecutor(logic, hero), {
+            isSummon: true, ownerId: caster.id, lifetime: duration, teamId: caster.teamId,
+        });
+        clone.avatarImage = caster.avatarImage;
+        clone.iconImage = caster.iconImage;
+        gameCtx.fighters.push(clone);
+        return newId;
+    },
+    spawnZone: (options: ZoneAIOptions) => {
+        if (!self || !options) return;
+        const parentObject = options.parent;
+        const isAttachedToHero = "id" in parentObject && typeof parentObject.id === "number";
+        
+        const constructorOptions: ZoneConstructorOptions = {
+            id: gameCtx.nextObjectId++, owner: self, parent: parentObject, shape: 'circle',
+            x: parentObject.x + (isAttachedToHero ? (parentObject as Hero).width / 2 : 0),
+            y: parentObject.y + (isAttachedToHero ? (parentObject as Hero).height / 2 : 0),
+            radius: options.radius, width: options.radius * 2, height: options.radius * 2,
+            lifetime: options.duration, maxDuration: options.duration, progress: 1.0,
+            onStay: shieldCallback(options.onStay, 'zone.onStay'),
+            drawLogic: shieldCallback(options.drawLogic, 'zone.drawLogic'),
             attachTo: isAttachedToHero ? (parentObject as Hero) : undefined,
-          };
-          gameCtx.zones.push(new Zone(constructorOptions));
-        },
-
-        // --- Visuals & Effects ---
-        spawnParticle: (
-          casterId,
-          startX,
-          startY,
-          lifetime,
-          updateFn,
-          drawFn,
-          drawLayer,
-          initialState
-        ) => {
-          gameCtx.effectManager.spawnParticle(
-            casterId,
-            startX,
-            startY,
-            lifetime,
-            updateFn,
-            drawFn,
-            drawLayer,
-            initialState
-          );
-        },
-        drawPath: (from, to, duration, drawFn, drawLayer) => {
-          gameCtx.effectManager.drawPath(from, to, duration, drawFn, drawLayer);
-        },
-        drawText: (text, x, y, options = {}) => {
-          const lifetime = options.duration || 60;
-          gameCtx.effectManager.spawnParticle(
-            self ? self.id : null,
-            x,
-            y,
-            lifetime,
-            (p) => {
-              p.y -= 0.5;
-            },
-            (p, ctx) => {
-              ctx.font = options.font || "bold 24px sans-serif";
-              ctx.fillStyle = options.color || "white";
-              ctx.textAlign = options.align || "center";
-              ctx.globalAlpha = p.progress;
-              if (options.shadowColor) {
-                ctx.shadowColor = options.shadowColor;
-                ctx.shadowBlur = options.shadowBlur || 5;
-              }
-              ctx.fillText(text, p.x, p.y);
-            },
-            options.drawLayer || 4
-          );
+        };
+        gameCtx.zones.push(new Zone(constructorOptions));
+    },
+    spawnBasicProjectile: (from, to, damage, knockback) => {
+      // This function's onHit logic is hardcoded by us, not the AI, so it doesn't need a shield.
+      if (!self || !from || !to) return;
+      const startX = from.x + from.width / 2;
+      const startY = from.y + from.height / 2;
+      const endX = to.x + to.width / 2;
+      const endY = to.y + to.height / 2;
+      const angle = Math.atan2(endY - startY, endX - startX);
+
+      const projectile = new Projectile({
+        id: gameCtx.nextObjectId++,
+        owner: self,
+        startX,
+        startY,
+        velocityX: Math.cos(angle) * 15, // Standard speed
+        velocityY: Math.sin(angle) * 15,
+        size: 15,
+        lifetime: 120, // 2 seconds
+        // Default onHit for basic attacks
+        onHit: (context) => {
+          const { target, applyForce, dealDamage } = context;
+          dealDamage(target, damage, "basic");
+          if (knockback) {
+            const angle = context.getAngle(context.projectile, target);
+            applyForce(target, angle, knockback);
+          }
         },
-        drawShape: (shape, x, y, options = {}) => {
-          const lifetime = options.duration || 60;
-          gameCtx.effectManager.spawnParticle(
-            self ? self.id : null,
-            x,
-            y,
-            lifetime,
-            () => {},
-            (p, ctx) => {
-              ctx.fillStyle = options.color || "white";
-              ctx.globalAlpha = (options.alpha ?? 1) * p.progress;
-              if (options.shadowColor) {
-                ctx.shadowColor = options.shadowColor;
-                ctx.shadowBlur = options.shadowBlur || 10;
-              }
-              if (shape === "circle") {
-                ctx.beginPath();
-                ctx.arc(p.x, p.y, options.radius || 50, 0, 2 * Math.PI);
-                ctx.fill();
-              } else {
-                const width = options.width || 100;
-                const height = options.height || 100;
-                ctx.fillRect(p.x - width / 2, p.y - height / 2, width, height);
-              }
-            },
-            options.drawLayer || 1
+        // Default drawLogic using hero's color
+        drawLogic: (p, ctx) => {
+          ctx.fillStyle = p.owner.color;
+          ctx.shadowColor = p.owner.color;
+          ctx.shadowBlur = 15;
+          ctx.beginPath();
+          ctx.arc(
+            p.x + p.size / 2,
+            p.y + p.size / 2,
+            p.size / 2,
+            0,
+            Math.PI * 2
           );
+          ctx.fill();
         },
-
-        // --- Cinematics & Time ---
-        setGameSpeed: (factor, duration) => {
-          gameCtx.gameSpeedModifier = { factor, duration };
-        },
-        scheduleAction: (delayFrames, callback) => {
-          if (!self) return;
-          gameCtx.scheduledActions.push({
-            delayFrames,
-            action: callback,
-            context: {},
-            casterId: self.id,
-          });
-        },
-        panCameraTo: (x, y) => gameCtx.camera.panTo(x, y),
-        zoomCamera: (level) => gameCtx.camera.setZoom(level),
-        focusCameraOn: (target) => gameCtx.camera.focusOn(target),
-        resetCamera: () => gameCtx.camera.reset(),
-        shakeCamera: (magnitude, duration) =>
-          gameCtx.cameraShake.shake(magnitude, duration),
-
-        // --- Utilities & Hero State ---
-        playSound: (soundName) => audioManager.playSound(soundName),
-        getCanvasDimensions: () => ({
-          width: canvas.width,
-          height: canvas.height,
-        }),
-        getRandomNumber: (min, max) => Math.random() * (max - min) + min,
-        getAngle: (p1, p2) => Math.atan2(p2.y - p1.y, p2.x - p1.x),
-        getDistance,
-        raycast: (startX, startY, angle, length, width): Hero[] => {
-          if (!self) return [];
-          const hits: Hero[] = [];
-          const stepX = Math.cos(angle) * 10;
-          const stepY = Math.sin(angle) * 10;
-          for (let i = 0; i < length / 10; i++) {
-            const checkX = startX + i * stepX;
-            const checkY = startY + i * stepY;
-            for (const fighter of gameCtx.fighters) {
-              if (
-                fighter.id === self.id ||
-                !(fighter instanceof Hero) ||
-                hits.includes(fighter)
+      });
+      gameCtx.projectiles.push(projectile);
+    },
+
+    // --- Visuals & Effects (Callbacks MUST be shielded where applicable) ---
+    spawnParticle: (casterId, startX, startY, lifetime, updateFn, drawFn, drawLayer, initialState) => {
+      gameCtx.effectManager.spawnParticle(
+        casterId, startX, startY, lifetime,
+        shieldCallback(updateFn, 'particle.updateFn')!,
+        shieldCallback(drawFn, 'particle.drawFn')!,
+        drawLayer, initialState
+      );
+    },
+    drawPath: (from, to, duration, drawFn, drawLayer) => {
+      if (drawFn) {
+        gameCtx.effectManager.drawPath(from, to, duration, shieldCallback(drawFn, 'path.drawFn')!, drawLayer);
+      }
+    },
+    drawText: (text, x, y, options = {}) => {
+        // This function's callbacks are hardcoded by us, so it is intrinsically safe.
+        const lifetime = options.duration || 60;
+        gameCtx.effectManager.spawnParticle(
+          self ? self.id : null,
+          x,
+          y,
+          lifetime,
+          (p) => {
+            p.y -= 0.5;
+          },
+          (p, ctx) => {
+            ctx.font = options.font || "bold 24px sans-serif";
+            ctx.fillStyle = options.color || "white";
+            ctx.textAlign = options.align || "center";
+            ctx.globalAlpha = p.progress;
+            if (options.shadowColor) {
+              ctx.shadowColor = options.shadowColor;
+              ctx.shadowBlur = options.shadowBlur || 5;
+            }
+            ctx.fillText(text, p.x, p.y);
+          },
+          options.drawLayer || 4
+        );
+    },
+    drawShape: (shape, x, y, options = {}) => {
+        // This function's callbacks are hardcoded by us, so it is intrinsically safe.
+        const lifetime = options.duration || 60;
+        gameCtx.effectManager.spawnParticle(
+          self ? self.id : null,
+          x,
+          y,
+          lifetime,
+          () => {},
+          (p, ctx) => {
+            ctx.fillStyle = options.color || "white";
+            ctx.globalAlpha = (options.alpha ?? 1) * p.progress;
+            if (options.shadowColor) {
+              ctx.shadowColor = options.shadowColor;
+              ctx.shadowBlur = options.shadowBlur || 10;
+            }
+            if (shape === "circle") {
+              ctx.beginPath();
+              ctx.arc(p.x, p.y, options.radius || 50, 0, 2 * Math.PI);
+              ctx.fill();
+            } else {
+              const width = options.width || 100;
+              const height = options.height || 100;
+              ctx.fillRect(p.x - width / 2, p.y - height / 2, width, height);
+            }
+          },
+          options.drawLayer || 1
+        );
+    },
+
+    // --- Cinematics & Time ---
+    setGameSpeed: (factor, duration) => {
+      gameCtx.gameSpeedModifier = { factor, duration };
+    },
+    scheduleAction: (delayFrames, callback) => {
+      if (!self || !callback) return;
+      // This is a critical one to shield.
+      const shieldedAction = shieldCallback(callback, 'scheduleAction');
+      if (shieldedAction) {
+        gameCtx.scheduledActions.push({
+          delayFrames, action: shieldedAction, casterId: self.id, context: {}
+        });
+      }
+    },
+    panCameraTo: (x, y) => gameCtx.camera.panTo(x, y),
+    zoomCamera: (level) => gameCtx.camera.setZoom(level),
+    focusCameraOn: (target) => gameCtx.camera.focusOn(target),
+    resetCamera: () => gameCtx.camera.reset(),
+    shakeCamera: (magnitude, duration) => gameCtx.cameraShake.shake(magnitude, duration),
+
+    // --- Utilities & Hero State (No Callbacks - Intrinsically Safe) ---
+    playSound: (soundName) => audioManager.playSound(soundName),
+    getCanvasDimensions: () => ({ width: canvasRef.current?.width || 0, height: canvasRef.current?.height || 0 }),
+    getRandomNumber: (min, max) => Math.random() * (max - min) + min,
+    getAngle: (p1, p2) => Math.atan2(p2.y - p1.y, p2.x - p1.x),
+    getDistance,
+    raycast: (startX, startY, angle, length, width): Hero[] => {
+        if (!self) return [];
+        const hits: Hero[] = [];
+        const stepX = Math.cos(angle) * 10;
+        const stepY = Math.sin(angle) * 10;
+        for (let i = 0; i < length / 10; i++) {
+          const checkX = startX + i * stepX;
+          const checkY = startY + i * stepY;
+          for (const fighter of gameCtx.fighters) {
+            if (
+              fighter.id === self.id ||
+              !(fighter instanceof Hero) ||
+              hits.includes(fighter)
+            )
+              continue;
+            if (
+              checkCollision(
+                {
+                  x: checkX - width / 2,
+                  y: checkY - width / 2,
+                  width: width,
+                  height: width,
+                },
+                fighter
               )
-                continue;
-              if (
-                checkCollision(
-                  {
-                    x: checkX - width / 2,
-                    y: checkY - width / 2,
-                    width: width,
-                    height: width,
-                  },
-                  fighter
-                )
-              ) {
-                hits.push(fighter);
-              }
+            ) {
+              hits.push(fighter as Hero);
             }
           }
-          return hits;
-        },
-        setHeroData: (target, key, value) => target.setData(key, value),
-        getHeroData: (target, key) => target.getData(key),
-      };
-    };
-
+        }
+        return hits;
+    },
+    setHeroData: (target, key, value) => target.setData(key, value),
+    getHeroData: (target, key) => target.getData(key),
+  };
+};
     // --- Battle Initialization ---
     let logger: HighlightLogger;
     const heroDataMap = new Map<number, HeroData>();
 
-    if (fullSetup.type === "HERO_BATTLE") {
-      const config = fullSetup.config;
+    const generateSpawnPoints = (count: number, bounds: GameBounds): { x: number, y: number }[] => {
+        const points = [];
+        const padding = 150; // Keep heroes away from edges initially
+        
+        // Handle case for 1 or 0 heroes gracefully
+        if (count <= 1) {
+            return [{ x: bounds.x + bounds.width / 2, y: bounds.y + bounds.height / 2 }];
+        }
 
-      const spawnPoints = [
-        { x: gameBounds.x + 100, y: gameBounds.y + 100 },
-        {
-          x: gameBounds.x + gameBounds.width - 200,
-          y: gameBounds.y + gameBounds.height - 200,
-        },
-        { x: gameBounds.x + 100, y: gameBounds.y + gameBounds.height - 200 },
-        { x: gameBounds.x + gameBounds.width - 200, y: gameBounds.y + 100 },
-        { x: gameBounds.x + gameBounds.width / 2, y: gameBounds.y + 100 },
-        { x: gameBounds.x + 100, y: gameBounds.y + gameBounds.height / 2 },
-        {
-          x: gameBounds.x + gameBounds.width - 200,
-          y: gameBounds.y + gameBounds.height / 2,
-        },
-        {
-          x: gameBounds.x + gameBounds.width / 2,
-          y: gameBounds.y + gameBounds.height - 200,
-        },
-      ];
+        const angleStep = (Math.PI * 2) / count;
+        const centerX = bounds.x + bounds.width / 2;
+        const centerY = bounds.y + bounds.height / 2;
+        const radiusX = (bounds.width / 2) - padding;
+        const radiusY = (bounds.height / 2) - padding;
+
+        for (let i = 0; i < count; i++) {
+            const angle = i * angleStep;
+            const x = centerX + Math.cos(angle) * radiusX;
+            const y = centerY + Math.sin(angle) * radiusY;
+            points.push({ x, y });
+        }
+        return points;
+    };
+    if (battleSetup.type === "HERO_BATTLE") {
+      // DEFENSIVE: Handle case where heroes are missing, even if the page component checked.
+      if (initialHeroes.length === 0) {
+        toast.error("Critical Error", { description: "Cannot start battle, hero data is missing." });
+        return; // Abort game loop.
+      }
 
-      gameState.fighters = config.heroes.map((heroData, i) => {
+      const spawnPoints = generateSpawnPoints(initialHeroes.length, gameBounds);
+
+      gameState.fighters = initialHeroes.map((heroData, i) => {
         const runtimeId = Date.now() + i;
         const hero = new Hero(
           heroData,
-          Date.now() + i,
+          runtimeId,
           spawnPoints[i].x,
           spawnPoints[i].y,
           sandboxExecutor,
           {}
         );
-        console.log(hero);
 
         hero.avatarImage = loadedImages[`hero_${i}_avatar`];
         hero.iconImage = loadedImages[`hero_${i}_icon`];
-
         heroDataMap.set(runtimeId, heroData);
-
         return hero;
       });
-      logger = new HighlightLogger(
-        gameState.fighters.map((f) => ({ id: f.id, name: f.name }))
-      );
-    } else {
+
+      logger = new HighlightLogger(gameState.fighters.map((f) => ({ id: f.id, name: f.name })));
+    }  else {
       // 'CUSTOM_BATTLE'
-      const config = fullSetup.config;
+      // Narrow config type to CustomBattleConfig
+      const config = fullSetup.config as import("@/types").CustomBattleConfig;
       const spawnPoints = [
         { x: gameBounds.x + 50, y: gameBounds.y + 50 },
         { x: gameBounds.x + gameBounds.width - 150, y: gameBounds.y + 50 },
@@ -1957,7 +1993,7 @@ const BattleArena = ({ battleSetup }: { battleSetup: BattleSetup }) => {
           // Determine the list of players based on the battle type
           players:
             fullSetup.type === "HERO_BATTLE"
-              ? fullSetup.config.heroes.map((heroData) => {
+              ? initialHeroes.map((heroData) => {
                   // For heroes, find their randomly assigned color from the game instance
                   const fighterInstance = gameState.fighters.find(
                     (f) => f.name === heroData.heroName

components/HeroRoster.tsx

@@ -78,7 +78,7 @@ const HeroRoster = ({ initialHeroes }: HeroRosterProps) => {
         const battleSetup: BattleSetup = {
             type: 'HERO_BATTLE',
             config: {
-                heroes: [selectedHeroes[0], selectedHeroes[1]],
+                heroIds: [selectedHeroes[0]._id, selectedHeroes[1]._id].filter((id): id is string => typeof id === 'string'),
                 // --- USE STATE FOR SETTINGS ---
                 gameSpeed: gameSpeed, 
                 activePowerUps: activePowerUps, 

lib/game/Hero.ts

@@ -70,6 +70,7 @@ export class Hero {
   isWinner: boolean = false;
   victoryScale: number = 1;
   initialSize: number;
+    maxSpeed: number = 6;
 
   constructor(
     heroData: HeroData,
@@ -823,7 +824,7 @@ export class Hero {
           const range = this.basicAttack.range || 50; // Use defined range or a sensible default.
           // Create a safety buffer. Be MORE cautious against contact heroes.
           const safetyBuffer =
-          //@ts-expect-error no error
+            //@ts-expect-error no error
             this.target.basicAttack.type === "CONTACT" ? 40 : 15;
           const optimalDistance = range - safetyBuffer;
 
@@ -834,7 +835,6 @@ export class Hero {
             // Otherwise, we are in the sweet spot. Stop moving forward.
             isMoving = false;
           }
-
         } else if (this.basicAttack.type === "RANGED") {
           const safeDistance =
             typeof this.basicAttack.range === "number"
@@ -1015,23 +1015,14 @@ export class Hero {
     allOpponents: (Square | Hero)[],
     powerUps: PowerUp[],
     api: GameAPI
-  ) {
-    // Filter to only get hero opponents
-    // Filter to only get hero opponents for the AI
-    const heroOpponents = allOpponents.filter(
-      (o) =>
-        o instanceof Hero &&
-        o.id !== this.id &&
-        o.teamId !== this.id &&
-        (o as Hero).ghostTimer <= 0
-    ) as Hero[];
-    // Standard state updates
+  ): boolean {
+    // --- V2's Advanced State Timers ---
     if (this.speakingTimer > 0) this.speakingTimer--;
     else this.isSpeaking = false;
     if (this.stunTimer > 0) {
       this.stunTimer--;
-      return;
-    } // Stunned heroes can't do anything
+      return false;
+    } // Return early like V1
     if (this.speedBoostTimer > 0) this.speedBoostTimer--;
     if (this.ghostTimer > 0) this.ghostTimer--;
     if (this.invinsibleTimer > 0) this.invinsibleTimer--;
@@ -1041,69 +1032,92 @@ export class Hero {
     if (Math.abs(this.rotationAnimation) > 0.01)
       this.rotationAnimation = lerp(this.rotationAnimation, 0, 0.15);
 
-    // 1. AI Logic: Decide and Move
-    this._makeDecision(heroOpponents, powerUps, api);
-    this._handleMovement(powerUps, api);
-
-    // 2. Physics & State Updates
-    this.basicAttackCooldownTimer--;
+    // --- V1's CORE MOVEMENT ENGINE (The "will-less" part) ---
+    let wallHit = false;
     const boost = this.speedBoostTimer > 0 ? 1.75 : 1.0;
-    const finalSpeed = this.speed * boost * gameSpeed;
+    // Use the hero's 'speed' stat from V2, but apply it to V1's movement style
+    const finalSpeed = (this.speed / 2) * boost * gameSpeed; // V2 speed stat is a bit high, scale it down
+
+   // --- NEW: Speed Limiting (Clamping) Logic ---
+    // Calculate the current speed using the Pythagorean theorem
+    const currentSpeed = Math.hypot(this.dx, this.dy);
+
+    // If the current speed exceeds our defined maxSpeed...
+    if (currentSpeed > this.maxSpeed) {
+      // ...calculate the scaling factor to bring it back to the max speed.
+      const factor = this.maxSpeed / currentSpeed;
+      // Apply the factor to both dx and dy to reduce speed without changing direction.
+      this.dx *= factor;
+      this.dy *= factor;
+    }
+    // ====================================================================
+    
     this.x += this.dx * finalSpeed;
     this.y += this.dy * finalSpeed;
 
-    // 4. Wall Collision
-    if (this.x + this.width > gameBounds.x + gameBounds.width) {
-      this.dx *= -1;
-      this.x = gameBounds.x + gameBounds.width - this.width;
-    } else if (this.x < gameBounds.x) {
+    if (
+      this.x + this.width > gameBounds.x + gameBounds.width ||
+      this.x < gameBounds.x
+    ) {
       this.dx *= -1;
-      this.x = gameBounds.x;
+      this.x = Math.max(
+        gameBounds.x,
+        Math.min(this.x, gameBounds.x + gameBounds.width - this.width)
+      );
+      wallHit = true;
     }
-    if (this.y + this.height > gameBounds.y + gameBounds.height) {
-      this.dy *= -1;
-      this.y = gameBounds.y + gameBounds.height - this.height;
-    } else if (this.y < gameBounds.y) {
+    if (
+      this.y + this.height > gameBounds.y + gameBounds.height ||
+      this.y < gameBounds.y
+    ) {
       this.dy *= -1;
-      this.y = gameBounds.y;
+      this.y = Math.max(
+        gameBounds.y,
+        Math.min(this.y, gameBounds.y + gameBounds.height - this.height)
+      );
+      wallHit = true;
     }
 
-    // Handle Melee Attack Logic Separately
+    // --- V2's ATTACK LOGIC (triggered by proximity, not AI decisions) ---
+    this.basicAttackCooldownTimer--;
+
+    // Filter for valid hero opponents
+    const heroOpponents = allOpponents.filter(
+      (o) =>
+        o instanceof Hero &&
+        o.id !== this.id &&
+        o.teamId !== this.id &&
+        o.ghostTimer <= 0
+    ) as Hero[];
+
     if (this.basicAttack.type === "MELEE") {
       if (this.isPrimedForMelee) {
-        // Attack is ready! Look for a target in range.
-        const targetInRange =
-          typeof this.basicAttack.range === "number"
-            ? heroOpponents.find(
-                (o) => api.getDistance(this, o) <= this.basicAttack.range!
-              )
-            : undefined;
-
+        const targetInRange = heroOpponents.find(
+          (o) => api.getDistance(this, o) <= (this.basicAttack.range || 0)
+        );
         if (targetInRange) {
           this._executeMeleeAttack(targetInRange, api);
           this.isPrimedForMelee = false;
           this.basicAttackCooldownTimer = this.basicAttack.cooldown * 60;
         }
-      } else {
-        // Cooldown logic
-        if (this.basicAttackCooldownTimer > 0) {
-          this.basicAttackCooldownTimer--;
-        } else {
-          this.isPrimedForMelee = true;
-        }
+      } else if (this.basicAttackCooldownTimer <= 0) {
+        this.isPrimedForMelee = true;
       }
     } else {
-      // Handle Ranged & Contact Attack Logic (your old system)
-      if (this.basicAttackCooldownTimer > 0) {
-        this.basicAttackCooldownTimer--;
-      } else {
-        if (this.basicAttack.type === "RANGED") {
-          if (this.target instanceof Hero) {
-            this._executeRangedAttack(this.target, api);
-          }
+      // RANGED and CONTACT
+      if (this.basicAttackCooldownTimer <= 0) {
+        const target = this._findNearestOpponent(heroOpponents, api);
+        if (
+          target &&
+          this.basicAttack.type === "RANGED" &&
+          api.getDistance(this, target) <= (this.basicAttack.range || 1000)
+        ) {
+          this._executeRangedAttack(target, api);
         }
       }
     }
+
+    return wallHit; // Keep V1's return value
   }
   draw(ctx: CanvasRenderingContext2D) {
     const centerX = this.x + this.width / 2;

lib/validators.ts

@@ -1,3 +1,4 @@
+import { Type } from "@google/genai";
 import { z } from "zod";
 
 export const heroFormSchema = z.object({
@@ -27,4 +28,53 @@ export const heroFormSchema = z.object({
   introLineAudioUrl: z.string().url().optional().nullable(),
   superpowerActivationLineAudioUrl: z.string().url().optional().nullable(),
   tags: z.array(z.string()).optional(),
-});
+});
+
+
+export const heroDataSchema = {
+  type: Type.OBJECT,
+  properties: {
+    heroName: { type: Type.STRING },
+    heroGender: { type: Type.STRING },
+    heroDescription: { type: Type.STRING },
+    heroColor: { type: Type.STRING },
+    heroHealth: { type: Type.NUMBER },
+    heroSpeed: { type: Type.NUMBER },
+    basicAttack: {
+      type: Type.OBJECT,
+      properties: {
+        type: { type: Type.STRING }, // e.g., "RANGED", "MELEE", "CONTACT"
+        damage: { type: Type.NUMBER },
+        cooldown: { type: Type.NUMBER },
+        range: { type: Type.NUMBER },
+        knockback: { type: Type.NUMBER },
+      },
+      required: ["type", "damage", "cooldown", "range", "knockback"],
+    },
+    powerName: { type: Type.STRING },
+    powerDescription: { type: Type.STRING },
+    powerLogicDescription: { type: Type.STRING },
+    introLine: { type: Type.STRING },
+    superpowerActivationLine: { type: Type.STRING },
+    avatarPrompt: { type: Type.STRING },
+    iconPrompt: { type: Type.STRING },
+    tags: { type: Type.ARRAY, items: { type: Type.STRING } },
+  },
+  required: [
+    "heroName",
+    "heroGender",
+    "heroDescription",
+    "heroColor",
+    "heroHealth",
+    "heroSpeed",
+    "basicAttack",
+    "powerName",
+    "powerDescription",
+    "powerLogicDescription",
+    "introLine",
+    "superpowerActivationLine",
+    "avatarPrompt",
+    "iconPrompt",
+    "tags",
+  ],
+};

model/battleSetup.model.ts

@@ -1,17 +1,35 @@
-import { Schema, Document, models, model } from "mongoose";
+import { HeroBattleConfig } from "@/types";
+import { Schema, Document, models, model, Model } from "mongoose";
 
-// Define an interface for our document to ensure type safety
-export interface IBattleSetup extends Document {
-  setupData: string; // We'll store the stringified JSON object
+// Define an interface for our document to ensure type safety.
+// This matches the BattleSetup type from types/index.ts
+export interface IBattleSetup extends HeroBattleConfig, Document {
   createdAt: Date;
 }
 
+// REFACTOR: Instead of a single JSON string, we define the schema's structure.
+// This leverages Mongoose's validation, prevents JSON parsing errors,
+// and makes the data more robust and queryable.
 const BattleSetupSchema = new Schema({
-  // Storing the large setup object as a single stringified JSON field is efficient
-  setupData: { type: String, required: true },
-  createdAt: { type: Date, default: Date.now, expires: '48h' } // Automatically delete docs after 1 hour
+  type: {
+    type: String,
+    required: true,
+    enum: ["HERO_BATTLE", "CUSTOM_BATTLE"],
+  },
+  // We use Schema.Types.Mixed for the config object because its structure
+  // depends on the `type` field. Mongoose will store the object directly.
+  config: {
+    type: Schema.Types.Mixed,
+    required: true,
+  },
+  createdAt: {
+    type: Date,
+    default: Date.now,
+  },
 });
 
-const BattleSetup = models.BattleSetup || model<IBattleSetup>("BattleSetup", BattleSetupSchema);
+// Use a type-safe model definition.
+const BattleSetupModel: Model<IBattleSetup> =
+  models.BattleSetup || model<IBattleSetup>("BattleSetup", BattleSetupSchema);
 
-export default BattleSetup;
+export default BattleSetupModel;

model/hero.model.ts

@@ -4,6 +4,13 @@ import { HeroData } from "@/types"; // We will ensure HeroData is correctly defi
 // Define an interface for our document to ensure type safety
 export type IHero = HeroData & Document & {
   createdAt: Date;
+  errorCount: number;
+  lastError?: {
+    message?: string;
+    faultyCode?: string;
+    reportedAt?: Date;
+  };
+  repairAttempts: number;
   // We can add more metadata here later, like createdBy, wins, losses, etc.
 };
 
@@ -28,7 +35,7 @@ const HeroSchema = new Schema({
   powerLogicDescription: { type: String, required: true },
   powerLogic: { type: String, required: true }, // The AI-generated code string
   introLine: { type: String, required: true },
-  superpowerActivationLine: { type: String, required:true },
+  superpowerActivationLine: { type: String, required: true },
   aiVoicer: { type: String, required: true },
   avatarPrompt: { type: String, required: true },
   iconPrompt: { type: String, required: true },
@@ -37,6 +44,18 @@ const HeroSchema = new Schema({
   introLineAudioUrl: { type: String },
   superpowerActivationLineAudioUrl: { type: String },
   tags: [{ type: String }],
+  errorCount: {
+    type: Number,
+    default: 0,
+    index: true, // Index this field for efficient querying by the repair worker.
+  },
+  lastError: {
+    message: { type: String },
+    faultyCode: { type: String },
+    reportedAt: { type: Date },
+  },
+  // We can add repairAttempts later if we build the "Fixer AI"
+  repairAttempts: { type: Number, default: 0 },
   createdAt: { type: Date, default: Date.now },
 });
 

repair.worker.ts

@@ -0,0 +1,173 @@
+// FILE: repair.worker.ts
+
+import "dotenv/config";
+import { GoogleGenAI } from "@google/genai";
+import { connectToDatabase } from "./lib/database";
+import Hero from "./model/hero.model";
+import { sanitizePowerLogicCode } from "./lib/utils";
+import { heroCoderPrompt } from "./lib/AiPrompts";
+import { IHero } from "./model/hero.model"; // Import the Mongoose document type
+
+// --- Configuration ---
+const REPAIR_INTERVAL_MS = 5 * 60 * 1000; // Run every 5 minutes
+const MAX_REPAIR_ATTEMPTS = 2; // How many times to try fixing a hero before giving up
+
+// --- Specialized AI Prompt for Fixing Code ---
+const fixerAiPrompt = `
+You are an expert JavaScript Game Engine Debugger. Your mission is to fix faulty code.
+You will be given the original code generation prompt, the hero's power description, the full faulty JavaScript code, and the specific runtime error it produced.
+
+Your task is to analyze the error and the code, identify the mistake, and provide a corrected, fully functional version of the JavaScript function.
+The mistake is likely a typo, using a non-existent API, or accessing a property on a null or undefined object (e.g., trying to use 'target.x' when 'target' might not exist).
+
+RULES:
+1.  Your response MUST be ONLY the corrected, complete, standalone JavaScript async arrow function: \`async ({...}) => { ... }\`.
+2.  Do NOT add any explanations, comments, or markdown.
+3.  Pay EXTREMELY close attention to the provided API documentation to ensure you are only using valid functions and properties.
+4.  Ensure all object access is safe. For example, check \`if (target)\` before using \`target.x\`.
+
+--- PROVIDED API DOCUMENTATION ---
+${heroCoderPrompt}
+`;
+
+
+/**
+ * Queries the database for heroes that have reported runtime errors.
+ */
+async function findBrokenHeroes(): Promise<IHero[]> {
+  console.log("[Repair Worker] Checking for broken heroes...");
+  try {
+    // Find heroes that have errors and haven't exceeded repair attempts.
+    const heroes = await Hero.find({
+      errorCount: { $gt: 0 },
+      // repairAttempts: { $lt: MAX_REPAIR_ATTEMPTS } // We'll add this field later
+    }).limit(5); // Process in batches to avoid overwhelming the AI API.
+
+    if (heroes.length > 0) {
+      console.log(`[Repair Worker] Found ${heroes.length} broken hero(es) to repair.`);
+    } else {
+      console.log("[Repair Worker] No broken heroes found. All systems nominal.");
+    }
+    return heroes;
+  } catch (error) {
+    console.error("[Repair Worker] CRITICAL: Could not query database for broken heroes.", error);
+    return [];
+  }
+}
+
+/**
+ * Uses the Fixer AI to attempt to repair a hero's faulty power logic.
+ * @param hero The Mongoose document of the hero to repair.
+ * @returns The new, sanitized code string if successful, otherwise null.
+ */
+async function attemptRepair(hero: IHero): Promise<string | null> {
+  // Defensive check for required error information
+  if (!hero.lastError?.faultyCode || !hero.lastError?.message || !hero.powerLogicDescription) {
+    console.error(`[Repair Worker] Hero ${hero.heroName} is flagged but missing error details. Cannot repair.`);
+    return null;
+  }
+
+  console.log(`[Repair Worker] Attempting to repair hero: ${hero.heroName}`);
+
+  // Construct the detailed prompt for the Fixer AI
+  const repairPrompt = `
+    HERO POWER DESCRIPTION:
+    ${hero.powerLogicDescription}
+
+    ---
+    FAULTY JAVASCRIPT CODE:
+    \`\`\`javascript
+    ${hero.lastError.faultyCode}
+    \`\`\`
+
+    ---
+    RUNTIME ERROR MESSAGE:
+    ${hero.lastError.message}
+  `;
+
+  try {
+    const apiKey = process.env.GEMINI_API_KEY;
+    if (!apiKey) {
+      throw new Error("GEMINI_API_KEY is not configured.");
+    }
+    const ai = new GoogleGenAI({ apiKey });
+
+    const result = await ai.models.generateContent({
+        model: "gemini-2.5-pro", // Use the most capable model for debugging
+        contents: repairPrompt,
+        config: {
+            systemInstruction: fixerAiPrompt,
+        }
+    });
+
+    const fixedCode = result.text;
+    if (!fixedCode) {
+      console.warn(`[Repair Worker] Fixer AI for ${hero.heroName} returned an empty response.`);
+      return null;
+    }
+
+    // IMPORTANT: We must validate the AI's fix. It might also be syntactically invalid.
+    return sanitizePowerLogicCode(fixedCode);
+
+  } catch (error) {
+    console.error(`[Repair Worker] AI repair attempt for ${hero.heroName} failed:`, error);
+    return null;
+  }
+}
+
+/**
+ * The main workflow for the repair worker.
+ */
+async function repairWorkflow() {
+  await connectToDatabase();
+
+  // 1. Find all broken heroes
+  const brokenHeroes = await findBrokenHeroes();
+
+  for (const hero of brokenHeroes) {
+    let repairSucceeded = false;
+    
+    // 2. Attempt to repair the hero's code (with retries)
+    for (let i = 0; i < MAX_REPAIR_ATTEMPTS; i++) {
+        console.log(`[Repair Worker] Repair attempt ${i + 1}/${MAX_REPAIR_ATTEMPTS} for ${hero.heroName}...`);
+        const newCode = await attemptRepair(hero);
+
+        if (newCode) {
+            // Repair successful! Update the hero in the database.
+            await Hero.updateOne(
+                { _id: hero._id },
+                {
+                    $set: {
+                        powerLogic: newCode,
+                        lastError: undefined, // Clear the last error
+                        errorCount: 0 // Reset error count
+                    }
+                }
+            );
+            console.log(`[Repair Worker] ✅ SUCCESS: Hero ${hero.heroName} has been repaired!`);
+            repairSucceeded = true;
+            break; // Exit the retry loop
+        }
+    }
+
+    // 3. If all repair attempts fail, delete the hero
+    if (!repairSucceeded) {
+      console.log(`[Repair Worker] ❌ FAILED: All repair attempts for ${hero.heroName} failed. Deleting hero...`);
+      await Hero.deleteOne({ _id: hero._id });
+      console.log(`[Repair Worker] Hero ${hero.heroName} has been deleted.`);
+    }
+  }
+}
+
+/**
+ * Main execution function that runs the workflow on a set interval.
+ */
+async function main() {
+  console.log("🤖 Robotic Repair Bay Worker started.");
+  
+  // Run immediately on start, then run on the specified interval.
+  await repairWorkflow().catch(console.error);
+  setInterval(() => repairWorkflow().catch(console.error), REPAIR_INTERVAL_MS);
+}
+
+main();

start.sh

@@ -1,40 +1,106 @@
 #!/bin/bash
-# Define the cache directory
+
+# This script is designed for robustness in a containerized environment like Hugging Face Spaces.
+# It builds the necessary worker scripts, then starts the Next.js server, the battle
+# generation worker, and the self-healing repair worker in parallel. It also includes
+# a cleanup mechanism to ensure all processes are terminated correctly on shutdown.
+
+# --- Graceful Shutdown Function and Trap ---
+# This function will be called when the script receives a shutdown signal.
+cleanup() {
+    echo ">>> Received shutdown signal. Cleaning up background processes..."
+    # The 'kill' command sends a termination signal to the specified Process IDs (PIDs).
+    # The '2>/dev/null' suppresses errors if a process has already exited.
+    if [ -n "$SERVER_PID" ]; then kill $SERVER_PID 2>/dev/null; fi
+    if [ -n "$BATTLE_WORKER_PID" ]; then kill $BATTLE_WORKER_PID 2>/dev/null; fi
+    if [ -n "$REPAIR_WORKER_PID" ]; then kill $REPAIR_WORKER_PID 2>/dev/null; fi
+    echo ">>> Cleanup complete."
+}
+
+# The 'trap' command registers the 'cleanup' function to be executed when the script
+# receives specific signals (EXIT, SIGINT, SIGTERM). This is crucial for clean shutdowns.
+trap cleanup EXIT SIGINT SIGTERM
+
+# --- Environment and Puppeteer Setup ---
+echo ">>> Setting up environment for Puppeteer..."
 export PUPPETEER_CACHE_DIR="/tmp/puppeteer_cache"
 
-# Find Chrome executable
+# Find Chrome executable in the cache copied by the Dockerfile.
 CHROME_EXECUTABLE_PATH=$(find /opt/puppeteer_cache -name "chrome" -type f -executable 2>/dev/null | head -1)
-
 if [ -z "$CHROME_EXECUTABLE_PATH" ] || [ ! -f "$CHROME_EXECUTABLE_PATH" ]; then
     CHROME_EXECUTABLE_PATH=$(find /opt/puppeteer_cache -path "*/chrome-linux*/chrome" -type f 2>/dev/null | head -1)
 fi
 
 if [ -z "$CHROME_EXECUTABLE_PATH" ] || [ ! -f "$CHROME_EXECUTABLE_PATH" ]; then
-    echo "!!! CRITICAL ERROR: Chrome executable not found !!!"
+    echo "!!! CRITICAL ERROR: Chrome executable not found in /opt/puppeteer_cache !!!"
     exit 1
 fi
-
 export PUPPETEER_EXECUTABLE_PATH=$CHROME_EXECUTABLE_PATH
 echo ">>> Puppeteer will use Chrome from: $PUPPETEER_EXECUTABLE_PATH"
 
-# CRITICAL: Bind to 0.0.0.0 so Hugging Face can detect the app is running
+# --- Build Step ---
+# Build both worker scripts (worker.ts and repair.worker.ts) using the single command.
+echo ">>> Building worker scripts..."
+npm run build:worker
+# Check if the build command was successful. If not, exit immediately.
+if [ $? -ne 0 ]; then
+    echo "!!! CRITICAL ERROR: Worker build failed. Exiting. !!!"
+    exit 1
+fi
+echo ">>> Worker build complete."
+
+# --- Process Execution ---
+# Set host and port for the Next.js server to be accessible within the container network.
 export HOST=0.0.0.0
 export PORT=7860
 
-# Start the Next.js server in the background
-# Use npm run start with proper host binding
+# 1. Start the Next.js server in the background.
+echo ">>> Starting Next.js server..."
 npm run start &
+# Capture the Process ID (PID) of the server.
+SERVER_PID=$!
+echo "Next.js server started with PID: $SERVER_PID"
 
-# Wait for the server to be ready with health check
-echo "Waiting for Next.js server to start..."
+# 2. Wait for the Next.js server to be ready before starting dependent workers.
+echo "Waiting for Next.js server to become available..."
 for i in {1..30}; do
-    if curl -f http://localhost:7860 >/dev/null 2>&1; then
-        echo "Next.js server is ready!"
+    # Use 'curl' to check if the server is responding to requests.
+    if curl -sf http://localhost:7860 >/dev/null; then
+        echo ">>> Next.js server is ready!"
         break
     fi
+    # If the loop ends without the server being ready, exit the script.
+    if [ $i -eq 30 ]; then
+        echo "!!! CRITICAL ERROR: Next.js server failed to start in time. Exiting. !!!"
+        exit 1
+    fi
     echo "Attempt $i: Server not ready yet, waiting..."
     sleep 2
 done
 
-# Start the automation worker in the foreground
-node dist/worker.js
+# 3. Start the battle generation worker in the background.
+echo ">>> Starting battle generation worker..."
+node dist/worker.js &
+# Capture the PID of the battle worker.
+BATTLE_WORKER_PID=$!
+echo "Battle worker started with PID: $BATTLE_WORKER_PID"
+
+# 4. Start the self-healing repair worker in the background.
+echo ">>> Starting self-healing repair worker..."
+node dist/repair.worker.js &
+# Capture the PID of the repair worker.
+REPAIR_WORKER_PID=$!
+echo "Repair worker started with PID: $REPAIR_WORKER_PID"
+
+
+echo ""
+echo "========================================="
+echo "      ALL SYSTEMS ARE OPERATIONAL"
+echo "========================================="
+echo ""
+
+# The 'wait' command is essential. It pauses the script here, preventing it from
+# exiting while the background processes are running. It will wait until the
+# specified process (the Next.js server) terminates. When it does, the script
+# will proceed, and the 'trap' will trigger the cleanup function.
+wait $SERVER_PID

tsconfig.worker.json

@@ -9,7 +9,8 @@
     "noEmit": false
   },
   "include": [
-    "worker.ts" // Only the entry point is needed! TS will find the rest.
+    "worker.ts", // Only the entry point is needed! TS will find the rest.,
+    "repair.worker.ts" 
   ],
   "exclude": ["node_modules", ".next", "components", "app/components"]
 }

types/index.ts

@@ -45,7 +45,7 @@ export type HeroData = {
 
 // The configuration for a hero-vs-hero battle
 export type HeroBattleConfig = {
-  heroes: [HeroData, HeroData];
+  heroIds: string[]; 
   gameSpeed: number;
   // We MUST include power-ups here to keep them in the game
   activePowerUps: PowerUpType[];

worker.ts

@@ -6,7 +6,7 @@ import path from "path";
 // We can directly import our server actions because this script runs in the same project context
 // import { generateAndSaveHero } from './app/actions/ai.actions';
 import {  saveBattleSetup } from "./app/actions/db.actions";
-import { BattleReport, BattleSetup, HeroData } from "./types";
+import { BattleReport, BattleSetup } from "./types";
 import { generateAndSaveHero, generateYouTubeMetadata } from "./app/actions/ai.actions";
 
 // --- CONFIGURATION ---
@@ -161,7 +161,7 @@ async function main() {
       const battleSetup: BattleSetup = {
         type: "HERO_BATTLE",
         config: {
-          heroes: [hero1 as HeroData, hero2 as HeroData],
+          heroIds: [hero1._id as string, hero2._id as string],
           gameSpeed: 1.5, // Speed up automated battles
           activePowerUps: [
             "SPEED_BOOST",