import type { ScrollMovementObservation } from '@agent-device/contracts/scroll-command';

import type { ScrollDirection } from '@agent-device/contracts/scroll-gesture';

import type { SnapshotResult } from '@agent-device/contracts/interactor-types';

import type { CommandFlags } from '@agent-device/contracts/command';

import { isMobilePlatform, type DeviceInfo } from '@agent-device/kernel/device';

import { buildSnapshotState } from '@agent-device/capture-kit/snapshot-state';

import {

readScrollEdgeState,

scrollNoProgressHint,

verticalEdgeFor,

type ScrollEdge,

} from '@agent-device/capture-kit/scroll-edge-state';

import { containsPoint } from '@agent-device/kernel/rect';

import { AppError } from '@agent-device/kernel/errors';

import type { Point, Rect, SnapshotState } from '@agent-device/kernel/snapshot';

import { emitDiagnostic } from '@agent-device/host-kit/diagnostics';

import { observeUntil, type ObservationSchedule } from '@agent-device/capture-kit/observe-until';

import {

areInteractionSurfaceSignaturesStable,

buildInteractionSurfaceSignature,

classifyBaselineSurfaceEvidence,

discriminatingSurfaceChangedWithinRect,

haveIdenticalDiscriminatingSurfaces,

snapshotSurfaceComparisonKey,

summarizeDiscriminatingSurfaceDivergence,

type InteractionSurfaceChange,

type InteractionSurfaceSignature,

} from './interaction-outcome-policy.ts';

import { refFrameState } from './ref-frame.ts';

import { isPostGestureStabilizationPending } from './deferred-interaction-outcome.ts';

import type { SessionState } from './session-state.ts';

/**

* What one directional scroll saw after its gesture, and the only thing that can back the distance

* the same response reports (#2714).

*

* `scroll <direction>` used to answer with the travel its gesture plan had computed. That number

* describes the swipe that was dispatched, not the content that moved, so a scroll whose gesture

* never reached the container reported success with a distance — repeatedly, on every retry, until a

* later assertion failed for a reason no log explained. This module reads the difference the command

* can actually observe: the tree the session already held before the gesture, and one tree after it.

*

* The evidence rules are not a second opinion on that pair. The signature, the subset-tolerant

* baseline classifier, and the strict no-effect bar all belong to

* `interaction-outcome-policy.ts`, the same comparators the deferred post-gesture stabilization

* applies to every other gesture, so "that scroll did nothing" means one thing in this daemon.

* What is new here is only WHEN the answer is owed: a directional scroll pays one capture to gate its

* own reply instead of leaving the proof to the next command's snapshot.

*

* The shape of the loop is the mirror image of that stabilization: a surface that differs from the

* baseline is answered on the first capture, so a scroll that worked pays nothing extra; only a

* surface that looks untouched keeps polling (a mid-flight or stale read is indistinguishable from a

* no-op until it either moves or goes quiet), and only an untouched surface at rest is ever reported.

* The one exception is a baseline that already ended in the scrolled direction: there a differing

* first read is an overscroll bounce until it holds still (`baselineEndsInDirection`).

*

* Nothing is classified before the two trees are established to be two views of one screen, and that

* gate runs on every capture rather than only on the quiet path. The deferred loop can adopt a new

* producer when a capture lineage changes under it and keep going, because its question is whether the

* surface ever settles; this one compares against a pre-gesture tree, so a pair from different

* lineages can never answer either way and the claim is withheld rather than re-based.

*/

/** How long a scroll keeps asking whether an untouched surface is really untouched (#1542's window). */

const SCROLL_MOVEMENT_SCHEDULE: ObservationSchedule = {

intervalMs: 200,

budgetMs: 1_500,

captureDeadline: 'cancel',

};

/** The pre-gesture surface, already in hand: no capture is spent to produce it. */

export type ScrollSurfaceBaseline = Readonly<{

signature: InteractionSurfaceSignature;

presentationKey: string | undefined;

comparisonKey: string | undefined;

/** The tree itself: whether the content already ended in the scrolled direction is asked of nodes. */

nodes: SnapshotState['nodes'];

}>;

/** Why there is nothing honest to compare this scroll's effect against. */

export type ScrollSurfaceBaselineAbsence =

| 'stored-surface-unusable'

| 'stored-surface-not-current'

| 'prior-gesture-unsettled';

/** Why this command owes no observation of its own effect. A reason, never text to match. */

export type ScrollMovementInapplicability =

| 'owner-without-capture'

