@kingsoftcloud/agentkit-harness-node 0.0.0-stage → 0.0.1

package/src/native/assistant-stream.mjs

@@ -0,0 +1,76 @@
+import { createHash } from 'node:crypto';
+import { invariant } from '@kingsoftcloud/agentkit-harness-core';
+import { finalResultDisplay } from './result-stream.mjs';
+
+// Display block identities are local to an attempt. They never authorize a
+// Native tool call, whose canonical identity arrives in the committed message.
+export function nativeStreamProjector(operationKey, configuration) {
+  const blocks = new Map();
+  const display = finalResultDisplay(configuration);
+  const project = record => {
+    const { event, time } = record;
+    const key = event.kind === 'tool_delta' ? `tool:${event.metadata.index}` : event.kind;
+    const output = [];
+    if (!blocks.has(key)) {
+      const index = blocks.size;
+      blocks.set(key, { index, id: `native-preview-${createHash('sha256').update(`${operationKey}:${key}`).digest('hex')}` });
+      output.push({ type: 'chunk', time, chunk: { type: 'block-start', index,
+        blockType: event.kind === 'text' ? 'text' : event.kind === 'thinking' ? 'reasoning' : 'tool-call' } });
+    }
+    const { index, id } = blocks.get(key);
+    const chunk = event.kind === 'tool_delta'
+      ? { type: 'tool-call-delta', index, id, argumentsDelta: event.text,
+        ...(event.metadata.name ? { name: event.metadata.name } : {}) }
+      : { type: event.kind === 'text' ? 'text-delta' : 'reasoning-delta', index, text: event.text };
+    output.push({ type: 'chunk', time, chunk });
+    return output;
+  };
+  return record => display(record).flatMap(project);
+}
+
+export function nativeDurableStream(operationKey, display, configuration) {
+  if (display === undefined) return [];
+  invariant(display.version === 'agentkit.model-display/v1' && Array.isArray(display.records)
+    && typeof operationKey === 'string', 'native_display_stream_invalid');
+  return display.records.flatMap(nativeStreamProjector(operationKey, configuration));
+}
+
+/** Public DSH frames; publication failures cannot change execution authority. */
+export function nativeLiveStream({ agent, runId, turn, publish, beginStep, revisions, configuration }) {
+  const attempts = new Map();
+  // DSH continuity revisions count every frame in the Agent lifecycle, not
+  // model attempts. Reusing a start revision for its chunks makes the real
+  // Session follower discard the active stream as a continuity violation.
+  const emit = frame => {
+    const revision = (revisions.get(agent) ?? 0) + 1;
+    revisions.set(agent, revision);
+    try { publish?.(structuredClone({ ...frame, revision })); } catch { /* display observer */ }
+  };
+  return {
+    pending(operationKey) { return attempts.has(operationKey); },
+    accept(context, record) {
+      if (!publish) return;
+      let attempt = attempts.get(context.operationKey);
+      if (!attempt) {
+        attempt = { attemptId: `${runId}:${context.operationKey}`, index: 0,
+          project: nativeStreamProjector(context.operationKey, configuration) };
+        attempts.set(context.operationKey, attempt);
+        emit({ type: 'start', attemptId: attempt.attemptId, turn, step: beginStep() });
+      }
+      for (const { time, chunk } of attempt.project(record)) emit({ type: 'chunk', attemptId: attempt.attemptId,
+        index: attempt.index++, time, chunk });
+    },
+    settled(operationKey, eventType, seq) {
+      const attempt = attempts.get(operationKey);
+      if (!attempt) return;
+      attempts.delete(operationKey);
+      emit({ type: 'end', attemptId: attempt.attemptId, index: attempt.index,
+        outcome: { kind: 'committed', eventType, seq } });
+    },
+    abandon() {
+      for (const attempt of attempts.values()) emit({ type: 'end', attemptId: attempt.attemptId,
+        index: attempt.index, outcome: { kind: 'abandoned' } });
+      attempts.clear();
+    },
+  };
+}

package/src/native/background-command-port.mjs

