athena-browser-mcp 1.0.3 → 2.0.1

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 (406) hide show
  1. package/README.md +131 -300
  2. package/dist/src/browser/index.d.ts +8 -0
  3. package/dist/src/browser/index.d.ts.map +1 -0
  4. package/dist/src/browser/index.js +8 -0
  5. package/dist/src/browser/index.js.map +1 -0
  6. package/dist/src/browser/page-registry.d.ts +126 -0
  7. package/dist/src/browser/page-registry.d.ts.map +1 -0
  8. package/dist/src/browser/page-registry.js +185 -0
  9. package/dist/src/browser/page-registry.js.map +1 -0
  10. package/dist/src/browser/session-manager.d.ts +246 -0
  11. package/dist/src/browser/session-manager.d.ts.map +1 -0
  12. package/dist/src/browser/session-manager.js +619 -0
  13. package/dist/src/browser/session-manager.js.map +1 -0
  14. package/dist/src/cdp/cdp-client.interface.d.ts +184 -0
  15. package/dist/src/cdp/cdp-client.interface.d.ts.map +1 -0
  16. package/dist/src/cdp/cdp-client.interface.js +9 -0
  17. package/dist/src/cdp/cdp-client.interface.js.map +1 -0
  18. package/dist/src/cdp/index.d.ts +9 -0
  19. package/dist/src/cdp/index.d.ts.map +1 -0
  20. package/dist/src/cdp/index.js +8 -0
  21. package/dist/src/cdp/index.js.map +1 -0
  22. package/dist/src/cdp/playwright-cdp-client.d.ts +84 -0
  23. package/dist/src/cdp/playwright-cdp-client.d.ts.map +1 -0
  24. package/dist/src/cdp/playwright-cdp-client.js +239 -0
  25. package/dist/src/cdp/playwright-cdp-client.js.map +1 -0
  26. package/dist/src/factpack/action-selector.d.ts +36 -0
  27. package/dist/src/factpack/action-selector.d.ts.map +1 -0
  28. package/dist/src/factpack/action-selector.js +367 -0
  29. package/dist/src/factpack/action-selector.js.map +1 -0
  30. package/dist/src/factpack/dialog-detector.d.ts +19 -0
  31. package/dist/src/factpack/dialog-detector.d.ts.map +1 -0
  32. package/dist/src/factpack/dialog-detector.js +354 -0
  33. package/dist/src/factpack/dialog-detector.js.map +1 -0
  34. package/dist/src/factpack/form-detector.d.ts +28 -0
  35. package/dist/src/factpack/form-detector.d.ts.map +1 -0
  36. package/dist/src/factpack/form-detector.js +555 -0
  37. package/dist/src/factpack/form-detector.js.map +1 -0
  38. package/dist/src/factpack/index.d.ts +32 -0
  39. package/dist/src/factpack/index.d.ts.map +1 -0
  40. package/dist/src/factpack/index.js +73 -0
  41. package/dist/src/factpack/index.js.map +1 -0
  42. package/dist/src/factpack/page-classifier.d.ts +22 -0
  43. package/dist/src/factpack/page-classifier.d.ts.map +1 -0
  44. package/dist/src/factpack/page-classifier.js +526 -0
  45. package/dist/src/factpack/page-classifier.js.map +1 -0
  46. package/dist/src/factpack/types.d.ts +307 -0
  47. package/dist/src/factpack/types.d.ts.map +1 -0
  48. package/dist/src/factpack/types.js +12 -0
  49. package/dist/src/factpack/types.js.map +1 -0
  50. package/dist/src/index.d.ts +6 -2
  51. package/dist/src/index.d.ts.map +1 -1
  52. package/dist/src/index.js +130 -83
  53. package/dist/src/index.js.map +1 -1
  54. package/dist/src/lib/constants.d.ts +27 -0
  55. package/dist/src/lib/constants.d.ts.map +1 -0
  56. package/dist/src/lib/constants.js +63 -0
  57. package/dist/src/lib/constants.js.map +1 -0
  58. package/dist/src/lib/index.d.ts +12 -0
  59. package/dist/src/lib/index.d.ts.map +1 -0
  60. package/dist/src/lib/index.js +17 -0
  61. package/dist/src/lib/index.js.map +1 -0
  62. package/dist/src/lib/regions.d.ts +29 -0
  63. package/dist/src/lib/regions.d.ts.map +1 -0
  64. package/dist/src/lib/regions.js +93 -0
  65. package/dist/src/lib/regions.js.map +1 -0
  66. package/dist/src/lib/scoring.d.ts +47 -0
  67. package/dist/src/lib/scoring.d.ts.map +1 -0
  68. package/dist/src/lib/scoring.js +79 -0
  69. package/dist/src/lib/scoring.js.map +1 -0
  70. package/dist/src/lib/selectors.d.ts +42 -0
  71. package/dist/src/lib/selectors.d.ts.map +1 -0
  72. package/dist/src/lib/selectors.js +138 -0
  73. package/dist/src/lib/selectors.js.map +1 -0
  74. package/dist/src/lib/text-utils.d.ts +138 -0
  75. package/dist/src/lib/text-utils.d.ts.map +1 -0
  76. package/dist/src/lib/text-utils.js +347 -0
  77. package/dist/src/lib/text-utils.js.map +1 -0
  78. package/dist/src/query/index.d.ts +9 -0
  79. package/dist/src/query/index.d.ts.map +1 -0
  80. package/dist/src/query/index.js +10 -0
  81. package/dist/src/query/index.js.map +1 -0
  82. package/dist/src/query/query-engine.d.ts +111 -0
  83. package/dist/src/query/query-engine.d.ts.map +1 -0
  84. package/dist/src/query/query-engine.js +509 -0
  85. package/dist/src/query/query-engine.js.map +1 -0
  86. package/dist/src/query/types/index.d.ts +5 -0
  87. package/dist/src/query/types/index.d.ts.map +1 -0
  88. package/dist/src/query/types/index.js +5 -0
  89. package/dist/src/query/types/index.js.map +1 -0
  90. package/dist/src/query/types/query.types.d.ts +141 -0
  91. package/dist/src/query/types/query.types.d.ts.map +1 -0
  92. package/dist/src/query/types/query.types.js +19 -0
  93. package/dist/src/query/types/query.types.js.map +1 -0
  94. package/dist/src/renderer/budget-manager.d.ts +46 -0
  95. package/dist/src/renderer/budget-manager.d.ts.map +1 -0
  96. package/dist/src/renderer/budget-manager.js +133 -0
  97. package/dist/src/renderer/budget-manager.js.map +1 -0
  98. package/dist/src/renderer/constants.d.ts +38 -0
  99. package/dist/src/renderer/constants.d.ts.map +1 -0
  100. package/dist/src/renderer/constants.js +29 -0
  101. package/dist/src/renderer/constants.js.map +1 -0
  102. package/dist/src/renderer/index.d.ts +12 -0
  103. package/dist/src/renderer/index.d.ts.map +1 -0
  104. package/dist/src/renderer/index.js +16 -0
  105. package/dist/src/renderer/index.js.map +1 -0
  106. package/dist/src/renderer/section-renderers.d.ts +42 -0
  107. package/dist/src/renderer/section-renderers.d.ts.map +1 -0
  108. package/dist/src/renderer/section-renderers.js +252 -0
  109. package/dist/src/renderer/section-renderers.js.map +1 -0
  110. package/dist/src/renderer/token-counter.d.ts +45 -0
  111. package/dist/src/renderer/token-counter.d.ts.map +1 -0
  112. package/dist/src/renderer/token-counter.js +65 -0
  113. package/dist/src/renderer/token-counter.js.map +1 -0
  114. package/dist/src/renderer/types.d.ts +71 -0
  115. package/dist/src/renderer/types.d.ts.map +1 -0
  116. package/dist/src/renderer/types.js +7 -0
  117. package/dist/src/renderer/types.js.map +1 -0
  118. package/dist/src/renderer/xml-renderer.d.ts +42 -0
  119. package/dist/src/renderer/xml-renderer.d.ts.map +1 -0
  120. package/dist/src/renderer/xml-renderer.js +103 -0
  121. package/dist/src/renderer/xml-renderer.js.map +1 -0
  122. package/dist/src/server/index.d.ts +8 -0
  123. package/dist/src/server/index.d.ts.map +1 -0
  124. package/dist/src/server/index.js +8 -0
  125. package/dist/src/server/index.js.map +1 -0
  126. package/dist/src/server/mcp-server.d.ts +24 -30
  127. package/dist/src/server/mcp-server.d.ts.map +1 -1
  128. package/dist/src/server/mcp-server.js +68 -321
  129. package/dist/src/server/mcp-server.js.map +1 -1
  130. package/dist/src/server/session-store.d.ts +148 -0
  131. package/dist/src/server/session-store.d.ts.map +1 -0
  132. package/dist/src/server/session-store.js +224 -0
  133. package/dist/src/server/session-store.js.map +1 -0
  134. package/dist/src/shared/errors/browser-session.error.d.ts +102 -0
  135. package/dist/src/shared/errors/browser-session.error.d.ts.map +1 -0
  136. package/dist/src/shared/errors/browser-session.error.js +153 -0
  137. package/dist/src/shared/errors/browser-session.error.js.map +1 -0
  138. package/dist/src/shared/errors/index.d.ts +2 -6
  139. package/dist/src/shared/errors/index.d.ts.map +1 -1
  140. package/dist/src/shared/errors/index.js +2 -6
  141. package/dist/src/shared/errors/index.js.map +1 -1
  142. package/dist/src/shared/services/index.d.ts +1 -3
  143. package/dist/src/shared/services/index.d.ts.map +1 -1
  144. package/dist/src/shared/services/index.js +1 -3
  145. package/dist/src/shared/services/index.js.map +1 -1
  146. package/dist/src/shared/services/logging.service.d.ts +10 -1
  147. package/dist/src/shared/services/logging.service.d.ts.map +1 -1
  148. package/dist/src/shared/services/logging.service.js +11 -1
  149. package/dist/src/shared/services/logging.service.js.map +1 -1
  150. package/dist/src/shared/services/selector-builder.service.d.ts +3 -6
  151. package/dist/src/shared/services/selector-builder.service.d.ts.map +1 -1
  152. package/dist/src/shared/services/selector-builder.service.js +42 -34
  153. package/dist/src/shared/services/selector-builder.service.js.map +1 -1
  154. package/dist/src/shared/types/base.types.d.ts +23 -81
  155. package/dist/src/shared/types/base.types.d.ts.map +1 -1
  156. package/dist/src/shared/types/base.types.js +4 -1
  157. package/dist/src/shared/types/base.types.js.map +1 -1
  158. package/dist/src/snapshot/element-resolver.d.ts +102 -0
  159. package/dist/src/snapshot/element-resolver.d.ts.map +1 -0
  160. package/dist/src/snapshot/element-resolver.js +379 -0
  161. package/dist/src/snapshot/element-resolver.js.map +1 -0
  162. package/dist/src/snapshot/extractors/attribute-extractor.d.ts +40 -0
  163. package/dist/src/snapshot/extractors/attribute-extractor.d.ts.map +1 -0
  164. package/dist/src/snapshot/extractors/attribute-extractor.js +237 -0
  165. package/dist/src/snapshot/extractors/attribute-extractor.js.map +1 -0
  166. package/dist/src/snapshot/extractors/ax-extractor.d.ts +31 -0
  167. package/dist/src/snapshot/extractors/ax-extractor.d.ts.map +1 -0
  168. package/dist/src/snapshot/extractors/ax-extractor.js +106 -0
  169. package/dist/src/snapshot/extractors/ax-extractor.js.map +1 -0
  170. package/dist/src/snapshot/extractors/dom-extractor.d.ts +21 -0
  171. package/dist/src/snapshot/extractors/dom-extractor.d.ts.map +1 -0
  172. package/dist/src/snapshot/extractors/dom-extractor.js +137 -0
  173. package/dist/src/snapshot/extractors/dom-extractor.js.map +1 -0
  174. package/dist/src/snapshot/extractors/grouping-resolver.d.ts +39 -0
  175. package/dist/src/snapshot/extractors/grouping-resolver.d.ts.map +1 -0
  176. package/dist/src/snapshot/extractors/grouping-resolver.js +260 -0
  177. package/dist/src/snapshot/extractors/grouping-resolver.js.map +1 -0
  178. package/dist/src/snapshot/extractors/index.d.ts +19 -0
  179. package/dist/src/snapshot/extractors/index.d.ts.map +1 -0
  180. package/dist/src/snapshot/extractors/index.js +27 -0
  181. package/dist/src/snapshot/extractors/index.js.map +1 -0
  182. package/dist/src/snapshot/extractors/label-resolver.d.ts +44 -0
  183. package/dist/src/snapshot/extractors/label-resolver.d.ts.map +1 -0
  184. package/dist/src/snapshot/extractors/label-resolver.js +173 -0
  185. package/dist/src/snapshot/extractors/label-resolver.js.map +1 -0
  186. package/dist/src/snapshot/extractors/layout-extractor.d.ts +52 -0
  187. package/dist/src/snapshot/extractors/layout-extractor.d.ts.map +1 -0
  188. package/dist/src/snapshot/extractors/layout-extractor.js +369 -0
  189. package/dist/src/snapshot/extractors/layout-extractor.js.map +1 -0
  190. package/dist/src/snapshot/extractors/locator-builder.d.ts +27 -0
  191. package/dist/src/snapshot/extractors/locator-builder.d.ts.map +1 -0
  192. package/dist/src/snapshot/extractors/locator-builder.js +223 -0
  193. package/dist/src/snapshot/extractors/locator-builder.js.map +1 -0
  194. package/dist/src/snapshot/extractors/region-resolver.d.ts +31 -0
  195. package/dist/src/snapshot/extractors/region-resolver.d.ts.map +1 -0
  196. package/dist/src/snapshot/extractors/region-resolver.js +168 -0
  197. package/dist/src/snapshot/extractors/region-resolver.js.map +1 -0
  198. package/dist/src/snapshot/extractors/state-extractor.d.ts +30 -0
  199. package/dist/src/snapshot/extractors/state-extractor.d.ts.map +1 -0
  200. package/dist/src/snapshot/extractors/state-extractor.js +181 -0
  201. package/dist/src/snapshot/extractors/state-extractor.js.map +1 -0
  202. package/dist/src/snapshot/extractors/types.d.ts +208 -0
  203. package/dist/src/snapshot/extractors/types.d.ts.map +1 -0
  204. package/dist/src/snapshot/extractors/types.js +145 -0
  205. package/dist/src/snapshot/extractors/types.js.map +1 -0
  206. package/dist/src/snapshot/index.d.ts +14 -0
  207. package/dist/src/snapshot/index.d.ts.map +1 -0
  208. package/dist/src/snapshot/index.js +18 -0
  209. package/dist/src/snapshot/index.js.map +1 -0
  210. package/dist/src/snapshot/snapshot-compiler.d.ts +73 -0
  211. package/dist/src/snapshot/snapshot-compiler.d.ts.map +1 -0
  212. package/dist/src/snapshot/snapshot-compiler.js +689 -0
  213. package/dist/src/snapshot/snapshot-compiler.js.map +1 -0
  214. package/dist/src/snapshot/snapshot-store.d.ts +137 -0
  215. package/dist/src/snapshot/snapshot-store.d.ts.map +1 -0
  216. package/dist/src/snapshot/snapshot-store.js +202 -0
  217. package/dist/src/snapshot/snapshot-store.js.map +1 -0
  218. package/dist/src/snapshot/snapshot.types.d.ts +236 -0
  219. package/dist/src/snapshot/snapshot.types.d.ts.map +1 -0
  220. package/dist/src/snapshot/snapshot.types.js +54 -0
  221. package/dist/src/snapshot/snapshot.types.js.map +1 -0
  222. package/dist/src/tools/browser-tools.d.ts +165 -0
  223. package/dist/src/tools/browser-tools.d.ts.map +1 -0
  224. package/dist/src/tools/browser-tools.js +932 -0
  225. package/dist/src/tools/browser-tools.js.map +1 -0
  226. package/dist/src/tools/index.d.ts +10 -0
  227. package/dist/src/tools/index.d.ts.map +1 -0
  228. package/dist/src/tools/index.js +54 -0
  229. package/dist/src/tools/index.js.map +1 -0
  230. package/dist/src/tools/tool-schemas.d.ts +10884 -0
  231. package/dist/src/tools/tool-schemas.d.ts.map +1 -0
  232. package/dist/src/tools/tool-schemas.js +883 -0
  233. package/dist/src/tools/tool-schemas.js.map +1 -0
  234. package/package.json +5 -3
  235. package/dist/src/bridge/cef-bridge.d.ts +0 -115
  236. package/dist/src/bridge/cef-bridge.d.ts.map +0 -1
  237. package/dist/src/bridge/cef-bridge.js +0 -417
  238. package/dist/src/bridge/cef-bridge.js.map +0 -1
  239. package/dist/src/domains/interaction/handlers/action.handler.d.ts +0 -72
  240. package/dist/src/domains/interaction/handlers/action.handler.d.ts.map +0 -1
  241. package/dist/src/domains/interaction/handlers/action.handler.js +0 -304
  242. package/dist/src/domains/interaction/handlers/action.handler.js.map +0 -1
  243. package/dist/src/domains/interaction/handlers/form.handler.d.ts +0 -66
  244. package/dist/src/domains/interaction/handlers/form.handler.d.ts.map +0 -1
  245. package/dist/src/domains/interaction/handlers/form.handler.js +0 -180
  246. package/dist/src/domains/interaction/handlers/form.handler.js.map +0 -1
  247. package/dist/src/domains/interaction/handlers/index.d.ts +0 -7
  248. package/dist/src/domains/interaction/handlers/index.d.ts.map +0 -1
  249. package/dist/src/domains/interaction/handlers/index.js +0 -7
  250. package/dist/src/domains/interaction/handlers/index.js.map +0 -1
  251. package/dist/src/domains/interaction/handlers/keyboard.handler.d.ts +0 -44
  252. package/dist/src/domains/interaction/handlers/keyboard.handler.d.ts.map +0 -1
  253. package/dist/src/domains/interaction/handlers/keyboard.handler.js +0 -247
  254. package/dist/src/domains/interaction/handlers/keyboard.handler.js.map +0 -1
  255. package/dist/src/domains/interaction/interaction.schemas.d.ts +0 -2463
  256. package/dist/src/domains/interaction/interaction.schemas.d.ts.map +0 -1
  257. package/dist/src/domains/interaction/interaction.schemas.js +0 -162
  258. package/dist/src/domains/interaction/interaction.schemas.js.map +0 -1
  259. package/dist/src/domains/interaction/interaction.types.d.ts +0 -134
  260. package/dist/src/domains/interaction/interaction.types.d.ts.map +0 -1
  261. package/dist/src/domains/interaction/interaction.types.js +0 -7
  262. package/dist/src/domains/interaction/interaction.types.js.map +0 -1
  263. package/dist/src/domains/interaction/strategies/accessibility-click.strategy.d.ts +0 -24
  264. package/dist/src/domains/interaction/strategies/accessibility-click.strategy.d.ts.map +0 -1
  265. package/dist/src/domains/interaction/strategies/accessibility-click.strategy.js +0 -69
  266. package/dist/src/domains/interaction/strategies/accessibility-click.strategy.js.map +0 -1
  267. package/dist/src/domains/interaction/strategies/bbox-click.strategy.d.ts +0 -28
  268. package/dist/src/domains/interaction/strategies/bbox-click.strategy.d.ts.map +0 -1
  269. package/dist/src/domains/interaction/strategies/bbox-click.strategy.js +0 -54
  270. package/dist/src/domains/interaction/strategies/bbox-click.strategy.js.map +0 -1
  271. package/dist/src/domains/interaction/strategies/click-strategy.interface.d.ts +0 -24
  272. package/dist/src/domains/interaction/strategies/click-strategy.interface.d.ts.map +0 -1
  273. package/dist/src/domains/interaction/strategies/click-strategy.interface.js +0 -7
  274. package/dist/src/domains/interaction/strategies/click-strategy.interface.js.map +0 -1
  275. package/dist/src/domains/interaction/strategies/dom-click.strategy.d.ts +0 -40
  276. package/dist/src/domains/interaction/strategies/dom-click.strategy.d.ts.map +0 -1
  277. package/dist/src/domains/interaction/strategies/dom-click.strategy.js +0 -135
  278. package/dist/src/domains/interaction/strategies/dom-click.strategy.js.map +0 -1
  279. package/dist/src/domains/interaction/strategies/index.d.ts +0 -8
  280. package/dist/src/domains/interaction/strategies/index.d.ts.map +0 -1
  281. package/dist/src/domains/interaction/strategies/index.js +0 -8
  282. package/dist/src/domains/interaction/strategies/index.js.map +0 -1
  283. package/dist/src/domains/navigation/handlers/index.d.ts +0 -5
  284. package/dist/src/domains/navigation/handlers/index.d.ts.map +0 -1
  285. package/dist/src/domains/navigation/handlers/index.js +0 -5
  286. package/dist/src/domains/navigation/handlers/index.js.map +0 -1
  287. package/dist/src/domains/navigation/handlers/navigation.handler.d.ts +0 -68
  288. package/dist/src/domains/navigation/handlers/navigation.handler.d.ts.map +0 -1
  289. package/dist/src/domains/navigation/handlers/navigation.handler.js +0 -246
  290. package/dist/src/domains/navigation/handlers/navigation.handler.js.map +0 -1
  291. package/dist/src/domains/navigation/navigation.schemas.d.ts +0 -115
  292. package/dist/src/domains/navigation/navigation.schemas.d.ts.map +0 -1
  293. package/dist/src/domains/navigation/navigation.schemas.js +0 -65
  294. package/dist/src/domains/navigation/navigation.schemas.js.map +0 -1
  295. package/dist/src/domains/navigation/navigation.types.d.ts +0 -70
  296. package/dist/src/domains/navigation/navigation.types.d.ts.map +0 -1
  297. package/dist/src/domains/navigation/navigation.types.js +0 -7
  298. package/dist/src/domains/navigation/navigation.types.js.map +0 -1
  299. package/dist/src/domains/perception/handlers/ax-tree.handler.d.ts +0 -32
  300. package/dist/src/domains/perception/handlers/ax-tree.handler.d.ts.map +0 -1
  301. package/dist/src/domains/perception/handlers/ax-tree.handler.js +0 -60
  302. package/dist/src/domains/perception/handlers/ax-tree.handler.js.map +0 -1
  303. package/dist/src/domains/perception/handlers/content.handler.d.ts +0 -55
  304. package/dist/src/domains/perception/handlers/content.handler.d.ts.map +0 -1
  305. package/dist/src/domains/perception/handlers/content.handler.js +0 -150
  306. package/dist/src/domains/perception/handlers/content.handler.js.map +0 -1
  307. package/dist/src/domains/perception/handlers/dom-tree.handler.d.ts +0 -21
  308. package/dist/src/domains/perception/handlers/dom-tree.handler.d.ts.map +0 -1
  309. package/dist/src/domains/perception/handlers/dom-tree.handler.js +0 -40
  310. package/dist/src/domains/perception/handlers/dom-tree.handler.js.map +0 -1
  311. package/dist/src/domains/perception/handlers/index.d.ts +0 -11
  312. package/dist/src/domains/perception/handlers/index.d.ts.map +0 -1
  313. package/dist/src/domains/perception/handlers/index.js +0 -11
  314. package/dist/src/domains/perception/handlers/index.js.map +0 -1
  315. package/dist/src/domains/perception/handlers/layout.handler.d.ts +0 -30
  316. package/dist/src/domains/perception/handlers/layout.handler.d.ts.map +0 -1
  317. package/dist/src/domains/perception/handlers/layout.handler.js +0 -61
  318. package/dist/src/domains/perception/handlers/layout.handler.js.map +0 -1
  319. package/dist/src/domains/perception/handlers/network.handler.d.ts +0 -31
  320. package/dist/src/domains/perception/handlers/network.handler.d.ts.map +0 -1
  321. package/dist/src/domains/perception/handlers/network.handler.js +0 -59
  322. package/dist/src/domains/perception/handlers/network.handler.js.map +0 -1
  323. package/dist/src/domains/perception/handlers/ui-discover.handler.d.ts +0 -21
  324. package/dist/src/domains/perception/handlers/ui-discover.handler.d.ts.map +0 -1
  325. package/dist/src/domains/perception/handlers/ui-discover.handler.js +0 -37
  326. package/dist/src/domains/perception/handlers/ui-discover.handler.js.map +0 -1
  327. package/dist/src/domains/perception/handlers/vision.handler.d.ts +0 -43
  328. package/dist/src/domains/perception/handlers/vision.handler.d.ts.map +0 -1
  329. package/dist/src/domains/perception/handlers/vision.handler.js +0 -116
  330. package/dist/src/domains/perception/handlers/vision.handler.js.map +0 -1
  331. package/dist/src/domains/perception/perception.schemas.d.ts +0 -1223
  332. package/dist/src/domains/perception/perception.schemas.d.ts.map +0 -1
  333. package/dist/src/domains/perception/perception.schemas.js +0 -108
  334. package/dist/src/domains/perception/perception.schemas.js.map +0 -1
  335. package/dist/src/domains/perception/perception.types.d.ts +0 -90
  336. package/dist/src/domains/perception/perception.types.d.ts.map +0 -1
  337. package/dist/src/domains/perception/perception.types.js +0 -7
  338. package/dist/src/domains/perception/perception.types.js.map +0 -1
  339. package/dist/src/domains/session/handlers/index.d.ts +0 -5
  340. package/dist/src/domains/session/handlers/index.d.ts.map +0 -1
  341. package/dist/src/domains/session/handlers/index.js +0 -5
  342. package/dist/src/domains/session/handlers/index.js.map +0 -1
  343. package/dist/src/domains/session/handlers/session.handler.d.ts +0 -68
  344. package/dist/src/domains/session/handlers/session.handler.d.ts.map +0 -1
  345. package/dist/src/domains/session/handlers/session.handler.js +0 -225
  346. package/dist/src/domains/session/handlers/session.handler.js.map +0 -1
  347. package/dist/src/domains/session/session.schemas.d.ts +0 -483
  348. package/dist/src/domains/session/session.schemas.d.ts.map +0 -1
  349. package/dist/src/domains/session/session.schemas.js +0 -61
  350. package/dist/src/domains/session/session.schemas.js.map +0 -1
  351. package/dist/src/domains/session/session.types.d.ts +0 -64
  352. package/dist/src/domains/session/session.types.d.ts.map +0 -1
  353. package/dist/src/domains/session/session.types.js +0 -7
  354. package/dist/src/domains/session/session.types.js.map +0 -1
  355. package/dist/src/server/tool-registry.d.ts +0 -53
  356. package/dist/src/server/tool-registry.d.ts.map +0 -1
  357. package/dist/src/server/tool-registry.js +0 -39
  358. package/dist/src/server/tool-registry.js.map +0 -1
  359. package/dist/src/server/types.d.ts +0 -46
  360. package/dist/src/server/types.d.ts.map +0 -1
  361. package/dist/src/server/types.js +0 -7
  362. package/dist/src/server/types.js.map +0 -1
  363. package/dist/src/shared/errors/error-codes.d.ts +0 -52
  364. package/dist/src/shared/errors/error-codes.d.ts.map +0 -1
  365. package/dist/src/shared/errors/error-codes.js +0 -63
  366. package/dist/src/shared/errors/error-codes.js.map +0 -1
  367. package/dist/src/shared/errors/error-response.d.ts +0 -61
  368. package/dist/src/shared/errors/error-response.d.ts.map +0 -1
  369. package/dist/src/shared/errors/error-response.js +0 -136
  370. package/dist/src/shared/errors/error-response.js.map +0 -1
  371. package/dist/src/shared/errors/mcp-error.d.ts +0 -57
  372. package/dist/src/shared/errors/mcp-error.d.ts.map +0 -1
  373. package/dist/src/shared/errors/mcp-error.js +0 -93
  374. package/dist/src/shared/errors/mcp-error.js.map +0 -1
  375. package/dist/src/shared/schemas/base.schemas.d.ts +0 -454
  376. package/dist/src/shared/schemas/base.schemas.d.ts.map +0 -1
  377. package/dist/src/shared/schemas/base.schemas.js +0 -168
  378. package/dist/src/shared/schemas/base.schemas.js.map +0 -1
  379. package/dist/src/shared/schemas/index.d.ts +0 -5
  380. package/dist/src/shared/schemas/index.d.ts.map +0 -1
  381. package/dist/src/shared/schemas/index.js +0 -5
  382. package/dist/src/shared/schemas/index.js.map +0 -1
  383. package/dist/src/shared/services/element-fusion.service.d.ts +0 -80
  384. package/dist/src/shared/services/element-fusion.service.d.ts.map +0 -1
  385. package/dist/src/shared/services/element-fusion.service.js +0 -286
  386. package/dist/src/shared/services/element-fusion.service.js.map +0 -1
  387. package/dist/src/shared/services/element-resolver.service.d.ts +0 -93
  388. package/dist/src/shared/services/element-resolver.service.d.ts.map +0 -1
  389. package/dist/src/shared/services/element-resolver.service.js +0 -378
  390. package/dist/src/shared/services/element-resolver.service.js.map +0 -1
  391. package/dist/src/shared/services/form-detector.service.d.ts +0 -119
  392. package/dist/src/shared/services/form-detector.service.d.ts.map +0 -1
  393. package/dist/src/shared/services/form-detector.service.js +0 -308
  394. package/dist/src/shared/services/form-detector.service.js.map +0 -1
  395. package/dist/src/shared/services/visibility-checker.service.d.ts +0 -55
  396. package/dist/src/shared/services/visibility-checker.service.d.ts.map +0 -1
  397. package/dist/src/shared/services/visibility-checker.service.js +0 -204
  398. package/dist/src/shared/services/visibility-checker.service.js.map +0 -1
  399. package/dist/tests/mocks/cdp-bridge.mock.d.ts +0 -45
  400. package/dist/tests/mocks/cdp-bridge.mock.d.ts.map +0 -1
  401. package/dist/tests/mocks/cdp-bridge.mock.js +0 -126
  402. package/dist/tests/mocks/cdp-bridge.mock.js.map +0 -1
  403. package/dist/tests/unit/shared/dom-transformer.service.test.d.ts +0 -5
  404. package/dist/tests/unit/shared/dom-transformer.service.test.d.ts.map +0 -1
  405. package/dist/tests/unit/shared/dom-transformer.service.test.js +0 -273
  406. package/dist/tests/unit/shared/dom-transformer.service.test.js.map +0 -1
