@descryy/mcp 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (260) hide show
  1. package/dist/action-handshake.d.ts +8 -75
  2. package/dist/action-handshake.d.ts.map +1 -1
  3. package/dist/action-handshake.js +9 -79
  4. package/dist/action-handshake.js.map +1 -1
  5. package/dist/bin/descry-mcp.d.ts +4 -15
  6. package/dist/bin/descry-mcp.d.ts.map +1 -1
  7. package/dist/bin/descry-mcp.js +12 -42
  8. package/dist/bin/descry-mcp.js.map +1 -1
  9. package/dist/browser/driver.d.ts +59 -224
  10. package/dist/browser/driver.d.ts.map +1 -1
  11. package/dist/browser/driver.js +9 -55
  12. package/dist/browser/driver.js.map +1 -1
  13. package/dist/browser/evidence.d.ts +10 -43
  14. package/dist/browser/evidence.d.ts.map +1 -1
  15. package/dist/browser/evidence.js +20 -54
  16. package/dist/browser/evidence.js.map +1 -1
  17. package/dist/browser/fake-driver.d.ts +4 -16
  18. package/dist/browser/fake-driver.d.ts.map +1 -1
  19. package/dist/browser/fake-driver.js +6 -20
  20. package/dist/browser/fake-driver.js.map +1 -1
  21. package/dist/browser/graph-write.d.ts +4 -45
  22. package/dist/browser/graph-write.d.ts.map +1 -1
  23. package/dist/browser/graph-write.js +8 -53
  24. package/dist/browser/graph-write.js.map +1 -1
  25. package/dist/browser/playwright-driver.d.ts +7 -91
  26. package/dist/browser/playwright-driver.d.ts.map +1 -1
  27. package/dist/browser/playwright-driver.js +40 -194
  28. package/dist/browser/playwright-driver.js.map +1 -1
  29. package/dist/browser/provider.d.ts +5 -34
  30. package/dist/browser/provider.d.ts.map +1 -1
  31. package/dist/browser/provider.js +4 -24
  32. package/dist/browser/provider.js.map +1 -1
  33. package/dist/browser/registry.d.ts +26 -106
  34. package/dist/browser/registry.d.ts.map +1 -1
  35. package/dist/browser/registry.js +20 -77
  36. package/dist/browser/registry.js.map +1 -1
  37. package/dist/browser/scenario-resolve.d.ts +10 -44
  38. package/dist/browser/scenario-resolve.d.ts.map +1 -1
  39. package/dist/browser/scenario-resolve.js +10 -41
  40. package/dist/browser/scenario-resolve.js.map +1 -1
  41. package/dist/browser/scenario-runner.d.ts +12 -70
  42. package/dist/browser/scenario-runner.d.ts.map +1 -1
  43. package/dist/browser/scenario-runner.js +30 -90
  44. package/dist/browser/scenario-runner.js.map +1 -1
  45. package/dist/browser/stack-parser.d.ts +4 -28
  46. package/dist/browser/stack-parser.d.ts.map +1 -1
  47. package/dist/browser/stack-parser.js +12 -39
  48. package/dist/browser/stack-parser.js.map +1 -1
  49. package/dist/browser/tool-support.d.ts +20 -67
  50. package/dist/browser/tool-support.d.ts.map +1 -1
  51. package/dist/browser/tool-support.js +21 -65
  52. package/dist/browser/tool-support.js.map +1 -1
  53. package/dist/browser/url-scheme.d.ts +14 -0
  54. package/dist/browser/url-scheme.d.ts.map +1 -0
  55. package/dist/browser/url-scheme.js +38 -0
  56. package/dist/browser/url-scheme.js.map +1 -0
  57. package/dist/cancellation.d.ts +11 -46
  58. package/dist/cancellation.d.ts.map +1 -1
  59. package/dist/cancellation.js +11 -46
  60. package/dist/cancellation.js.map +1 -1
  61. package/dist/capped.d.ts +9 -33
  62. package/dist/capped.d.ts.map +1 -1
  63. package/dist/capped.js +7 -27
  64. package/dist/capped.js.map +1 -1
  65. package/dist/disclosure-ledger.d.ts +6 -30
  66. package/dist/disclosure-ledger.d.ts.map +1 -1
  67. package/dist/disclosure-ledger.js +4 -26
  68. package/dist/disclosure-ledger.js.map +1 -1
  69. package/dist/index.d.ts +10 -26
  70. package/dist/index.d.ts.map +1 -1
  71. package/dist/index.js +7 -17
  72. package/dist/index.js.map +1 -1
  73. package/dist/module-trust.d.ts +24 -0
  74. package/dist/module-trust.d.ts.map +1 -0
  75. package/dist/module-trust.js +60 -0
  76. package/dist/module-trust.js.map +1 -0
  77. package/dist/path-confinement.d.ts +31 -0
  78. package/dist/path-confinement.d.ts.map +1 -0
  79. package/dist/path-confinement.js +44 -0
  80. package/dist/path-confinement.js.map +1 -0
  81. package/dist/protocol.d.ts +10 -53
  82. package/dist/protocol.d.ts.map +1 -1
  83. package/dist/protocol.js +14 -60
  84. package/dist/protocol.js.map +1 -1
  85. package/dist/registry.d.ts +10 -58
  86. package/dist/registry.d.ts.map +1 -1
  87. package/dist/registry.js +38 -90
  88. package/dist/registry.js.map +1 -1
  89. package/dist/render.d.ts +42 -11
  90. package/dist/render.d.ts.map +1 -1
  91. package/dist/render.js +74 -10
  92. package/dist/render.js.map +1 -1
  93. package/dist/runtime-registry.d.ts +7 -66
  94. package/dist/runtime-registry.d.ts.map +1 -1
  95. package/dist/runtime-registry.js +39 -114
  96. package/dist/runtime-registry.js.map +1 -1
  97. package/dist/scenarios/index.d.ts +1 -1
  98. package/dist/scenarios/index.d.ts.map +1 -1
  99. package/dist/scenarios/index.js +1 -1
  100. package/dist/scenarios/index.js.map +1 -1
  101. package/dist/scenarios/parse.d.ts +4 -18
  102. package/dist/scenarios/parse.d.ts.map +1 -1
  103. package/dist/scenarios/parse.js +14 -34
  104. package/dist/scenarios/parse.js.map +1 -1
  105. package/dist/scenarios/scenario.d.ts +18 -74
  106. package/dist/scenarios/scenario.d.ts.map +1 -1
  107. package/dist/scenarios/scenario.js +7 -34
  108. package/dist/scenarios/scenario.js.map +1 -1
  109. package/dist/scenarios/storage.d.ts +11 -41
  110. package/dist/scenarios/storage.d.ts.map +1 -1
  111. package/dist/scenarios/storage.js +57 -47
  112. package/dist/scenarios/storage.js.map +1 -1
  113. package/dist/server.d.ts.map +1 -1
  114. package/dist/server.js +37 -17
  115. package/dist/server.js.map +1 -1
  116. package/dist/session.d.ts +67 -259
  117. package/dist/session.d.ts.map +1 -1
  118. package/dist/session.js +69 -250
  119. package/dist/session.js.map +1 -1
  120. package/dist/tools/analyze.d.ts +24 -118
  121. package/dist/tools/analyze.d.ts.map +1 -1
  122. package/dist/tools/analyze.js +44 -166
  123. package/dist/tools/analyze.js.map +1 -1
  124. package/dist/tools/browser-click.d.ts +3 -21
  125. package/dist/tools/browser-click.d.ts.map +1 -1
  126. package/dist/tools/browser-click.js +10 -31
  127. package/dist/tools/browser-click.js.map +1 -1
  128. package/dist/tools/browser-close-session.d.ts +4 -13
  129. package/dist/tools/browser-close-session.d.ts.map +1 -1
  130. package/dist/tools/browser-close-session.js +4 -13
  131. package/dist/tools/browser-close-session.js.map +1 -1
  132. package/dist/tools/browser-fill.d.ts +5 -36
  133. package/dist/tools/browser-fill.d.ts.map +1 -1
  134. package/dist/tools/browser-fill.js +9 -44
  135. package/dist/tools/browser-fill.js.map +1 -1
  136. package/dist/tools/browser-navigate.d.ts +6 -27
  137. package/dist/tools/browser-navigate.d.ts.map +1 -1
  138. package/dist/tools/browser-navigate.js +6 -23
  139. package/dist/tools/browser-navigate.js.map +1 -1
  140. package/dist/tools/browser-run-scenario.d.ts +5 -31
  141. package/dist/tools/browser-run-scenario.d.ts.map +1 -1
  142. package/dist/tools/browser-run-scenario.js +10 -46
  143. package/dist/tools/browser-run-scenario.js.map +1 -1
  144. package/dist/tools/browser-save-scenario.d.ts +3 -28
  145. package/dist/tools/browser-save-scenario.d.ts.map +1 -1
  146. package/dist/tools/browser-save-scenario.js +15 -74
  147. package/dist/tools/browser-save-scenario.js.map +1 -1
  148. package/dist/tools/browser-snapshot.d.ts +6 -39
  149. package/dist/tools/browser-snapshot.d.ts.map +1 -1
  150. package/dist/tools/browser-snapshot.js +4 -31
  151. package/dist/tools/browser-snapshot.js.map +1 -1
  152. package/dist/tools/browser-start-session.d.ts +4 -23
  153. package/dist/tools/browser-start-session.d.ts.map +1 -1
  154. package/dist/tools/browser-start-session.js +33 -55
  155. package/dist/tools/browser-start-session.js.map +1 -1
  156. package/dist/tools/browser-type.d.ts +5 -35
  157. package/dist/tools/browser-type.d.ts.map +1 -1
  158. package/dist/tools/browser-type.js +10 -45
  159. package/dist/tools/browser-type.js.map +1 -1
  160. package/dist/tools/contracts.d.ts +9 -86
  161. package/dist/tools/contracts.d.ts.map +1 -1
  162. package/dist/tools/contracts.js +24 -80
  163. package/dist/tools/contracts.js.map +1 -1
  164. package/dist/tools/cross-pr.d.ts +42 -30
  165. package/dist/tools/cross-pr.d.ts.map +1 -1
  166. package/dist/tools/cross-pr.js +81 -62
  167. package/dist/tools/cross-pr.js.map +1 -1
  168. package/dist/tools/git-diff.d.ts +18 -2
  169. package/dist/tools/git-diff.d.ts.map +1 -1
  170. package/dist/tools/git-diff.js +118 -26
  171. package/dist/tools/git-diff.js.map +1 -1
  172. package/dist/tools/git-history.d.ts +5 -16
  173. package/dist/tools/git-history.d.ts.map +1 -1
  174. package/dist/tools/git-history.js +3 -10
  175. package/dist/tools/git-history.js.map +1 -1
  176. package/dist/tools/history.d.ts +4 -33
  177. package/dist/tools/history.d.ts.map +1 -1
  178. package/dist/tools/history.js +6 -31
  179. package/dist/tools/history.js.map +1 -1
  180. package/dist/tools/impact.d.ts +7 -51
  181. package/dist/tools/impact.d.ts.map +1 -1
  182. package/dist/tools/impact.js +15 -67
  183. package/dist/tools/impact.js.map +1 -1
  184. package/dist/tools/index.d.ts +3 -8
  185. package/dist/tools/index.d.ts.map +1 -1
  186. package/dist/tools/index.js +3 -8
  187. package/dist/tools/index.js.map +1 -1
  188. package/dist/tools/kit.d.ts +66 -113
  189. package/dist/tools/kit.d.ts.map +1 -1
  190. package/dist/tools/kit.js +60 -28
  191. package/dist/tools/kit.js.map +1 -1
  192. package/dist/tools/link-workspace.d.ts +7 -45
  193. package/dist/tools/link-workspace.d.ts.map +1 -1
  194. package/dist/tools/link-workspace.js +10 -48
  195. package/dist/tools/link-workspace.js.map +1 -1
  196. package/dist/tools/lookup.d.ts +4 -14
  197. package/dist/tools/lookup.d.ts.map +1 -1
  198. package/dist/tools/lookup.js +4 -14
  199. package/dist/tools/lookup.js.map +1 -1
  200. package/dist/tools/mark-incident.d.ts +7 -54
  201. package/dist/tools/mark-incident.d.ts.map +1 -1
  202. package/dist/tools/mark-incident.js +15 -68
  203. package/dist/tools/mark-incident.js.map +1 -1
  204. package/dist/tools/observe-runtime.d.ts +27 -210
  205. package/dist/tools/observe-runtime.d.ts.map +1 -1
  206. package/dist/tools/observe-runtime.js +257 -435
  207. package/dist/tools/observe-runtime.js.map +1 -1
  208. package/dist/tools/observe-tests.d.ts +9 -100
  209. package/dist/tools/observe-tests.d.ts.map +1 -1
  210. package/dist/tools/observe-tests.js +24 -152
  211. package/dist/tools/observe-tests.js.map +1 -1
  212. package/dist/tools/pr-analysis.d.ts +18 -2
  213. package/dist/tools/pr-analysis.d.ts.map +1 -1
  214. package/dist/tools/pr-analysis.js +73 -23
  215. package/dist/tools/pr-analysis.js.map +1 -1
  216. package/dist/tools/pre-push.d.ts +68 -16
  217. package/dist/tools/pre-push.d.ts.map +1 -1
  218. package/dist/tools/pre-push.js +98 -35
  219. package/dist/tools/pre-push.js.map +1 -1
  220. package/dist/tools/propagation.d.ts +11 -53
  221. package/dist/tools/propagation.d.ts.map +1 -1
  222. package/dist/tools/propagation.js +14 -57
  223. package/dist/tools/propagation.js.map +1 -1
  224. package/dist/tools/questions.d.ts +13 -63
  225. package/dist/tools/questions.d.ts.map +1 -1
  226. package/dist/tools/questions.js +33 -105
  227. package/dist/tools/questions.js.map +1 -1
  228. package/dist/tools/refusal-fetch.d.ts +4 -40
  229. package/dist/tools/refusal-fetch.d.ts.map +1 -1
  230. package/dist/tools/refusal-fetch.js +4 -40
  231. package/dist/tools/refusal-fetch.js.map +1 -1
  232. package/dist/tools/runtime-incident.d.ts +4 -63
  233. package/dist/tools/runtime-incident.d.ts.map +1 -1
  234. package/dist/tools/runtime-incident.js +10 -87
  235. package/dist/tools/runtime-incident.js.map +1 -1
  236. package/dist/tools/scope.d.ts +7 -25
  237. package/dist/tools/scope.d.ts.map +1 -1
  238. package/dist/tools/scope.js +10 -29
  239. package/dist/tools/scope.js.map +1 -1
  240. package/dist/tools/similar-incidents.d.ts +11 -86
  241. package/dist/tools/similar-incidents.d.ts.map +1 -1
  242. package/dist/tools/similar-incidents.js +7 -71
  243. package/dist/tools/similar-incidents.js.map +1 -1
  244. package/dist/tools/validate.d.ts +14 -69
  245. package/dist/tools/validate.d.ts.map +1 -1
  246. package/dist/tools/validate.js +23 -74
  247. package/dist/tools/validate.js.map +1 -1
  248. package/dist/tools/verification-status.d.ts +9 -64
  249. package/dist/tools/verification-status.d.ts.map +1 -1
  250. package/dist/tools/verification-status.js +9 -62
  251. package/dist/tools/verification-status.js.map +1 -1
  252. package/dist/tools/verify-claim.d.ts +5 -52
  253. package/dist/tools/verify-claim.d.ts.map +1 -1
  254. package/dist/tools/verify-claim.js +6 -56
  255. package/dist/tools/verify-claim.js.map +1 -1
  256. package/dist/transport.d.ts +15 -52
  257. package/dist/transport.d.ts.map +1 -1
  258. package/dist/transport.js +16 -60
  259. package/dist/transport.js.map +1 -1
  260. package/package.json +30 -21
