@undo76/agent-dom 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 (7) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +122 -0
  3. package/dist/index.cjs +603 -0
  4. package/dist/index.d.cts +128 -0
  5. package/dist/index.d.ts +128 -0
  6. package/dist/index.js +574 -0
  7. package/package.json +57 -0
package/dist/index.d.cts ADDED
@@ -0,0 +1,128 @@
1
+ type TextMatch = string | RegExp;
2
+ type BrowserWindow = Window & typeof globalThis;
3
+ interface ObserveOptions {
4
+ /** Include only elements an agent can directly interact with. */
5
+ interactiveOnly?: boolean;
6
+ /** Include elements hidden by HTML, ARIA, or CSS. */
7
+ includeHidden?: boolean;
8
+ /** Limit the observation to an element or an open shadow root. */
9
+ root?: Document | Element | ShadowRoot;
10
+ /** Maximum accessible-name length before truncation. */
11
+ maxNameLength?: number;
12
+ }
13
+ interface ElementState {
14
+ disabled?: boolean;
15
+ checked?: boolean | "mixed";
16
+ selected?: boolean;
17
+ expanded?: boolean;
18
+ pressed?: boolean | "mixed";
19
+ required?: boolean;
20
+ readonly?: boolean;
21
+ value?: string;
22
+ level?: number;
23
+ }
24
+ interface ObservedElement extends ElementState {
25
+ readonly ref: string;
26
+ readonly role: string;
27
+ readonly name: string;
28
+ readonly description?: string;
29
+ readonly tag: string;
30
+ readonly interactive: boolean;
31
+ readonly depth: number;
32
+ }
33
+ interface RoleLocatorOptions {
34
+ name?: TextMatch;
35
+ }
36
+ interface Observation {
37
+ readonly generation: number;
38
+ readonly text: string;
39
+ readonly elements: readonly ObservedElement[];
40
+ get(ref: string): ObservedElement;
41
+ findByRole(role: string, options?: RoleLocatorOptions): ObservedElement;
42
+ findByLabel(label: TextMatch): ObservedElement;
43
+ findByText(text: TextMatch): ObservedElement;
44
+ }
45
+ type AgentAction = {
46
+ type: "click";
47
+ ref: string;
48
+ } | {
49
+ type: "fill";
50
+ ref: string;
51
+ value: string;
52
+ } | {
53
+ type: "select";
54
+ ref: string;
55
+ value: string | readonly string[];
56
+ } | {
57
+ type: "check";
58
+ ref: string;
59
+ } | {
60
+ type: "uncheck";
61
+ ref: string;
62
+ } | {
63
+ type: "focus";
64
+ ref: string;
65
+ } | {
66
+ type: "scroll";
67
+ ref: string;
68
+ block?: ScrollLogicalPosition;
69
+ inline?: ScrollLogicalPosition;
70
+ } | {
71
+ type: "press";
72
+ ref: string;
73
+ key: string;
74
+ };
75
+ interface CreateAgentPageOptions {
76
+ root?: Document | Element | ShadowRoot;
77
+ }
78
+
79
+ declare class AgentPage {
80
+ #private;
81
+ readonly window: BrowserWindow;
82
+ readonly root: Document | Element | ShadowRoot;
83
+ constructor(window: BrowserWindow, options?: CreateAgentPageOptions);
84
+ observe(options?: ObserveOptions): Observation;
85
+ snapshot(options?: ObserveOptions): Observation;
86
+ getByRole(role: string, options?: RoleLocatorOptions): string;
87
+ getByLabel(label: TextMatch): string;
88
+ getByText(text: TextMatch): string;
89
+ click(ref: string): void;
90
+ fill(ref: string, value: string): void;
91
+ select(ref: string, value: string | readonly string[]): void;
92
+ check(ref: string): void;
93
+ uncheck(ref: string): void;
94
+ focus(ref: string): void;
95
+ scroll(ref: string, block?: ScrollLogicalPosition, inline?: ScrollLogicalPosition): void;
96
+ press(ref: string, key: string): void;
97
+ act(action: AgentAction): void;
98
+ destroy(): void;
99
+ }
100
+ declare function createAgentPage(window: BrowserWindow, options?: CreateAgentPageOptions): AgentPage;
101
+
102
+ declare class AgentObservation implements Observation {
103
+ readonly generation: number;
104
+ readonly text: string;
105
+ readonly elements: readonly ObservedElement[];
106
+ constructor(generation: number, elements: ObservedElement[]);
107
+ get(ref: string): ObservedElement;
108
+ findByRole(role: string, options?: RoleLocatorOptions): ObservedElement;
109
+ findByLabel(label: TextMatch): ObservedElement;
110
+ findByText(text: TextMatch): ObservedElement;
111
+ }
112
+
113
+ declare class AgentDomError extends Error {
114
+ readonly name: string;
115
+ }
116
+ declare class StaleElementReferenceError extends AgentDomError {
117
+ readonly name: string;
118
+ constructor(ref: string, snapshotGeneration: number, currentGeneration: number);
119
+ }
120
+ declare class ElementNotFoundError extends AgentDomError {
121
+ readonly name: string;
122
+ constructor(message: string);
123
+ }
124
+ declare class ActionError extends AgentDomError {
125
+ readonly name: string;
126
+ }
127
+
128
+ export { ActionError, type AgentAction, AgentDomError, AgentObservation, AgentPage, type BrowserWindow, type CreateAgentPageOptions, ElementNotFoundError, type ElementState, type Observation, type ObserveOptions, type ObservedElement, type RoleLocatorOptions, StaleElementReferenceError, type TextMatch, createAgentPage };
package/dist/index.d.ts ADDED
@@ -0,0 +1,128 @@
1
+ type TextMatch = string | RegExp;
2
+ type BrowserWindow = Window & typeof globalThis;
3
+ interface ObserveOptions {
4
+ /** Include only elements an agent can directly interact with. */
5
+ interactiveOnly?: boolean;
6
+ /** Include elements hidden by HTML, ARIA, or CSS. */
7
+ includeHidden?: boolean;
8
+ /** Limit the observation to an element or an open shadow root. */
9
+ root?: Document | Element | ShadowRoot;
10
+ /** Maximum accessible-name length before truncation. */
11
+ maxNameLength?: number;
12
+ }
13
+ interface ElementState {
14
+ disabled?: boolean;
15
+ checked?: boolean | "mixed";
16
+ selected?: boolean;
17
+ expanded?: boolean;
18
+ pressed?: boolean | "mixed";
19
+ required?: boolean;
20
+ readonly?: boolean;
21
+ value?: string;
22
+ level?: number;
23
+ }
24
+ interface ObservedElement extends ElementState {
25
+ readonly ref: string;
26
+ readonly role: string;
27
+ readonly name: string;
28
+ readonly description?: string;
29
+ readonly tag: string;
30
+ readonly interactive: boolean;
31
+ readonly depth: number;
32
+ }
33
+ interface RoleLocatorOptions {
34
+ name?: TextMatch;
35
+ }
36
+ interface Observation {
37
+ readonly generation: number;
38
+ readonly text: string;
39
+ readonly elements: readonly ObservedElement[];
40
+ get(ref: string): ObservedElement;
41
+ findByRole(role: string, options?: RoleLocatorOptions): ObservedElement;
42
+ findByLabel(label: TextMatch): ObservedElement;
43
+ findByText(text: TextMatch): ObservedElement;
44
+ }
45
+ type AgentAction = {
46
+ type: "click";
47
+ ref: string;
48
+ } | {
49
+ type: "fill";
50
+ ref: string;
51
+ value: string;
52
+ } | {
53
+ type: "select";
54
+ ref: string;
55
+ value: string | readonly string[];
56
+ } | {
57
+ type: "check";
58
+ ref: string;
59
+ } | {
60
+ type: "uncheck";
61
+ ref: string;
62
+ } | {
63
+ type: "focus";
64
+ ref: string;
65
+ } | {
66
+ type: "scroll";
67
+ ref: string;
68
+ block?: ScrollLogicalPosition;
69
+ inline?: ScrollLogicalPosition;
70
+ } | {
71
+ type: "press";
72
+ ref: string;
73
+ key: string;
74
+ };
75
+ interface CreateAgentPageOptions {
76
+ root?: Document | Element | ShadowRoot;
77
+ }
78
+
79
+ declare class AgentPage {
80
+ #private;
81
+ readonly window: BrowserWindow;
82
+ readonly root: Document | Element | ShadowRoot;
83
+ constructor(window: BrowserWindow, options?: CreateAgentPageOptions);
84
+ observe(options?: ObserveOptions): Observation;
85
+ snapshot(options?: ObserveOptions): Observation;
86
+ getByRole(role: string, options?: RoleLocatorOptions): string;
87
+ getByLabel(label: TextMatch): string;
88
+ getByText(text: TextMatch): string;
89
+ click(ref: string): void;
90
+ fill(ref: string, value: string): void;
91
+ select(ref: string, value: string | readonly string[]): void;
92
+ check(ref: string): void;
93
+ uncheck(ref: string): void;
94
+ focus(ref: string): void;
95
+ scroll(ref: string, block?: ScrollLogicalPosition, inline?: ScrollLogicalPosition): void;
96
+ press(ref: string, key: string): void;
97
+ act(action: AgentAction): void;
98
+ destroy(): void;
99
+ }
100
+ declare function createAgentPage(window: BrowserWindow, options?: CreateAgentPageOptions): AgentPage;
101
+
102
+ declare class AgentObservation implements Observation {
103
+ readonly generation: number;
104
+ readonly text: string;
105
+ readonly elements: readonly ObservedElement[];
106
+ constructor(generation: number, elements: ObservedElement[]);
107
+ get(ref: string): ObservedElement;
108
+ findByRole(role: string, options?: RoleLocatorOptions): ObservedElement;
109
+ findByLabel(label: TextMatch): ObservedElement;
110
+ findByText(text: TextMatch): ObservedElement;
111
+ }
112
+
113
+ declare class AgentDomError extends Error {
114
+ readonly name: string;
115
+ }
116
+ declare class StaleElementReferenceError extends AgentDomError {
117
+ readonly name: string;
118
+ constructor(ref: string, snapshotGeneration: number, currentGeneration: number);
119
+ }
120
+ declare class ElementNotFoundError extends AgentDomError {
121
+ readonly name: string;
122
+ constructor(message: string);
123
+ }
124
+ declare class ActionError extends AgentDomError {
125
+ readonly name: string;
126
+ }
127
+
128
+ export { ActionError, type AgentAction, AgentDomError, AgentObservation, AgentPage, type BrowserWindow, type CreateAgentPageOptions, ElementNotFoundError, type ElementState, type Observation, type ObserveOptions, type ObservedElement, type RoleLocatorOptions, StaleElementReferenceError, type TextMatch, createAgentPage };