explorbot 0.1.11 → 0.1.13

package/README.md

@@ -173,12 +173,22 @@ See [docs/commands.md](docs/commands.md) for all commands.
 | Test plans | `output/plans/*.md` | Markdown documentation of scenarios |
 | Experience | `./experience/` | What Explorbot learned about your app |
 
-Every run is saved as a real Playwright or CodeceptJS test you can commit and run from CI. Choose the framework in your config:
+Every run is saved as a real Playwright or CodeceptJS test you can commit and run from CI. Configure the Historian to choose the output framework, record screencasts of every run, or both:
 
 ```js
-ai: { agents: { historian: { framework: 'playwright' } } }  // or 'codeceptjs' (default)
+ai: {
+  agents: {
+    historian: {
+      framework: 'playwright',          // or 'codeceptjs' (default)
+      screencast: true,                 // record .webm video per scenario, chapters labelled with each step
+      // screencast: { size: { width: 1280, height: 720 }, quality: 95 }
+    },
+  },
+}
 ```
 
+Screencasts land in `output/screencasts/<plan>-<n>-<scenario>.webm` and are listed alongside generated tests at the end of every run.
+
 Playwright output uses the actual `page.locator(...)` calls executed during the run, with each action wrapped in `test.step` so failures land on a labelled step:
 
 ```ts

package/bin/explorbot-cli.ts

@@ -586,32 +586,32 @@ addCommonOptions(program.command('research <url>').description('Research a page
   }
 );
 
-addCommonOptions(program.command('drill <url>').description('Drill all components on a page to learn interactions').option('--knowledge <path>', 'Save learned interactions to knowledge file at this URL path').option('--max <count>', 'Maximum number of components to drill', '20')).action(
-  async (url, options) => {
-    try {
-      const explorBot = new ExplorBot(buildExplorBotOptions(url, options));
-      await explorBot.start();
+addCommonOptions(
+  program.command('drill <url>').alias('driller').description('Drill all components on a page to learn interactions').option('--knowledge <path>', 'Save learned interactions to knowledge file at this URL path').option('--max-components <count>', 'Maximum number of components to drill')
+).action(async (url, options) => {
+  try {
+    const explorBot = new ExplorBot(buildExplorBotOptions(url, options));
+    await explorBot.start();
 
-      await explorBot.visit(url);
+    await explorBot.visit(url);
 
-      const plan = await explorBot.agentBosun().drill({
-        knowledgePath: options.knowledge,
-        maxComponents: Number.parseInt(options.max, 10),
-        interactive: false,
-      });
+    const plan = await explorBot.agentDriller().drill({
+      knowledgePath: options.knowledge,
+      maxComponents: Number.parseInt(options.maxComponents || '30', 10),
+      interactive: false,
+    });
 
-      console.log(`\nDrill completed: ${plan.tests.length} components`);
-      console.log(`Successful: ${plan.tests.filter((t) => t.isSuccessful).length}`);
-      console.log(`Failed: ${plan.tests.filter((t) => t.hasFailed).length}`);
+    console.log(`\nDrill completed: ${plan.tests.length} components`);
+    console.log(`Successful: ${plan.tests.filter((t) => t.isSuccessful).length}`);
+    console.log(`Failed: ${plan.tests.filter((t) => t.hasFailed).length}`);
 
-      await explorBot.stop();
-      await showStatsAndExit(0);
-    } catch (error) {
-      console.error('Failed:', error instanceof Error ? error.message : 'Unknown error');
-      await showStatsAndExit(1);
-    }
+    await explorBot.stop();
+    await showStatsAndExit(0);
+  } catch (error) {
+    console.error('Failed:', error instanceof Error ? error.message : 'Unknown error');
+    await showStatsAndExit(1);
   }
-);
+});
 
 program
   .command('context <url>')

package/dist/bin/explorbot-cli.js

@@ -531,14 +531,14 @@ addCommonOptions(program.command('research <url>').description('Research a page
         await showStatsAndExit(1);
     }
 });
-addCommonOptions(program.command('drill <url>').description('Drill all components on a page to learn interactions').option('--knowledge <path>', 'Save learned interactions to knowledge file at this URL path').option('--max <count>', 'Maximum number of components to drill', '20')).action(async (url, options) => {
+addCommonOptions(program.command('drill <url>').alias('driller').description('Drill all components on a page to learn interactions').option('--knowledge <path>', 'Save learned interactions to knowledge file at this URL path').option('--max-components <count>', 'Maximum number of components to drill')).action(async (url, options) => {
     try {
         const explorBot = new ExplorBot(buildExplorBotOptions(url, options));
         await explorBot.start();
         await explorBot.visit(url);
-        const plan = await explorBot.agentBosun().drill({
+        const plan = await explorBot.agentDriller().drill({
             knowledgePath: options.knowledge,
-            maxComponents: Number.parseInt(options.max, 10),
+            maxComponents: Number.parseInt(options.maxComponents || '30', 10),
             interactive: false,
         });
         console.log(`\nDrill completed: ${plan.tests.length} components`);

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -78,7 +78,7 @@
     "@opentelemetry/sdk-trace-base": "^2.2.0",
     "@opentelemetry/semantic-conventions": "^1.38.0",
     "@scalar/openapi-parser": "^0.25.6",
-    "@testomatio/reporter": "^2.7.6",
+    "@testomatio/reporter": "^2.7.9-beta.2-markdown",
     "ai": "^6.0.6",
     "axe-core": "^4.11.1",
     "bash-tool": "^1.3.15",
@@ -104,11 +104,12 @@
     "micromatch": "^4.0.8",
     "ora-classic": "^5.4.2",
     "parse5": "^8.0.0",
-    "playwright": "^1.40.0",
+    "playwright": "^1.59.0",
     "react": "^19.1.1",
     "strip-ansi": "^7.1.2",
     "turndown": "^7.2.1",
     "unique-names-generator": "^4.7.1",
+    "yaml": "^2.8.3",
     "yargs": "^17.7.2",
     "zod": "^4.1.8"
   },

package/dist/rules/researcher/container-rules.md

@@ -5,6 +5,8 @@ Container CSS must be a SINGLE semantic selector — one class, one id, or one a
 - VALID: semantic class names that describe what the section IS (`.product-list`, `.sidebar-menu`, `.user-profile`, `.search-results`), semantic roles (`[role="dialog"]`), semantic ids (`#main-content`)
 
 The container must uniquely identify a semantic wrapper, not a path through the DOM.