| 'non-swipe-platform'

| 'caller-declined-observation'

| 'settle-observer-owns-outcome';

/**

* Everything about this scroll's observation that is knowable before it dispatches, decided once, in

* one place: whether the command owes the read at all, and what it gets to compare against.

*

* The declines are the device's and the caller's — a platform that moves content with a wheel or a JS

* step instead of a synthesized swipe, a caller that pays for its own observation (Maestro's replay

* loop), and `--settle`, which freezes its own baseline and already answers whether the surface

* moved. Whether the bound runtime can read a screen at all is the one fact not knowable here, since

* binding happens after this returns; that owner reports its own `owner-without-capture`.

*/

export type ScrollMovementPlan =

| Readonly<{

kind: 'declined';

reason: Exclude<ScrollMovementInapplicability, 'owner-without-capture'>;

}>

| Readonly<{ kind: 'unobservable'; reason: ScrollSurfaceBaselineAbsence }>

| Readonly<{ kind: 'observe'; baseline: ScrollSurfaceBaseline }>;

export function planScrollMovement(params: {

device: DeviceInfo;

flags: CommandFlags | undefined;

session: SessionState;

}): ScrollMovementPlan {

if (!isMobilePlatform(params.device)) return { kind: 'declined', reason: 'non-swipe-platform' };

if (params.flags?.postGestureStabilization === false) {

return { kind: 'declined', reason: 'caller-declined-observation' };

}

if (params.flags?.settle === true) {

return { kind: 'declined', reason: 'settle-observer-owns-outcome' };

}

return freezeScrollSurfaceBaseline(params.session);

}

/** Where the swipe ran, so a container elsewhere on the screen cannot be blamed for the no-op. */

export type ScrollSwipeEvidence = Readonly<{

/** Midpoint of the dispatched gesture, in the same space as a snapshot rect. */

midpoint?: Point;

/** The travel the gesture plan produced, reported on the refusal. */

pixels?: number;

}>;

export function readScrollSurfaceBaseline(

snapshot: SnapshotState | undefined,

): ScrollSurfaceBaseline | undefined {

if (!snapshot || snapshot.nodes.length === 0) return undefined;

const signature = buildInteractionSurfaceSignature(snapshot.nodes);

if (signature.length === 0) return undefined;

return {

signature,

presentationKey: snapshot.presentationKey,

comparisonKey: snapshotSurfaceComparisonKey(snapshot),

nodes: snapshot.nodes,

};

}

/**

* Freezes what a directional scroll can compare its own effect against, at the one moment that

* answer is available: before the command dispatches.

*

* The tree the session stores is not automatically the screen as it stands — a mutation may have

* happened since it was captured, and its own gesture is about to be another one. ADR 0014 already

* encodes exactly that question: the ref frame stays `active` while no device side effect has

* crossed since the last publication, which is while the stored tree still is the newest

* observation. Anything else and there is nothing honest to compare against, so this names the reason

* instead of letting a stale tree back a movement claim (#2714).

*/

function freezeScrollSurfaceBaseline(session: SessionState): ScrollMovementPlan {

const baseline = readScrollSurfaceBaseline(session.snapshot);

if (!baseline) return { kind: 'unobservable', reason: 'stored-surface-unusable' };

if (refFrameState(session) !== 'active') {

return { kind: 'unobservable', reason: 'stored-surface-not-current' };

}

if (isPostGestureStabilizationPending(session)) {

// A gesture nobody has read yet may still be moving this tree, which would bill its motion to

// the scroll being dispatched now.

return { kind: 'unobservable', reason: 'prior-gesture-unsettled' };

}

return { kind: 'observe', baseline };

}

/**

* Observes one directional scroll and returns the movement its response may claim.

*

* Throws `scroll_no_progress` when it proves the gesture did not land: the surface is byte-for-byte

* what it was, the tree still names hidden content in the direction that was scrolled, and the swipe

* ran inside that container. Every other untouched surface answers honestly instead — at the edge of

* the content, in a direction with no end-of-content signal, or as `unobserved` when the evidence

* would not support the claim either way.

*

* A capture that fails does not fail the scroll: the gesture already happened, so an unreadable tree

* answers `unobserved` and leaves the caller's scroll succeeded.

*/

