@nuanu-ai/agentbrowse 0.2.7 → 0.2.8

package/dist/control-semantics.js

@@ -0,0 +1,299 @@
+const DATE_LIKE_LABEL_RE = /(?:\b\d{1,2}\b|январ|феврал|март|апрел|ма[йя]|июн|июл|август|сентябр|октябр|ноябр|декабр|january|february|march|april|may|june|july|august|september|october|november|december|date|дата|calendar|datepicker|календар)/i;
+const SUBMIT_LABEL_RE = /(?:buy|book|continue|search|find|open|submit|next|pay|купить|забронировать|продолжить|найти|открыть|оплатить)/i;
+const PREREQUISITE_HINT_RE = /(?:choose|select|pick|set|enter|fill|complete)\b.*\b(?:first|before)\b|(?:first|before)\b.*\b(?:choose|select|pick|set|enter|fill|complete)\b|(?:сначала|сперва)\b.*\b(?:выберите|заполните|укажите|введите|завершите)\b|\b(?:выберите|заполните|укажите|введите|завершите)\b.*\b(?:сначала|сперва)\b|required first|available after|unlock/i;
+const PHONE_FIELD_RE = /\b(phone|mobile|telephone|tel)\b/i;
+const CARD_NUMBER_FIELD_RE = /\b(card.?number|cc.?number|cardnumber|pan|cc-number)\b/i;
+const CARD_EXPIRY_FIELD_RE = /\b(exp(?:iry|iration)(?: date)?|cc-exp|valid\s+thru|valid\s+through|mm\s*\/\s*yy(?:yy)?)\b/i;
+const CARD_CVC_FIELD_RE = /\b(cvc|cvv|cc-csc|security code|card cvc)\b/i;
+const DATE_VALUE_MASK_RE = /(?:^|\b)(?:dd|d|дд|д)\s*[./-]\s*(?:mm|m|мм|м)\s*[./-]\s*(?:yyyy|yyy|yy|y|гггг|гг|г)(?:\b|$)/i;
+const NON_CARD_DATE_FIELD_RE = /\b(?:birth|dob|date|issued|expires|expiry|expiration|expir)\b|(?:дата|рожд|срок)/i;
+function normalizeText(value) {
+    return (value ?? '').trim().toLowerCase();
+}
+function primaryLabel(facts) {
+    return facts.label ?? facts.displayLabel ?? facts.text ?? facts.placeholder ?? '';
+}
+function valueTypeHintBlob(facts) {
+    return [
+        facts.label,
+        facts.displayLabel,
+        facts.text,
+        facts.placeholder,
+        facts.inputName,
+        facts.autocomplete,
+    ]
+        .filter((value) => Boolean(value))
+        .join(' ')
+        .trim();
+}
+export function inferComparableValueTypeFromFacts(facts) {
+    const inputType = normalizeText(facts.inputType);
+    const autocomplete = normalizeText(facts.autocomplete);
+    const hintBlob = valueTypeHintBlob(facts);
+    if (inputType === 'tel' ||
+        autocomplete.includes('tel') ||
+        PHONE_FIELD_RE.test(hintBlob)) {
+        return 'phone';
+    }
+    if (autocomplete.includes('cc-number') || CARD_NUMBER_FIELD_RE.test(hintBlob)) {
+        return 'card-number';
+    }
+    const cardExpiryLike = autocomplete.includes('cc-exp') ||
+        (inputType !== 'date' &&
+            CARD_EXPIRY_FIELD_RE.test(hintBlob) &&
+            (autocomplete.startsWith('cc-') ||
+                /\b(card|credit|debit)\b/i.test(hintBlob) ||
+                /\bmm\s*\/\s*yy(?:yy)?\b/i.test(hintBlob)));
+    if (cardExpiryLike) {
+        return 'expiry';
+    }
+    if (autocomplete.includes('cc-csc') || CARD_CVC_FIELD_RE.test(hintBlob)) {
+        return 'cvc';
+    }
+    const nonCardDateLike = inputType === 'date' ||
+        DATE_VALUE_MASK_RE.test(hintBlob) ||
+        (NON_CARD_DATE_FIELD_RE.test(hintBlob) &&
+            !autocomplete.startsWith('cc-') &&
+            !/\b(card|credit|debit|cvc|cvv|security code)\b/i.test(hintBlob));
+    if (nonCardDateLike) {
+        return 'date';
+    }
+    return undefined;
+}
+function isPopupBackedTextEntry(facts) {
+    const kind = normalizeText(facts.kind);
+    const role = normalizeText(facts.role);
+    const surfaceKind = normalizeText(facts.surfaceKind);
+    if ((kind === 'input' || kind === 'textarea' || role === 'textbox') &&
+        (Boolean(facts.controlsSurfaceSelector) ||
+            surfaceKind === 'listbox' ||
+            surfaceKind === 'menu' ||
+            facts.states?.expanded !== undefined)) {
+        return true;
+    }
+    return false;
+}
+function isSelectLikePopupOwner(facts) {
+    const kind = normalizeText(facts.kind);
+    const role = normalizeText(facts.role);
+    if (kind === 'select' || kind === 'combobox' || role === 'combobox') {
+        return true;
+    }
+    return isPopupBackedTextEntry(facts) && facts.states?.readonly === true;
+}
+function isButtonLikeInputFacts(facts) {
+    return (normalizeText(facts.kind) === 'input' &&
+        ['button', 'submit', 'reset'].includes(normalizeText(facts.inputType)));
+}
+export function isLikelyDateLikeLabel(value) {
+    const trimmed = (value ?? '').trim();
+    if (!trimmed) {
+        return false;
+    }
+    if (/^\+?\d{1,4}$/.test(trimmed)) {
+        return false;
+    }
+    if (/\+\d{1,4}\b/.test(trimmed)) {
+        return false;
+    }
+    return DATE_LIKE_LABEL_RE.test(trimmed);
+}
+export function inferAllowedActionsFromFacts(facts) {
+    const kind = normalizeText(facts.kind);
+    const role = normalizeText(facts.role);
+    const interactionHint = normalizeText(facts.interactionHint);
+    const legacyMethod = normalizeText(facts.legacyMethod);
+    const selectLikePopupOwner = isSelectLikePopupOwner(facts);
+    const buttonLikeInput = isButtonLikeInputFacts(facts);
+    const actions = new Set();
+    if (selectLikePopupOwner) {
+        actions.add('click');
+        actions.add('select');
+        actions.add('press');
+        if (facts.surfaceKind === 'datepicker' || isLikelyDateLikeLabel(primaryLabel(facts))) {
+            actions.add('fill');
+        }
+        if (kind === 'combobox' || role === 'combobox') {
+            actions.add('fill');
+            actions.add('type');
+        }
+    }
+    else if (!buttonLikeInput && (kind === 'input' || kind === 'textarea' || role === 'textbox')) {
+        actions.add('click');
+        actions.add('fill');
+        actions.add('type');
+        actions.add('press');
+    }
+    if (!selectLikePopupOwner && (kind === 'select' || kind === 'combobox' || role === 'combobox')) {
+        actions.add('click');
+        actions.add('select');
+        actions.add('press');
+        if (kind === 'combobox' || role === 'combobox') {
+            actions.add('fill');
+            actions.add('type');
+        }
+    }
+    if (kind === 'option' || role === 'option' || role === 'menuitem') {
+        actions.add('click');
+    }
+    if (role === 'gridcell' || facts.structure?.family === 'structured-grid') {
+        actions.add('click');
+        actions.add('press');
+    }
+    if (kind === 'button' || kind === 'link' || role === 'button' || role === 'link') {
+        actions.add('click');
+        actions.add('press');
+    }
+    if (interactionHint === 'click') {
+        actions.add('click');
+        actions.add('press');
+    }
+    if (legacyMethod === 'click') {
+        actions.add('click');
+        actions.add('press');
+    }
+    if (legacyMethod === 'fill') {
+        actions.add('click');
+        actions.add('fill');
+        actions.add('type');
+        actions.add('press');
+    }
+    if (legacyMethod === 'type') {
+        actions.add('click');
+        actions.add('type');
+        actions.add('press');
+    }
+    if (legacyMethod === 'select') {
+        actions.add('click');
+        actions.add('select');
+        actions.add('press');
+    }
+    if (legacyMethod === 'press') {
+        actions.add('press');
+    }
+    return [...actions];
+}
+export function inferAvailabilityFromFacts(states, contextHint, options = {}) {
+    if (states?.occupied === true) {
+        return { state: 'gated', reason: 'occupied' };
+    }
+    const blocked = states?.disabled === true ||
+        states?.ariaDisabled === true ||
+        states?.readonly === true ||
+        states?.selectable === false;
+    if (blocked && PREREQUISITE_HINT_RE.test(contextHint ?? '')) {
+        return { state: 'gated', reason: 'prerequisite' };
+    }
+    if (states?.selectable === false) {
+        return { state: 'gated', reason: 'not-selectable' };
+    }
+    if (states?.disabled === true || states?.ariaDisabled === true) {
+        return { state: 'gated', reason: 'disabled' };
+    }
+    if (states?.readonly === true) {
+        if (options.readonlyInteractive) {
+            return { state: 'available' };
+        }
+        return { state: 'gated', reason: 'readonly' };
+    }
+    return { state: 'available' };
+}
+export function inferControlFamilyFromFacts(facts, allowedActions) {
+    const kind = normalizeText(facts.kind);
+    const role = normalizeText(facts.role);
+    const legacyMethod = normalizeText(facts.legacyMethod);
+    const label = primaryLabel(facts);
+    const dateLike = isLikelyDateLikeLabel(label) || facts.surfaceKind === 'datepicker';
+    const comparableValueType = inferComparableValueTypeFromFacts(facts);
+    if (facts.structure?.family === 'structured-grid') {
+        return 'structured-grid';
+    }
+    if (comparableValueType === 'expiry') {
+        return 'text-input';
+    }
+    if (dateLike &&
+        (kind === 'input' ||
+            kind === 'textarea' ||
+            kind === 'select' ||
+            kind === 'combobox' ||
+            role === 'textbox' ||
+            role === 'combobox' ||
+            kind === 'option' ||
+            role === 'option' ||
+            role === 'menuitem' ||
+            allowedActions.includes('select') ||
+            legacyMethod === 'select')) {
+        return 'datepicker';
+    }
+    if (isSelectLikePopupOwner(facts) ||
+        kind === 'option' ||
+        role === 'option' ||
+        role === 'menuitem' ||
+        allowedActions.includes('select') ||
+        legacyMethod === 'select') {
+        return 'select';
+    }
+    if (isButtonLikeInputFacts(facts)) {
+        return 'trigger';
+    }
+    if (kind === 'input' ||
+        kind === 'textarea' ||
+        role === 'textbox' ||
+        allowedActions.includes('fill') ||
+        allowedActions.includes('type') ||
+        legacyMethod === 'fill' ||
+        legacyMethod === 'type') {
+        return 'text-input';
+    }
+    if (kind === 'button' ||
+        kind === 'link' ||
+        role === 'button' ||
+        role === 'link' ||
+        allowedActions.includes('click') ||
+        allowedActions.includes('press') ||
+        legacyMethod === 'click' ||
+        legacyMethod === 'press') {
+        return 'trigger';
+    }
+    return undefined;
+}
+export function inferAcceptancePolicyFromFacts(facts, allowedActions) {
+    const legacyMethod = normalizeText(facts.legacyMethod);
+    const label = primaryLabel(facts);
+    const states = facts.states;
+    const kind = normalizeText(facts.kind);
+    const role = normalizeText(facts.role);
+    const controlFamily = inferControlFamilyFromFacts(facts, allowedActions);
+    if (facts.structure?.family === 'structured-grid') {
+        return facts.structure.variant === 'date-cell' ? 'date-selection' : 'selection';
+    }
+    if (states?.checked !== undefined ||
+        states?.selected !== undefined ||
+        states?.pressed !== undefined) {
+        return 'toggle';
+    }
+    if (controlFamily === 'text-input') {
+        return 'value-change';
+    }
+    if (states?.expanded !== undefined) {
+        return 'disclosure';
+    }
+    if (controlFamily === 'datepicker') {
+        return 'date-selection';
+    }
+    if (controlFamily === 'select') {
+        return 'selection';
+    }
+    if (role === 'link' || kind === 'link') {
+        return 'navigation';
+    }
+    if (!legacyMethod && SUBMIT_LABEL_RE.test(label)) {
+        return 'submit';
+    }
+    if (controlFamily === 'trigger' ||
+        legacyMethod === 'click' ||
+        legacyMethod === 'press') {
+        return 'generic-click';
+    }
+    return undefined;
+}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AA8KA,iBAAe,IAAI,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsGhE;AAED,OAAO,EAAE,IAAI,EAAE,CAAC;AAEhB,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAWzF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAqNA,iBAAe,IAAI,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmJhE;AAED,OAAO,EAAE,IAAI,EAAE,CAAC;AAEhB,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAWzF"}

