|
| 1 | +import type { ScreenshotOverlayRef } from '@agent-device/kernel/snapshot'; |
| 2 | + |
| 3 | +/** |
| 4 | + * The typed `details.androidSnapshotTimeoutScreenshot` payload published when an accessibility |
| 5 | + * snapshot times out and the daemon falls back to a screenshot (#1983). |
| 6 | + * |
| 7 | + * The shape is a discriminated union rather than a bag of optional fields because each arm is a |
| 8 | + * different claim about what evidence exists: no capture at all, a capture with no snapshot to |
| 9 | + * annotate from, a capture annotated with overlay refs, or a capture whose annotation failed. |
| 10 | + * Callers construct it through the builders below so an assembly site cannot publish a fifth, |
| 11 | + * undeclared arm. |
| 12 | + */ |
| 13 | +type CapturedSnapshotTimeoutEvidenceBase = { |
| 14 | + path: string; |
| 15 | + overlayRefsRequested: true; |
| 16 | +}; |
| 17 | + |
| 18 | +export type SnapshotTimeoutEvidence = |
| 19 | + | { |
| 20 | + captureFailed: true; |
| 21 | + error: string; |
| 22 | + } |
| 23 | + | (CapturedSnapshotTimeoutEvidenceBase & { |
| 24 | + overlayRefSource: 'unavailable'; |
| 25 | + overlayRefsAnnotated: false; |
| 26 | + overlayRefCount: 0; |
| 27 | + }) |
| 28 | + | (CapturedSnapshotTimeoutEvidenceBase & { |
| 29 | + overlayRefSource: 'session-snapshot'; |
| 30 | + overlayRefsAnnotated: boolean; |
| 31 | + overlayRefCount: number; |
| 32 | + overlayRefs: ScreenshotOverlayRef[]; |
| 33 | + }) |
| 34 | + | (CapturedSnapshotTimeoutEvidenceBase & { |
| 35 | + overlayRefSource: 'session-snapshot'; |
| 36 | + overlayRefsAnnotated: false; |
| 37 | + overlayRefCount: 0; |
| 38 | + overlayAnnotationError: string; |
| 39 | + }); |
| 40 | + |
| 41 | +/** No screenshot was taken: the evidence path itself failed. */ |
| 42 | +export function snapshotTimeoutCaptureFailed(error: string): SnapshotTimeoutEvidence { |
| 43 | + return { captureFailed: true, error }; |
| 44 | +} |
| 45 | + |
| 46 | +/** A screenshot exists, but no stored observation was available to derive overlay refs from. */ |
| 47 | +export function snapshotTimeoutEvidenceWithoutOverlaySource(path: string): SnapshotTimeoutEvidence { |
| 48 | + return { |
| 49 | + path, |
| 50 | + overlayRefsRequested: true, |
| 51 | + overlayRefsAnnotated: false, |
| 52 | + overlayRefSource: 'unavailable', |
| 53 | + overlayRefCount: 0, |
| 54 | + }; |
| 55 | +} |
| 56 | + |
| 57 | +/** A screenshot annotated from the stored observation. An empty ref list is not an annotation. */ |
| 58 | +export function snapshotTimeoutEvidenceWithOverlayRefs( |
| 59 | + path: string, |
| 60 | + overlayRefs: ScreenshotOverlayRef[], |
| 61 | +): SnapshotTimeoutEvidence { |
| 62 | + return { |
| 63 | + path, |
| 64 | + overlayRefsRequested: true, |
| 65 | + overlayRefsAnnotated: overlayRefs.length > 0, |
| 66 | + overlayRefCount: overlayRefs.length, |
| 67 | + overlayRefSource: 'session-snapshot', |
| 68 | + overlayRefs, |
| 69 | + }; |
| 70 | +} |
| 71 | + |
| 72 | +/** A screenshot exists and a stored observation existed, but annotating it threw. */ |
| 73 | +export function snapshotTimeoutEvidenceOverlayFailed( |
| 74 | + path: string, |
| 75 | + overlayAnnotationError: string, |
| 76 | +): SnapshotTimeoutEvidence { |
| 77 | + return { |
| 78 | + path, |
| 79 | + overlayRefsRequested: true, |
| 80 | + overlayRefsAnnotated: false, |
| 81 | + overlayRefSource: 'session-snapshot', |
| 82 | + overlayRefCount: 0, |
| 83 | + overlayAnnotationError, |
| 84 | + }; |
| 85 | +} |
| 86 | + |
| 87 | +/** |
| 88 | + * The overlay counts a diagnostic may report, narrowed off the union so a log site does not |
| 89 | + * re-derive the arm discrimination with `in` checks. |
| 90 | + */ |
| 91 | +export function snapshotTimeoutEvidenceOverlayCounts(evidence: SnapshotTimeoutEvidence): { |
| 92 | + overlayRefCount: number | undefined; |
| 93 | + overlayRefsAnnotated: boolean | undefined; |
| 94 | +} { |
| 95 | + return 'captureFailed' in evidence |
| 96 | + ? { overlayRefCount: undefined, overlayRefsAnnotated: undefined } |
| 97 | + : { |
| 98 | + overlayRefCount: evidence.overlayRefCount, |
| 99 | + overlayRefsAnnotated: evidence.overlayRefsAnnotated, |
| 100 | + }; |
| 101 | +} |
0 commit comments