export async function observeScrollMovement(params: {

direction: ScrollDirection;

baseline: ScrollSurfaceBaseline;

swipe: ScrollSwipeEvidence;

capture: () => Promise<SnapshotResult>;

/** The same two overrides `pollForScrollRest` takes: how long to ask, and how often. */

budgetMs?: number;

pollMs?: number;

}): Promise<ScrollMovementObservation> {

const { direction, baseline, swipe } = params;

const verdict = await pollForSurfaceVerdict(baseline, params);

switch (verdict.kind) {

case 'moved':

return await claimMoved({ ...verdict, direction, baseline, swipe });

case 'blind':

return reportScrollMovementUnobserved(direction, verdict.reason, { swipe });

case 'settled':

return await decideUnchanged({ ...verdict, direction, baseline, swipe });

}

}

/** What the polling could say about the surface, before any of it is interpreted. */

type SurfaceVerdict =

| Readonly<{

kind: 'moved';

observed: ObservedSurface;

attempts: number;

startedAt: number;

}>

| Readonly<{ kind: 'blind'; reason: SurfaceBlindReason }>

| Readonly<{

kind: 'settled';

observed: ObservedSurface;

evidence: InteractionSurfaceChange;

attempts: number;

startedAt: number;

}>;

/** What one capture's verdict decides, before the loop's own timing is stitched back on. */

type SurfaceJudgement =

| Readonly<{ kind: 'blind'; reason: SurfaceBlindReason }>

| Readonly<{ kind: 'moved'; observed: ObservedSurface }>

| Readonly<{ kind: 'settled'; observed: ObservedSurface; evidence: InteractionSurfaceChange }>;

/** Why this capture cannot be compared against the pre-gesture tree at all, movement included. */

type SurfaceBlindReason = 'capture-unreadable' | 'surface-unsettled' | ScrollSurfacePairDrift;

/**

* Whether two captures describe one screen. Capture backends do not agree on which nodes exist, so a

* pair across a lineage change — the XCTest-channel fallback swapping the producer mid-request

* (#1569) — or across the interactive-only difference `snapshot -i` stores says nothing about

* movement in either direction, however different the two trees look.

*/

type ScrollSurfacePairDrift = 'baseline-presentation-drift' | 'capture-lineage-drift';

function surfacePairDrift(

baseline: ScrollSurfaceBaseline,

observed: ObservedSurface,

): ScrollSurfacePairDrift | undefined {

if (baseline.presentationKey !== observed.presentationKey) return 'baseline-presentation-drift';

if (baseline.comparisonKey !== observed.comparisonKey) return 'capture-lineage-drift';

return undefined;

}

/**

* Polls until an untouched surface proves itself. A surface that differs from the baseline is a

* verdict on the first capture, so a scroll that worked pays for one read, unless the baseline

* already ended in the scrolled direction, where the change must hold still first

* (`baselineEndsInDirection`). One that looks untouched

* needs a quiet pair, because a gesture still in flight and a gesture that did nothing answer a

* single read identically. A surface that never holds still expires as `surface-unsettled` rather

* than being called a no-op — and that answer is worth a warning the others are not, since it spent

* the whole budget confirming nothing.

*/

async function pollForSurfaceVerdict(

baseline: ScrollSurfaceBaseline,

params: {

direction: ScrollDirection;

capture: () => Promise<SnapshotResult>;

budgetMs?: number;

pollMs?: number;

swipe: ScrollSwipeEvidence;

},

): Promise<SurfaceVerdict> {

// The edge question is asked only of the pre-gesture (baseline) tree, so it never depends on a

// poll's outcome and can be answered once, before the loop starts, rather than lazily on the

// first `changed` reading.

const changeNeedsRest = await baselineEndsInDirection(baseline, params.direction, params.swipe);

let previous: InteractionSurfaceSignature | undefined;

const observed = await observeUntil<CaptureReading, SurfaceJudgement>({

capture: () => readOneCapture(baseline, params.capture),

schedule: {

intervalMs: params.pollMs ?? SCROLL_MOVEMENT_SCHEDULE.intervalMs,

budgetMs: params.budgetMs ?? SCROLL_MOVEMENT_SCHEDULE.budgetMs,

captureDeadline: SCROLL_MOVEMENT_SCHEDULE.captureDeadline,

},

verdict: (latest) => {

if (latest.kind === 'blind')

return { kind: 'done', result: { kind: 'blind', reason: latest.reason } };

const judged = settledVerdict(latest, { previous, changeNeedsRest });

previous = latest.observed.signature;

return judged ? { kind: 'done', result: judged } : { kind: 'continue' };

},

});

const attempts = observed.polls.length;

const startedAt = Date.now() - observed.waitedMs;

if (observed.kind !== 'done') return budgetExpiredVerdict(params, attempts, startedAt);

return observed.result.kind === 'blind'

? observed.result

: { ...observed.result, attempts, startedAt };

}