package/README.md CHANGED
@@ -1,364 +1,195 @@
1
- # Browser Automation MCP Server
1
+ # Athena Browser MCP
2
2
 
3
3
  [![CI](https://github.com/lespaceman/athena-browser-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/lespaceman/athena-browser-mcp/actions/workflows/ci.yml)
4
4
  [![npm version](https://badge.fury.io/js/athena-browser-mcp.svg)](https://www.npmjs.com/package/athena-browser-mcp)
5
- [![codecov](https://codecov.io/gh/lespaceman/athena-browser-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/lespaceman/athena-browser-mcp)
6
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7
6
 
8
- A comprehensive Model Context Protocol (MCP) server that exposes browser automation capabilities for AI agents through Qt + CEF (Chromium Embedded Framework).
7
+ Minimal MCP server for AI browser automation - 11 simple tools.
9
8
 
10
- ## Overview
9
+ ## Design Philosophy
11
10
 
12
- This MCP server provides 40+ tools organized into three categories:
11
+ 1. **Page state in system prompt** - Agent always knows current page state without querying
12
+ 2. **Lightweight delta responses** - Tools return what changed, not full snapshots
13
+ 3. **Simple verb-based naming** - `click`, `type`, `press` instead of `action_click`, `action_type`
13
14
 
14
- ### A) Perception & Understanding Tools (11 tools)
15
+ ## Architecture
15
16
 
16
- - **DOM & Accessibility**: Get stable DOM trees and accessibility information
17
- - **Layout & Visibility**: Check element geometry and visibility
18
- - **UI Discovery**: Fuse DOM+AX+layout for intelligent element discovery
19
- - **Vision/OCR**: Fallback text detection for canvas/SVG elements
20
- - **Network Observation**: Monitor and capture network requests
21
- - **Content Extraction**: Extract main content using Readability/Trafilatura
17
+ ```
18
+ ┌─────────────────────────────────────────────────────────────────┐
19
+ │ AI Agent │
20
+ │ ┌────────────────────────────────────────────────────────────┐
21
+ │ │ System Prompt: Current page state (URL, forms, actions) │ │
22
+ │ └────────────────────────────────────────────────────────────┘
23
+ └───────────────────────────┬─────────────────────────────────────┘
24
+ │ MCP Protocol (stdio)
25
+ ┌───────────────────────────▼─────────────────────────────────────┐
26
+ │ SESSION: open, close │
27
+ │ NAVIGATION: goto │
28
+ │ OBSERVATION: snapshot, find │
29
+ │ INTERACTION: click, type, press, select, hover, scroll │
30
+ └───────────────────────────┬─────────────────────────────────────┘
31
+ │ Playwright + CDP
32
+ ┌───────────────────────────▼─────────────────────────────────────┐
33
+ │ Chromium Browser │
34
+ └─────────────────────────────────────────────────────────────────┘
35
+ ```
22
36
 
23
- ### B) Interaction & Navigation Tools (14 tools)
37
+ ## Tools
24
38
 
25
- - **Target Resolution**: Resolve semantic hints to concrete elements
26
- - **Actions**: Click, type, select, scroll, upload files
27
- - **Navigation**: Go to URLs, wait for conditions, switch frames
28
- - **Form Toolkit**: Detect, fill, and submit forms intelligently
29
- - **Keyboard**: Press key sequences and type text
39
+ ### Session
30
40
 
31
- ### C) Session, Memory & Safety Tools (10 tools)
41
+ | Tool | Purpose | Input |
42
+ | ------- | --------------------- | ---------------------------- |
43
+ | `open` | Start browser session | `{ headless?, connect_to? }` |
44
+ | `close` | End browser session | `{ page_id? }` |
32
45
 
33
- - **Session Management**: Save/restore cookies and storage
34
- - **Site Memory**: Learn stable selectors for recurring sites
35
- - **Safety Controls**: Domain allowlists, action budgets, audit logs
36
- - **Audit Snapshots**: Capture screenshots, DOM, and HAR files
46
+ ### Navigation
37
47
 
38
- ## Architecture
48
+ | Tool | Purpose | Input |
49
+ | ------ | ----------------------- | ------------------------------------------------------------ |
50
+ | `goto` | Navigate to URL | `{ url: "https://..." }` |
51
+ | | Go back/forward/refresh | `{ back: true }` / `{ forward: true }` / `{ refresh: true }` |
39
52
 
40
- ```
41
- ┌─────────────┐
42
- │ Claude │ (AI Agent)
43
- └──────┬──────┘
44
- │ MCP Protocol
45
-
46
- ┌──────▼──────────────────────┐
47
- │ MCP Server (Node.js) │
48
- │ - Tool routing │
49
- │ - Safety policies │
50
- │ - Audit logging │
51
- └──────┬──────────────────────┘
52
- │ IPC/WebSocket
53
-
54
- ┌──────▼──────────────────────┐
55
- │ CEF Bridge (Qt/C++) │
56
- │ - CDP communication │
57
- │ - Screenshot capture │
58
- │ - File system access │
59
- └──────┬──────────────────────┘
60
- │ Chrome DevTools Protocol
61
-
62
- ┌──────▼──────────────────────┐
63
- │ Chromium Engine (CEF) │
64
- │ - Render web pages │
65
- │ - Execute JavaScript │
66
- │ - Network handling │
67
- └─────────────────────────────┘
68
- ```
53
+ ### Observation
69
54
 
70
- ## Installation
55
+ | Tool | Purpose | Input |
56
+ | ---------- | ----------------------------- | --------------------------------------- |
57
+ | `snapshot` | Capture fresh page state | `{ include_factpack?, include_nodes? }` |
58
+ | `find` | Find elements by criteria | `{ kind?, label?, region? }` |
59
+ | | Get details for specific node | `{ node_id }` |
71
60
 
72
- ```bash
73
- npm install
74
- npm run build
75
- ```
61
+ ### Interaction
76
62
 
77
- ## Configuration
78
-
79
- ### Claude Desktop Configuration
63
+ | Tool | Purpose | Input |
64
+ | -------- | ---------------------- | ------------------------------------------ |
65
+ | `click` | Click element | `{ node_id }` |
66
+ | `type` | Type text into element | `{ text, node_id?, clear? }` |
67
+ | `press` | Press keyboard key | `{ key }` (Enter, Tab, Escape, etc.) |
68
+ | `select` | Choose dropdown option | `{ node_id, value }` |
69
+ | `hover` | Hover over element | `{ node_id }` (reveal menus/tooltips) |
70
+ | `scroll` | Scroll page or element | `{ node_id? }` or `{ direction, amount? }` |
80
71
 
81
- Add to your Claude Desktop config file:
72
+ ## Response Format
82
73
 
83
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
84
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
85
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
74
+ Tools return lightweight deltas describing what changed:
86
75
 
87
76
  ```json
88
77
  {
89
- "mcpServers": {
90
- "browser-automation": {
91
- "command": "node",
92
- "args": ["/path/to/athena-browser-mcp/dist/src/index.js"],
93
- "env": {
94
- "CEF_BRIDGE_HOST": "localhost",
95
- "CEF_BRIDGE_PORT": "9222",
96
- "ALLOWED_FILE_DIRS": "/home/user/downloads,/tmp"
97
- }
98
- }
99
- }
78
+ "delta": {
79
+ "action": "Clicked 'Sign In' button",
80
+ "changes": [
81
+ { "type": "navigation", "from": "/login", "to": "/dashboard" }
82
+ ]
83
+ },
84
+ "page_state": { ... }
100
85
  }
101
86
  ```
102
87
 
103
- ### Environment Variables
88
+ ### Change Types
104
89
 
105
- - `CEF_BRIDGE_HOST`: Host for CEF bridge connection (default: localhost)
106
- - `CEF_BRIDGE_PORT`: Port for CEF bridge connection (default: 9222)
107
- - `ALLOWED_FILE_DIRS`: Comma-separated list of directories for file uploads
108
- - `DEFAULT_TIMEOUT_MS`: Default timeout for operations (default: 30000)
90
+ | Type | Description |
91
+ | ---------------- | ------------------------- |
92
+ | `focused` | Element received focus |
93
+ | `filled` | Input field value changed |
94
+ | `selected` | Dropdown option selected |
95
+ | `clicked` | Element was clicked |
96
+ | `navigation` | URL changed |
97
+ | `page_changed` | Page type changed |
98
+ | `modal_opened` | Modal dialog appeared |
99
+ | `modal_closed` | Modal dialog dismissed |
100
+ | `form_submitted` | Form was submitted |
109
101
 
110
102
  ## Usage Examples
111
103
 
112
- ### Example 1: Login Flow
104
+ ### Login Flow
113
105
 
114
- ```typescript
115
- // 1. Discover form elements
116
- const form = await mcp.tools.form_detect({});
117
-
118
- // 2. Fill credentials
119
- await mcp.tools.form_fill({
120
- pairs: [
121
- { slot: 'email', text: 'user@example.com' },
122
- { slot: 'password', text: '********' },
123
- ],
124
- });
125
-
126
- // 3. Submit form
127
- await mcp.tools.form_submit({ strategy: 'button' });
128
-
129
- // 4. Wait for navigation
130
- await mcp.tools.nav_wait({ for: 'route-change' });
131
-
132
- // 5. Save session
133
- const session = await mcp.tools.session_save({ domain: 'example.com' });
134
106
  ```
107
+ 1. open { }
108
+ → System prompt updated with initial page state
135
109
 
136
- ### Example 2: Search and Extract
137
-
138
- ```typescript
139
- // 1. Navigate to search page
140
- await mcp.tools.nav_goto({ url: 'https://example.com/search' });
110
+ 2. goto { url: "https://example.com/login" }
111
+ → Page changed: login form detected
112
+ → System prompt updated with form fields
141
113
 
142
- // 2. Find search box
143
- const searchBox = await mcp.tools.targets_resolve({
144
- hint: { role: 'textbox', label: 'Search' },
145
- });
114
+ 3. find { kind: "input", label: "email" }
115
+ { matches: [{ node_id: "42", label: "Email" }] }
146
116
 
147
- // 3. Type search query
148
- await mcp.tools.act_type({
149
- target: searchBox,
150
- text: 'machine learning',
151
- submit: 'Enter',
152
- });
117
+ 4. click { node_id: "42" }
118
+ Focused: Email field
153
119
 
154
- // 4. Wait for results
155
- await mcp.tools.nav_wait({ for: 'network-idle' });
120
+ 5. type { text: "user@example.com" }
121
+ Filled: Email = "user@example.com"
156
122
 
157
- // 5. Extract main content
158
- const content = await mcp.tools.content_extract_main({
159
- mode: 'readability',
160
- });
161
- ```
162
-
163
- ### Example 3: Handle Canvas UI (with OCR fallback)
164
-
165
- ```typescript
166
- // 1. Try semantic resolution first
167
- let button = await mcp.tools.targets_resolve({
168
- hint: { role: 'button', label: 'Download' },
169
- });
170
-
171
- // 2. Fallback to vision if needed
172
- if (!button) {
173
- button = await mcp.tools.vision_find_by_text({
174
- text: 'Download',
175
- fuzzy: true,
176
- });
177
- }
123
+ 6. press { key: "Tab" }
124
+ Focused: Password field
178
125
 
179
- // 3. Click using bbox strategy
180
- if (button) {
181
- await mcp.tools.act_click({
182
- target: button,
183
- strategy: 'bbox',
184
- });
185
- }
126
+ 7. type { text: "password123" }
127
+ Filled: Password = "••••••••••••"
186
128
 
187
- // 4. Verify with network observation
188
- const download = await mcp.tools.net_observe({
189
- patterns: ['*.pdf', '*.csv'],
190
- });
129
+ 8. press { key: "Enter" }
130
+ Form submitted
131
+ → Navigation: /login → /dashboard
191
132
  ```
192
133
 
193
- ## Tool Categories
194
-
195
- ### Deterministic-First, Vision-Assisted Fallback
196
-
197
- The toolkit prioritizes deterministic methods:
198
-
199
- 1. **Accessibility tree** (most stable)
200
- 2. **DOM selectors** (CSS, XPath)
201
- 3. **Layout/geometry** (bounding boxes)
202
- 4. **Vision/OCR** (last resort for canvas/SVG)
203
-
204
- ### Selector Bundles
134
+ ### E-commerce Purchase
205
135
 
206
- Each `ElementRef` contains multiple locators for resilience:
207
-
208
- ```typescript
209
- interface ElementRef {
210
- frameId: string;
211
- nodeId?: number;
212
- selectors: {
213
- ax?: string; // Accessibility path
214
- css?: string; // CSS selector
215
- xpath?: string; // XPath expression
216
- };
217
- bbox?: { x: number; y: number; w: number; h: number };
218
- role?: string;
219
- label?: string;
220
- name?: string;
221
- }
222
136
  ```
137
+ 1. goto { url: "https://shop.example.com/product/123" }
138
+ → System prompt: product page, Add to Cart [node:101], Size [node:103]
223
139
 
224
- ### Safety Features
225
-
226
- 1. **Domain Allowlists**: Restrict navigation to approved domains
227
- 2. **Action Budgets**: Rate limit to prevent runaway automation
228
- 3. **File Path Validation**: Only upload files from allowed directories
229
- 4. **Audit Logging**: All actions captured with pre/post screenshots
230
- 5. **Confirmation Prompts**: For destructive actions (delete, purchase)
231
-
232
- ## Implementation Checklist
233
-
234
- ### Phase 1: Core Tools (Week 1-2)
140
+ 2. select { node_id: "103", value: "Large" }
141
+ → Selected: Size = "Large"
235
142
 
236
- - [ ] `targets_resolve` - Element resolution
237
- - [ ] `act_click` - Click actions
238
- - [ ] `act_type` - Text input
239
- - [ ] `nav_wait` - Wait conditions
240
- - [ ] `ui_discover` - Element discovery
241
- - [ ] CEF Bridge basic IPC
242
-
243
- ### Phase 2: Robustness (Week 3-4)
244
-
245
- - [ ] `form_detect` / `form_fill` / `form_submit`
246
- - [ ] Selector bundle system
247
- - [ ] Shadow DOM piercing
248
- - [ ] Frame handling
249
- - [ ] Visibility checks
250
-
251
- ### Phase 3: Advanced Features (Week 5-6)
252
-
253
- - [ ] `vision_ocr` / `vision_find_by_text`
254
- - [ ] `net_observe` / `net_get_response_body`
255
- - [ ] `session_save` / `session_restore`
256
- - [ ] Site memory profiles
257
- - [ ] Virtualized list handling
258
-
259
- ### Phase 4: Safety & Production (Week 7-8)
260
-
261
- - [ ] `safety_set_policy`
262
- - [ ] `audit_snapshot`
263
- - [ ] Domain allowlists
264
- - [ ] Action budgets
265
- - [ ] Comprehensive logging
266
- - [ ] Error recovery
267
-
268
- ## CEF Bridge Requirements
269
-
270
- Your Qt/CEF application must expose these capabilities via IPC:
271
-
272
- ```typescript
273
- interface CEFBridge {
274
- // CDP Methods
275
- executeDevToolsMethod(method: string, params: any): Promise<any>;
276
- onDevToolsEvent(handler: (event: string, params: any) => void): void;
277
-
278
- // Screenshot
279
- captureScreenshot(region?: BBox): Promise<string>; // Returns base64 or path
280
-
281
- // File System
282
- saveFile(path: string, data: Buffer): Promise<void>;
283
- readFile(path: string): Promise<Buffer>;
284
-
285
- // Safety
286
- setSafetyPolicy(policy: SafetyPolicy): void;
287
- }
143
+ 3. click { node_id: "101" }
144
+ Clicked: Add to Cart
145
+ Modal opened: "Added to cart"
288
146
  ```
289
147
 
290
- ## Testing
148
+ ## Installation
291
149
 
292
150
  ```bash
293
- # Run tests
294
- npm test
295
-
296
- # Test with Claude Desktop
297
- # 1. Configure Claude Desktop (see Configuration section)
298
- # 2. Restart Claude Desktop
299
- # 3. Start a conversation with Claude
300
- # 4. Ask: "Can you help me navigate to example.com and find the search box?"
151
+ npm install
152
+ npm run build
301
153
  ```
302
154
 
303
- ## Debugging
155
+ ## Configuration
304
156
 
305
- Enable debug logging:
157
+ ### Claude Desktop
306
158
 
307
- ```bash
308
- DEBUG=mcp:* node dist/src/index.js
309
- ```
159
+ Add to your Claude Desktop config:
310
160
 
311
- Check MCP communication:
161
+ **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
162
+ **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
163
+ **Linux**: `~/.config/Claude/claude_desktop_config.json`
312
164
 
313
- ```bash
314
- # View MCP protocol messages
315
- tail -f ~/Library/Logs/Claude/mcp*.log # macOS
165
+ ```json
166
+ {
167
+ "mcpServers": {
168
+ "browser": {
169
+ "command": "node",
170
+ "args": ["/path/to/athena-browser-mcp/dist/src/index.js"]
171
+ }
172
+ }
173
+ }
316
174
  ```
317
175
 
318
- ## API Reference
319
-
320
- See [src/config/tools.json](./src/config/tools.json) for complete tool definitions.
321
-
322
- See type definitions in:
323
-
324
- - [src/domains/interaction/interaction.types.ts](./src/domains/interaction/interaction.types.ts)
325
- - [src/domains/perception/perception.types.ts](./src/domains/perception/perception.types.ts)
326
- - [src/domains/navigation/navigation.types.ts](./src/domains/navigation/navigation.types.ts)
327
- - [src/domains/session/session.types.ts](./src/domains/session/session.types.ts)
328
-
329
- ## Design Principles
176
+ ### Environment Variables
330
177
 
331
- 1. **Separation of Concerns**: Agent never touches CDP directly
332
- 2. **Resilience**: Multiple locator strategies with automatic fallback
333
- 3. **Observability**: Every action logged with screenshots
334
- 4. **Safety**: Allowlists, budgets, and confirmations built-in
335
- 5. **Determinism**: Prefer stable AX/DOM methods over vision
336
- 6. **Testability**: Each tool is independently testable
178
+ | Variable | Description | Default |
179
+ | -------------------- | ------------------------- | ------- |
180
+ | `DEFAULT_TIMEOUT_MS` | Default operation timeout | `30000` |
337
181
 
338
- ## Contributing
182
+ ## Development
339
183
 
340
- 1. Add new tools to `src/config/tools.json`
341
- 2. Add type definitions to appropriate domain type files
342
- 3. Implement handlers in respective domain handler files
343
- 4. Add tests in `tests/`
344
- 5. Update README with examples
184
+ ```bash
185
+ npm run build # Compile TypeScript
186
+ npm run type-check # TypeScript type checking
187
+ npm run lint # ESLint
188
+ npm run format # Prettier format
189
+ npm run check # Run all checks
190
+ npm test # Run tests
191
+ ```
345
192
 
346
193
  ## License
347
194
 
348
195
  MIT
349
-
350
- ## Support
351
-
352
- For issues or questions, please open an issue on GitHub or contact the development team.
353
-
354
- ## Roadmap
355
-
356
- - [ ] Multi-tab support
357
- - [ ] Browser extension API bridge
358
- - [ ] Performance profiling tools
359
- - [ ] A/B testing utilities
360
- - [ ] Visual regression testing
361
- - [ ] Accessibility audit tools
362
- - [ ] Network throttling
363
- - [ ] Geolocation simulation
364
- - [ ] Device emulation
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Browser Module
3
+ *
4
+ * Exports for browser lifecycle management.
5
+ */
6
+ export { PageRegistry, type PageHandle } from './page-registry.js';
7
+ export { SessionManager, type LaunchOptions, type ConnectOptions, type ConnectionState, type ConnectionStateChangeEvent, } from './session-manager.js';
8
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EACL,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,0BAA0B,GAChC,MAAM,sBAAsB,CAAC"}
@@ -0,0 +1,8 @@
1
+ /**
2
+ * Browser Module
3
+ *
4
+ * Exports for browser lifecycle management.
5
+ */
6
+ export { PageRegistry } from './page-registry.js';
7
+ export { SessionManager, } from './session-manager.js';
8
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAmB,MAAM,oBAAoB,CAAC;AACnE,OAAO,EACL,cAAc,GAKf,MAAM,sBAAsB,CAAC"}
@@ -0,0 +1,126 @@
1
+ /**
2
+ * Page Registry
3
+ *
4
+ * Tracks active Playwright pages and their CDP sessions.
5
+ * Provides a central registry for page lifecycle management.
6
+ */
7
+ import type { Page } from 'playwright';
8
+ import type { CdpClient } from '../cdp/cdp-client.interface.js';
9
+ /**
10
+ * Handle to a registered page with its CDP session
11
+ */
12
+ export interface PageHandle {
13
+ /** Unique identifier for this page */
14
+ page_id: string;
15
+ /** Playwright Page instance */
16
+ page: Page;
17
+ /** CDP client for this page */
18
+ cdp: CdpClient;
19
+ /** When the page was registered */
20
+ created_at: Date;
21
+ /** Current URL (may be stale) */
22
+ url?: string;
23
+ /** Page title (may be stale) */
24
+ title?: string;
25
+ }
26
+ /**
27
+ * Registry for tracking active pages
28
+ */
29
+ export declare class PageRegistry {
30
+ private readonly pages;
31
+ /** Most recently used page ID for default resolution */
32
+ private mruPageId;
33
+ /**
34
+ * Register a new page with its CDP session
35
+ *
36
+ * @param page - Playwright Page instance
37
+ * @param cdp - CDP client for the page
38
+ * @returns PageHandle with unique page_id
39
+ * @throws Error if page is already closed
40
+ */
41
+ register(page: Page, cdp: CdpClient): PageHandle;
42
+ /**
43
+ * Get a page handle by its ID
44
+ *
45
+ * @param page_id - The page identifier
46
+ * @returns PageHandle if found, undefined otherwise
47
+ */
48
+ get(page_id: string): PageHandle | undefined;
49
+ /**
50
+ * Remove a page from the registry
51
+ *
52
+ * @param page_id - The page identifier
53
+ * @returns true if page was removed, false if not found
54
+ */
55
+ remove(page_id: string): boolean;
56
+ /**
57
+ * List all registered pages
58
+ *
59
+ * @returns Array of all PageHandle objects
60
+ */
61
+ list(): PageHandle[];
62
+ /**
63
+ * Remove all pages from the registry
64
+ */
65
+ clear(): void;
66
+ /**
67
+ * Get the number of registered pages
68
+ *
69
+ * @returns Current page count
70
+ */
71
+ size(): number;
72
+ /**
73
+ * Check if a page is registered
74
+ *
75
+ * @param page_id - The page identifier
76
+ * @returns true if page exists
77
+ */
78
+ has(page_id: string): boolean;
79
+ /**
80
+ * Update metadata for a page
81
+ *
82
+ * @param page_id - The page identifier
83
+ * @param metadata - Partial metadata to update
84
+ * @returns true if updated, false if page not found
85
+ */
86
+ updateMetadata(page_id: string, metadata: Partial<Pick<PageHandle, 'url' | 'title'>>): boolean;
87
+ /**
88
+ * Find a handle by its Playwright Page instance
89
+ *
90
+ * @param page - Playwright Page instance to find
91
+ * @returns PageHandle if found, undefined otherwise
92
+ */
93
+ findByPage(page: Page): PageHandle | undefined;
94
+ /**
95
+ * Find all handles with a matching URL
96
+ *
97
+ * @param url - URL to search for
98
+ * @returns Array of matching PageHandle objects
99
+ */
100
+ findByUrl(url: string): PageHandle[];
101
+ /**
102
+ * Check if a page handle is still valid (page not closed, CDP active)
103
+ *
104
+ * Use this to detect stale handles before performing operations.
105
+ *
106
+ * @param page_id - The page identifier
107
+ * @returns true if the handle exists and both page and CDP session are active
108
+ */
109
+ isValid(page_id: string): boolean;
110
+ /**
111
+ * Touch a page to mark it as most recently used.
112
+ *
113
+ * @param page_id - The page identifier
114
+ * @returns true if the page exists and was touched, false otherwise
115
+ */
116
+ touch(page_id: string): boolean;
117
+ /**
118
+ * Get the most recently used page.
119
+ *
120
+ * Falls back to the first registered page if MRU is not set.
121
+ *
122
+ * @returns PageHandle for MRU page, or undefined if no pages
123
+ */
124
+ getMostRecent(): PageHandle | undefined;
125
+ }
126
+ //# sourceMappingURL=page-registry.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"page-registry.d.ts","sourceRoot":"","sources":["../../../src/browser/page-registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAGhE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAEhB,+BAA+B;IAC/B,IAAI,EAAE,IAAI,CAAC;IAEX,+BAA+B;IAC/B,GAAG,EAAE,SAAS,CAAC;IAEf,mCAAmC;IACnC,UAAU,EAAE,IAAI,CAAC;IAEjB,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,wDAAwD;IACxD,OAAO,CAAC,SAAS,CAAuB;IAExC;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,GAAG,UAAU;IAsBhD;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI5C;;;;;OAKG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAUhC;;;;OAIG;IACH,IAAI,IAAI,UAAU,EAAE;IAIpB;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;;;OAIG;IACH,IAAI,IAAI,MAAM;IAId;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAI7B;;;;;;OAMG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,GAAG,OAAO,CAAC,CAAC,GAAG,OAAO;IAgB9F;;;;;OAKG;IACH,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,UAAU,GAAG,SAAS;IAI9C;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE;IAIpC;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAmBjC;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAQ/B;;;;;;OAMG;IACH,aAAa,IAAI,UAAU,GAAG,SAAS;CAOxC"}