@@ -1,40 +1,7 @@
1
1
  /**
2
- * The browser port — what `@descryy/mcp` needs from a browser, stated as an
3
- * interface this package owns.
4
- *
5
- * ## Why a port at all
6
- *
7
- * `@descryy/runtime-browser` is not on the registry yet
8
- * (`mcp-browser-tools.md` §3.1), so a lane that imported it directly could
9
- * not run today. That is the immediate reason and it is the weakest one.
10
- * The lasting reason is that everything above this line — seven tools, the
11
- * session registry, the scenario runner — otherwise becomes untestable
12
- * without launching a real Chromium per assertion, and a suite that needs a
13
- * browser to test its session bookkeeping is a suite people stop running.
14
- *
15
- * ## Derived, not invented
16
- *
17
- * Every member below exists because a real export in
18
- * `descry-runtime/packages/browser/src/index.ts` provides it. The refusal
19
- * shape is `launchBrowserSessionOrRefuse`'s verbatim; `isUsable()` is
20
- * `BrowserSession`'s, including its reason for existing (a crashed page
21
- * still reports `isClosed() === false`, so crash tracking cannot be derived
22
- * from closure); the action verbs are `BrowserActionCollector`'s; the
23
- * console and network observations are what the two collectors emit. The
24
- * port narrows that surface — it does not add to it. Nothing here can be
25
- * satisfied by the real package only by writing new runtime code, with one
26
- * disclosed exception, `type()` below.
27
- *
28
- * ## What the port deliberately does not carry
29
- *
30
- * A verdict. There is no `severity`, no `isBug`, no `category` on any
31
- * observation, because `DEC-381` rules that
32
- * classification stays in the desktop pipeline. That is enforced structurally
33
- * rather than by convention: a tool cannot report a triaged finding through
34
- * a port that has nowhere to put one.
35
- *
36
- * Rule 1 holds here as everywhere — nothing in this file names a language, a
37
- * framework, or a file extension.
2
+ * Browser port for @descryy/mcp — testable without a real Chromium; runtime-browser isn't
3
+ * registry-published yet (§3.1). Mirrors runtime-browser's real exports (exception: `type()`);
4
+ * no verdict/severity (DEC-381). Rule 1: nothing here names a language, framework or extension.
38
5
  */
