@web-auto/camo 0.1.2 → 0.1.4

package/src/commands/window.mjs

@@ -24,7 +24,38 @@ export async function handleWindowCommand(args) {
     const width = parseInt(args[widthIdx + 1]);
     const height = parseInt(args[heightIdx + 1]);
     const result = await callAPI('window:resize', { profileId, width, height });
-    console.log(JSON.stringify(result, null, 2));
+    const measured = await callAPI('evaluate', {
+      profileId,
+      script: '({ innerWidth: window.innerWidth, innerHeight: window.innerHeight, outerWidth: window.outerWidth, outerHeight: window.outerHeight })',
+    });
+    const innerWidth = Math.max(320, Number(measured?.result?.innerWidth || 0) || 0);
+    const innerHeight = Math.max(240, Number(measured?.result?.innerHeight || 0) || 0);
+    const outerWidth = Math.max(320, Number(measured?.result?.outerWidth || 0) || innerWidth);
+    const outerHeight = Math.max(240, Number(measured?.result?.outerHeight || 0) || innerHeight);
+    const rawDeltaW = Math.max(0, outerWidth - innerWidth);
+    const rawDeltaH = Math.max(0, outerHeight - innerHeight);
+    const frameW = rawDeltaW > 400 ? 16 : Math.min(rawDeltaW, 120);
+    const frameH = rawDeltaH > 400 ? 88 : Math.min(rawDeltaH, 180);
+    const targetViewportWidth = Math.max(320, outerWidth - frameW);
+    const targetViewportHeight = Math.max(240, outerHeight - frameH);
+    const viewport = await callAPI('page:setViewport', {
+      profileId,
+      width: targetViewportWidth,
+      height: targetViewportHeight,
+    });
+    console.log(JSON.stringify({
+      ok: true,
+      profileId,
+      window: result,
+      measured: measured?.result || null,
+      targetViewport: {
+        width: targetViewportWidth,
+        height: targetViewportHeight,
+        frameW,
+        frameH,
+      },
+      viewport,
+    }, null, 2));
   } else {
     throw new Error('Usage: camo window <move|resize> [profileId] --x <x> --y <y> / --width <w> --height <h>');
   }

package/src/container/change-notifier.mjs

