@csmodding/gameface-devtools-mcp 0.2.0 → 1.0.0

package/dist/server.mjs

@@ -30319,7 +30319,7 @@ class StdioServerTransport {
 }
 
 // src/server.ts
-var import_common_tags4 = __toESM(require_lib(), 1);
+var import_common_tags5 = __toESM(require_lib(), 1);
 
 // src/cdp.ts
 var import_common_tags = __toESM(require_lib(), 1);
@@ -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 {}
@@ -30602,9 +30602,8 @@ function num(value, fallback) {
   return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 }
 
-// src/debugger.ts
+// src/console.ts
 var import_common_tags2 = __toESM(require_lib(), 1);
-import { setTimeout as sleep } from "node:timers/promises";
 
 // src/shared.ts
 function text(value) {
@@ -30633,7 +30632,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) {
@@ -30647,13 +30646,517 @@ function valToStr(value) {
   }
 }
 
+// src/console.ts
+var DEFAULT_CONSOLE_LIMIT = 50;
+var DEFAULT_MAX_ENTRIES = 500;
+var MILLIS_DIGITS = 3;
+var EPOCH_MS_FLOOR = 1000000000000;
+var CAPTURE_DEPTH_CAP = 4;
+var DEFAULT_RENDER_DEPTH = 2;
+var LEVEL_WIDTH = 20;
+var STRING_CLIP = 200;
+var DEFAULT_EXPAND_TIMEOUT_MS = 2000;
+var DEFAULT_MAX_PENDING = 32;
+
+class ConsoleBuffer {
+  entries = [];
+  queue = [];
+  isDraining = false;
+  generation = 0;
+  cdp;
+  max;
+  maxPending;
+  expandTimeoutMs;
+  constructor(cdp, reloads, options = {}) {
+    this.cdp = cdp;
+    this.max = options.max ?? DEFAULT_MAX_ENTRIES;
+    this.maxPending = options.maxPending ?? DEFAULT_MAX_PENDING;
+    this.expandTimeoutMs = options.expandTimeoutMs ?? DEFAULT_EXPAND_TIMEOUT_MS;
+    cdp.onConnect(async (conn) => {
+      await conn.ensureDomain("Runtime");
+      await conn.ensureDomain("Log");
+    });
+    cdp.onEvent((method, params) => {
+      this.handle(method, params ?? {});
+    });
+    reloads?.onReload((count) => {
+      this.enqueueText("reload", "info", `view reloaded (#${count})`);
+    });
+  }
+  read(options) {
+    const { limit = DEFAULT_CONSOLE_LIMIT, level, clear = false } = options;
+    const depth = Math.min(Math.max(options.depth ?? DEFAULT_RENDER_DEPTH, 1), CAPTURE_DEPTH_CAP);
+    const filtered = level ? this.entries.filter((entry) => entry.level == level) : this.entries;
+    const taken = filtered.slice(-limit);
+    if (clear) {
+      this.clear();
+    }
+    return taken.map((entry) => renderLine(entry, depth));
+  }
+  clear() {
+    this.entries.length = 0;
+    this.queue.length = 0;
+    this.generation++;
+  }
+  handle(method, params) {
+    if (method == "Runtime.consoleAPICalled") {
+      this.enqueue({
+        at: entryTime(params.timestamp),
+        kind: "console",
+        level: params.type ?? "log",
+        args: params.args ?? [],
+        expand: this.expanding() < this.maxPending
+      });
+    } else if (method == "Log.entryAdded") {
+      const entry = params.entry ?? {};
+      this.enqueueText(entry.source ?? "log", entry.level ?? "info", entry.text ?? "", entry.timestamp);
+    } else if (method == "Runtime.exceptionThrown") {
+      this.enqueueText("exception", "error", formatException(params.exceptionDetails), params.timestamp);
+    }
+  }
+  enqueueText(kind, level, line, timestamp) {
+    this.enqueue({
+      at: entryTime(timestamp),
+      kind,
+      level,
+      args: [{ type: "string", value: line }],
+      expand: false
+    });
+  }
+  enqueue(capture) {
+    this.queue.push(capture);
+    this.drain();
+  }
+  expanding() {
+    return this.queue.filter((capture) => capture.expand).length;
+  }
+  async drain() {
+    if (this.isDraining) {
+      return;
+    }
+    this.isDraining = true;
+    try {
+      for (let next = this.queue.shift();next; next = this.queue.shift()) {
+        const { generation } = this;
+        const args = await Promise.all(next.args.map((arg) => this.resolveArg(arg, next.expand)));
+        if (generation == this.generation) {
+          this.push({ at: next.at, kind: next.kind, level: next.level, args });
+        }
+      }
+    } finally {
+      this.isDraining = false;
+    }
+  }
+  async resolveArg(arg, expand) {
+    if (arg.objectId == null) {
+      return describedValue(arg);
+    }
+    if (expand) {
+      const tree = await this.expand(arg.objectId);
+      if (tree) {
+        return tree;
+      }
+    }
+    return previewValue(arg.preview) ?? describedValue(arg);
+  }
+  async expand(objectId) {
+    try {
+      const response = await withTimeout(this.cdp.call("Runtime.callFunctionOn", {
+        objectId,
+        functionDeclaration: SERIALIZE_SOURCE,
+        arguments: [{ value: CAPTURE_DEPTH_CAP }, { value: LEVEL_WIDTH }, { value: STRING_CLIP }],
+        returnByValue: true
+      }), this.expandTimeoutMs);
+      const value = response.result?.value;
+      if (response.exceptionDetails || value == null || typeof value != "object") {
+        return;
+      }
+      return value;
+    } catch {
+      return;
+    }
+  }
+  push(entry) {
+    this.entries.push(entry);
+    if (this.entries.length > this.max) {
+      this.entries.splice(0, this.entries.length - this.max);
+    }
+  }
+}
+async function gameConsole(client, buffer, options) {
+  try {
+    await client.connection();
+  } catch (error51) {
+    return toErrorResult(error51);
+  }
+  const lines = buffer.read(options);
+  if (lines.length == 0) {
+    return text(import_common_tags2.oneLine`
+      No console entries captured yet.
+      Capture begins once the server connects to the application;
+      trigger some UI activity (or a game_eval console.log) and retry.
+    `);
+  }
+  return text(lines.join(`
+`));
+}
+function entryTime(timestamp) {
+  const isEpoch = typeof timestamp == "number" && timestamp > EPOCH_MS_FLOOR;
+  return isEpoch ? timestamp : Date.now();
+}
+function withTimeout(promise3, timeoutMs) {
+  let timer;
+  const deadline = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(`console expansion timed out`)), timeoutMs);
+  });
+  return Promise.race([promise3, deadline]).finally(() => clearTimeout(timer));
+}
+function serializeConsoleArgFn(cap, width, clip) {
+  const seen = new Set;
+  return walk(this, 0);
+  function walk(value, depth) {
+    if (typeof value == "string") {
+      return value.length > clip ? { kind: "string", text: value.slice(0, clip), clipped: true } : { kind: "string", text: value };
+    }
+    if (value === null || typeof value != "object") {
+      return { kind: "raw", text: scalarText(value) };
+    }
+    const node = value;
+    if (typeof node.nodeType == "number") {
+      return { kind: "node", text: nodeText(node) };
+    }
+    if (value instanceof Date) {
+      return { kind: "raw", text: dateText(value) };
+    }
+    if (value instanceof RegExp || value instanceof Error) {
+      return { kind: "raw", text: String(value) };
+    }
+    if (seen.has(value)) {
+      return { kind: "circular" };
+    }
+    const shape = Array.isArray(value) ? "array" : value instanceof Map ? "map" : value instanceof Set ? "set" : "object";
+    if (depth >= cap) {
+      return {
+        kind: "capped",
+        of: shape,
+        ctor: shape == "object" ? ctorName(value) : undefined,
+        size: sizeOf(value, shape)
+      };
+    }
+    seen.add(value);
+    try {
+      return expand(value, shape, depth);
+    } finally {
+      seen.delete(value);
+    }
+  }
+  function expand(value, shape, depth) {
+    if (shape == "array") {
+      const all = value;
+      const items = all.slice(0, width).map((item) => walk(item, depth + 1));
+      return { kind: "array", items, more: dropped(all.length, items.length) };
+    }
+    if (shape == "map") {
+      const all = Array.from(value.entries());
+      const pairs = all.slice(0, width).map((pair) => [walk(pair[0], depth + 1), walk(pair[1], depth + 1)]);
+      return { kind: "map", size: all.length, pairs, more: dropped(all.length, pairs.length) };
+    }
+    if (shape == "set") {
+      const all = Array.from(value.values());
+      const items = all.slice(0, width).map((item) => walk(item, depth + 1));
+      return { kind: "set", size: all.length, items, more: dropped(all.length, items.length) };
+    }
+    const bag = value;
+    const keys = Object.keys(bag);
+    const entries = keys.slice(0, width).map((key) => [key, readProperty(bag, key, depth)]);
+    return {
+      kind: "object",
+      ctor: ctorName(value),
+      entries,
+      more: dropped(keys.length, entries.length)
+    };
+  }
+  function dropped(total, kept) {
+    return total > kept ? total - kept : undefined;
+  }
+  function readProperty(bag, key, depth) {
+    try {
+      return walk(bag[key], depth + 1);
+    } catch {
+      return { kind: "raw", text: "[unreadable]" };
+    }
+  }
+  function scalarText(value) {
+    if (typeof value == "function") {
+      const named = value;
+      return named.name ? `[Function: ${named.name}]` : `[Function (anonymous)]`;
+    }
+    if (typeof value == "bigint") {
+      return `${value}n`;
+    }
+    if (typeof value == "symbol") {
+      return value.toString();
+    }
+    return String(value);
+  }
+  function nodeText(node) {
+    const name = typeof node.tagName == "string" ? node.tagName : String(node.nodeName);
+    const id = typeof node.id == "string" && node.id ? `#${node.id}` : "";
+    const classes = typeof node.className == "string" ? node.className.trim() : "";
+    const suffix = classes ? `.${classes.split(/\s+/u).join(".")}` : "";
+    return `<${name.toLowerCase()}${id}${suffix}>`;
+  }
+  function dateText(value) {
+    try {
+      return value.toISOString();
+    } catch {
+      return String(value);
+    }
+  }
+  function ctorName(value) {
+    const name = value.constructor?.name;
+    return name && name != "Object" ? name : undefined;
+  }
+  function sizeOf(value, shape) {
+    return shape == "map" || shape == "set" ? value.size : undefined;
+  }
+}
+var SERIALIZE_SOURCE = serializeConsoleArgFn.toString();
+function renderLine(entry, depth) {
+  const args = entry.args.map((arg) => renderArgument(arg, depth));
+  return `${formatClock(entry.at)} [${entry.level}] (${entry.kind}) ${args.join(" ")}`;
+}
+function renderArgument(value, depth) {
+  try {
+    return renderValue(value, depth);
+  } catch {
+    return `[unrenderable]`;
+  }
+}
+function formatClock(at) {
+  const date6 = new Date(at);
+  const hours = String(date6.getHours()).padStart(2, "0");
+  const minutes = String(date6.getMinutes()).padStart(2, "0");
+  const seconds = String(date6.getSeconds()).padStart(2, "0");
+  const millis = String(date6.getMilliseconds()).padStart(MILLIS_DIGITS, "0");
+  return `${hours}:${minutes}:${seconds}.${millis}`;
+}
+function renderValue(value, depth) {
+  switch (value.kind) {
+    case "raw":
+    case "node": {
+      return value.text;
+    }
+    case "string": {
+      const held = value.text.replaceAll("\r", String.raw`\r`).replaceAll(`
+`, String.raw`\n`);
+      return `'${held}${value.clipped ? "…" : ""}'`;
+    }
+    case "circular": {
+      return `[Circular]`;
+    }
+    case "capped": {
+      return collapsed(value);
+    }
+    case "object": {
+      if (depth <= 0) {
+        return collapsed({ of: "object", ctor: value.ctor });
+      }
+      const parts = value.entries.map(([key, held]) => `${renderKey(key)}: ${renderValue(held, depth - 1)}`);
+      return `${value.ctor ? `${value.ctor} ` : ""}{${joinParts(parts, value.more)}}`;
+    }
+    case "array": {
+      if (depth <= 0) {
+        return collapsed({ of: "array" });
+      }
+      return `[${joinParts(value.items.map((item) => renderValue(item, depth - 1)), value.more)}]`;
+    }
+    case "map": {
+      if (depth <= 0) {
+        return collapsed({ of: "map", size: value.size });
+      }
+      const parts = value.pairs.map(([key, held]) => `${renderValue(key, depth - 1)} => ${renderValue(held, depth - 1)}`);
+      return `Map(${value.size}) {${joinParts(parts, value.more)}}`;
+    }
+    case "set": {
+      if (depth <= 0) {
+        return collapsed({ of: "set", size: value.size });
+      }
+      return `Set(${value.size}) {${joinParts(value.items.map((item) => renderValue(item, depth - 1)), value.more)}}`;
+    }
+    default: {
+      const unreachable = value;
+      throw new Error(`Unhandled console value ${JSON.stringify(unreachable)}`);
+    }
+  }
+}
+function collapsed(value) {
+  if (value.of == "array") {
+    return `[…]`;
+  }
+  if (value.of == "map" || value.of == "set") {
+    const label = value.of == "map" ? "Map" : "Set";
+    return `${label}(${value.size ?? "?"}) {…}`;
+  }
+  return `${value.ctor ? `${value.ctor} ` : ""}{…}`;
+}
+function joinParts(parts, more) {
+  const marked = more == null ? parts : [...parts, more === true ? `…more` : `…${more} more`];
+  return marked.join(", ");
+}
+function renderKey(key) {
+  return /^[A-Za-z_$][\w$]*$/u.test(key) ? key : `'${key}'`;
+}
+function previewValue(preview) {
+  if (!preview) {
+    return;
+  }
+  const scalar = previewScalar(preview);
+  if (scalar) {
+    return scalar;
+  }
+  if (preview.subtype == "array") {
+    const items = (preview.properties ?? []).map((property) => previewProperty(property));
+    const size2 = previewSize(preview.description) ?? items.length;
+    return { kind: "array", items, more: previewOverflow(preview, items.length, size2) };
+  }
+  if (preview.subtype == "set") {
+    const items = (preview.entries ?? []).map((entry) => previewValue(entry.value) ?? unknownValue());
+    const size2 = previewSize(preview.description) ?? items.length;
+    return { kind: "set", size: size2, items, more: previewOverflow(preview, items.length, size2) };
+  }
+  if (preview.subtype == "map") {
+    const pairs = (preview.entries ?? []).map((entry) => {
+      const key = previewValue(entry.key) ?? unknownValue();
+      return [key, previewValue(entry.value) ?? unknownValue()];
+    });
+    const size2 = previewSize(preview.description) ?? pairs.length;
+    return { kind: "map", size: size2, pairs, more: previewOverflow(preview, pairs.length, size2) };
+  }
+  if (isStringified(preview)) {
+    return { kind: "raw", text: oneLineText(preview.description ?? preview.subtype ?? "object") };
+  }
+  const label = preview.description;
+  const entries = (preview.properties ?? []).map((property) => [property.name, previewProperty(property)]);
+  const size = preview.subtype ? previewSize(preview.description) : undefined;
+  return {
+    kind: "object",
+    ctor: label && label != "Object" ? label : undefined,
+    entries,
+    more: previewOverflow(preview, entries.length, size)
+  };
+}
+function previewScalar(preview) {
+  if (preview.type && preview.type != "object") {
+    return preview.type == "string" ? clippedString(preview.description ?? "") : { kind: "raw", text: oneLineText(preview.description ?? preview.type) };
+  }
+  if (preview.subtype == "node") {
+    return { kind: "node", text: preview.description ?? "node" };
+  }
+  return;
+}
+function isStringified(preview) {
+  return Boolean(preview.subtype) && !preview.properties?.length;
+}
+function previewProperty(property) {
+  if (property.valuePreview) {
+    return previewValue(property.valuePreview) ?? unknownValue();
+  }
+  if (property.type == "string") {
+    return clippedString(property.value ?? "");
+  }
+  if (property.type == "object") {
+    return previewObjectProperty(property);
+  }
+  const described = property.value?.length ? property.value : property.type;
+  return { kind: "raw", text: oneLineText(described) };
+}
+function previewObjectProperty(property) {
+  const { subtype, value } = property;
+  if (subtype == "array" || subtype == "map" || subtype == "set") {
+    return { kind: "capped", of: subtype, size: previewSize(value) };
+  }
+  if (subtype == "node") {
+    return { kind: "node", text: value ?? "node" };
+  }
+  if (subtype) {
+    return { kind: "raw", text: oneLineText(value ?? subtype) };
+  }
+  const named = value && value != "Object";
+  return { kind: "capped", of: "object", ctor: named ? value : undefined };
+}
+function previewOverflow(preview, shown, size = shown) {
+  if (size > shown) {
+    return size - shown;
+  }
+  return preview.overflow ? true : undefined;
+}
+function previewSize(description) {
+  const size = /\((?<size>\d+)\)$/u.exec(description ?? "")?.groups?.size;
+  return size == null ? undefined : Number(size);
+}
+function clippedString(held) {
+  return held.length > STRING_CLIP ? { kind: "string", text: held.slice(0, STRING_CLIP), clipped: true } : { kind: "string", text: held };
+}
+function oneLineText(held) {
+  const flat = held.split(/\r\n|[\r\n]/u).map((line) => line.trim()).find((line) => line.length);
+  return clipText(flat ?? "");
+}
+function clipText(held) {
+  return held.length > STRING_CLIP ? `${held.slice(0, STRING_CLIP)}…` : held;
+}
+function describedValue(arg) {
+  return { kind: "raw", text: valToStr(describeRemoteObject(arg)) };
+}
+function unknownValue() {
+  return { kind: "capped", of: "object" };
+}
+
 // src/debugger.ts