@@ -0,0 +1,95 @@
+// Observe existing command handles through the canonical launch receipt. This
+// port has no launch, stop, approval or model capability; those are separate
+// durable tool/Host operations. Backend selection never falls back to the env.
+import { BACKGROUND_COMMAND_CONTRACT, backgroundCommandObservation, backgroundCommandRef,
+  commandProbe, canonical, copy, NativeError, BACKGROUND_NOTIFICATION_ADMISSION } from '@kingsoftcloud/agentkit-harness-core';
+import { ownedCommandReceipt } from './owned-command.mjs';
+
+const backends = new Set(['local_process', 'e2b']);
+const check = (value, code) => { if (!value) throw new NativeError(code); };
+const same = (left, right) => canonical(left) === canonical(right);
+
+/** readers[backend] performs one nonblocking, read-only handle lookup. */
+export function createBackgroundCommandPort({ scope, store, readers = {} }) {
+  const pinnedScope = copy(scope), bindings = Object.fromEntries(Object.entries(readers));
+  check(Object.entries(bindings).every(([backend, reader]) => backends.has(backend) && typeof reader === 'function'),
+    'invalid_background_command_readers');
+  return Object.freeze({
+    contract: BACKGROUND_COMMAND_CONTRACT,
+    /** Controlled idle admission reads the original receipt, never environment
+     * hints. This method cannot create a turn or mutate the backend. */
+    async observeCompletion(request) {
+      const signal = request.signal;
+      check(signal instanceof AbortSignal, 'background_notification_signal_invalid');
+      const { signal: _, ...body } = request, sealed = canonical(body);
+      let original;
+      const current = () => {
+        signal.throwIfAborted();
+        const { signal: liveSignal, ...live } = request;
+        check(liveSignal === signal && canonical(live) === sealed && same(request.scope, pinnedScope), 'background_notification_request_drift');
+        const source = store.load(pinnedScope, request.sourceRunId), snapshot = source.snapshot;
+        const head = store.sessionHead(pinnedScope, snapshot.sessionId);
+        const ref = backgroundCommandRef(request.ref);
+        check(same(body, { contract: BACKGROUND_NOTIFICATION_ADMISSION, scope: pinnedScope, sourceRunId: snapshot.runId,
+          sessionId: snapshot.sessionId, sourceConfigDigest: snapshot.configDigest, sourceRevision: snapshot.revision,
+          headRunId: head?.runId, ref }) && snapshot.phase === 'completed' && head?.phase === 'completed'
+          && ref.sourceRunId === snapshot.runId && snapshot.backgroundCommands.some(row => same(row.ref, ref) && !row.notified)
+          && head.backgroundCommands.some(row => same(row.ref, ref) && !row.notified), 'background_notification_read_unbound');
+        if (original) check(same(original, source), 'background_notification_read_changed');
+        else original = source;
+        return { ...ownedCommandReceipt({ scope: pinnedScope, store, current: source, ref }), source };
+      };
+      const { ref, backend, source } = current();
+      if (!backend || !bindings[backend]) return backgroundCommandObservation({ ref, status: 'unavailable' });
+      let output;
+      try {
+        output = await bindings[backend]({ scope: copy(pinnedScope), sessionId: source.snapshot.sessionId,
+          runId: source.snapshot.runId, ref: copy(ref), stdoutCursor: 0, stderrCursor: 0, maxBytes: 8192, waitSeconds: 0, signal });
+      } catch {
+        current(); return backgroundCommandObservation({ ref, status: 'unavailable' });
+      }
+      current();
+      if (['starting', 'running'].includes(output?.status)) return null;
+      try {
+        check(output && typeof output === 'object' && !Array.isArray(output), 'invalid_background_command_output');
+        return backgroundCommandObservation({ ...output, ref,
+          outputMayBeTruncated: output.outputMayBeTruncated === true || output.stdoutCursor >= 8192 || output.stderrCursor >= 8192 });
+      } catch { return backgroundCommandObservation({ ref, status: 'unavailable' }); }
+    },
+    async observe(request) {
+      request.signal.throwIfAborted();
+      check(same(request.scope, pinnedScope), 'background_command_scope_mismatch');
+      const current = store.load(pinnedScope, request.runId);
+      const config = current.snapshot.taskContract ? { ...current.configuration, contract: current.snapshot.taskContract } : current.configuration;
+      const intent = current.intents.find(item => item.operationKey === current.snapshot.pendingIntent) ?? null;
+      const expected = commandProbe(current.snapshot, config, intent), { signal, ...plain } = request;
+      check(expected && same(expected, plain), 'background_command_owner_mismatch');
+      check(new Set(request.refs.map(ref => ref.taskId)).size === request.refs.length, 'background_command_owner_mismatch');
+      // Verify the entire request before touching any external handle.
+      const owned = request.refs.map(candidate => {
+        return ownedCommandReceipt({ scope: pinnedScope, store, current, ref: backgroundCommandRef(candidate) });
+      });
+      const observations = [];
+      for (const { ref, backend } of owned) {
+        signal.throwIfAborted();
+        const unavailable = () => backgroundCommandObservation({ ref, status: 'unavailable' });
+        if (!backend || !bindings[backend]) observations.push(unavailable());
+        else {
+          try {
+            const output = await bindings[backend]({ scope: copy(pinnedScope), sessionId: current.snapshot.sessionId,
+              runId: request.runId, ref: copy(ref), stdoutCursor: 0, stderrCursor: 0, maxBytes: 8192, waitSeconds: 0, signal });
+            signal.throwIfAborted();
+            check(output && typeof output === 'object' && !Array.isArray(output), 'invalid_background_command_output');
+            check(output.outputMayBeTruncated === undefined || typeof output.outputMayBeTruncated === 'boolean', 'invalid_background_command_output');
+            if (['starting', 'running'].includes(output.status)) continue;
+            observations.push(backgroundCommandObservation({ ...output, ref,
+              outputMayBeTruncated: output.outputMayBeTruncated === true || output.stdoutCursor >= 8192 || output.stderrCursor >= 8192,
+            }));
+          } catch (error) { signal.throwIfAborted(); observations.push(unavailable()); }
+        }
+        if (observations.length === 8) break;
+      }
+      return observations;
+    },
+  });
+}