/**

* The verdict one readable capture supports, or nothing yet. A changed surface is movement on sight

* unless the baseline already ended in that direction, where it must hold still first; an unchanged

* surface is settled only as the second of a quiet pair.

*/

function settledVerdict(

reading: Exclude<CaptureReading, { kind: 'blind' }>,

poll: {

previous: InteractionSurfaceSignature | undefined;

changeNeedsRest: boolean;

},

): SurfaceJudgement | undefined {

const atRest = surfaceIsAtRest(poll.previous, reading.observed.signature);

if (reading.kind === 'changed') {

if (!poll.changeNeedsRest || atRest) {

return { kind: 'moved', observed: reading.observed };

}

return undefined;

}

if (!atRest) return undefined;

return { kind: 'settled', observed: reading.observed, evidence: reading.evidence };

}

/**

* Whether the pre-gesture tree already showed the end of the content in the scrolled direction. A

* scroll past that edge on iOS rubber-bands: the first capture lands mid-bounce with every row shifted

* by a few points and reads as `changed`, then the content springs back to exactly the baseline, which

* is what the next command's stabilization later observes as a stale-accept (#2884). So a change against

* a baseline that had nothing left to reveal is credited only once the surface holds still and still

* differs; a scroll whose baseline still hid content keeps paying one read.

*/

async function baselineEndsInDirection(

baseline: ScrollSurfaceBaseline,

direction: ScrollDirection,

swipe: ScrollSwipeEvidence,

): Promise<boolean> {

const edge = verticalEdgeFor(direction);

if (!edge) return false;

// The question is asked of the scroller the swipe ran in, through the selection the edge verdict

// uses: among the containers holding the point, the one that still hides content in that

// direction. An inner list at its end inside an outer list with more below hands the gesture to

// the outer list, so the outer list's edge is what gates the claim.

const state = await readScrollEdgeState(baseline.nodes, edge, { point: swipe.midpoint });

const ends = state.containerRect !== undefined && !state.canScroll;

if (ends) {

emitDiagnostic({

level: 'debug',

phase: 'scroll_movement_edge_rest_required',

data: { direction, containerRect: state.containerRect },

});

}

return ends;

}

/**

* What a single capture says, on its own: nothing at all when the tree could not be read or comes from

* another lineage, movement when the surface differs from the baseline, and otherwise the untouched

* pair the loop has to prove is at rest before it can be reported.

*/

type CaptureReading =

| Readonly<{ kind: 'blind'; reason: SurfaceBlindReason }>

| Readonly<{ kind: 'changed'; observed: ObservedSurface }>

| Readonly<{ kind: 'unchanged'; observed: ObservedSurface; evidence: InteractionSurfaceChange }>;

async function readOneCapture(

baseline: ScrollSurfaceBaseline,

capture: () => Promise<SnapshotResult>,

): Promise<CaptureReading> {

const observed = await captureSurface(capture);

if (!observed) return { kind: 'blind', reason: 'capture-unreadable' };

const drift = surfacePairDrift(baseline, observed);

if (drift) return { kind: 'blind', reason: drift };

const evidence = classifyBaselineSurfaceEvidence(baseline.signature, observed.signature);

if (evidence === 'changed') return { kind: 'changed', observed };

return { kind: 'unchanged', observed, evidence };

}

/**

* The surface never held still, so this command spent its whole budget confirming nothing. That answer

* is worth a warning the others are not: it is also the one that cost the caller the most.

*/

function budgetExpiredVerdict(

params: {

direction: ScrollDirection;

swipe: ScrollSwipeEvidence;

},

attempts: number,

startedAt: number,

): SurfaceVerdict {

emitDiagnostic({

level: 'warn',

phase: 'scroll_movement_budget_expired',

data: {

direction: params.direction,

attempts,

durationMs: Date.now() - startedAt,

...(params.swipe.pixels === undefined ? {} : { requestedPixels: params.swipe.pixels }),

},

});

return { kind: 'blind', reason: 'surface-unsettled' };

}

function surfaceIsAtRest(

previous: InteractionSurfaceSignature | undefined,

next: InteractionSurfaceSignature,

): boolean {

return previous !== undefined && areInteractionSurfaceSignaturesStable(previous, next);

}