package/dist/index.js

@@ -14,9 +14,15 @@ Commands:
   launch [url] [options]          Launch browser, optionally navigate to URL
   solve-captcha [--timeout <s>]   Wait for captcha and solve it on current page
   navigate <url>                  Navigate current tab to URL
-  act "<instruction>"             Perform an action (click, type, scroll...)
-  extract "<instruction>"         Extract data from the page
-  observe ["<instruction>"]       Discover available actions/elements
+  get-secrets-catalog [url]       Refresh stored-secret metadata for a URL or current page
+  create-intent <fillRef> <storedSecretRef>
+                                  Create or reuse an intent for one stored secret fill
+  poll-intent <intentId>          Poll stored-secret intent status
+  fill-secret <fillRef> <intentId>
+                                  Fill protected fields from the one-time delivered secret payload
+  act <targetRef> <action> [value] Perform action on a previously observed target
+  extract '<schema-json>' [scopeRef] Extract structured data from the page or a stored scope
+  observe ["<goal>"]              Discover available targets/elements
   screenshot [--path <file>]      Capture a screenshot
   status                          Check browser state
   close                           Close browser and clean up
@@ -26,8 +32,7 @@ Options:
   --full                          Launch browser in full-size window
   --profile <name>                Solver profile name for launch (default: "default")
   --headless                      Launch browser in headless mode
