browserrig 0.1.0__py3-none-any.whl

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 (167) hide show
  1. browserrig/__init__.py +158 -0
  2. browserrig/activity/__init__.py +5 -0
  3. browserrig/activity/models.py +93 -0
  4. browserrig/activity/plugin.py +247 -0
  5. browserrig/activity/state.py +16 -0
  6. browserrig/agent.py +55 -0
  7. browserrig/browser/__init__.py +33 -0
  8. browserrig/browser/base.py +70 -0
  9. browserrig/browser/chrome.py +242 -0
  10. browserrig/browser/config.py +119 -0
  11. browserrig/browser/downloads.py +128 -0
  12. browserrig/browser/favicon.py +119 -0
  13. browserrig/browser/frame.py +227 -0
  14. browserrig/browser/frames.py +116 -0
  15. browserrig/browser/images.py +23 -0
  16. browserrig/browser/input.py +147 -0
  17. browserrig/browser/models.py +8 -0
  18. browserrig/browser/plugin.py +44 -0
  19. browserrig/browser/process.py +144 -0
  20. browserrig/browser/setup.py +12 -0
  21. browserrig/browser/tab.py +311 -0
  22. browserrig/browser/tabs.py +366 -0
  23. browserrig/browser/worlds.py +64 -0
  24. browserrig/choreography/__init__.py +31 -0
  25. browserrig/choreography/events.py +133 -0
  26. browserrig/choreography/plugin.py +75 -0
  27. browserrig/choreography/scenes.py +167 -0
  28. browserrig/choreography/stage.py +53 -0
  29. browserrig/choreography/tabstrip.py +112 -0
  30. browserrig/completion.py +184 -0
  31. browserrig/composition.py +108 -0
  32. browserrig/core/__init__.py +61 -0
  33. browserrig/core/errors.py +18 -0
  34. browserrig/core/geometry.py +149 -0
  35. browserrig/core/ids.py +10 -0
  36. browserrig/core/kinds.py +180 -0
  37. browserrig/core/options.py +7 -0
  38. browserrig/core/tools.py +32 -0
  39. browserrig/events.py +665 -0
  40. browserrig/files/__init__.py +25 -0
  41. browserrig/files/config.py +13 -0
  42. browserrig/files/containers.py +200 -0
  43. browserrig/files/content.py +65 -0
  44. browserrig/files/data.py +80 -0
  45. browserrig/files/documents.py +248 -0
  46. browserrig/files/formats.py +84 -0
  47. browserrig/files/imaging.py +138 -0
  48. browserrig/files/kinds.py +78 -0
  49. browserrig/files/models.py +71 -0
  50. browserrig/files/reading.py +382 -0
  51. browserrig/files/spreadsheets.py +417 -0
  52. browserrig/files/system.py +204 -0
  53. browserrig/files/text.py +64 -0
  54. browserrig/files/xlsx.py +53 -0
  55. browserrig/handoff/__init__.py +4 -0
  56. browserrig/handoff/changes.py +48 -0
  57. browserrig/handoff/models.py +31 -0
  58. browserrig/handoff/plugin.py +308 -0
  59. browserrig/handoff/state.py +21 -0
  60. browserrig/input/__init__.py +35 -0
  61. browserrig/input/controller.py +69 -0
  62. browserrig/input/keyboard.py +267 -0
  63. browserrig/input/motor.py +118 -0
  64. browserrig/input/mouse.py +346 -0
  65. browserrig/input/pointer.py +84 -0
  66. browserrig/input/presenter.py +49 -0
  67. browserrig/input/target.py +67 -0
  68. browserrig/input/wheel.py +40 -0
  69. browserrig/kinds.py +33 -0
  70. browserrig/nudges/__init__.py +3 -0
  71. browserrig/nudges/plugin.py +295 -0
  72. browserrig/nudges/state.py +23 -0
  73. browserrig/observation/__init__.py +53 -0
  74. browserrig/observation/capture.py +374 -0
  75. browserrig/observation/changes.py +63 -0
  76. browserrig/observation/config.py +12 -0
  77. browserrig/observation/content.py +176 -0
  78. browserrig/observation/delta.py +69 -0
  79. browserrig/observation/dom.py +97 -0
  80. browserrig/observation/extraction/__init__.py +335 -0
  81. browserrig/observation/extraction/accessibility.py +62 -0
  82. browserrig/observation/extraction/document.py +471 -0
  83. browserrig/observation/extraction/elements.py +676 -0
  84. browserrig/observation/extraction/semantics.py +351 -0
  85. browserrig/observation/extraction/styles.py +30 -0
  86. browserrig/observation/extraction/visibility.py +108 -0
  87. browserrig/observation/find.py +152 -0
  88. browserrig/observation/handle.py +170 -0
  89. browserrig/observation/images.py +243 -0
  90. browserrig/observation/marks.py +157 -0
  91. browserrig/observation/models.py +230 -0
  92. browserrig/observation/plugin.py +413 -0
  93. browserrig/observation/redirects.py +40 -0
  94. browserrig/observation/references.py +47 -0
  95. browserrig/observation/render.py +291 -0
  96. browserrig/observation/renderer.py +76 -0
  97. browserrig/observation/state.py +37 -0
  98. browserrig/pacing/__init__.py +5 -0
  99. browserrig/pacing/plugin.py +22 -0
  100. browserrig/py.typed +0 -0
  101. browserrig/readiness/__init__.py +25 -0
  102. browserrig/readiness/config.py +12 -0
  103. browserrig/readiness/dom.py +83 -0
  104. browserrig/readiness/downloads.py +30 -0
  105. browserrig/readiness/hooks.py +27 -0
  106. browserrig/readiness/models.py +13 -0
  107. browserrig/readiness/plugin.py +170 -0
  108. browserrig/readiness/policies.py +43 -0
  109. browserrig/readiness/state.py +20 -0
  110. browserrig/readiness/strategy.py +30 -0
  111. browserrig/readiness/wait.py +238 -0
  112. browserrig/scripts/README.md +39 -0
  113. browserrig/scripts/__init__.py +186 -0
  114. browserrig/scripts/content.js +526 -0
  115. browserrig/scripts/cursor.js +57 -0
  116. browserrig/scripts/element.js +82 -0
  117. browserrig/scripts/find.js +377 -0
  118. browserrig/scripts/focused.js +15 -0
  119. browserrig/scripts/lib/composed.js +21 -0
  120. browserrig/scripts/lib/elements.js +9 -0
  121. browserrig/scripts/lib/geometry.js +13 -0
  122. browserrig/scripts/lib/hit.js +84 -0
  123. browserrig/scripts/lib/markdown.js +32 -0
  124. browserrig/scripts/lib/scroll.js +226 -0
  125. browserrig/scripts/lib/secret.js +74 -0
  126. browserrig/scripts/lib/visibility.js +42 -0
  127. browserrig/scripts/models.py +153 -0
  128. browserrig/scripts/owner_hits.js +4 -0
  129. browserrig/scripts/owner_scroll.js +7 -0
  130. browserrig/scripts/owner_size.js +11 -0
  131. browserrig/scripts/page_facts.js +9 -0
  132. browserrig/scripts/reset.js +4 -0
  133. browserrig/scripts/scroll.js +5 -0
  134. browserrig/scripts/secret_field.js +7 -0
  135. browserrig/scripts/secret_focus.js +31 -0
  136. browserrig/scripts/seed.js +13 -0
  137. browserrig/scripts/stability.js +140 -0
  138. browserrig/scripts/tab_strip.js +27 -0
  139. browserrig/scripts/viewport.js +3 -0
  140. browserrig/secrets/__init__.py +5 -0
  141. browserrig/secrets/models.py +90 -0
  142. browserrig/secrets/origin.py +95 -0
  143. browserrig/secrets/plugin.py +397 -0
  144. browserrig/secrets/redaction.py +107 -0
  145. browserrig/secrets/state.py +6 -0
  146. browserrig/secrets/totp.py +62 -0
  147. browserrig/terminal.py +120 -0
  148. browserrig/tools/__init__.py +51 -0
  149. browserrig/tools/chains.py +55 -0
  150. browserrig/tools/dialogs.py +23 -0
  151. browserrig/tools/effects.py +8 -0
  152. browserrig/tools/execution.py +333 -0
  153. browserrig/tools/files.py +411 -0
  154. browserrig/tools/find.py +125 -0
  155. browserrig/tools/forms.py +76 -0
  156. browserrig/tools/intents.py +82 -0
  157. browserrig/tools/javascript.py +37 -0
  158. browserrig/tools/keyboard.py +126 -0
  159. browserrig/tools/mouse.py +224 -0
  160. browserrig/tools/navigation.py +189 -0
  161. browserrig/tools/scrolling.py +39 -0
  162. browserrig/tools/tabs.py +81 -0
  163. browserrig/tools/targeting.py +59 -0
  164. browserrig-0.1.0.dist-info/METADATA +174 -0
  165. browserrig-0.1.0.dist-info/RECORD +167 -0
  166. browserrig-0.1.0.dist-info/WHEEL +4 -0
  167. browserrig-0.1.0.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,366 @@
