@e2edev/e2e 0.12.0 → 0.13.0

package/dist/agent/observation-feed.js

@@ -0,0 +1,281 @@
+/**
+ * What one step has seen of the screen, and how it looks again.
+ *
+ * The feed owns every capture of a step: the settle that reads an action's
+ * result after its effect, the ring of recent observations an id is resolved
+ * against, the pixel decision (masking proven, viewport untainted), and the
+ * executor's redacted view of a capture. Nothing else in the step observes
+ * the engine; the dispatcher and the pixel tier ask the feed.
+ */
+import { TestError } from '../internal/errors.js';
+import { describeTarget } from './actions.js';
+import { relocateDescriptor } from '../cache/relocate.js';
+import { AgentError } from './error.js';
+import { isTransitionalObservation, observationShape, pixelsForModel, prepareObservation, projectTree, settleObservation, } from './observation.js';
+import { observationByteBudget } from './observation-budget.js';
+import { instrumentPhase, recordPolicyEvent, retryingObserve } from './phases.js';
+/**
+ * Observations kept for resolving an id the newest one no longer carries.
+ * A turn that batches actions addresses the screen it saw, while every
+ * action's own look re-observes; on an engine that mints ids per observation
+ * (a device), each look renumbers the tree. A few looks back is as far as one
+ * turn can reach.
+ */
+const MAX_RECENT_OBSERVATIONS = 8;
+export class ObservationFeed {
+    runtime;
+    accounting;
+    queue;
+    options;
+    newest;
+    /** The newest observations of the step, oldest first; see MAX_RECENT_OBSERVATIONS. */
+    recent = [];
+    /**
+     * The screen shape the newest committed action was resolved against, kept
+     * until the next settled observation has waited for the screen to leave it.
+     * Armed by actions whose effect shows in the tree; a secret fill leaves no
+     * visible trace and a scroll moves nothing the tree records, so neither
+     * arms it. Without this, the observation after a tap on a link reads the
+     * old page, stable and wrong, and the model repairs what already worked.
+     */
+    pendingChange;
+    /** The change wait the pending action asked for; undefined takes the default. */
+    pendingChangeWaitMs;
+    /** The last pixel decision recorded on this step: `allowed`, or the withheld reason. */
+    pixelsDecided;
+    /** Why requested pixels did not become model input, when they did not. */
+    visionDegraded;
+    /** True once pixels this feed cleared were handed to the executor as model input. */
+    pixelsSent = false;
+    constructor(runtime, accounting, queue, options) {
+        this.runtime = runtime;
+        this.accounting = accounting;
+        this.queue = queue;
+        this.options = options;
+    }
+    /** The newest observation of the step, if any was captured. */
+    get latest() {
+        return this.newest;
+    }
+    /** The newest observation, which an action addresses; before the first look there is nothing to address. */
+    requireLatest() {
+        if (this.newest === undefined) {
+            throw new AgentError('LOCATOR_NOT_FOUND', 'no observation has been captured yet; observe before acting');
+        }
+        return this.newest;
+    }
+    /** One raw capture in queue order, for replay's looks between retries. */
+    observeLatest() {
+        return this.queue.run(() => this.observeNow(false, false));
+    }
+    /**
+     * One settled capture in queue order: the executor-facing observe. An
+     * executor observation is followed by a model call measured in seconds, so
+     * the bounded settle wait is noise there — and it guarantees the model never
+     * reads a snapshot the app is still reacting to, which a fast model turns
+     * into a repeated action (double-committing a toggle) and a verdict judged
+     * on pre-render state. Replay's pre-action looks and the cache session's
+     * probes settle through this same path.
+     */
+    observeSettled(pixels = false) {
+        return this.queue.run(() => this.observeNow(true, pixels));
+    }
+    /** The executor-facing observe: the options checked before anything is captured, then one settled look, viewed. */
+    async observe(options = {}) {
+        if (options === null || typeof options !== 'object') {
+            throw new TestError('INVALID_ARGUMENT', 'observe options must be an object');
+        }
+        return this.view(await this.observeSettled(options.pixels === true), options);
+    }
+    /** The executor's view of one capture: redacted text, and the tree and pixels it asked for. */
+    async view(observation, options) {
+        const redact = this.runtime.redact;
+        // Prefer location from this capture; only engines without it need a separate probe.
+        const path = await this.currentPath(observation);
+        return {
+            revision: observation.revision,
+            text: observation.text,
+            truncated: observation.truncated,
+            viewport: observation.viewport,
+            ...(path === undefined ? {} : { path: redact(path) }),
+            ...(options.tree === true ? { tree: projectTree(observation.tree, redact) } : {}),
+            ...(options.pixels === true ? this.pixelsFor(observation) : {}),
+        };
+    }
+    /** Best-effort current location path + query, for trace preconditions. */
+    async currentPath(observation) {
+        const currentUrl = this.runtime.engine.session.url;
+        if (observation?.url === undefined && currentUrl === undefined)
+            return undefined;
+        try {
+            const url = new URL(observation?.url ?? (await currentUrl(this.accounting.operation())));
+            return `${url.pathname}${url.search}`;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Arms the change wait: the next settled observation waits for the screen
+     * to leave the newest observation's shape, for the default two seconds or
+     * the given brief window.
+     */
+    armChange(waitMs) {
+        if (this.newest === undefined)
+            return;
+        this.pendingChange = observationShape(this.newest);
+        this.pendingChangeWaitMs = waitMs;
+    }
+    /**
+     * Resolves an executor target against the newest observation. An id the
+     * newest observation no longer carries, but a recent one did, is re-found
+     * in the newest one by its descriptor: a turn that batches actions keeps
+     * addressing the screen it saw while each action's own look re-observes,
+     * and an engine that mints ids per observation renumbers the tree between
+     * them. Exactly one match, or the id counts as gone.
+     */
+    resolve(target) {
+        if (typeof target?.id !== 'string' || target.id === '') {
+            throw new TestError('INVALID_ARGUMENT', 'action target must be { id: string }');
+        }
+        const id = target.id.replace(/^#/, '');
+        const latest = this.requireLatest();
+        const node = latest.nodes.get(id) ?? this.refound(id, latest);
+        if (node === undefined) {
+            throw new AgentError('LOCATOR_NOT_FOUND', `node #${id} is not on the current screen (observation ${latest.revision}); it was removed or never existed`);
+        }
+        return { node, observation: latest };
+    }
+    /**
+     * Re-finds a node that went stale: one fresh capture, then the trace
+     * recorder's own descriptor matching (`cache/relocate.ts`) against it,
+     * exactly one match or nothing. The capture is taken directly rather than
+     * through the queued observe: this runs inside a queued action body, and a
+     * queued observation would wait on its own caller.
+     */
+    async relocate(stale) {
+        const options = { redact: this.runtime.redact, testIdAttribute: this.runtime.config.testIdAttribute };
+        const descriptor = describeTarget(stale, options.redact, options.testIdAttribute);
+        if (descriptor === undefined)
+            return undefined;
+        this.accounting.checkpoint();
+        const observation = await instrumentPhase(this.runtime, { api: this.accounting.api, kind: 'observation', phase: 'agent.observe', name: 'relocate' }, () => this.capture(false), (prepared) => ({ count: prepared.nodes.size, bytes: prepared.bytes }));
+        this.publish(observation);
+        const relocated = relocateDescriptor(descriptor, observation.nodes, options);
+        if (relocated.kind !== 'found')
+            return undefined;
+        const node = observation.nodes.get(relocated.id);
+        return node === undefined ? undefined : { node, observation };
+    }
+    /** The step's pixel record for the report. */
+    visionReport() {
+        return {
+            ...(this.pixelsSent ? { visionInput: true } : {}),
+            ...(this.visionDegraded === undefined ? {} : { visionDegraded: this.visionDegraded }),
+        };
+    }
+    /** One recorded observation; when `settle`, the captures loop inside it. */
+    async observeNow(settle, pixels) {
+        this.accounting.checkpoint();
+        // A tainted viewport never captures pixels: the engine would mask what it
+        // knows about, and the secret may be anywhere on screen by now.
+        const capturePixels = pixels && !this.runtime.taint.value;
+        // A settled look consumes the pending change: it waits for the screen to
+        // leave the pre-action shape once, and later looks read the screen as is.
+        const changedFrom = settle ? this.pendingChange : undefined;
+        const changeWaitMs = settle ? this.pendingChangeWaitMs : undefined;
+        if (settle) {
+            this.pendingChange = undefined;
+            this.pendingChangeWaitMs = undefined;
+        }
+        const observation = await instrumentPhase(this.runtime, { api: this.accounting.api, kind: 'observation', phase: 'agent.observe' }, () => settle
+            ? settleObservation(() => this.capture(capturePixels), observationShape, {
+                remainingMs: () => this.accounting.remainingMs(),
+                // The step's own hard stop must interrupt a settle sleep too —
+                // the attempt signal alone would let settling outlive the step
+                // by one poll interval.
+                signal: this.accounting.signal,
+            }, { changedFrom, changeWaitMs, transitional: isTransitionalObservation })
+            : this.capture(capturePixels), (prepared) => ({ count: prepared.nodes.size, bytes: prepared.bytes }));
+        this.publish(observation);
+        return observation;
+    }
+    /** Makes an observation the newest, remembers it among the recent ones, and books its size. */
+    publish(observation) {
+        this.newest = observation;
+        this.recent.push(observation);
+        if (this.recent.length > MAX_RECENT_OBSERVATIONS)
+            this.recent.shift();
+        const metrics = this.accounting.metrics;
+        metrics.observationBytes = Math.max(metrics.observationBytes, observation.bytes);
+    }
+    /** One raw observation capture: retried at the engine, then redacted and bounded. */
+    async capture(pixels) {
+        const raw = await retryingObserve({
+            observe: (operation) => this.runtime.engine.session.observe(operation, { pixels }),
+            operation: () => this.accounting.operation(),
+            guard: (cause) => this.accounting.checkpoint(cause),
+            signal: this.runtime.engine.signal,
+            api: this.accounting.api,
+        });
+        return prepareObservation(raw, {
+            redact: this.runtime.redact,
+            maxBytes: this.byteBudget(pixels),
+            testIdAttribute: this.runtime.config.testIdAttribute,
+        });
+    }
+    /**
+     * Bytes one act observation may contribute to a model turn, clamped like a
+     * judgment's. The loop's history grows past what any one observation costs,
+     * so the fixed part counted here is what every turn resends: the project
+     * context and the prior-step ledger.
+     */
+    byteBudget(pixels) {
+        const metrics = this.accounting.metrics;
+        return observationByteBudget({
+            maxObservationBytes: this.options.maxObservationBytes,
+            maxModelTokensPerCall: this.runtime.config.limits.maxModelTokensPerCall,
+        }, { fixedBytes: metrics.contextBytes + metrics.ledgerBytes, pixels });
+    }
+    /**
+     * Pixels for a caller that asked for them, or the reason they are withheld —
+     * the same decision the judgment tier makes, recorded as a policy event
+     * whenever it changes within the step.
+     */
+    pixelsFor(observation) {
+        const outcome = pixelsForModel(observation, this.runtime.taint.value);
+        if ('withheld' in outcome) {
+            this.recordPixelDecision('denied', outcome.withheld);
+            this.visionDegraded = outcome.withheld;
+            return { pixelsWithheld: outcome.withheld };
+        }
+        this.recordPixelDecision('allowed');
+        this.pixelsSent = true;
+        const metrics = this.accounting.metrics;
+        metrics.pixelBytes = Math.max(metrics.pixelBytes ?? 0, outcome.pixels.data.byteLength);
+        return { pixels: outcome.pixels };
+    }
+    recordPixelDecision(decision, code) {
+        const key = code ?? decision;
+        if (this.pixelsDecided === key)
+            return;
+        this.pixelsDecided = key;
+        recordPolicyEvent(this.runtime.steps, 'vision.pixels', decision, code);
+    }
+    /** The newest node matching the descriptor of what `id` named in a recent observation, if exactly one. */
+    refound(id, latest) {
+        let earlier;
+        for (let index = this.recent.length - 1; index >= 0 && earlier === undefined; index -= 1) {
+            earlier = this.recent[index].nodes.get(id);
+        }
+        if (earlier === undefined)
+            return undefined;
+        const options = { redact: this.runtime.redact, testIdAttribute: this.runtime.config.testIdAttribute };
+        const descriptor = describeTarget(earlier, options.redact, options.testIdAttribute);
+        if (descriptor === undefined)
+            return undefined;
+        const relocated = relocateDescriptor(descriptor, latest.nodes, options);
+        return relocated.kind === 'found' ? latest.nodes.get(relocated.id) : undefined;
+    }
+}
+//# sourceMappingURL=observation-feed.js.map

package/dist/agent/observation-feed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-feed.js","sourceRoot":"","sources":["../../src/agent/observation-feed.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGxC,OAAO,EACL,yBAAyB,EACzB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,WAAW,EACX,iBAAiB,GAElB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGlF;;;;;;GAMG;AACH,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAOlC,MAAM,OAAO,eAAe;IAuBP,OAAO;IACP,UAAU;IACV,KAAK;IACL,OAAO;IAzBlB,MAAM,CAA+B;IAC7C,sFAAsF;IACrE,MAAM,GAAuB,EAAE,CAAC;IACjD;;;;;;;OAOG;IACK,aAAa,CAAqB;IAC1C,iFAAiF;IACzE,mBAAmB,CAAqB;IAChD,wFAAwF;IAChF,aAAa,CAAqB;IAC1C,0EAA0E;IAClE,cAAc,CAAgC;IACtD,qFAAqF;IAC7E,UAAU,GAAG,KAAK,CAAC;IAE3B,YACmB,OAAqB,EACrB,UAA0B,EAC1B,KAAqB,EACrB,OAA+B;uBAH/B,OAAO;0BACP,UAAU;qBACV,KAAK;uBACL,OAAO;IACvB,CAAC;IAEJ,+DAA+D;IAC/D,IAAI,MAAM;QACR,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,4GAA4G;IAC5G,aAAa;QACX,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC9B,MAAM,IAAI,UAAU,CAAC,mBAAmB,EAAE,6DAA6D,CAAC,CAAC;QAC3G,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,0EAA0E;IAC1E,aAAa;QACX,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED;;;;;;;;OAQG;IACH,cAAc,CAAC,MAAM,GAAG,KAAK;QAC3B,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED,mHAAmH;IACnH,KAAK,CAAC,OAAO,CAAC,OAAO,GAA2B,EAAE;QAChD,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YACpD,MAAM,IAAI,SAAS,CAAC,kBAAkB,EAAE,mCAAmC,CAAC,CAAC;QAC/E,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;IAChF,CAAC;IAED,+FAA+F;IACvF,KAAK,CAAC,IAAI,CAAC,WAA6B,EAAE,OAA+B;QAC/E,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;QACnC,oFAAoF;QACpF,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;QACjD,OAAO;YACL,QAAQ,EAAE,WAAW,CAAC,QAAQ;YAC9B,IAAI,EAAE,WAAW,CAAC,IAAI;YACtB,SAAS,EAAE,WAAW,CAAC,SAAS;YAChC,QAAQ,EAAE,WAAW,CAAC,QAAQ;YAC9B,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;YACrD,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjF,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SAChE,CAAC;IACJ,CAAC;IAED,0EAA0E;IAC1E,KAAK,CAAC,WAAW,CAAC,WAA8B;QAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC;QACnD,IAAI,WAAW,EAAE,GAAG,KAAK,SAAS,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACjF,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,MAAM,UAAW,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC;YAC1F,OAAO,GAAG,GAAG,CAAC,QAAQ,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;QACxC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,SAAS,CAAC,MAAe;QACvB,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO;QACtC,IAAI,CAAC,aAAa,GAAG,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACnD,IAAI,CAAC,mBAAmB,GAAG,MAAM,CAAC;IACpC,CAAC;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,MAAsB;QAC5B,IAAI,OAAO,MAAM,EAAE,EAAE,KAAK,QAAQ,IAAI,MAAM,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;YACvD,MAAM,IAAI,SAAS,CAAC,kBAAkB,EAAE,sCAAsC,CAAC,CAAC;QAClF,CAAC;QACD,MAAM,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACvC,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;QAC9D,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,IAAI,UAAU,CAClB,mBAAmB,EACnB,SAAS,EAAE,8CAA8C,MAAM,CAAC,QAAQ,oCAAoC,CAC7G,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;IACvC,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,CAAC,KAAmB;QAChC,MAAM,OAAO,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;QACtG,MAAM,UAAU,GAAG,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;QAClF,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC/C,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;QAC7B,MAAM,WAAW,GAAG,MAAM,eAAe,CACvC,IAAI,CAAC,OAAO,EACZ,EAAE,GAAG,EAAE,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,UAAU,EAAE,EAC3F,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EACzB,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CACtE,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC1B,MAAM,SAAS,GAAG,kBAAkB,CAAC,UAAU,EAAE,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAC7E,IAAI,SAAS,CAAC,IAAI,KAAK,OAAO;YAAE,OAAO,SAAS,CAAC;QACjD,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QACjD,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IAChE,CAAC;IAED,8CAA8C;IAC9C,YAAY;QACV,OAAO;YACL,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjD,GAAG,CAAC,IAAI,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC;SACtF,CAAC;IACJ,CAAC;IAED,4EAA4E;IACpE,KAAK,CAAC,UAAU,CAAC,MAAe,EAAE,MAAe;QACvD,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC;QAC7B,0EAA0E;QAC1E,gEAAgE;QAChE,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;QAC1D,yEAAyE;QACzE,0EAA0E;QAC1E,MAAM,WAAW,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;QAC5D,MAAM,YAAY,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC,SAAS,CAAC;QACnE,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,CAAC,aAAa,GAAG,SAAS,CAAC;YAC/B,IAAI,CAAC,mBAAmB,GAAG,SAAS,CAAC;QACvC,CAAC;QACD,MAAM,WAAW,GAAG,MAAM,eAAe,CACvC,IAAI,CAAC,OAAO,EACZ,EAAE,GAAG,EAAE,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,eAAe,EAAE,EACzE,GAAG,EAAE,CACH,MAAM;YACJ,CAAC,CAAC,iBAAiB,CACf,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EACjC,gBAAgB,EAChB;gBACE,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE;gBAChD,+DAA+D;gBAC/D,+DAA+D;gBAC/D,wBAAwB;gBACxB,MAAM,EAAE,IAAI,CAAC,UAAU,CAAC,MAAM;aAC/B,EACD,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,yBAAyB,EAAE,CACvE;YACH,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,EACjC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CACtE,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC1B,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,+FAA+F;IACvF,OAAO,CAAC,WAA6B;QAC3C,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC;QAC1B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC9B,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,uBAAuB;YAAE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACtE,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;QACxC,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,gBAAgB,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC;IACnF,CAAC;IAED,qFAAqF;IAC7E,KAAK,CAAC,OAAO,CAAC,MAAe;QACnC,MAAM,GAAG,GAAG,MAAM,eAAe,CAAC;YAChC,OAAO,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,MAAM,EAAE,CAAC;YAClF,SAAS,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,EAAE;YAC5C,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC;YACnD,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM;YAClC,GAAG,EAAE,IAAI,CAAC,UAAU,CAAC,GAAG;SACzB,CAAC,CAAC;QACH,OAAO,kBAAkB,CAAC,GAAG,EAAE;YAC7B,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM;YAC3B,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;YACjC,eAAe,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,eAAe;SACrD,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACK,UAAU,CAAC,MAAe;QAChC,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;QACxC,OAAO,qBAAqB,CAC1B;YACE,mBAAmB,EAAE,IAAI,CAAC,OAAO,CAAC,mBAAmB;YACrD,qBAAqB,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,qBAAqB;SACxE,EACD,EAAE,UAAU,EAAE,OAAO,CAAC,YAAY,GAAG,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,CACnE,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACK,SAAS,CAAC,WAA6B;QAC7C,MAAM,OAAO,GAAG,cAAc,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACtE,IAAI,UAAU,IAAI,OAAO,EAAE,CAAC;YAC1B,IAAI,CAAC,mBAAmB,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;YACrD,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;YACvC,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;QAC9C,CAAC;QACD,IAAI,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC;QACpC,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;QACxC,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,UAAU,IAAI,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACvF,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;IACpC,CAAC;IAEO,mBAAmB,CAAC,QAA8B,EAAE,IAAa;QACvE,MAAM,GAAG,GAAG,IAAI,IAAI,QAAQ,CAAC;QAC7B,IAAI,IAAI,CAAC,aAAa,KAAK,GAAG;YAAE,OAAO;QACvC,IAAI,CAAC,aAAa,GAAG,GAAG,CAAC;QACzB,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;IACzE,CAAC;IAED,0GAA0G;IAClG,OAAO,CAAC,EAAU,EAAE,MAAwB;QAClD,IAAI,OAAiC,CAAC;QACtC,KAAK,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,IAAI,OAAO,KAAK,SAAS,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;YACzF,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9C,CAAC;QACD,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC5C,MAAM,OAAO,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;QACtG,MAAM,UAAU,GAAG,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;QACpF,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC/C,MAAM,SAAS,GAAG,kBAAkB,CAAC,UAAU,EAAE,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QACxE,OAAO,SAAS,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACjF,CAAC;CACF"}

package/dist/agent/observation.d.ts

@@ -1,7 +1,7 @@
 /** Observation capture, redaction, and model serialization. */
 import type { Observation, SemanticNode } from '../engine/surface.ts';
 import type { VisionDegradation } from '../run/steps.ts';
-import type { ExecutorNode, ExecutorPixels } from './executor.ts';
+import type { ExecutorNode, ExecutorObservation, ExecutorPixels } from './executor.ts';
 /** Why pixels the caller asked for are not part of this observation. */
 type PixelsWithheld = 'MASKING_UNPROVEN';
 export interface AgentObservation {
@@ -51,6 +51,19 @@ export declare function pixelsForModel(observation: AgentObservation, tainted: b
 } | {
     readonly withheld: VisionDegradation;
 };
+/**
+ * Roles the model can act on by id: the controls a hit-tested point resolves
+ * to, and the lines that mark a screen as one the tree can drive at all.
+ */
+export declare const INTERACTIVE_ROLES: ReadonlySet<string>;
+/**
+ * How many listed nodes the model could act on by id, read off the rendered
+ * lines. A screen with none is one the tree cannot describe (a canvas, a
+ * game, a native surface the platform exposes no semantics for), and the
+ * model needs pixels from the first turn rather than a round trip to discover
+ * that. Lives next to `formatNode` so the line grammar keeps one owner.
+ */
+export declare function interactiveNodeCount(observation: Pick<ExecutorObservation, 'text'>): number;
 /**
  * Projects the raw tree onto the executor-facing node shape: the same
  * redaction the text serialization applies, field by field, and no value at

package/dist/agent/observation.d.ts.map

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

package/dist/agent/observation.js

@@ -1,6 +1,7 @@
 /** Observation capture, redaction, and model serialization. */
 import { collapseText } from '../internal/text.js';
 import { sleep } from '../internal/time.js';
+import { sizeForModel } from './pixels.js';
 /** Appended when the node walk stopped at the observation byte budget. */
 const TRUNCATION_MARKER = '[observation truncated at the resolved observation byte limit]';
 /**
@@ -90,7 +91,47 @@ export function pixelsForModel(observation, tainted) {
     if (observation.pixels === undefined) {
         return { withheld: observation.pixelsWithheld ?? 'UNSUPPORTED_CAPABILITY' };
     }
-    return { pixels: observation.pixels };
+    // Sized here, once per observation a model receives, not per capture: the
+    // settle loop captures several times per action and only digests the bytes.
+    return { pixels: sizeForModel(observation.pixels) };
+}
+/**
+ * Roles the model can act on by id: the controls a hit-tested point resolves
+ * to, and the lines that mark a screen as one the tree can drive at all.
+ */
+export const INTERACTIVE_ROLES = new Set([
+    'button',
+    'link',
+    'textbox',
+    'searchbox',
+    'combobox',
+    'checkbox',
+    'radio',
+    'switch',
+    'tab',
+    'menuitem',
+    'menuitemcheckbox',
+    'menuitemradio',
+    'option',
+    'slider',
+    'spinbutton',
+    'treeitem',
+]);
+/**
+ * How many listed nodes the model could act on by id, read off the rendered
+ * lines. A screen with none is one the tree cannot describe (a canvas, a
+ * game, a native surface the platform exposes no semantics for), and the
+ * model needs pixels from the first turn rather than a round trip to discover
+ * that. Lives next to `formatNode` so the line grammar keeps one owner.
+ */
+export function interactiveNodeCount(observation) {
+    let count = 0;
+    for (const line of observation.text.split('\n')) {
+        const role = /^\s*#\S+ (\S+)/.exec(line)?.[1];
+        if (role !== undefined && INTERACTIVE_ROLES.has(role))
+            count += 1;
+    }
+    return count;
 }
 /**
  * Projects the raw tree onto the executor-facing node shape: the same
@@ -178,13 +219,28 @@ function formatNode(node, depth, redact, testIdAttribute) {
  * Lives next to `formatNode` so the line grammar keeps one owner.
  */
 export function observationShape(observation) {
-    return observation.text
+    const text = observation.text
         .replaceAll(/(^|\n)(\s*)#\S+/g, '$1$2')
         .replaceAll(/ \[([^\]]*)\]/g, (_match, states) => {
         const stable = states.split(' ').filter((state) => state !== 'focused');
         return stable.length === 0 ? '' : ` [${stable.join(' ')}]`;
     })
         .replaceAll(CLOCK_PATTERN, '<time>');
+    // A capture taken with pixels is shaped by them too: on a canvas, a map, or
+    // a game the tree never moves, and without the pixels every action would
+    // wait out the whole change window and then be reported as having done
+    // nothing. A digest keeps the shape a string and the comparison cheap.
+    const pixels = observation.pixels;
+    return pixels === undefined ? text : `${text}\n<pixels ${digest(pixels.data)}>`;
+}
+/** FNV-1a over the image bytes: fast, and equal frames encode to equal bytes. */
+function digest(bytes) {
+    let hash = 0x811c9dc5;
+    for (const byte of bytes) {
+        hash ^= byte;
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(16);
 }
 /** `12:05`, `0:59`, `23:59:59`: a value that changes on its own once a second or minute. */
 const CLOCK_PATTERN = /\b\d{1,2}:\d{2}(?::\d{2})?\b/g;

package/dist/agent/observation.js.map

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

package/dist/agent/operation-queue.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Call-order serialization for one step's observations and actions.
+ *
+ * An executor (or an AI SDK loop running parallel tool calls) that issues a
+ * second action before the first settles would otherwise resolve both
+ * targets against the same pre-action observation — exactly the wrong-node
+ * hazard the staleness rule exists to prevent. Queued, the second call sees
+ * the newest observation and a stale id fails loud instead of acting on the
+ * wrong node.
+ *
+ * Invariant: a queued body must never enqueue another operation itself — the
+ * inner call would wait behind its own caller and deadlock. Action bodies
+ * call the engine session directly, secret authorization never observes, and
+ * a relocation captures raw rather than through the queued observe.
+ */
+export declare class OperationQueue {
+    private chain;
+    /** Runs `body` after every operation queued before it, in call order. */
+    run<T>(body: () => Promise<T>): Promise<T>;
+}
+//# sourceMappingURL=operation-queue.d.ts.map

package/dist/agent/operation-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-queue.d.ts","sourceRoot":"","sources":["../../src/agent/operation-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAuC;IAEpD,yEAAyE;IACzE,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CASzC;CACF"}

package/dist/agent/operation-queue.js

@@ -0,0 +1,27 @@
+/**
+ * Call-order serialization for one step's observations and actions.
+ *
+ * An executor (or an AI SDK loop running parallel tool calls) that issues a
+ * second action before the first settles would otherwise resolve both
+ * targets against the same pre-action observation — exactly the wrong-node
+ * hazard the staleness rule exists to prevent. Queued, the second call sees
+ * the newest observation and a stale id fails loud instead of acting on the
+ * wrong node.
+ *
+ * Invariant: a queued body must never enqueue another operation itself — the
+ * inner call would wait behind its own caller and deadlock. Action bodies
+ * call the engine session directly, secret authorization never observes, and
+ * a relocation captures raw rather than through the queued observe.
+ */
+export class OperationQueue {
+    chain = Promise.resolve();
+    /** Runs `body` after every operation queued before it, in call order. */
+    run(body) {
+        // The chain is always already settled-to-undefined, so failures propagate
+        // to their own caller and never poison the queue.
+        const run = this.chain.then(body);
+        this.chain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+}
+//# sourceMappingURL=operation-queue.js.map

package/dist/agent/operation-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation-queue.js","sourceRoot":"","sources":["../../src/agent/operation-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,cAAc;IACjB,KAAK,GAAqB,OAAO,CAAC,OAAO,EAAE,CAAC;IAEpD,yEAAyE;IACzE,GAAG,CAAI,IAAsB;QAC3B,0EAA0E;QAC1E,kDAAkD;QAClD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,IAAI,CACnB,GAAG,EAAE,CAAC,SAAS,EACf,GAAG,EAAE,CAAC,SAAS,CAChB,CAAC;QACF,OAAO,GAAG,CAAC;IACb,CAAC;CACF"}

package/dist/agent/pixels.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The screenshot a model receives, sized for it. Engines capture at CSS or
+ * device scale; a 1280 by 720 web viewport or a 1170 by 2532 phone is more
+ * image than a model needs to place a tap, and every image pixel is paid
+ * for on every turn it stays in the conversation. The long side is capped
+ * and the image resampled, and `scale` (image pixels per CSS pixel) is
+ * reduced with it, so every coordinate a model reads off the image still
+ * maps onto the viewport through the same arithmetic. Masked regions stay
+ * masked: a box filter over black stays black.
+ */
+import type { ObservationPixels } from '../engine/surface.ts';
+/** Sizes a captured screenshot for the model; the input is returned as is when it already fits. */
+export declare function sizeForModel<P extends ObservationPixels>(pixels: P): P;
+/**
+ * Resamples the image so its longer side is at most `maxLongSide`, with a
+ * box filter over the source pixels each target pixel covers. Returns the
+ * input untouched when it already fits or cannot be decoded; whatever else
+ * the caller's pixels carry (a masked-region count) rides along unchanged.
+ */
+export declare function downscalePixels<P extends ObservationPixels>(pixels: P, maxLongSide: number): P;
+//# sourceMappingURL=pixels.d.ts.map

package/dist/agent/pixels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pixels.d.ts","sourceRoot":"","sources":["../../src/agent/pixels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAa9D,mGAAmG;AACnG,wBAAgB,YAAY,CAAC,CAAC,SAAS,iBAAiB,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAEtE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,iBAAiB,EAAE,MAAM,EAAE,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,CAAC,CAgB9F"}

package/dist/agent/pixels.js

@@ -0,0 +1,85 @@
+/**
+ * The screenshot a model receives, sized for it. Engines capture at CSS or
+ * device scale; a 1280 by 720 web viewport or a 1170 by 2532 phone is more
+ * image than a model needs to place a tap, and every image pixel is paid
+ * for on every turn it stays in the conversation. The long side is capped
+ * and the image resampled, and `scale` (image pixels per CSS pixel) is
+ * reduced with it, so every coordinate a model reads off the image still
+ * maps onto the viewport through the same arithmetic. Masked regions stay
+ * masked: a box filter over black stays black.
+ */
+import { PNG } from 'pngjs';
+/**
+ * Longest side a model-bound screenshot keeps, in image pixels. Measured on
+ * gpt-5.6 over a ten-key drawn keypad and an eight-screen drawn wizard, four
+ * runs per size: a 1280 by 720 capture costs about 1390 input tokens per
+ * turn, 1024 about 960, 768 about 680, 640 about 580, 512 about 500. Every
+ * size down to 640 passed every run; at 512 the model misread the keypad's
+ * display, needed retries, and once accepted a wrong code. 768 keeps a full
+ * step of margin above that cliff for 35% less per run than full size.
+ */
+const MAX_SCREENSHOT_LONG_SIDE = 768;
+/** Sizes a captured screenshot for the model; the input is returned as is when it already fits. */
+export function sizeForModel(pixels) {
+    return downscalePixels(pixels, MAX_SCREENSHOT_LONG_SIDE);
+}
+/**
+ * Resamples the image so its longer side is at most `maxLongSide`, with a
+ * box filter over the source pixels each target pixel covers. Returns the
+ * input untouched when it already fits or cannot be decoded; whatever else
+ * the caller's pixels carry (a masked-region count) rides along unchanged.
+ */
+export function downscalePixels(pixels, maxLongSide) {
+    const longSide = Math.max(pixels.width, pixels.height);
+    if (longSide <= maxLongSide || maxLongSide <= 0)
+        return pixels;
+    const factor = maxLongSide / longSide;
+    const width = Math.max(1, Math.round(pixels.width * factor));
+    const height = Math.max(1, Math.round(pixels.height * factor));
+    let source;
+    try {
+        source = PNG.sync.read(Buffer.from(pixels.data));
+    }
+    catch {
+        return pixels;
+    }
+    const target = new PNG({ width, height });
+    boxResample(source.data, source.width, source.height, target.data, width, height);
+    const data = new Uint8Array(PNG.sync.write(target));
+    return { ...pixels, data, width, height, scale: pixels.scale * (width / pixels.width) };
+}
+/** Averages, per channel, every source pixel a target pixel covers. RGBA, 8 bits per channel. */
+function boxResample(source, sourceWidth, sourceHeight, target, targetWidth, targetHeight) {
+    const xRatio = sourceWidth / targetWidth;
+    const yRatio = sourceHeight / targetHeight;
+    for (let ty = 0; ty < targetHeight; ty += 1) {
+        const y0 = Math.floor(ty * yRatio);
+        const y1 = Math.min(sourceHeight, Math.max(y0 + 1, Math.floor((ty + 1) * yRatio)));
+        for (let tx = 0; tx < targetWidth; tx += 1) {
+            const x0 = Math.floor(tx * xRatio);
+            const x1 = Math.min(sourceWidth, Math.max(x0 + 1, Math.floor((tx + 1) * xRatio)));
+            let r = 0;
+            let g = 0;
+            let b = 0;
+            let a = 0;
+            let count = 0;
+            for (let y = y0; y < y1; y += 1) {
+                let offset = (y * sourceWidth + x0) * 4;
+                for (let x = x0; x < x1; x += 1) {
+                    r += source[offset];
+                    g += source[offset + 1];
+                    b += source[offset + 2];
+                    a += source[offset + 3];
+                    offset += 4;
+                    count += 1;
+                }
+            }
+            const at = (ty * targetWidth + tx) * 4;
+            target[at] = Math.round(r / count);
+            target[at + 1] = Math.round(g / count);
+            target[at + 2] = Math.round(b / count);
+            target[at + 3] = Math.round(a / count);
+        }
+    }
+}
+//# sourceMappingURL=pixels.js.map