@quiesco/protocol 0.0.0-stage → 0.1.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 (68) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +10 -2
  3. package/dist/actions.d.ts +238 -0
  4. package/dist/actions.d.ts.map +1 -0
  5. package/dist/actions.js +2 -0
  6. package/dist/actions.js.map +1 -0
  7. package/dist/assertions.d.ts +74 -0
  8. package/dist/assertions.d.ts.map +1 -0
  9. package/dist/assertions.js +2 -0
  10. package/dist/assertions.js.map +1 -0
  11. package/dist/config.d.ts +54 -0
  12. package/dist/config.d.ts.map +1 -0
  13. package/dist/config.js +2 -0
  14. package/dist/config.js.map +1 -0
  15. package/dist/constants.d.ts +43 -0
  16. package/dist/constants.d.ts.map +1 -0
  17. package/dist/constants.js +42 -0
  18. package/dist/constants.js.map +1 -0
  19. package/dist/element.d.ts +49 -0
  20. package/dist/element.d.ts.map +1 -0
  21. package/dist/element.js +2 -0
  22. package/dist/element.js.map +1 -0
  23. package/dist/errors.d.ts +106 -0
  24. package/dist/errors.d.ts.map +1 -0
  25. package/dist/errors.js +26 -0
  26. package/dist/errors.js.map +1 -0
  27. package/dist/events.d.ts +19 -0
  28. package/dist/events.d.ts.map +1 -0
  29. package/dist/events.js +2 -0
  30. package/dist/events.js.map +1 -0
  31. package/dist/index.d.ts +13 -0
  32. package/dist/index.d.ts.map +1 -0
  33. package/dist/index.js +13 -0
  34. package/dist/index.js.map +1 -0
  35. package/dist/json.d.ts +6 -0
  36. package/dist/json.d.ts.map +1 -0
  37. package/dist/json.js +2 -0
  38. package/dist/json.js.map +1 -0
  39. package/dist/matcher.d.ts +44 -0
  40. package/dist/matcher.d.ts.map +1 -0
  41. package/dist/matcher.js +22 -0
  42. package/dist/matcher.js.map +1 -0
  43. package/dist/messages.d.ts +49 -0
  44. package/dist/messages.d.ts.map +1 -0
  45. package/dist/messages.js +2 -0
  46. package/dist/messages.js.map +1 -0
  47. package/dist/methods.d.ts +256 -0
  48. package/dist/methods.d.ts.map +1 -0
  49. package/dist/methods.js +2 -0
  50. package/dist/methods.js.map +1 -0
  51. package/dist/webview.d.ts +9 -0
  52. package/dist/webview.d.ts.map +1 -0
  53. package/dist/webview.js +31 -0
  54. package/dist/webview.js.map +1 -0
  55. package/package.json +47 -3
  56. package/src/actions.ts +107 -0
  57. package/src/assertions.ts +29 -0
  58. package/src/config.ts +54 -0
  59. package/src/constants.ts +46 -0
  60. package/src/element.ts +51 -0
  61. package/src/errors.ts +61 -0
  62. package/src/events.ts +11 -0
  63. package/src/index.ts +12 -0
  64. package/src/json.ts +3 -0
  65. package/src/matcher.ts +59 -0
  66. package/src/messages.ts +55 -0
  67. package/src/methods.ts +140 -0
  68. package/src/webview.ts +30 -0