package/src/native/browser-action-observation.mjs

@@ -0,0 +1,43 @@
+/** Diagnostic facts only: never browser authority, a receipt or replay permission. */
+const phases = new Set(['queued', 'preflight', 'replay', 'target', 'actionability', 'navigate', 'dispatch', 'settle',
+  'capture_dom', 'capture_screenshot', 'capture_controls', 'publish', 'close']);
+const outcomes = new Set(['ok', 'error', 'uncertain', 'timeout', 'canceled']);
+const keys = ['contract', 'actionId', 'kind', 'phase', 'dispatchStarted', 'dispatchCompleted', 'elapsedMs', 'timeoutMs', 'outcome', 'errorCode'];
+const safeCode = value => value === null || typeof value === 'string' && /^[a-z][a-z0-9_]{0,95}$/.test(value);
+
+export function admitBrowserActionObservation(value, action) {
+  try {
+    if (!value || typeof value !== 'object' || Array.isArray(value)
+      || Object.keys(value).length !== keys.length || !Object.keys(value).every(key => keys.includes(key))) return null;
+    value = Object.fromEntries(keys.map(key => [key, value[key]]));
+    if (value.contract !== 'browser-action-observation/v1' || value.actionId !== action.actionId || value.kind !== action.kind
+      || !phases.has(value.phase) || !outcomes.has(value.outcome) || !safeCode(value.errorCode)
+      || typeof value.dispatchStarted !== 'boolean' || typeof value.dispatchCompleted !== 'boolean'
+      || value.dispatchCompleted && !value.dispatchStarted || value.timeoutMs !== action.timeoutMs
+      || !Number.isSafeInteger(value.elapsedMs) || value.elapsedMs < 0) return null;
+    return value;
+  } catch { return null; }
+}
+
+export function createBrowserActionAttempt(action) {
+  const startedAt = performance.now();
+  return { started: false, phase: 'queued', dispatchStarted: false, dispatchCompleted: false,
+    publish(observer, { signal, internal, observation, failureCode }) {
+      if (typeof observer !== 'function') return;
+      const errorCode = internal.aborted ? signal?.aborted ? 'action_canceled' : 'action_timed_out'
+        : observation?.errorCode ?? failureCode ?? null;
+      const value = admitBrowserActionObservation({ contract: 'browser-action-observation/v1',
+        actionId: action.actionId, kind: action.kind, phase: this.phase,
+        dispatchStarted: this.dispatchStarted, dispatchCompleted: this.dispatchCompleted,
+        elapsedMs: Math.max(0, Math.round(performance.now() - startedAt)), timeoutMs: action.timeoutMs,
+        outcome: internal.aborted ? signal?.aborted ? 'canceled' : 'timeout' : observation?.status ?? 'error',
+        errorCode: safeCode(errorCode) ? errorCode : 'browser_action_error',
+      }, action);
+      if (!value) return;
+      try {
+        const pending = observer(Object.freeze(value));
+        if (pending && typeof pending.then === 'function') void Promise.resolve(pending).catch(() => {});
+      } catch { /* Observer failure cannot change browser execution. */ }
+    },
+  };
+}