@@ -0,0 +1,311 @@
+// Change Notifier - Subscribe to DOM changes and element events
+
+function normalizeSelector(selector) {
+  if (!selector) return { visible: true };
+  if (typeof selector === 'string') return { css: selector, visible: true };
+  if (typeof selector !== 'object') return { visible: true };
+  return {
+    ...selector,
+    visible: selector.visible !== false,
+  };
+}
+
+function selectorKey(selector) {
+  const normalized = normalizeSelector(selector);
+  const stable = {
+    css: normalized.css || null,
+    tag: normalized.tag || null,
+    id: normalized.id || null,
+    classes: Array.isArray(normalized.classes) ? [...normalized.classes].sort() : [],
+    visible: normalized.visible !== false,
+  };
+  return JSON.stringify(stable);
+}
+
+function parseCssSelector(css) {
+  const raw = typeof css === 'string' ? css.trim() : '';
+  if (!raw) return [];
+  const attrRegex = /\[\s*([^\s~|^$*=\]]+)\s*(\*=|\^=|\$=|=)?\s*(?:"([^"]*)"|'([^']*)'|([^\]\s]+))?\s*\]/g;
+  return raw
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean)
+    .map((item) => {
+      const tagMatch = item.match(/^[a-zA-Z][\w-]*/);
+      const idMatch = item.match(/#([\w-]+)/);
+      const classMatches = item.match(/\.([\w-]+)/g) || [];
+      const attrs = [];
+      let attrMatch = attrRegex.exec(item);
+      while (attrMatch) {
+        attrs.push({
+          name: String(attrMatch[1] || '').toLowerCase(),
+          op: attrMatch[2] || 'exists',
+          value: attrMatch[3] ?? attrMatch[4] ?? attrMatch[5] ?? '',
+        });
+        attrMatch = attrRegex.exec(item);
+      }
+      attrRegex.lastIndex = 0;
+      return {
+        tag: tagMatch ? tagMatch[0].toLowerCase() : null,
+        id: idMatch ? idMatch[1] : null,
+        classes: classMatches.map((token) => token.slice(1)),
+        attrs,
+      };
+    });
+}
+
+function nodeAttribute(node, name, nodeId, nodeClasses) {
+  const key = String(name || '').toLowerCase();
+  if (!key) return null;
+  if (key === 'id') return nodeId || null;
+  if (key === 'class') return Array.from(nodeClasses).join(' ');
+
+  const attrs = node?.attrs && typeof node.attrs === 'object' ? node.attrs : null;
+  if (attrs && attrs[key] !== undefined && attrs[key] !== null) return String(attrs[key]);
+
+  const direct = node?.[key];
+  if (typeof direct === 'string' || typeof direct === 'number' || typeof direct === 'boolean') {
+    return String(direct);
+  }
+  return null;
+}
+
+function matchAttribute(node, attrSpec, nodeId, nodeClasses) {
+  const value = nodeAttribute(node, attrSpec.name, nodeId, nodeClasses);
+  if (attrSpec.op === 'exists') return value !== null && value !== '';
+  if (value === null) return false;
+  const expected = String(attrSpec.value || '');
+  if (attrSpec.op === '=') return value === expected;
+  if (attrSpec.op === '*=') return value.includes(expected);
+  if (attrSpec.op === '^=') return value.startsWith(expected);
+  if (attrSpec.op === '$=') return value.endsWith(expected);
+  return false;
+}
+
+export class ChangeNotifier {
+  constructor() {
+    this.subscriptions = new Map(); // topic -> Set<callback>
+    this.elementWatchers = new Map(); // selector -> { lastState, callbacks }
+    this.lastSnapshot = null;
+  }
+
+  nodePassesVisibility(node, selector, viewport) {
+    const normalized = normalizeSelector(selector);
+    if (normalized.visible === false) return true;
+    if (!node || typeof node !== 'object') return false;
+    if (typeof node.visible === 'boolean') return node.visible;
+
+    const rect = node.rect || null;
+    if (!rect) return true;
+    const width = Number(rect.width || 0);
+    const height = Number(rect.height || 0);
+    if (width <= 0 || height <= 0) return false;
+
+    const vw = Number(viewport?.width || 0);
+    const vh = Number(viewport?.height || 0);
+    if (vw <= 0 || vh <= 0) return true;
+    const left = Number(rect.left ?? rect.x ?? 0);
+    const top = Number(rect.top ?? rect.y ?? 0);
+    const right = Number(rect.right ?? (left + width));
+    const bottom = Number(rect.bottom ?? (top + height));
+    return right > 0 && bottom > 0 && left < vw && top < vh;
+  }
+
+  // Subscribe to a topic
+  subscribe(topic, callback) {
+    if (!this.subscriptions.has(topic)) {
+      this.subscriptions.set(topic, new Set());
+    }
+    this.subscriptions.get(topic).add(callback);
+    return () => {
+      this.subscriptions.get(topic)?.delete(callback);
+    };
+  }
+
+  // Watch specific elements by selector
+  watch(selector, options = {}) {
+    const { onAppear, onDisappear, onChange, throttle = 200 } = options;
+    const resolvedSelector = normalizeSelector(selector);
+    const key = selectorKey(resolvedSelector);
+    const resolvedThrottle = Math.max(50, Number(throttle) || 200);
+
+    if (!this.elementWatchers.has(key)) {
+      this.elementWatchers.set(key, {
+        selector: resolvedSelector,
+        lastState: null,
+        lastNotifyTime: 0,
+        throttle: resolvedThrottle,
+        callbacks: { onAppear, onDisappear, onChange },
+      });
+    } else {
+      const watcher = this.elementWatchers.get(key);
+      if (onAppear) watcher.callbacks.onAppear = onAppear;
+      if (onDisappear) watcher.callbacks.onDisappear = onDisappear;
+      if (onChange) watcher.callbacks.onChange = onChange;
+      watcher.throttle = resolvedThrottle;
+    }
+
+    return () => {
+      this.elementWatchers.delete(key);
+    };
+  }
+
+  // Notify all subscribers of a topic
+  notify(topic, data) {
+    const callbacks = this.subscriptions.get(topic);
+    if (!callbacks) return;
+    for (const callback of callbacks) {
+      try {
+        callback(data);
+      } catch (err) {
+        console.error(`[ChangeNotifier] callback error for ${topic}:`, err);
+      }
+    }
+  }
+
+  // Process new DOM snapshot and trigger notifications
+  processSnapshot(snapshot) {
+    const now = Date.now();
+    const prevSnapshot = this.lastSnapshot;
+    this.lastSnapshot = snapshot;
+
+    // Notify general DOM change
+    this.notify('dom:changed', { snapshot, prevSnapshot });
+
+    // Process element watchers
+    for (const [, watcher] of this.elementWatchers) {
+      const { lastState, callbacks, lastNotifyTime, throttle } = watcher;
+
+      // Throttle notifications
+      if (now - lastNotifyTime < throttle) continue;
+
+      const currentElements = this.findElements(snapshot, watcher.selector);
+      const currentState = currentElements.map(e => e.path).sort().join(',');
+
+      if (lastState !== null && currentState !== lastState) {
+        // Something changed
+        const prevElements = watcher.prevElements || [];
+        const appeared = currentElements.filter(e => !prevElements.find(p => p.path === e.path));
+        const disappeared = prevElements.filter(e => !currentElements.find(c => c.path === e.path));
+
+        if (appeared.length > 0 && callbacks.onAppear) {
+          callbacks.onAppear(appeared);
+          watcher.lastNotifyTime = now;
+        }
+        if (disappeared.length > 0 && callbacks.onDisappear) {
+          callbacks.onDisappear(disappeared);
+          watcher.lastNotifyTime = now;
+        }
+        if (callbacks.onChange) {
+          callbacks.onChange({ current: currentElements, previous: prevElements, appeared, disappeared });
+          watcher.lastNotifyTime = now;
+        }
+      }
+
+      watcher.lastState = currentState;
+      watcher.prevElements = currentElements;
+    }
+  }
+
+  // Find elements matching selector in DOM tree
+  findElements(node, selector, path = 'root', context = null) {
+    const results = [];
+    if (!node) return results;
+    const normalized = normalizeSelector(selector);
+    const runtimeContext = context || {
+      viewport: node?.__viewport || null,
+    };
+
+    // Check if current node matches
+    if (this.nodeMatchesSelector(node, normalized) && this.nodePassesVisibility(node, normalized, runtimeContext.viewport)) {
+      results.push({ ...node, path });
+    }
+
+    // Recurse into children
+    if (node.children) {
+      for (let i = 0; i < node.children.length; i++) {
+        const childResults = this.findElements(node.children[i], normalized, `${path}/${i}`, runtimeContext);
+        results.push(...childResults);
+      }
+    }
+
+    return results;
+  }
+
+  // Check if node matches selector
+  nodeMatchesSelector(node, selector) {
+    if (!node) return false;
+    const normalized = normalizeSelector(selector);
+    if (!normalized || typeof normalized !== 'object') return false;
+
+    const nodeTag = typeof node.tag === 'string' ? node.tag.toLowerCase() : null;
+    const nodeId = typeof node.id === 'string' ? node.id : null;
+    const nodeClasses = new Set(Array.isArray(node.classes) ? node.classes : []);
+
+    // Exact selector string (fast path).
+    if (normalized.css && node.selector === normalized.css) return true;
+
+    const cssVariants = parseCssSelector(normalized.css);
+    if (cssVariants.length > 0) {
+      for (const cssVariant of cssVariants) {
+        const hasConstraints = Boolean(
+          cssVariant.tag
+            || cssVariant.id
+            || (cssVariant.classes && cssVariant.classes.length > 0)
+            || (cssVariant.attrs && cssVariant.attrs.length > 0),
+        );
+        if (!hasConstraints) continue;
+
+        let matched = true;
+        if (cssVariant.tag && nodeTag !== cssVariant.tag) matched = false;
+        if (cssVariant.id && nodeId !== cssVariant.id) matched = false;
+        if (matched && cssVariant.classes.length > 0) {
+          matched = cssVariant.classes.every((className) => nodeClasses.has(className));
+        }
+        if (matched && cssVariant.attrs.length > 0) {
+          matched = cssVariant.attrs.every((attrSpec) => matchAttribute(node, attrSpec, nodeId, nodeClasses));
+        }
+        if (matched) return true;
+      }
+    }
+
+    const requiredTag = normalized.tag ? String(normalized.tag).toLowerCase() : null;
+    const requiredId = normalized.id ? String(normalized.id) : null;
+    const requiredClasses = Array.isArray(normalized.classes)
+      ? normalized.classes.filter(Boolean).map((className) => String(className))
+      : [];
+
+    const hasStructuredSelector = Boolean(requiredTag || requiredId || requiredClasses.length > 0);
+    if (!hasStructuredSelector) return false;
+    if (requiredTag && nodeTag !== requiredTag) return false;
+    if (requiredId && nodeId !== requiredId) return false;
+    if (requiredClasses.length > 0 && !requiredClasses.every((className) => nodeClasses.has(className))) {
+      return false;
+    }
+    return true;
+  }
+
+  // Cleanup
+  destroy() {
+    this.subscriptions.clear();
+    this.elementWatchers.clear();
+    this.lastSnapshot = null;
+  }
+}
+
+// Global instance
+let globalNotifier = null;
+
+export function getChangeNotifier() {
+  if (!globalNotifier) {
+    globalNotifier = new ChangeNotifier();
+  }
+  return globalNotifier;
+}
+
+export function destroyChangeNotifier() {
+  if (globalNotifier) {
+    globalNotifier.destroy();
+    globalNotifier = null;
+  }
+}

