@browserflow-ai/exploration 0.0.6

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 (58) hide show
  1. package/dist/adapters/claude-cli.d.ts +57 -0
  2. package/dist/adapters/claude-cli.d.ts.map +1 -0
  3. package/dist/adapters/claude-cli.js +195 -0
  4. package/dist/adapters/claude-cli.js.map +1 -0
  5. package/dist/adapters/claude.d.ts +54 -0
  6. package/dist/adapters/claude.d.ts.map +1 -0
  7. package/dist/adapters/claude.js +160 -0
  8. package/dist/adapters/claude.js.map +1 -0
  9. package/dist/adapters/index.d.ts +6 -0
  10. package/dist/adapters/index.d.ts.map +1 -0
  11. package/dist/adapters/index.js +4 -0
  12. package/dist/adapters/index.js.map +1 -0
  13. package/dist/adapters/types.d.ts +196 -0
  14. package/dist/adapters/types.d.ts.map +1 -0
  15. package/dist/adapters/types.js +3 -0
  16. package/dist/adapters/types.js.map +1 -0
  17. package/dist/agent-browser-session.d.ts +62 -0
  18. package/dist/agent-browser-session.d.ts.map +1 -0
  19. package/dist/agent-browser-session.js +272 -0
  20. package/dist/agent-browser-session.js.map +1 -0
  21. package/dist/evidence.d.ts +111 -0
  22. package/dist/evidence.d.ts.map +1 -0
  23. package/dist/evidence.js +144 -0
  24. package/dist/evidence.js.map +1 -0
  25. package/dist/explorer.d.ts +180 -0
  26. package/dist/explorer.d.ts.map +1 -0
  27. package/dist/explorer.js +393 -0
  28. package/dist/explorer.js.map +1 -0
  29. package/dist/index.d.ts +15 -0
  30. package/dist/index.d.ts.map +1 -0
  31. package/dist/index.js +15 -0
  32. package/dist/index.js.map +1 -0
  33. package/dist/locator-candidates.d.ts +127 -0
  34. package/dist/locator-candidates.d.ts.map +1 -0
  35. package/dist/locator-candidates.js +358 -0
  36. package/dist/locator-candidates.js.map +1 -0
  37. package/dist/step-executor.d.ts +99 -0
  38. package/dist/step-executor.d.ts.map +1 -0
  39. package/dist/step-executor.js +646 -0
  40. package/dist/step-executor.js.map +1 -0
  41. package/package.json +34 -0
  42. package/src/adapters/claude-cli.test.ts +134 -0
  43. package/src/adapters/claude-cli.ts +240 -0
  44. package/src/adapters/claude.test.ts +195 -0
  45. package/src/adapters/claude.ts +190 -0
  46. package/src/adapters/index.ts +21 -0
  47. package/src/adapters/types.ts +207 -0
  48. package/src/agent-browser-session.test.ts +369 -0
  49. package/src/agent-browser-session.ts +349 -0
  50. package/src/evidence.test.ts +239 -0
  51. package/src/evidence.ts +203 -0
  52. package/src/explorer.test.ts +321 -0
  53. package/src/explorer.ts +565 -0
  54. package/src/index.ts +51 -0
  55. package/src/locator-candidates.test.ts +602 -0
  56. package/src/locator-candidates.ts +441 -0
  57. package/src/step-executor.test.ts +696 -0
  58. package/src/step-executor.ts +783 -0