package/src/native/browser-availability.mjs

@@ -0,0 +1,22 @@
+import { accessSync, constants, statSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { chromium } from 'playwright-core';
+
+function executable(path) {
+  try { return isAbsolute(path) && statSync(path).isFile() && (accessSync(path, constants.X_OK), true); }
+  catch { return false; }
+}
+
+/** Use an installed executable with a fresh browser profile. Discovery performs
+ * no download, browser launch, user-profile access or permission grant. */
+export function resolveNativeBrowserExecutable({ env = process.env, platform = process.platform,
+  bundledPath = chromium.executablePath(), canExecute = executable } = {}) {
+  const explicit = env.KSADK_BROWSER_EXECUTABLE_PATH;
+  if (explicit) return isAbsolute(explicit) && canExecute(explicit) ? explicit : null;
+  const candidates = [bundledPath,
+    ...(platform === 'darwin' ? ['/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+      '/Applications/Chromium.app/Contents/MacOS/Chromium'] : []),
+    ...(platform === 'linux' ? ['/usr/bin/chromium', '/usr/bin/chromium-browser', '/usr/bin/google-chrome'] : []),
+  ];
+  return candidates.find(path => typeof path === 'string' && isAbsolute(path) && canExecute(path)) ?? null;
+}

package/src/native/browser-canvas-metrics.mjs

@@ -0,0 +1,71 @@
+/** Host-side pixels, not page canvas APIs, supply diagnostic colour evidence.
+ * Python uses Pillow thumbnail/quantize. Node samples at most 64x64 pixels and
+ * uses a deterministic weighted median cut with at most 16 RGB buckets.
+ * Numeric values may differ; uniformity is diagnostic, never a pass verdict. */
+import { PNG } from 'pngjs';
+import { invariant } from '@kingsoftcloud/agentkit-harness-core';
+
+// JSON persists -0 as 0. Emit canonical numbers before the first receipt so
+// an in-memory result and its cold-restored durable receipt stay identical.
+const round = n => Math.round(n * 10000) / 10000 || 0;
+export function browserImageVariation(bytes) {
+  invariant(Buffer.isBuffer(bytes) && bytes.length >= 24 && bytes.length <= 16 * 1024 * 1024
+    && bytes.readUInt32BE(16) * bytes.readUInt32BE(20) <= 16 * 1024 * 1024, 'browser_canvas_image_limit');
+  const image = PNG.sync.read(bytes), histogram = new Map();
+  const width = Math.min(64, image.width), height = Math.min(64, image.height);
+  for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
+    const offset = (Math.floor((y + .5) * image.height / height) * image.width + Math.floor((x + .5) * image.width / width)) * 4;
+    const color = [...image.data.subarray(offset, offset + 3)], key = color.join(',');
+    const previous = histogram.get(key); if (previous) previous.count++; else histogram.set(key, { color, count: 1 });
+  }
+  const ranges = values => [0, 1, 2].map(channel => Math.max(...values.map(v => v.color[channel])) - Math.min(...values.map(v => v.color[channel])));
+  const buckets = [[...histogram.values()]];
+  while (buckets.length < 16) {
+    let selected = -1, range = 0, channel = 0;
+    buckets.forEach((values, i) => ranges(values).forEach((value, c) => { if (value > range) { selected = i; range = value; channel = c; } }));
+    if (selected === -1) break;
+    const values = buckets[selected].sort((a, b) => a.color[channel] - b.color[channel]);
+    const half = values.reduce((sum, value) => sum + value.count, 0) / 2;
+    let count = 0, index = 0;
+    do { count += values[index++].count; } while (count < half && index < values.length - 1);
+    buckets.splice(selected, 1, values.slice(0, index), values.slice(index));
+  }
+  const counts = buckets.map(values => values.reduce((sum, value) => sum + value.count, 0)), total = width * height;
+  const dominant = Math.max(...counts) / total;
+  return { colour_buckets: counts.length, dominant_ratio: round(dominant),
+    entropy_bits: round(-counts.reduce((sum, count) => { const p = count / total; return sum + p * Math.log2(p); }, 0)),
+    visually_uniform: counts.length <= 2 || dominant >= .995 };
+}
+
+export async function browserCanvasMetrics(page, step) {
+  const result = [], canvases = page.locator('canvas'), count = Math.min(await step(() => canvases.count()), 3);
+  for (let index = 0; index < count; index++) {
+    const canvas = canvases.nth(index), box = await step(() => canvas.boundingBox());
+    if (!box || box.width < 8 || box.height < 8) continue;
+    const viewport = page.viewportSize() ?? { width: 1280, height: 720 };
+    let handle, hidden;
+    try {
+      handle = await step(() => canvas.elementHandle());
+      // The handle owns the exact nodes/styles. No page-controlled dataset or
+      // selector is used to recover the original visibility after capture.
+      hidden = await step(() => page.evaluateHandle(element => {
+        const saved = [];
+        for (const node of document.body.querySelectorAll('*')) {
+          if (node === element || node.contains(element)) continue;
+          saved.push([node, node.style.getPropertyValue('visibility'), node.style.getPropertyPriority('visibility')]);
+          node.style.setProperty('visibility', 'hidden', 'important');
+        }
+        return saved;
+      }, handle));
+      const bytes = await step(() => canvas.screenshot({ timeout: 5000 }));
+      result.push({ index, width: Math.round(box.width * 10) / 10, height: Math.round(box.height * 10) / 10,
+        viewport_coverage: round(box.width * box.height / (viewport.width * viewport.height)), ...browserImageVariation(bytes) });
+    } catch (error) {
+      result.push({ index, error: String(error.code ?? error.name ?? 'canvas_capture_failed').slice(0, 500) });
+    } finally {
+      try { if (hidden) await step(() => hidden.evaluate(saved => { for (const [node, value, priority] of saved) node.style.setProperty('visibility', value, priority); })); }
+      finally { await hidden?.dispose().catch(() => {}); await handle?.dispose().catch(() => {}); }
+    }
+  }
+  return result;
+}

package/src/native/browser-dom.mjs

@@ -0,0 +1,193 @@
+/** Bounded host-owned DOM handles for the Native Playwright browser adapter.
+ *
+ * Ported from ksadk/harness/browser_adapters/native_dom_snapshot.py @ 355059d. One page task
+ * samples the DOM channels and returns metadata plus the exact elements that produced it.
+ * Input values stay excluded; page-provided text never mints reference IDs. Element handles are
+ * host-owned and stored only in this process-local map, never in page globals or DOM attributes.
+ *
+ * Format differences from the Python source (documented per the migration contract):
+ *  - The page function returns camelCase meta/control keys (scrollX, scrollY, pointerLockActive,
+ *    hitTestReachable, duplicateId) instead of Python's snake_case, matching the TS browser
+ *    contract's camelCase BrowserObservation/BrowserControl. The capture logic is otherwise a
+ *    faithful port of DOM_CAPTURE.
+ *  - getProperties() returns a Map in Playwright JS (a dict in Python); iteration is adapted.
+ *  - randomUUID() (with dashes stripped) replaces uuid4().hex; tokens remain 32 hex chars.
+ */
+import { randomUUID } from 'node:crypto';
+
+/** Self-contained page function. Runs in the page; must not close over any module variable.
+ *  Returns { refElements, meta }. refElements is the live node list used to mint element refs;
+ *  meta is the JSON-serializable observation sample (no input values). */
+function domCapture() {
+  const semantic = Array.from(document.querySelectorAll(
+    'button,input,textarea,select,a[href],[role="button"],[contenteditable="true"]'
+  ));
+  const pointer = Array.from(document.querySelectorAll('*')).slice(0, 4000).filter((el) => {
+    const isPointer = getComputedStyle(el).cursor === 'pointer';
+    return isPointer && (!el.parentElement || getComputedStyle(el.parentElement).cursor !== 'pointer');
+  });
+  const nodes = Array.from(new Set([...semantic, ...pointer]));
+  const visible = nodes.filter((el) => {
+    const rect = el.getBoundingClientRect();
+    const style = getComputedStyle(el);
+    const type = (el.getAttribute('type') || '').toLowerCase();
+    return rect.width > 0 && rect.height > 0 && style.visibility !== 'hidden'
+      && style.display !== 'none' && type !== 'password' && type !== 'hidden';
+  });
+  const structuralSelector = (el) => {
+    const parts = [];
+    let node = el;
+    while (node && node.nodeType === 1 && parts.length < 20) {
+      const id = node.id && globalThis.CSS && CSS.escape ? '#' + CSS.escape(node.id) : null;
+      if (id && document.querySelectorAll(id).length === 1) { parts.unshift(id); break; }
+      const tag = node.tagName.toLowerCase();
+      const siblings = node.parentElement
+        ? Array.from(node.parentElement.children).filter((sibling) => sibling.tagName === node.tagName)
+        : [node];
+      parts.unshift(tag + ':nth-of-type(' + (siblings.indexOf(node) + 1) + ')');
+      node = node.parentElement;
+    }
+    if (node && node.parentElement && parts.length >= 20) return null;
+    const candidate = parts.join(' > ');
+    return candidate && candidate.length <= 512 && document.querySelectorAll(candidate).length === 1
+      ? candidate : null;
+  };
+  const refElements = visible.slice(0, 40);
+  const controls = refElements.map((el) => {
+    const tag = el.tagName.toLowerCase();
+    const rect = el.getBoundingClientRect();
+    const inViewport = rect.right > 0 && rect.bottom > 0 && rect.left < innerWidth && rect.top < innerHeight;
+    const hitX = Math.max(0, Math.min(innerWidth - 1,
+      (Math.max(0, rect.left) + Math.min(innerWidth, rect.right)) / 2));
+    const hitY = Math.max(0, Math.min(innerHeight - 1,
+      (Math.max(0, rect.top) + Math.min(innerHeight, rect.bottom)) / 2));
+    const hit = inViewport ? document.elementFromPoint(hitX, hitY) : null;
+    const id = el.id && globalThis.CSS && CSS.escape ? '#' + CSS.escape(el.id) : null;
+    const duplicateId = Boolean(id && document.querySelectorAll(id).length > 1);
+    const selector = duplicateId ? null : id || structuralSelector(el);
+    const label = el.getAttribute('aria-label') || (el.labels && el.labels[0] ? el.labels[0].innerText : '')
+      || el.getAttribute('placeholder') || el.innerText || '';
+    return {
+      tag,
+      role: el.getAttribute('role') || '',
+      label: Array.from(String(label).trim()).slice(0, 160).join(''),
+      selector,
+      duplicateId,
+      clickable: tag === 'button' || el.getAttribute('role') === 'button'
+        || getComputedStyle(el).cursor === 'pointer',
+      hitTestReachable: !inViewport ? null : !el.matches(':disabled') && (hit === el || el.contains(hit))
+    };
+  });
+  return {
+    refElements,
+    meta: {
+      url: location.href,
+      title: document.title,
+      text: (document.body && document.body.innerText) || '',
+      focus: (document.activeElement && document.activeElement.tagName) || '',
+      scrollX: Math.round(window.scrollX),
+      scrollY: Math.round(window.scrollY),
+      lifecycle: document.readyState,
+      pointerLockActive: Boolean(document.pointerLockElement),
+      controls
+    }
+  };
+}
+
+async function disposeHandles(handles) {
+  for (const handle of handles) {
+    try { await handle.dispose(); } catch { /* navigation/closing may have released the context */ }
+  }
+}
+
+/** Latest bounded observation; unchanged DOM nodes retain their opaque ID across captures. */
+export class BrowserElementRefs {
+  constructor() { this._elements = new Map(); }
+
+  async clear() {
+    const previous = this._elements;
+    this._elements = new Map();
+    await disposeHandles([...previous.values()]);
+  }
+
+  /** Capture one DOM sample. Returns { meta, tokens } where tokens[i] is the opaque ref for
+   *  control i (or null if no element was retained). Unchanged nodes keep their prior token. */
+  async capture(page) {
+    const transient = [];
+    const acquired = [];
+    let adopted = false;
+    try {
+      const collection = await page.evaluateHandle(domCapture);
+      transient.push(collection);
+      const metadata = await collection.getProperty('meta');
+      transient.push(metadata);
+      const nodes = await collection.getProperty('refElements');
+      transient.push(nodes);
+      const meta = await metadata.jsonValue();
+      if (!meta || typeof meta !== 'object' || Array.isArray(meta)) throw new Error('invalid DOM snapshot');
+
+      const handles = new Map();
+      const props = await nodes.getProperties(); // Map<string, JSHandle>
+      for (const [index, handle] of props) {
+        acquired.push(handle);
+        const element = handle.asElement();
+        if (/^\d+$/.test(index) && Number(index) < 40 && element) handles.set(Number(index), element);
+      }
+
+      let priorTokens = [...this._elements.keys()];
+      let priorHandles = [...this._elements.values()];
+      if (priorHandles.length > 0) {
+        let sameDocument = false;
+        try { sameDocument = await priorHandles[0].evaluate((node) => node.ownerDocument === document); }
+        catch { sameDocument = false; }
+        if (!sameDocument) {
+          // A successful click can navigate without _navigate(); its old execution context cannot
+          // supply refs to the new document, which does not justify replaying that click.
+          await this.clear();
+          priorTokens = [];
+          priorHandles = [];
+        }
+      }
+
+      // Compare actual node identity in one browser task, without writing refs into an untrusted
+      // DOM/global map or one RPC per element pair.
+      const matches = handles.size > 0
+        ? await nodes.evaluate((nodesArr, prior) => nodesArr.map((node) => prior.indexOf(node)), priorHandles)
+        : [];
+
+      const refs = new Map();
+      const tokens = [];
+      const controls = Array.isArray(meta.controls) ? meta.controls : [];
+      for (let index = 0; index < Math.min(40, controls.length); index++) {
+        const element = handles.get(index);
+        if (!element) { tokens.push(null); continue; }
+        const match = index < matches.length ? matches[index] : -1;
+        const token = (match >= 0 && match < priorTokens.length) ? priorTokens[match] : randomUUID().replace(/-/g, '');
+        refs.set(token, element);
+        tokens.push(token);
+      }
+
+      const previous = this._elements;
+      this._elements = refs;
+      adopted = true;
+      const retained = new Set(refs.values());
+      await disposeHandles([...previous.values(), ...acquired.filter((h) => !retained.has(h))]);
+      return { meta, tokens };
+    } finally {
+      if (!adopted) await disposeHandles(acquired);
+      await disposeHandles(transient);
+    }
+  }
+
+  /** Resolve a token to a live ElementHandle, or null if it is stale/detached/foreign. */
+  async resolve(token) {
+    const element = this._elements.get(token);
+    if (!element) return null;
+    try {
+      const connected = await element.evaluate((node) => node.isConnected);
+      return connected ? element : null;
+    } catch { return null; }
+  }
+}
+
+export { domCapture, domCapture as DOM_CAPTURE };