@reconcrap/boss-recommend-mcp 2.0.4 → 2.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reconcrap/boss-recommend-mcp",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "Unified MCP pipeline for recommend-page filtering and screening on Boss Zhipin",
   "keywords": [
     "boss",

package/src/chat-mcp.js

@@ -494,7 +494,8 @@ async function waitForHealthyChat(client, config, {
       domain: "chat",
       roots: roots.roots,
       selectorProbes: config.selectorProbes,
-      accessibilityProbes: config.accessibilityProbes
+      accessibilityProbes: config.accessibilityProbes,
+      viewportProbes: config.viewportProbes
     });
     if (lastCheck.status === HEALTH_STATUS.HEALTHY) return lastCheck;
     await sleep(intervalMs);

package/src/core/browser/index.js

@@ -10,6 +10,7 @@ export const BOSS_LOGIN_URL = "https://www.zhipin.com/web/user/?ka=bticket";
 
 export const ALLOWED_CDP_DOMAINS = new Set([
   "Accessibility",
+  "Browser",
   "DOM",
   "Input",
   "Network",

package/src/core/self-heal/index.js

@@ -5,6 +5,26 @@ import {
   querySelectorAll,
   sleep
 } from "../browser/index.js";
+import {
+  compactViewportHealthResult,
+  ensureHealthyViewport
+} from "./viewport.js";
+
+export {
+  buildViewportHealthDiagnostics,
+  compactViewportHealthResult,
+  compactViewportState,
+  createViewportRunGuard,
+  ensureHealthyViewport,
+  getCurrentWindowInfo,
+  isListViewportCollapsed,
+  readViewportState,
+  setWindowStateIfPossible,
+  toggleWindowStateForViewportRecovery,
+  VIEWPORT_COLLAPSE_MIN_EXPECTED_WIDTH,
+  VIEWPORT_COLLAPSE_NEAR_FULLSCREEN_RATIO,
+  VIEWPORT_COLLAPSE_RATIO_THRESHOLD
+} from "./viewport.js";
 
 export const PROBE_STATUS = Object.freeze({
   PASS: "pass",
@@ -245,6 +265,26 @@ export function createNetworkProbe({
   };
 }
 
+export function createViewportCollapseProbe({
+  id = "viewport_collapse",
+  root = "frame",
+  frameOwnerRoot = "frameOwner",
+  required = true,
+  repair = true,
+  description = ""
+} = {}) {
+  if (!id) throw new Error("Viewport collapse probe requires an id");
+  return {
+    type: "viewport",
+    id,
+    root,
+    frameOwnerRoot,
+    required: Boolean(required),
+    repair: Boolean(repair),
+    description
+  };
+}
+
 export async function runSelectorProbe(client, roots, probe) {
   const nodeId = rootNodeId(roots, probe.root);
   if (!nodeId) {
@@ -338,6 +378,52 @@ export function runNetworkProbe(networkEvents = [], probe) {
   };
 }
 
+export async function runViewportCollapseProbe(client, roots, probe) {
+  const nodeId = rootNodeId(roots, probe.root);
+  if (!nodeId) {
+    return {
+      ...probe,
+      ok: !probe.required,
+      status: probe.required ? PROBE_STATUS.BLOCKED : PROBE_STATUS.OPTIONAL_ABSENT,
+      count: 0,
+      collapsed: false,
+      recovered: false,
+      error: `Root not found: ${probe.root}`
+    };
+  }
+
+  try {
+    const health = await ensureHealthyViewport(client, {
+      roots,
+      root: probe.root,
+      frameOwnerRoot: probe.frameOwnerRoot,
+      reason: probe.id,
+      repair: probe.repair
+    });
+    const ok = Boolean(health.ok);
+    return {
+      ...probe,
+      ok: probe.required ? ok : true,
+      status: ok ? PROBE_STATUS.PASS : probe.required ? PROBE_STATUS.FAIL : PROBE_STATUS.OPTIONAL_ABSENT,
+      count: ok ? 1 : 0,
+      collapsed: Boolean(health.collapsed),
+      recovered: Boolean(health.recovered),
+      viewport_health: compactViewportHealthResult(health),
+      error: health.error || null
+    };
+  } catch (error) {
+    return {
+      ...probe,
+      ok: !probe.required,
+      status: probe.required ? PROBE_STATUS.ERROR : PROBE_STATUS.OPTIONAL_ABSENT,
+      count: 0,
+      collapsed: false,
+      recovered: false,
+      error: error?.message || String(error)
+    };
+  }
+}
+
 export function summarizeProbeResults(probes = []) {
   const required = probes.filter((probe) => probe.required);
   const blocked = required.filter((probe) => probe.status === PROBE_STATUS.BLOCKED);
@@ -370,6 +456,7 @@ export function buildDriftReport(probes = []) {
       expected_min_count: probe.minCount,
       observed_count: probe.count || 0,
       selectors: probe.selectors || [],
+      viewport_health: probe.viewport_health || undefined,
       error: probe.error || null
     }));
 }
@@ -380,6 +467,7 @@ export async function runSelfHealCheck({
   roots = {},
   selectorProbes = [],
   accessibilityProbes = [],
+  viewportProbes = [],
   networkProbes = [],
   networkEvents = []
 } = {}) {
@@ -393,8 +481,13 @@ export async function runSelfHealCheck({
     accessibilityResults.push(await runAccessibilityProbe(client, probe));
   }
 
+  const viewportResults = [];
+  for (const probe of viewportProbes) {
+    viewportResults.push(await runViewportCollapseProbe(client, roots, probe));
+  }
+
   const networkResults = networkProbes.map((probe) => runNetworkProbe(networkEvents, probe));
-  const probes = [...selectorResults, ...accessibilityResults, ...networkResults];
+  const probes = [...selectorResults, ...accessibilityResults, ...viewportResults, ...networkResults];
   const summary = summarizeProbeResults(probes);
 
   return {
@@ -507,6 +600,16 @@ export function buildRecommendSelfHealConfig(rules = {}) {
         description: "Candidate detail popup may mount inside the recommend frame"
       })
     ],
+    viewportProbes: [
+      createViewportCollapseProbe({
+        id: "recommend_viewport_collapse",
+        root: "frame",
+        frameOwnerRoot: "frameOwner",
+        required: true,
+        repair: true,
+        description: "Recommend frame/list viewport has not collapsed relative to the Chrome window"
+      })
+    ],
     accessibilityProbes: [
       createAccessibilityProbe({
         id: "accessibility_tree",
@@ -610,6 +713,16 @@ export function buildRecruitSelfHealConfig(rules = {}) {
         description: "Candidate detail popup may mount inside the search frame"
       })
     ],
+    viewportProbes: [
+      createViewportCollapseProbe({
+        id: "recruit_viewport_collapse",
+        root: "frame",
+        frameOwnerRoot: "frameOwner",
+        required: true,
+        repair: true,
+        description: "Search frame/list viewport has not collapsed relative to the Chrome window"
+      })
+    ],
     accessibilityProbes: [
       createAccessibilityProbe({
         id: "accessibility_tree",
@@ -711,6 +824,16 @@ export function buildChatSelfHealConfig(rules = {}) {
         description: "Resume iframe appears after the online resume is opened"
       })
     ],
+    viewportProbes: [
+      createViewportCollapseProbe({
+        id: "chat_viewport_collapse",
+        root: "top",
+        frameOwnerRoot: "top",
+        required: true,
+        repair: true,
+        description: "Chat list viewport has not collapsed relative to the Chrome window"
+      })
+    ],
     accessibilityProbes: [
       createAccessibilityProbe({
         id: "accessibility_tree",
@@ -756,7 +879,8 @@ export async function resolveRecommendSelfHealRoots(client, config = buildRecomm
   return {
     roots: {
       top: topRoot.nodeId,
-      frame: iframe.documentNodeId
+      frame: iframe.documentNodeId,
+      frameOwner: iframe.nodeId
     },
     topRoot,
     iframe
@@ -779,7 +903,8 @@ export async function resolveRecruitSelfHealRoots(client, config = buildRecruitS
   return {
     roots: {
       top: topRoot.nodeId,
-      frame: iframe.documentNodeId
+      frame: iframe.documentNodeId,
+      frameOwner: iframe.nodeId
     },
     topRoot,
     iframe

package/src/core/self-heal/viewport.js

@@ -0,0 +1,564 @@
+import {
+  getNodeBox,
+  querySelector,
+  sleep
+} from "../browser/index.js";
+
+export const VIEWPORT_COLLAPSE_RATIO_THRESHOLD = 0.6;
+export const VIEWPORT_COLLAPSE_MIN_EXPECTED_WIDTH = 1000;
+export const VIEWPORT_COLLAPSE_NEAR_FULLSCREEN_RATIO = 0.85;
+
+const ABSOLUTE_COLLAPSE_LIMITS = Object.freeze({
+  clientHeight: 260,
+  clientWidth: 280,
+  frameHeight: 320,
+  frameWidth: 460,
+  viewportHeight: 260,
+  viewportWidth: 360
+});
+
+function normalizeText(value) {
+  return String(value ?? "").replace(/\s+/g, " ").trim();
+}
+
+function getPositiveNumber(...values) {
+  for (const value of values) {
+    const number = Number(value);
+    if (Number.isFinite(number) && number > 0) return number;
+  }
+  return 0;
+}
+
+function rootNodeId(roots = {}, name) {
+  const root = roots[name];
+  if (typeof root === "number") return root;
+  if (root?.nodeId) return root.nodeId;
+  if (root?.documentNodeId) return root.documentNodeId;
+  return 0;
+}
+
+function compactRect(rect = {}) {
+  return {
+    width: getPositiveNumber(rect.width),
+    height: getPositiveNumber(rect.height)
+  };
+}
+
+function pickViewportSize(layoutMetrics = {}, axis = "width") {
+  const clientKey = axis === "width" ? "clientWidth" : "clientHeight";
+  return getPositiveNumber(
+    layoutMetrics?.cssVisualViewport?.[clientKey],
+    layoutMetrics?.cssLayoutViewport?.[clientKey],
+    layoutMetrics?.visualViewport?.[clientKey],
+    layoutMetrics?.layoutViewport?.[clientKey]
+  );
+}
+
+async function getLayoutMetrics(client) {
+  if (typeof client?.Page?.getLayoutMetrics !== "function") return null;
+  try {
+    return await client.Page.getLayoutMetrics();
+  } catch {
+    return null;
+  }
+}
+
+export async function getCurrentWindowInfo(client) {
+  if (typeof client?.Browser?.getWindowForTarget !== "function") {
+    return {
+      ok: false,
+      unsupported: true,
+      error: "Browser.getWindowForTarget is not available"
+    };
+  }
+
+  try {
+    const targetWindow = await client.Browser.getWindowForTarget({});
+    let bounds = targetWindow?.bounds || null;
+    if (
+      targetWindow?.windowId
+      && typeof client?.Browser?.getWindowBounds === "function"
+    ) {
+      const currentBounds = await client.Browser.getWindowBounds({
+        windowId: targetWindow.windowId
+      });
+      bounds = currentBounds?.bounds || bounds;
+    }
+    return {
+      ok: true,
+      windowId: targetWindow?.windowId || null,
+      bounds
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error?.message || String(error)
+    };
+  }
+}
+
+async function readBox(client, nodeId) {
+  if (!nodeId) return null;
+  try {
+    return await getNodeBox(client, nodeId);
+  } catch {
+    return null;
+  }
+}
+
+async function readBestContentBox(client, rootNodeIdValue) {
+  const directBox = await readBox(client, rootNodeIdValue);
+  if (directBox?.rect?.width && directBox?.rect?.height) return directBox;
+
+  for (const selector of ["body", "html"]) {
+    const nodeId = await querySelector(client, rootNodeIdValue, selector).catch(() => 0);
+    const box = await readBox(client, nodeId);
+    if (box?.rect?.width && box?.rect?.height) return box;
+  }
+  return directBox;
+}
+
+export function buildViewportHealthDiagnostics(state, windowInfo = null, layoutMetrics = null) {
+  const topViewport = state?.topViewport || {};
+  const bounds = windowInfo?.bounds || null;
+  const windowState = normalizeText(bounds?.windowState || "").toLowerCase() || null;
+  const windowWidth = getPositiveNumber(bounds?.width);
+  const screenAvailWidth = getPositiveNumber(topViewport.screenAvailWidth);
+  const topOuterWidth = getPositiveNumber(topViewport.outerWidth);
+  const actualWidth = getPositiveNumber(
+    layoutMetrics?.cssVisualViewport?.clientWidth,
+    layoutMetrics?.cssLayoutViewport?.clientWidth,
+    topViewport.visualWidth,
+    topViewport.innerWidth,
+    state?.viewport?.width,
+    state?.clientWidth,
+    state?.frameRect?.width
+  );
+  const actualHeight = getPositiveNumber(
+    layoutMetrics?.cssVisualViewport?.clientHeight,
+    layoutMetrics?.cssLayoutViewport?.clientHeight,
+    topViewport.visualHeight,
+    topViewport.innerHeight,
+    state?.viewport?.height,
+    state?.clientHeight,
+    state?.frameRect?.height
+  );
+  const hasScreenWidth = screenAvailWidth > 0;
+  const nearFullscreen = Boolean(
+    windowState === "maximized"
+    || (
+      windowWidth > 0
+      && hasScreenWidth
+      && windowWidth >= screenAvailWidth * VIEWPORT_COLLAPSE_NEAR_FULLSCREEN_RATIO
+    )
+    || (
+      topOuterWidth > 0
+      && hasScreenWidth
+      && topOuterWidth >= screenAvailWidth * VIEWPORT_COLLAPSE_NEAR_FULLSCREEN_RATIO
+    )
+  );
+  const fallbackExpectedWidth = getPositiveNumber(screenAvailWidth, windowWidth, topOuterWidth);
+  let expectedWidth = 0;
+  if (windowWidth > 0) {
+    expectedWidth = hasScreenWidth && windowWidth >= screenAvailWidth * VIEWPORT_COLLAPSE_NEAR_FULLSCREEN_RATIO
+      ? Math.min(windowWidth, screenAvailWidth)
+      : windowWidth;
+  } else if (topOuterWidth > 0) {
+    expectedWidth = hasScreenWidth && topOuterWidth >= screenAvailWidth * VIEWPORT_COLLAPSE_NEAR_FULLSCREEN_RATIO
+      ? Math.min(topOuterWidth, screenAvailWidth)
+      : topOuterWidth;
+  } else {
+    expectedWidth = fallbackExpectedWidth;
+  }
+  const widthRatio = actualWidth > 0 && expectedWidth > 0
+    ? actualWidth / expectedWidth
+    : null;
+  const relativeCollapsed = Boolean(
+    nearFullscreen
+    && expectedWidth >= VIEWPORT_COLLAPSE_MIN_EXPECTED_WIDTH
+    && actualWidth > 0
+    && widthRatio !== null
+    && widthRatio <= VIEWPORT_COLLAPSE_RATIO_THRESHOLD
+  );
+
+  return {
+    threshold: VIEWPORT_COLLAPSE_RATIO_THRESHOLD,
+    minExpectedWidth: VIEWPORT_COLLAPSE_MIN_EXPECTED_WIDTH,
+    nearFullscreen,
+    windowState,
+    windowWidth,
+    screenAvailWidth,
+    topOuterWidth,
+    actualWidth,
+    actualHeight,
+    expectedWidth,
+    widthRatio,
+    relativeCollapsed
+  };
+}
+
+export function isListViewportCollapsed(state) {
+  if (!state?.ok) return false;
+  if (state.viewportDiagnostics?.relativeCollapsed === true) return true;
+  const clientHeight = Number(state.clientHeight || 0);
+  const clientWidth = Number(state.clientWidth || 0);
+  const frameWidth = Number(state.frameRect?.width || 0);
+  const frameHeight = Number(state.frameRect?.height || 0);
+  const viewportWidth = Number(state.viewport?.width || 0);
+  const viewportHeight = Number(state.viewport?.height || 0);
+
+  return (
+    (clientHeight > 0 && clientHeight < ABSOLUTE_COLLAPSE_LIMITS.clientHeight)
+    || (clientWidth > 0 && clientWidth < ABSOLUTE_COLLAPSE_LIMITS.clientWidth)
+    || (frameHeight > 0 && frameHeight < ABSOLUTE_COLLAPSE_LIMITS.frameHeight)
+    || (frameWidth > 0 && frameWidth < ABSOLUTE_COLLAPSE_LIMITS.frameWidth)
+    || (viewportHeight > 0 && viewportHeight < ABSOLUTE_COLLAPSE_LIMITS.viewportHeight)
+    || (viewportWidth > 0 && viewportWidth < ABSOLUTE_COLLAPSE_LIMITS.viewportWidth)
+  );
+}
+
+export async function readViewportState(client, {
+  roots = {},
+  root = "frame",
+  frameOwnerRoot = "frameOwner"
+} = {}) {
+  const targetRootNodeId = rootNodeId(roots, root);
+  if (!targetRootNodeId) {
+    return {
+      ok: false,
+      root,
+      error: `Root not found: ${root}`
+    };
+  }
+
+  const layoutMetrics = await getLayoutMetrics(client);
+  const windowInfo = await getCurrentWindowInfo(client);
+  const contentBox = await readBestContentBox(client, targetRootNodeId);
+  const ownerNodeId = rootNodeId(roots, frameOwnerRoot);
+  const ownerBox = ownerNodeId ? await readBox(client, ownerNodeId) : null;
+  const frameRect = compactRect(ownerBox?.rect || contentBox?.rect || {});
+  const clientWidth = getPositiveNumber(
+    contentBox?.rect?.width,
+    frameRect.width,
+    pickViewportSize(layoutMetrics, "width")
+  );
+  const clientHeight = getPositiveNumber(
+    contentBox?.rect?.height,
+    frameRect.height,
+    pickViewportSize(layoutMetrics, "height")
+  );
+  const viewportWidth = pickViewportSize(layoutMetrics, "width") || clientWidth;
+  const viewportHeight = pickViewportSize(layoutMetrics, "height") || clientHeight;
+  const bounds = windowInfo?.bounds || {};
+  const topViewport = {
+    innerWidth: viewportWidth,
+    innerHeight: viewportHeight,
+    outerWidth: getPositiveNumber(bounds.width, viewportWidth),
+    outerHeight: getPositiveNumber(bounds.height, viewportHeight),
+    visualWidth: getPositiveNumber(layoutMetrics?.cssVisualViewport?.clientWidth, viewportWidth),
+    visualHeight: getPositiveNumber(layoutMetrics?.cssVisualViewport?.clientHeight, viewportHeight),
+    screenAvailWidth: getPositiveNumber(bounds.width),
+    screenAvailHeight: getPositiveNumber(bounds.height),
+    devicePixelRatio: getPositiveNumber(layoutMetrics?.cssVisualViewport?.scale, 1)
+  };
+  const state = {
+    ok: true,
+    root,
+    rootNodeId: targetRootNodeId,
+    frameOwnerRoot,
+    frameOwnerNodeId: ownerNodeId || null,
+    clientWidth,
+    clientHeight,
+    frameRect,
+    viewport: {
+      width: viewportWidth,
+      height: viewportHeight
+    },
+    topViewport,
+    windowInfo
+  };
+  state.viewportDiagnostics = buildViewportHealthDiagnostics(state, windowInfo, layoutMetrics);
+  state.collapsed = isListViewportCollapsed(state);
+  return state;
+}
+
+export async function setWindowStateIfPossible(client, windowState, reason = "viewport_recovery") {
+  const windowInfo = await getCurrentWindowInfo(client);
+  if (!windowInfo.ok || !windowInfo.windowId || typeof client?.Browser?.setWindowBounds !== "function") {
+    return {
+      ok: false,
+      reason,
+      windowState,
+      error: windowInfo.error || "Browser.setWindowBounds is not available"
+    };
+  }
+
+  try {
+    await client.Browser.setWindowBounds({
+      windowId: windowInfo.windowId,
+      bounds: {
+        windowState
+      }
+    });
+    return {
+      ok: true,
+      reason,
+      windowState,
+      windowId: windowInfo.windowId,
+      before: windowInfo.bounds || null
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      reason,
+      windowState,
+      windowId: windowInfo.windowId,
+      error: error?.message || String(error)
+    };
+  }
+}
+
+export async function toggleWindowStateForViewportRecovery(client, {
+  reason = "viewport_recovery",
+  settleMs = 520,
+  bringToFront = true
+} = {}) {
+  const currentInfo = await getCurrentWindowInfo(client);
+  const currentState = normalizeText(currentInfo?.bounds?.windowState || "").toLowerCase();
+  const sequence = currentState === "normal"
+    ? ["maximized", "normal"]
+    : ["normal", "maximized"];
+  const attempts = [];
+
+  for (const windowState of sequence) {
+    const attempt = await setWindowStateIfPossible(client, windowState, reason);
+    attempts.push(attempt);
+    if (attempt.ok && settleMs > 0) await sleep(settleMs);
+  }
+
+  if (bringToFront && typeof client?.Page?.bringToFront === "function") {
+    await client.Page.bringToFront();
+  }
+
+  return {
+    ok: attempts.some((attempt) => attempt.ok),
+    applied: attempts.some((attempt) => attempt.ok),
+    reason,
+    current_state: currentState || null,
+    sequence,
+    attempts
+  };
+}
+
+export function compactViewportState(state = null) {
+  if (!state) return null;
+  return {
+    ok: Boolean(state.ok),
+    root: state.root || null,
+    error: state.error || null,
+    clientWidth: state.clientWidth || 0,
+    clientHeight: state.clientHeight || 0,
+    frameRect: state.frameRect || null,
+    viewport: state.viewport || null,
+    topViewport: state.topViewport
+      ? {
+          innerWidth: state.topViewport.innerWidth || 0,
+          innerHeight: state.topViewport.innerHeight || 0,
+          outerWidth: state.topViewport.outerWidth || 0,
+          outerHeight: state.topViewport.outerHeight || 0,
+          visualWidth: state.topViewport.visualWidth || 0,
+          visualHeight: state.topViewport.visualHeight || 0,
+          screenAvailWidth: state.topViewport.screenAvailWidth || 0,
+          screenAvailHeight: state.topViewport.screenAvailHeight || 0,
+          devicePixelRatio: state.topViewport.devicePixelRatio || 0
+        }
+      : null,
+    viewportDiagnostics: state.viewportDiagnostics || null,
+    collapsed: Boolean(state.collapsed)
+  };
+}
+
+export function compactViewportHealthResult(result = null) {
+  if (!result) return null;
+  return {
+    ok: Boolean(result.ok),
+    collapsed: Boolean(result.collapsed),
+    recovered: Boolean(result.recovered),
+    reason: result.reason || null,
+    state: compactViewportState(result.state),
+    before: compactViewportState(result.before),
+    repair: result.repair
+      ? {
+          ok: Boolean(result.repair.ok),
+          applied: Boolean(result.repair.applied),
+          current_state: result.repair.current_state || null,
+          sequence: result.repair.sequence || [],
+          attempts: (result.repair.attempts || []).map((attempt) => ({
+            ok: Boolean(attempt.ok),
+            windowState: attempt.windowState,
+            error: attempt.error || null
+          }))
+        }
+      : null,
+    error: result.error || null
+  };
+}
+
+export async function ensureHealthyViewport(client, {
+  roots = {},
+  root = "frame",
+  frameOwnerRoot = "frameOwner",
+  reason = "viewport_recovery",
+  repair = true,
+  recoveryDelayMs = 900
+} = {}) {
+  const before = await readViewportState(client, {
+    roots,
+    root,
+    frameOwnerRoot
+  });
+  if (!before.ok) {
+    return {
+      ok: false,
+      collapsed: false,
+      recovered: false,
+      reason,
+      state: before,
+      error: before.error || "viewport state could not be read"
+    };
+  }
+
+  if (!isListViewportCollapsed(before)) {
+    return {
+      ok: true,
+      collapsed: false,
+      recovered: false,
+      reason,
+      state: before
+    };
+  }
+
+  if (!repair) {
+    return {
+      ok: false,
+      collapsed: true,
+      recovered: false,
+      reason,
+      before,
+      state: before,
+      error: "viewport collapsed and repair disabled"
+    };
+  }
+
+  const repairResult = await toggleWindowStateForViewportRecovery(client, { reason });
+  if (recoveryDelayMs > 0) await sleep(recoveryDelayMs);
+  const after = await readViewportState(client, {
+    roots,
+    root,
+    frameOwnerRoot
+  });
+  const stillCollapsed = isListViewportCollapsed(after);
+  return {
+    ok: after.ok && !stillCollapsed,
+    collapsed: stillCollapsed,
+    recovered: after.ok && !stillCollapsed && repairResult.applied,
+    reason,
+    before,
+    state: after,
+    repair: repairResult,
+    error: after.ok && !stillCollapsed
+      ? null
+      : "viewport collapsed after recovery attempt"
+  };
+}
+
+export function createViewportRunGuard({
+  client,
+  domain = "boss",
+  root = "frame",
+  frameOwnerRoot = "frameOwner",
+  runControl = null,
+  getRoots = null,
+  rootNodesFromState = (rootState) => rootState?.rootNodes || rootState?.roots || rootState || {},
+  repair = true,
+  maxEvents = 10
+} = {}) {
+  if (!client) throw new Error("createViewportRunGuard requires a guarded CDP client");
+  const events = [];
+  const stats = {
+    checks: 0,
+    recoveries: 0,
+    failures: 0
+  };
+
+  function recordEvent(phase, health) {
+    const compact = compactViewportHealthResult(health);
+    const shouldRecord = Boolean(health?.recovered || !health?.ok || health?.collapsed);
+    if (!shouldRecord) return compact;
+    const event = {
+      phase,
+      at: new Date().toISOString(),
+      ...compact
+    };
+    events.push(event);
+    if (events.length > maxEvents) events.shift();
+    if (runControl) {
+      runControl.checkpoint({
+        viewport_health: event,
+        viewport_health_events: events.slice(),
+        viewport_health_stats: { ...stats }
+      });
+    }
+    return compact;
+  }
+
+  async function ensure(rootState, {
+    phase = "run",
+    reason = `${domain}:${phase}`
+  } = {}) {
+    let currentRootState = rootState;
+    if (!currentRootState && typeof getRoots === "function") {
+      currentRootState = await getRoots(client);
+    }
+    const roots = rootNodesFromState(currentRootState);
+    stats.checks += 1;
+    const health = await ensureHealthyViewport(client, {
+      roots,
+      root,
+      frameOwnerRoot,
+      reason,
+      repair
+    });
+    if (health.recovered) stats.recoveries += 1;
+    if (!health.ok) stats.failures += 1;
+    const compact = recordEvent(phase, health);
+    if (!health.ok) {
+      const error = new Error(`${String(domain).toUpperCase()}_LIST_VIEWPORT_COLLAPSED`);
+      error.code = "LIST_VIEWPORT_COLLAPSED";
+      error.domain = domain;
+      error.phase = phase;
+      error.viewport_health = compact;
+      throw error;
+    }
+    if (health.recovered && typeof getRoots === "function") {
+      currentRootState = await getRoots(client);
+    }
+    return {
+      rootState: currentRootState,
+      health,
+      compact,
+      stats: { ...stats },
+      events: events.slice()
+    };
+  }
+
+  return {
+    ensure,
+    getStats() {
+      return { ...stats };
+    },
+    getEvents() {
+      return events.slice();
+    }
+  };
+}

package/src/domains/chat/run-service.js

@@ -22,6 +22,7 @@ import {
   getNextInfiniteListCandidate,
   markInfiniteListCandidateProcessed
 } from "../../core/infinite-list/index.js";
+import { createViewportRunGuard } from "../../core/self-heal/index.js";
 import { createRunLifecycleManager } from "../../core/run/index.js";
 import {
   callScreeningLlm,
@@ -250,9 +251,13 @@ async function setupChatRunContext(client, {
   normalizedStartFrom,
   readyTimeoutMs,
   listSettleMs,
-  runControl
+  runControl,
+  ensureViewport = null
 } = {}) {
-  const rootState = await getChatRoots(client);
+  let rootState = await getChatRoots(client);
+  if (ensureViewport) {
+    rootState = await ensureViewport(rootState, "context_roots");
+  }
   runControl.checkpoint({
     top_document_node_id: rootState.rootNodes.top
   });
@@ -280,6 +285,10 @@ async function setupChatRunContext(client, {
   if (normalizeText(job) && !jobSelection.selected) {
     throw new Error(`Chat job selection failed: ${jobSelection.reason || "unknown"}`);
   }
+  rootState = await getChatRoots(client);
+  if (ensureViewport) {
+    rootState = await ensureViewport(rootState, "context_job");
+  }
   runControl.checkpoint({
     chat_context_step: "job_selection",
     primary_label: primaryLabel,
@@ -294,6 +303,10 @@ async function setupChatRunContext(client, {
   if (!startFilter.ok) {
     throw new Error(`Chat start filter selection failed: ${startFilter.error || "unknown"}`);
   }
+  rootState = await getChatRoots(client);
+  if (ensureViewport) {
+    rootState = await ensureViewport(rootState, "context_start_filter");
+  }
   runControl.checkpoint({
     chat_context_step: "start_filter",
     primary_label: primaryLabel,
@@ -362,6 +375,18 @@ export async function runChatWorkflow({
     domain: "chat",
     listName: "chat-candidates"
   });
+  const viewportGuard = createViewportRunGuard({
+    client,
+    domain: "chat",
+    root: "top",
+    frameOwnerRoot: "top",
+    runControl,
+    getRoots: getChatRoots
+  });
+  async function ensureChatViewport(rootState, phase) {
+    const result = await viewportGuard.ensure(rootState, { phase });
+    return result.rootState || rootState;
+  }
   const results = [];
   let cardNodeIds = [];
   let listEndReason = "";
@@ -398,7 +423,8 @@ export async function runChatWorkflow({
     normalizedStartFrom,
     readyTimeoutMs,
     listSettleMs,
-    runControl
+    runControl,
+    ensureViewport: ensureChatViewport
   });
   let rootState = setup.rootState;
   contextSetup = {
@@ -431,7 +457,8 @@ export async function runChatWorkflow({
       normalizedStartFrom,
       readyTimeoutMs,
       listSettleMs,
-      runControl
+      runControl,
+      ensureViewport: ensureChatViewport
     });
     rootState = recoveredSetup.rootState;
     contextSetup = {
@@ -449,7 +476,7 @@ export async function runChatWorkflow({
   await runControl.waitIfPaused();
   runControl.throwIfCanceled();
   runControl.setPhase("chat:cards");
-  const cardRootState = await getChatRoots(client);
+  const cardRootState = await ensureChatViewport(await getChatRoots(client), "cards");
   const initialCards = await waitForChatCandidateNodeIds(client, cardRootState.rootNodes.top, {
     timeoutMs: cardTimeoutMs,
     intervalMs: 500
@@ -479,7 +506,9 @@ export async function runChatWorkflow({
       request_skipped: 0,
       unique_seen: compactInfiniteListState(listState).seen_count,
       scroll_count: compactInfiniteListState(listState).scroll_count,
-      list_end_reason: listEndReason
+      list_end_reason: listEndReason,
+      viewport_checks: viewportGuard.getStats().checks,
+      viewport_recoveries: viewportGuard.getStats().recoveries
     });
     runControl.setPhase("chat:done");
     return {
@@ -493,6 +522,10 @@ export async function runChatWorkflow({
         requested_start_from: normalizedStartFrom
       },
       candidate_list: compactInfiniteListState(listState),
+      viewport_health: {
+        stats: viewportGuard.getStats(),
+        events: viewportGuard.getEvents()
+      },
       list_end_reason: listEndReason,
       target_pass_count: passTarget,
       process_until_list_end: Boolean(processUntilListEnd),
@@ -524,7 +557,9 @@ export async function runChatWorkflow({
     request_satisfied: 0,
     request_skipped: 0,
     unique_seen: compactInfiniteListState(listState).seen_count,
-    scroll_count: 0
+    scroll_count: 0,
+    viewport_checks: viewportGuard.getStats().checks,
+    viewport_recoveries: viewportGuard.getStats().recoveries
   });
 
   while (
@@ -537,6 +572,7 @@ export async function runChatWorkflow({
     await runControl.waitIfPaused();
     runControl.throwIfCanceled();
     runControl.setPhase("chat:candidate");
+    rootState = await ensureChatViewport(rootState, "candidate_loop");
     const loopTopLevelState = await getChatTopLevelState(client);
     if (!loopTopLevelState.is_chat_shell) {
       await recoverAndReapplyChatContext("candidate_loop_non_chat_shell", {
@@ -554,7 +590,8 @@ export async function runChatWorkflow({
       settleMs: listSettleMs,
       fallbackPoint: listFallbackPoint,
       findNodeIds: async () => {
-        const currentRootState = await getChatRoots(client);
+        const currentRootState = await ensureChatViewport(await getChatRoots(client), "candidate_find_nodes");
+        rootState = currentRootState;
         const currentCards = await waitForChatCandidateNodeIds(client, currentRootState.rootNodes.top, {
           timeoutMs: Math.min(cardTimeoutMs, 8000),
           intervalMs: 500
@@ -609,6 +646,7 @@ export async function runChatWorkflow({
         await runControl.waitIfPaused();
         runControl.throwIfCanceled();
         runControl.setPhase("chat:detail");
+        rootState = await ensureChatViewport(rootState, "detail");
 
         detailStep = "select_candidate";
         networkRecorder.clear();
@@ -921,6 +959,8 @@ export async function runChatWorkflow({
       unique_seen: compactInfiniteListState(listState).seen_count,
       scroll_count: compactInfiniteListState(listState).scroll_count,
       list_end_reason: listEndReason || null,
+      viewport_checks: viewportGuard.getStats().checks,
+      viewport_recoveries: viewportGuard.getStats().recoveries,
       last_candidate_id: screeningCandidate.id || null,
       last_candidate_key: candidateKey,
       last_score: screening.score
@@ -950,6 +990,10 @@ export async function runChatWorkflow({
     card_count: cardNodeIds.length,
     context_setup: contextSetup,
     candidate_list: compactInfiniteListState(listState),
+    viewport_health: {
+      stats: viewportGuard.getStats(),
+      events: viewportGuard.getEvents()
+    },
     list_end_reason: listEndReason || null,
     target_pass_count: passTarget,
     process_until_list_end: Boolean(processUntilListEnd),

package/src/domains/recommend/roots.js

@@ -25,7 +25,8 @@ export async function getRecommendRoots(client, {
     ].filter(Boolean),
     rootNodes: {
       top: topRoot.nodeId,
-      frame: iframe?.documentNodeId || 0
+      frame: iframe?.documentNodeId || 0,
+      frameOwner: iframe?.nodeId || 0
     }
   };
 }
@@ -49,7 +50,8 @@ export async function waitForRecommendRoots(client, {
         roots: [],
         rootNodes: {
           top: 0,
-          frame: 0
+          frame: 0,
+          frameOwner: 0
         }
       };
     }

package/src/domains/recommend/run-service.js

@@ -20,6 +20,7 @@ import {
   markInfiniteListCandidateProcessed,
   resetInfiniteListForRefreshRound
 } from "../../core/infinite-list/index.js";
+import { createViewportRunGuard } from "../../core/self-heal/index.js";
 import { screenCandidate } from "../../core/screening/index.js";
 import {
   closeRecommendDetail,
@@ -372,6 +373,18 @@ export async function runRecommendWorkflow({
     domain: "recommend",
     listName: "recommend-candidates"
   });
+  const viewportGuard = createViewportRunGuard({
+    client,
+    domain: "recommend",
+    root: "frame",
+    frameOwnerRoot: "frameOwner",
+    runControl,
+    getRoots: getRecommendRoots
+  });
+  async function ensureRecommendViewport(rootState, phase) {
+    const result = await viewportGuard.ensure(rootState, { phase });
+    return result.rootState || rootState;
+  }
   const results = [];
   const refreshAttempts = [];
   let refreshRounds = 0;
@@ -389,6 +402,7 @@ export async function runRecommendWorkflow({
   runControl.throwIfCanceled();
   runControl.setPhase("recommend:roots");
   let rootState = await getRecommendRoots(client);
+  rootState = await ensureRecommendViewport(rootState, "roots");
   runControl.checkpoint({
     iframe_selector: rootState.iframe.selector,
     iframe_document_node_id: rootState.iframe.documentNodeId
@@ -406,6 +420,7 @@ export async function runRecommendWorkflow({
       throw new Error(`Requested recommend job was not selected: ${jobSelection.reason}`);
     }
     rootState = await getRecommendRoots(client);
+    rootState = await ensureRecommendViewport(rootState, "job");
     runControl.checkpoint({
       job_selection: compactJobSelection(jobSelection)
     });
@@ -424,6 +439,7 @@ export async function runRecommendWorkflow({
     throw new Error(`Recommend page scope was not selected: ${pageScopeSelection.reason || pageScopeSelection.effective_scope || requestedPageScope}`);
   }
   rootState = await getRecommendRoots(client);
+  rootState = await ensureRecommendViewport(rootState, "page_scope");
   runControl.checkpoint({
     page_scope: compactPageScopeSelection(pageScopeSelection)
   });
@@ -440,6 +456,8 @@ export async function runRecommendWorkflow({
     if (!filterResult.confirmed) {
       throw new Error("Recommend run filter selection was not confirmed");
     }
+    rootState = await getRecommendRoots(client);
+    rootState = await ensureRecommendViewport(rootState, "filter");
     runControl.checkpoint({
       filter: compactFilterResult(filterResult)
     });
@@ -448,6 +466,7 @@ export async function runRecommendWorkflow({
   await runControl.waitIfPaused();
   runControl.throwIfCanceled();
   runControl.setPhase("recommend:cards");
+  rootState = await ensureRecommendViewport(rootState, "cards");
   cardNodeIds = await waitForRecommendCardNodeIds(client, rootState.iframe.documentNodeId, {
     timeoutMs: cardTimeoutMs,
     intervalMs: 300
@@ -468,13 +487,16 @@ export async function runRecommendWorkflow({
     unique_seen: compactInfiniteListState(listState).seen_count,
     scroll_count: 0,
     refresh_rounds: 0,
-    refresh_attempts: 0
+    refresh_attempts: 0,
+    viewport_checks: viewportGuard.getStats().checks,
+    viewport_recoveries: viewportGuard.getStats().recoveries
   });
 
   while (results.length < limit) {
     await runControl.waitIfPaused();
     runControl.throwIfCanceled();
     runControl.setPhase("recommend:candidate");
+    rootState = await ensureRecommendViewport(rootState, "candidate_loop");
 
     const nextCandidateResult = await getNextInfiniteListCandidate({
       client,
@@ -485,7 +507,9 @@ export async function runRecommendWorkflow({
       settleMs: listSettleMs,
       fallbackPoint: listFallbackPoint,
       findNodeIds: async () => {
-        const currentRootState = await getRecommendRoots(client);
+        let currentRootState = await getRecommendRoots(client);
+        currentRootState = await ensureRecommendViewport(currentRootState, "candidate_find_nodes");
+        rootState = currentRootState;
         const currentCardNodeIds = await waitForRecommendCardNodeIds(client, currentRootState.iframe.documentNodeId, {
           timeoutMs: Math.min(cardTimeoutMs, 5000),
           intervalMs: 300
@@ -544,10 +568,13 @@ export async function runRecommendWorkflow({
           refresh_attempts: refreshAttempts.length,
           refresh_method: refreshResult.method || null,
           refresh_forced_recent_not_view: true,
-          list_end_reason: listEndReason
+          list_end_reason: listEndReason,
+          viewport_checks: viewportGuard.getStats().checks,
+          viewport_recoveries: viewportGuard.getStats().recoveries
         });
         if (refreshResult.ok) {
           rootState = refreshResult.root_state || await getRecommendRoots(client);
+          rootState = await ensureRecommendViewport(rootState, "refresh_after");
           cardNodeIds = await waitForRecommendCardNodeIds(client, rootState.iframe.documentNodeId, {
             timeoutMs: cardTimeoutMs,
             intervalMs: 300
@@ -579,6 +606,7 @@ export async function runRecommendWorkflow({
       await runControl.waitIfPaused();
       runControl.throwIfCanceled();
       runControl.setPhase("recommend:detail");
+      rootState = await ensureRecommendViewport(rootState, "detail");
       networkRecorder.clear();
       const openedDetail = await openRecommendCardDetail(client, cardNodeId);
       const waitPlan = getCvNetworkWaitPlan(cvAcquisitionState);
@@ -719,6 +747,8 @@ export async function runRecommendWorkflow({
       refresh_rounds: refreshRounds,
       refresh_attempts: refreshAttempts.length,
       list_end_reason: listEndReason || null,
+      viewport_checks: viewportGuard.getStats().checks,
+      viewport_recoveries: viewportGuard.getStats().recoveries,
       last_candidate_id: screeningCandidate.id || null,
       last_candidate_key: candidateKey,
       last_score: screening.score
@@ -756,6 +786,10 @@ export async function runRecommendWorkflow({
     filter: compactFilterResult(filterResult),
     card_count: cardNodeIds.length,
     candidate_list: compactInfiniteListState(listState),
+    viewport_health: {
+      stats: viewportGuard.getStats(),
+      events: viewportGuard.getEvents()
+    },
     list_end_reason: listEndReason || null,
     refresh_rounds: refreshRounds,
     refresh_attempts: refreshAttempts,

package/src/domains/recruit/roots.js

@@ -25,7 +25,8 @@ export async function getRecruitRoots(client, {
     ].filter(Boolean),
     rootNodes: {
       top: topRoot.nodeId,
-      frame: iframe?.documentNodeId || 0
+      frame: iframe?.documentNodeId || 0,
+      frameOwner: iframe?.nodeId || 0
     }
   };
 }

package/src/domains/recruit/run-service.js

@@ -18,6 +18,7 @@ import {
   markInfiniteListCandidateProcessed,
   resetInfiniteListForRefreshRound
 } from "../../core/infinite-list/index.js";
+import { createViewportRunGuard } from "../../core/self-heal/index.js";
 import { screenCandidate } from "../../core/screening/index.js";
 import {
   closeRecruitDetail,
@@ -140,6 +141,18 @@ export async function runRecruitWorkflow({
     domain: "recruit",
     listName: "search-results"
   });
+  const viewportGuard = createViewportRunGuard({
+    client,
+    domain: "recruit",
+    root: "frame",
+    frameOwnerRoot: "frameOwner",
+    runControl,
+    getRoots: getRecruitRoots
+  });
+  async function ensureRecruitViewport(rootState, phase) {
+    const result = await viewportGuard.ensure(rootState, { phase });
+    return result.rootState || rootState;
+  }
   const results = [];
   const refreshAttempts = [];
   let refreshRounds = 0;
@@ -153,6 +166,7 @@ export async function runRecruitWorkflow({
   runControl.throwIfCanceled();
   runControl.setPhase("recruit:roots");
   let rootState = await getRecruitRoots(client);
+  rootState = await ensureRecruitViewport(rootState, "roots");
   runControl.checkpoint({
     iframe_selector: rootState.iframe.selector,
     iframe_document_node_id: rootState.iframe.documentNodeId,
@@ -186,11 +200,13 @@ export async function runRecruitWorkflow({
       }
     });
     rootState = await getRecruitRoots(client);
+    rootState = await ensureRecruitViewport(rootState, "search");
   }
 
   await runControl.waitIfPaused();
   runControl.throwIfCanceled();
   runControl.setPhase("recruit:cards");
+  rootState = await ensureRecruitViewport(rootState, "cards");
   cardNodeIds = await waitForRecruitCardNodeIds(client, rootState.iframe.documentNodeId, {
     timeoutMs: cardTimeoutMs,
     intervalMs: 300
@@ -209,13 +225,16 @@ export async function runRecruitWorkflow({
     unique_seen: compactInfiniteListState(listState).seen_count,
     scroll_count: 0,
     refresh_rounds: 0,
-    refresh_attempts: 0
+    refresh_attempts: 0,
+    viewport_checks: viewportGuard.getStats().checks,
+    viewport_recoveries: viewportGuard.getStats().recoveries
   });
 
   while (results.length < limit) {
     await runControl.waitIfPaused();
     runControl.throwIfCanceled();
     runControl.setPhase("recruit:candidate");
+    rootState = await ensureRecruitViewport(rootState, "candidate_loop");
 
     const nextCandidateResult = await getNextInfiniteListCandidate({
       client,
@@ -226,7 +245,9 @@ export async function runRecruitWorkflow({
       settleMs: listSettleMs,
       fallbackPoint: listFallbackPoint,
       findNodeIds: async () => {
-        const currentRootState = await getRecruitRoots(client);
+        let currentRootState = await getRecruitRoots(client);
+        currentRootState = await ensureRecruitViewport(currentRootState, "candidate_find_nodes");
+        rootState = currentRootState;
         const currentCardNodeIds = await waitForRecruitCardNodeIds(client, currentRootState.iframe.documentNodeId, {
           timeoutMs: Math.min(cardTimeoutMs, 5000),
           intervalMs: 300
@@ -283,10 +304,13 @@ export async function runRecruitWorkflow({
           refresh_attempts: refreshAttempts.length,
           refresh_method: refreshResult.method || null,
           refresh_forced_recent_viewed: true,
-          list_end_reason: listEndReason
+          list_end_reason: listEndReason,
+          viewport_checks: viewportGuard.getStats().checks,
+          viewport_recoveries: viewportGuard.getStats().recoveries
         });
         if (refreshResult.ok) {
           rootState = await getRecruitRoots(client);
+          rootState = await ensureRecruitViewport(rootState, "refresh_after");
           cardNodeIds = await waitForRecruitCardNodeIds(client, rootState.iframe.documentNodeId, {
             timeoutMs: cardTimeoutMs,
             intervalMs: 300
@@ -318,6 +342,7 @@ export async function runRecruitWorkflow({
       await runControl.waitIfPaused();
       runControl.throwIfCanceled();
       runControl.setPhase("recruit:detail");
+      rootState = await ensureRecruitViewport(rootState, "detail");
       networkRecorder.clear();
       const openedDetail = await openRecruitCardDetail(client, cardNodeId);
       const waitPlan = getCvNetworkWaitPlan(cvAcquisitionState);
@@ -430,6 +455,8 @@ export async function runRecruitWorkflow({
       refresh_rounds: refreshRounds,
       refresh_attempts: refreshAttempts.length,
       list_end_reason: listEndReason || null,
+      viewport_checks: viewportGuard.getStats().checks,
+      viewport_recoveries: viewportGuard.getStats().recoveries,
       last_candidate_id: screeningCandidate.id || null,
       last_candidate_key: candidateKey,
       last_score: screening.score
@@ -459,6 +486,10 @@ export async function runRecruitWorkflow({
     search_params: normalizedSearchParams,
     card_count: cardNodeIds.length,
     candidate_list: compactInfiniteListState(listState),
+    viewport_health: {
+      stats: viewportGuard.getStats(),
+      events: viewportGuard.getEvents()
+    },
     list_end_reason: listEndReason || null,
     refresh_rounds: refreshRounds,
     refresh_attempts: refreshAttempts,

package/src/index.js

@@ -1911,7 +1911,8 @@ async function handleRunRecommendSelfHealTool({ workspaceRoot, args }) {
       domain: "recommend",
       roots: rootState?.roots || {},
       selectorProbes: config.selectorProbes,
-      accessibilityProbes: config.accessibilityProbes
+      accessibilityProbes: config.accessibilityProbes,
+      viewportProbes: config.viewportProbes
     });
     assertNoForbiddenCdpCalls(methodLog);
 

package/src/recommend-mcp.js

@@ -623,7 +623,8 @@ async function waitForHealthyRecommend(client, config, {
       domain: "recommend",
       roots: roots.roots,
       selectorProbes: config.selectorProbes,
-      accessibilityProbes: config.accessibilityProbes
+      accessibilityProbes: config.accessibilityProbes,
+      viewportProbes: config.viewportProbes
     });
     if (lastCheck.status === HEALTH_STATUS.HEALTHY) return lastCheck;
     await sleep(intervalMs);