+
+Iframes are not sections — list each iframe as a single row of type `iframe` inside the section that contains it. Never use an iframe selector as a section's `> Container:`.
 </container_rules>
 
 <css_selector_rules>

package/dist/src/action-result.js

@@ -371,8 +371,9 @@ export class ActionResult {
         try {
             const urlObj = new URL(this.url);
             const path = urlObj.pathname.replace(/\/$/, '') || '/';
+            const search = urlObj.search || '';
             const hash = urlObj.hash || '';
-            return path + hash;
+            return path + search + hash;
         }
         catch {
             // If URL parsing fails, assume it's already a relative URL

package/dist/src/action.js

@@ -12,6 +12,7 @@ import { ConfigParser, outputPath } from './config.js';
 import { Observability } from "./observability.js";
 import { htmlCombinedSnapshot, minifyHtml } from './utils/html.js';
 import { createDebug, log, setStepSpanParent, tag } from './utils/logger.js';
+import { safeFilename } from "./utils/strings.js";
 const debugLog = createDebug('explorbot:action');
 const FATAL_BROWSER_ERRORS = /Frame was detached|Target closed|Execution context was destroyed|Protocol error|Session closed/i;
 class Action {
@@ -73,7 +74,7 @@ class Action {
             const url = page?.url() || (await this.actor.grabCurrentUrl?.());
             let screenshotFile = undefined;
             if (includeScreenshot) {
-                const filename = `${stateHash}_${timestamp}.png`;
+                const filename = safeFilename(`${stateHash}_${timestamp}`, '.png');
                 screenshotFile = await this.actor
                     .saveScreenshot(filename)
                     .then(() => filename)
@@ -85,12 +86,12 @@ class Action {
             // Save HTML to file
             const statesDir = outputPath('states');
             fs.mkdirSync(statesDir, { recursive: true });
-            const htmlFile = `${stateHash}_${timestamp}.html`;
+            const htmlFile = safeFilename(`${stateHash}_${timestamp}`, '.html');
             const htmlPath = join(statesDir, htmlFile);
             fs.writeFileSync(htmlPath, html, 'utf8');
             debugLog('Captured page state');
             // Save logs to file
-            const logFile = `${stateHash}_${timestamp}.log`;
+            const logFile = safeFilename(`${stateHash}_${timestamp}`, '.log');
             const logPath = join(statesDir, logFile);
             const formattedLogs = browserLogs.map((log) => {
                 const logTimestamp = new Date().toISOString();
@@ -112,7 +113,7 @@ class Action {
                 debugLog('ARIA snapshot failed:', err instanceof Error ? `${err.message}\n${err.stack}` : err);
             }
             if (ariaSnapshot) {
-                const ariaFileName = `${stateHash}_${timestamp}.aria.yaml`;
+                const ariaFileName = safeFilename(`${stateHash}_${timestamp}`, '.aria.yaml');
                 const ariaPath = join(statesDir, ariaFileName);
                 fs.writeFileSync(ariaPath, ariaSnapshot, 'utf8');
                 ariaSnapshotFile = ariaFileName;
@@ -323,12 +324,6 @@ class Action {
         }
         catch (error) {
             this.lastError = error;
-            if (error && typeof error === 'object') {
-                const errorObj = error;
-                if (typeof errorObj.fetchDetails === 'function') {
-                    await errorObj.fetchDetails();
-                }
-            }
             debugLog(`Attempt failed: ${codeBlock}: ${errorToString(error) || this.lastError?.toString()}`);
             return false;
         }

package/dist/src/ai/captain.js

@@ -174,8 +174,6 @@ export class Captain extends CaptainBase {
     ${knowledge}
 
     ${experience}
-
-    Use runCommand("/research") if you need deeper page understanding or UI element mapping.
     `;
     }
     planSummary() {