type ObservedSurface = Readonly<{

signature: InteractionSurfaceSignature;

presentationKey: string | undefined;

comparisonKey: string | undefined;

/** The tree itself: the edge question is asked of nodes, not of the identity signature. */

nodes: SnapshotState['nodes'];

}>;

async function captureSurface(

capture: () => Promise<SnapshotResult>,

): Promise<ObservedSurface | undefined> {

let result: SnapshotResult;

try {

result = await capture();

} catch {

// The gesture is already done; a tree this command cannot read withholds the claim, it does not

// undo the scroll.

return undefined;

}

const state = buildSnapshotState(result, undefined);

return {

signature: buildInteractionSurfaceSignature(state.nodes),

presentationKey: state.presentationKey,

comparisonKey: snapshotSurfaceComparisonKey(state),

nodes: state.nodes,

};

}

/**

* A changed surface credits the gesture only when the change sits inside the scroller the swipe ran

* in. The captured tree carries system chrome along with the app's content, and on Android the status

* bar clocks and icons change on their own while a frozen list sits underneath them — measured on the

* tester's `/catalog`, a battery icon alone turned the pair into "changed" over a list that never

* moved. Without a container to confine the claim to (no scroller resolved, or the horizontal axis the

* analyzer does not read) the whole-surface difference is all there is, and stays the answer.

*/

async function claimMoved(params: {

direction: ScrollDirection;

baseline: ScrollSurfaceBaseline;

swipe: ScrollSwipeEvidence;

observed: ObservedSurface;

attempts: number;

startedAt: number;

}): Promise<ScrollMovementObservation> {

const { direction, baseline, swipe, observed } = params;

const edge = verticalEdgeFor(direction);

const containerRect = edge

? (await readScrollEdgeState(observed.nodes, edge)).containerRect

: undefined;

if (

containerRect &&

!discriminatingSurfaceChangedWithinRect(baseline.signature, observed.signature, containerRect)

) {

return reportScrollMovementUnobserved(direction, 'change-outside-container', {

swipe,

containerRect,

});

}

return reportObserved(direction, 'moved', swipe, params.attempts, params.startedAt);

}

async function decideUnchanged(params: {

direction: ScrollDirection;

baseline: ScrollSurfaceBaseline;

swipe: ScrollSwipeEvidence;

observed: ObservedSurface;

evidence: InteractionSurfaceChange;

attempts: number;

startedAt: number;

}): Promise<ScrollMovementObservation> {

const { direction, baseline, observed, evidence, swipe } = params;

const comparison = settledPairBlindness(baseline, observed, evidence);

if (comparison)

return reportScrollMovementUnobserved(direction, comparison.reason, {

swipe,

divergence: comparison.divergence,

});

return await decideEdgeVerdict(params);

}

type SurfaceComparison = Readonly<{

reason: 'no-comparable-content' | 'surface-divergence';

divergence?: Record<string, unknown>;

}>;

/**

* What a pair already known comparable still cannot say about being untouched. The subset-tolerant

* classifier is 'unchanged' for a narrower capture of the same screen, so the no-effect claim needs

* the strict both-directions bar (#1601 review P1): a scroll that replaced every list cell under

* fixed chrome must not be readable as a gesture that did nothing.

*/

function settledPairBlindness(

baseline: ScrollSurfaceBaseline,

observed: ObservedSurface,

evidence: InteractionSurfaceChange,

): SurfaceComparison | undefined {

if (evidence === 'ambiguous') return { reason: 'no-comparable-content' };

if (!haveIdenticalDiscriminatingSurfaces(baseline.signature, observed.signature)) {

return {

reason: 'surface-divergence',

divergence: summarizeDiscriminatingSurfaceDivergence(baseline.signature, observed.signature),

};

}

return undefined;

}

/** What an untouched surface is: the end of the content, a direction with no edge to read, or a gesture that never landed. */

async function decideEdgeVerdict(params: {

direction: ScrollDirection;

swipe: ScrollSwipeEvidence;

observed: ObservedSurface;

attempts: number;

startedAt: number;

}): Promise<ScrollMovementObservation> {

const { direction, observed, swipe } = params;

const edge = verticalEdgeFor(direction);

if (!edge) {

// The hidden-content analyzer reads the vertical axis only, so a horizontal scroll that moved

// nothing cannot tell a pager at its end from a list that ignored the swipe. It reports what it

// measured and leaves the two apart, rather than guessing.

return reportObserved(direction, 'unchanged', swipe, params.attempts, params.startedAt);

}

const edgeState = await readScrollEdgeState(observed.nodes, edge);

const containerRect = edgeState.containerRect;

if (!containerRect) {

// `canScroll: false` here means the tree named no scroll container at all, which says nothing

// about where the content ends.

return reportScrollMovementUnobserved(direction, 'no-scroll-container', { swipe });

}

if (swipe.midpoint && !containerHoldsSwipe(containerRect, swipe.midpoint)) {

return reportScrollMovementUnobserved(direction, 'container-outside-swipe', {

swipe,

containerRect,

});

}

if (edgeState.canScroll) {

throw scrollNoProgressError(direction, edge, swipe, containerRect);

}

return reportObserved(direction, 'at-edge', swipe, params.attempts, params.startedAt);

}