@@ -0,0 +1,393 @@
1
+ // @browserflow-ai/exploration - Main exploration orchestrator
2
+ // Debug flag - set via BF_DEBUG=1 environment variable
3
+ const DEBUG = process.env.BF_DEBUG === '1';
4
+ function debug(...args) {
5
+ if (DEBUG) {
6
+ console.error('[explorer]', ...args);
7
+ }
8
+ }
9
+ import { StepExecutor } from './step-executor';
10
+ import { EvidenceCollector } from './evidence';
11
+ import { LocatorCandidateGenerator } from './locator-candidates';
12
+ import * as path from 'path';
13
+ /**
14
+ * Explorer - Main orchestrator for AI-powered browser exploration
15
+ *
16
+ * Coordinates between:
17
+ * - AI adapter (Claude, OpenAI, etc.)
18
+ * - Step executor (runs individual steps)
19
+ * - Evidence collector (screenshots, traces)
20
+ * - Locator candidate generator (element selection strategies)
21
+ */
22
+ export class Explorer {
23
+ adapter;
24
+ browser;
25
+ outputDir;
26
+ headless;
27
+ defaultViewport;
28
+ stepExecutor;
29
+ evidenceCollector;
30
+ locatorGenerator;
31
+ constructor(config) {
32
+ this.adapter = config.adapter;
33
+ this.browser = config.browser;
34
+ this.outputDir = config.outputDir ?? './explorations';
35
+ this.headless = config.headless ?? true;
36
+ this.defaultViewport = config.viewport ?? { width: 1280, height: 720 };
37
+ this.stepExecutor = new StepExecutor();
38
+ this.evidenceCollector = new EvidenceCollector();
39
+ this.locatorGenerator = new LocatorCandidateGenerator();
40
+ }
41
+ /**
42
+ * Generate a unique exploration ID
43
+ */
44
+ generateExplorationId() {
45
+ const timestamp = Date.now();
46
+ const random = Math.random().toString(36).slice(2, 8);
47
+ return `exp-${timestamp}-${random}`;
48
+ }
49
+ /**
50
+ * Run full exploration on a spec
51
+ *
52
+ * This is the main orchestration method that:
53
+ * 1. Launches browser
54
+ * 2. Navigates to starting page
55
+ * 3. Executes each step with evidence collection
56
+ * 4. Handles failures gracefully (continues on error)
57
+ * 5. Produces ExplorationOutput
58
+ *
59
+ * @param spec - The spec to explore
60
+ * @param baseUrl - Base URL for navigation
61
+ * @param options - Additional options
62
+ * @returns Promise resolving to exploration output
63
+ */
64
+ async runExploration(spec, baseUrl, options = {}) {
65
+ const startTime = Date.now();
66
+ const explorationId = this.generateExplorationId();
67
+ const steps = [];
68
+ const errors = [];
69
+ // Configure evidence collector with exploration-specific output directory
70
+ const explorationOutputDir = path.join(this.outputDir, explorationId);
71
+ this.evidenceCollector.setOutputDir(explorationOutputDir);
72
+ // Determine viewport - spec preconditions override defaults
73
+ const viewport = spec.preconditions?.viewport ??
74
+ options.viewport ??
75
+ this.defaultViewport;
76
+ // Ensure browser is available
77
+ if (!this.browser) {
78
+ throw new Error('Browser session not configured');
79
+ }
80
+ try {
81
+ // 1. Launch browser
82
+ await this.browser.launch({
83
+ headless: options.headless ?? this.headless,
84
+ viewport,
85
+ });
86
+ // Register browser session with evidence collector
87
+ this.evidenceCollector.registerSession(explorationId, this.browser);
88
+ // 2. Navigate to starting page
89
+ const pageConfig = spec.preconditions?.page;
90
+ const startPage = pageConfig?.url ?? '/';
91
+ const fullUrl = startPage.startsWith('http') ? startPage : `${baseUrl}${startPage}`;
92
+ await this.browser.navigate(fullUrl);
93
+ // Wait briefly for JS to initialize (configurable via spec timeout)
94
+ // Note: For JS-heavy apps, consider adding explicit wait steps in the spec
95
+ if (this.browser.waitForTimeout) {
96
+ debug('Waiting 1s for page to stabilize...');
97
+ await this.browser.waitForTimeout(1000);
98
+ }
99
+ // 3. Execute each step
100
+ for (let i = 0; i < spec.steps.length; i++) {
101
+ const specStep = spec.steps[i];
102
+ const stepResult = await this.executeStepWithEvidence(specStep, i, baseUrl, explorationId);
103
+ steps.push(stepResult);
104
+ if (stepResult.execution.status === 'failed' && stepResult.execution.error) {
105
+ errors.push(`Step ${i}: ${stepResult.execution.error}`);
106
+ }
107
+ }
108
+ // 4. Build output
109
+ const overallStatus = steps.every((s) => s.execution.status === 'completed')
110
+ ? 'completed'
111
+ : 'failed';
112
+ return {
113
+ spec: spec.name,
114
+ specPath: options.specPath ?? `specs/${spec.name}.yaml`,
115
+ specDescription: spec.description,
116
+ explorationId,
117
+ timestamp: new Date().toISOString(),
118
+ durationMs: Date.now() - startTime,
119
+ browser: 'chromium',
120
+ viewport,
121
+ baseUrl,
122
+ steps,
123
+ outcomeChecks: [],
124
+ overallStatus,
125
+ errors,
126
+ };
127
+ }
128
+ finally {
129
+ // Unregister browser session from evidence collector
130
+ this.evidenceCollector.unregisterSession(explorationId);
131
+ // Always close browser
132
+ await this.browser.close();
133
+ }
134
+ }
135
+ /**
136
+ * Execute a single step with evidence collection (screenshots)
137
+ */
138
+ async executeStepWithEvidence(step, stepIndex, baseUrl, explorationId) {
139
+ const startTime = Date.now();
140
+ let snapshotBefore;
141
+ let snapshotAfter;
142
+ // Capture before screenshot
143
+ const screenshotBeforePath = `screenshots/step-${String(stepIndex).padStart(2, '0')}-before.png`;
144
+ const screenshotAfterPath = `screenshots/step-${String(stepIndex).padStart(2, '0')}-after.png`;
145
+ try {
146
+ debug(`Step ${stepIndex}: ${step.action} - starting`);
147
+ // Take before screenshot and save to disk
148
+ debug(`Step ${stepIndex}: capturing before screenshot`);
149
+ await this.evidenceCollector.captureScreenshot(explorationId, `step-${String(stepIndex).padStart(2, '0')}-before`);
150
+ // Get snapshot for element finding
151
+ debug(`Step ${stepIndex}: getting before snapshot`);
152
+ snapshotBefore = await this.browser.getSnapshot({ interactive: true });
153
+ debug(`Step ${stepIndex}: snapshot has ${Object.keys(snapshotBefore.refs).length} refs, tree: ${snapshotBefore.tree.slice(0, 100)}...`);
154
+ // Execute the step
155
+ debug(`Step ${stepIndex}: executing action ${step.action}`);
156
+ const startAction = Date.now();
157
+ const execution = await this.executeAction(step, snapshotBefore, baseUrl);
158
+ debug(`Step ${stepIndex}: action completed in ${Date.now() - startAction}ms, status: ${execution.status}`);
159
+ // Take after screenshot and save to disk
160
+ debug(`Step ${stepIndex}: capturing after screenshot`);
161
+ await this.evidenceCollector.captureScreenshot(explorationId, `step-${String(stepIndex).padStart(2, '0')}-after`);
162
+ // Get after snapshot
163
+ debug(`Step ${stepIndex}: getting after snapshot`);
164
+ snapshotAfter = await this.browser.getSnapshot({ interactive: true });
165
+ debug(`Step ${stepIndex}: after snapshot has ${Object.keys(snapshotAfter.refs).length} refs`);
166
+ return {
167
+ stepIndex,
168
+ specAction: step,
169
+ execution: {
170
+ ...execution,
171
+ durationMs: Date.now() - startTime,
172
+ },
173
+ screenshots: {
174
+ before: screenshotBeforePath,
175
+ after: screenshotAfterPath,
176
+ },
177
+ snapshotBefore: snapshotBefore,
178
+ snapshotAfter: snapshotAfter,
179
+ };
180
+ }
181
+ catch (error) {
182
+ const errorMessage = error instanceof Error ? error.message : String(error);
183
+ return {
184
+ stepIndex,
185
+ specAction: step,
186
+ execution: {
187
+ status: 'failed',
188
+ method: step.action,
189
+ durationMs: Date.now() - startTime,
190
+ error: errorMessage,
191
+ },
192
+ screenshots: {
193
+ before: screenshotBeforePath,
194
+ after: screenshotAfterPath,
195
+ },
196
+ snapshotBefore: snapshotBefore,
197
+ };
198
+ }
199
+ }
200
+ /**
201
+ * Execute a single action based on step type
202
+ */
203
+ async executeAction(step, snapshot, baseUrl) {
204
+ switch (step.action) {
205
+ case 'navigate': {
206
+ // Support both url (canonical) and to (legacy)
207
+ const targetUrl = step.url ?? step.to;
208
+ if (!targetUrl) {
209
+ throw new Error('Navigate action requires "url" field');
210
+ }
211
+ const url = targetUrl.startsWith('http') ? targetUrl : `${baseUrl}${targetUrl}`;
212
+ await this.browser.navigate(url);
213
+ return {
214
+ status: 'completed',
215
+ method: 'navigate',
216
+ durationMs: 0,
217
+ };
218
+ }
219
+ case 'click': {
220
+ const elementRef = await this.findElementRef(step, snapshot);
221
+ if (this.browser.click) {
222
+ await this.browser.click(elementRef);
223
+ }
224
+ return {
225
+ status: 'completed',
226
+ method: 'click',
227
+ elementRef,
228
+ durationMs: 0,
229
+ };
230
+ }
231
+ case 'fill': {
232
+ const elementRef = await this.findElementRef(step, snapshot);
233
+ const value = step.value ?? '';
234
+ if (this.browser.fill) {
235
+ await this.browser.fill(elementRef, value);
236
+ }
237
+ return {
238
+ status: 'completed',
239
+ method: 'fill',
240
+ elementRef,
241
+ durationMs: 0,
242
+ };
243
+ }
244
+ case 'wait': {
245
+ // Wait actions are handled by timing, for now just mark completed
246
+ return {
247
+ status: 'completed',
248
+ method: 'wait',
249
+ durationMs: 0,
250
+ };
251
+ }
252
+ case 'verify_state': {
253
+ // Verify state by checking conditions
254
+ return {
255
+ status: 'completed',
256
+ method: 'verify_state',
257
+ durationMs: 0,
258
+ };
259
+ }
260
+ default: {
261
+ return {
262
+ status: 'completed',
263
+ method: step.action,
264
+ durationMs: 0,
265
+ };
266
+ }
267
+ }
268
+ }
269
+ /**
270
+ * Find element ref using AI adapter or direct selector/ref
271
+ */
272
+ async findElementRef(step, snapshot) {
273
+ // If step has a direct ref, use it
274
+ if (step.ref) {
275
+ return step.ref;
276
+ }
277
+ // If step has a selector, it's already specified
278
+ if (step.selector) {
279
+ return step.selector;
280
+ }
281
+ // Check for target object (v2 spec format)
282
+ const target = step.target;
283
+ if (target) {
284
+ // If target has CSS selector, use it directly
285
+ if (target.css) {
286
+ return target.css;
287
+ }
288
+ // If target has testid, convert to Playwright testId selector
289
+ if (target.testid) {
290
+ return `[data-testid="${target.testid}"]`;
291
+ }
292
+ // Use AI adapter to find element from query or other target properties
293
+ const query = target.query
294
+ || (target.role && `a ${target.role} element`)
295
+ || (target.text && `element with text "${target.text}"`)
296
+ || (target.label && `element with label "${target.label}"`)
297
+ || (target.placeholder && `input with placeholder "${target.placeholder}"`);
298
+ if (query) {
299
+ const result = await this.adapter.findElement(query, snapshot);
300
+ if (result.ref === 'NOT_FOUND') {
301
+ throw new Error(`Element not found for query: ${query}`);
302
+ }
303
+ return result.ref;
304
+ }
305
+ }
306
+ // Legacy: Use AI adapter to find element from step.query (legacy format)
307
+ if (step.query) {
308
+ const result = await this.adapter.findElement(step.query, snapshot);
309
+ if (result.ref === 'NOT_FOUND') {
310
+ throw new Error(`Element not found for query: ${step.query}`);
311
+ }
312
+ return result.ref;
313
+ }
314
+ throw new Error('Step must have ref, selector, target, or query');
315
+ }
316
+ /**
317
+ * Run exploration on a spec
318
+ *
319
+ * @param spec - The spec to explore
320
+ * @param baseUrl - Base URL for the browser session
321
+ * @param options - Additional options
322
+ * @returns Promise resolving to exploration output
323
+ */
324
+ async explore(spec, baseUrl, options = {}) {
325
+ const params = {
326
+ spec,
327
+ specPath: options.specPath ?? `specs/${spec.name}.yaml`,
328
+ baseUrl,
329
+ browser: options.browser ?? 'chromium',
330
+ viewport: options.viewport ?? { width: 1280, height: 720 },
331
+ timeout: options.timeout ?? 30000,
332
+ outputDir: options.outputDir ?? `${this.outputDir}/${spec.name}`,
333
+ sessionId: options.sessionId,
334
+ };
335
+ // Delegate to adapter for AI-powered exploration
336
+ return this.adapter.explore(params);
337
+ }
338
+ /**
339
+ * Execute a single step manually (for testing/debugging)
340
+ *
341
+ * @param step - The step to execute
342
+ * @param stepIndex - Index of the step (default: 0)
343
+ * @returns Promise resolving to step result
344
+ */
345
+ async executeStep(step, stepIndex = 0) {
346
+ return this.stepExecutor.execute(step, stepIndex);
347
+ }
348
+ /**
349
+ * Capture evidence (screenshot) at current state
350
+ *
351
+ * @param sessionId - Browser session ID
352
+ * @param name - Evidence name/identifier
353
+ * @returns Promise resolving to evidence file path
354
+ */
355
+ async captureEvidence(sessionId, name) {
356
+ return this.evidenceCollector.captureScreenshot(sessionId, name);
357
+ }
358
+ /**
359
+ * Generate locator candidates for an element
360
+ *
361
+ * @param query - Natural language description of element
362
+ * @param snapshot - Browser snapshot with element refs
363
+ * @returns Promise resolving to ranked list of locator options
364
+ */
365
+ async generateLocators(query, snapshot) {
366
+ return this.locatorGenerator.generateCandidates(query, snapshot);
367
+ }
368
+ /**
369
+ * Get the configured AI adapter
370
+ */
371
+ getAdapter() {
372
+ return this.adapter;
373
+ }
374
+ /**
375
+ * Get the step executor instance
376
+ */
377
+ getStepExecutor() {
378
+ return this.stepExecutor;
379
+ }
380
+ /**
381
+ * Get the evidence collector instance
382
+ */
383
+ getEvidenceCollector() {
384
+ return this.evidenceCollector;
385
+ }
386
+ /**
387
+ * Get the locator generator instance
388
+ */
389
+ getLocatorGenerator() {
390
+ return this.locatorGenerator;
391
+ }
392
+ }
393
+ //# sourceMappingURL=explorer.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"explorer.js","sourceRoot":"","sources":["../src/explorer.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,15 @@
1
+ export { Explorer } from './explorer';
2
+ export type { ExplorerConfig, BrowserSession, BrowserLaunchOptions } from './explorer';
3
+ export { ClaudeAdapter } from './adapters/claude';
4
+ export type { ClaudeAdapterConfig } from './adapters/claude';
5
+ export { ClaudeCliAdapter } from './adapters/claude-cli';
6
+ export type { ClaudeCliAdapterConfig } from './adapters/claude-cli';
7
+ export { AgentBrowserSession, createBrowserSession } from './agent-browser-session';
8
+ export type { AIAdapter, ExploreParams, ExplorationOutput, RetryParams, ReviewFeedback, Spec, SpecStep, StepResult, StepExecution, StepScreenshots, OutcomeCheck, EnhancedSnapshot, FindElementResult, } from './adapters/types';
9
+ export { StepExecutor } from './step-executor';
10
+ export type { StepExecutorConfig } from './step-executor';
11
+ export { EvidenceCollector } from './evidence';
12
+ export type { EvidenceCollectorConfig, EvidenceMetadata, ScreenshotOptions, } from './evidence';
13
+ export { LocatorCandidateGenerator } from './locator-candidates';
14
+ export type { LocatorCandidateGeneratorConfig, LocatorCandidate, ElementInfo, } from './locator-candidates';
15
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGvF,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAGpE,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAGpF,YAAY,EACV,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,IAAI,EACJ,QAAQ,EACR,UAAU,EACV,aAAa,EACb,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAG1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,YAAY,EACV,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AACjE,YAAY,EACV,+BAA+B,EAC/B,gBAAgB,EAChB,WAAW,GACZ,MAAM,sBAAsB,CAAC"}
package/dist/index.js ADDED
@@ -0,0 +1,15 @@
1
+ // @browserflow-ai/exploration - AI exploration engine
2
+ // Main orchestrator
3
+ export { Explorer } from './explorer';
4
+ // Adapters
5
+ export { ClaudeAdapter } from './adapters/claude';
6
+ export { ClaudeCliAdapter } from './adapters/claude-cli';
7
+ // Browser Session Adapters
8
+ export { AgentBrowserSession, createBrowserSession } from './agent-browser-session';
9
+ // Step execution
10
+ export { StepExecutor } from './step-executor';
11
+ // Evidence collection
12
+ export { EvidenceCollector } from './evidence';
13
+ // Locator generation
14
+ export { LocatorCandidateGenerator } from './locator-candidates';
15
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sDAAsD;AAEtD,oBAAoB;AACpB,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGtC,WAAW;AACX,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGzD,2BAA2B;AAC3B,OAAO,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAmBpF,iBAAiB;AACjB,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAG/C,sBAAsB;AACtB,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAO/C,qBAAqB;AACrB,OAAO,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC"}
@@ -0,0 +1,127 @@
1
+ /**
2
+ * A locator candidate with confidence score
3
+ */
4
+ export interface LocatorCandidate {
5
+ locator: string;
6
+ type: 'ref' | 'css' | 'xpath' | 'text' | 'role' | 'testid';
7
+ confidence: number;
8
+ description?: string;
9
+ }
10
+ /**
11
+ * Element information from browser snapshot
12
+ */
13
+ export interface ElementInfo {
14
+ ref: string;
15
+ tag: string;
16
+ role?: string;
17
+ text?: string;
18
+ ariaLabel?: string;
19
+ testId?: string;
20
+ className?: string;
21
+ id?: string;
22
+ attributes?: Record<string, string>;
23
+ }
24
+ /**
25
+ * Configuration for the locator generator
26
+ */
27
+ export interface LocatorCandidateGeneratorConfig {
28
+ preferredStrategies?: ('ref' | 'testid' | 'role' | 'text' | 'css' | 'xpath')[];
29
+ maxCandidates?: number;
30
+ }
31
+ /**
32
+ * LocatorCandidateGenerator - Generates ranked locator options for elements
33
+ *
34
+ * Uses multiple strategies to find elements:
35
+ * - Element refs from agent-browser snapshots
36
+ * - Test IDs (data-testid, data-test, etc.)
37
+ * - ARIA roles and labels
38
+ * - Text content matching
39
+ * - CSS selectors
40
+ * - XPath expressions
41
+ */
42
+ export declare class LocatorCandidateGenerator {
43
+ private preferredStrategies;
44
+ private maxCandidates;
45
+ constructor(config?: LocatorCandidateGeneratorConfig);
46
+ /**
47
+ * Generate locator candidates for an element based on natural language query
48
+ *
49
+ * @param query - Natural language description (e.g., "Submit button in the form")
50
+ * @param snapshot - Browser snapshot containing element refs
51
+ * @returns Promise resolving to ranked list of locator strings
52
+ */
53
+ generateCandidates(query: string, snapshot: Record<string, unknown>): Promise<string[]>;
54
+ /**
55
+ * Generate detailed locator candidates with metadata
56
+ *
57
+ * @param query - Natural language description
58
+ * @param snapshot - Browser snapshot
59
+ * @returns Promise resolving to ranked list of candidates with scores
60
+ */
61
+ generateDetailedCandidates(query: string, snapshot: Record<string, unknown>): Promise<LocatorCandidate[]>;
62
+ /**
63
+ * Generate all applicable locator candidates for a known element
64
+ *
65
+ * @param element - Element information
66
+ * @returns Promise resolving to ranked list of candidates
67
+ */
68
+ generateCandidatesForElement(element: ElementInfo): Promise<LocatorCandidate[]>;
69
+ /**
70
+ * Find candidate locators matching a query
71
+ */
72
+ private findCandidates;
73
+ /**
74
+ * Parse element info from snapshot ref data
75
+ */
76
+ private parseElementFromRef;
77
+ /**
78
+ * Calculate how well an element matches the query
79
+ * Returns a score from 0 (no match) to 1 (perfect match)
80
+ */
81
+ private calculateMatchScore;
82
+ /**
83
+ * Generate a CSS selector for an element
84
+ */
85
+ private generateCssSelectorForElement;
86
+ /**
87
+ * Escape special characters in CSS selectors
88
+ */
89
+ private escapeCssSelector;
90
+ /**
91
+ * Calculate CSS selector confidence based on element attributes
92
+ */
93
+ private calculateCssConfidence;
94
+ /**
95
+ * Generate a locator from element ref
96
+ */
97
+ generateRefLocator(ref: string): LocatorCandidate;
98
+ /**
99
+ * Generate a locator from test ID
100
+ */
101
+ generateTestIdLocator(testId: string): LocatorCandidate;
102
+ /**
103
+ * Generate a locator from ARIA role
104
+ */
105
+ generateRoleLocator(role: string, name?: string): LocatorCandidate;
106
+ /**
107
+ * Generate a locator from text content
108
+ */
109
+ generateTextLocator(text: string, exact?: boolean): LocatorCandidate;
110
+ /**
111
+ * Generate a CSS selector locator
112
+ */
113
+ generateCssLocator(selector: string): LocatorCandidate;
114
+ /**
115
+ * Get the maximum number of candidates to return
116
+ */
117
+ getMaxCandidates(): number;
118
+ /**
119
+ * Set the maximum number of candidates to return
120
+ */
121
+ setMaxCandidates(max: number): void;
122
+ /**
123
+ * Get the preferred strategies in order
124
+ */
125
+ getPreferredStrategies(): string[];
126
+ }
127
+ //# sourceMappingURL=locator-candidates.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"locator-candidates.d.ts","sourceRoot":"","sources":["../src/locator-candidates.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,KAAK,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAC9C,mBAAmB,CAAC,EAAE,CAAC,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAC,EAAE,CAAC;IAC/E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA0CD;;;;;;;;;;GAUG;AACH,qBAAa,yBAAyB;IACpC,OAAO,CAAC,mBAAmB,CAAW;IACtC,OAAO,CAAC,aAAa,CAAS;gBAElB,MAAM,GAAE,+BAAoC;IAWxD;;;;;;OAMG;IACG,kBAAkB,CACtB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,MAAM,EAAE,CAAC;IAKpB;;;;;;OAMG;IACG,0BAA0B,CAC9B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAK9B;;;;;OAKG;IACG,4BAA4B,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAuCrF;;OAEG;YACW,cAAc;IAyC5B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAc3B;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAoE3B;;OAEG;IACH,OAAO,CAAC,6BAA6B;IAqBrC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAe9B;;OAEG;IACH,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB;IASjD;;OAEG;IACH,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB;IASvD;;OAEG;IACH,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,gBAAgB;IAUlE;;OAEG;IACH,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,OAAe,GAAG,gBAAgB;IAU3E;;OAEG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB;IAStD;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;OAEG;IACH,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAInC;;OAEG;IACH,sBAAsB,IAAI,MAAM,EAAE;CAGnC"}