@gate-forge/witness 0.0.0-stage → 0.8.0

package/dist/witness/browser.js

@@ -0,0 +1,644 @@
+import { declaredSurfaceFields, renderSurfaceTemplate, } from '../surface.js';
+/** Fail-closed engine browser error (surfaced as 409/503 downstream). */
+export class EngineBrowserError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EngineBrowserError';
+    }
+}
+/** Bounded wait for a rendered selector (fail closed, never indefinite). */
+const ENGINE_STEP_TIMEOUT_MS = 15_000;
+/**
+ * Walks one validated wizard step list on the engine-owned page
+ * (surface v2 create). Every interaction runs here, engine-side: the
+ * test supplies intent (field values) only. A step referencing an
+ * input field the journey did not provide fails closed — the engine
+ * never invents values. Unknown shapes are unreachable post-
+ * validation, but still refused defensively (never silently skipped).
+ *
+ * Args:
+ *   page: the engine-owned page (real or structural stub).
+ *   appBase: the trusted attested subject origin (never suite input).
+ *   steps: the validated wizard walk, in order.
+ *   fields: the journey's declared input values, keyed by field name.
+ */
+export async function driveCreateSteps(page, appBase, steps, fields) {
+    for (const step of steps) {
+        if ('goto' in step) {
+            await page.goto(`${appBase}${step.goto}`, { timeout: ENGINE_STEP_TIMEOUT_MS });
+        }
+        else if ('click' in step) {
+            await page.locator(step.click).click({ timeout: ENGINE_STEP_TIMEOUT_MS });
+        }
+        else if ('fill' in step) {
+            const value = step.fill.field !== undefined ? fields[step.fill.field] : step.fill.value;
+            if (typeof value !== 'string') {
+                throw new EngineBrowserError(`browser.create steps: fill of '${step.fill.selector}' references field ` +
+                    `'${String(step.fill.field)}' the journey did not provide — the engine never invents input values`);
+            }
+            await page.locator(step.fill.selector).fill(value, { timeout: ENGINE_STEP_TIMEOUT_MS });
+        }
+        else if ('check' in step) {
+            await page.locator(step.check).check({ timeout: ENGINE_STEP_TIMEOUT_MS });
+        }
+        else if ('press' in step) {
+            await page.keyboard.press(step.press);
+        }
+        else if ('waitFor' in step) {
+            await page.waitForSelector(step.waitFor, { timeout: ENGINE_STEP_TIMEOUT_MS });
+        }
+        else {
+            throw new EngineBrowserError(`browser.create steps: unknown wizard step ${JSON.stringify(step)} — refusing to drive`);
+        }
+    }
+}
+/**
+ * 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 class EngineBrowserManager {
+    launcher;
+    browser = null;
+    launching = null;
+    sessions = new Map();
+    /**
+     * 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.
+     */
+    dnsPinRules = null;
+    /**
+     * @param launcher - the browser launcher to use. REQUIRED: this
+     *   package is runner-neutral and must not assume a browser. The
+     *   Playwright-defaulting subclass lives in
+     *   `@gate-forge/pack-playwright`.
+     */
+    constructor(launcher) {
+        this.launcher = launcher;
+        if (typeof launcher.launch !== 'function') {
+            throw new EngineBrowserError('an engine browser launcher is required: the runner-neutral witness never assumes a browser');
+        }
+    }
+    /**
+     * 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) {
+        if (this.browser !== null || this.launching !== null) {
+            throw new EngineBrowserError('DNS pin rules arrive after browser launch: pins must precede every navigation');
+        }
+        this.dnsPinRules = rules;
+    }
+    /**
+     * 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).
+     */
+    async pageFor(sessionId) {
+        const existing = this.sessions.get(sessionId);
+        if (existing !== undefined)
+            return existing.page;
+        const browser = await this.ensureBrowser();
+        const context = await browser.newContext();
+        const page = await context.newPage();
+        this.sessions.set(sessionId, { context, page });
+        return 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.
+     */
+    async closeSession(sessionId) {
+        const entry = this.sessions.get(sessionId);
+        if (entry === undefined)
+            return;
+        this.sessions.delete(sessionId);
+        await entry.context.close().catch(() => undefined);
+    }
+    /** Closes every engine context and the browser (witness stop). */
+    async closeAll() {
+        const entries = [...this.sessions.values()];
+        this.sessions.clear();
+        await Promise.all(entries.map((entry) => entry.context.close().catch(() => undefined)));
+        const browser = this.browser;
+        this.browser = null;
+        this.launching = null;
+        if (browser !== null)
+            await browser.close().catch(() => undefined);
+    }
+    /** Lazy Chromium launch (single flight; fail closed with the cause). */
+    async ensureBrowser() {
+        if (this.browser !== null)
+            return this.browser;
+        this.launching ??= this.launcher
+            .launch({
+            headless: true,
+            // DNS binding (loopback-pins): attested hostnames resolve ONLY
+            // to their startup-approved loopback IPs inside this browser —
+            // a mid-run DNS change cannot move its traffic off loopback.
+            ...(this.dnsPinRules !== null ? { args: [`--host-resolver-rules=${this.dnsPinRules}`] } : {}),
+        })
+            .then((browser) => {
+            this.browser = browser;
+            return browser;
+        })
+            .catch((error) => {
+            this.launching = null;
+            throw new EngineBrowserError(`the engine-owned browser cannot launch: ${error.message} — browser ` +
+                'contracts stay blocking until a working Chromium is available to the witness process');
+        });
+        return this.launching;
+    }
+}
+/** Captures app-origin responses on one page for the action window. */
+async function captureExchanges(page, appOrigin, action) {
+    const captured = [];
+    // Replacement-origin enforcement (fake-frontend fix 2026-09-14): every
+    // URL the engine page touches during the window — main-frame
+    // navigations AND every hop of every redirect chain — must stay on the
+    // trusted origin. A form submit, link, or redirect landing elsewhere
+    // fails the action closed instead of observing a foreign frontend.
+    const violations = [];
+    const checkUrl = (url, where) => {
+        let origin;
+        try {
+            origin = new URL(url).origin;
+        }
+        catch {
+            return; // non-URL (about:blank, data:) — the final page.url check covers landing
+        }
+        if (origin !== appOrigin)
+            violations.push(`${where}: ${url}`);
+    };
+    // Main-frame navigation guard: page.url() is the main frame's URL,
+    // so asserting it on every frame event covers navigations while
+    // subresource loads (same URL, no-op) cannot false-positive.
+    const mainFrameListener = () => {
+        const current = page.url();
+        if (current.startsWith('about:') || current.startsWith('data:'))
+            return;
+        checkUrl(current, 'navigation to foreign origin');
+    };
+    page.on('framenavigated', mainFrameListener);
+    const listener = (response) => {
+        // Walk the full redirect chain: the final URL AND every hop must be
+        // same-origin — a 303 to a foreign frontend is rejected even though
+        // the 303 itself came from the app. Scoped to redirects and document
+        // navigations: plain cross-origin SUBRESOURCES (fonts, icons) are
+        // not navigations, never become evidence, and must not false-positive.
+        const request = response.request();
+        const chain = [request.url()];
+        let previous = request.redirectedFrom();
+        while (previous !== null && typeof previous === 'object' && 'url' in previous) {
+            const hop = previous;
+            chain.push(hop.url());
+            previous = hop.redirectedFrom();
+        }
+        const involvedRedirect = chain.length > 1;
+        let resourceType = '';
+        try {
+            resourceType = request.resourceType();
+        }
+        catch {
+            resourceType = '';
+        }
+        if (involvedRedirect || resourceType === 'document') {
+            for (const url of chain)
+                checkUrl(url, 'redirect chain left the trusted origin');
+        }
+        let url;
+        try {
+            url = new URL(response.url());
+        }
+        catch {
+            return;
+        }
+        if (url.origin !== appOrigin)
+            return;
+        const chunks = [];
+        void response
+            .body()
+            .then((body) => chunks.push(body))
+            .catch(() => undefined)
+            .finally(() => {
+            captured.push({
+                method: response.request().method().toUpperCase(),
+                path: canonicalExchangePath(url.pathname),
+                status: response.status(),
+                body: Buffer.concat(chunks).slice(0, 16384),
+            });
+        });
+    };
+    page.on('response', listener);
+    // The drive's own error (status mismatch, missing row) is recorded
+    // but yields to origin violations: a redirect escape is the stronger
+    // security signal and must name itself even when the foreign page
+    // ALSO fails a rendered check.
+    let driveError = null;
+    try {
+        await action();
+        // Let in-flight response bodies settle (bounded): the mutation's own
+        // exchange must be captured before the window closes.
+        await page.waitForTimeout(250);
+    }
+    catch (error) {
+        driveError = error;
+    }
+    finally {
+        page.off('response', listener);
+        page.off('framenavigated', mainFrameListener);
+    }
+    // Await the pending body reads (bounded by the step timeout overall).
+    await page.waitForTimeout(250);
+    // The landing itself must be the trusted origin (backstop for
+    // navigations that produced no response event).
+    checkUrl(page.url(), 'engine page landed on a foreign origin');
+    if (violations.length > 0) {
+        throw new EngineBrowserError(`browser action left the trusted application origin '${appOrigin}': ` +
+            `${violations.slice(0, 3).join('; ')} — replacement origins and redirects are rejected; ` +
+            'no action record is issued for a foreign frontend');
+    }
+    if (driveError !== null)
+        throw driveError;
+    return captured;
+}
+/** Canonicalizes an engine-observed path (lockstep with the witness). */
+function canonicalExchangePath(pathname) {
+    let path = pathname.split('?')[0]?.split('#')[0] ?? '/';
+    if (!path.startsWith('/'))
+        path = `/${path}`;
+    if (path.length > 1)
+        path = path.replace(/\/+$/, '');
+    return path;
+}
+/** Reads the cells of a legacy table row in DOM order. */
+async function rowCells(row) {
+    const cells = row.locator('td');
+    const count = await cells.count();
+    const out = [];
+    for (let i = 0; i < count; i++) {
+        out.push(((await cells.nth(i).textContent()) ?? '').trim());
+    }
+    return out;
+}
+/**
+ * Checks whether one descriptor uses v3 row-relative field locators.
+ *
+ * Args:
+ *   list: the validated list descriptor.
+ *
+ * Returns:
+ *   boolean: true when v3 relative locators are present.
+ */
+function usesRelativeListLocators(list) {
+    return typeof list.idLocator === 'string';
+}
+/**
+ * Reads an entity id from a row with its versioned list strategy.
+ *
+ * Args:
+ *   row: the matched entity row or card.
+ *   surface: the validated consumer surface descriptor.
+ *
+ * Returns:
+ *   Promise<string>: the trimmed rendered entity id.
+ */
+async function readRowEntityId(row, surface) {
+    if (usesRelativeListLocators(surface.list)) {
+        return ((await row.locator(surface.list.idLocator).textContent()) ?? '').trim();
+    }
+    const cells = await rowCells(row);
+    return (cells[surface.list.idCellIndex] ?? '').trim();
+}
+/** Every entity id rendered in the list right now. */
+async function collectIds(page, surface) {
+    const rows = page.locator(surface.list.rowSelector);
+    const count = await rows.count();
+    const ids = new Set();
+    for (let i = 0; i < count; i++) {
+        const id = await readRowEntityId(rows.nth(i), surface);
+        if (id !== '')
+            ids.add(id);
+    }
+    return ids;
+}
+/** The rendered row for one entity (null when the UI exposes none). */
+async function findRow(page, surface, entityId) {
+    const rows = page.locator(surface.list.rowSelector);
+    const count = await rows.count();
+    for (let i = 0; i < count; i++) {
+        const row = rows.nth(i);
+        if ((await readRowEntityId(row, surface)) === entityId)
+            return row;
+    }
+    return null;
+}
+/** The rendered field values of one row. */
+async function readRowFields(page, surface, row) {
+    void page;
+    const fields = {};
+    if (usesRelativeListLocators(surface.list)) {
+        for (const [name, selector] of Object.entries(surface.list.fieldLocators)) {
+            fields[name] = ((await row.locator(selector).textContent()) ?? '').trim();
+        }
+    }
+    else {
+        const cells = await rowCells(row);
+        for (const [name, index] of Object.entries(surface.list.fieldCellIndexes)) {
+            fields[name] = (cells[index] ?? '').trim();
+        }
+    }
+    return fields;
+}
+/** Fills exactly the declared inputs on the current form. */
+async function fillFormFields(page, selectors, fields) {
+    for (const [name, selector] of Object.entries(selectors)) {
+        const value = fields[name];
+        if (value === undefined)
+            continue;
+        await page.locator(selector).fill(value, { timeout: ENGINE_STEP_TIMEOUT_MS });
+    }
+}
+/** Reads the current form's input values back. */
+async function readFormFields(page, selectors) {
+    const fields = {};
+    for (const [name, selector] of Object.entries(selectors)) {
+        fields[name] = await page.locator(selector).inputValue({ timeout: ENGINE_STEP_TIMEOUT_MS });
+    }
+    return fields;
+}
+/** Navigates to the list and proves it rendered. */
+async function gotoList(page, appBase, surface) {
+    await page.goto(`${appBase}${surface.list.path}`, { timeout: ENGINE_STEP_TIMEOUT_MS });
+    await page.waitForSelector(surface.list.readySelector, { timeout: ENGINE_STEP_TIMEOUT_MS });
+}
+/** Waits for the post-action landing and proves it rendered. */
+async function waitAfterAction(page, surface) {
+    await page.waitForURL((url) => url.pathname === surface.afterAction.path, {
+        timeout: ENGINE_STEP_TIMEOUT_MS,
+    });
+    await page.waitForSelector(surface.list.readySelector, { timeout: ENGINE_STEP_TIMEOUT_MS });
+}
+/**
+ * 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 async function driveEngineAction(page, appBase, surface, operation, input) {
+    const appOrigin = new URL(appBase).origin;
+    try {
+        return await driveEngineActionInner(page, appBase, appOrigin, surface, operation, input);
+    }
+    catch (error) {
+        // Every Playwright failure (timeout, navigation, detached frame) is
+        // an engine-observed unsuccessful action — never a 500: the test
+        // fails and the gate blocks with the precise cause.
+        if (error instanceof EngineBrowserError)
+            throw error;
+        throw new EngineBrowserError(`browser.${operation} failed: ${error.message}`);
+    }
+}
+/** The operation dispatch (wrapped by {@link driveEngineAction}). */
+async function driveEngineActionInner(page, appBase, appOrigin, surface, operation, input) {
+    switch (operation) {
+        case 'create': {
+            const fields = declaredSurfaceFields('browser.create', input.fields ?? {}, surface.create.fields);
+            let entityId = '';
+            let rendered = {};
+            const exchanges = await captureExchanges(page, appOrigin, async () => {
+                await gotoList(page, appBase, surface);
+                const before = await collectIds(page, surface);
+                if ('steps' in surface.create) {
+                    // Wizard walk (surface v2): the engine performs the declared
+                    // steps itself — every click/type is engine-observed.
+                    await driveCreateSteps(page, appBase, surface.create.steps, fields);
+                }
+                else {
+                    await page.goto(`${appBase}${surface.create.formPath}`, { timeout: ENGINE_STEP_TIMEOUT_MS });
+                    await page.waitForSelector(surface.create.formReadySelector, { timeout: ENGINE_STEP_TIMEOUT_MS });
+                    await fillFormFields(page, surface.create.fields, fields);
+                    await page.locator(surface.create.submitSelector).click({ timeout: ENGINE_STEP_TIMEOUT_MS });
+                }
+                await waitAfterAction(page, surface);
+                const created = [...(await collectIds(page, surface))].filter((id) => !before.has(id));
+                if (created.length !== 1) {
+                    throw new EngineBrowserError(`browser.create observed ${String(created.length)} new entities, expected exactly one — ` +
+                        'the rendered outcome is ambiguous, so no action record is issued');
+                }
+                entityId = created[0];
+                const row = await findRow(page, surface, entityId);
+                if (row === null) {
+                    throw new EngineBrowserError(`browser.create: the rendered list exposes no row for the created entity ${entityId}`);
+                }
+                rendered = await readRowFields(page, surface, row);
+                if (surface.status.createdValue !== undefined) {
+                    const shown = rendered[surface.status.field] ?? '';
+                    if (shown !== surface.status.createdValue) {
+                        throw new EngineBrowserError(`browser.create: entity ${entityId} rendered ${surface.status.field} '${shown}', ` +
+                            `expected '${surface.status.createdValue}' — the application displays an error state, ` +
+                            'so the action fails instead of earning proof');
+                    }
+                }
+            });
+            requireAppRequest(exchanges, 'create');
+            return { entityId, enteredFields: fields, renderedFields: rendered, exchanges };
+        }
+        case 'read': {
+            const entityId = input.entityId ?? '';
+            if (entityId === '')
+                throw new EngineBrowserError('browser.read requires { entityId }');
+            let rendered = {};
+            const exchanges = await captureExchanges(page, appOrigin, async () => {
+                await gotoList(page, appBase, surface);
+                const row = await findRow(page, surface, entityId);
+                if (row === null) {
+                    throw new EngineBrowserError(`browser.read: the rendered UI exposes no row for ${entityId}`);
+                }
+                const edit = row.locator(surface.edit.linkSelector);
+                if ((await edit.count()) === 0) {
+                    throw new EngineBrowserError(`browser.read: the rendered UI exposes no navigation control for ${entityId}`);
+                }
+                await edit.click({ timeout: ENGINE_STEP_TIMEOUT_MS });
+                await page.waitForSelector(renderSurfaceTemplate(surface.edit.formReadySelectorTemplate, entityId), {
+                    timeout: ENGINE_STEP_TIMEOUT_MS,
+                });
+                rendered = await readFormFields(page, surface.edit.fields);
+            });
+            return { entityId, enteredFields: {}, renderedFields: rendered, exchanges };
+        }
+        case 'update': {
+            const entityId = input.entityId ?? '';
+            if (entityId === '')
+                throw new EngineBrowserError('browser.update requires { entityId }');
+            const fields = declaredSurfaceFields('browser.update', input.fields ?? {}, surface.edit.fields);
+            let rendered = {};
+            const exchanges = await captureExchanges(page, appOrigin, async () => {
+                await gotoList(page, appBase, surface);
+                const row = await findRow(page, surface, entityId);
+                if (row === null) {
+                    throw new EngineBrowserError(`browser.update: the rendered UI exposes no row for ${entityId}`);
+                }
+                await row.locator(surface.edit.linkSelector).click({ timeout: ENGINE_STEP_TIMEOUT_MS });
+                await page.waitForSelector(renderSurfaceTemplate(surface.edit.formReadySelectorTemplate, entityId), {
+                    timeout: ENGINE_STEP_TIMEOUT_MS,
+                });
+                await fillFormFields(page, surface.edit.fields, fields);
+                await page
+                    .locator(renderSurfaceTemplate(surface.edit.saveSelectorTemplate, entityId))
+                    .first()
+                    .click({ timeout: ENGINE_STEP_TIMEOUT_MS });
+                await waitAfterAction(page, surface);
+                const updatedRow = await findRow(page, surface, entityId);
+                if (updatedRow === null) {
+                    throw new EngineBrowserError(`browser.update: entity ${entityId} vanished after update`);
+                }
+                rendered = await readRowFields(page, surface, updatedRow);
+            });
+            requireAppRequest(exchanges, 'update');
+            return { entityId, enteredFields: fields, renderedFields: rendered, exchanges };
+        }
+        case 'delete': {
+            const entityId = input.entityId ?? '';
+            if (entityId === '')
+                throw new EngineBrowserError('browser.archive requires { entityId }');
+            const deleteFields = { ...surface.deleteFields };
+            let rendered = {};
+            const exchanges = await captureExchanges(page, appOrigin, async () => {
+                await gotoList(page, appBase, surface);
+                const row = await findRow(page, surface, entityId);
+                if (row === null) {
+                    throw new EngineBrowserError(`browser.archive: the rendered UI exposes no row for ${entityId}`);
+                }
+                const control = row.locator(renderSurfaceTemplate(surface.archive.controlSelectorTemplate, entityId));
+                if ((await control.count()) === 0) {
+                    throw new EngineBrowserError(`browser.archive: entity ${entityId} exposes no archive control (already archived?)`);
+                }
+                await control.click({ timeout: ENGINE_STEP_TIMEOUT_MS });
+                await waitAfterAction(page, surface);
+                const archivedRow = await findRow(page, surface, entityId);
+                if (archivedRow === null) {
+                    throw new EngineBrowserError(`browser.archive: entity ${entityId} vanished after archive`);
+                }
+                rendered = await readRowFields(page, surface, archivedRow);
+                if (surface.status.archivedValue !== undefined) {
+                    const shown = rendered[surface.status.field] ?? '';
+                    if (shown !== surface.status.archivedValue) {
+                        throw new EngineBrowserError(`browser.archive: entity ${entityId} rendered ${surface.status.field} '${shown}', ` +
+                            `expected '${surface.status.archivedValue}' — the application displays an error ` +
+                            'state, so the action fails instead of earning proof');
+                    }
+                }
+            });
+            requireAppRequest(exchanges, 'delete');
+            return { entityId, enteredFields: deleteFields, renderedFields: rendered, exchanges };
+        }
+    }
+}
+/**
+ * Requires that the action window captured at least one application
+ * request that the app did not reject: a rendered click that caused no
+ * request (or only error statuses) proves no application behavior.
+ *
+ * Args:
+ *   exchanges: the engine-captured app-origin exchanges.
+ *   operation: the performed operation (diagnostic only).
+ *
+ * Throws:
+ *   EngineBrowserError: when no acceptable application request exists.
+ */
+function requireAppRequest(exchanges, operation) {
+    const mutation = exchanges.filter((entry) => entry.method !== 'GET' && entry.method !== 'HEAD');
+    if (mutation.length === 0) {
+        throw new EngineBrowserError(`browser.${operation}: the engine captured no application request for the action — ` +
+            'a rendered click that caused no request proves no application behavior');
+    }
+    const accepted = mutation.find((entry) => entry.status < 400);
+    if (accepted === undefined) {
+        throw new EngineBrowserError(`browser.${operation}: every captured application request was rejected ` +
+            `(${mutation.map((entry) => `${entry.method} ${entry.path} → ${String(entry.status)}`).join(', ')}) — ` +
+            'the application refused the action, so it fails instead of earning proof');
+    }
+}
+/**
+ * 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 async function readEngineVisible(page, appBase, surface, operation, entityId) {
+    try {
+        await gotoList(page, appBase, surface);
+        const row = await findRow(page, surface, entityId);
+        if (row === null) {
+            throw new EngineBrowserError(`browser.visible: the rendered UI exposes no row for ${entityId}`);
+        }
+        if (operation === 'read') {
+            await row.locator(surface.edit.linkSelector).click({ timeout: ENGINE_STEP_TIMEOUT_MS });
+            await page.waitForSelector(renderSurfaceTemplate(surface.edit.formReadySelectorTemplate, entityId), {
+                timeout: ENGINE_STEP_TIMEOUT_MS,
+            });
+            return readFormFields(page, surface.edit.fields);
+        }
+        return readRowFields(page, surface, row);
+    }
+    catch (error) {
+        if (error instanceof EngineBrowserError)
+            throw error;
+        throw new EngineBrowserError(`browser.visible failed: ${error.message}`);
+    }
+}
+//# sourceMappingURL=browser.js.map