package/src/container/element-filter.mjs

@@ -0,0 +1,143 @@
+// Container Element Filter - Filter DOM elements by visibility, container definitions
+
+function parseCssSelector(css) {
+  const raw = typeof css === 'string' ? css.trim() : '';
+  if (!raw) return [];
+  return raw
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean)
+    .map((item) => {
+      const tagMatch = item.match(/^[a-zA-Z][\w-]*/);
+      const idMatch = item.match(/#([\w-]+)/);
+      const classMatches = item.match(/\.([\w-]+)/g) || [];
+      return {
+        tag: tagMatch ? tagMatch[0].toLowerCase() : null,
+        id: idMatch ? idMatch[1] : null,
+        classes: classMatches.map((token) => token.slice(1)),
+      };
+    });
+}
+
+export class ElementFilter {
+  constructor(options = {}) {
+    this.viewportMargin = options.viewportMargin || 0;
+    this.minVisibleRatio = options.minVisibleRatio || 0.5;
+  }
+
+  // Check if element is in viewport
+  isInViewport(rect, viewport) {
+    return (
+      rect.left < viewport.width + this.viewportMargin &&
+      rect.right > -this.viewportMargin &&
+      rect.top < viewport.height + this.viewportMargin &&
+      rect.bottom > -this.viewportMargin
+    );
+  }
+
+  // Calculate visibility ratio
+  getVisibilityRatio(rect, viewport) {
+    const visibleLeft = Math.max(0, rect.left);
+    const visibleTop = Math.max(0, rect.top);
+    const visibleRight = Math.min(viewport.width, rect.right);
+    const visibleBottom = Math.min(viewport.height, rect.bottom);
+
+    const visibleArea = Math.max(0, visibleRight - visibleLeft) * Math.max(0, visibleBottom - visibleTop);
+    const totalArea = rect.width * rect.height;
+
+    return totalArea > 0 ? visibleArea / totalArea : 0;
+  }
+
+  // Filter elements by container definition
+  filterByContainer(elements, containerDef) {
+    const selectors = containerDef.selectors || [];
+    const results = [];
+
+    for (const element of elements) {
+      for (const selector of selectors) {
+        if (this.matchesSelector(element, selector)) {
+          results.push({
+            element,
+            container: containerDef,
+            matchedSelector: selector,
+          });
+          break;
+        }
+      }
+    }
+
+    return results;
+  }
+
+  // Check if element matches selector definition
+  matchesSelector(element, selector) {
+    if (!element || !selector) return false;
+    if (selector.css && element.selector === selector.css) return true;
+
+    const elementTag = typeof element.tag === 'string' ? element.tag.toLowerCase() : null;
+    const elementId = typeof element.id === 'string' ? element.id : null;
+    const elementClasses = new Set(Array.isArray(element.classes) ? element.classes : []);
+
+    const cssVariants = parseCssSelector(selector.css);
+    if (cssVariants.length > 0) {
+      for (const cssVariant of cssVariants) {
+        let matched = true;
+        if (cssVariant.tag && elementTag !== cssVariant.tag) matched = false;
+        if (cssVariant.id && elementId !== cssVariant.id) matched = false;
+        if (matched && cssVariant.classes.length > 0) {
+          matched = cssVariant.classes.every((className) => elementClasses.has(className));
+        }
+        if (matched) return true;
+      }
+    }
+
+    const requiredTag = selector.tag ? String(selector.tag).toLowerCase() : null;
+    const requiredId = selector.id ? String(selector.id) : null;
+    const requiredClasses = Array.isArray(selector.classes)
+      ? selector.classes.filter(Boolean).map((className) => String(className))
+      : [];
+
+    const hasStructuredSelector = Boolean(requiredTag || requiredId || requiredClasses.length > 0);
+    if (!hasStructuredSelector) return false;
+    if (requiredTag && elementTag !== requiredTag) return false;
+    if (requiredId && elementId !== requiredId) return false;
+    if (requiredClasses.length > 0 && !requiredClasses.every((className) => elementClasses.has(className))) {
+      return false;
+    }
+    return true;
+  }
+
+  // Main filter method
+  filter(elements, options = {}) {
+    const {
+      container,
+      viewport,
+      requireVisible = true,
+      minVisibleRatio = this.minVisibleRatio,
+    } = options;
+
+    let results = [...elements];
+
+    // Filter by container definition
+    if (container) {
+      results = this.filterByContainer(results, container);
+    }
+
+    // Filter by viewport visibility
+    if (requireVisible && viewport) {
+      results = results.filter(item => {
+        const rect = item.element?.rect || item.rect;
+        if (!rect) return false;
+        const ratio = this.getVisibilityRatio(rect, viewport);
+        item.visibilityRatio = ratio;
+        return ratio >= minVisibleRatio;
+      });
+    }
+
+    return results;
+  }
+}
+
+export function createElementFilter(options) {
+  return new ElementFilter(options);
+}

