@mercuryo-ai/agentbrowse 0.2.60 → 0.2.63

package/dist/sticky-owner-host-entry.js

@@ -0,0 +1,97 @@
+import { existsSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { connectPlaywright, disconnectPlaywright } from './playwright-runtime.js';
+function readArgValue(argv, name) {
+    const index = argv.indexOf(name);
+    const value = index >= 0 ? argv[index + 1] : undefined;
+    if (!value || value.startsWith('--')) {
+        throw new Error(`Missing ${name} argument.`);
+    }
+    return value;
+}
+function parseArgs(argv = process.argv) {
+    const ttlRaw = readArgValue(argv, '--ttl-ms');
+    const ttlMs = Number(ttlRaw);
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+        throw new Error('Invalid --ttl-ms argument.');
+    }
+    return {
+        manifestPath: readArgValue(argv, '--manifest'),
+        cdpUrl: readArgValue(argv, '--cdp-url'),
+        hostId: readArgValue(argv, '--host-id'),
+        browserSessionId: readArgValue(argv, '--browser-session-id'),
+        touchPath: readArgValue(argv, '--touch-path'),
+        ttlMs,
+    };
+}
+function touchLeaseFile(path) {
+    writeFileSync(path, new Date().toISOString());
+}
+function readLeaseAgeMs(path) {
+    if (!existsSync(path)) {
+        return Number.POSITIVE_INFINITY;
+    }
+    try {
+        return Math.max(0, Date.now() - statSync(path).mtimeMs);
+    }
+    catch {
+        return Number.POSITIVE_INFINITY;
+    }
+}
+async function main() {
+    const args = parseArgs();
+    const browser = await connectPlaywright(args.cdpUrl);
+    const binding = await browser.bind(args.hostId, {
+        metadata: {
+            hostId: args.hostId,
+            browserSessionId: args.browserSessionId,
+            pid: process.pid,
+            startedAt: new Date().toISOString(),
+        },
+    });
+    touchLeaseFile(args.touchPath);
+    writeFileSync(args.manifestPath, JSON.stringify({
+        endpoint: binding.endpoint,
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+    }, null, 2));
+    let shuttingDown = false;
+    let ttlInterval = null;
+    const shutdown = async () => {
+        if (shuttingDown) {
+            return;
+        }
+        shuttingDown = true;
+        if (ttlInterval) {
+            clearInterval(ttlInterval);
+            ttlInterval = null;
+        }
+        await browser.unbind().catch(() => undefined);
+        await disconnectPlaywright(browser).catch(() => undefined);
+        rmSync(args.touchPath, { force: true });
+        process.exit(0);
+    };
+    const reapExpiredOwner = () => {
+        if (readLeaseAgeMs(args.touchPath) >= args.ttlMs) {
+            void shutdown();
+        }
+    };
+    browser.on('disconnected', () => {
+        void shutdown();
+    });
+    process.on('SIGINT', () => {
+        void shutdown();
+    });
+    process.on('SIGTERM', () => {
+        void shutdown();
+    });
+    const ttlCheckMs = Math.max(5_000, Math.min(Math.floor(args.ttlMs / 6), 60_000));
+    ttlInterval = setInterval(reapExpiredOwner, ttlCheckMs);
+    ttlInterval.unref?.();
+    reapExpiredOwner();
+    await new Promise(() => { });
+}
+void main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(message);
+    process.exit(1);
+});

package/dist/sticky-owner.d.ts

@@ -0,0 +1,15 @@
+import { type Browser } from 'playwright-core';
+import { type BrowserSessionState } from './browser-session-state.js';
+export type RestoreBrowserSessionOwnerResult = {
+    success: true;
+    session: BrowserSessionState;
+    restored: boolean;
+} | {
+    success: false;
+    reason: 'sticky_owner_unrecoverable';
+};
+export declare function initializeBrowserSessionOwner(session: BrowserSessionState): Promise<BrowserSessionState>;
+export declare function terminateBrowserSessionOwner(session: BrowserSessionState | null): Promise<void>;
+export declare function restoreBrowserSessionOwner(session: BrowserSessionState): Promise<RestoreBrowserSessionOwnerResult>;
+export declare function withStickyOwnerBrowser<TResult>(session: BrowserSessionState, operation: (browser: Browser) => Promise<TResult>): Promise<TResult>;
+//# sourceMappingURL=sticky-owner.d.ts.map