39
6
  import type { StackTrace } from "@descryy/runtime-contracts";
40
7
  /** A page element as a snapshot presented it. `ref` is the handle an action takes. */
@@ -42,42 +9,18 @@ export interface SnapshotElement {
42
9
  readonly ref: string;
43
10
  readonly role: string;
44
11
  readonly name: string;
45
- /**
46
- * How the driver will find this element again. Present so a reply can be
47
- * read by a human, **not** so a caller can act on it: every verb takes a
48
- * `ref`, never a selector, because a ref ties the action to a snapshot the
49
- * agent actually saw and a selector does not.
50
- *
51
- * Also what a scenario stores to find the element again in a *later*
52
- * session (`scenario-resolve.ts`), which is the property that actually
53
- * needs it to be durable — a value scoped to this one snapshot would defeat
54
- * that the moment the generation counter moved on.
55
- *
56
- * **Null when no candidate resolves to exactly one element on the page.**
57
- * A driver must never fabricate a selector that might not match, or might
58
- * match the wrong thing — that is precision over recall (rule 2) applied
59
- * here: an honest null beats a value that looks like a selector and isn't
60
- * one. `browser_save_scenario` refuses to save a step naming such an
61
- * element, by name, rather than writing a scenario doomed to fail at
62
- * replay.
63
- */
12
+ /** How the driver finds this element again; every verb takes a `ref`, never a selector,
13
+ * because a ref ties to the snapshot the agent saw. Also what a scenario persists across
14
+ * sessions. **Null when no candidate resolves to exactly one element** (rule 2: no guessed selector). */
64
15
  readonly selector: string | null;
65
16
  }