-var SCRIPT_REPLAY_WAIT_MS = 350;
+var import_common_tags3 = __toESM(require_lib(), 1);
+import { setTimeout as sleep } from "node:timers/promises";
 var POLL_INTERVAL_MS = 50;
 var PAUSE_WAIT_MS = 3000;
 var RESUME_WAIT_MS = 2000;
 var STEP_WAIT_MS = 2000;
 var MAX_SCOPE_VARIABLES = 50;
+var MAX_SEARCH_MATCHES = 10;
+var SEARCH_SNIPPET_MARGIN = 40;
+var DEFAULT_SOURCE_MAX_CHARS = 4000;
+var EMPTY_SCRIPT_MAP_NOTE = import_common_tags3.oneLine`
+  No scripts are parsed on this connection: a view reload re-parses every one of them.
+  Take the reload count from game_status, game_eval of location.reload(), then game_wait with
+  reload true and that count as sinceReloads, then call this again.
+`;
+var NO_MATCH_NOTE = import_common_tags3.oneLine`
+  Nothing matched. The search is case-sensitive and literal (no regex), and it only reaches scripts
+  parsed on this connection: game_debug_scripts lists them.
+`;
+var FILTER_MISS_NOTE = import_common_tags3.oneLine`
+  No parsed script's url contains that urlContains, so the query never ran against anything.
+  game_debug_scripts lists the urls; the url filter is case-insensitive, so case is not the cause.
+`;
+var FILTER_MISS_LIST_NOTE = import_common_tags3.oneLine`
+  No parsed script's url contains that filter, though others are parsed: call this without one to
+  see every url. Matching is case-insensitive, so case is not the cause.
+`;
+var UNREADABLE_NOTE = import_common_tags3.oneLine`
+  The engine has no source for any of the scripts matched, so the query never ran: their ids are
+  stale, which a view reload clears by re-parsing everything under fresh ones.
+`;
+var SEARCH_HINT = import_common_tags3.oneLine`
+  Pass a match's line and column to game_debug_set_breakpoint to break there; both are 1-based, as
+  everywhere in these tools, and its urlContains takes the match's url as printed.
+`;
+var SINGLE_LINE_HINT = import_common_tags3.oneLine`
+  That script is one line, as a minified bundle is, so the whole module sits on the line the
+  resolved location names and the breakpoint bound to the first breakable position at or after the
+  one you asked for: read the column above to see where it landed.
+  At the module's own first column that is evaluation code, which runs on load and never again
+  during interaction.
+  To break inside a function, find its column with game_debug_search_source and pass that column
+  here.
+`;
 function escapeRegex2(value) {
   return value.replaceAll(/[.*+?^${}()|[\]\\]/gu, String.raw`\$&`);
 }