function containerHoldsSwipe(containerRect: Rect, midpoint: Point): boolean {

return containsPoint(containerRect, midpoint.x, midpoint.y);

}

/**

* The gesture did not reach the container: hidden content is still there, and the surface never

* moved. Same typed family as `scroll_edge_no_progress` and `scroll_until_no_progress`, and the same

* hint, because the caller's next move is the same whichever loop noticed.

*/

function scrollNoProgressError(

direction: ScrollDirection,

edge: ScrollEdge,

swipe: ScrollSwipeEvidence,

containerRect: Rect,

): AppError {

return new AppError(

'COMMAND_FAILED',

`scroll ${direction} moved nothing: the container still reports hidden content ${

edge === 'bottom' ? 'below' : 'above'

} and its contents never shifted`,

{

reason: 'scroll_no_progress',

direction,

hiddenContentAt: edge,

containerRect,

...(swipe.pixels === undefined ? {} : { requestedPixels: swipe.pixels }),

hint: scrollNoProgressHint({

targetDirectly: `with scroll ${direction} --until <selector>`,

rawDrag: swipe.midpoint !== undefined,

}),

},

);

}

/**

* Why a scroll that owed an observation could not make one: no usable baseline before the gesture, no

* readable or settled tree after it, or a pair that turned out not to be comparable. A reason, never

* text a caller has to match.

*/

export type ScrollMovementUnobservedReason =

| ScrollSurfaceBaselineAbsence

| SurfaceBlindReason

| 'no-comparable-content'

| 'surface-divergence'

| 'no-scroll-container'

| 'container-outside-swipe'

| 'change-outside-container';

/** What accompanies the reason in the daemon log, so one line explains the whole verdict. */

export type ScrollMovementUnobservedEvidence = Readonly<{

swipe: ScrollSwipeEvidence;

/** What the two surfaces disagreed on, for a `surface-divergence`. */

divergence?: Record<string, unknown>;

/** The scroll container the edge analyzer resolved, when it resolved one. */

containerRect?: Rect;

}>;

/**

* Tells the daemon log that this command owed no observation at all — the owner cannot read a

* screen, the device has no swipe to verify, or the caller (or another observer) already declined

* or owns that read. The response carries no `movement` field, so the reason has to live somewhere.

*/

export function reportScrollMovementNotApplicable(

direction: ScrollDirection,

reason: ScrollMovementInapplicability,

): void {

emitDiagnostic({

level: 'debug',

phase: 'scroll_movement_not_applicable',

data: { direction, reason },

});

}

/**

* Records why a scroll that DID owe an observation could not make one, and answers `unobserved`: the

* distance it reports then rests on the gesture plan alone.

*/

export function reportScrollMovementUnobserved(

direction: ScrollDirection,

reason: ScrollMovementUnobservedReason,

evidence: ScrollMovementUnobservedEvidence,

): ScrollMovementObservation {

emitDiagnostic({

level: 'info',

phase: 'scroll_movement_unobserved',

data: {

direction,

reason,

...(evidence.swipe.pixels === undefined ? {} : { requestedPixels: evidence.swipe.pixels }),

...(evidence.divergence ?? {}),

...(evidence.containerRect === undefined ? {} : { containerRect: evidence.containerRect }),

},

});

return 'unobserved';

}

function reportObserved(

direction: ScrollDirection,

movement: Exclude<ScrollMovementObservation, 'unobserved'>,

swipe: ScrollSwipeEvidence,

attempts: number,

startedAt: number,

): ScrollMovementObservation {

emitDiagnostic({

level: movement === 'moved' ? 'debug' : 'info',

phase: 'scroll_movement_observed',

data: {

direction,

movement,

attempts,

durationMs: Date.now() - startedAt,

...(swipe.pixels === undefined ? {} : { requestedPixels: swipe.pixels }),

},

});

return movement;

}