@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/annotations/inspect.js

@@ -0,0 +1,34 @@
+// One step of the inspector loop (PROP-0018), shared by the terminal and a host: read the next
+// comment from the capture target, keep it as a note, act on the button the person pressed, and
+// tell them in the page what happened. Whether a send goes straight to the agent depends on where
+// the comment came from, never on what the page or a client claims.
+import { now } from "../core/fs.js";
+function message(action, note, send, sessionId) {
+    if (!sessionId)
+        return 'Annotation saved';
+    if (note.delivery?.confirm)
+        return action === 'send' ? 'Annotated — confirm sending it in the terminal' : 'Annotated — confirm it in the terminal before it is sent';
+    if (action === 'save')
+        return 'Annotated — the agent can read it';
+    if (send?.state === 'sent')
+        return 'Sent to the agent';
+    if (send?.state === 'busy')
+        return 'Annotated — it goes to the agent when it finishes';
+    return 'Sending to the agent';
+}
+export async function inspectStep(capture, notes, key, sessionId, surface) {
+    const state = await capture.next(key);
+    const { result, ...rest } = state;
+    if (!result)
+        return { ...rest, note: null, send: null, message: null };
+    // Anything but a send is a save, whatever the page reports.
+    const action = sessionId && result.action === 'send' ? 'send' : 'save';
+    const { note, send } = await notes.createAndAct({
+        source: { url: result.url, title: result.title, capturedAt: now(), surface, representationHint: result.documentId, ...(state.app ? { app: state.app } : {}) },
+        target: result.target,
+        body: result.body
+    }, action, sessionId, state.trusted);
+    const text = message(action, note, send, sessionId);
+    await capture.toast(key, text).catch(() => undefined);
+    return { ...rest, note, send, message: text };
+}

package/dist/sdk/annotations/isolated.d.ts

@@ -0,0 +1,6 @@
+import type { Page } from 'playwright-core';
+/** Evaluates `expression` (which yields a JSON string) and says whether the page could have reached it. */
+export declare function evaluateIsolated(page: Page, expression: string): Promise<{
+    reply: unknown;
+    trusted: boolean;
+}>;

package/dist/sdk/annotations/isolated.js

@@ -0,0 +1,51 @@
+const WORLD = 'harness-page-notes';
+const worlds = new WeakMap();
+const watched = new WeakSet();
+async function createWorld(page) {
+    const cdp = await page.context().newCDPSession(page);
+    const { frameTree } = await cdp.send('Page.getFrameTree');
+    const { executionContextId } = await cdp.send('Page.createIsolatedWorld', { frameId: frameTree.frame.id, worldName: WORLD, grantUniveralAccess: false });
+    const world = { cdp, contextId: executionContextId };
+    worlds.set(page, world);
+    if (!watched.has(page)) {
+        watched.add(page);
+        // A new document destroys the world; the next call makes another.
+        page.on('framenavigated', (frame) => {
+            if (frame !== page.mainFrame())
+                return;
+            const old = worlds.get(page);
+            worlds.delete(page);
+            void old?.cdp.detach().catch(() => undefined);
+        });
+    }
+    return world;
+}
+/** Evaluates `expression` (which yields a JSON string) and says whether the page could have reached it. */
+export async function evaluateIsolated(page, expression) {
+    if (typeof page.context !== 'function' || typeof page.context().newCDPSession !== 'function') {
+        return { reply: await page.evaluate(expression), trusted: false };
+    }
+    let lastError = null;
+    for (let attempt = 0; attempt < 2; attempt++) {
+        let world = worlds.get(page) ?? null;
+        try {
+            world ??= await createWorld(page);
+            const evaluated = await world.cdp.send('Runtime.evaluate', { expression, contextId: world.contextId, returnByValue: true, awaitPromise: false });
+            if (evaluated.exceptionDetails)
+                throw new Error(evaluated.exceptionDetails.text || 'The page helper failed.');
+            return { reply: evaluated.result?.value, trusted: true };
+        }
+        catch (error) {
+            lastError = error;
+            worlds.delete(page);
+            void world?.cdp.detach().catch(() => undefined);
+            // A context that went away with a navigation is made again once; anything else falls back.
+            if (attempt === 0 && /context|target closed|detached/i.test(String(error)))
+                continue;
+            break;
+        }
+    }
+    if (/closed/i.test(String(lastError)))
+        throw lastError;
+    return { reply: await page.evaluate(expression), trusted: false };
+}

package/dist/sdk/annotations/pageScript.d.ts

@@ -0,0 +1,28 @@
+/** The helper's source. `__ARGS__` is replaced with one JSON operation; the expression evaluates to a JSON string. */
+export declare const PAGE_SCRIPT: string;
+export type PageOperation = {
+    operation: 'identity';
+} | {
+    operation: 'begin';
+    kind: 'text' | 'element' | 'inspect';
+    captureId: string;
+} | {
+    operation: 'capture';
+    captureId: string;
+} | {
+    operation: 'next';
+    captureId: string;
+} | {
+    operation: 'toast';
+    text: string;
+} | {
+    operation: 'cancel';
+    captureId?: string;
+} | {
+    operation: 'resolve' | 'reveal';
+    target: unknown;
+};
+/** The expression to evaluate in the page for one operation. */
+export declare function pageCall(operation: PageOperation): string;
+/** Reads the helper's reply, throwing its error. */
+export declare function pageReply<T>(reply: unknown): T;