66
17
  export interface PageSnapshot {
67
18
  readonly url: string;
68
19
  readonly title: string;
69
20
  readonly elements: readonly SnapshotElement[];
70
- /**
71
- * How many elements the page had, before any budget applied.
72
- *
73
- * Always present, and always the uncapped figure. §5.2's requirement in one
74
- * field: without it a caller cannot tell "there are no more elements" from
75
- * "the rest did not fit", and those are different facts about their page.
76
- * The driver never truncates — it returns what it saw and this equals
77
- * `elements.length` here — but the field is on the port rather than
78
- * invented by the tool, so the tool cannot lose track of the real count
79
- * while paging.
80
- */
21
+ /** Element count before any budget applied, always uncapped (§5.2) — lets a caller
22
+ * distinguish "no more elements" from "the rest didn't fit". Driver never truncates
23
+ * (equals elements.length here), but lives on the port so a tool can't lose the real count. */
81
24
  readonly totalElements: number;
82
25
  }
83
26
  export type BrowserActionKind = "navigate" | "click" | "type" | "fill";
@@ -85,30 +28,16 @@ export interface ObservedAction {
85
28
  readonly action: BrowserActionKind;
86
29
  /** Null for `navigate`, which acts on the page rather than on an element. */
87
30
  readonly ref: string | null;
88
- /**
89
- * How text reached the field — `"append"` for `type`, `"replace"` for
90
- * `fill`, null for actions that enter no text.
91
- *
92
- * Carried because without it the two text verbs' evidence reads
93
- * identically, and "the field now contains X" and "X was added to whatever
94
- * the field already contained" are different facts about a run. The runtime
95
- * collector's own `INPUT` payload carries the same field for the same
96
- * reason.
97
- */
31
+ /** How text reached the field — "append" for `type`, "replace" for `fill`, null when no
32
+ * text entered. Without it "field now contains X" and "X was appended" read identically;
33
+ * the runtime collector's INPUT payload carries the same field for the same reason. */
98
34
  readonly mode: "replace" | "append" | null;
99
35
  readonly url: string;
100
36
  readonly at: string;
101
37
  }
