Repository navigation
Expand file tree
/
Copy pathcapture-disclosure.ts
More file actions
181 lines (169 loc) · 7.22 KB
/
Copy pathcapture-disclosure.ts
File metadata and controls
181 lines (169 loc) · 7.22 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
import type { SnapshotState } from '@agent-device/kernel/snapshot';
import { systemSurfaceDisclosure } from '@agent-device/contracts/android-system-surface-disclosure';
import { iosSystemSurfaceDisclosure } from '@agent-device/contracts/ios-system-surface';
import { iosTargetActivationDisclosure } from '@agent-device/contracts/ios-target-activation';
import { formatGestureUnsettledWarning } from '@agent-device/capture-kit/post-gesture-stability';
import type { DaemonResponse } from './daemon-request.ts';
/** The capture provenance a response must be disclosed against (#2438, #2682, unsettled gestures). */
export type CaptureProvenance = Pick<
SnapshotState,
'systemSurfaceOnly' | 'iosSystemSurfaceBundleId' | 'targetActivation' | 'unsettledGesture'
>;
/**
* The foreground repair THIS request paid for, filled by the capture path only when the request
* actually captured a tree (#2682).
*
* Separate from the consumed tree on purpose. A selector read may answer from a cached or stored
* tree — that tree still describes the surface the response is about, which is what #2438 discloses
* — but a cache hit performed no device work, so it can own no repair. Stamping the repair off the
* consumed tree would tell a command "you found the session app out of foreground" when it never
* looked, which is a fabricated observation rather than a disclosure.
*/
export type RequestActivationProof = {
state?: CaptureProvenance;
};
/**
* Note the repair a capture paid for, and hand that capture back. First fact wins: a later capture in
* the same request that reports no repair — a sparse recovery's fresh tree, a poll's fact-less read —
* cannot erase the capture that did (#2682). One rule, because three capture paths owe it and a
* hand-copied condition drifts from the other two the moment one of them learns something.
*/
export function recordActivationProof<T extends CaptureProvenance>(
proof: RequestActivationProof | undefined,
snapshot: T,
): T {
if (proof !== undefined && proof.state === undefined && snapshot.targetActivation !== undefined) {
proof.state = snapshot;
}
return snapshot;
}
/**
* Append the occluding-system-surface disclosure to a selector-route response whose consumed
* snapshot was a system surface: an Android notification shade / quick settings, or an iOS in-place
* system sheet such as web sign-in or Apple Pay (#2438). Both found and not-found outcomes must
* explain that app content is occluded: a match found inside the surface is not app content, and a
* miss is expected while the surface covers the app.
*/
export function withSystemSurfaceDisclosure(
response: DaemonResponse,
snapshot: CaptureProvenance | undefined,
): DaemonResponse {
const disclosure = snapshot?.iosSystemSurfaceBundleId
? iosSystemSurfaceDisclosure(snapshot.iosSystemSurfaceBundleId)
: systemSurfaceDisclosure(snapshot);
return disclosure ? appendDisclosure(response, disclosure, 'warning') : response;
}
/**
* Disclose a fact about the whole answered tree (#2682 foreground repair, an unsettled gesture). Its
* sentence is APPENDED, never replacing an earlier warning, and the typed fact lands on either
* outcome (`data` or `error.details`) even when the sentence was already carried.
*/
function withTreeFactDisclosure<K extends 'targetActivation' | 'unsettledGesture'>(
response: DaemonResponse,
key: K,
fact: CaptureProvenance[K],
sentence: (fact: NonNullable<CaptureProvenance[K]>) => string,
): DaemonResponse {
if (!fact) return response;
const disclosed = appendDisclosure(response, sentence(fact), 'warnings');
return disclosed.ok
? { ...disclosed, data: { ...disclosed.data, [key]: fact } }
: {
...disclosed,
error: { ...disclosed.error, details: { ...disclosed.error.details, [key]: fact } },
};
}
export function withTargetActivationDisclosure(
response: DaemonResponse,
snapshot: CaptureProvenance | undefined,
): DaemonResponse {
return withTreeFactDisclosure(
response,
'targetActivation',
snapshot?.targetActivation,
iosTargetActivationDisclosure,
);
}
/**
* Every capture-provenance disclosure a response owes, from the two different things a capture can
* prove: what the answered tree describes (#2438 — cache tiers included, because the surface is
* still on screen) and what this request's own capture found (#2682 — cache hits excluded, because
* a request that captured nothing repaired nothing).
*/
export function withCaptureDisclosures(params: {
response: DaemonResponse;
consumedTree: CaptureProvenance | undefined;
activationProof?: RequestActivationProof;
}): DaemonResponse {
const { response, consumedTree, activationProof } = params;
return withTargetActivationDisclosure(
withTreeFactDisclosure(
withSystemSurfaceDisclosure(response, consumedTree),
'unsettledGesture',
consumedTree?.unsettledGesture,
formatGestureUnsettledWarning,
),
activationProof?.state,
);
}
/**
* Which success-side field a disclosure enters. #2438's surface sentence shipped on the singular
* `warning`; the repair sentence ships on the `warnings` array beside the typed fact that travels
* with it. Failure has one carrier for both: `error.details.hint`.
*/
type DisclosureCarrier = 'warning' | 'warnings';
/**
* The ONE gate every disclosure passes before it enters a response, whichever carrier that response
* uses. Routes nest — a failing `get text` under a repairing capture passes through the wrapper twice,
* once in the selector route and once in the interaction route — so a wrapper that spoke
* unconditionally would say it twice. Equality is on a sentence this module owns, never a text sniff:
* a response already carrying it comes back untouched.
*/
function appendDisclosure(
response: DaemonResponse,
disclosure: string,
carrier: DisclosureCarrier,
): DaemonResponse {
if (carriesDisclosure(response, disclosure)) return response;
if (!response.ok) {
const details = response.error.details ?? {};
return {
...response,
error: {
...response.error,
details: { ...details, hint: appended(details.hint, disclosure) },
},
};
}
if (carrier === 'warnings') {
return {
...response,
data: {
...response.data,
warnings: [...responseWarnings(response.data?.warnings), disclosure],
},
};
}
return {
...response,
data: { ...response.data, warning: appended(response.data?.warning, disclosure) },
};
}
/**
* Every text a disclosure could already sit in, so a sentence spoken by an inner route cannot be
* spoken again by the wrapper around it.
*/
function carriesDisclosure(response: DaemonResponse, disclosure: string): boolean {
const carriers: unknown[] = response.ok
? [response.data?.warning, ...responseWarnings(response.data?.warnings)]
: [response.error.details?.hint];
return carriers.some((carrier) => typeof carrier === 'string' && carrier.includes(disclosure));
}
function appended(existing: unknown, disclosure: string): string {
return typeof existing === 'string' && existing.trim() !== ''
? `${existing}\n${disclosure}`
: disclosure;
}
function responseWarnings(value: unknown): string[] {
return Array.isArray(value) ? value.filter((entry): entry is string => entry !== undefined) : [];
}