@gate-forge/pack-playwright 0.1.0

package/dist/witness/adapter-registry.js

@@ -0,0 +1,158 @@
+/**
+ * Adapter loading + registry (pin #8, plan §5.4).
+ *
+ * Reviewed evidence adapters load from `.gateforge/adapters/<name>.mjs`
+ * at WITNESS START (engine-side — the test process never imports them).
+ * Default export contract:
+ *
+ * ```js
+ * export default {
+ *   read: async (ctx, id) => body | null,   // GET-only; ctx.get(path) is the transport
+ *   normalize: (body) => ({ entityId, fields }), // stamped from the RESPONSE, never caller args
+ *   deletion: 'hard' | 'archive',
+ *   environmentFingerprint: '…',            // must match the target's marker header
+ *   baseUrl: 'http://…',                    // optional override of the witness adapter base
+ *   probeServer: async (ctx, subject) => ({ found, fields }), // optional: the
+ *                          // SERVER-WITNESSED persistence channel probe — executed
+ *                          // ONLY in this trusted witness process
+ * };
+ * ```
+ *
+ * The registry loads fail-closed: a missing/invalid module, a missing
+ * `read`/`normalize`/`deletion`/`environmentFingerprint`, an unknown
+ * deletion value, or a duplicate name aborts witness startup with an
+ * actionable diagnostic naming the file. The registry is frozen after
+ * load — there is no registration path a test could reach (invariant 6,
+ * GF-11 "registration path does not exist").
+ */
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/**
+ * Loads every `.mjs` adapter in `dir` into a frozen registry.
+ *
+ * Args:
+ *   dir: the configured adapters directory (absolute).
+ *
+ * Returns:
+ *   Map<string, EvidenceAdapter>: keyed by the file basename sans `.mjs`.
+ *
+ * Throws:
+ *   AdapterRegistryError: fail-closed load problems — unreadable dir,
+ *     unimportable module, or a module missing any contract member.
+ */
+export async function loadAdapters(dir) {
+    const registry = new Map();
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            // No adapters directory at all: the registry stays empty; the
+            // witness then answers 400 for every persistence request (a run
+            // with persistence obligations and no adapters is misconfigured).
+            return registry;
+        }
+        throw new AdapterRegistryError(`cannot read adapters directory '${dir}': ${error.message}`);
+    }
+    for (const entry of entries.sort()) {
+        if (!entry.endsWith('.mjs'))
+            continue;
+        const name = entry.slice(0, -'.mjs'.length);
+        if (registry.has(name)) {
+            throw new AdapterRegistryError(`duplicate adapter '${name}' (multiple '${entry}' files is a config error)`);
+        }
+        const module = await importAdapter(dir, entry, name);
+        const adapter = validateAdapter(module, name);
+        registry.set(name, adapter);
+    }
+    return Object.freeze(registry);
+}
+/** Imports one adapter module; import errors carry an actionable message. */
+async function importAdapter(dir, entry, name) {
+    try {
+        const loaded = (await import(pathToFileURL(join(dir, entry)).href));
+        return loaded.default;
+    }
+    catch (error) {
+        throw new AdapterRegistryError(`adapter '${name}' (${join(dir, entry)}) could not be imported: ` +
+            `${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Validates one adapter module against the pin-#8 contract.
+ *
+ * Args:
+ *   module: the default export of the adapter file.
+ *   name: adapter name, used in diagnostics.
+ *
+ * Returns:
+ *   EvidenceAdapter: the validated adapter.
+ *
+ * Throws:
+ *   AdapterRegistryError: when any required member is missing or shaped
+ *   wrong. Optional `baseUrl` (a string) overrides the witness's
+ *   configured adapter base for this adapter.
+ */
+export function validateAdapter(module, name) {
+    if (typeof module !== 'object' || module === null) {
+        throw new AdapterRegistryError(`adapter '${name}' must default-export an object {read, normalize, deletion, environmentFingerprint}`);
+    }
+    const adapter = module;
+    const problems = [];
+    if (typeof adapter['read'] !== 'function')
+        problems.push('read must be an async function (ctx, id)');
+    if (typeof adapter['normalize'] !== 'function')
+        problems.push('normalize must be a function (body) => {entityId, fields}');
+    if (adapter['deletion'] !== 'hard' && adapter['deletion'] !== 'archive') {
+        problems.push("deletion must be 'hard' or 'archive'");
+    }
+    if (typeof adapter['environmentFingerprint'] !== 'string') {
+        problems.push('environmentFingerprint must be a string');
+    }
+    if (adapter['baseUrl'] !== undefined &&
+        (typeof adapter['baseUrl'] !== 'string' || adapter['baseUrl'].length === 0)) {
+        problems.push('baseUrl must be a non-empty string when present');
+    }
+    if (adapter['list'] !== undefined && typeof adapter['list'] !== 'function') {
+        problems.push('list must be a function (ctx) => entity[] when present');
+    }
+    // Server probe (server-witnessed persistence channel): OPTIONAL — an
+    // adapter without it simply cannot serve the channel and every server
+    // intent for the resource resolves to a typed
+    // SERVER_PROBE_UNAVAILABLE failure. A PRESENT but malformed export is
+    // a contract violation caught here at load, fail-closed, not at
+    // intent time.
+    if (adapter['probeServer'] !== undefined && typeof adapter['probeServer'] !== 'function') {
+        problems.push('probeServer must be an async function (ctx, subject) => {found, fields} when present');
+    }
+    if (problems.length > 0) {
+        throw new AdapterRegistryError(`adapter '${name}' violates the adapter contract: ${problems.join('; ')}`);
+    }
+    return {
+        read: adapter['read'],
+        normalize: adapter['normalize'],
+        deletion: adapter['deletion'],
+        environmentFingerprint: adapter['environmentFingerprint'],
+        baseUrl: adapter['baseUrl'],
+        ...(adapter['list'] !== undefined
+            ? { list: adapter['list'] }
+            : {}),
+        ...(adapter['probeServer'] !== undefined
+            ? { probeServer: adapter['probeServer'] }
+            : {}),
+    };
+}
+/** Fail-closed adapter-loading error (witness startup aborts). */
+export class AdapterRegistryError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AdapterRegistryError';
+    }
+}
+/** The transport the witness hands to adapter `read` calls (GET-only). */
+export function makeAdapterContext(baseUrl, resourceId, get, headers) {
+    return Object.freeze({ baseUrl, resourceId, get, ...(headers ? { headers } : {}) });
+}
+//# sourceMappingURL=adapter-registry.js.map

package/dist/witness/adapter-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-registry.js","sourceRoot":"","sources":["../../src/witness/adapter-registry.ts"],"names":[],"mappings":"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"}

package/dist/witness/bin.d.ts

@@ -0,0 +1,21 @@
+import type { WitnessHandle } from './types.js';
+/** One-line usage (the header comment above is the long form). */
+export declare const WITNESS_BIN_USAGE: string;
+/**
+ * Reads env + argv and starts the witness.
+ *
+ * Args:
+ *   argv: CLI flags (see the module header; `--help` prints usage and
+ *     returns a never-started handle).
+ *   env: process environment.
+ *
+ * Returns:
+ *   WitnessHandle once listening (or a handle with an empty `url` for
+ *   `--help`; the wrapper skips its URL banner in that case).
+ *
+ * Throws:
+ *   WitnessStartupError / AttestationError / AdapterRegistryError:
+ *     fail-closed startup problems (exit 2 via the wrapper).
+ */
+export declare function main(argv: readonly string[], env: NodeJS.ProcessEnv): Promise<WitnessHandle>;
+//# sourceMappingURL=bin.d.ts.map

package/dist/witness/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../../src/witness/bin.ts"],"names":[],"mappings":"AA0DA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,QAKK,CAAC;AAkFpC;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,IAAI,CACxB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,OAAO,CAAC,aAAa,CAAC,CAiCxB"}

package/dist/witness/bin.js

@@ -0,0 +1,172 @@
+/**
+ * Witness process entry (`gateforge-witness`): derives configuration
+ * from CLI flags and the environment and starts the loopback witness
+ * service.
+ *
+ * Usage (every flag has an env fallback; the flag wins when both are
+ * given):
+ *
+ *   gateforge-witness [--help]
+ *     [--proxy-target <url>]       start the observation proxy against
+ *                                  this loopback base URL (ADR 0004 D7)
+ *     [--mount-path <prefix>]      browser-facing mount prefix the proxy
+ *                                  strips before forwarding AND recording
+ *                                  (e.g. /api; requires --proxy-target)
+ *     [--state-dir <dir>]          manifest append at shutdown
+ *     [--classifications <path>]   classifications YAML input
+ *     [--adapters-dir <dir>]       reviewed adapters (default .gateforge/adapters)
+ *     [--target-base-url <url>]    attestation subject (GF-10, loopback)
+ *     [--target-fingerprint <m>]   expected marker (GF-13)
+ *     [--adapter-base-url <url>]   default adapter read base
+ *
+ * Env surface:
+ *   GATEFORGE_RUN_ID, GATEFORGE_RUN_TOKEN        (required; CLI contract)
+ *   GATEFORGE_PROXY_TARGET, GATEFORGE_MOUNT_PATH (observation proxy)
+ *   GATEFORGE_STATE_DIR                          (manifest append at shutdown)
+ *   GATEFORGE_ADAPTERS_DIR                       (default .gateforge/adapters)
+ *   GATEFORGE_CLASSIFICATIONS                    (classifications YAML path)
+ *   GATEFORGE_TARGET_BASE_URL                    (attestation subject, GF-10)
+ *   GATEFORGE_TARGET_FINGERPRINT                 (expected marker, GF-13)
+ *   GATEFORGE_ADAPTER_BASE_URL                   (default adapter read base)
+ *   GATEFORGE_WITNESS_VERIFIER_KEY               (attestation verifier key)
+ *
+ * SECRETS NEVER TRAVEL ON ARGV (a process's cmdline is world-readable
+ * via /proc — the same rule `gateforge test-gates` applies): the run
+ * id/token are env-only (set by 'gateforge test-gates'), and the
+ * verifier key is read from GATEFORGE_WITNESS_VERIFIER_KEY only. With a
+ * verifier key the witness serves the MAC-attested ledger surface;
+ * without one it stays unauthenticated and downstream evaluation fails
+ * closed.
+ *
+ * The wrapper prints `GATEFORGE_WITNESS_URL=<url>` once listening — and
+ * `GATEFORGE_WITNESS_PROXY_URL=<url>` when an observation proxy is
+ * active; the process serves until SIGTERM/SIGINT.
+ */
+import { startWitness, WitnessStartupError } from './server.js';
+import { ENV_ADAPTER_BASE_URL, ENV_ADAPTERS_DIR, ENV_CLASSIFICATIONS, ENV_MOUNT_PATH, ENV_PROXY_TARGET, ENV_RUN_ID, ENV_RUN_TOKEN, ENV_STATE_DIR, ENV_TARGET_BASE_URL, ENV_TARGET_FINGERPRINT, ENV_WITNESS_VERIFIER_KEY, } from '../constants.js';
+/** One-line usage (the header comment above is the long form). */
+export const WITNESS_BIN_USAGE = 'usage: gateforge-witness [--proxy-target <url>] [--mount-path <prefix>] ' +
+    '[--state-dir <dir>] [--classifications <path>] [--adapters-dir <dir>] ' +
+    '[--target-base-url <url>] [--target-fingerprint <marker>] [--adapter-base-url <url>] ' +
+    '(run id/token via GATEFORGE_RUN_ID/GATEFORGE_RUN_TOKEN; verifier key via ' +
+    'GATEFORGE_WITNESS_VERIFIER_KEY)';
+/** Flags this bin accepts (values; `--help` is handled separately). */
+const VALUE_FLAGS = new Set([
+    'proxy-target',
+    'mount-path',
+    'state-dir',
+    'classifications',
+    'adapters-dir',
+    'target-base-url',
+    'target-fingerprint',
+    'adapter-base-url',
+    'adapter-read-authorization',
+]);
+/**
+ * Parses the bin argv (`--flag value` and `--flag=value` shapes).
+ * Unknown flags and missing values fail closed with the usage line —
+ * a mis-wired harness must never silently start a half-configured
+ * witness.
+ *
+ * Args:
+ *   argv: arguments after node/script.
+ *
+ * Returns:
+ *   WitnessBinFlags: parsed flag values.
+ *
+ * Throws:
+ *   WitnessStartupError: on any malformed argv.
+ */
+function parseFlags(argv) {
+    const values = new Map();
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index] ?? '';
+        if (!token.startsWith('--')) {
+            throw new WitnessStartupError(`unexpected argument '${token}'\n${WITNESS_BIN_USAGE}`);
+        }
+        const body = token.slice(2);
+        const eq = body.indexOf('=');
+        const name = eq >= 0 ? body.slice(0, eq) : body;
+        if (name.length === 0) {
+            throw new WitnessStartupError(`invalid flag '${token}'\n${WITNESS_BIN_USAGE}`);
+        }
+        if (name === 'help') {
+            continue; // handled by the caller before parsing matters
+        }
+        if (!VALUE_FLAGS.has(name)) {
+            throw new WitnessStartupError(`unknown flag '--${name}'\n${WITNESS_BIN_USAGE}`);
+        }
+        let value = eq >= 0 ? body.slice(eq + 1) : undefined;
+        if (value === undefined) {
+            const next = argv[index + 1];
+            if (next === undefined || next.startsWith('--')) {
+                throw new WitnessStartupError(`flag '--${name}' requires a value\n${WITNESS_BIN_USAGE}`);
+            }
+            value = next;
+            index += 1;
+        }
+        if (values.has(name)) {
+            throw new WitnessStartupError(`flag '--${name}' may only be given once\n${WITNESS_BIN_USAGE}`);
+        }
+        values.set(name, value);
+    }
+    return { values };
+}
+/** Flag value or its env fallback (undefined when neither is set). */
+function flagOrEnv(flags, name, envValue) {
+    const fromFlags = flags.values.get(name);
+    if (fromFlags !== undefined && fromFlags !== '')
+        return fromFlags;
+    if (envValue !== undefined && envValue !== '')
+        return envValue;
+    return undefined;
+}
+/**
+ * Reads env + argv and starts the witness.
+ *
+ * Args:
+ *   argv: CLI flags (see the module header; `--help` prints usage and
+ *     returns a never-started handle).
+ *   env: process environment.
+ *
+ * Returns:
+ *   WitnessHandle once listening (or a handle with an empty `url` for
+ *   `--help`; the wrapper skips its URL banner in that case).
+ *
+ * Throws:
+ *   WitnessStartupError / AttestationError / AdapterRegistryError:
+ *     fail-closed startup problems (exit 2 via the wrapper).
+ */
+export async function main(argv, env) {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        process.stdout.write(`${WITNESS_BIN_USAGE}\n`);
+        return Object.freeze({ url: '', proxyUrl: null, stop: async () => { } });
+    }
+    const flags = parseFlags(argv);
+    const runId = env[ENV_RUN_ID];
+    const token = env[ENV_RUN_TOKEN];
+    if (runId === undefined || runId === '') {
+        throw new WitnessStartupError(`${ENV_RUN_ID} is required (set by 'gateforge test-gates')`);
+    }
+    if (token === undefined || token === '') {
+        throw new WitnessStartupError(`${ENV_RUN_TOKEN} is required (set by 'gateforge test-gates')`);
+    }
+    // Environment-only, deliberately absent from argv (world-readable
+    // /proc cmdline): the suite must never see the verifier key either way.
+    const verifierKey = env[ENV_WITNESS_VERIFIER_KEY] ?? null;
+    return startWitness({
+        runId,
+        token,
+        proxyTarget: flagOrEnv(flags, 'proxy-target', env[ENV_PROXY_TARGET]),
+        mountPath: flagOrEnv(flags, 'mount-path', env[ENV_MOUNT_PATH]),
+        stateDir: flagOrEnv(flags, 'state-dir', env[ENV_STATE_DIR]),
+        classificationsPath: flagOrEnv(flags, 'classifications', env[ENV_CLASSIFICATIONS]),
+        adaptersDir: flagOrEnv(flags, 'adapters-dir', env[ENV_ADAPTERS_DIR] ?? '.gateforge/adapters'),
+        targetBaseUrl: flagOrEnv(flags, 'target-base-url', env[ENV_TARGET_BASE_URL]),
+        targetFingerprint: flagOrEnv(flags, 'target-fingerprint', env[ENV_TARGET_FINGERPRINT]),
+        adapterBaseUrl: flagOrEnv(flags, 'adapter-base-url', env[ENV_ADAPTER_BASE_URL]),
+        adapterReadAuthorization: flagOrEnv(flags, 'adapter-read-authorization', env['GATEFORGE_ADAPTER_READ_AUTHORIZATION']) ?? null,
+        verifierKey,
+    });
+}
+//# sourceMappingURL=bin.js.map

package/dist/witness/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/witness/bin.ts"],"names":[],"mappings":"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"}

package/dist/witness/browser.d.ts

@@ -0,0 +1,173 @@
+/**
+ * The engine-owned browser (plan Phase 1 item 4): Chromium contexts the
+ * WITNESS process creates and drives itself — one isolated context per
+ * supervisor-opened test session, closed when the session seals.
+ *
+ * Test code NEVER touches these pages: the worker holds no handle, no
+ * URL, and no capability over them. The engine executes the constrained
+ * surface operations (create/read/update/archive) with the
+ * consumer-declared locators, and observes each step itself:
+ * - the rendered control it clicked and the values it typed;
+ * - the actual application request the action caused (captured from the
+ *   engine page's own network, app-origin only);
+ * - the resulting navigation and the rendered row/form it read back.
+ *
+ * Forgery resistance (why this channel is proof):
+ * - fabricated DOM (`page.evaluate` in the worker page) is irrelevant:
+ *   the engine reads its OWN page;
+ * - mocked responses (`page.route` in the worker) are irrelevant: the
+ *   worker cannot route the engine's traffic;
+ * - direct API/Node mutations bypass the engine page entirely: no
+ *   engine action runs, so no engine-observed action/visible records
+ *   exist for them — invented suite-submitted records never satisfy;
+ * - HTTP-200-while-error: the engine asserts the rendered status
+ *   itself (created/archived values) AND captures the app response
+ *   status — a displayed error fails the action fail-closed.
+ *
+ * Surface selectors are LOCATORS, never proof: a lying descriptor only
+ * makes the engine fail to find elements (fail closed).
+ */
+import { type Browser, type Page } from 'playwright';
+import { type SurfaceDescriptor } from '../surface.js';
+/** The UI operations the engine can perform (constrained subset). */
+export type EngineOperation = 'create' | 'read' | 'update' | 'delete';
+/** One app-origin exchange the engine captured during an action. */
+export interface EngineCapturedExchange {
+    /** Uppercase method (GET, POST, ...). */
+    method: string;
+    /** Canonical observed path (query/fragment stripped). */
+    path: string;
+    /** Response status the app answered. */
+    status: number;
+    /** Response body bytes (bounded snapshot for hashing). */
+    body: Buffer;
+}
+/** What the engine observed performing one action. */
+export interface EngineActionObservation {
+    /** Entity id OBSERVED from the rendered list (never declared). */
+    entityId: string;
+    /** The exact input values the engine typed (exact-value echo source). */
+    enteredFields: Record<string, string>;
+    /** The rendered fields the engine read back after the action. */
+    renderedFields: Record<string, string>;
+    /** App-origin exchanges captured inside the action window. */
+    exchanges: EngineCapturedExchange[];
+    /** Engine-side pre-observation marker (filled by the witness layer). */
+    preObservationId?: string;
+}
+/** Fail-closed engine browser error (surfaced as 409/503 downstream). */
+export declare class EngineBrowserError extends Error {
+    constructor(message: string);
+}
+/** The browser launcher the engine drives (default: pinned Chromium). */
+export interface EngineBrowserLauncher {
+    launch(options?: Record<string, unknown>): Promise<Browser>;
+}
+/**
+ * Owns the engine Chromium instance and its per-session contexts.
+ *
+ * Args:
+ *   launcher: browser launcher (default: the pinned Chromium). Tests
+ *     inject a failing launcher to prove the fail-closed path; the
+ *     driving and observation below stay engine code regardless of
+ *     which executable launches.
+ */
+export declare class EngineBrowserManager {
+    private readonly launcher;
+    private browser;
+    private launching;
+    private readonly sessions;
+    /**
+     * Pinned `--host-resolver-rules` value binding every attested hostname
+     * to its startup-approved loopback IPs. Set once at witness startup
+     * (before any launch); the browser is then incapable of resolving
+     * those names anywhere but loopback, regardless of later DNS changes.
+     */
+    private dnsPinRules;
+    constructor(launcher?: EngineBrowserLauncher);
+    /**
+     * Installs the DNS pin rules for the next (first) launch.
+     *
+     * Args:
+     *   rules: the `--host-resolver-rules` value, or null when nothing is
+     *     pinned (plain launch, previous behavior).
+     *
+     * Throws:
+     *   EngineBrowserError: when the browser already launched — pins must
+     *   precede every navigation (fail closed, never silently unbound).
+     */
+    setDnsPinRules(rules: string | null): void;
+    /**
+     * Returns the engine page for one session, creating the isolated
+     * context on first use.
+     *
+     * Args:
+     *   sessionId: the supervisor-opened session the context belongs to.
+     *
+     * Returns:
+     *   Promise<Page>: the session's engine-owned page.
+     *
+     * Throws:
+     *   EngineBrowserError: when Chromium cannot launch (fail closed —
+     *     the capability is honestly unavailable at runtime).
+     */
+    pageFor(sessionId: string): Promise<Page>;
+    /**
+     * Closes and forgets one session's engine context (session seal).
+     * Late engine calls for the session then recreate nothing — callers
+     * must refuse sealed sessions before driving (they do: every browser
+     * endpoint requires an OPEN session first).
+     *
+     * Args:
+     *   sessionId: the sealed session.
+     */
+    closeSession(sessionId: string): Promise<void>;
+    /** Closes every engine context and the browser (witness stop). */
+    closeAll(): Promise<void>;
+    /** Lazy Chromium launch (single flight; fail closed with the cause). */
+    private ensureBrowser;
+}
+/**
+ * Drives one constrained surface operation on the engine page and
+ * observes every step itself.
+ *
+ * Args:
+ *   page: the session's engine-owned page.
+ *   appBase: loopback app base the engine navigates (validated upstream).
+ *   surface: the validated consumer descriptor (locators only).
+ *   operation: the constrained operation to perform.
+ *   input: entered fields (create/update) and/or the target entity id.
+ *
+ * Returns:
+ *   Promise<EngineActionObservation>: the engine's own observation —
+ *   observed entity id, entered + rendered fields, captured exchanges.
+ *
+ * Throws:
+ *   EngineBrowserError: fail-closed on every untrusted outcome —
+ *   missing rows, ambiguous creation, wrong rendered status, no
+ *   application request, or an application error status.
+ */
+export declare function driveEngineAction(page: Page, appBase: string, surface: SurfaceDescriptor, operation: EngineOperation, input: {
+    fields?: Record<string, string>;
+    entityId?: string;
+}): Promise<EngineActionObservation>;
+/**
+ * Re-reads the rendered result for one entity on the engine page
+ * (the `visible.confirm` counterpart): row read for mutations, form
+ * read for reads.
+ *
+ * Args:
+ *   page: the session's engine-owned page.
+ *   appBase: loopback app base.
+ *   surface: the validated consumer descriptor.
+ *   operation: the original action (decides row vs form readback).
+ *   entityId: the engine-observed entity id.
+ *
+ * Returns:
+ *   Promise<Record<string, string>>: the rendered fields.
+ *
+ * Throws:
+ *   EngineBrowserError: when the UI no longer exposes the entity.
+ */
+export declare function readEngineVisible(page: Page, appBase: string, surface: SurfaceDescriptor, operation: EngineOperation, entityId: string): Promise<Record<string, string>>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/witness/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/witness/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAY,KAAK,OAAO,EAAqC,KAAK,IAAI,EAAiB,MAAM,YAAY,CAAC;AACjH,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AAEvB,qEAAqE;AACrE,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEtE,oEAAoE;AACpE,MAAM,WAAW,sBAAsB;IACrC,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,sDAAsD;AACtD,MAAM,WAAW,uBAAuB;IACtC,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,8DAA8D;IAC9D,SAAS,EAAE,sBAAsB,EAAE,CAAC;IACpC,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,yEAAyE;AACzE,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,yEAAyE;AACzE,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7D;AAKD;;;;;;;;GAQG;AACH,qBAAa,oBAAoB;IAYnB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAXrC,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,SAAS,CAAiC;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8D;IACvF;;;;;OAKG;IACH,OAAO,CAAC,WAAW,CAAuB;gBAEb,QAAQ,GAAE,qBAAgC;IAEvE;;;;;;;;;;OAUG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAS1C;;;;;;;;;;;;;OAaG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU/C;;;;;;;;OAQG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpD,kEAAkE;IAC5D,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAU/B,wEAAwE;YAC1D,aAAa;CAuB5B;AAgND;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,iBAAiB,EAC1B,SAAS,EAAE,eAAe,EAC1B,KAAK,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D,OAAO,CAAC,uBAAuB,CAAC,CAWlC;AAkLD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,iBAAiB,EAC1B,SAAS,EAAE,eAAe,EAC1B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAmBjC"}