102
- /**
103
- * What `rewriteScriptUrls` did with one script URL in a stack.
104
- *
105
- * Per URL rather than a summary, because partial mapping is the steady state:
106
- * an application's own bundle maps, its CDN dependency does not, and a
107
- * browser extension's frame never will. Collapsing that into a count would
108
- * report a shortfall where there is a boundary, and would leave a caller
109
- * unable to tell a misconfigured `documentRoot` from a third-party script it
110
- * should ignore.
111
- */
38
+ /** What rewriteScriptUrls did with one script URL. Per-URL, not a summary — partial mapping
39
+ * is the steady state (own bundle maps, CDN dependency doesn't), and collapsing to a count
40
+ * would hide that boundary and any third-party script a caller should ignore. */
112
41
  export interface ScriptUrlOutcome {
113
42
  /** The URL as it appeared in the stack, `:line:column` suffix included. */
114
43
  readonly url: string;
@@ -119,110 +48,53 @@ export interface ScriptUrlOutcome {
119
48
  }
120
49
  export interface ObservedConsoleError {
121
50
  readonly text: string;
122
- /**
123
- * The stack, rendered from parsed frames, or null.
124
- *
125
- * Already rewritten to real files and lines where that was possible:
126
- * `rewriteScriptUrls` runs inside the runtime collector, on the stack text
127
- * *before* the parser sees it, using the `resolveSourceRoot` the driver put
128
- * on the collector context. What survives as an `http://` URL here is a
129
- * frame that genuinely did not map, and `scriptUrlMapping` says why.
130
- */
51
+ /** Stack rendered from parsed frames, or null. Already rewritten to real files/lines where
52
+ * possible — rewriteScriptUrls runs inside the runtime collector before the parser sees it.
53
+ * A surviving http:// URL is a frame that genuinely didn't map (see scriptUrlMapping). */
131
54
  readonly stackText: string | null;
132
- /**
133
- * Per-URL mapping outcomes from the collector, empty when it attempted no
134
- * mapping. **Empty is not "nothing mapped"** — it is "no rewrite ran",
135
- * which happens with no stack parser configured, and the two must not be
136
- * reported alike.
137
- */
55
+ /** Per-URL mapping outcomes; empty means no rewrite ran (no stack parser configured),
56
+ * not "nothing mapped" — the two must not be reported alike. */
138
57
  readonly scriptUrlMapping: readonly ScriptUrlOutcome[];
139
58
  readonly at: string;
140
59
  }
141
- /**
142
- * How a request's lifecycle actually ended, when the collector can tell.
143
- *
144
- * `status: null` used to carry two different facts at once: "this will never
145
- * answer" and "it has not answered *yet*". `"pending"` splits the second one
146
- * back out — a request still in flight when the observation window closed is
147
- * neither a success nor a failure, and folding it into either taught a false
148
- * positive on a perfectly healthy, still-loading page.
149
- *
150
- * - `"answered"` — a real status came back, carried in `status`.
151
- * - `"unanswered"` — a real failure: Playwright's own `requestfailed` fired,
152
- * or the page closed with this request outstanding.
153
- * - `"pending"` — still in flight when the drain happened. Not a verdict
154
- * either way; reported under its own key rather than as a failure.
155
- */
60
+ /** How a request's lifecycle ended, when the collector can tell. `status: null` used to
61
+ * conflate "never answers" with "hasn't yet" — `"pending"` splits that back out (still
62
+ * in flight at drain, neither success nor failure); `"unanswered"` is Playwright's own requestfailed. */
156
63
  export type RequestOutcome = "answered" | "unanswered" | "pending";
157
64
  export interface ObservedRequest {
158
65
  readonly method: string;
159
66
  readonly url: string;
160
67
  /** Null when the request produced no response at all, which is a different fact from a 500. */
161
68
  readonly status: number | null;
162
- /**
163
- * How this request's lifecycle ended, when the collector reports it.
164
- *
165
- * Optional on purpose: the field is `descry-runtime`'s browser collector to
166
- * populate (a separate lane's work), and this port must not assume that
167
- * build is running. Absent means no outcome information at all — see
168
- * `isFailedRequest`, which degrades to its pre-existing status-only rule
169
- * rather than mis-reading an older build's silence as a new fact.
170
- */
69
+ /** How this request's lifecycle ended, when the collector reports it. Optional: a separate
70
+ * lane's field to populate, this port can't assume that build is running. Absent degrades to
71
+ * isFailedRequest's pre-existing status-only rule rather than mis-reading an older build. */
171
72
  readonly outcome?: RequestOutcome;
172
73
  /** The `fetch()` call site as raw text, when the initiator capture claimed one. Null is honest absence. */
173
74
  readonly stackText: string | null;
174
75
  /** Per-URL mapping outcomes for that call site. See `ScriptUrlOutcome`. */
175
76
  readonly scriptUrlMapping: readonly ScriptUrlOutcome[];
176
- /**
177
- * The same call site, parsed into frames with real file paths.
178
- *
179
- * Null unless the caller named a stack-trace parser for the application
180
- * being driven — this package cannot parse a stack itself without naming a
181
- * language, which rule 1 forbids above the IR. **This is the field the R4
182
- * edge write needs**: `confirmObservedFrontendCaller` takes a `StackTrace`,
183
- * not text, and a run with no parser produces no arrow and says so.
184
- */
77
+ /** Same call site parsed into frames with real file paths. Null unless the caller named a
78
+ * stack-trace parser — this package can't parse a stack itself without naming a language
79
+ * (rule 1). **The field the R4 edge write needs** (confirmObservedFrontendCaller). */
185
80
  readonly stackTrace: StackTrace | null;
186
81
  readonly at: string;
187
82
  }
188
- /**
189
- * A request that did not succeed. Mechanical, not a judgement.
190
- *
191
- * With no `outcome` reported (an older `descry-runtime` build), this keeps
192
- * the original rule exactly: no response at all, or a 4xx/5xx status. With an
193
- * `outcome`, `"pending"` is deliberately excluded — a request still in flight
194
- * when the window closed is not evidence of anything — and `"unanswered"` is
195
- * always a failure regardless of `status`, since Playwright's own
196
- * `requestfailed` (or a page closing mid-request) is a stronger signal than
197
- * an absent status by itself.
198
- */
83
+ /** A request that didn't succeed — mechanical, not a judgement. With no `outcome` (older
84
+ * descry-runtime build): no response, or 4xx/5xx. With `outcome`: "pending" excluded (in-flight
85
+ * proves nothing); "unanswered" is always a failure (requestfailed is stronger than a bare status). */
199
86
  export declare function isFailedRequest(request: ObservedRequest): boolean;
200
87
  /** Everything witnessed since the last drain. Raw — see this file's header. */
201
88
  export interface BrowserObservation {
202
89
  readonly actions: readonly ObservedAction[];
203
90
  readonly consoleErrors: readonly ObservedConsoleError[];
204
- /**
205
- * Every request the page issued, not only the ones that failed.
206
- *
207
- * A successful call is what proves *this frontend action reached this
208
- * backend route* — the arrow the whole plan exists for — so filtering to
209
- * failures here would throw away the evidence the R4 edge write runs on.
210
- * The reply narrows to failures for readability; the correlation does not.
211
- */
91
+ /** Every request issued, not only failures — a success proves *this frontend action reached
92
+ * this backend route*, the arrow the R4 edge write runs on. Filtering here would discard
93
+ * it; the reply narrows to failures for readability, correlation does not. */
212
94
  readonly requests: readonly ObservedRequest[];
213
- /**
214
- * Actions whose network activity had not finished when the driver stopped
215
- * waiting.
216
- *
217
- * This exists because the alternative is the failure this surface is built
218
- * to prevent. An action returns after a bounded wait; if a request it
219
- * caused is still in flight at that bound, its evidence lands after the
220
- * drain and is simply not in the reply — and a reply missing evidence looks
221
- * exactly like a reply from a page that produced none. One is "nothing
222
- * happened", the other is "I stopped looking", and rule 7 does not permit
223
- * them to render the same. Anything in here means the observation for that
224
- * action is incomplete and says so.
225
- */
95
+ /** Actions whose network activity hadn't finished when the driver stopped waiting. Without
96
+ * this, "nothing happened" and "I stopped looking" render identically — rule 7 forbids that.
97
+ * Non-empty means that action's observation is incomplete, and says so. */
226
98
  readonly unsettled: readonly UnsettledAction[];
227
99
  }
228
100
  export interface UnsettledAction {
@@ -236,14 +108,9 @@ export interface BrowserLaunchOptions {
236
108
  readonly targetUrl: string;
237
109
  readonly headless?: boolean;
238
110
  }
239
- /**
240
- * `launchBrowserSessionOrRefuse`'s refusal, unchanged.
241
- *
242
- * `remedy` is the exact command that fixes it, **supplied by the driver and
243
- * never held as a constant in this package**. The real driver passes
244
- * `CHROMIUM_INSTALL_REMEDY` through; a copy here would be a second source of
245
- * truth for one string, and the copy is the one that goes stale.
246
- */
111
+ /** launchBrowserSessionOrRefuse's refusal, unchanged. `remedy` is supplied by the driver
112
+ * (CHROMIUM_INSTALL_REMEDY), never held as a constant here — a copy would be a second
113
+ * source of truth that goes stale. */
247
114
  export interface ChromiumRefusal {
248
115
  readonly refusal: "chromiumNotInstalled";
249
116
  readonly message: string;
@@ -261,14 +128,9 @@ export declare class BrowserSessionCrashedError extends Error {
261
128
  readonly sessionId: string;
262
129
  constructor(sessionId: string);
263
130
  }
264
- /**
265
- * The ref named no element in the current snapshot.
266
- *
267
- * Thrown for an invented ref **and** for a ref from a superseded snapshot,
268
- * because those are the same mistake: acting on an element the agent has not
269
- * seen. Falling back to the stale selector would let a click land on whatever
270
- * now matches it on a page the caller has never inspected.
271
- */
131
+ /** The ref named no element in the current snapshot. Thrown for an invented ref and for a
132
+ * ref from a superseded snapshot alike — both are acting on an element the agent never saw;
133
+ * falling back to a stale selector could click whatever now matches on an uninspected page. */
272
134
  export declare class UnknownElementRefError extends Error {
273
135
  constructor(ref: string);
274
136
  }
@@ -276,60 +138,33 @@ export interface BrowserPageSession {
276
138
  readonly sessionId: string;
277
139
  /** When the page was actually created, ISO-8601. What evidence is ordered by. */
278
140
  readonly startedAt: string;
279
- /**
280
- * False once the page has crashed or closed. Not derivable from closure —
281
- * `runtime-browser` verified directly that a real crash still reports
282
- * `isClosed() === false`, which is why this is a member rather than
283
- * something a caller computes.
284
- */
141
+ /** False once the page crashed or closed. Not derivable from closure — runtime-browser
142
+ * verified a real crash still reports isClosed() === false, so this is a member, not
143
+ * something a caller computes. */
285
144
  isUsable(): boolean;
286
145
  currentUrl(): string;
287
146
  navigate(url: string): Promise<void>;
288
147
  snapshot(): Promise<PageSnapshot>;
289
148
  click(ref: string): Promise<void>;
290
- /**
291
- * Type `text` as real keystrokes, appending to whatever the field holds.
292
- *
293
- * The append/replace difference against `fill` is the visible half. The
294
- * half that decides which verb is correct for a page is that **this one
295
- * fires key events and `fill` fires none**: a field that opens an
296
- * autocomplete on keydown, validates per character, or debounces a search
297
- * sees nothing at all from a `fill`. A caller reaching for `fill` on a
298
- * search box gets a page that was never typed into — a wrong answer
299
- * produced by entirely correct code — so both members exist and the tool
300
- * prose has to state the real distinction, not the tidy one.
301
- */
149
+ /** Types real keystrokes, appending to the field. Unlike `fill`, **this fires key events** —
150
+ * an autocomplete, per-character validation, or debounced search sees nothing from `fill`.
151
+ * Using `fill` on such a field is a wrong answer from entirely correct code. */
302
152
  type(ref: string, text: string): Promise<void>;
303
153
  /** Replace the element's value with `text`, setting it directly. Fires no key events. */
304
154
  fill(ref: string, text: string): Promise<void>;
305
- /**
306
- * Everything witnessed since the last drain, removed from the session as it
307
- * is returned.
308
- *
309
- * Drained rather than peeked, and that is a contract, not an implementation
310
- * detail: §4 requires evidence to be flushed on four separate teardown
311
- * paths, and a peeking read would make the flush re-report every
312
- * observation already attached to an earlier reply.
313
- */
155
+ /** Everything witnessed since the last drain, removed as it's returned. Drained, not peeked —
156
+ * a contract (§4 requires flush on four teardown paths): a peeking read would re-report
157
+ * observations already attached to an earlier reply. */
314
158
  drainEvidence(): Promise<BrowserObservation>;
315
- /**
316
- * Tear down and return whatever was still held.
317
- *
318
- * Idempotent, and returns the final flush rather than `void`. Evidence
319
- * captured and then dropped is worse than evidence never captured, because
320
- * nothing discloses it — so the last thing a session does is hand back what
321
- * it was holding, on every path including a crash.
322
- */
159
+ /** Tear down and return whatever was still held. Idempotent, returns the final flush rather
160
+ * than void — evidence captured then dropped is worse than never captured, since nothing
161
+ * discloses it; every path, crash included, hands back what it was holding. */
323
162
  close(): Promise<BrowserObservation>;
324
163
  }
325
164
  export interface BrowserDriver {
326
- /**
327
- * Open a session at `targetUrl`, or refuse.
328
- *
329
- * A missing browser is a **returned value**, never a thrown error, so a
330
- * tool mapping it onto the `refused` state cannot forget to catch it —
331
- * `refused` is a fact about Descry, never about the user's code.
332
- */
165
+ /** Open a session at targetUrl, or refuse. A missing browser is a **returned value**, never
166
+ * a thrown error, so a tool mapping it to `refused` can't forget to catch it — `refused` is
167
+ * a fact about Descry, never the user's code. */
333
168
  launch(options: BrowserLaunchOptions): Promise<BrowserLaunchResult>;
334
169
  }
335
170
  //# sourceMappingURL=driver.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/browser/driver.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/browser/driver.ts"],"names":[],"mappings":"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"}
@@ -1,52 +1,11 @@
1
1
  /**
2
- * The browser port — what `@descryy/mcp` needs from a browser, stated as an
3
- * interface this package owns.
4
- *
5
- * ## Why a port at all
6
- *
7
- * `@descryy/runtime-browser` is not on the registry yet
8
- * (`mcp-browser-tools.md` §3.1), so a lane that imported it directly could
9
- * not run today. That is the immediate reason and it is the weakest one.
10
- * The lasting reason is that everything above this line — seven tools, the
11
- * session registry, the scenario runner — otherwise becomes untestable
12
- * without launching a real Chromium per assertion, and a suite that needs a
13
- * browser to test its session bookkeeping is a suite people stop running.
14
- *
15
- * ## Derived, not invented
16
- *
17
- * Every member below exists because a real export in
18
- * `descry-runtime/packages/browser/src/index.ts` provides it. The refusal
19
- * shape is `launchBrowserSessionOrRefuse`'s verbatim; `isUsable()` is
20
- * `BrowserSession`'s, including its reason for existing (a crashed page
21
- * still reports `isClosed() === false`, so crash tracking cannot be derived
22
- * from closure); the action verbs are `BrowserActionCollector`'s; the
23
- * console and network observations are what the two collectors emit. The
24
- * port narrows that surface — it does not add to it. Nothing here can be
25
- * satisfied by the real package only by writing new runtime code, with one
26
- * disclosed exception, `type()` below.
27
- *
28
- * ## What the port deliberately does not carry
29
- *
30
- * A verdict. There is no `severity`, no `isBug`, no `category` on any
31
- * observation, because `DEC-381` rules that
32
- * classification stays in the desktop pipeline. That is enforced structurally
33
- * rather than by convention: a tool cannot report a triaged finding through
34
- * a port that has nowhere to put one.
35
- *
36
- * Rule 1 holds here as everywhere — nothing in this file names a language, a
37
- * framework, or a file extension.
38
- */
39
- /**
40
- * A request that did not succeed. Mechanical, not a judgement.
41
- *
42
- * With no `outcome` reported (an older `descry-runtime` build), this keeps
43
- * the original rule exactly: no response at all, or a 4xx/5xx status. With an
44
- * `outcome`, `"pending"` is deliberately excluded — a request still in flight
45
- * when the window closed is not evidence of anything — and `"unanswered"` is
46
- * always a failure regardless of `status`, since Playwright's own
47
- * `requestfailed` (or a page closing mid-request) is a stronger signal than
48
- * an absent status by itself.
2
+ * Browser port for @descryy/mcp — testable without a real Chromium; runtime-browser isn't
3
+ * registry-published yet (§3.1). Mirrors runtime-browser's real exports (exception: `type()`);
4
+ * no verdict/severity (DEC-381). Rule 1: nothing here names a language, framework or extension.
49
5
  */
6
+ /** A request that didn't succeed — mechanical, not a judgement. With no `outcome` (older
7
+ * descry-runtime build): no response, or 4xx/5xx. With `outcome`: "pending" excluded (in-flight
8
+ * proves nothing); "unanswered" is always a failure (requestfailed is stronger than a bare status). */
50
9
  export function isFailedRequest(request) {
51
10
  if (request.outcome === undefined)
52
11
  return request.status === null || request.status >= 400;
@@ -66,14 +25,9 @@ export class BrowserSessionCrashedError extends Error {
66
25
  this.sessionId = sessionId;
67
26
  }
68
27
  }
69
- /**
70
- * The ref named no element in the current snapshot.
71
- *
72
- * Thrown for an invented ref **and** for a ref from a superseded snapshot,
73
- * because those are the same mistake: acting on an element the agent has not
74
- * seen. Falling back to the stale selector would let a click land on whatever
75
- * now matches it on a page the caller has never inspected.
76
- */
28
+ /** The ref named no element in the current snapshot. Thrown for an invented ref and for a
29
+ * ref from a superseded snapshot alike — both are acting on an element the agent never saw;
30
+ * falling back to a stale selector could click whatever now matches on an uninspected page. */
77
31
  export class UnknownElementRefError extends Error {
78
32
  constructor(ref) {
79
33
  super(`"${ref}" is not an element in this session's current snapshot. Refs are issued per snapshot and are ` +
@@ -1 +1 @@
1
- {"version":3,"file":"driver.js","sourceRoot":"","sources":["../../src/browser/driver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAgKH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAAC,OAAwB;IACtD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC,MAAM,KAAK,IAAI,IAAI,OAAO,CAAC,MAAM,IAAI,GAAG,CAAC;IAC3F,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAChD,OAAO,OAAO,CAAC,OAAO,KAAK,YAAY,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,IAAI,IAAI,OAAO,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC;AAChG,CAAC;AAsCD,MAAM,CAAC,MAAM,iBAAiB,GAAuB,EAAE,OAAO,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;AA0BrH,kHAAkH;AAClH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAC1C,SAAS,CAAS;IAE3B,YAAY,SAAiB;QAC3B,KAAK,CACH,mBAAmB,SAAS,yEAAyE;YACnG,gGAAgG;YAChG,+EAA+E,CAClF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;QACzC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,GAAW;QACrB,KAAK,CACH,IAAI,GAAG,+FAA+F;YACpG,kFAAkF,CACrF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF"}
1
+ {"version":3,"file":"driver.js","sourceRoot":"","sources":["../../src/browser/driver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAwFH;;wGAEwG;AACxG,MAAM,UAAU,eAAe,CAAC,OAAwB;IACtD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,OAAO,CAAC,MAAM,KAAK,IAAI,IAAI,OAAO,CAAC,MAAM,IAAI,GAAG,CAAC;IAC3F,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAChD,OAAO,OAAO,CAAC,OAAO,KAAK,YAAY,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,IAAI,IAAI,OAAO,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC;AAChG,CAAC;AAuBD,MAAM,CAAC,MAAM,iBAAiB,GAAuB,EAAE,OAAO,EAAE,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;AAqBrH,kHAAkH;AAClH,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAC1C,SAAS,CAAS;IAE3B,YAAY,SAAiB;QAC3B,KAAK,CACH,mBAAmB,SAAS,yEAAyE;YACnG,gGAAgG;YAChG,+EAA+E,CAClF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;QACzC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAED;;gGAEgG;AAChG,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,GAAW;QACrB,KAAK,CACH,IAAI,GAAG,+FAA+F;YACpG,kFAAkF,CACrF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF"}
@@ -1,42 +1,15 @@
1
- /**
2
- * How a browser observation becomes part of a tool reply — §5.3.
3
- *
4
- * Two rules live here rather than in each of the seven tools, because seven
5
- * copies of a disclosure is seven chances for one of them to be missing.
6
- *
7
- * **Attached, not fetched.** Evidence rides on the reply for the action that
8
- * produced it. A separate `browser_get_evidence` would make the caller
9
- * correlate two replies to learn that its own click caused the error, and
10
- * would let it skip the second call entirely.
11
- *
12
- * **Raw, and disclosed as raw.** Per
13
- * `DEC-381`, nothing here classifies. The
14
- * note below is not decoration: a calling agent that receives a console error
15
- * has to know Descry is not claiming it is a bug, or it will report Descry as
16
- * having said so.
17
- */
1
+ /** How a browser observation becomes part of a reply, §5.3. Attached to the same reply, not
2
+ * fetched separately, so a caller can't skip correlating cause and evidence. Raw and disclosed as
3
+ * raw (DEC-381): nothing here classifies anything as a bug — the note below exists so a calling
4
+ * agent doesn't mistake Descry's silence for a verdict. */
18
5
  import { type BrowserObservation, type ObservedRequest } from "./driver.ts";
19
6
  export interface BrowserEvidenceReport {
20
7
  readonly consoleErrors: BrowserObservation["consoleErrors"];
21
- /**
22
- * The requests that did not succeed, listed.
23
- *
24
- * Narrowed from everything the page issued, because a page load can issue
25
- * fifty requests and a reply that lists every stylesheet is a reply nobody
26
- * reads. The narrowing is mechanical — no response, or a 4xx/5xx — and it
27
- * is **only a narrowing of the reply**: the correlation that mints R4 edges
28
- * runs over every request, since a successful call is exactly what proves a
29
- * frontend action reached a backend route.
30
- */
8
+ /** Requests that did not succeed (no response, or 4xx/5xx) — a narrowing of the reply only;
9
+ * R4-edge correlation still runs over every request, since a success proves a route reached. */
31
10
  readonly failedRequests: readonly ObservedRequest[];
32
- /**
33
- * Requests still in flight when the observation window closed.
34
- *
35
- * Not a failure and not a success — `isFailedRequest` deliberately excludes
36
- * these. Reported under its own key rather than silently absent, because a
37
- * healthy request that simply had not answered yet must not read the same
38
- * as a page that issued nothing.
39
- */
11
+ /** Still in flight when the window closed — not a failure, not a success; kept under its own
12
+ * key so it never reads as either. */
40
13
  readonly pendingRequests: readonly ObservedRequest[];
41
14
  /** How many requests the page issued in total, so the list above is read as a subset and not as all of it. */
42
15
  readonly totalRequests: number;
@@ -46,13 +19,7 @@ export interface BrowserEvidenceReport {
46
19
  }
47
20
  export declare function evidenceReport(observation: BrowserObservation): BrowserEvidenceReport;
48
21
  export declare function isEmpty(report: BrowserEvidenceReport): boolean;
49
- /**
50
- * The notes any reply carrying evidence must include.
51
- *
52
- * The triage disclaimer is emitted **only when there is something to
53
- * disclaim**. A reply with no errors that solemnly explained it had not
54
- * triaged them would be noise on the overwhelmingly common path, and noise is
55
- * how a real disclosure stops being read.
56
- */
22
+ /** Notes any reply carrying evidence must include. The triage disclaimer fires only when there's
23
+ * something to disclaim — noise on the common empty path is how a real disclosure stops being read. */
57
24
  export declare function evidenceNotes(report: BrowserEvidenceReport): string[];
58
25
  //# sourceMappingURL=evidence.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../../src/browser/evidence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAmB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAE7F,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,kBAAkB,CAAC,eAAe,CAAC,CAAC;IAC5D;;;;;;;;;OASG;IACH,QAAQ,CAAC,cAAc,EAAE,SAAS,eAAe,EAAE,CAAC;IACpD;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,EAAE,SAAS,eAAe,EAAE,CAAC;IACrD,8GAA8G;IAC9G,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAC;IAChD,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAC;CACrD;AAED,wBAAgB,cAAc,CAAC,WAAW,EAAE,kBAAkB,GAAG,qBAAqB,CASrF;AAED,wBAAgB,OAAO,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,EAAE,CAmCrE"}
1
+ {"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../../src/browser/evidence.ts"],"names":[],"mappings":"AAAA;;;4DAG4D;AAE5D,OAAO,EAAmB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAE7F,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,kBAAkB,CAAC,eAAe,CAAC,CAAC;IAC5D;qGACiG;IACjG,QAAQ,CAAC,cAAc,EAAE,SAAS,eAAe,EAAE,CAAC;IACpD;2CACuC;IACvC,QAAQ,CAAC,eAAe,EAAE,SAAS,eAAe,EAAE,CAAC;IACrD,8GAA8G;IAC9G,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAC;IAChD,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC,WAAW,CAAC,CAAC;CACrD;AAED,wBAAgB,cAAc,CAAC,WAAW,EAAE,kBAAkB,GAAG,qBAAqB,CASrF;AAED,wBAAgB,OAAO,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAE9D;AAUD;wGACwG;AACxG,wBAAgB,aAAa,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,EAAE,CA+BrE"}