-  --schema '<json>'               Schema for extract (e.g. '{"price":"number"}')
-  --variables '<json>'            Variables for act (sensitive, not sent to LLM)
+  --no-headless                   Explicit alias for visible browser mode
   --path <file>                   Output path for screenshot
   --timeout <seconds>             Timeout for solve-captcha command (default: 90)
   --help                          Show this help message
@@ -39,6 +44,10 @@ Environment:
 const KNOWN_COMMANDS = new Set([
     'launch',
     'navigate',
+    'get-secrets-catalog',
+    'create-intent',
+    'poll-intent',
+    'fill-secret',
     'solve-captcha',
     'act',
     'extract',
@@ -82,6 +91,21 @@ function getPositional(args, valueFlags = []) {
     }
     return undefined;
 }
+function getPositionals(args, valueFlags = []) {
+    const valueFlagSet = new Set(valueFlags);
+    const values = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg.startsWith('--')) {
+            if (valueFlagSet.has(arg)) {
+                i += 1;
+            }
+            continue;
+        }
+        values.push(arg);
+    }
+    return values;
+}
 function parseLaunchArgs(args) {
     let url;
     let compact = true;
@@ -93,6 +117,10 @@ function parseLaunchArgs(args) {
             headless = true;
             continue;
         }
+        if (arg === '--no-headless') {
+            headless = false;
+            continue;
+        }
         if (arg === '--compact') {
             compact = true;
             continue;
@@ -128,15 +156,19 @@ function parseCaptchaTimeout(args) {
     }
     return timeout;
 }
-/** Require an active browser session, return CDP URL. */
-function requireSession() {
+/** Require an active browser session. */
+function requireSessionRecord() {
     const session = loadSession();
     if (session)
-        return session.cdpUrl;
+        return session;
     // Fallback: try CDP on port 9222 directly
     // (Chrome may have been launched by agentpay-cli or externally)
-    // Caller will handle connection errors.
-    return 'ws://localhost:9222';
+    // Caller will handle connection errors. Runtime state starts empty.
+    return {
+        cdpUrl: 'ws://localhost:9222',
+        pid: process.pid,
+        launchedAt: new Date().toISOString(),
+    };
 }
 async function main(argv = process.argv) {
     const parsed = getCommand(argv);
@@ -168,7 +200,42 @@ async function main(argv = process.argv) {
             if (!url)
                 outputError(`Usage: ${browseCommand('navigate', '<url>')}`);
             const { navigate } = await import('./commands/navigate.js');
-            await navigate(requireSession(), url);
+            await navigate(requireSessionRecord(), url);
+            break;
+        }
+        case 'get-secrets-catalog': {
+            const url = getPositional(args);
+            const { getSecretsCatalog } = await import('./commands/get-secrets-catalog.js');
+            await getSecretsCatalog(requireSessionRecord(), url);
+            break;
+        }
+        case 'create-intent': {
+            const positionals = getPositionals(args);
+            const [fillRef, storedSecretRef] = positionals;
+            if (!fillRef || !storedSecretRef) {
+                outputError(`Usage: ${browseCommand('create-intent', '<fillRef>', '<storedSecretRef>')}`);
+            }
+            const { createIntent } = await import('./commands/create-intent.js');
+            await createIntent(requireSessionRecord(), fillRef, storedSecretRef);
+            break;
+        }
+        case 'poll-intent': {
+            const intentId = getPositional(args);
+            if (!intentId) {
+                outputError(`Usage: ${browseCommand('poll-intent', '<intentId>')}`);
+            }
+            const { pollIntent } = await import('./commands/poll-intent.js');
+            await pollIntent(requireSessionRecord(), intentId);
+            break;
+        }
+        case 'fill-secret': {
+            const positionals = getPositionals(args);
+            const [fillRef, intentId] = positionals;
+            if (!fillRef || !intentId) {
+                outputError(`Usage: ${browseCommand('fill-secret', '<fillRef>', '<intentId>')}`);
+            }
+            const { fillSecret } = await import('./commands/fill-secret.js');
+            await fillSecret(requireSessionRecord(), fillRef, intentId);
             break;
         }
         case 'solve-captcha': {
@@ -178,36 +245,32 @@ async function main(argv = process.argv) {
             break;
         }
         case 'act': {
-            const instruction = getPositional(args, ['--variables']);
-            if (!instruction)
-                outputError(`Usage: ${browseCommand('act', '"<instruction>"')}`);
-            let variables;
-            const varsJson = getFlag(args, '--variables');
-            if (varsJson) {
-                try {
-                    variables = JSON.parse(varsJson);
-                }
-                catch {
-                    outputError('Invalid --variables JSON');
-                }
+            const positionals = getPositionals(args);
+            const [targetRef, action, ...valueParts] = positionals;
+            if (!targetRef || !action) {
+                outputError(`Usage: ${browseCommand('act', '<targetRef>', '<action>', '[value]')}`);
+            }
+            const { act, isBrowseAction } = await import('./commands/act.js');
+            if (!isBrowseAction(action)) {
+                outputError(`Unsupported act action: ${action}. Expected one of: click, fill, type, select, press.`);
             }
-            const { act } = await import('./commands/act.js');
-            await act(requireSession(), instruction, variables);
+            await act(requireSessionRecord(), targetRef, action, valueParts.length > 0 ? valueParts.join(' ') : undefined);
             break;
         }
         case 'extract': {
-            const instruction = getPositional(args, ['--schema']);
-            if (!instruction)
-                outputError(`Usage: ${browseCommand('extract', '"<instruction>"')}`);
-            const schemaJson = getFlag(args, '--schema');
+            const positionals = getPositionals(args);
+            const [schemaJson, scopeRef] = positionals;
+            if (!schemaJson) {
+                outputError(`Usage: ${browseCommand('extract', "'<schema-json>'", '[scopeRef]')}`);
+            }
             const { extract } = await import('./commands/extract.js');
-            await extract(requireSession(), instruction, schemaJson);
+            await extract(requireSessionRecord(), schemaJson, scopeRef);
             break;
         }
         case 'observe': {
             const instruction = getPositional(args);
             const { observe } = await import('./commands/observe.js');
-            await observe(requireSession(), instruction);
+            await observe(requireSessionRecord(), instruction);
             break;
         }
         case 'screenshot': {
@@ -217,7 +280,7 @@ async function main(argv = process.argv) {
             }
             const filePath = getFlag(args, '--path');
             const { screenshot } = await import('./commands/screenshot.js');
-            await screenshot(requireSession(), filePath);
+            await screenshot(requireSessionRecord(), filePath);
             break;
         }
         case 'status': {

package/dist/output.d.ts

@@ -1,6 +1,6 @@
 /**
  * Structured output helpers.
- * Human-readable text to stdout/stderr.
+ * Machine-readable JSON to stdout.
  */
 export interface BrowseResult {
     success: boolean;
@@ -9,8 +9,20 @@ export interface BrowseResult {
     title?: string;
     [key: string]: unknown;
 }
-/** Write result to stdout and exit. Errors go to stderr with exit 1. */
+export interface BrowseContractFailure extends Omit<BrowseResult, 'success'> {
+    error: string;
+    outcomeType: string;
+    message: string;
+    reason: string;
+}
+/** Write final structured result to stdout and exit. */
 export declare function outputJSON(result: BrowseResult): never;
+/** Write structured failure result to stdout and exit 1. */
+export declare function outputFailure(result: Omit<BrowseResult, 'success'> & {
+    error: string;
+}): never;
+/** Write a normalized contract failure result to stderr and exit 1. */
+export declare function outputContractFailure(result: BrowseContractFailure): never;
 /** Write error to stderr and exit 1. */
 export declare function outputError(error: string): never;
 /** Write a progress/info message to stderr. */

package/dist/output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAEH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AASD,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,KAAK,CAsBtD;AAED,wCAAwC;AACxC,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAEhD;AAED,+CAA+C;AAC/C,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1C;AAED,6CAA6C;AAC7C,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAG5C"}
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAEA;;;GAGG;AAEH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,qBAAsB,SAAQ,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC;IAC1E,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAMD,wDAAwD;AACxD,wBAAgB,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,KAAK,CAMtD;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,KAAK,CAE9F;AAED,uEAAuE;AACvE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,KAAK,CAE1E;AAED,wCAAwC;AACxC,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAEhD;AAED,+CAA+C;AAC/C,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1C;AAED,6CAA6C;AAC7C,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAG5C"}

package/dist/output.js

@@ -1,38 +1,26 @@
 import { browseCommandName } from './command-name.js';
-/** Format a value for display. Objects/arrays → indented JSON, rest → string. */
-function formatValue(value) {
-    if (value === null || value === undefined)
-        return '';
-    if (typeof value === 'object')
-        return JSON.stringify(value, null, 2);
-    return String(value);
+function serializeResult(result) {
+    return `${JSON.stringify(result, null, 2)}\n`;
 }
-/** Write result to stdout and exit. Errors go to stderr with exit 1. */
+/** Write final structured result to stdout and exit. */
 export function outputJSON(result) {
-    if (!result.success) {
-        process.stderr.write(`${result.error ?? 'Unknown error'}\n`);
-        process.exit(1);
-    }
-    const { success: _, ...rest } = result;
-    const entries = Object.entries(rest).filter(([, v]) => v !== undefined);
-    if (entries.length === 0) {
-        process.exit(0);
-    }
-    const maxKey = Math.max(...entries.map(([k]) => k.length));
-    for (const [key, value] of entries) {
-        const formatted = formatValue(value);
-        if (typeof value === 'object' && value !== null) {
-            process.stdout.write(`${key}:\n${formatted}\n`);
-        }
-        else {
-            process.stdout.write(`${key.padEnd(maxKey)}  ${formatted}\n`);
-        }
-    }
-    process.exit(0);
+    const normalizedResult = result.success
+        ? result
+        : { ...result, error: result.error ?? 'Unknown error' };
+    process.stdout.write(serializeResult(normalizedResult));
+    process.exit(result.success ? 0 : 1);
+}
+/** Write structured failure result to stdout and exit 1. */
+export function outputFailure(result) {
+    outputJSON({ success: false, ...result });
+}
+/** Write a normalized contract failure result to stderr and exit 1. */
+export function outputContractFailure(result) {
+    outputFailure(result);
 }
 /** Write error to stderr and exit 1. */
 export function outputError(error) {
-    outputJSON({ success: false, error });
+    outputFailure({ error });
 }
 /** Write a progress/info message to stderr. */
 export function info(message) {

package/dist/playwright-runtime.d.ts

@@ -0,0 +1,35 @@
+import { type Browser, type Page } from 'playwright-core';
+import type { BrowseSession } from './session.js';
+export declare function connectPlaywright(cdpUrl: string): Promise<Browser>;
+export declare function disconnectPlaywright(browser: Browser): void;
+export declare function listPages(browser: Browser): Page[];
+type LaunchPageMetadata = {
+    page: Page | null;
+    url: string;
+    title: string;
+    targetId?: string;
+};
+export declare function readLaunchPageMetadata(browser: Browser, options?: {
+    requestedUrl?: string;
+    fallbackUrl?: string;
+    fallbackTitle?: string;
+    timeoutMs?: number;
+}): Promise<LaunchPageMetadata>;
+export declare function syncLaunchPage(session: BrowseSession, browser: Browser, options?: {
+    requestedUrl?: string;
+    fallbackUrl?: string;
+    fallbackTitle?: string;
+    timeoutMs?: number;
+}): Promise<{
+    url: string;
+    title: string;
+    targetId?: string;
+}>;
+export declare function resolvePageByRef(browser: Browser, session: BrowseSession, pageRef: string): Promise<Page>;
+export declare function syncSessionPage(session: BrowseSession, pageRef: string, page: Page): Promise<{
+    url: string;
+    title: string;
+    targetId?: string;
+}>;
+export {};
+//# sourceMappingURL=playwright-runtime.d.ts.map

package/dist/playwright-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-runtime.d.ts","sourceRoot":"","sources":["../src/playwright-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAGlD,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAExE;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAO3D;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,EAAE,CAElD;AAmCD,KAAK,kBAAkB,GAAG;IACxB,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAmFF,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACf,GACL,OAAO,CAAC,kBAAkB,CAAC,CAgD7B;AAED,wBAAsB,cAAc,CAClC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACf,GACL,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAgC5D;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CA8Cf;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,IAAI,GACT,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAW5D"}