package/src/container/index.mjs

@@ -0,0 +1,3 @@
+// Container module - element filtering and change notification
+export { ElementFilter, createElementFilter } from './element-filter.mjs';
+export { ChangeNotifier, getChangeNotifier, destroyChangeNotifier } from './change-notifier.mjs';

package/src/container/runtime-core/checkpoint.mjs

@@ -0,0 +1,195 @@
+import { callAPI, getDomSnapshotByProfile } from '../../utils/browser-service.mjs';
+import {
+  asErrorPayload,
+  buildSelectorCheck,
+  ensureActiveSession,
+  getCurrentUrl,
+  isCheckpointRiskUrl,
+  maybeSelector,
+  normalizeArray,
+} from './utils.mjs';
+
+export const XHS_CHECKPOINTS = {
+  search_ready: [
+    '#search-input',
+    'input.search-input',
+    '.search-result-list',
+  ],
+  home_ready: [
+    '.feeds-page',
+    '.note-item',
+  ],
+  detail_ready: [
+    '.note-scroller',
+    '.note-content',
+    '.interaction-container',
+  ],
+  comments_ready: [
+    '.comments-container',
+    '.comment-item',
+  ],
+  login_guard: [
+    '.login-container',
+    '.login-dialog',
+    '#login-container',
+  ],
+  risk_control: [
+    '.qrcode-box',
+    '.captcha-container',
+    '[class*="captcha"]',
+  ],
+};
+
+export async function detectCheckpoint({ profileId, platform = 'xiaohongshu' }) {
+  if (platform !== 'xiaohongshu') {
+    return asErrorPayload('UNSUPPORTED_PLATFORM', `Unsupported platform: ${platform}`);
+  }
+
+  try {
+    const session = await ensureActiveSession(profileId);
+    const resolvedProfile = session.profileId || profileId;
+    const [url, snapshot] = await Promise.all([
+      getCurrentUrl(resolvedProfile),
+      getDomSnapshotByProfile(resolvedProfile),
+    ]);
+
+    const signals = [];
+    const counter = {};
+    const addCount = (label, selectors) => {
+      for (const css of selectors) {
+        const count = buildSelectorCheck(snapshot, css).length;
+        if (count > 0) {
+          counter[css] = count;
+          signals.push(`${label}:${css}`);
+        }
+      }
+    };
+
+    addCount('search_ready', XHS_CHECKPOINTS.search_ready);
+    addCount('home_ready', XHS_CHECKPOINTS.home_ready);
+    addCount('detail_ready', XHS_CHECKPOINTS.detail_ready);
+    addCount('comments_ready', XHS_CHECKPOINTS.comments_ready);
+    addCount('login_guard', XHS_CHECKPOINTS.login_guard);
+    addCount('risk_control', XHS_CHECKPOINTS.risk_control);
+
+    let checkpoint = 'unknown';
+    if (!url || !url.includes('xiaohongshu.com')) checkpoint = 'offsite';
+    else if (isCheckpointRiskUrl(url)) checkpoint = 'risk_control';
+    else if (signals.some((item) => item.startsWith('login_guard:'))) checkpoint = 'login_guard';
+    else if (signals.some((item) => item.startsWith('comments_ready:'))) checkpoint = 'comments_ready';
+    else if (signals.some((item) => item.startsWith('detail_ready:'))) checkpoint = 'detail_ready';
+    else if (signals.some((item) => item.startsWith('search_ready:'))) checkpoint = 'search_ready';
+    else if (signals.some((item) => item.startsWith('home_ready:'))) checkpoint = 'home_ready';
+
+    return {
+      ok: true,
+      code: 'CHECKPOINT_DETECTED',
+      message: 'Checkpoint detected',
+      data: {
+        profileId: resolvedProfile,
+        platform,
+        checkpoint,
+        url,
+        signals,
+        selectorHits: counter,
+      },
+    };
+  } catch (err) {
+    return asErrorPayload('CHECKPOINT_DETECT_FAILED', err?.message || String(err));
+  }
+}
+
+export async function captureCheckpoint({
+  profileId,
+  containerId = null,
+  selector = null,
+  platform = 'xiaohongshu',
+}) {
+  try {
+    const session = await ensureActiveSession(profileId);
+    const resolvedProfile = session.profileId || profileId;
+    const checkpointRes = await detectCheckpoint({ profileId: resolvedProfile, platform });
+    const effectiveSelector = maybeSelector({ profileId: resolvedProfile, containerId, selector });
+    const snapshot = await getDomSnapshotByProfile(resolvedProfile);
+    const matched = effectiveSelector ? buildSelectorCheck(snapshot, effectiveSelector) : [];
+
+    return {
+      ok: true,
+      code: 'CHECKPOINT_CAPTURED',
+      message: 'Checkpoint captured',
+      data: {
+        profileId: resolvedProfile,
+        checkpoint: checkpointRes?.data?.checkpoint || 'unknown',
+        checkpointUrl: checkpointRes?.data?.url || '',
+        containerId,
+        selector: effectiveSelector,
+        selectorCount: matched.length,
+        capturedAt: new Date().toISOString(),
+      },
+    };
+  } catch (err) {
+    return asErrorPayload('CHECKPOINT_CAPTURE_FAILED', err?.message || String(err));
+  }
+}
+
+export async function restoreCheckpoint({
+  profileId,
+  checkpoint = null,
+  action,
+  containerId = null,
+  selector = null,
+  targetCheckpoint = null,
+  platform = 'xiaohongshu',
+}) {
+  try {
+    const session = await ensureActiveSession(profileId);
+    const resolvedProfile = session.profileId || profileId;
+    const effectiveSelector = maybeSelector({ profileId: resolvedProfile, containerId, selector });
+    let actionResult = null;
+
+    if (action === 'requery_container') {
+      if (!effectiveSelector) return asErrorPayload('CONTAINER_NOT_FOUND', 'Selector is required for requery_container');
+      const snapshot = await getDomSnapshotByProfile(resolvedProfile);
+      const matches = buildSelectorCheck(snapshot, effectiveSelector);
+      if (matches.length === 0) return asErrorPayload('CONTAINER_NOT_FOUND', `Container selector not found: ${effectiveSelector}`);
+      actionResult = { selector: effectiveSelector, count: matches.length };
+    } else if (action === 'scroll_into_view') {
+      if (!effectiveSelector) return asErrorPayload('CONTAINER_NOT_FOUND', 'Selector is required for scroll_into_view');
+      actionResult = await callAPI('evaluate', {
+        profileId: resolvedProfile,
+        script: `(async () => {
+          const el = document.querySelector(${JSON.stringify(effectiveSelector)});
+          if (!el) throw new Error('Element not found');
+          el.scrollIntoView({ behavior: 'auto', block: 'center', inline: 'nearest' });
+          return { ok: true, selector: ${JSON.stringify(effectiveSelector)} };
+        })()`,
+      });
+    } else if (action === 'page_back') {
+      actionResult = await callAPI('page:back', { profileId: resolvedProfile });
+    } else if (action === 'goto_checkpoint_url') {
+      const url = checkpoint?.checkpointUrl || checkpoint?.url || '';
+      if (!url) return asErrorPayload('CHECKPOINT_RESTORE_FAILED', 'checkpointUrl is required for goto_checkpoint_url');
+      actionResult = await callAPI('goto', { profileId: resolvedProfile, url });
+    } else {
+      return asErrorPayload('UNSUPPORTED_RECOVERY_ACTION', `Unsupported recovery action: ${action}`);
+    }
+
+    const checkpointAfter = await detectCheckpoint({ profileId: resolvedProfile, platform });
+    const reached = checkpointAfter?.data?.checkpoint || 'unknown';
+    const targetMatched = targetCheckpoint ? reached === targetCheckpoint : true;
+    return {
+      ok: true,
+      code: targetMatched ? 'CHECKPOINT_RESTORED' : 'CHECKPOINT_RESTORE_PARTIAL',
+      message: targetMatched ? 'Checkpoint restored' : 'Recovery action completed but target checkpoint not reached',
+      data: {
+        profileId: resolvedProfile,
+        action,
+        actionResult,
+        reachedCheckpoint: reached,
+        targetCheckpoint,
+      },
+    };
+  } catch (err) {
+    return asErrorPayload('CHECKPOINT_RESTORE_FAILED', err?.message || String(err));
+  }
+}