@csmodding/gameface-devtools-mcp 0.2.0 → 0.3.0

package/dist/server.mjs

@@ -30399,8 +30399,8 @@ class CdpConnection {
     this.target = target;
     this.onEvent = onEvent;
     ws.addEventListener("message", (event) => this.handleMessage(event));
-    ws.addEventListener("close", () => this.handleClose("connection closed"));
-    ws.addEventListener("error", () => this.handleClose("connection error"));
+    ws.addEventListener("close", () => this.handleClose(`connection closed`));
+    ws.addEventListener("error", () => this.handleClose(`connection error`));
   }
   static async open(cfg, target, onEvent) {
     const ws = new WebSocket(target.wsUrl);
@@ -30427,7 +30427,7 @@ class CdpConnection {
   }
   call(method, params) {
     if (!this.isOpen) {
-      return Promise.reject(new CdpError("CDP connection is not open"));
+      return Promise.reject(new CdpError(`CDP connection is not open`));
     }
     const id = this.nextId++;
     return new Promise((resolve, reject) => {
@@ -30453,7 +30453,7 @@ class CdpConnection {
     this.enabledDomains.add(domain2);
   }
   close() {
-    this.handleClose("closed by client");
+    this.handleClose(`closed by client`);
     try {
       this.ws.close();
     } catch {}
@@ -30633,7 +30633,7 @@ function describeRemoteObject(obj) {
 }
 function formatException(details) {
   const exception = details?.exception;
-  const desc = exception?.description ?? exception?.value ?? details?.text ?? "unknown error";
+  const desc = exception?.description ?? exception?.value ?? details?.text ?? `unknown error`;
   return typeof desc == "string" ? desc : JSON.stringify(desc);
 }
 function valToStr(value) {
@@ -30666,12 +30666,15 @@ class DebuggerSession {
   nextBpId = 1;
   pausedSeq = 0;
   client;
-  constructor(client) {
+  constructor(client, reloads) {
     this.client = client;
     client.onConnect((conn) => this.onConnect(conn));
     client.onEvent((method, params) => {
       this.handle(method, params);
     });
+    reloads.onReload(() => {
+      this.scripts.clear();
+    });
   }
   async status(setPause) {
     try {
@@ -30817,7 +30820,7 @@ class DebuggerSession {
     try {
       await this.ensureReady();
       if (!this.paused) {
-        return text("Not paused (the UI is running). Set a breakpoint or use game_debug_step pause.");
+        return text(`Not paused (the UI is running). Set a breakpoint or use game_debug_step pause.`);
       }
       const frames = [];
       for (const [index, frame] of this.paused.callFrames.entries()) {
@@ -30886,7 +30889,7 @@ class DebuggerSession {
         return text(paused ? `Paused at ${this.topLocation()}.` : `Pause requested; nothing executed within ${PAUSE_WAIT_MS}ms (UI idle).`);
       }
       if (!this.paused) {
-        return errorText("Not paused. Set a breakpoint and trigger it, or use action 'pause' first.");
+        return errorText(`Not paused. Set a breakpoint and trigger it, or use action 'pause' first.`);
       }
       if (action == "resume") {
         await this.client.call("Debugger.resume");
@@ -30894,7 +30897,7 @@ class DebuggerSession {
         while (Date.now() < deadline && this.paused) {
           await sleep(POLL_INTERVAL_MS);
         }
-        return text("Resumed (UI unfrozen).");
+        return text(`Resumed (UI unfrozen).`);
       }
       const cdpMethod = { over: "stepOver", into: "stepInto", out: "stepOut" }[action];
       const before = this.pausedSeq;
@@ -31002,204 +31005,15 @@ class DebuggerSession {
 // src/tools.ts
 var import_common_tags3 = __toESM(require_lib(), 1);
 import { setTimeout as sleep2 } from "node:timers/promises";
-var collectDomFn = (sel, all, maxHtml) => {
-  const matches = document.querySelectorAll(sel);
-  const first = matches.item(0);
-  const chosen = all ? Array.from(matches) : first ? [first] : [];
-  const describe3 = (el) => {
-    const rect = el.getBoundingClientRect();
-    const attributes = {};
-    for (const attr of Array.from(el.attributes)) {
-      attributes[attr.name] = attr.value;
-    }
-    const classAttr = el.getAttribute("class");
-    let html = el.outerHTML || "";
-    const truncated = html.length > maxHtml;
-    if (truncated) {
-      html = html.slice(0, maxHtml);
-    }
-    return {
-      tagName: el.tagName ? el.tagName.toLowerCase() : null,
-      id: el.id || null,
-      classes: classAttr != null && classAttr.length > 0 ? classAttr : null,
-      rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
-      attributes,
-      outerHTML: html,
-      truncated
-    };
-  };
-  return { count: matches.length, elements: chosen.map((el) => describe3(el)) };
-};
-var clickFn = (sel, index) => {
-  const nodes = document.querySelectorAll(sel);
-  if (nodes.length == 0) {
-    return { found: false, count: 0, fired: [] };
-  }
-  const el = nodes[index];
-  if (!el) {
-    return { found: false, count: nodes.length, fired: [] };
-  }
-  const rect = el.getBoundingClientRect();
-  const cx = rect.x + rect.width / 2;
-  const cy = rect.y + rect.height / 2;
-  const base = {
-    bubbles: true,
-    cancelable: true,
-    view: window,
-    button: 0,
-    clientX: cx,
-    clientY: cy
-  };
-  const Pointer = typeof PointerEvent == "function" ? PointerEvent : MouseEvent;
-  const fired = [];
-  const fire = (Ctor, type, extra) => {
-    try {
-      el.dispatchEvent(new Ctor(type, { ...base, ...extra }));
-      fired.push(type);
-    } catch {}
-  };
-  fire(Pointer, "pointerdown", { pointerId: 1, isPrimary: true });
-  fire(MouseEvent, "mousedown");
-  fire(Pointer, "pointerup", { pointerId: 1, isPrimary: true });
-  fire(MouseEvent, "mouseup");
-  fire(MouseEvent, "click");
-  return { found: true, count: nodes.length, x: cx, y: cy, fired };
-};
-var waitCheckFn = (sel, visible) => {
-  const el = document.querySelector(sel);
-  if (!el) {
-    return false;
-  }
-  if (!visible) {
-    return true;
-  }
-  const rect = el.getBoundingClientRect();
-  return rect.width > 0 && rect.height > 0;
-};
-var fillFn = (sel, value) => {
-  const el = document.querySelector(sel);
-  if (!el) {
-    return { found: false };
-  }
-  try {
-    el.focus();
-  } catch {}
-  const tag = (el.tagName || "").toLowerCase();
-  if (el.isContentEditable) {
-    el.textContent = value;
-    el.dispatchEvent(new Event("input", { bubbles: true }));
-    el.dispatchEvent(new Event("change", { bubbles: true }));
-    return { found: true, mode: "contenteditable", value: el.textContent ?? "" };
-  }
-  const field = el;
-  const proto = tag == "textarea" ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
-  const setter = Object.getOwnPropertyDescriptor(proto, "value")?.set;
-  if (setter) {
-    setter.call(el, value);
-  } else {
-    field.value = value;
-  }
-  el.dispatchEvent(new Event("input", { bubbles: true }));
-  el.dispatchEvent(new Event("change", { bubbles: true }));
-  return { found: true, mode: tag || "input", value: field.value };
-};
-var typeFn = (sel, textToType) => {
-  const el = document.querySelector(sel);
-  if (!el) {
-    return { found: false, typed: 0 };
-  }
-  try {
-    el.focus();
-  } catch {}
-  const tag = (el.tagName || "").toLowerCase();
-  const editable = el.isContentEditable;
-  const field = el;
-  const proto = tag == "textarea" ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
-  const setter = Object.getOwnPropertyDescriptor(proto, "value")?.set;
-  const current = () => {
-    if (editable) {
-      return el.textContent ?? "";
-    }
-    return field.value || "";
-  };
-  const setValue = (next) => {
-    if (editable) {
-      el.textContent = next;
-    } else if (setter) {
-      setter.call(el, next);
-    } else {
-      field.value = next;
-    }
-  };
-  let typed = 0;
-  for (const ch of textToType) {
-    const opts = {
-      bubbles: true,
-      cancelable: true,
-      key: ch,
-      view: window
-    };
-    try {
-      el.dispatchEvent(new KeyboardEvent("keydown", opts));
-    } catch {}
-    setValue(current() + ch);
-    el.dispatchEvent(new Event("input", { bubbles: true }));
-    try {
-      el.dispatchEvent(new KeyboardEvent("keyup", opts));
-    } catch {}
-    typed++;
-  }
-  el.dispatchEvent(new Event("change", { bubbles: true }));
-  return { found: true, typed, value: current() };
-};
-var hoverFn = (sel) => {
-  const el = document.querySelector(sel);
-  if (!el) {
-    return { found: false };
-  }
-  const rect = el.getBoundingClientRect();
-  const cx = rect.x + rect.width / 2;
-  const cy = rect.y + rect.height / 2;
-  const base = {
-    bubbles: true,
-    cancelable: true,
-    view: window,
-    clientX: cx,
-    clientY: cy
-  };
-  const noBubble = { ...base, bubbles: false };
-  const fired = [];
-  const fire = (type, init) => {
-    try {
-      el.dispatchEvent(new MouseEvent(type, init));
-      fired.push(type);
-    } catch {}
-  };
-  fire("pointerover", base);
-  fire("mouseover", base);
-  fire("pointerenter", noBubble);
-  fire("mouseenter", noBubble);
-  fire("mousemove", base);
-  return { found: true, x: cx, y: cy, fired };
-};
-var rectFn = (sel) => {
-  const el = document.querySelector(sel);
-  if (!el) {
-    return { found: false };
-  }
-  const rect = el.getBoundingClientRect();
-  return { found: true, x: rect.x, y: rect.y, width: rect.width, height: rect.height };
-};
-function callPageFn(fn, ...args) {
-  const serialisedArgs = args.map((arg) => JSON.stringify(arg)).join(", ");
-  return `(${fn.toString()})(${serialisedArgs})`;
-}
 var POLL_INTERVAL_MS2 = 150;
 var MAX_WAIT_MS = 60000;
 var DEFAULT_WAIT_TIMEOUT_MS = 8000;
+var DEFAULT_RELOAD_WAIT_TIMEOUT_MS = 30000;
+var DEFAULT_QUIESCENT_MS = 1000;
 var DEFAULT_JPEG_QUALITY = 80;
 var DEFAULT_CONSOLE_LIMIT = 50;
-async function gameStatus(client) {
+var DEFAULT_FIND_LIMIT = 20;
+async function gameStatus(client, reloads) {
   const { host, port } = client.config;
   try {
     const target = await client.discover();
@@ -31213,12 +31027,25 @@ async function gameStatus(client) {
         protocol = versionInfo["Protocol-Version"];
       }
     } catch {}
+    let tracking = false;
+    try {
+      await client.connection();
+      tracking = true;
+    } catch {}
+    const { lastReloadAt } = reloads;
     return text(JSON.stringify({
       reachable: true,
       endpoint: `http://${host}:${port}`,
       target: { id: target.id, url: target.url, title: target.title, wsUrl: target.wsUrl },
       browser,
-      cdpProtocol: protocol
+      cdpProtocol: protocol,
+      reloads: tracking ? {
+        tracking: true,
+        count: reloads.count,
+        lastReloadAt: lastReloadAt == null ? null : new Date(lastReloadAt).toISOString(),
+        lastReloadAgoMs: lastReloadAt == null ? null : Date.now() - lastReloadAt,
+        contextUniqueId: reloads.contextUniqueId ?? null
+      } : { tracking: false }
     }, null, 2));
   } catch (error51) {
     return text(JSON.stringify({
@@ -31248,36 +31075,45 @@ async function gameEval(client, expression, awaitPromise = false) {
     return toErrorResult(error51);
   }
 }
-async function gameScreenshot(client, format = "png", quality, selector) {
+async function gameScreenshot(client, options = {}) {
+  const { format = "jpeg", quality, selector, index = 0 } = options;
   try {
     await client.ensureDomain("Page");
     const params = { format };
     if (format == "jpeg") {
       params.quality = quality ?? DEFAULT_JPEG_QUALITY;
     }
+    let caption;
     if (selector) {
       const rectRes = await client.call("Runtime.evaluate", {
-        expression: callPageFn(rectFn, selector),
+        expression: callPageFn(rectFn, selector, index),
         returnByValue: true
       });
       const rect = rectRes.result.value;
       if (!rect?.found) {
-        return errorText(`No element matched ${JSON.stringify(selector)} for game_screenshot.`);
+        return errorText(import_common_tags3.oneLine`
+          No element matched ${JSON.stringify(selector)} for game_screenshot at index ${index}
+          (matches found: ${rect?.count ?? 0}).
+        `);
       }
       if (!(rect.width > 0 && rect.height > 0)) {
         return errorText(`Element ${JSON.stringify(selector)} has a zero-size box; nothing to capture.`);
       }
       params.clip = { x: rect.x, y: rect.y, width: rect.width, height: rect.height, scale: 1 };
+      caption = import_common_tags3.oneLine`
+        Clipped to ${JSON.stringify(selector)} [index ${index}]. Matches: ${rect.count}.
+      `;
     }
     const res = await client.call("Page.captureScreenshot", params);
     if (!res?.data) {
-      return errorText("Page.captureScreenshot returned no image data.");
+      return errorText(`Page.captureScreenshot returned no image data.`);
     }
-    return {
-      content: [
-        { type: "image", data: res.data, mimeType: format == "jpeg" ? "image/jpeg" : "image/png" }
-      ]
+    const image = {
+      type: "image",
+      data: res.data,
+      mimeType: format == "jpeg" ? "image/jpeg" : "image/png"
     };
+    return { content: caption ? [{ type: "text", text: caption }, image] : [image] };
   } catch (error51) {
     return toErrorResult(error51);
   }
@@ -31300,6 +31136,44 @@ async function gameDom(client, selector, all = false, maxHtml = 4000) {
     return toErrorResult(error51);
   }
 }
+async function gameFind(client, options) {
+  const {
+    text: needle,
+    match = "contains",
+    caseSensitive = false,
+    selector = "*",
+    deepest = true,
+    tag = false,
+    limit = DEFAULT_FIND_LIMIT
+  } = options;
+  try {
+    const res = await client.call("Runtime.evaluate", {
+      expression: callPageFn(findFn, {
+        sel: selector,
+        needle,
+        mode: match,
+        caseSensitive,
+        deepest,
+        tag,
+        limit
+      }),
+      returnByValue: true
+    });
+    if (res.exceptionDetails) {
+      return errorText(`Find failed: ${formatException(res.exceptionDetails)}`);
+    }
+    const value = res.result.value;
+    if (!value) {
+      return errorText(`game_find returned no result for selector ${JSON.stringify(selector)}.`);
+    }
+    if ("error" in value) {
+      return errorText(`game_find: ${value.error}`);
+    }
+    return text(JSON.stringify({ selector, match, ...value }, null, 2));
+  } catch (error51) {
+    return toErrorResult(error51);
+  }
+}
 async function gameClick(client, selector, index = 0) {
   try {
     const res = await client.call("Runtime.evaluate", {
@@ -31325,18 +31199,74 @@ async function gameClick(client, selector, index = 0) {
     return toErrorResult(error51);
   }
 }
-async function gameWait(client, options) {
-  const { selector, predicate, timeoutMs = DEFAULT_WAIT_TIMEOUT_MS, visible = false } = options;
-  if (!selector && !predicate) {
-    return errorText("game_wait needs either 'selector' or 'predicate'.");
+async function gameWait(client, reloads, options) {
+  const {
+    selector,
+    predicate,
+    reload = false,
+    sinceReloads,
+    quiescentMs = DEFAULT_QUIESCENT_MS,
+    visible = false
+  } = options;
+  if (!reload && !selector && !predicate) {
+    return errorText(`game_wait needs at least one of 'reload', 'selector', or 'predicate'.`);
   }
+  if (selector && predicate) {
+    return errorText(`game_wait takes either 'selector' or 'predicate', not both.`);
+  }
+  const timeoutMs = options.timeoutMs ?? (reload ? DEFAULT_RELOAD_WAIT_TIMEOUT_MS : DEFAULT_WAIT_TIMEOUT_MS);
   const budget = Math.min(Math.max(timeoutMs, 0), MAX_WAIT_MS);
-  const deadline = Date.now() + budget;
   const start = Date.now();
-  const expression = selector ? callPageFn(waitCheckFn, selector, visible) : `Boolean(${predicate ?? ""})`;
-  let lastError;
+  const deadline = start + budget;
   try {
-    for (;; ) {
+    if (reload) {
+      const failed = await waitForReload();
+      if (failed) {
+        return failed;
+      }
+      if (!selector && !predicate) {
+        return text(`Reload observed after ${Date.now() - start}ms (reload count: ${reloads.count}).`);
+      }
+    }
+    return await pollCondition();
+  } catch (error51) {
+    return toErrorResult(error51);
+  }
+  async function waitForReload() {
+    await client.connection();
+    const baseline = sinceReloads ?? reloads.count;
+    while (reloads.count <= baseline) {
+      if (Date.now() >= deadline) {
+        return errorText(import_common_tags3.oneLine`
+          Timed out after ${budget}ms waiting for a view reload
+          (reload count still ${reloads.count}, baseline ${baseline}).
+        `);
+      }
+      await sleep2(POLL_INTERVAL_MS2);
+    }
+    if (quiescentMs > 0) {
+      let lastCount = reloads.count;
+      let quietSince = Date.now();
+      while (Date.now() - quietSince < quiescentMs) {
+        if (Date.now() >= deadline) {
+          return errorText(import_common_tags3.oneLine`
+            Timed out after ${budget}ms: reload observed, but context swaps kept arriving within the
+            ${quiescentMs}ms quiescence window.
+          `);
+        }
+        await sleep2(POLL_INTERVAL_MS2);
+        if (reloads.count != lastCount) {
+          lastCount = reloads.count;
+          quietSince = Date.now();
+        }
+      }
+    }
+    return;
+  }
+  async function pollCondition() {
+    const expression = selector ? callPageFn(waitCheckFn, selector, visible) : `Boolean(${predicate ?? ""})`;
+    let lastError;
+    while (true) {
       const res = await client.call("Runtime.evaluate", {
         expression,
         returnByValue: true
@@ -31345,7 +31275,8 @@ async function gameWait(client, options) {
         lastError = formatException(res.exceptionDetails);
       } else if (res.result.value) {
         const what = selector ? `selector ${JSON.stringify(selector)}` : "predicate";
-        return text(`Condition met (${what}) after ${Date.now() - start}ms.`);
+        const reloadNote = reload ? ` Reload count: ${reloads.count}.` : "";
+        return text(`Condition met (${what}) after ${Date.now() - start}ms.${reloadNote}`);
       } else {
         lastError = undefined;
       }
@@ -31356,14 +31287,12 @@ async function gameWait(client, options) {
       }
       await sleep2(POLL_INTERVAL_MS2);
     }
-  } catch (error51) {
-    return toErrorResult(error51);
   }
 }
-async function gameFill(client, selector, value) {
+async function gameFill(client, selector, value, index = 0) {
   try {
     const res = await client.call("Runtime.evaluate", {
-      expression: callPageFn(fillFn, selector, value),
+      expression: callPageFn(fillFn, selector, value, index),
       returnByValue: true
     });
     if (res.exceptionDetails) {
@@ -31371,20 +31300,23 @@ async function gameFill(client, selector, value) {
     }
     const info = res.result.value;
     if (!info?.found) {
-      return errorText(`No element matched ${JSON.stringify(selector)} for game_fill.`);
+      return errorText(import_common_tags3.oneLine`
+        No element matched ${JSON.stringify(selector)} for game_fill at index ${index}
+        (matches found: ${info?.count ?? 0}).
+      `);
     }
     return text(import_common_tags3.oneLine`
-      Filled ${JSON.stringify(selector)} (${info.mode}).
-      Value is now ${JSON.stringify(info.value)}.
+      Filled ${JSON.stringify(selector)} [index ${index}] (${info.mode}).
+      Value is now ${JSON.stringify(info.value)}. Matches: ${info.count}.
     `);
   } catch (error51) {
     return toErrorResult(error51);
   }
 }
-async function gameType(client, selector, textToType) {
+async function gameType(client, selector, textToType, index = 0) {
   try {
     const res = await client.call("Runtime.evaluate", {
-      expression: callPageFn(typeFn, selector, textToType),
+      expression: callPageFn(typeFn, selector, textToType, index),
       returnByValue: true
     });
     if (res.exceptionDetails) {
@@ -31392,20 +31324,23 @@ async function gameType(client, selector, textToType) {
     }
     const info = res.result.value;
     if (!info?.found) {
-      return errorText(`No element matched ${JSON.stringify(selector)} for game_type.`);
+      return errorText(import_common_tags3.oneLine`
+        No element matched ${JSON.stringify(selector)} for game_type at index ${index}
+        (matches found: ${info?.count ?? 0}).
+      `);
     }
     return text(import_common_tags3.oneLine`
-      Typed ${info.typed} char(s) into ${JSON.stringify(selector)}.
-      Value is now ${JSON.stringify(info.value)}.
+      Typed ${info.typed} char(s) into ${JSON.stringify(selector)} [index ${index}].
+      Value is now ${JSON.stringify(info.value)}. Matches: ${info.count}.
     `);
   } catch (error51) {
     return toErrorResult(error51);
   }
 }
-async function gameHover(client, selector) {
+async function gameHover(client, selector, index = 0) {
   try {
     const res = await client.call("Runtime.evaluate", {
-      expression: callPageFn(hoverFn, selector),
+      expression: callPageFn(hoverFn, selector, index),
       returnByValue: true
     });
     if (res.exceptionDetails) {
@@ -31413,31 +31348,160 @@ async function gameHover(client, selector) {
     }
     const info = res.result.value;
     if (!info?.found) {
-      return errorText(`No element matched ${JSON.stringify(selector)} for game_hover.`);
+      return errorText(import_common_tags3.oneLine`
+        No element matched ${JSON.stringify(selector)} for game_hover at index ${index}
+        (matches found: ${info?.count ?? 0}).
+      `);
+    }
+    return text(import_common_tags3.oneLine`
+      Hovered ${JSON.stringify(selector)} [index ${index}] at
+      (${info.x.toFixed(0)}, ${info.y.toFixed(0)}).
+      Dispatched: ${info.fired.join(", ")}. Matches: ${info.count}.
+    `);
+  } catch (error51) {
+    return toErrorResult(error51);
+  }
+}
+async function gameKey(client, options) {
+  const {
+    key,
+    count = 1,
+    ctrl = false,
+    shift = false,
+    alt = false,
+    meta: meta3 = false,
+    selector,
+    index = 0
+  } = options;
+  try {
+    const res = await client.call("Runtime.evaluate", {
+      expression: callPageFn(keyFn, {
+        key,
+        count,
+        ctrl,
+        shift,
+        alt,
+        meta: meta3,
+        sel: selector ?? null,
+        index
+      }),
+      returnByValue: true
+    });
+    if (res.exceptionDetails) {
+      return errorText(`Key press failed: ${formatException(res.exceptionDetails)}`);
+    }
+    const info = res.result.value;
+    if (!info) {
+      return errorText(`game_key returned no result.`);
+    }
+    if (!info.found) {
+      return errorText(import_common_tags3.oneLine`
+        No element matched ${JSON.stringify(selector)} for game_key at index ${index}
+        (matches found: ${info.count}).
+      `);
     }
+    const where = info.via == "selector" ? `${JSON.stringify(selector)} [index ${index}] ${info.target}` : info.via == "activeElement" ? `the focused element ${info.target}` : `document`;
+    const matchNote = info.matches == null ? "" : ` Matches: ${info.matches}.`;
     return text(import_common_tags3.oneLine`
-      Hovered ${JSON.stringify(selector)} at (${info.x.toFixed(0)}, ${info.y.toFixed(0)}).
-      Dispatched: ${info.fired.join(", ")}.
+      Pressed ${keyLabel(key, { ctrl, shift, alt, meta: meta3 })} ${info.presses}x on ${where}.${matchNote}
+      Default prevented: ${info.defaultPrevented ? "yes" : "no"}.
     `);
   } catch (error51) {
     return toErrorResult(error51);
   }
 }
+function keyLabel(key, mods) {
+  const parts = [];
+  if (mods.ctrl) {
+    parts.push("Ctrl");
+  }
+  if (mods.shift) {
+    parts.push("Shift");
+  }
+  if (mods.alt) {
+    parts.push("Alt");
+  }
+  if (mods.meta) {
+    parts.push("Meta");
+  }
+  parts.push(key == " " ? "Space" : key);
+  return parts.join("+");
+}
 
-class ConsoleBuffer {
-  entries = [];
-  max;
-  constructor(client, max = 500) {
-    this.max = max;
+class ReloadTracker {
+  reloadCount = 0;
+  lastReloadAtMs;
+  uniqueId;
+  reloadListeners = new Set;
+  constructor(client) {
     client.onConnect(async (conn) => {
       await conn.ensureDomain("Runtime");
-      await conn.ensureDomain("Log");
     });
     client.onEvent((method, params) => {
       this.handle(method, params);
     });
   }
-  read(limit, level, clear) {
+  get count() {
+    return this.reloadCount;
+  }
+  get lastReloadAt() {
+    return this.lastReloadAtMs;
+  }
+  get contextUniqueId() {
+    return this.uniqueId;
+  }
+  onReload(listener) {
+    this.reloadListeners.add(listener);
+  }
+  handle(method, params) {
+    if (method != "Runtime.executionContextCreated") {
+      return;
+    }
+    const { context } = params;
+    const isDefault = context?.auxData?.isDefault;
+    if (!(isDefault == true || isDefault == "true") || context?.uniqueId == null) {
+      return;
+    }
+    if (this.uniqueId == context.uniqueId) {
+      return;
+    }
+    const isBaseline = this.uniqueId == null;
+    this.uniqueId = context.uniqueId;
+    if (isBaseline) {
+      return;
+    }
+    this.reloadCount++;
+    this.lastReloadAtMs = Date.now();
+    for (const listener of this.reloadListeners) {
+      try {
+        listener(this.reloadCount);
+      } catch {}
+    }
+  }
+}
+
+class ConsoleBuffer {
+  entries = [];
+  max;
+  constructor(client, reloads, max = 500) {
+    this.max = max;
+    client.onConnect(async (conn) => {
+      await conn.ensureDomain("Runtime");
+      await conn.ensureDomain("Log");
+    });
+    client.onEvent((method, params) => {
+      this.handle(method, params);
+    });
+    reloads.onReload((count) => {
+      this.push({
+        ts: Date.now(),
+        kind: "reload",
+        level: "info",
+        text: `view reloaded (#${count})`
+      });
+    });
+  }
+  read(limit, level, clear) {
     const filtered = level ? this.entries.filter((entry) => entry.level == level) : this.entries;
     const out = filtered.slice(-limit);
     if (clear) {
@@ -31496,214 +31560,733 @@ async function gameConsole(client, buffer, options) {
   return text(entries.map((entry) => `[${entry.level}] (${entry.kind}) ${entry.text}`).join(`
 `));
 }
+function callPageFn(fn, ...args) {
+  const serialisedArgs = args.map((arg) => JSON.stringify(arg)).join(", ");
+  return `(${fn.toString()})(${serialisedArgs})`;
+}
+function collectDomFn(sel, all, maxHtml) {
+  const matches = document.querySelectorAll(sel);
+  const first = matches.item(0);
+  const chosen = all ? Array.from(matches) : first ? [first] : [];
+  return { count: matches.length, elements: chosen.map((el) => describe3(el)) };
+  function describe3(el) {
+    const rect = el.getBoundingClientRect();
+    const attributes = {};
+    for (const attr of Array.from(el.attributes)) {
+      attributes[attr.name] = attr.value;
+    }
+    const classAttr = el.getAttribute("class");
+    let html = el.outerHTML || "";
+    const truncated = html.length > maxHtml;
+    if (truncated) {
+      html = html.slice(0, maxHtml);
+    }
+    return {
+      tagName: el.tagName ? el.tagName.toLowerCase() : null,
+      id: el.id || null,
+      classes: classAttr != null && classAttr.length > 0 ? classAttr : null,
+      rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+      attributes,
+      outerHTML: html,
+      truncated
+    };
+  }
+}
+function findFn(args) {
+  const { sel, needle, mode, caseSensitive, deepest, tag, limit } = args;
+  const SNIPPET_MAX = 100;
+  const target = caseSensitive ? needle : needle.toLowerCase();
+  let regex;
+  if (mode == "regex") {
+    try {
+      regex = new RegExp(needle, caseSensitive ? "" : "i");
+    } catch (error51) {
+      return { error: `Invalid regex: ${error51 instanceof Error ? error51.message : String(error51)}` };
+    }
+  }
+  const found = [];
+  for (const el of Array.from(document.querySelectorAll(sel))) {
+    if (matches((el.textContent || "").trim())) {
+      found.push(el);
+    }
+  }
+  const kept = deepest ? found.filter((el) => !found.some((other) => other != el && el.contains(other))) : found;
+  const chosen = kept.slice(0, limit);
+  if (tag) {
+    for (const stale of Array.from(document.querySelectorAll("[data-gf-find]"))) {
+      stale.removeAttribute("data-gf-find");
+    }
+    for (const [i, el] of chosen.entries()) {
+      el.setAttribute("data-gf-find", String(i + 1));
+    }
+  }
+  return {
+    unprunedTotal: found.length,
+    total: kept.length,
+    returned: chosen.length,
+    tagged: tag,
+    elements: chosen.map((el, i) => describe3(el, i))
+  };
+  function matches(raw) {
+    if (mode == "regex") {
+      return regex != null && regex.test(raw);
+    }
+    const hay = caseSensitive ? raw : raw.toLowerCase();
+    if (mode == "equals") {
+      return hay == target;
+    }
+    return hay.includes(target);
+  }
+  function describe3(el, i) {
+    const rect = el.getBoundingClientRect();
+    const classAttr = el.getAttribute("class");
+    const raw = (el.textContent || "").trim();
+    const truncated = raw.length > SNIPPET_MAX;
+    const info = {
+      tagName: el.tagName ? el.tagName.toLowerCase() : null,
+      id: el.id || null,
+      classes: classAttr != null && classAttr.length > 0 ? classAttr : null,
+      rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
+      text: truncated ? raw.slice(0, SNIPPET_MAX) : raw,
+      truncated
+    };
+    if (tag) {
+      info.selector = `[data-gf-find="${i + 1}"]`;
+    }
+    return info;
+  }
+}
+function clickFn(sel, index) {
+  const nodes = document.querySelectorAll(sel);
+  if (nodes.length == 0) {
+    return { found: false, count: 0, fired: [] };
+  }
+  const node = nodes[index];
+  if (!node) {
+    return { found: false, count: nodes.length, fired: [] };
+  }
+  const el = node;
+  const rect = el.getBoundingClientRect();
+  const cx = rect.x + rect.width / 2;
+  const cy = rect.y + rect.height / 2;
+  const base = {
+    bubbles: true,
+    cancelable: true,
+    view: window,
+    button: 0,
+    clientX: cx,
+    clientY: cy
+  };
+  const Pointer = typeof PointerEvent == "function" ? PointerEvent : MouseEvent;
+  const fired = [];
+  fire(Pointer, "pointerdown", { pointerId: 1, isPrimary: true });
+  fire(MouseEvent, "mousedown");
+  fire(Pointer, "pointerup", { pointerId: 1, isPrimary: true });
+  fire(MouseEvent, "mouseup");
+  fire(MouseEvent, "click");
+  return { found: true, count: nodes.length, x: cx, y: cy, fired };
+  function fire(Ctor, type, extra) {
+    try {
+      el.dispatchEvent(new Ctor(type, { ...base, ...extra }));
+      fired.push(type);
+    } catch {}
+  }
+}
+function waitCheckFn(sel, visible) {
+  const el = document.querySelector(sel);
+  if (!el) {
+    return false;
+  }
+  if (!visible) {
+    return true;
+  }
+  const rect = el.getBoundingClientRect();
+  return rect.width > 0 && rect.height > 0;
+}
+function fillFn(sel, value, index) {
+  const nodes = document.querySelectorAll(sel);
+  if (nodes.length == 0) {
+    return { found: false, count: 0 };
+  }
+  const node = nodes[index];
+  if (!node) {
+    return { found: false, count: nodes.length };
+  }
+  const el = node;
+  const count = nodes.length;
+  try {
+    el.focus();
+  } catch {}
+  const tag = (el.tagName || "").toLowerCase();
+  if (el.isContentEditable) {
+    el.textContent = value;
+    el.dispatchEvent(new Event("input", { bubbles: true }));
+    el.dispatchEvent(new Event("change", { bubbles: true }));
+    return { found: true, count, mode: "contenteditable", value: el.textContent ?? "" };
+  }
+  const field = el;
+  const proto = tag == "textarea" ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+  const setter = Object.getOwnPropertyDescriptor(proto, "value")?.set;
+  if (setter) {
+    setter.call(el, value);
+  } else {
+    field.value = value;
+  }
+  el.dispatchEvent(new Event("input", { bubbles: true }));
+  el.dispatchEvent(new Event("change", { bubbles: true }));
+  return { found: true, count, mode: tag || "input", value: field.value };
+}
+function typeFn(sel, textToType, index) {
+  const nodes = document.querySelectorAll(sel);
+  if (nodes.length == 0) {
+    return { found: false, count: 0, typed: 0 };
+  }
+  const node = nodes[index];
+  if (!node) {
+    return { found: false, count: nodes.length, typed: 0 };
+  }
+  const el = node;
+  const count = nodes.length;
+  try {
+    el.focus();
+  } catch {}
+  const tag = (el.tagName || "").toLowerCase();
+  const editable = el.isContentEditable;
+  const field = el;
+  const proto = tag == "textarea" ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+  const setter = Object.getOwnPropertyDescriptor(proto, "value")?.set;
+  let typed = 0;
+  for (const ch of textToType) {
+    const opts = {
+      bubbles: true,
+      cancelable: true,
+      key: ch,
+      view: window
+    };
+    try {
+      el.dispatchEvent(new KeyboardEvent("keydown", opts));
+    } catch {}
+    setValue(current() + ch);
+    el.dispatchEvent(new Event("input", { bubbles: true }));
+    try {
+      el.dispatchEvent(new KeyboardEvent("keyup", opts));
+    } catch {}
+    typed++;
+  }
+  el.dispatchEvent(new Event("change", { bubbles: true }));
+  return { found: true, count, typed, value: current() };
+  function current() {
+    if (editable) {
+      return el.textContent ?? "";
+    }
+    return field.value || "";
+  }
+  function setValue(next) {
+    if (editable) {
+      el.textContent = next;
+    } else if (setter) {
+      setter.call(el, next);
+    } else {
+      field.value = next;
+    }
+  }
+}
+function hoverFn(sel, index) {
+  const nodes = document.querySelectorAll(sel);
+  if (nodes.length == 0) {
+    return { found: false, count: 0 };
+  }
+  const node = nodes[index];
+  if (!node) {
+    return { found: false, count: nodes.length };
+  }
+  const el = node;
+  const count = nodes.length;
+  const rect = el.getBoundingClientRect();
+  const cx = rect.x + rect.width / 2;
+  const cy = rect.y + rect.height / 2;
+  const base = {
+    bubbles: true,
+    cancelable: true,
+    view: window,
+    clientX: cx,
+    clientY: cy
+  };
+  const noBubble = { ...base, bubbles: false };
+  const fired = [];
+  fire("pointerover", base);
+  fire("mouseover", base);
+  fire("pointerenter", noBubble);
+  fire("mouseenter", noBubble);
+  fire("mousemove", base);
+  return { found: true, count, x: cx, y: cy, fired };
+  function fire(type, init) {
+    try {
+      el.dispatchEvent(new MouseEvent(type, init));
+      fired.push(type);
+    } catch {}
+  }
+}
+function keyFn(args) {
+  const { key, count, ctrl, shift, alt, meta: meta3, sel, index } = args;
+  let target;
+  let via;
+  let node = null;
+  let matches = null;
+  if (sel == null) {
+    const active = document.activeElement;
+    if (active) {
+      target = active;
+      node = active;
+      via = "activeElement";
+    } else {
+      target = document.body || document;
+      node = document.body;
+      via = "document";
+    }
+  } else {
+    const nodes = document.querySelectorAll(sel);
+    if (nodes.length == 0) {
+      return { found: false, count: 0 };
+    }
+    const chosen = nodes[index];
+    if (!chosen) {
+      return { found: false, count: nodes.length };
+    }
+    try {
+      chosen.focus();
+    } catch {}
+    target = chosen;
+    node = chosen;
+    matches = nodes.length;
+    via = "selector";
+  }
+  const map3 = codeFor(key);
+  const init = {
+    bubbles: true,
+    cancelable: true,
+    view: window,
+    key,
+    ctrlKey: ctrl,
+    shiftKey: shift,
+    altKey: alt,
+    metaKey: meta3
+  };
+  if (map3) {
+    init.code = map3.code;
+  }
+  let defaultPrevented = false;
+  let presses = 0;
+  for (let i = 0;i < count; i++) {
+    if (dispatch("keydown")) {
+      defaultPrevented = true;
+    }
+    dispatch("keyup");
+    presses++;
+  }
+  return {
+    found: true,
+    via,
+    target: node ? describe3(node) : "document",
+    matches,
+    presses,
+    defaultPrevented
+  };
+  function dispatch(type) {
+    try {
+      const ev = new KeyboardEvent(type, init);
+      force(ev, "key", key);
+      if (map3) {
+        force(ev, "code", map3.code);
+        force(ev, "keyCode", map3.keyCode);
+        force(ev, "which", map3.keyCode);
+      }
+      const notPrevented = target.dispatchEvent(ev);
+      return type == "keydown" && !notPrevented;
+    } catch {
+      return false;
+    }
+  }
+  function force(ev, prop, value) {
+    try {
+      Object.defineProperty(ev, prop, { get: () => value, configurable: true });
+    } catch {}
+  }
+  function codeFor(name) {
+    const table = {
+      Escape: { code: "Escape", keyCode: 27 },
+      Enter: { code: "Enter", keyCode: 13 },
+      Tab: { code: "Tab", keyCode: 9 },
+      " ": { code: "Space", keyCode: 32 },
+      Backspace: { code: "Backspace", keyCode: 8 },
+      Delete: { code: "Delete", keyCode: 46 },
+      Home: { code: "Home", keyCode: 36 },
+      End: { code: "End", keyCode: 35 },
+      PageUp: { code: "PageUp", keyCode: 33 },
+      PageDown: { code: "PageDown", keyCode: 34 },
+      ArrowUp: { code: "ArrowUp", keyCode: 38 },
+      ArrowDown: { code: "ArrowDown", keyCode: 40 },
+      ArrowLeft: { code: "ArrowLeft", keyCode: 37 },
+      ArrowRight: { code: "ArrowRight", keyCode: 39 }
+    };
+    const known = table[name];
+    if (known) {
+      return known;
+    }
+    const F1_KEY_CODE = 112;
+    const fn = /^F(?<num>[1-9]|1[0-2])$/u.exec(name);
+    if (fn) {
+      const num2 = Number(fn.groups?.num);
+      return { code: `F${num2}`, keyCode: F1_KEY_CODE + num2 - 1 };
+    }
+    if (/^[a-zA-Z]$/u.test(name)) {
+      const upper = name.toUpperCase();
+      return { code: `Key${upper}`, keyCode: upper.codePointAt(0) ?? 0 };
+    }
+    if (/^[0-9]$/u.test(name)) {
+      return { code: `Digit${name}`, keyCode: name.codePointAt(0) ?? 0 };
+    }
+    return;
+  }
+  function describe3(el) {
+    const tag = el.tagName ? el.tagName.toLowerCase() : "node";
+    const id = el.id ? `#${el.id}` : "";
+    const classAttr = el.getAttribute("class");
+    const cls = classAttr && classAttr.trim() ? `.${classAttr.trim().split(/\s+/u)[0]}` : "";
+    return `<${tag}${id}${cls}>`;
+  }
+}
+function rectFn(sel, index) {
+  const nodes = document.querySelectorAll(sel);
+  if (nodes.length == 0) {
+    return { found: false, count: 0 };
+  }
+  const el = nodes[index];
+  if (!el) {
+    return { found: false, count: nodes.length };
+  }
+  const rect = el.getBoundingClientRect();
+  return {
+    found: true,
+    count: nodes.length,
+    x: rect.x,
+    y: rect.y,
+    width: rect.width,
+    height: rect.height
+  };
+}
 
 // src/server.ts
 var { version: VERSION } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 async function main() {
   const config2 = loadConfig();
   const client = new CdpClient(config2);
-  const consoleBuffer = new ConsoleBuffer(client);
-  const debug = new DebuggerSession(client);
+  const reloads = new ReloadTracker(client);
+  const consoleBuffer = new ConsoleBuffer(client, reloads);
+  const debug = new DebuggerSession(client, reloads);
   const server = new McpServer({ name: "gameface-devtools-mcp", version: VERSION });
   server.registerTool("game_status", {
-    title: "Gameface UI status",
+    title: `Gameface UI status`,
     description: import_common_tags4.oneLine`
-        Check whether the Gameface UI debug endpoint is reachable and report the live page
-        target and engine info. Run this first when other game_* tools fail.
+        Check whether the Gameface UI debug endpoint is reachable and report the live page target,
+        engine info, and view-reload tracking (count, last reload time, context id).
+        Calling it arms reload tracking and returns the baseline count for game_wait's sinceReloads.
+        Run this first when other game_* tools fail.
       `
-  }, () => gameStatus(client));
+  }, () => gameStatus(client, reloads));
   server.registerTool("game_eval", {
-    title: "Evaluate JS in the Gameface UI",
+    title: `Evaluate JS in the Gameface UI`,
     description: import_common_tags4.oneLine`
         Evaluate a JavaScript expression in the running Gameface UI (CDP Runtime.evaluate,
-        returnByValue) and return the resulting value as JSON. Use document.querySelector and
-        friends to read the live DOM, inspect React state, or call UI APIs.
+        returnByValue) and return the resulting value as JSON.
+        Use document.querySelector and friends to read the live DOM, inspect state, or call UI APIs.
       `,
     inputSchema: {
-      expression: exports_external.string().describe("JavaScript expression to evaluate in the page context"),
-      awaitPromise: exports_external.boolean().optional().describe("If the expression returns a Promise, await it before returning")
+      expression: exports_external.string().describe(`JavaScript expression to evaluate in the page context`),
+      awaitPromise: exports_external.boolean().optional().describe(`If the expression returns a Promise, await it before returning`)
     }
   }, ({ expression, awaitPromise }) => gameEval(client, expression, awaitPromise));
   server.registerTool("game_screenshot", {
-    title: "Screenshot the Gameface UI",
+    title: `Screenshot the Gameface UI`,
     description: import_common_tags4.oneLine`
         Capture a screenshot of the Gameface viewport (CDP Page.captureScreenshot) and return it
-        as an inline image. Pass a selector to clip the capture to one element. Use jpeg with a
-        lower quality to reduce payload size.
+        as an inline image.
+        Pass a selector to clip the capture to one element; use index to pick among matches.
+        Hangs while the JS debugger is paused; resume (game_debug_step) before capturing.
       `,
     inputSchema: {
-      format: exports_external.enum(["png", "jpeg"]).optional().describe("Image format (default: png)"),
-      quality: exports_external.number().min(1).max(100).optional().describe("JPEG quality 1-100 (only used when format is jpeg; default 80)"),
-      selector: exports_external.string().optional().describe("If set, clip the screenshot to this element's bounding box")
+      format: exports_external.enum(["png", "jpeg"]).optional().describe(`Image format (default: jpeg)`),
+      quality: exports_external.number().min(1).max(100).optional().describe(`JPEG quality 1-100 (only used when format is jpeg; default 80)`),
+      selector: exports_external.string().optional().describe(`If set, clip the screenshot to this element's bounding box`),
+      index: exports_external.number().int().min(0).optional().describe(`Which match to clip to when several exist (default: 0)`)
     }
-  }, ({ format, quality, selector }) => gameScreenshot(client, format, quality, selector));
+  }, ({ format, quality, selector, index }) => gameScreenshot(client, { format, quality, selector, index }));
   server.registerTool("game_wait", {
-    title: "Wait for a condition in the Gameface UI",
+    title: `Wait for a condition in the Gameface UI`,
     description: import_common_tags4.oneLine`
-        Wait until a CSS selector matches (optionally visible) or a JS predicate becomes truthy,
-        polling the page. Provide exactly one of selector / predicate. Returns when met or times
-        out.
+        Wait until a CSS selector matches (optionally visible), a JS predicate becomes truthy,
+        and/or a view reload happens. Provide at least one of reload / selector / predicate
+        (selector and predicate are mutually exclusive).
+        With reload, the phases compose: reload first, then a quiescence window, then the
+        selector/predicate poll in the fresh context.
+        Returns when met or times out.
       `,
     inputSchema: {
-      selector: exports_external.string().optional().describe("CSS selector to wait for"),
-      predicate: exports_external.string().optional().describe("JS expression evaluated in the page; waits until it is truthy"),
-      timeoutMs: exports_external.number().int().min(0).optional().describe("Max time to wait in ms (default 8000, capped at 60000)"),
-      visible: exports_external.boolean().optional().describe("For selector waits, also require a non-zero bounding box (default false)")
-    }
-  }, ({ selector, predicate, timeoutMs, visible }) => gameWait(client, { selector, predicate, timeoutMs, visible }));
+      selector: exports_external.string().optional().describe(`CSS selector to wait for`),
+      predicate: exports_external.string().optional().describe(`JS expression evaluated in the page; waits until it is truthy`),
+      reload: exports_external.boolean().optional().describe(import_common_tags4.oneLine`
+            Wait for a view reload (context reset) before the selector/predicate phase.
+            Without sinceReloads, waits for the next reload after the call starts.
+          `),
+      sinceReloads: exports_external.number().int().min(0).optional().describe(import_common_tags4.oneLine`
+            Baseline reload count (from a prior game_status or game_wait).
+            The reload phase is satisfied as soon as the count exceeds it, even if the reload
+            already happened; use it to avoid racing a reload you triggered yourself.
+          `),
+      quiescentMs: exports_external.number().int().min(0).optional().describe(import_common_tags4.oneLine`
+            After a reload is observed, hold until no further context swap for this long (default
+            1000, 0 disables); absorbs engines that swap the context several times per reload.
+          `),
+      timeoutMs: exports_external.number().int().min(0).optional().describe(import_common_tags4.oneLine`
+            Max time to wait in ms (default 8000, or 30000 when reload is set; capped at 60000)
+          `),
+      visible: exports_external.boolean().optional().describe(`For selector waits, also require a non-zero bounding box (default false)`)
+    }
+  }, ({ selector, predicate, reload, sinceReloads, quiescentMs, timeoutMs, visible }) => gameWait(client, reloads, {
+    selector,
+    predicate,
+    reload,
+    sinceReloads,
+    quiescentMs,
+    timeoutMs,
+    visible
+  }));
   server.registerTool("game_fill", {
-    title: "Set an input value in the Gameface UI",
+    title: `Set an input value in the Gameface UI`,
     description: import_common_tags4.oneLine`
         Set the value of an input, textarea, or contenteditable element and fire input/change so
-        React's onChange runs. Best for setting a field in one shot; use game_type for keystrokes.
+        the UI framework reacts as if the user edited it.
+        Best for setting a field in one shot; use game_type for keystrokes.
+        Use index to pick among matches.
       `,
     inputSchema: {
-      selector: exports_external.string().describe("CSS selector of the field to fill"),
-      value: exports_external.string().describe("Value to set")
+      selector: exports_external.string().describe(`CSS selector of the field to fill`),
+      value: exports_external.string().describe(`Value to set`),
+      index: exports_external.number().int().min(0).optional().describe(`Which match to fill when several exist (default: 0)`)
     }
-  }, ({ selector, value }) => gameFill(client, selector, value));
+  }, ({ selector, value, index }) => gameFill(client, selector, value, index));
   server.registerTool("game_type", {
-    title: "Type text into the Gameface UI",
+    title: `Type text into the Gameface UI`,
     description: import_common_tags4.oneLine`
         Type text into an element character by character, firing real KeyboardEvents plus keeping
-        the value in sync. Use when handlers react to individual keystrokes; otherwise game_fill.
+        the value in sync.
+        Use when handlers react to individual keystrokes; otherwise game_fill.
+        Use index to pick among matches.
       `,
     inputSchema: {
-      selector: exports_external.string().describe("CSS selector of the field to type into"),
-      text: exports_external.string().describe("Text to type")
+      selector: exports_external.string().describe(`CSS selector of the field to type into`),
+      text: exports_external.string().describe(`Text to type`),
+      index: exports_external.number().int().min(0).optional().describe(`Which match to type into when several exist (default: 0)`)
     }
-  }, ({ selector, text: text2 }) => gameType(client, selector, text2));
+  }, ({ selector, text: text2, index }) => gameType(client, selector, text2, index));
   server.registerTool("game_hover", {
-    title: "Hover an element in the Gameface UI",
+    title: `Hover an element in the Gameface UI`,
     description: import_common_tags4.oneLine`
         Hover an element by dispatching the pointer/mouse over/enter/move sequence in the page, so
-        React onMouseEnter / onPointerOver handlers (tooltips, hover states) fire.
+        the UI's mouseenter / pointerover JS handlers (tooltips) fire.
+        The CSS :hover state is NOT set (only real game-forwarded mouse input sets it); verify a
+        hover by its DOM effect, never by styling.
+        Use index to pick among matches.
       `,
     inputSchema: {
-      selector: exports_external.string().describe("CSS selector of the element to hover")
+      selector: exports_external.string().describe(`CSS selector of the element to hover`),
+      index: exports_external.number().int().min(0).optional().describe(`Which match to hover when several exist (default: 0)`)
     }
-  }, ({ selector }) => gameHover(client, selector));
+  }, ({ selector, index }) => gameHover(client, selector, index));
+  server.registerTool("game_key", {
+    title: `Press a key in the Gameface UI`,
+    description: import_common_tags4.oneLine`
+        Press a named key by dispatching a real bubbling keydown+keyup in the page
+        (KeyboardEvent.key, e.g. Escape, Enter, ArrowDown, a, F5), optionally with
+        ctrl/shift/alt/meta and a repeat count.
+        With a selector it focuses that element and dispatches on it (index picks among matches);
+        without one it dispatches on the focused element, else document.
+        It fires ONLY keydown and keyup (no keypress) and performs NO default action: no character
+        insertion, no Backspace delete, no Tab focus move, no scrolling; use game_type to enter
+        text.
+        It reaches the UI's JS keydown handlers, but keys the game routes through its own native
+        input layer do NOT respond (e.g. an Escape-to-close handled by the engine rather than the
+        DOM).
+        The result reports whether a handler called preventDefault, the observable signal the key
+        was consumed.
+      `,
+    inputSchema: {
+      key: exports_external.string().describe(`KeyboardEvent.key name to press, e.g. Escape, Enter, ArrowDown, a, F5`),
+      count: exports_external.number().int().min(1).max(100).optional().describe(`How many keydown+keyup presses to fire back-to-back (default 1)`),
+      ctrl: exports_external.boolean().optional().describe(`Hold Ctrl (ctrlKey) during the press (default false)`),
+      shift: exports_external.boolean().optional().describe(`Hold Shift (shiftKey) during the press (default false)`),
+      alt: exports_external.boolean().optional().describe(`Hold Alt (altKey) during the press (default false)`),
+      meta: exports_external.boolean().optional().describe(`Hold Meta / Win / Cmd (metaKey) during the press (default false)`),
+      selector: exports_external.string().optional().describe(`If set, focus this element and dispatch on it; else the focused element`),
+      index: exports_external.number().int().min(0).optional().describe(`Which match to target when the selector has several (default: 0)`)
+    }
+  }, ({ key, count, ctrl, shift, alt, meta: meta3, selector, index }) => gameKey(client, { key, count, ctrl, shift, alt, meta: meta3, selector, index }));
   server.registerTool("game_console", {
-    title: "Read the Gameface UI console",
+    title: `Read the Gameface UI console`,
     description: import_common_tags4.oneLine`
         Return recent console.* calls, log entries, and uncaught exceptions captured from the
-        Gameface UI. Capture starts when the server first connects to the application.
+        Gameface UI.
+        Capture starts when the server first connects to the application.
       `,
     inputSchema: {
-      limit: exports_external.number().int().min(1).max(1000).optional().describe("Max entries to return (default 50)"),
-      level: exports_external.string().optional().describe("Filter by level, e.g. error / warning / log / info"),
-      clear: exports_external.boolean().optional().describe("Clear the buffer after reading (default false)")
+      limit: exports_external.number().int().min(1).max(1000).optional().describe(`Max entries to return (default 50)`),
+      level: exports_external.string().optional().describe(`Filter by level, e.g. error / warning / log / info`),
+      clear: exports_external.boolean().optional().describe(`Clear the buffer after reading (default false)`)
     }
   }, ({ limit, level, clear }) => gameConsole(client, consoleBuffer, { limit, level, clear }));
   server.registerTool("game_dom", {
-    title: "Inspect Gameface UI DOM",
+    title: `Inspect Gameface UI DOM`,
     description: import_common_tags4.oneLine`
         Return DOM details (tag, id, classes, attributes, bounding rect, outerHTML) for elements
-        matching a CSS selector in the live Gameface UI. Set all=true to return every match.
+        matching a CSS selector in the live Gameface UI.
+        Set all=true to return every match.
       `,
     inputSchema: {
-      selector: exports_external.string().describe("CSS selector to query in the Gameface UI"),
-      all: exports_external.boolean().optional().describe("Return all matches instead of just the first (default: false)"),
-      maxHtml: exports_external.number().min(0).optional().describe("Max outerHTML characters per element before truncation (default: 4000)")
+      selector: exports_external.string().describe(`CSS selector to query in the Gameface UI`),
+      all: exports_external.boolean().optional().describe(`Return all matches instead of just the first (default: false)`),
+      maxHtml: exports_external.number().min(0).optional().describe(`Max outerHTML characters per element before truncation (default: 4000)`)
     }
   }, ({ selector, all, maxHtml }) => gameDom(client, selector, all, maxHtml));
+  server.registerTool("game_find", {
+    title: `Find elements by text in the Gameface UI`,
+    description: import_common_tags4.oneLine`
+        Locate elements by their text content in the live Gameface UI: scan a CSS selector's matches
+        (default: every element) and filter on trimmed textContent by equals/contains/regex
+        (case-insensitive by default).
+        Returns tag, id, classes, and bounding rect per match, plus match counts before and after
+        deepest pruning so pruning and limit truncation are both visible.
+        Set tag=true to stamp matches with data-gf-find handles and get back ready-to-use selectors
+        for game_click / game_hover / game_screenshot.
+        The go-to way to find an element when class names are build-hashed and there is no XPath.
+      `,
+    inputSchema: {
+      text: exports_external.string().describe(`Text to match against each element's trimmed textContent`),
+      match: exports_external.enum(["equals", "contains", "regex"]).optional().describe(`How to match the text: equals / contains / regex (default: contains)`),
+      caseSensitive: exports_external.boolean().optional().describe(`Match case-sensitively (default: false)`),
+      selector: exports_external.string().optional().describe(`CSS selector scoping the scan (default: *, every element)`),
+      deepest: exports_external.boolean().optional().describe(`Keep only the innermost match, pruning ancestors that also matched (default: true)`),
+      tag: exports_external.boolean().optional().describe(import_common_tags4.oneLine`
+              Stamp matches with data-gf-find handles and return them as selectors, clearing any
+              prior handles first (default: false).
+            `),
+      limit: exports_external.number().int().min(1).max(100).optional().describe(`Max matches to return (default: 20); the total count is always reported`)
+    }
+  }, ({ text: text2, match, caseSensitive, selector, deepest, tag, limit }) => gameFind(client, { text: text2, match, caseSensitive, selector, deepest, tag, limit }));
   server.registerTool("game_click", {
-    title: "Click an element in the Gameface UI",
+    title: `Click an element in the Gameface UI`,
     description: import_common_tags4.oneLine`
-        Click the element matching a CSS selector by dispatching a real bubbling
-        pointer/mouse/click sequence in the page (NOT CDP Input, which Gameface ignores for the
-        UI). React onClick handlers fire via event delegation. Use index to pick among matches.
+        Click the element matching a CSS selector by dispatching a real bubbling pointer/mouse/click
+        sequence in the page (NOT CDP Input, which Gameface ignores for the UI).
+        Use index to pick among matches.
       `,
     inputSchema: {
-      selector: exports_external.string().describe("CSS selector of the element to click"),
-      index: exports_external.number().int().min(0).optional().describe("Which match to click when several exist (default: 0)")
+      selector: exports_external.string().describe(`CSS selector of the element to click`),
+      index: exports_external.number().int().min(0).optional().describe(`Which match to click when several exist (default: 0)`)
     }
   }, ({ selector, index }) => gameClick(client, selector, index));
   server.registerTool("game_debug_status", {
-    title: "JS debugger status",
+    title: `JS debugger status`,
     description: import_common_tags4.oneLine`
         Report debugger state: whether paused (and where), pause-on-exceptions mode, breakpoints,
-        and parsed script count. Pass setPauseOnExceptions to change exception pausing. Enables
-        the debugger on first use. Hitting a breakpoint FREEZES the UI until resumed.
+        and parsed script count.
+        Pass setPauseOnExceptions to change exception pausing.
+        Enables the debugger on first use.
+        Hitting a breakpoint FREEZES the UI until resumed.
       `,
     inputSchema: {
-      setPauseOnExceptions: exports_external.enum(["none", "uncaught", "all"]).optional().describe("If set, change which exceptions pause execution (default none)")
+      setPauseOnExceptions: exports_external.enum(["none", "uncaught", "all"]).optional().describe(`If set, change which exceptions pause execution (default none)`)
     }
   }, ({ setPauseOnExceptions }) => debug.status(setPauseOnExceptions));
   server.registerTool("game_debug_scripts", {
-    title: "List parsed UI scripts",
+    title: `List parsed UI scripts`,
     description: import_common_tags4.oneLine`
-        List JavaScript scripts parsed in the Gameface UI (scriptId + url + line count),
-        optionally filtered by a url substring. Use the scriptId with game_debug_source.
+        List JavaScript scripts parsed in the Gameface UI (scriptId + url + line count), optionally
+        filtered by a url substring.
+        Only scripts parsed after the debugger attached appear (Gameface does not replay
+        scriptParsed); an empty list means attach first, then trigger a view reload to repopulate.
+        Use the scriptId with game_debug_source.
       `,
     inputSchema: {
-      filter: exports_external.string().optional().describe("Only scripts whose url contains this substring")
+      filter: exports_external.string().optional().describe(`Only scripts whose url contains this substring`)
     }
   }, ({ filter }) => debug.listScripts(filter));
   server.registerTool("game_debug_source", {
-    title: "Get UI script source",
+    title: `Get UI script source`,
     description: import_common_tags4.oneLine`
         Return the source of a script (by scriptId from game_debug_scripts), with line numbers.
         Pass lineStart/lineEnd to get a range (large scripts are capped at 400 lines).
       `,
     inputSchema: {
-      scriptId: exports_external.string().describe("Script id from game_debug_scripts"),
-      lineStart: exports_external.number().int().min(1).optional().describe("First line (1-based)"),
-      lineEnd: exports_external.number().int().min(1).optional().describe("Last line (1-based)")
+      scriptId: exports_external.string().describe(`Script id from game_debug_scripts`),
+      lineStart: exports_external.number().int().min(1).optional().describe(`First line (1-based)`),
+      lineEnd: exports_external.number().int().min(1).optional().describe(`Last line (1-based)`)
     }
   }, ({ scriptId, lineStart, lineEnd }) => debug.getSource(scriptId, lineStart, lineEnd));
   server.registerTool("game_debug_set_breakpoint", {
-    title: "Set a breakpoint",
+    title: `Set a breakpoint`,
     description: import_common_tags4.oneLine`
-        Set a breakpoint by url substring + line (1-based). Add a condition (JS expression) to
-        only pause when it is truthy, which limits how often the UI freezes. Hitting it FREEZES
-        the UI until you resume with game_debug_step.
+        Set a breakpoint by url substring + line (1-based).
+        Add a condition (JS expression) to only pause when it is truthy, which limits how often the
+        UI freezes.
+        Hitting it FREEZES the UI until you resume with game_debug_step.
       `,
     inputSchema: {
-      urlContains: exports_external.string().describe("Substring of the script url to break in"),
-      line: exports_external.number().int().min(1).describe("Line number (1-based)"),
-      column: exports_external.number().int().min(0).optional().describe("Column (0-based), optional"),
-      condition: exports_external.string().optional().describe("Optional JS condition; pause only when it evaluates truthy")
+      urlContains: exports_external.string().describe(`Substring of the script url to break in`),
+      line: exports_external.number().int().min(1).describe(`Line number (1-based)`),
+      column: exports_external.number().int().min(0).optional().describe(`Column (0-based), optional`),
+      condition: exports_external.string().optional().describe(`Optional JS condition; pause only when it evaluates truthy`)
     }
   }, ({ urlContains, line, column, condition }) => debug.setBreakpoint(urlContains, line, column, condition));
   server.registerTool("game_debug_remove_breakpoint", {
-    title: "Remove a breakpoint",
-    description: "Remove a breakpoint by its id (from game_debug_status), or pass 'all'.",
+    title: `Remove a breakpoint`,
+    description: `Remove a breakpoint by its id (from game_debug_status), or pass 'all'.`,
     inputSchema: {
-      breakpoint: exports_external.string().describe("Breakpoint id, or 'all'")
+      breakpoint: exports_external.string().describe(`Breakpoint id, or 'all'`)
     }
   }, ({ breakpoint }) => debug.removeBreakpoint(breakpoint));
   server.registerTool("game_debug_pause_state", {
-    title: "Inspect the paused stack",
+    title: `Inspect the paused stack`,
     description: import_common_tags4.oneLine`
-        When paused, return the call stack (frames with function + location + scope types). Set
-        expandScopes to also list local/closure variables of each frame. Returns 'not paused'
-        otherwise.
+        When paused, return the call stack (frames with function + location + scope types).
+        Set expandScopes to also list local/closure variables of each frame.
+        Returns 'not paused' otherwise.
       `,
     inputSchema: {
-      expandScopes: exports_external.boolean().optional().describe("Also list local/closure variables per frame (default false)")
+      expandScopes: exports_external.boolean().optional().describe(`Also list local/closure variables per frame (default false)`)
     }
   }, ({ expandScopes }) => debug.pauseStateReport(expandScopes ?? false));
   server.registerTool("game_debug_evaluate", {
-    title: "Evaluate while debugging",
+    title: `Evaluate while debugging`,
     description: import_common_tags4.oneLine`
-        Evaluate a JS expression. When paused, it runs in the selected call frame's scope
-        (Debugger.evaluateOnCallFrame) so you can read locals; otherwise it runs globally. Prefer
-        this over game_eval while paused.
+        Evaluate a JS expression.
+        When paused, it runs in the selected call frame's scope (Debugger.evaluateOnCallFrame) so
+        you can read locals; otherwise it runs globally.
+        Prefer this over game_eval while paused.
       `,
     inputSchema: {
-      expression: exports_external.string().describe("JS expression to evaluate"),
-      frameIndex: exports_external.number().int().min(0).optional().describe("Call frame index to evaluate in when paused (default 0 = top)")
+      expression: exports_external.string().describe(`JS expression to evaluate`),
+      frameIndex: exports_external.number().int().min(0).optional().describe(`Call frame index to evaluate in when paused (default 0 = top)`)
     }
   }, ({ expression, frameIndex }) => debug.evaluate(expression, frameIndex));
   server.registerTool("game_debug_step", {
-    title: "Step / resume / pause execution",
+    title: `Step / resume / pause execution`,
     description: import_common_tags4.oneLine`
-        Control paused execution: resume (unfreeze the UI), over / into / out (step), or pause
-        (break at the next statement). Stepping reports the new location.
+        Control paused execution: resume (unfreeze the UI), over/into/out (step), or pause (break at
+        the next statement).
+        Stepping reports the new location.
       `,
     inputSchema: {
-      action: exports_external.enum(["resume", "over", "into", "out", "pause"]).describe("resume | over | into | out | pause")
+      action: exports_external.enum(["resume", "over", "into", "out", "pause"]).describe(`resume | over | into | out | pause`)
     }
   }, ({ action }) => debug.step(action));
   const transport = new StdioServerTransport;