package/src/methods.ts ADDED
@@ -0,0 +1,140 @@
1
+ import type { ActionMode, ActionSpec, HostInput } from './actions.js';
2
+ import type { AssertionSpec } from './assertions.js';
3
+ import type { AgentConfig } from './config.js';
4
+ import type { ElementSummary, Rect, TreeNode } from './element.js';
5
+ import type { JsonValue } from './json.js';
6
+ import type { Matcher } from './matcher.js';
7
+
8
+ export type Platform = 'ios' | 'android' | 'web';
9
+
10
+ /** State of one idle tracker (requirements.md §6.2 `IdleTracker`). */
11
+ export interface TrackerState {
12
+ name: string;
13
+ idle: boolean;
14
+ /** Human-readable busy reasons, e.g. `GET https://api.example.com/todos (1200ms)`. */
15
+ busy: string[];
16
+ }
17
+
18
+ /** Common option: disable the automatic wait-for-idle around a single call (§6.2 `{ sync: false }`). */
19
+ /** Results of query / action / assert / webview / scrollView carry the ms spent waiting for idle (Phase 6.9). */
20
+ export interface SyncTiming {
21
+ syncMs?: number;
22
+ }
23
+
24
+ export interface SyncOption {
25
+ sync?: boolean;
26
+ timeoutMs?: number;
27
+ }
28
+
29
+ /** Methods the HOST calls on the AGENT. */
30
+ export interface AgentMethods {
31
+ query: { params: { matcher: Matcher } & SyncOption; result: { elements: ElementSummary[] } & SyncTiming };
32
+ action: {
33
+ params: { action: ActionSpec; mode: ActionMode } & SyncOption;
34
+ /** `hostInput` is set when the host must perform the real input itself (web native mode). */
35
+ result: { element?: ElementSummary; hostInput?: HostInput } & SyncTiming;
36
+ };
37
+ assert: { params: { assertion: AssertionSpec } & SyncOption; result: { elements: ElementSummary[] } & SyncTiming };
38
+ waitForIdle: { params: { timeoutMs?: number }; result: { waitedMs: number } };
39
+ getTree: { params: Record<string, never>; result: { root: TreeNode | null } };
40
+ reset: { params: Record<string, never>; result: { durationMs: number } };
41
+ backdoor: { params: { name: string; args: JsonValue[] }; result: { value: JsonValue } };
42
+ getIdleState: { params: Record<string, never>; result: { trackers: TrackerState[] } };
43
+ /** Replace the agent config at runtime (Phase 6.5 `app.sync.*`); the next `hello` carries it too. */
44
+ configure: { params: { config: AgentConfig }; result: Record<string, never> };
45
+ /** Window size, pixel ratio and app state (element screenshots, background detection). */
46
+ deviceInfo: { params: Record<string, never>; result: DeviceInfo };
47
+ /** Leave for the home screen from inside the app (iOS @quiesco/native); `false` when not available. */
48
+ suspend: { params: Record<string, never>; result: { suspended: boolean } };
49
+ /**
50
+ * Rotate the app's window from inside the app (iOS @quiesco/native; Phase 6.6). `supported: false`
51
+ * when the app cannot (no native module, other platforms); `error` when iOS refused the request.
52
+ */
53
+ setOrientation: { params: { orientation: Orientation }; result: { supported: boolean; error?: string } };
54
+ /**
55
+ * The clipboard, read / written from inside the app (@quiesco/native; Phase 6.6). Inside the app because
56
+ * iOS asks the user before an app reads text another process (simctl pbcopy) put there, and Android
57
+ * has no shell command for it. `supported: false` without the native module.
58
+ */
59
+ getClipboard: { params: Record<string, never>; result: { supported: boolean; text?: string } };
60
+ setClipboard: { params: { text: string }; result: { supported: boolean } };
61
+ /**
62
+ * Post a notification as the app (Android @quiesco/native; Phase 6.7). `supported: false` without it;
63
+ * `enabled: false` when the app may not show notifications (POST_NOTIFICATIONS not granted).
64
+ */
65
+ postNotification: { params: { title: string; body: string; data: Record<string, string> }; result: { supported: boolean; enabled?: boolean } };
66
+ /**
67
+ * A WebView (Phase 6.8): waits for idle, finds the single WebView matching `matcher` (default: the only
68
+ * one on screen), and on iOS / Android (@quiesco/native) evaluates `script` in its page. On the web the
69
+ * WebView is an `<iframe>` the host reaches itself (Playwright frames): no `value`, the host uses `rect`.
70
+ */
71
+ webview: { params: { matcher?: Matcher; script?: string } & SyncOption; result: WebViewCallResult & SyncTiming };
72
+ /**
73
+ * A scroll view (Phase 6.9 full-page screenshots): the one containing the element matching `matcher`
74
+ * (default: the largest visible one). With `to`, scrolls it there first (programmatically) and waits
75
+ * for idle. `indicators`: show / hide its scroll indicators (native; they would end up in the
76
+ * screenshots). Reports where it is.
77
+ */
78
+ scrollView: { params: { matcher?: Matcher; to?: { x: number; y: number }; indicators?: boolean } & SyncOption; result: ScrollViewInfo & SyncTiming };
79
+ }
80
+
81
+ export interface ScrollViewInfo {
82
+ /** The scroll view's visible area in window coordinates. */
83
+ rect: Rect;
84
+ /** Content offset (how far it is scrolled). */
85
+ offset: { x: number; y: number };
86
+ /** Size of the scrollable content. */
87
+ content: { width: number; height: number };
88
+ /** With `indicators`: whether they were shown before (native only). */
89
+ indicatorsWere?: boolean;
90
+ }
91
+
92
+ export interface WebViewCallResult {
93
+ /** The WebView in window coordinates (logical units). */
94
+ rect: Rect;
95
+ /** Native: the page is (re)loading. */
96
+ loading?: boolean;
97
+ /** Native: the result of `script` (a string expression). */
98
+ value?: string;
99
+ /** Web: the host evaluates the script in the iframe at `rect` itself. */
100
+ viaHost?: boolean;
101
+ }
102
+
103
+ export type Orientation = 'portrait' | 'landscape';
104
+
105
+ /** `AppState` as React Native reports it; `unknown` where it cannot be read. */
106
+ export type AppStateName = 'active' | 'background' | 'inactive' | 'unknown';
107
+
108
+ export interface DeviceInfo {
109
+ /** The app window in logical units (dp / pt / CSS px), the space of element rects. */
110
+ window: { width: number; height: number };
111
+ /** Physical pixels per logical unit. */
112
+ pixelRatio: number;
113
+ appState: AppStateName;
114
+ /** Phase 6.6 read-backs (optional for older agents): what the app sees of the device state. */
115
+ colorScheme?: 'light' | 'dark' | null;
116
+ /** Text size multiplier (`PixelRatio.getFontScale()`). */
117
+ fontScale?: number;
118
+ /** The JS engine's default locale (`Intl.DateTimeFormat().resolvedOptions().locale`). */
119
+ locale?: string;
120
+ }
121
+
122
+ /** Methods the AGENT calls on the HOST. */
123
+ export interface HostMethods {
124
+ hello: {
125
+ params: {
126
+ sessionId: string | null;
127
+ platform: Platform;
128
+ protocolVersion: number;
129
+ agentVersion: string;
130
+ /** Whether @quiesco/native is linked (enables the `native` action mode). */
131
+ nativeModule: boolean;
132
+ };
133
+ result: { accepted: true; sessionId: string; config: AgentConfig };
134
+ };
135
+ }
136
+
137
+ export type AgentMethodName = keyof AgentMethods;
138
+ export type HostMethodName = keyof HostMethods;
139
+ export type ParamsOf<M extends { params: unknown }> = M['params'];
140
+ export type ResultOf<M extends { result: unknown }> = M['result'];
package/src/webview.ts ADDED
@@ -0,0 +1,30 @@
1
+ /**
2
+ * WebView pages (Phase 6.8): the script Quiesco installs in a WebView's pages to know when they are busy.
3
+ * The agent registers it to run at document start of every later load (native WebViews) and the host's
4
+ * page-state script runs it in the current page too; it is idempotent.
5
+ *
6
+ * It counts the page's fetch / XMLHttpRequest calls still running in `window.__quiescoPending`.
7
+ */
8
+ export const WEBVIEW_HOOK = `(function () {
9
+ if (window.__quiescoHook) return;
10
+ window.__quiescoHook = true;
11
+ window.__quiescoPending = 0;
12
+ var done = function () { window.__quiescoPending = Math.max(0, window.__quiescoPending - 1); };
13
+ if (typeof window.fetch === 'function') {
14
+ var f = window.fetch;
15
+ window.fetch = function () {
16
+ window.__quiescoPending++;
17
+ var p;
18
+ try { p = f.apply(this, arguments); } catch (e) { done(); throw e; }
19
+ return p.then(function (r) { done(); return r; }, function (e) { done(); throw e; });
20
+ };
21
+ }
22
+ if (typeof XMLHttpRequest === 'function') {
23
+ var send = XMLHttpRequest.prototype.send;
24
+ XMLHttpRequest.prototype.send = function () {
25
+ window.__quiescoPending++;
26
+ this.addEventListener('loadend', done);
27
+ try { return send.apply(this, arguments); } catch (e) { done(); throw e; }
28
+ };
29
+ }
30
+ })();`;