package/dist/sticky-owner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sticky-owner.d.ts","sourceRoot":"","sources":["../src/sticky-owner.ts"],"names":[],"mappings":"AAMA,OAAO,EAAY,KAAK,OAAO,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAIL,KAAK,mBAAmB,EAGzB,MAAM,4BAA4B,CAAC;AAWpC,MAAM,MAAM,gCAAgC,GACxC;IACE,OAAO,EAAE,IAAI,CAAC;IACd,OAAO,EAAE,mBAAmB,CAAC;IAC7B,QAAQ,EAAE,OAAO,CAAC;CACnB,GACD;IACE,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE,4BAA4B,CAAC;CACtC,CAAC;AAyVN,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,mBAAmB,CAAC,CAU9B;AAED,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,mBAAmB,GAAG,IAAI,GAClC,OAAO,CAAC,IAAI,CAAC,CA2Bf;AAED,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,gCAAgC,CAAC,CAiG3C;AAED,wBAAsB,sBAAsB,CAAC,OAAO,EAClD,OAAO,EAAE,mBAAmB,EAC5B,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAChD,OAAO,CAAC,OAAO,CAAC,CA0BlB"}

package/dist/sticky-owner.js

@@ -0,0 +1,431 @@
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { chromium } from 'playwright-core';
+import { buildStickyOwnerMetadata, isSessionAlive, resolveBrowserSessionId, } from './browser-session-state.js';
+import { connectPlaywright, disconnectPlaywright } from './playwright-runtime.js';
+const HOST_READY_TIMEOUT_MS = 5_000;
+const HOST_READY_POLL_MS = 50;
+const HOST_CONNECT_TIMEOUT_MS = 3_000;
+const HOST_STOP_TIMEOUT_MS = 1_000;
+const DEFAULT_STICKY_OWNER_TTL_MS = 30 * 60 * 1_000;
+const STICKY_OWNER_HEARTBEAT_FLOOR_MS = 5_000;
+const STICKY_OWNER_HEARTBEAT_CEILING_MS = 60_000;
+const inProcessOwners = new WeakMap();
+function resolveStickyOwnerBootstrapMode() {
+    const explicit = process.env.AGENTBROWSE_STICKY_OWNER_MODE?.trim().toLowerCase();
+    if (explicit === 'detached_process') {
+        return 'detached_process';
+    }
+    if (explicit === 'in_process') {
+        return 'in_process';
+    }
+    if (process.env.VITEST) {
+        return 'in_process';
+    }
+    return 'detached_process';
+}
+function createHostId() {
+    return `owner_${randomUUID().replace(/-/g, '')}`;
+}
+function resolveStickyOwnerTtlMs() {
+    const raw = process.env.AGENTBROWSE_STICKY_OWNER_TTL_MS?.trim();
+    if (!raw) {
+        return DEFAULT_STICKY_OWNER_TTL_MS;
+    }
+    const ttlMs = Number(raw);
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+        return DEFAULT_STICKY_OWNER_TTL_MS;
+    }
+    return ttlMs;
+}
+function getStickyOwnerTouchPath(hostId) {
+    return join(tmpdir(), `agentbrowse-sticky-owner-${hostId}.touch`);
+}
+function buildInProcessStickyOwner(session, options = {}) {
+    return buildStickyOwnerMetadata({
+        hostId: options.hostId ?? session.stickyOwner?.hostId ?? createHostId(),
+        state: options.state ?? 'active',
+        startedAt: options.startedAt ?? session.stickyOwner?.startedAt ?? new Date().toISOString(),
+        browserSessionId: resolveBrowserSessionId(session),
+        transport: {
+            type: 'in_process',
+        },
+    });
+}
+function readStickyOwnerLastUsedMs(stickyOwner) {
+    if (stickyOwner.touchPath) {
+        try {
+            if (existsSync(stickyOwner.touchPath)) {
+                return statSync(stickyOwner.touchPath).mtimeMs;
+            }
+        }
+        catch {
+            // Fall through to metadata timestamps.
+        }
+    }
+    const candidate = stickyOwner.lastUsedAt ?? stickyOwner.startedAt;
+    const parsed = Date.parse(candidate);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+function isStickyOwnerExpired(stickyOwner) {
+    if (stickyOwner.transport.type !== 'playwright_bind') {
+        return false;
+    }
+    const ttlMs = stickyOwner.ttlMs ?? DEFAULT_STICKY_OWNER_TTL_MS;
+    return Date.now() - readStickyOwnerLastUsedMs(stickyOwner) >= ttlMs;
+}
+function removeStickyOwnerTouchFile(stickyOwner) {
+    if (!stickyOwner?.touchPath) {
+        return;
+    }
+    rmSync(stickyOwner.touchPath, { force: true });
+}
+function touchStickyOwnerLease(session) {
+    if (!session.stickyOwner || session.stickyOwner.transport.type !== 'playwright_bind') {
+        return;
+    }
+    const touchedAt = new Date().toISOString();
+    if (session.stickyOwner.touchPath) {
+        writeFileSync(session.stickyOwner.touchPath, touchedAt);
+    }
+    session.stickyOwner = {
+        ...session.stickyOwner,
+        lastUsedAt: touchedAt,
+    };
+}
+function startStickyOwnerLeaseHeartbeat(session) {
+    if (!session.stickyOwner || session.stickyOwner.transport.type !== 'playwright_bind') {
+        return () => undefined;
+    }
+    const ttlMs = session.stickyOwner.ttlMs ?? DEFAULT_STICKY_OWNER_TTL_MS;
+    const heartbeatMs = Math.max(STICKY_OWNER_HEARTBEAT_FLOOR_MS, Math.min(Math.floor(ttlMs / 3), STICKY_OWNER_HEARTBEAT_CEILING_MS));
+    const timer = setInterval(() => {
+        try {
+            touchStickyOwnerLease(session);
+        }
+        catch {
+            // Best-effort heartbeat; restore path will handle stale or dead owners later.
+        }
+    }, heartbeatMs);
+    timer.unref?.();
+    return () => clearInterval(timer);
+}
+function markStickyOwnerState(session, state) {
+    if (!session.stickyOwner) {
+        return;
+    }
+    session.stickyOwner = {
+        ...session.stickyOwner,
+        state,
+    };
+}
+function isProcessAlive(pid) {
+    if (typeof pid !== 'number' || !Number.isFinite(pid) || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitForProcessExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!isProcessAlive(pid)) {
+            return true;
+        }
+        await sleep(50);
+    }
+    return !isProcessAlive(pid);
+}
+async function canConnectToStickyOwnerEndpoint(endpoint) {
+    let browser = null;
+    try {
+        browser = await chromium.connect(endpoint, {
+            timeout: HOST_CONNECT_TIMEOUT_MS,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (browser) {
+            await disconnectPlaywright(browser);
+        }
+    }
+}
+function getStickyOwnerHostEntryPath() {
+    const currentPath = fileURLToPath(import.meta.url);
+    const suffix = currentPath.endsWith('.ts') ? '.ts' : '.js';
+    return fileURLToPath(new URL(`./sticky-owner-host-entry${suffix}`, import.meta.url));
+}
+function getStickyOwnerHostSpawnArgs(entryPath, manifestPath, cdpUrl, hostId, browserSessionId, touchPath, ttlMs) {
+    const args = [
+        entryPath,
+        '--manifest',
+        manifestPath,
+        '--cdp-url',
+        cdpUrl,
+        '--host-id',
+        hostId,
+        '--browser-session-id',
+        browserSessionId,
+        '--touch-path',
+        touchPath,
+        '--ttl-ms',
+        String(ttlMs),
+    ];
+    if (entryPath.endsWith('.ts')) {
+        return ['--import', 'tsx', ...args];
+    }
+    return args;
+}
+async function waitForStickyOwnerManifest(manifestPath) {
+    const deadline = Date.now() + HOST_READY_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if (existsSync(manifestPath)) {
+            const payload = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+            if (typeof payload.endpoint === 'string' &&
+                payload.endpoint.trim().length > 0 &&
+                typeof payload.pid === 'number' &&
+                Number.isFinite(payload.pid) &&
+                payload.pid > 0 &&
+                typeof payload.startedAt === 'string' &&
+                payload.startedAt.trim().length > 0) {
+                rmSync(manifestPath, { force: true });
+                return {
+                    endpoint: payload.endpoint,
+                    pid: payload.pid,
+                    startedAt: payload.startedAt,
+                };
+            }
+        }
+        await sleep(HOST_READY_POLL_MS);
+    }
+    throw new Error('sticky_owner_bootstrap_timeout');
+}
+async function bootstrapDetachedStickyOwner(session) {
+    const hostId = session.stickyOwner?.hostId ?? createHostId();
+    const browserSessionId = resolveBrowserSessionId(session);
+    const ttlMs = session.stickyOwner?.ttlMs ?? resolveStickyOwnerTtlMs();
+    const manifestPath = join(tmpdir(), `agentbrowse-sticky-owner-${hostId}.json`);
+    const touchPath = session.stickyOwner?.touchPath ?? getStickyOwnerTouchPath(hostId);
+    const touchedAt = new Date().toISOString();
+    writeFileSync(touchPath, touchedAt);
+    const entryPath = getStickyOwnerHostEntryPath();
+    const child = spawn(process.execPath, getStickyOwnerHostSpawnArgs(entryPath, manifestPath, session.cdpUrl, hostId, browserSessionId, touchPath, ttlMs), {
+        detached: true,
+        stdio: 'ignore',
+    });
+    child.unref();
+    try {
+        const ready = await waitForStickyOwnerManifest(manifestPath);
+        return buildStickyOwnerMetadata({
+            hostId,
+            state: 'active',
+            startedAt: ready.startedAt,
+            lastUsedAt: touchedAt,
+            ttlMs,
+            touchPath,
+            browserSessionId,
+            pid: ready.pid,
+            transport: {
+                type: 'playwright_bind',
+                endpoint: ready.endpoint,
+                mode: 'pipe',
+            },
+        });
+    }
+    catch (error) {
+        if (isProcessAlive(child.pid)) {
+            process.kill(child.pid, 'SIGTERM');
+            await waitForProcessExit(child.pid, HOST_STOP_TIMEOUT_MS).catch(() => undefined);
+        }
+        rmSync(manifestPath, { force: true });
+        rmSync(touchPath, { force: true });
+        throw error;
+    }
+}
+async function ensureInProcessOwner(session) {
+    const existing = inProcessOwners.get(session);
+    if (existing) {
+        return existing;
+    }
+    const browser = await connectPlaywright(session.cdpUrl);
+    const owner = {
+        browser,
+        hostId: session.stickyOwner?.hostId ?? createHostId(),
+        startedAt: session.stickyOwner?.startedAt ?? new Date().toISOString(),
+    };
+    inProcessOwners.set(session, owner);
+    session.stickyOwner = buildInProcessStickyOwner(session, {
+        hostId: owner.hostId,
+        startedAt: owner.startedAt,
+    });
+    return owner;
+}
+export async function initializeBrowserSessionOwner(session) {
+    if (resolveStickyOwnerBootstrapMode() === 'in_process') {
+        session.stickyOwner = buildInProcessStickyOwner(session, {
+            state: 'active',
+        });
+        return session;
+    }
+    session.stickyOwner = await bootstrapDetachedStickyOwner(session);
+    return session;
+}
+export async function terminateBrowserSessionOwner(session) {
+    if (!session?.stickyOwner) {
+        return;
+    }
+    if (session.stickyOwner.transport.type === 'in_process') {
+        const owner = inProcessOwners.get(session);
+        inProcessOwners.delete(session);
+        if (owner) {
+            await disconnectPlaywright(owner.browser);
+        }
+        markStickyOwnerState(session, 'dead');
+        return;
+    }
+    const ownerPid = session.stickyOwner.pid;
+    if (isProcessAlive(ownerPid)) {
+        process.kill(ownerPid, 'SIGTERM');
+        const exited = await waitForProcessExit(ownerPid, HOST_STOP_TIMEOUT_MS);
+        if (!exited && isProcessAlive(ownerPid)) {
+            process.kill(ownerPid, 'SIGKILL');
+            await waitForProcessExit(ownerPid, HOST_STOP_TIMEOUT_MS).catch(() => undefined);
+        }
+    }
+    removeStickyOwnerTouchFile(session.stickyOwner);
+    markStickyOwnerState(session, 'dead');
+}
+export async function restoreBrowserSessionOwner(session) {
+    const stickyOwner = session.stickyOwner;
+    if (!stickyOwner) {
+        if (resolveStickyOwnerBootstrapMode() === 'in_process') {
+            try {
+                await ensureInProcessOwner(session);
+                return {
+                    success: true,
+                    session,
+                    restored: true,
+                };
+            }
+            catch {
+                return {
+                    success: false,
+                    reason: 'sticky_owner_unrecoverable',
+                };
+            }
+        }
+        if (!(await isSessionAlive(session))) {
+            return {
+                success: false,
+                reason: 'sticky_owner_unrecoverable',
+            };
+        }
+        try {
+            session.stickyOwner = await bootstrapDetachedStickyOwner(session);
+            return {
+                success: true,
+                session,
+                restored: true,
+            };
+        }
+        catch {
+            return {
+                success: false,
+                reason: 'sticky_owner_unrecoverable',
+            };
+        }
+    }
+    if (stickyOwner.transport.type === 'in_process') {
+        try {
+            await ensureInProcessOwner(session);
+            return {
+                success: true,
+                session,
+                restored: false,
+            };
+        }
+        catch {
+            return {
+                success: false,
+                reason: 'sticky_owner_unrecoverable',
+            };
+        }
+    }
+    if (stickyOwner.state === 'active' &&
+        !isStickyOwnerExpired(stickyOwner) &&
+        isProcessAlive(stickyOwner.pid) &&
+        (await canConnectToStickyOwnerEndpoint(stickyOwner.transport.endpoint))) {
+        return {
+            success: true,
+            session,
+            restored: false,
+        };
+    }
+    await terminateBrowserSessionOwner(session);
+    if (!(await isSessionAlive(session))) {
+        return {
+            success: false,
+            reason: 'sticky_owner_unrecoverable',
+        };
+    }
+    try {
+        markStickyOwnerState(session, 'recovering');
+        session.stickyOwner = await bootstrapDetachedStickyOwner(session);
+        return {
+            success: true,
+            session,
+            restored: true,
+        };
+    }
+    catch {
+        session.stickyOwner = {
+            ...stickyOwner,
+            state: 'dead',
+        };
+        return {
+            success: false,
+            reason: 'sticky_owner_unrecoverable',
+        };
+    }
+}
+export async function withStickyOwnerBrowser(session, operation) {
+    const stickyOwner = session.stickyOwner;
+    if (!stickyOwner || stickyOwner.transport.type === 'playwright_bind') {
+        const restored = await restoreBrowserSessionOwner(session);
+        if (!restored.success || !session.stickyOwner) {
+            throw new Error('sticky_owner_unrecoverable');
+        }
+    }
+    if (session.stickyOwner?.transport.type === 'playwright_bind') {
+        touchStickyOwnerLease(session);
+        const browser = await chromium.connect(session.stickyOwner.transport.endpoint, {
+            timeout: HOST_CONNECT_TIMEOUT_MS,
+        });
+        const stopHeartbeat = startStickyOwnerLeaseHeartbeat(session);
+        try {
+            return await operation(browser);
+        }
+        finally {
+            stopHeartbeat();
+            touchStickyOwnerLease(session);
+            await disconnectPlaywright(browser);
+        }
+    }
+    const owner = await ensureInProcessOwner(session);
+    return operation(owner.browser);
+}

package/dist/testing.d.ts

@@ -1,5 +1,6 @@
 /**
  * Stable testing helpers for packages that wrap AgentBrowse.
  */
+export { createFixtureGroupStore, createFixtureMatchStore, createFixtureResolver, fixtureResolvedArtifact, fixtureResolvedValue, } from './match-resolve-fill.test-support.js';
 export { installFetchBackedTestAssistiveRuntime, uninstallTestAssistiveRuntime, } from './assistive-runtime.test-support.js';
 //# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,sCAAsC,EACtC,6BAA6B,GAC9B,MAAM,qCAAqC,CAAC"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EACL,sCAAsC,EACtC,6BAA6B,GAC9B,MAAM,qCAAqC,CAAC"}

package/dist/testing.js

@@ -1,4 +1,5 @@
 /**
  * Stable testing helpers for packages that wrap AgentBrowse.
  */
+export { createFixtureGroupStore, createFixtureMatchStore, createFixtureResolver, fixtureResolvedArtifact, fixtureResolvedValue, } from './match-resolve-fill.test-support.js';
 export { installFetchBackedTestAssistiveRuntime, uninstallTestAssistiveRuntime, } from './assistive-runtime.test-support.js';

package/docs/README.md

@@ -9,30 +9,47 @@ Public guides for `@mercuryo-ai/agentbrowse`.
    turns the Quick Start into a working model for every main API.
 3. [api-reference.md](./api-reference.md) — lookup for types, result
    shapes, and error codes (keep open while coding).
-4. Only-when-needed: [configuration.md](./configuration.md),
+4. [match-resolve-fill.md](./match-resolve-fill.md) when your runtime
+   needs to decide which caller-supplied value belongs in which
+   observed field.
+5. Only-when-needed: [configuration.md](./configuration.md),
    [assistive-runtime.md](./assistive-runtime.md),
    [protected-fill.md](./protected-fill.md).
-5. Before shipping: [integration-checklist.md](./integration-checklist.md)
+6. Before shipping: [integration-checklist.md](./integration-checklist.md)
    and [troubleshooting.md](./troubleshooting.md).
 
 Full list:
 
 - [getting-started.md](./getting-started.md)
   The first guide to read after the package README. It explains the normal
-  session flow and what each main API is for.
+  session flow and what each main API is for, including the
+  `match` / `resolve` / `fill` primitives.
 - [api-reference.md](./api-reference.md)
-  Compact reference for the public API, result shapes, observe payloads, and
-  extraction schema input.
+  Compact reference for the public API, result shapes, observe payloads,
+  match/resolve/fill types, and extraction schema input.
+
+## Match / resolve / fill
+
+- [match-resolve-fill.md](./match-resolve-fill.md)
+  How the three primitives decide which value fits which observed field,
+  how to wire a resolver adapter, and the design rules (no raw values in
+  public results, stable resolved refs, adapter boundary).
+- [protected-fill.md](./protected-fill.md)
+  How the low-level `fillProtectedForm(...)` path works and when to
+  prefer it over the `fill(session, form, plan, { resolver })` route.
+- [testing.md](./testing.md)
+  Stable fixture builders for match/resolve/fill unit tests, plus the
+  fetch-backed assistive runtime helper for packages that wrap
+  AgentBrowse.
+
+## Runtime and integration
+
 - [configuration.md](./configuration.md)
   Persistence, proxy, diagnostics, and client configuration.
 - [assistive-runtime.md](./assistive-runtime.md)
-  How to connect an OpenAI-compatible LLM backend for extraction and better
-  goal-based page understanding.
-- [protected-fill.md](./protected-fill.md)
-  How protected fill works and when to use it instead of a normal fill action.
+  How to connect an OpenAI-compatible LLM backend for extraction and
+  better goal-based page understanding.
 - [integration-checklist.md](./integration-checklist.md)
   Checklist for packages and services that integrate AgentBrowse.
-- [testing.md](./testing.md)
-  Stable testing helpers for packages that wrap AgentBrowse.
 - [troubleshooting.md](./troubleshooting.md)
   Common launch, observe, extract, and anti-bot issues.