@@ -30666,12 +31169,21 @@ 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();
+    });
+  }
+  get pause() {
+    if (!this.paused) {
+      return;
+    }
+    return { reason: this.paused.reason, location: this.topLocation() };
   }
   async status(setPause) {
     try {
@@ -30684,8 +31196,9 @@ class DebuggerSession {
         id: bp.id,
         urlContains: bp.urlContains,
         line: bp.lineNumber + 1,
+        column: bp.columnNumber == null ? undefined : bp.columnNumber + 1,
         condition: bp.condition,
-        resolved: bp.locations.length
+        resolvedLocations: bp.resolved
       }));
       return text(JSON.stringify({
         enabled: true,
@@ -30706,49 +31219,87 @@ class DebuggerSession {
   async listScripts(filter) {
     try {
       await this.ensureReady();
-      const needle = filter?.toLowerCase();
-      let scripts = [...this.scripts.values()];
-      if (needle) {
-        scripts = scripts.filter((script) => script.url.toLowerCase().includes(needle));
-      }
-      scripts.sort((a, b) => a.url.localeCompare(b.url));
+      const scripts = this.filteredScripts(filter);
       const cap = 120;
       const shown = scripts.slice(0, cap).map((script) => ({
         scriptId: script.scriptId,
         url: script.url || "(anonymous)",
-        lines: script.endLine || undefined
+        lines: script.endLine - script.startLine + 1,
+        firstLine: script.startLine == 0 ? undefined : script.startLine + 1
       }));
       return text(JSON.stringify({
         total: scripts.length,
         shown: shown.length,
         truncated: scripts.length > cap,
-        scripts: shown
+        scripts: shown,
+        note: this.listNote(scripts.length)
       }, null, 2));
     } catch (error51) {
       return toErrorResult(error51);
     }
   }
-  async getSource(scriptId, lineStart, lineEnd) {
+  async searchSource(query, urlContains) {
     try {
       await this.ensureReady();
-      const res = await this.client.call("Debugger.getScriptSource", {
-        scriptId
-      });
-      const source = res?.scriptSource;
+      const scripts = this.filteredScripts(urlContains);
+      const { matches, total, unreadable } = await this.collectMatches(scripts, query);
+      const missNote = this.missNote(scripts.length, unreadable);
+      return text(JSON.stringify({
+        query,
+        urlContains,
+        scriptsSearched: urlContains == null ? undefined : scripts.length,
+        total,
+        returned: matches.length,
+        truncated: total > matches.length,
+        matches,
+        note: total == 0 ? missNote : undefined,
+        hint: total == 0 ? undefined : SEARCH_HINT
+      }, null, 2));
+    } catch (error51) {
+      return toErrorResult(error51);
+    }
+  }
+  async getSource(scriptId, lineStart, lineEnd, maxChars) {
+    try {
+      await this.ensureReady();
+      const source = await this.scriptSource(scriptId);
       if (source == null) {
         return errorText(`No source for scriptId ${scriptId}.`);
       }
       const lines = source.split(`
 `);
-      const from = lineStart && lineStart > 0 ? lineStart : 1;
+      const offset = this.scripts.get(scriptId)?.startLine ?? 0;
+      const first = offset + 1;
+      const last = offset + lines.length;
       const cap = 400;
-      const to = lineEnd && lineEnd >= from ? Math.min(lineEnd, from + cap - 1) : Math.min(lines.length, from + cap - 1);
+      const from = lineStart && lineStart > first ? lineStart : first;
+      if (from > last) {
+        return errorText(import_common_tags3.oneLine`
+          Script ${scriptId} spans lines ${first}-${last}, so there is nothing at line ${from}.
+        `);
+      }
+      const to = Math.min(lineEnd && lineEnd >= from ? lineEnd : last, last, from + cap - 1);
       const padWidth = 5;
-      const slice = lines.slice(from - 1, to).map((line, index) => `${String(from + index).padStart(padWidth)}  ${line}`).join(`
+      const rendered = lines.slice(from - first, to - offset).map((line, index) => `${String(from + index).padStart(padWidth)}  ${line}`).join(`
 `);
-      const note = to < lines.length || from > 1 ? `
-... showing lines ${from}-${to} of ${lines.length}.` : "";
-      return text(slice + note);
+      const budget = maxChars ?? DEFAULT_SOURCE_MAX_CHARS;
+      const clipped = rendered.length > budget;
+      const body = clipped ? rendered.slice(0, budget) : rendered;
+      const shownTo = from + body.replace(/\n$/u, "").split(`
+`).length - 1;
+      const notes = [];
+      if (shownTo < last || from > first) {
+        notes.push(`showing lines ${from}-${shownTo} of ${last}`);
+      }
+      if (clipped) {
+        notes.push(import_common_tags3.oneLine`
+          clipped to ${budget} of ${rendered.length} characters: raise maxChars for more, or reach
+          a position inside a minified line with game_debug_search_source
+        `);
+      }
+      const note = notes.length > 0 ? `
+... ${notes.join(". ")}.` : "";
+      return text(body + note);
     } catch (error51) {
       return toErrorResult(error51);
     }
@@ -30757,34 +31308,42 @@ class DebuggerSession {
     try {
       await this.ensureReady();
       const lineNumber = Math.max(0, line - 1);
+      const columnNumber = column == null ? undefined : Math.max(0, column - 1);
       const urlRegex = escapeRegex2(urlContains);
-      const res = await this.client.call("Debugger.setBreakpointByUrl", { urlRegex, lineNumber, columnNumber: column, condition });
+      const res = await this.client.call("Debugger.setBreakpointByUrl", { urlRegex, lineNumber, columnNumber, condition });
       const id = this.nextBpId++;
       const locations = res.locations ?? [];
+      const resolved = locations.map((loc) => this.locStr(loc));
       this.breakpoints.set(id, {
         id,
         urlContains,
         urlRegex,
         lineNumber,
-        columnNumber: column,
+        columnNumber,
         condition,
         cdpId: res.breakpointId,
-        locations
+        resolved
+      });
+      const singleLine = locations.some((loc) => {
+        const script = this.scripts.get(loc.scriptId);
+        return script != null && script.endLine == script.startLine;
       });
       return text(JSON.stringify({
         id,
         urlContains,
         line,
-        condition: condition ?? null,
-        resolvedLocations: locations.map((loc) => this.locStr(loc)),
+        column,
+        condition,
+        resolvedLocations: resolved,
         pending: locations.length == 0,
-        note: locations.length == 0 ? import_common_tags2.oneLine`
+        note: locations.length == 0 ? import_common_tags3.oneLine`
                     Pending: no matching script/line loaded yet, or the line has no code.
                     It will bind when the script loads.
-                  ` : import_common_tags2.oneLine`
+                  ` : import_common_tags3.oneLine`
                     Hitting this breakpoint FREEZES the UI until you resume
                     (game_debug_step resume).
-                  `
+                  `,
+        hint: singleLine ? SINGLE_LINE_HINT : undefined
       }, null, 2));
     } catch (error51) {
       return toErrorResult(error51);
@@ -30817,7 +31376,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()) {
@@ -30843,7 +31402,7 @@ class DebuggerSession {
       if (this.paused) {
         const frame = this.paused.callFrames[frameIndex];
         if (!frame) {
-          return errorText(import_common_tags2.oneLine`
+          return errorText(import_common_tags3.oneLine`
             No call frame at index ${frameIndex}
             (paused stack has ${this.paused.callFrames.length}).
           `);
@@ -30886,15 +31445,21 @@ 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");
-        const deadline = Date.now() + RESUME_WAIT_MS;
-        while (Date.now() < deadline && this.paused) {
-          await sleep(POLL_INTERVAL_MS);
+        await this.waitUntil(() => !this.paused, RESUME_WAIT_MS);
+        if (this.paused) {
+          return errorText(import_common_tags3.oneLine`
+            Resume sent, but the UI is paused again at ${this.topLocation()}
+            (reason: ${this.paused.reason}), so it is still frozen.
+            Whatever armed that pause sits on the resumed path, so clear it before resuming again:
+            game_debug_remove_breakpoint for a breakpoint, or game_debug_status
+            setPauseOnExceptions none when the reason above is an exception.
+          `);
         }
-        return text("Resumed (UI unfrozen).");
+        return text(`Resumed (UI unfrozen).`);
       }
       const cdpMethod = { over: "stepOver", into: "stepInto", out: "stepOut" }[action];
       const before = this.pausedSeq;
@@ -30919,7 +31484,7 @@ class DebuggerSession {
           condition: bp.condition
         });
         bp.cdpId = res.breakpointId;
-        bp.locations = res.locations ?? [];
+        bp.resolved = (res.locations ?? []).map((loc) => this.locStr(loc));
       } catch {}
     }
   }
@@ -30929,6 +31494,7 @@ class DebuggerSession {
         scriptId: params.scriptId,
         url: params.url || "",
         startLine: params.startLine ?? 0,
+        startColumn: params.startColumn ?? 0,
         endLine: params.endLine ?? 0,
         length: params.length
       });
@@ -30941,13 +31507,79 @@ class DebuggerSession {
       this.pausedSeq++;
     } else if (method == "Debugger.resumed") {
       this.paused = undefined;
+    } else if (method == "Debugger.breakpointResolved") {
+      this.recordResolved(params);
+    }
+  }
+  recordResolved(params) {
+    const location = params.location;
+    const bp = [...this.breakpoints.values()].find((entry) => entry.cdpId == params.breakpointId);
+    if (location == null || bp == null) {
+      return;
+    }
+    const at = this.locStr(location);
+    if (!bp.resolved.includes(at)) {
+      bp.resolved.push(at);
     }
   }
   async ensureReady() {
     await this.client.connection();
+  }
+  filteredScripts(contains) {
+    return [...this.scripts.values()].filter((script) => matchesUrl(script.url, contains)).toSorted((a, b) => a.url.localeCompare(b.url));
+  }
+  listNote(selected) {
+    if (this.scripts.size == 0) {
+      return EMPTY_SCRIPT_MAP_NOTE;
+    }
+    return selected == 0 ? FILTER_MISS_LIST_NOTE : undefined;
+  }
+  missNote(scriptsSearched, unreadable) {
     if (this.scripts.size == 0) {
-      await sleep(SCRIPT_REPLAY_WAIT_MS);
+      return EMPTY_SCRIPT_MAP_NOTE;
+    }
+    if (scriptsSearched == 0) {
+      return FILTER_MISS_NOTE;
+    }
+    return unreadable == scriptsSearched ? UNREADABLE_NOTE : NO_MATCH_NOTE;
+  }
+  async collectMatches(scripts, query) {
+    const matches = [];
+    let total = 0;
+    let unreadable = 0;
+    for (const script of scripts) {
+      let source;
+      try {
+        source = await this.scriptSource(script.scriptId);
+      } catch {
+        unreadable++;
+        continue;
+      }
+      if (source == null) {
+        unreadable++;
+        continue;
+      }
+      let at = source.indexOf(query);
+      while (at >= 0) {
+        total++;
+        if (matches.length < MAX_SEARCH_MATCHES) {
+          matches.push({
+            url: script.url || "(anonymous)",
+            scriptId: script.scriptId,
+            ...resourcePosition(script, positionAt(source, at)),
+            snippet: snippetAt(source, at, query.length)
+          });
+        }
+        at = source.indexOf(query, at + query.length);
+      }
     }
+    return { matches, total, unreadable };
+  }
+  async scriptSource(scriptId) {
+    const res = await this.client.call("Debugger.getScriptSource", {
+      scriptId
+    });
+    return res?.scriptSource;
   }
   async removeCdpBreakpoint(bp) {
     if (bp.cdpId == null) {
@@ -30975,10 +31607,13 @@ class DebuggerSession {
     }
     return variables;
   }
-  async waitForNewPause(beforeSeq, timeoutMs) {
+  waitForNewPause(beforeSeq, timeoutMs) {
+    return this.waitUntil(() => this.pausedSeq > beforeSeq, timeoutMs);
+  }
+  async waitUntil(done, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-      if (this.pausedSeq > beforeSeq) {
+      if (done()) {
         return true;
       }
       await sleep(POLL_INTERVAL_MS);
@@ -30987,8 +31622,8 @@ class DebuggerSession {
   }
   locStr(loc) {
     const url2 = this.scripts.get(loc.scriptId)?.url ?? "";
-    const label = url2.length > 0 ? url2 : loc.scriptId;
-    return `${label}:${loc.lineNumber + 1}`;
+    const label = url2.length > 0 ? url2 : `(unknown script ${loc.scriptId})`;
+    return `${label}:${loc.lineNumber + 1}:${(loc.columnNumber ?? 0) + 1}`;
   }
   topLocation() {
     const frame = this.paused?.callFrames[0];
@@ -30998,208 +31633,48 @@ class DebuggerSession {
     return `${frame.functionName || "(anonymous)"} at ${this.locStr(frame.location)}`;
   }
 }
+function matchesUrl(url2, contains) {
+  if (contains == null) {
+    return true;
+  }
+  return url2.toLowerCase().includes(contains.toLowerCase());
+}
+function resourcePosition(script, position) {
+  return {
+    line: position.line + script.startLine,
+    column: position.line == 1 ? position.column + script.startColumn : position.column
+  };
+}
+function positionAt(source, index) {
+  let line = 1;
+  let lineStart = 0;
+  for (let at = source.indexOf(`
+`);at >= 0 && at < index; at = source.indexOf(`
+`, at + 1)) {
+    line++;
+    lineStart = at + 1;
+  }
+  return { line, column: index - lineStart + 1 };
+}
+function snippetAt(source, index, length) {
+  const from = Math.max(0, index - SEARCH_SNIPPET_MARGIN);
+  const to = Math.min(source.length, index + length + SEARCH_SNIPPET_MARGIN);
+  const head = from > 0 ? "…" : "";
+  const tail = to < source.length ? "…" : "";
+  return `${head}${source.slice(from, to)}${tail}`;
+}
 
 // src/tools.ts
-var import_common_tags3 = __toESM(require_lib(), 1);
+var import_common_tags4 = __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_QUERY_LIMIT = 20;
+async function gameStatus(client, reloads) {
   const { host, port } = client.config;
   try {
     const target = await client.discover();
@@ -31213,19 +31688,32 @@ 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({
       reachable: false,
       endpoint: `http://${host}:${port}`,
       error: error51 instanceof Error ? error51.message : String(error51),
-      hint: import_common_tags3.oneLine`
+      hint: import_common_tags4.oneLine`
             Launch the Gameface application with its CDP debug port open, then retry.
             Override host/port via GAMEFACE_HOST / GAMEFACE_PORT.
           `
@@ -31248,36 +31736,58 @@ async function gameEval(client, expression, awaitPromise = false) {
     return toErrorResult(error51);
   }
 }
-async function gameScreenshot(client, format = "png", quality, selector) {
+async function gameScreenshot(client, debug, options = {}) {
+  const { format = "png", quality, selector, index = 0 } = options;
   try {
+    await client.connection();
+    const { pause } = debug;
+    if (pause) {
+      return errorText(import_common_tags4.oneLine`
+        game_screenshot cannot capture while the JS debugger holds the UI paused
+        (${pause.reason}, at ${pause.location}): the capture needs the frame loop the pause has
+        frozen, so it would hang until the call times out.
+        Resume with game_debug_step action=resume, then capture.
+        Resuming abandons this stopped frame, so read what you still need from it first, with
+        game_debug_pause_state and game_debug_evaluate; both work while paused, as do game_eval,
+        game_dom, game_query and the input tools.
+      `);
+    }
     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_tags4.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_tags4.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 +31810,86 @@ async function gameDom(client, selector, all = false, maxHtml = 4000) {
     return toErrorResult(error51);
   }
 }
+async function gameQuery(client, options) {
+  const mode = options.match ?? "contains";
+  const needle = options.text ?? null;
+  const { selector } = options;
+  const rejection = queryRejection(options, mode);
+  if (rejection != null) {
+    return errorText(rejection);
+  }
+  const args = {
+    sel: selector ?? "*",
+    needle,
+    mode,
+    caseSensitive: options.caseSensitive ?? false,
+    deepest: options.deepest ?? (needle != null && needle.length > 0),
+    tag: options.tag ?? false,
+    attributes: options.attributes ?? false,
+    limit: options.limit ?? DEFAULT_QUERY_LIMIT
+  };
+  try {
+    const res = await client.call("Runtime.evaluate", {
+      expression: callPageFn(queryFn, args),
+      returnByValue: true
+    });
+    if (res.exceptionDetails) {
+      return errorText(`Query failed: ${formatException(res.exceptionDetails)}`);
+    }
+    const value = res.result.value;
+    if (!value) {
+      return errorText(`game_query returned no result for selector ${JSON.stringify(args.sel)}.`);
+    }
+    if ("error" in value) {
+      return errorText(`game_query: ${value.error}`);
+    }
+    const envelope = {
+      selector: args.sel,
+      match: args.needle == null ? undefined : args.mode,
+      deepest: args.deepest,
+      ...value
+    };
+    return text(JSON.stringify(envelope, null, 2));
+  } catch (error51) {
+    return toErrorResult(error51);
+  }
+}
+function queryRejection(options, mode) {
+  const { text: needle, selector } = options;
+  if (needle == null && selector == null) {
+    return `game_query needs text, selector, or both; neither was given.`;
+  }
+  if (selector != null && selector.trim().length == 0) {
+    return `game_query: selector is blank; pass a real one.`;
+  }
+  if (mode == "equals" && needle != null && needle.trim() != needle) {
+    return import_common_tags4.oneLine`
+      game_query: equals compares against trimmed text, so trim yours; where that empties it, pass
+      '' with a selector to find elements carrying no text.
+    `;
+  }
+  if (needle == "" && mode != "equals") {
+    return import_common_tags4.oneLine`
+      game_query: empty text matches every element under ${mode}; pass match: 'equals' with a
+      selector to find elements carrying no text.
+    `;
+  }
+  if (needle == "" && selector == null) {
+    return `game_query: empty text needs a selector to scope it.`;
+  }
+  return;
+}
+function pausedNote(debug) {
+  const { pause } = debug;
+  if (!pause) {
+    return "";
+  }
+  return import_common_tags4.oneLine`
+    The UI is paused in the JS debugger (${pause.reason}, at ${pause.location}): nothing in it can
+    change until you resume with game_debug_step action=resume, so resume and retry rather than
+    reading this as an unreachable condition.
+  `;
+}
 async function gameClick(client, selector, index = 0) {
   try {
     const res = await client.call("Runtime.evaluate", {
@@ -31311,12 +31901,12 @@ async function gameClick(client, selector, index = 0) {
     }
     const info = res.result.value;
     if (!info?.found) {
-      return errorText(import_common_tags3.oneLine`
+      return errorText(import_common_tags4.oneLine`
         No element to click for selector ${JSON.stringify(selector)} at index ${index}
         (matches found: ${info?.count ?? 0}).
       `);
     }
-    return text(import_common_tags3.oneLine`
+    return text(import_common_tags4.oneLine`
       Clicked ${JSON.stringify(selector)} [index ${index}] at
       (${info.x.toFixed(0)}, ${info.y.toFixed(0)}).
       Dispatched: ${info.fired.join(", ")}. Matches: ${info.count}.
@@ -31325,18 +31915,78 @@ 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, debug, 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);
+  }
+  function timedOut(reason) {
+    const paused = pausedNote(debug);
+    return errorText(paused.length > 0 ? `${reason} ${paused}` : reason);
+  }
+  async function waitForReload() {
+    await client.connection();
+    const baseline = sinceReloads ?? reloads.count;
+    while (reloads.count <= baseline) {
+      if (Date.now() >= deadline) {
+        return timedOut(import_common_tags4.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 timedOut(import_common_tags4.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,25 +31995,24 @@ 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;
       }
       if (Date.now() >= deadline) {
         const what = selector ? `selector ${JSON.stringify(selector)}` : "predicate";
         const errorNote = lastError ? ` Last predicate error: ${lastError}` : "";
-        return errorText(`Timed out after ${budget}ms waiting for ${what}.${errorNote}`);
+        return timedOut(`Timed out after ${budget}ms waiting for ${what}.${errorNote}`);
       }
       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 +32020,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_tags4.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)}.
+    return text(import_common_tags4.oneLine`
+      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 +32044,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_tags4.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)}.
+    return text(import_common_tags4.oneLine`
+      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,88 +32068,569 @@ 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_tags4.oneLine`
+        No element matched ${JSON.stringify(selector)} for game_hover at index ${index}
+        (matches found: ${info?.count ?? 0}).
+      `);
+    }
+    return text(import_common_tags4.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.`);
     }
-    return text(import_common_tags3.oneLine`
-      Hovered ${JSON.stringify(selector)} at (${info.x.toFixed(0)}, ${info.y.toFixed(0)}).
-      Dispatched: ${info.fired.join(", ")}.
+    if (!info.found) {
+      return errorText(import_common_tags4.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_tags4.oneLine`
+      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) {
-    const filtered = level ? this.entries.filter((entry) => entry.level == level) : this.entries;
-    const out = filtered.slice(-limit);
-    if (clear) {
-      this.entries.length = 0;
-    }
-    return out;
+  get count() {
+    return this.reloadCount;
   }
-  push(entry) {
-    this.entries.push(entry);
-    if (this.entries.length > this.max) {
-      this.entries.splice(0, this.entries.length - this.max);
-    }
+  get lastReloadAt() {
+    return this.lastReloadAtMs;
+  }
+  get contextUniqueId() {
+    return this.uniqueId;
+  }
+  onReload(listener) {
+    this.reloadListeners.add(listener);
   }
   handle(method, params) {
-    if (method == "Runtime.consoleAPICalled") {
-      const args = (params.args ?? []).map((arg) => valToStr(describeRemoteObject(arg)));
-      this.push({
-        ts: params.timestamp ?? 0,
-        kind: "console",
-        level: params.type ?? "log",
-        text: args.join(" ")
-      });
-    } else if (method == "Log.entryAdded") {
-      const entry = params.entry ?? {};
-      this.push({
-        ts: entry.timestamp ?? 0,
-        kind: entry.source ?? "log",
-        level: entry.level ?? "info",
-        text: entry.text ?? ""
-      });
-    } else if (method == "Runtime.exceptionThrown") {
-      this.push({
-        ts: params.timestamp ?? 0,
-        kind: "exception",
-        level: "error",
-        text: formatException(params.exceptionDetails)
-      });
+    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 {}
     }
   }
 }
-async function gameConsole(client, buffer, options) {
-  const { limit = DEFAULT_CONSOLE_LIMIT, level, clear = false } = options;
+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 queryFn(args) {
+  const { sel, needle, mode, caseSensitive, deepest, tag, attributes, limit } = args;
+  const SNIPPET_MAX = 100;
+  const target = needle == null ? "" : caseSensitive ? needle : needle.toLowerCase();
+  let regex;
+  if (needle != null && 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 (needle == null || matches((el.textContent || "").trim())) {
+      found.push(el);
+    }
+  }
+  const kept = deepest ? innermost(found) : found;
+  const chosen = kept.slice(0, limit);
+  if (tag) {
+    for (const stale of Array.from(document.querySelectorAll("[data-gf-tag]"))) {
+      stale.removeAttribute("data-gf-tag");
+    }
+    for (const [i, el] of chosen.entries()) {
+      el.setAttribute("data-gf-tag", String(i + 1));
+    }
+  }
+  return {
+    unprunedTotal: found.length,
+    total: kept.length,
+    returned: chosen.length,
+    tagged: tag,
+    elements: chosen.map((el, i) => describe3(el, i))
+  };
+  function innermost(all) {
+    const remaining = new Set(all);
+    for (const el of all) {
+      for (let parent = el.parentElement;parent != null; parent = parent.parentElement) {
+        remaining.delete(parent);
+      }
+    }
+    return Array.from(remaining);
+  }
+  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 (attributes) {
+      const map3 = {};
+      for (const attr of Array.from(el.attributes)) {
+        if (attr.name != "data-gf-tag") {
+          map3[attr.name] = attr.value;
+        }
+      }
+      info.attributes = map3;
+    }
+    if (tag) {
+      info.selector = `[data-gf-tag="${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 {
-    await client.connection();
-  } catch (error51) {
-    return toErrorResult(error51);
+    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 entries = buffer.read(limit, level, clear);
-  if (entries.length == 0) {
-    return text(import_common_tags3.oneLine`
-      No console entries captured yet.
-      Capture begins once the server connects to the application;
-      trigger some UI activity (or a game_eval console.log) and retry.
-    `);
+  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 {}
   }
-  return text(entries.map((entry) => `[${entry.level}] (${entry.kind}) ${entry.text}`).join(`
-`));
+}
+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
@@ -31502,208 +32638,359 @@ var { version: VERSION } = JSON.parse(readFileSync(new URL("../package.json", im
 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",
-    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.
+    title: `Gameface UI status`,
+    description: import_common_tags5.oneLine`
+        Check whether the Gameface UI debug endpoint is reachable and report the live page target,
+        engine info, and view-reload tracking.
+        Run this first when other game_* tools fail.
+        Calling it arms reload tracking and returns the baseline count for game_wait's sinceReloads.
       `
-  }, () => gameStatus(client));
+  }, () => gameStatus(client, reloads));
   server.registerTool("game_eval", {
-    title: "Evaluate JS in the Gameface UI",
-    description: import_common_tags4.oneLine`
+    title: `Evaluate JS in the Gameface UI`,
+    description: import_common_tags5.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.
       `,
     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",
-    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.
+    title: `Screenshot the Gameface UI`,
+    description: import_common_tags5.oneLine`
+        Capture a screenshot of the Gameface viewport and return it as an inline image; a selector
+        clips the capture to one element.
+        Clipping is the only lever on what the image costs you in context: that cost tracks the
+        pixel area captured, never the encoded file size.
+        Refuses while the JS debugger holds the UI paused: the capture needs the frame loop a
+        pause freezes.
       `,
     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, quality, selector }) => gameScreenshot(client, format, quality, selector));
+      format: exports_external.enum(["png", "jpeg"]).optional().describe(`Image format (default: png)`),
+      quality: exports_external.number().min(1).max(100).optional().describe(import_common_tags5.oneLine`
+              JPEG quality 1-100 (only used when format is jpeg; default 80).
+              Trades fidelity for transfer bytes, leaving the image's context cost unchanged.
+            `),
+      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, index }) => gameScreenshot(client, debug, { format, quality, selector, index }));
   server.registerTool("game_wait", {
-    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.
+    title: `Wait for a condition in the Gameface UI`,
+    description: import_common_tags5.oneLine`
+        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.
+        It stays usable while the JS debugger is paused, and a timeout says so when it was.
       `,
     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_tags5.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_tags5.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_tags5.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_tags5.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, debug, {
+    selector,
+    predicate,
+    reload,
+    sinceReloads,
+    quiescentMs,
+    timeoutMs,
+    visible
+  }));
   server.registerTool("game_fill", {
-    title: "Set an input value in the Gameface UI",
-    description: import_common_tags4.oneLine`
+    title: `Set an input value in the Gameface UI`,
+    description: import_common_tags5.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.
       `,
     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",
-    description: import_common_tags4.oneLine`
+    title: `Type text into the Gameface UI`,
+    description: import_common_tags5.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.
       `,
     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",
-    description: import_common_tags4.oneLine`
+    title: `Hover an element in the Gameface UI`,
+    description: import_common_tags5.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.
       `,
     inputSchema: {
-      selector: exports_external.string().describe("CSS selector of the element to hover")
-    }
-  }, ({ selector }) => gameHover(client, selector));
+      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, index }) => gameHover(client, selector, index));
+  server.registerTool("game_key", {
+    title: `Press a key in the Gameface UI`,
+    description: import_common_tags5.oneLine`
+        Press a named key by dispatching a real bubbling keydown+keyup (no keypress) in the page
+        (KeyboardEvent.key, e.g. Escape, Enter, ArrowDown, a, F5), optionally with
+        ctrl/shift/alt/meta and a repeat count.
+        It 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, else document`),
+      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",
-    description: import_common_tags4.oneLine`
+    title: `Read the Gameface UI console`,
+    description: import_common_tags5.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, each prefixed with local wall-clock time and its object arguments expanded to
+        their real values (state {a: 1, b: {c: {…}}, arr: [1, 2, 3]}).
+        Capture starts when the server first connects to the application.
+        Truncation is always marked: {…} / […] at the rendered depth, …N more past the per-level
+        cap, a trailing ellipsis inside a clipped string.
+        For unbounded depth or parseable output, read the value with game_eval + JSON.stringify.
       `,
     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, level, clear }) => gameConsole(client, consoleBuffer, { limit, level, clear }));
+      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`),
+      depth: exports_external.number().int().min(1).max(CAPTURE_DEPTH_CAP).optional().describe(import_common_tags5.oneLine`
+              How many levels of an expanded object to render (default
+              ${String(DEFAULT_RENDER_DEPTH)}).
+              Entries are captured ${String(CAPTURE_DEPTH_CAP)} levels deep, so re-reading the same
+              entries deeper works up to that cap.
+            `),
+      clear: exports_external.boolean().optional().describe(import_common_tags5.oneLine`
+            Empty the buffer once this read has taken its entries (default false).
+            It also drops captures still being expanded, so a line logged moments before the call
+            is discarded rather than surfacing on the next read.
+          `)
+    }
+  }, ({ limit, level, depth, clear }) => gameConsole(client, consoleBuffer, { limit, level, depth, clear }));
   server.registerTool("game_dom", {
-    title: "Inspect Gameface UI DOM",
-    description: import_common_tags4.oneLine`
+    title: `Inspect Gameface UI DOM`,
+    description: import_common_tags5.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.
+        outerHTML dominates the response: to locate elements, get a targetable handle, or read
+        attributes across many matches, use game_query.
       `,
     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_query", {
+    title: `Find elements in the Gameface UI`,
+    description: import_common_tags5.oneLine`
+        Locate elements in the live Gameface UI by CSS selector, by trimmed textContent
+        (equals/contains/regex, case-insensitive by default), or by both; one of the two is
+        required, and match/caseSensitive are ignored without text.
+        Returns tag, id, classes and bounding rect per match, attributes on request, with the
+        counts before and after deepest pruning and the limit, so both truncations are visible.
+        Set tag=true for data-gf-tag handles feeding game_click / game_hover / game_screenshot.
+        To read an element's markup, use game_dom.
+      `,
+    inputSchema: {
+      text: exports_external.string().optional().describe(import_common_tags5.oneLine`
+              Text to match against each element's trimmed textContent, so pass it trimmed under
+              match=equals; omit it to select on the selector alone, or pass '' with match=equals
+              and a selector for elements carrying no text.
+            `),
+      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 to match, alone or scoping the text scan (with text, defaults to *)`),
+      deepest: exports_external.boolean().optional().describe(import_common_tags5.oneLine`
+              Keep only the innermost match, pruning ancestors that also matched (default: true
+              when non-empty text drives the match, false otherwise).
+            `),
+      tag: exports_external.boolean().optional().describe(import_common_tags5.oneLine`
+              Stamp matches with data-gf-tag handles and return them as selectors, clearing any
+              prior handles first (default: false).
+            `),
+      attributes: exports_external.boolean().optional().describe(`Return each match's attributes, this tool's own data-gf-tag aside (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, attributes, limit }) => gameQuery(client, { text: text2, match, caseSensitive, selector, deepest, tag, attributes, limit }));
   server.registerTool("game_click", {
-    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.
+    title: `Click an element in the Gameface UI`,
+    description: import_common_tags5.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).
       `,
     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",
-    description: import_common_tags4.oneLine`
+    title: `JS debugger status`,
+    description: import_common_tags5.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.
+        Enables the debugger on first use.
       `,
     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",
-    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.
+    title: `List parsed UI scripts`,
+    description: import_common_tags5.oneLine`
+        List JavaScript scripts parsed in the Gameface UI (scriptId + url + line count).
+        Only scripts parsed since the debugger attached appear, since Gameface does not replay
+        scriptParsed; an empty list is what a late attach looks like, and the result says how to
+        fill it.
+        Feed the scriptId to game_debug_source; game_debug_search_source finds a position inside
+        one.
       `,
     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",
-    description: import_common_tags4.oneLine`
+    title: `Get UI script source`,
+    description: import_common_tags5.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).
+        The window is capped at 400 lines, range or not; the result says which lines it showed.
+        It renders whole lines, so a low line count is no promise of a small answer: one minified
+        line can be the whole module, and reaching a position inside such a line is
+        game_debug_search_source's job.
+      `,
+    inputSchema: {
+      scriptId: exports_external.string().describe(`Script id from game_debug_scripts`),
+      lineStart: exports_external.number().int().min(1).optional().describe(import_common_tags5.oneLine`
+            First line, 1-based and numbered as the whole file or document is, so a script embedded
+            in a page starts at its firstLine from game_debug_scripts rather than at 1.
+          `),
+      lineEnd: exports_external.number().int().min(1).optional().describe(`Last line, numbered as lineStart is`),
+      maxChars: exports_external.number().int().min(1).optional().describe(import_common_tags5.oneLine`
+              Characters of source to return before clipping (default
+              ${String(DEFAULT_SOURCE_MAX_CHARS)}); the result says when it clipped and at what.
+            `)
+    }
+  }, ({ scriptId, lineStart, lineEnd, maxChars }) => debug.getSource(scriptId, lineStart, lineEnd, maxChars));
+  server.registerTool("game_debug_search_source", {
+    title: `Search UI script sources`,
+    description: import_common_tags5.oneLine`
+        Find a literal string across the parsed script sources and return each hit as
+        url + line + column (1-based) with a snippet of surrounding source.
+        The query is case-sensitive and literal, no regex; read the total/truncated fields for what
+        the ${MAX_SEARCH_MATCHES}-match cap hid.
+        This is how you target a column in a minified one-line bundle, where a line breakpoint binds
+        to module-evaluation code that never runs during interaction: search for the code you mean,
+        then pass its line and column to game_debug_set_breakpoint.
       `,
     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)")
+      query: exports_external.string().min(1).describe(`Literal string to find (case-sensitive, not a regex)`),
+      urlContains: exports_external.string().optional().describe(`Only search scripts whose url contains this substring (case-insensitive)`)
     }
