AzuTear
98 lines
3.5 KiB
TypeScript
98 lines
3.5 KiB
TypeScript
// Card-ready gating for the auto-scan loop (ADR replaces the fixed 280ms settle
|
|
// delay). After clicking a tile, instead of waiting a hardcoded interval and
|
|
// hoping the detail card has rendered, poll a cheap detail fingerprint until it
|
|
// has both (a) changed from the previously-read artifact and (b) stabilized
|
|
// across consecutive samples. This is faster on quick machines and correct on
|
|
// slow ones, and it is robust to particle/hover-glow animation: if the card
|
|
// never fully stabilizes within the budget it still proceeds once the content
|
|
// has changed, rather than looping forever on an animated frame.
|
|
//
|
|
// Pure except for the injected async sampler/clock, so it is unit testable.
|
|
|
|
export interface CardReadyOptions {
|
|
/** Consecutive equal samples required to call the card stable. */
|
|
minStableSamples?: number;
|
|
/** Total time budget before giving up on full stability. */
|
|
maxWaitMs?: number;
|
|
/** Delay between samples. */
|
|
pollIntervalMs?: number;
|
|
/** Proceed with changed-but-animated content after this much elapsed time. */
|
|
acceptChangedAfterMs?: number;
|
|
}
|
|
|
|
export interface CardReadyDeps {
|
|
/** Fast capture -> detail fingerprint. */
|
|
sampleFingerprint: () => Promise<string>;
|
|
wait: (ms: number) => Promise<void>;
|
|
now: () => number;
|
|
/** Returns a non-empty reason to abort (ESC held, stop pressed, ...). */
|
|
checkAbort?: () => Promise<string> | string;
|
|
}
|
|
|
|
export interface CardReadyResult {
|
|
/** Safe to read the full artifact: content changed (and stabilized or budget spent). */
|
|
ready: boolean;
|
|
/** The detail differs from the previously-read artifact. */
|
|
changed: boolean;
|
|
/** Reached the required number of consecutive equal samples. */
|
|
stable: boolean;
|
|
/** Latest sampled fingerprint. */
|
|
fingerprint: string;
|
|
/** Non-empty when aborted via checkAbort. */
|
|
abortReason: string;
|
|
polls: number;
|
|
}
|
|
|
|
const DEFAULT_MIN_STABLE = 2;
|
|
const DEFAULT_MAX_WAIT_MS = 900;
|
|
const DEFAULT_POLL_MS = 90;
|
|
|
|
export async function waitForCardReady(
|
|
deps: CardReadyDeps,
|
|
previousFingerprint: string,
|
|
options: CardReadyOptions = {},
|
|
): Promise<CardReadyResult> {
|
|
const minStable = Math.max(1, options.minStableSamples ?? DEFAULT_MIN_STABLE);
|
|
const maxWaitMs = Math.max(0, options.maxWaitMs ?? DEFAULT_MAX_WAIT_MS);
|
|
const pollIntervalMs = Math.max(1, options.pollIntervalMs ?? DEFAULT_POLL_MS);
|
|
const acceptChangedAfterMs = Math.max(0, options.acceptChangedAfterMs ?? maxWaitMs);
|
|
|
|
const start = deps.now();
|
|
let previousSample = "";
|
|
let stableCount = 0;
|
|
let latest = "";
|
|
let polls = 0;
|
|
|
|
for (;;) {
|
|
if (deps.checkAbort) {
|
|
const abortReason = await deps.checkAbort();
|
|
if (abortReason) {
|
|
return { ready: false, changed: false, stable: false, fingerprint: latest, abortReason, polls };
|
|
}
|
|
}
|
|
|
|
latest = await deps.sampleFingerprint();
|
|
polls++;
|
|
|
|
stableCount = latest && latest === previousSample ? stableCount + 1 : 1;
|
|
previousSample = latest;
|
|
|
|
const changed = Boolean(latest) && latest !== previousFingerprint;
|
|
const stable = stableCount >= minStable;
|
|
|
|
const elapsedMs = deps.now() - start;
|
|
|
|
if (changed && (stable || elapsedMs >= acceptChangedAfterMs)) {
|
|
return { ready: true, changed: true, stable, fingerprint: latest, abortReason: "", polls };
|
|
}
|
|
|
|
if (elapsedMs >= maxWaitMs) {
|
|
// Budget spent. Proceed if the content has at least changed, even if it is
|
|
// still animating (never fully stabilizes).
|
|
return { ready: changed, changed, stable, fingerprint: latest, abortReason: "", polls };
|
|
}
|
|
|
|
await deps.wait(pollIntervalMs);
|
|
}
|
|
}
|