1
+ from __future__ import annotations
2
+
3
+ import asyncio
4
+ from collections.abc import Callable
5
+ from contextlib import AsyncExitStack, suppress
6
+ from pathlib import Path
7
+ from typing import TYPE_CHECKING
8
+
9
+ from cdpify import CdpClient, CdpSession
10
+ from cdpify.domains.page import FrameNavigatedEvent
11
+ from cdpify.domains.runtime import (
12
+ ExecutionContextDestroyedEvent,
13
+ ExecutionContextsClearedEvent,
14
+ )
15
+ from cdpify.domains.target import (
16
+ TargetDestroyedEvent,
17
+ TargetInfo,
18
+ TargetInfoChangedEvent,
19
+ )
20
+
21
+ from browserrig.core import BrowserError, TabGesture, TargetId
22
+ from browserrig.events import TabActivatedEvent, TabClosedEvent, TabOpenedEvent
23
+ from browserrig.input import Input
24
+
25
+ from .config import BrowserOptions
26
+ from .frame import Frame
27
+ from .frames import discover_frames
28
+ from .models import TabInfo
29
+ from .tab import Tab, TabListener, validated_url
30
+ from .worlds import Worlds
31
+
32
+ if TYPE_CHECKING:
33
+ from .base import EventSink
34
+
35
+
36
+ class Tabs:
37
+ """The browser's controlled tabs, their sessions and active document."""
38
+
39
+ def __init__(
40
+ self,
41
+ options: BrowserOptions,
42
+ devices: Input,
43
+ *,
44
+ check: Callable[[], None],
45
+ emit: EventSink,
46
+ on_change: TabListener | None = None,
47
+ ) -> None:
48
+ self._options = options
49
+ self._input = devices
50
+ self._check = check
51
+ self._emit = emit
52
+ self._on_tab_change = on_change
53
+ self._tabs: dict[TargetId, Tab] = {}
54
+ self._active = ""
55
+ self._context: str | None = None
56
+ self._target_context: str | None = None
57
+ self._sessions: dict[str, str] = {}
58
+ self._closed_targets: set[TargetId] = set()
59
+ self._worlds = Worlds()
60
+ self._attach_lock = asyncio.Lock()
61
+ self._stack: AsyncExitStack | None = None
62
+ self.client: CdpClient
63
+
64
+ @property
65
+ def active(self) -> Tab:
66
+ tab = self.focused()
67
+ if tab is None:
68
+ raise BrowserError("No active tab; open or explicitly activate one")
69
+ return tab
70
+
71
+ async def start(self, client: CdpClient, stack: AsyncExitStack) -> str | None:
72
+ """Bind the connection and create its controlled browser context."""
73
+ self.client = client
74
+ self._stack = stack
75
+ await self._create_context()
76
+ return self._context
77
+
78
+ async def open_initial(self) -> None:
79
+ if self._options.target_id is None:
80
+ await self.open(self._options.url)
81
+ return
82
+ tab = await self._attach(self._options.target_id)
83
+ await self._input.mouse.switch_tab(
84
+ TabGesture.ACTIVATE, tab.id, lambda: self._focus(tab, front=False)
85
+ )
86
+
87
+ async def discard(self) -> None:
88
+ for tab in tuple(self._tabs.values()):
89
+ await tab.discard()
90
+
91
+ async def list(self) -> tuple[TabInfo, ...]:
92
+ self._check()
93
+ targets = await self._targets()
94
+ self._closed_targets.intersection_update(info.target_id for info in targets)
95
+ found = []
96
+ for info in targets:
97
+ if info.target_id in self._closed_targets:
98
+ continue
99
+ if info.type != "page":
100
+ continue
101
+ if self._context is not None and info.browser_context_id != self._context:
102
+ continue
103
+ if self._context is None and info.target_id not in self._tabs:
104
+ continue
105
+ found.append(
106
+ TabInfo(
107
+ id=info.target_id,
108
+ title=info.title,
109
+ url=info.url,
110
+ active=info.target_id == self._active,
111
+ )
112
+ )
113
+ return tuple(found)
114
+
115
+ async def open(self, target: str | Path = "about:blank") -> Tab:
116
+ """Open a URL, or a local file that calling code has already vetted.
117
+
118
+ Strings may come from the model and are limited to HTTP(S) and about:blank.
119
+ A `Path` opens as file:// without checks; resolve it through `files` first.
120
+ """
121
+ url = (
122
+ target.absolute().as_uri()
123
+ if isinstance(target, Path)
124
+ else validated_url(target)
125
+ )
126
+ self._check()
127
+ opened: list[Tab] = []
128
+
129
+ async def open_new() -> None:
130
+ opened.append(await self._create(url))
131
+ await self._focus(opened[0], front=False)
132
+
133
+ await self._input.mouse.switch_tab(TabGesture.OPEN, "", open_new)
134
+ return opened[0]
135
+
136
+ async def activate(self, target_id: str) -> Tab:
137
+ if target_id not in {tab.id for tab in await self.list()}:
138
+ raise BrowserError("Target is outside this browser's controlled scope")
139
+ tab = await self._attach(target_id)
140
+ if tab.id == self._active:
141
+ # Already in front: nothing to press, but late viewers still need the cursor.
142
+ await tab.bring_to_front()
143
+ await self._emit(
144
+ TabActivatedEvent(target_id=tab.id, document_id=tab.document_id)
145
+ )
146
+ await self._input.mouse.publish_cursor()
147
+ return tab
148
+ await self._input.mouse.switch_tab(
149
+ TabGesture.ACTIVATE, tab.id, lambda: self._focus(tab)
150
+ )
151
+ return tab
152
+
153
+ async def close(self, target_id: str) -> Tab:
154
+ if target_id not in {tab.id for tab in await self.list()}:
155
+ raise BrowserError("Target is outside this browser's controlled scope")
156
+
157
+ async def close() -> None:
158
+ await self.client.target.close_target(target_id=target_id)
159
+ await self._forget(target_id)
160
+ if self.focused() is not None:
161
+ return
162
+ remaining = [tab for tab in await self.list() if tab.id != target_id]
163
+ if remaining:
164
+ await self._focus(await self._attach(remaining[0].id))
165
+ else:
166
+ await self._focus(await self._create("about:blank"), front=False)
167
+
168
+ await self._input.mouse.switch_tab(TabGesture.CLOSE, target_id, close)
169
+ return self.active
170
+
171
+ def focused(self) -> Tab | None:
172
+ self._check()
173
+ tab = self._tabs.get(self._active)
174
+ return None if tab is None or tab.closed else tab
175
+
176
+ async def handle(self, event: object, session_id: str | None) -> None:
177
+ if session_id is None:
178
+ match event:
179
+ case TargetInfoChangedEvent(target_info=info):
180
+ await self._on_target_info(info)
181
+ case TargetDestroyedEvent(target_id=target_id):
182
+ await self._forget(target_id)
183
+ return
184
+ self._invalidate_contexts(event, session_id)
185
+ if tab := self._tabs.get(self._sessions.get(session_id, "")):
186
+ await tab.handle(event)
187
+
188
+ async def _create_context(self) -> None:
189
+ options = self._options
190
+ if options.target_id is not None:
191
+ target = await self.client.target.get_target_info(
192
+ target_id=options.target_id
193
+ )
194
+ self._target_context = target.target_info.browser_context_id
195
+ return
196
+ assert self._stack is not None
197
+ context = await self.client.target.create_browser_context(
198
+ dispose_on_detach=True
199
+ )
200
+ self._context = context.browser_context_id
201
+ self._stack.push_async_callback(
202
+ self.client.target.dispose_browser_context, browser_context_id=self._context
203
+ )
204
+
205
+ async def _create(self, url: str) -> Tab:
206
+ result = await self.client.target.create_target(
207
+ url=url, browser_context_id=self._context or self._target_context
208
+ )
209
+ return await self._attach(result.target_id, opened=True)
210
+
211
+ async def _focus(self, tab: Tab, *, front: bool = True) -> None:
212
+ if front:
213
+ await tab.bring_to_front()
214
+ self._active = tab.id
215
+ await self._emit(
216
+ TabActivatedEvent(target_id=tab.id, document_id=tab.document_id)
217
+ )
218
+
219
+ async def _on_target_info(self, info: TargetInfo) -> None:
220
+ if known := self._tabs.get(info.target_id):
221
+ known.url, known.title = info.url, info.title
222
+ await known.report_change()
223
+ elif (
224
+ info.type == "page"
225
+ and self._context
226
+ and info.browser_context_id == self._context
227
+ ):
228
+ await self._attach(
229
+ info.target_id, opened=True, opener_id=info.opener_id or ""
230
+ )
231
+
232
+ async def _attach(
233
+ self, target_id: str, *, opened: bool = False, opener_id: str = ""
234
+ ) -> Tab:
235
+ async with self._attach_lock:
236
+ if target_id in self._tabs:
237
+ return self._tabs[target_id]
238
+ if target_id in self._closed_targets:
239
+ raise BrowserError("Target has already closed")
240
+ attached = await self.client.target.attach_to_target(
241
+ target_id=target_id, flatten=True
242
+ )
243
+ cdp = self.client.session(attached.session_id)
244
+ try:
245
+ await _enable_session(cdp, self._options)
246
+ tab = Tab(
247
+ target_id,
248
+ cdp,
249
+ emit=self._emit,
250
+ worlds=self._worlds,
251
+ discover_frames=self._discover_frames,
252
+ current_action=lambda: self._input.action_id,
253
+ on_change=self._on_tab_change,
254
+ )
255
+ await tab.sync_document()
256
+ if target_id in self._closed_targets:
257
+ raise BrowserError("Target closed while attaching")
258
+ self._tabs[target_id] = tab
259
+ self._sessions[attached.session_id] = target_id
260
+ if opened:
261
+ await self._emit(
262
+ TabOpenedEvent(
263
+ target_id=tab.id, url=tab.url, opener_id=opener_id
264
+ )
265
+ )
266
+ # A tab attached mid-session already shows a page worth reading.
267
+ await tab.report_change(settled=True)
268
+ if self._context is None:
269
+ assert self._stack is not None
270
+ self._stack.push_async_callback(self._detach, attached.session_id)
271
+ return tab
272
+ except (Exception, asyncio.CancelledError):
273
+ await self._detach(attached.session_id)
274
+ raise
275
+
276
+ async def _discover_frames(
277
+ self, tab: Tab
278
+ ) -> tuple[tuple[Frame, ...], tuple[str, ...]]:
279
+ """Resolve each frame to its own session, including cross-process targets."""
280
+ self._check()
281
+ targets = await self._targets()
282
+ live = {info.target_id for info in targets if info.type == "iframe"}
283
+ for sid, target_id in tuple(self._sessions.items()):
284
+ if target_id not in self._tabs and target_id not in live:
285
+ await self._detach(sid)
286
+ return await discover_frames(tab, targets, self._frame_session)
287
+
288
+ async def _frame_session(self, frame_id: str) -> CdpSession:
289
+ """Reuse owned OOPIF sessions; discard stale sessions when targets disappear."""
290
+ async with self._attach_lock:
291
+ sid = next(
292
+ (sid for sid, tid in self._sessions.items() if tid == frame_id), None
293
+ )
294
+ if sid is None:
295
+ attached = await self.client.target.attach_to_target(
296
+ target_id=frame_id, flatten=True
297
+ )
298
+ sid = attached.session_id
299
+ self._sessions[sid] = frame_id
300
+ assert self._stack is not None
301
+ self._stack.push_async_callback(self._detach, sid)
302
+ cdp = self.client.session(sid)
303
+ try:
304
+ await _enable_session(cdp, self._options, frame=True)
305
+ except (Exception, asyncio.CancelledError):
306
+ await self._detach(sid)
307
+ raise
308
+ return self.client.session(sid)
309
+
310
+ async def _detach(self, session_id: str) -> None:
311
+ self._sessions.pop(session_id, None)
312
+ self._worlds.invalidate(session_id=session_id)
313
+ if self.client.is_connected:
314
+ # The target may already have been destroyed by its owner.
315
+ with suppress(Exception):
316
+ await self.client.target.detach_from_target(session_id=session_id)
317
+
318
+ async def _forget(self, target_id: str) -> None:
319
+ self._closed_targets.add(target_id)
320
+ tab = self._tabs.pop(target_id, None)
321
+ for sid, tid in tuple(self._sessions.items()):
322
+ if tid == target_id:
323
+ self._sessions.pop(sid, None)
324
+ self._worlds.invalidate(session_id=sid)
325
+ if self._active == target_id:
326
+ self._active = ""
327
+ self._input.mouse.forget(target_id)
328
+ if tab is not None:
329
+ await tab.discard()
330
+ await self._emit(TabClosedEvent(target_id=target_id))
331
+
332
+ async def _targets(self) -> tuple[TargetInfo, ...]:
333
+ result = await self.client.target.get_targets()
334
+ return tuple(result.target_infos)
335
+
336
+ def _invalidate_contexts(self, event: object, session_id: str) -> None:
337
+ match event:
338
+ case ExecutionContextsClearedEvent():
339
+ self._worlds.invalidate(session_id=session_id)
340
+ case ExecutionContextDestroyedEvent(execution_context_id=context):
341
+ self._worlds.invalidate(session_id=session_id, context_id=context)
342
+ case FrameNavigatedEvent(frame=frame):
343
+ self._worlds.invalidate(frame_id=frame.id)
344
+ for tab in self._tabs.values():
345
+ tab.layout_changed()
346
+
347
+
348
+ async def _enable_session(
349
+ cdp: CdpSession, options: BrowserOptions, *, frame: bool = False
350
+ ) -> None:
351
+ """Enable browserrig's domains, then apply the viewport and custom setup."""
352
+ await asyncio.gather(
353
+ cdp.page.enable(),
354
+ cdp.page.set_lifecycle_events_enabled(enabled=True),
355
+ cdp.runtime.enable(),
356
+ )
357
+ viewport = options.viewport
358
+ if viewport is not None and not frame:
359
+ await cdp.emulation.set_device_metrics_override(
360
+ width=viewport.width,
361
+ height=viewport.height,
362
+ device_scale_factor=viewport.scale,
363
+ mobile=False,
364
+ )
365
+ for setup in options.session_setup:
366
+ await setup.apply(cdp, frame=frame)
@@ -0,0 +1,64 @@
1
+ import asyncio
2
+ from collections.abc import Awaitable, Callable
3
+
4
+ from cdpify import CdpSession
5
+ from cdpify.exceptions import CDPCommandError
6
+
7
+
8
+ class Worlds:
9
+ """Document-scoped isolated contexts shared by successive frame discoveries."""
10
+
11
+ def __init__(self) -> None:
12
+ self._ids: dict[tuple[str, str, str], int] = {}
13
+ self._generation = 0
14
+ self._lock = asyncio.Lock()
15
+
16
+ async def run[T](
17
+ self,
18
+ cdp: CdpSession,
19
+ frame_id: str,
20
+ document_id: str,
21
+ operation: Callable[[int], Awaitable[T]],
22
+ *,
23
+ retry: bool = True,
24
+ ) -> T:
25
+ context = await self.context(cdp, frame_id, document_id)
26
+ try:
27
+ return await operation(context)
28
+ except CDPCommandError as error:
29
+ # Only a context rejected before execution is safe to retry.
30
+ if not retry or "cannot find context" not in error.message.lower():
31
+ raise
32
+ self.invalidate(session_id=cdp.session_id, frame_id=frame_id)
33
+ return await operation(await self.context(cdp, frame_id, document_id))
34
+
35
+ async def context(self, cdp: CdpSession, frame_id: str, document_id: str) -> int:
36
+ key = (cdp.session_id, frame_id, document_id)
37
+ async with self._lock:
38
+ if key in self._ids:
39
+ return self._ids[key]
40
+ generation = self._generation
41
+ result = await cdp.page.create_isolated_world(
42
+ frame_id=frame_id, world_name="browserrig"
43
+ )
44
+ if generation == self._generation:
45
+ self._ids[key] = result.execution_context_id
46
+ return result.execution_context_id
47
+
48
+ def invalidate(
49
+ self,
50
+ *,
51
+ session_id: str | None = None,
52
+ frame_id: str | None = None,
53
+ context_id: int | None = None,
54
+ ) -> None:
55
+ self._generation += 1
56
+ self._ids = {
57
+ key: value
58
+ for key, value in self._ids.items()
59
+ if not (
60
+ (session_id is None or key[0] == session_id)
61
+ and (frame_id is None or key[1] == frame_id)
62
+ and (context_id is None or value == context_id)
63
+ )
64
+ }
@@ -0,0 +1,31 @@
1
+ """Optional staging of browser work for people watching it live."""
2
+
3
+ from .events import (
4
+ SCENE_EVENTS,
5
+ BarTypedEvent,
6
+ CursorEnteredEvent,
7
+ FileTransferEvent,
8
+ FindBarEvent,
9
+ FindResultsEvent,
10
+ HighlightElementEvent,
11
+ TabPressedEvent,
12
+ WaitingEvent,
13
+ )
14
+ from .plugin import InputVisualization
15
+ from .stage import Stage
16
+ from .tabstrip import TabStrip
17
+
18
+ __all__ = [
19
+ "SCENE_EVENTS",
20
+ "BarTypedEvent",
21
+ "InputVisualization",
22
+ "CursorEnteredEvent",
23
+ "FileTransferEvent",
24
+ "FindBarEvent",
25
+ "FindResultsEvent",
26
+ "HighlightElementEvent",
27
+ "Stage",
28
+ "TabPressedEvent",
29
+ "TabStrip",
30
+ "WaitingEvent",
31
+ ]
@@ -0,0 +1,133 @@
1
+ """Events of the staged scene: what a viewer sees beyond raw input.
2
+
3
+ They are only emitted while the `InputVisualization` plugin is mounted.
4
+ """
5
+
6
+ from dataclasses import dataclass, field
7
+ from typing import Literal
8
+
9
+ from browserrig.core import BrowserBar, FileTransferDirection, TabGesture
10
+ from browserrig.events import EventKind, InputEvent
11
+ from browserrig.observation import FindMark
12
+
13
+
14
+ @dataclass(frozen=True, slots=True)
15
+ class HighlightElementEvent(InputEvent):
16
+ ref: str
17
+ x: float
18
+ y: float
19
+ width: float
20
+ height: float
21
+ type: Literal[EventKind.HIGHLIGHT_ELEMENT] = field(
22
+ default=EventKind.HIGHLIGHT_ELEMENT, kw_only=True
23
+ )
24
+
25
+
26
+ @dataclass(frozen=True, slots=True)
27
+ class WaitingEvent(InputEvent):
28
+ duration: float
29
+ type: Literal[EventKind.WAITING] = field(default=EventKind.WAITING, kw_only=True)
30
+
31
+
32
+ @dataclass(frozen=True, slots=True)
33
+ class BarTypedEvent(InputEvent):
34
+ """One key typed into the browser's address or find bar, not into the page.
35
+
36
+ `text` is the bar's whole content after the key; `key` is "Enter" when the text is
37
+ submitted. The harness waits `duration` before the next key.
38
+ """
39
+
40
+ browser_bar: BrowserBar
41
+ key: str
42
+ text: str
43
+ duration: float
44
+ type: Literal[EventKind.BAR_TYPED] = field(
45
+ default=EventKind.BAR_TYPED, kw_only=True
46
+ )
47
+
48
+
49
+ @dataclass(frozen=True, slots=True)
50
+ class FindBarEvent(InputEvent):
51
+ """The find bar opens, as with Ctrl+F, or closes; closing removes every find marker."""
52
+
53
+ visible: bool
54
+ type: Literal[EventKind.FIND_BAR] = field(default=EventKind.FIND_BAR, kw_only=True)
55
+
56
+
57
+ @dataclass(frozen=True, slots=True)
58
+ class FindResultsEvent(InputEvent):
59
+ """Matches for the find bar's text, updated after each key and after scrolling to one.
60
+
61
+ `active` numbers the current match from 1, or is 0 without one, of `total`. `marks`
62
+ covers the matches in the viewport, in viewport CSS pixels: viewers draw them like a
63
+ browser's find highlights, the active one distinct. They hold until the next results
64
+ event or until the find bar closes; the page shows the same markers meanwhile.
65
+ """
66
+
67
+ query: str
68
+ total: int
69
+ active: int
70
+ marks: tuple[FindMark, ...] = ()
71
+ type: Literal[EventKind.FIND_RESULTS] = field(
72
+ default=EventKind.FIND_RESULTS, kw_only=True
73
+ )
74
+
75
+
76
+ @dataclass(frozen=True, slots=True)
77
+ class FileTransferEvent(InputEvent):
78
+ """Files move into a new tab or onto a page element; the harness waits for `duration`."""
79
+
80
+ direction: FileTransferDirection
81
+ paths: tuple[str, ...]
82
+ duration: float
83
+ x: float | None = None
84
+ y: float | None = None
85
+ type: Literal[EventKind.FILE_TRANSFER] = field(
86
+ default=EventKind.FILE_TRANSFER, kw_only=True
87
+ )
88
+
89
+
90
+ @dataclass(frozen=True, slots=True)
91
+ class TabPressedEvent(InputEvent):
92
+ """The pointer leaves the page and presses a control in the viewer's tab strip.
93
+
94
+ The event belongs to the tab the pointer leaves, starting at `from_position`.
95
+ `tab_id` names the pressed tab; it is empty for the new-tab button. Viewers place
96
+ the control themselves; the harness waits `duration` before switching tabs.
97
+ """
98
+
99
+ gesture: TabGesture
100
+ tab_id: str
101
+ from_position: tuple[float, float]
102
+ duration: float
103
+ type: Literal[EventKind.TAB_PRESSED] = field(
104
+ default=EventKind.TAB_PRESSED, kw_only=True
105
+ )
106
+
107
+
108
+ @dataclass(frozen=True, slots=True)
109
+ class CursorEnteredEvent(InputEvent):
110
+ """After a tab press, the pointer returns from the tab strip into this tab's page.
111
+
112
+ It travels to `to_position`, where this tab last had the pointer; the harness waits
113
+ `duration` before dispatching native input there.
114
+ """
115
+
116
+ to_position: tuple[float, float]
117
+ duration: float
118
+ easing: Literal["easeInOutCubic"] = "easeInOutCubic"
119
+ type: Literal[EventKind.CURSOR_ENTERED] = field(
120
+ default=EventKind.CURSOR_ENTERED, kw_only=True
121
+ )
122
+
123
+
124
+ SCENE_EVENTS = (
125
+ HighlightElementEvent,
126
+ WaitingEvent,
127
+ BarTypedEvent,
128
+ FindBarEvent,
129
+ FindResultsEvent,
130
+ FileTransferEvent,
131
+ TabPressedEvent,
132
+ CursorEnteredEvent,
133
+ )
@@ -0,0 +1,75 @@
1
+ from typing import Any
2
+
3
+ from harnessed import Context, Plugin, hook
4
+ from harnessed.events import TurnStartedEvent
5
+ from harnessed.hooks import Next
6
+ from harnessed.kernel import dependency
7
+
8
+ from browserrig.browser import Browser
9
+ from browserrig.events import INPUT_EVENTS
10
+ from browserrig.tools import (
11
+ FindIntent,
12
+ NavigateIntent,
13
+ OpenFileIntent,
14
+ Perform,
15
+ TargetLocated,
16
+ UploadIntent,
17
+ WaitIntent,
18
+ )
19
+
20
+ from . import scenes
21
+ from .events import SCENE_EVENTS, HighlightElementEvent
22
+ from .stage import Stage
23
+
24
+
25
+ class InputVisualization(Plugin, slot="browserrig.choreography"):
26
+ """Stage the browser for people watching: visible input and browser UI.
27
+
28
+ Tools and input devices only describe what they do. This plugin streams input as
29
+ live events, shows browser UI such as the address and find bars and highlights the
30
+ elements tools act on. How fast input runs is up to `InputPacing`. Without this plugin
31
+ no input events are emitted.
32
+ """
33
+
34
+ events = INPUT_EVENTS + SCENE_EVENTS
35
+ _browser = dependency(Browser)
36
+
37
+ async def setup(self, ctx: Context) -> None:
38
+ inputs = self._browser.input
39
+ ctx.effect(inputs.present(Stage(lambda: inputs.action_id)))
40
+
41
+ async def publish_cursor(_event: TurnStartedEvent) -> None:
42
+ # Live subscribers often attach late, so seed their cursor at turn start.
43
+ await inputs.mouse.publish_cursor()
44
+
45
+ ctx.on(TurnStartedEvent, publish_cursor)
46
+
47
+ @hook(Perform)
48
+ async def _stage(self, event: Perform, next_: Next[Any]) -> Any:
49
+ scene = scenes.Scene(event.tab, event.action_id)
50
+ match event.intent:
51
+ case FindIntent() as intent:
52
+ return await scenes.find(scene, intent, next_)
53
+ case NavigateIntent() as intent:
54
+ return await scenes.navigate(scene, intent, next_)
55
+ case WaitIntent() as intent:
56
+ return await scenes.wait(scene, intent, next_)
57
+ case OpenFileIntent() as intent:
58
+ return await scenes.open_file(scene, intent, next_)
59
+ case UploadIntent() as intent:
60
+ return await scenes.upload(scene, intent, next_)
61
+ return await next_()
62
+
63
+ @hook(TargetLocated)
64
+ async def _highlight(self, event: TargetLocated) -> None:
65
+ bounds = event.bounds
66
+ await event.tab.emit(
67
+ HighlightElementEvent(
68
+ ref=event.ref,
69
+ x=bounds.x,
70
+ y=bounds.y,
71
+ width=bounds.width,
72
+ height=bounds.height,
73
+ action_id=event.action_id,
74
+ )
75
+ )