-  }, ({ scriptId, lineStart, lineEnd }) => debug.getSource(scriptId, lineStart, lineEnd));
+  }, ({ query, urlContains }) => debug.searchSource(query, urlContains));
   server.registerTool("game_debug_set_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.
+    title: `Set a breakpoint`,
+    description: import_common_tags5.oneLine`
+        Set a breakpoint by url substring + line, and optionally column; both are 1-based.
+        A condition limits how often the UI freezes; a line alone can bind somewhere that never
+        runs again, so check the resolved location the result reports back.
+        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(import_common_tags5.oneLine`
+            Substring of the script url to break in, matched case-sensitively; copy it from the url
+            game_debug_scripts or game_debug_search_source printed, whose own filters are not.
+          `),
+      line: exports_external.number().int().min(1).describe(`Line number (1-based)`),
+      column: exports_external.number().int().min(1).optional().describe(`Column (1-based), optional; take one from game_debug_search_source`),
+      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",
-    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.
+    title: `Inspect the paused stack`,
+    description: import_common_tags5.oneLine`
+        When paused, return the call stack (frames with function + location + scope types);
+        '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",
-    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.
+    title: `Evaluate while debugging`,
+    description: import_common_tags5.oneLine`
+        Evaluate a JS expression.
+        When paused, it runs in the selected call frame's scope 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",
-    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.
+    title: `Step / resume / pause execution`,
+    description: import_common_tags5.oneLine`
+        Control paused execution: resume (unfreeze the UI), over/into/out (step), or pause (break at
+        the next statement).
+        Stepping reports the new location, and resume fails rather than claiming success when the
+        UI is paused again the moment it continues (a breakpoint on the resumed path).
       `,
     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;