explorbot 0.1.11 → 0.1.12

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/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -104,7 +104,7 @@
     "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",

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;

package/dist/src/ai/bosun.js

@@ -5,8 +5,8 @@ import { ActionResult } from "../action-result.js";
 import { setActivity } from "../activity.js";
 import { Observability } from "../observability.js";
 import { Plan, Task, Test, TestResult } from "../test-plan.js";
-import { HooksRunner } from "../utils/hooks-runner.js";
 import { getCliName } from "../utils/cli-name.js";
+import { HooksRunner } from "../utils/hooks-runner.js";
 import { createDebug, tag } from "../utils/logger.js";
 import { loop, pause } from "../utils/loop.js";
 import { printNextSteps } from "../utils/next-steps.js";

package/dist/src/ai/historian/codeceptjs.js

@@ -5,6 +5,7 @@ import { ConfigParser } from "../../config.js";
 import { KnowledgeTracker } from "../../knowledge-tracker.js";
 import { tag } from "../../utils/logger.js";
 import { relativeToCwd } from "../../utils/next-steps.js";
+import { safeFilename } from "../../utils/strings.js";
 import { ASSERTION_TOOLS, CODECEPT_TOOLS } from "../tools.js";
 import { escapeString, getExecutionLabel, isNonReusableCode, stripComments } from "./utils.js";
 export function WithCodeceptJS(Base) {
@@ -78,8 +79,7 @@ export function WithCodeceptJS(Base) {
             }
             const testsDir = ConfigParser.getInstance().getTestsDir();
             mkdirSync(testsDir, { recursive: true });
-            const filename = plan.title.replace(/[^a-zA-Z0-9]/g, '_').toLowerCase();
-            const filePath = join(testsDir, `${filename}.js`);
+            const filePath = join(testsDir, safeFilename(plan.title, '.js'));
             writeFileSync(filePath, lines.join('\n'));
             this.savedFiles.add(filePath);
             tag('substep').log(`Saved plan tests to: ${relativeToCwd(filePath)}`);

package/dist/src/ai/historian/experience.js

@@ -29,6 +29,7 @@ export function WithExperience(Base) {
             if (task instanceof Test && result !== 'failed') {
                 await this.reportSession(task, steps);
             }
+            await this.stopScreencast();
             tag('substep').log(`Historian saved session for: ${task.description}`);
         }
         async reportSession(test, steps) {

package/dist/src/ai/historian/playwright.js

@@ -6,6 +6,7 @@ import { KnowledgeTracker } from "../../knowledge-tracker.js";
 import { renderAssertion, renderCall } from "../../playwright-recorder.js";
 import { tag } from "../../utils/logger.js";
 import { relativeToCwd } from "../../utils/next-steps.js";
+import { safeFilename } from "../../utils/strings.js";
 import { ASSERTION_TOOLS, CODECEPT_TOOLS } from "../tools.js";
 import { escapeString, getExecutionLabel } from "./utils.js";
 const PLAYWRIGHT_EMITTED_TOOLS = [...CODECEPT_TOOLS, ...ASSERTION_TOOLS];
@@ -14,7 +15,7 @@ export function WithPlaywright(Base) {
         async toPlaywrightCode(conversation, scenario) {
             const toolExecutions = conversation.getToolExecutions();
             const successfulSteps = toolExecutions.filter((exec) => exec.wasSuccessful && PLAYWRIGHT_EMITTED_TOOLS.includes(exec.toolName));
-            const callsByGroup = this.recorder ? await this.recorder.exportChunk() : new Map();
+            const callsByGroup = this.playwright?.recorder ? await this.playwright.recorder.exportChunk() : new Map();
             const stepLines = [];
             for (const exec of successfulSteps) {
                 const explanation = getExecutionLabel(exec);
@@ -46,7 +47,7 @@ export function WithPlaywright(Base) {
                     }
                 }
             }
-            const pilotVerifications = this.recorder ? this.recorder.drainVerifications() : [];
+            const pilotVerifications = this.playwright?.recorder ? this.playwright.recorder.drainVerifications() : [];
             if (pilotVerifications.length > 0) {
                 const assertionLines = [];
                 for (const step of pilotVerifications) {
@@ -115,8 +116,7 @@ export function WithPlaywright(Base) {
             lines.push('});');
             const testsDir = ConfigParser.getInstance().getTestsDir();
             mkdirSync(testsDir, { recursive: true });
-            const filename = plan.title.replace(/[^a-zA-Z0-9]/g, '_').toLowerCase();
-            const filePath = join(testsDir, `${filename}.spec.ts`);
+            const filePath = join(testsDir, safeFilename(plan.title, '.spec.ts'));
             writeFileSync(filePath, lines.join('\n'));
             this.savedFiles.add(filePath);
             tag('substep').log(`Saved plan tests to: ${relativeToCwd(filePath)}`);

package/dist/src/ai/historian/screencast.js

@@ -0,0 +1,121 @@
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+// @ts-ignore
+import * as codeceptjs from 'codeceptjs';
+import { outputPath } from "../../config.js";
+import { tag } from "../../utils/logger.js";
+import { relativeToCwd } from "../../utils/next-steps.js";
+import { safeFilename } from "../../utils/strings.js";
+import { debugLog } from "./mixin.js";
+export function WithScreencast(Base) {
+    return class extends Base {
+        screencastPage = null;
+        screencastActive = false;
+        screencastPath = null;
+        screencastListenersInstalled = false;
+        screencastTask = null;
+        screencastLastChapter = null;
+        onTestBefore;
+        onStepPassed;
+        onTestAfter;
+        isScreencastActive() {
+            return this.screencastActive;
+        }
+        attachScreencast() {
+            if (this.screencastListenersInstalled)
+                return;
+            if (!this.config?.ai?.agents?.historian?.screencast)
+                return;
+            if (!this.playwright?.helper)
+                return;
+            this.onTestBefore = (test) => {
+                void this.startScreencast(test);
+            };
+            this.onStepPassed = (step) => {
+                void this.emitChapter(step);
+            };
+            this.onTestAfter = () => {
+                void this.stopScreencast();
+            };
+            codeceptjs.event.dispatcher.on('test.before', this.onTestBefore);
+            codeceptjs.event.dispatcher.on('step.passed', this.onStepPassed);
+            codeceptjs.event.dispatcher.on('test.after', this.onTestAfter);
+            this.screencastListenersInstalled = true;
+        }
+        async startScreencast(test) {
+            if (this.screencastActive)
+                return;
+            const page = this.playwright?.helper?.page;
+            if (!page?.screencast?.start)
+                return;
+            const task = test?._explorbotTest;
+            const scenarioName = task?.scenario || test?.title || 'scenario';
+            const planTitle = task?.plan?.title;
+            const planTests = task?.plan?.tests;
+            const index = planTests && task ? planTests.indexOf(task) + 1 : 0;
+            const parts = [];
+            if (planTitle)
+                parts.push(safeFilename(planTitle));
+            if (index > 0)
+                parts.push(String(index));
+            parts.push(safeFilename(scenarioName));
+            const dir = outputPath('screencasts');
+            mkdirSync(dir, { recursive: true });
+            const filePath = join(dir, `${parts.join('-')}.webm`);
+            const screencastConfig = this.config?.ai?.agents?.historian?.screencast;
+            const screencastOpts = typeof screencastConfig === 'object' ? screencastConfig : {};
+            const size = screencastOpts.size ?? page.viewportSize?.() ?? undefined;
+            const quality = screencastOpts.quality ?? 95;
+            try {
+                await page.screencast.start({ path: filePath, quality, size });
+                await page.screencast.showActions({ position: 'top-left' });
+                this.screencastPage = page;
+                this.screencastPath = filePath;
+                this.screencastActive = true;
+                this.screencastTask = test?._explorbotTest || null;
+                this.screencastLastChapter = null;
+            }
+            catch (err) {
+                tag('substep').log(`Screencast start failed: ${err.message}`);
+            }
+        }
+        async emitChapter(_step) {
+            if (!this.screencastActive)
+                return;
+            const explanation = this.screencastTask?.activeNote?.getMessage?.();
+            if (!explanation)
+                return;
+            if (explanation === this.screencastLastChapter)
+                return;
+            this.screencastLastChapter = explanation;
+            try {
+                await this.screencastPage.screencast.showChapter(explanation);
+            }
+            catch (err) {
+                debugLog('screencast.showChapter failed:', err);
+            }
+        }
+        async stopScreencast() {
+            if (!this.screencastActive)
+                return;
+            const path = this.screencastPath;
+            const task = this.screencastTask;
+            try {
+                await this.screencastPage.screencast.stop();
+            }
+            catch (err) {
+                tag('substep').log(`Screencast stop failed: ${err.message}`);
+            }
+            this.screencastActive = false;
+            this.screencastPage = null;
+            this.screencastPath = null;
+            this.screencastTask = null;
+            this.screencastLastChapter = null;
+            if (path) {
+                this.savedFiles.add(path);
+                task?.addArtifact?.(path);
+                tag('substep').log(`Saved screencast: ${relativeToCwd(path)}`);
+            }
+        }
+    };
+}

package/dist/src/ai/historian.js

@@ -5,18 +5,20 @@ import { relativeToCwd } from "../utils/next-steps.js";
 import { WithCodeceptJS } from "./historian/codeceptjs.js";
 import { WithExperience } from "./historian/experience.js";
 import { WithPlaywright } from "./historian/playwright.js";
+import { WithScreencast } from "./historian/screencast.js";
 export { isNonReusableCode } from "./historian/utils.js";
-const HistorianBase = WithPlaywright(WithCodeceptJS(WithExperience(Object)));
+const HistorianBase = WithScreencast(WithPlaywright(WithCodeceptJS(WithExperience(Object))));
 export class Historian extends HistorianBase {
-    constructor(provider, experienceTracker, reporter, stateManager, config, recorder) {
+    constructor(provider, experienceTracker, reporter, stateManager, config, playwright) {
         super();
         this.provider = provider;
         this.experienceTracker = experienceTracker || new ExperienceTracker();
         this.reporter = reporter;
         this.stateManager = stateManager;
         this.config = config;
-        this.recorder = recorder;
+        this.playwright = playwright;
         this.savedFiles = new Set();
+        this.attachScreencast();
     }
     isPlaywrightFramework() {
         return this.config?.ai?.agents?.historian?.framework === 'playwright';

package/dist/src/commands/explore-command.js

@@ -1,11 +1,13 @@
 import figureSet from 'figures';
 import { getStyles } from '../ai/planner/styles.js';
+import { outputPath } from '../config.js';
 import { Stats } from '../stats.js';
 import { getCliName } from "../utils/cli-name.js";
 import { ErrorPageError } from "../utils/error-page.js";
 import { tag } from '../utils/logger.js';
 import { jsonToTable } from '../utils/markdown-parser.js';
 import { printNextSteps, relativeToCwd } from "../utils/next-steps.js";
+import { safeFilename } from "../utils/strings.js";
 import { BaseCommand } from './base-command.js';
 export class ExploreCommand extends BaseCommand {
     name = 'explore';
@@ -145,11 +147,25 @@ export class ExploreCommand extends BaseCommand {
             });
         }
         const savedFiles = this.explorBot.agentHistorian().getSavedFiles();
-        if (savedFiles.length > 0) {
-            const commands = savedFiles.map((f) => ({ label: '', command: `${cli} rerun ${relativeToCwd(f)}` }));
+        const screencasts = savedFiles.filter((f) => f.endsWith('.webm'));
+        const testFiles = savedFiles.filter((f) => !f.endsWith('.webm'));
+        if (testFiles.length > 0) {
+            const commands = testFiles.map((f) => ({ label: '', command: `${cli} rerun ${relativeToCwd(f)}` }));
             commands.push({ label: 'List tests', command: `${cli} runs` });
             sections.push({
-                label: `Generated tests (${savedFiles.length})`,
+                label: `Generated tests (${testFiles.length})`,
+                commands,
+            });
+        }
+        if (screencasts.length > 0) {
+            const commands = screencasts.map((f) => ({ label: '', command: relativeToCwd(f) }));
+            const screencastDir = relativeToCwd(outputPath('screencasts'));
+            const planSlugs = [...new Set(this.completedPlans.map((p) => safeFilename(p.title)).filter(Boolean))];
+            for (const slug of planSlugs) {
+                commands.push({ label: 'Browse plan', command: `ls ${screencastDir}/${slug}-*` });
+            }
+            sections.push({
+                label: `Screencasts (${screencasts.length})`,
                 commands,
             });
         }

package/dist/src/explorbot.js

@@ -218,7 +218,10 @@ export class ExplorBot {
         return (this.agents.historian ||= this.createAgent(({ ai, explorer, config }) => {
             const experienceTracker = explorer.getStateManager().getExperienceTracker();
             const reporter = explorer.getReporter();
-            return new Historian(ai, experienceTracker, reporter, explorer.getStateManager(), config, explorer.getPlaywrightRecorder());
+            return new Historian(ai, experienceTracker, reporter, explorer.getStateManager(), config, {
+                recorder: explorer.getPlaywrightRecorder(),
+                helper: explorer.playwrightHelper,
+            });
         }));
     }
     agentRerunner() {

package/dist/src/explorer.js

@@ -612,6 +612,7 @@ function toCodeceptjsTest(test) {
     codeceptjsTest.fullTitle = () => `${parent.title} ${test.scenario}`;
     codeceptjsTest.state = 'pending';
     codeceptjsTest.notes = test.getPrintableNotes();
+    codeceptjsTest._explorbotTest = test;
     return codeceptjsTest;
 }
 const REF_LINE_PATTERN = /^(\s*)-\s+(\w+)\s*(?:"([^"]*)")?.*?\[ref=(e\d+)\]/;
@@ -629,7 +630,7 @@ function parseAriaRefs(ariaSnapshot) {
     return entries;
 }
 export async function annotatePageElements(page) {
-    const ariaSnapshot = await page.locator('body').ariaSnapshot({ forAI: true });
+    const ariaSnapshot = await page.locator('body').ariaSnapshot({ mode: 'ai' });
     const refEntries = parseAriaRefs(ariaSnapshot);
     const byRole = new Map();
     for (const { role, name, ref } of refEntries) {

package/dist/src/reporter.js

@@ -78,6 +78,7 @@ export class Reporter {
         const noteEntries = Object.entries(test.notes)
             .map(([timestampKey, note]) => ({
             startTime: note.startTime,
+            endTime: note.endTime,
             message: note.message,
             status: note.status,
             screenshot: note.screenshot,
@@ -105,7 +106,7 @@ export class Reporter {
             const step = {
                 category: 'user',
                 title: noteEntry.message,
-                duration: 0,
+                duration: Math.max(0, Math.round(noteEntry.endTime - noteEntry.startTime)),
                 status: noteEntry.status || 'none',
                 steps: noteSteps.length > 0 ? noteSteps : undefined,
             };
@@ -148,6 +149,7 @@ export class Reporter {
                 meta = Object.fromEntries(Object.entries(meta).filter(([, v]) => v));
             }
             const steps = this.combineStepsAndNotes(test, screenshotFile);
+            const durationMs = test.getDurationMs();
             const testData = {
                 rid: test.id,
                 title: test.scenario,
@@ -162,6 +164,7 @@ export class Reporter {
                 files: Object.values(test.artifacts) || [],
                 message: test.summary || this.extractLastNoteMessage(test) || '',
                 meta,
+                time: durationMs != null ? Math.round(durationMs) : 0,
             };
             debugLog(testData);
             await this.client.addTestRun(status, testData);

package/dist/src/utils/strings.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 export function truncateJson(input) {
     if (!input)
         return '';
@@ -11,3 +12,17 @@ export function sanitizeFilename(name) {
         .replace(/^_+|_+$/g, '')
         .slice(0, 50);
 }
+export function safeFilename(name, ext = '', maxBytes = 240) {
+    const sanitized = name.replace(/[^a-zA-Z0-9]/g, '_').toLowerCase();
+    const extBytes = Buffer.byteLength(ext, 'utf8');
+    const budget = maxBytes - extBytes;
+    if (Buffer.byteLength(sanitized, 'utf8') <= budget)
+        return sanitized + ext;
+    const hash = createHash('sha1').update(name).digest('hex').slice(0, 8);
+    const suffix = `_${hash}`;
+    let truncated = sanitized;
+    while (Buffer.byteLength(truncated + suffix, 'utf8') > budget && truncated.length > 0) {
+        truncated = truncated.slice(0, -1);
+    }
+    return truncated + suffix + ext;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -104,7 +104,7 @@
     "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",

package/src/action.ts

@@ -21,6 +21,7 @@ import type { StateManager } from './state-manager.js';
 import { extractCodeBlocks } from './utils/code-extractor.js';
 import { htmlCombinedSnapshot, minifyHtml } from './utils/html.js';
 import { createDebug, log, setStepSpanParent, tag } from './utils/logger.js';
+import { safeFilename } from './utils/strings.ts';
 import { throttle } from './utils/throttle.ts';
 
 const debugLog = createDebug('explorbot:action');
@@ -89,7 +90,7 @@ class Action {
       let screenshotFile: string | undefined = undefined;
 
       if (includeScreenshot) {
-        const filename = `${stateHash}_${timestamp}.png`;
+        const filename = safeFilename(`${stateHash}_${timestamp}`, '.png');
         screenshotFile = await (this.actor as any)
           .saveScreenshot(filename)
           .then(() => filename)
@@ -102,13 +103,13 @@ 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: any) => {
         const logTimestamp = new Date().toISOString();
@@ -134,7 +135,7 @@ class Action {
       }
 
       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;

package/src/ai/bosun.ts

@@ -9,8 +9,8 @@ import type { KnowledgeTracker } from '../knowledge-tracker.ts';
 import { Observability } from '../observability.ts';
 import { Plan, Task, Test, TestResult } from '../test-plan.ts';
 import { diffAriaSnapshots } from '../utils/aria.ts';
-import { HooksRunner } from '../utils/hooks-runner.ts';
 import { getCliName } from '../utils/cli-name.ts';
+import { HooksRunner } from '../utils/hooks-runner.ts';
 import { createDebug, tag } from '../utils/logger.ts';
 import { loop, pause } from '../utils/loop.ts';
 import { type NextStepSection, printNextSteps } from '../utils/next-steps.ts';

package/src/ai/historian/codeceptjs.ts

@@ -6,6 +6,7 @@ import { KnowledgeTracker } from '../../knowledge-tracker.ts';
 import type { Plan } from '../../test-plan.ts';
 import { tag } from '../../utils/logger.ts';
 import { relativeToCwd } from '../../utils/next-steps.ts';
+import { safeFilename } from '../../utils/strings.ts';
 import type { Conversation } from '../conversation.ts';
 import { ASSERTION_TOOLS, CODECEPT_TOOLS } from '../tools.ts';
 import type { Constructor } from './mixin.ts';
@@ -97,8 +98,7 @@ export function WithCodeceptJS<T extends Constructor>(Base: T) {
       const testsDir = ConfigParser.getInstance().getTestsDir();
       mkdirSync(testsDir, { recursive: true });
 
-      const filename = plan.title.replace(/[^a-zA-Z0-9]/g, '_').toLowerCase();
-      const filePath = join(testsDir, `${filename}.js`);
+      const filePath = join(testsDir, safeFilename(plan.title, '.js'));
       writeFileSync(filePath, lines.join('\n'));
       this.savedFiles.add(filePath);
 

package/src/ai/historian/experience.ts

@@ -2,7 +2,6 @@ import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult } from '../../action-result.ts';
 import { ExperienceTracker, type SessionStep } from '../../experience-tracker.ts';
-import type { PlaywrightRecorder } from '../../playwright-recorder.ts';
 import type { Reporter, ReporterStep } from '../../reporter.ts';
 import type { StateManager } from '../../state-manager.ts';
 import { type Task, Test } from '../../test-plan.ts';
@@ -24,10 +23,10 @@ export function WithExperience<T extends Constructor>(Base: T) {
     declare experienceTracker: ExperienceTracker;
     declare reporter: Reporter | undefined;
     declare stateManager: StateManager | undefined;
-    declare recorder: PlaywrightRecorder | undefined;
     declare isPlaywrightFramework: () => boolean;
     declare toCode: (conversation: Conversation, scenario: string) => string;
     declare toPlaywrightCode: (conversation: Conversation, scenario: string) => Promise<string>;
+    declare stopScreencast: () => Promise<void>;
 
     async saveSession(task: Task, initialState: ActionResult, conversation: Conversation): Promise<void> {
       debugLog('Saving session experience');
@@ -55,6 +54,8 @@ export function WithExperience<T extends Constructor>(Base: T) {
         await this.reportSession(task, steps);
       }
 
+      await this.stopScreencast();
+
       tag('substep').log(`Historian saved session for: ${task.description}`);
     }
 

package/src/ai/historian/playwright.ts

@@ -7,6 +7,7 @@ import { type PlaywrightRecorder, type TraceCall, renderAssertion, renderCall }
 import type { Plan } from '../../test-plan.ts';
 import { tag } from '../../utils/logger.ts';
 import { relativeToCwd } from '../../utils/next-steps.ts';
+import { safeFilename } from '../../utils/strings.ts';
 import type { Conversation } from '../conversation.ts';
 import { ASSERTION_TOOLS, CODECEPT_TOOLS } from '../tools.ts';
 import type { Constructor } from './mixin.ts';
@@ -21,14 +22,14 @@ export interface PlaywrightMethods {
 
 export function WithPlaywright<T extends Constructor>(Base: T) {
   return class extends Base {
-    declare recorder: PlaywrightRecorder | undefined;
+    declare playwright: { recorder: PlaywrightRecorder; helper: any } | undefined;
     declare savedFiles: Set<string>;
 
     async toPlaywrightCode(conversation: Conversation, scenario: string): Promise<string> {
       const toolExecutions = conversation.getToolExecutions();
       const successfulSteps = toolExecutions.filter((exec) => exec.wasSuccessful && PLAYWRIGHT_EMITTED_TOOLS.includes(exec.toolName as any));
 
-      const callsByGroup = this.recorder ? await this.recorder.exportChunk() : new Map<string, TraceCall[]>();
+      const callsByGroup = this.playwright?.recorder ? await this.playwright.recorder.exportChunk() : new Map<string, TraceCall[]>();
 
       const stepLines: string[] = [];
       for (const exec of successfulSteps) {
@@ -59,7 +60,7 @@ export function WithPlaywright<T extends Constructor>(Base: T) {
         }
       }
 
-      const pilotVerifications = this.recorder ? this.recorder.drainVerifications() : [];
+      const pilotVerifications = this.playwright?.recorder ? this.playwright.recorder.drainVerifications() : [];
       if (pilotVerifications.length > 0) {
         const assertionLines: string[] = [];
         for (const step of pilotVerifications) {
@@ -135,8 +136,7 @@ export function WithPlaywright<T extends Constructor>(Base: T) {
       const testsDir = ConfigParser.getInstance().getTestsDir();
       mkdirSync(testsDir, { recursive: true });
 
-      const filename = plan.title.replace(/[^a-zA-Z0-9]/g, '_').toLowerCase();
-      const filePath = join(testsDir, `${filename}.spec.ts`);
+      const filePath = join(testsDir, safeFilename(plan.title, '.spec.ts'));
       writeFileSync(filePath, lines.join('\n'));
       this.savedFiles.add(filePath);
 

package/src/ai/historian/screencast.ts

@@ -0,0 +1,133 @@
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+// @ts-ignore
+import * as codeceptjs from 'codeceptjs';
+import { outputPath } from '../../config.ts';
+import type { ExplorbotConfig } from '../../config.ts';
+import type { PlaywrightRecorder } from '../../playwright-recorder.ts';
+import { tag } from '../../utils/logger.ts';
+import { relativeToCwd } from '../../utils/next-steps.ts';
+import { safeFilename } from '../../utils/strings.ts';
+import { type Constructor, debugLog } from './mixin.ts';
+
+export interface ScreencastMethods {
+  attachScreencast(): void;
+  isScreencastActive(): boolean;
+  stopScreencast(): Promise<void>;
+}
+
+export function WithScreencast<T extends Constructor>(Base: T) {
+  return class extends Base {
+    declare config: ExplorbotConfig | undefined;
+    declare savedFiles: Set<string>;
+    declare playwright: { recorder: PlaywrightRecorder; helper: any } | undefined;
+
+    private screencastPage: any = null;
+    private screencastActive = false;
+    private screencastPath: string | null = null;
+    private screencastListenersInstalled = false;
+    private screencastTask: any = null;
+    private screencastLastChapter: string | null = null;
+    private onTestBefore?: (test: any) => void;
+    private onStepPassed?: (step: any) => void;
+    private onTestAfter?: () => void;
+
+    isScreencastActive(): boolean {
+      return this.screencastActive;
+    }
+
+    attachScreencast(): void {
+      if (this.screencastListenersInstalled) return;
+      if (!this.config?.ai?.agents?.historian?.screencast) return;
+      if (!this.playwright?.helper) return;
+
+      this.onTestBefore = (test: any) => {
+        void this.startScreencast(test);
+      };
+      this.onStepPassed = (step: any) => {
+        void this.emitChapter(step);
+      };
+      this.onTestAfter = () => {
+        void this.stopScreencast();
+      };
+
+      codeceptjs.event.dispatcher.on('test.before', this.onTestBefore);
+      codeceptjs.event.dispatcher.on('step.passed', this.onStepPassed);
+      codeceptjs.event.dispatcher.on('test.after', this.onTestAfter);
+
+      this.screencastListenersInstalled = true;
+    }
+
+    private async startScreencast(test: any): Promise<void> {
+      if (this.screencastActive) return;
+      const page = this.playwright?.helper?.page;
+      if (!page?.screencast?.start) return;
+
+      const task = test?._explorbotTest;
+      const scenarioName = task?.scenario || test?.title || 'scenario';
+      const planTitle: string | undefined = task?.plan?.title;
+      const planTests: any[] | undefined = task?.plan?.tests;
+      const index = planTests && task ? planTests.indexOf(task) + 1 : 0;
+
+      const parts: string[] = [];
+      if (planTitle) parts.push(safeFilename(planTitle));
+      if (index > 0) parts.push(String(index));
+      parts.push(safeFilename(scenarioName));
+
+      const dir = outputPath('screencasts');
+      mkdirSync(dir, { recursive: true });
+      const filePath = join(dir, `${parts.join('-')}.webm`);
+
+      const screencastConfig = this.config?.ai?.agents?.historian?.screencast;
+      const screencastOpts = typeof screencastConfig === 'object' ? screencastConfig : {};
+      const size = screencastOpts.size ?? page.viewportSize?.() ?? undefined;
+      const quality = screencastOpts.quality ?? 95;
+
+      try {
+        await page.screencast.start({ path: filePath, quality, size });
+        await page.screencast.showActions({ position: 'top-left' });
+        this.screencastPage = page;
+        this.screencastPath = filePath;
+        this.screencastActive = true;
+        this.screencastTask = test?._explorbotTest || null;
+        this.screencastLastChapter = null;
+      } catch (err) {
+        tag('substep').log(`Screencast start failed: ${(err as Error).message}`);
+      }
+    }
+
+    private async emitChapter(_step: any): Promise<void> {
+      if (!this.screencastActive) return;
+      const explanation = this.screencastTask?.activeNote?.getMessage?.();
+      if (!explanation) return;
+      if (explanation === this.screencastLastChapter) return;
+      this.screencastLastChapter = explanation;
+      try {
+        await this.screencastPage.screencast.showChapter(explanation);
+      } catch (err) {
+        debugLog('screencast.showChapter failed:', err);
+      }
+    }
+
+    async stopScreencast(): Promise<void> {
+      if (!this.screencastActive) return;
+      const path = this.screencastPath;
+      const task = this.screencastTask;
+      try {
+        await this.screencastPage.screencast.stop();
+      } catch (err) {
+        tag('substep').log(`Screencast stop failed: ${(err as Error).message}`);
+      }
+      this.screencastActive = false;
+      this.screencastPage = null;
+      this.screencastPath = null;
+      this.screencastTask = null;
+      this.screencastLastChapter = null;
+      if (path) {
+        this.savedFiles.add(path);
+        task?.addArtifact?.(path);
+        tag('substep').log(`Saved screencast: ${relativeToCwd(path)}`);
+      }
+    }
+  };
+}

package/src/ai/historian.ts

@@ -10,13 +10,14 @@ import { relativeToCwd } from '../utils/next-steps.ts';
 import { type CodeceptJSMethods, WithCodeceptJS } from './historian/codeceptjs.ts';
 import { type ExperienceMethods, WithExperience } from './historian/experience.ts';
 import { type PlaywrightMethods, WithPlaywright } from './historian/playwright.ts';
+import { type ScreencastMethods, WithScreencast } from './historian/screencast.ts';
 import type { Provider } from './provider.ts';
 
 export { isNonReusableCode } from './historian/utils.ts';
 
-const HistorianBase = WithPlaywright(WithCodeceptJS(WithExperience(Object as unknown as new (...args: any[]) => object)));
+const HistorianBase = WithScreencast(WithPlaywright(WithCodeceptJS(WithExperience(Object as unknown as new (...args: any[]) => object))));
 
-export interface Historian extends ExperienceMethods, CodeceptJSMethods, PlaywrightMethods {}
+export interface Historian extends ExperienceMethods, CodeceptJSMethods, PlaywrightMethods, ScreencastMethods {}
 
 export class Historian extends HistorianBase {
   declare provider: Provider;
@@ -24,18 +25,19 @@ export class Historian extends HistorianBase {
   declare reporter: Reporter | undefined;
   declare stateManager: StateManager | undefined;
   declare config: ExplorbotConfig | undefined;
-  declare recorder: PlaywrightRecorder | undefined;
+  declare playwright: { recorder: PlaywrightRecorder; helper: any } | undefined;
   declare savedFiles: Set<string>;
 
-  constructor(provider: Provider, experienceTracker?: ExperienceTracker, reporter?: Reporter, stateManager?: StateManager, config?: ExplorbotConfig, recorder?: PlaywrightRecorder) {
+  constructor(provider: Provider, experienceTracker?: ExperienceTracker, reporter?: Reporter, stateManager?: StateManager, config?: ExplorbotConfig, playwright?: { recorder: PlaywrightRecorder; helper: any }) {
     super();
     this.provider = provider;
     this.experienceTracker = experienceTracker || new ExperienceTracker();
     this.reporter = reporter;
     this.stateManager = stateManager;
     this.config = config;
-    this.recorder = recorder;
+    this.playwright = playwright;
     this.savedFiles = new Set();
+    this.attachScreencast();
   }
 
   isPlaywrightFramework(): boolean {

package/src/commands/explore-command.ts

@@ -1,5 +1,6 @@
 import figureSet from 'figures';
 import { getStyles } from '../ai/planner/styles.js';
+import { outputPath } from '../config.js';
 import { Stats } from '../stats.js';
 import type { Plan } from '../test-plan.js';
 import { getCliName } from '../utils/cli-name.ts';
@@ -7,6 +8,7 @@ import { ErrorPageError } from '../utils/error-page.ts';
 import { tag } from '../utils/logger.js';
 import { jsonToTable } from '../utils/markdown-parser.js';
 import { type NextStepSection, printNextSteps, relativeToCwd } from '../utils/next-steps.ts';
+import { safeFilename } from '../utils/strings.ts';
 import { BaseCommand, type Suggestion } from './base-command.js';
 
 export class ExploreCommand extends BaseCommand {
@@ -152,11 +154,27 @@ export class ExploreCommand extends BaseCommand {
     }
 
     const savedFiles = this.explorBot.agentHistorian().getSavedFiles();
-    if (savedFiles.length > 0) {
-      const commands = savedFiles.map((f) => ({ label: '', command: `${cli} rerun ${relativeToCwd(f)}` }));
+    const screencasts = savedFiles.filter((f) => f.endsWith('.webm'));
+    const testFiles = savedFiles.filter((f) => !f.endsWith('.webm'));
+
+    if (testFiles.length > 0) {
+      const commands = testFiles.map((f) => ({ label: '', command: `${cli} rerun ${relativeToCwd(f)}` }));
       commands.push({ label: 'List tests', command: `${cli} runs` });
       sections.push({
-        label: `Generated tests (${savedFiles.length})`,
+        label: `Generated tests (${testFiles.length})`,
+        commands,
+      });
+    }
+
+    if (screencasts.length > 0) {
+      const commands = screencasts.map((f) => ({ label: '', command: relativeToCwd(f) }));
+      const screencastDir = relativeToCwd(outputPath('screencasts'));
+      const planSlugs = [...new Set(this.completedPlans.map((p) => safeFilename(p.title)).filter(Boolean))];
+      for (const slug of planSlugs) {
+        commands.push({ label: 'Browse plan', command: `ls ${screencastDir}/${slug}-*` });
+      }
+      sections.push({
+        label: `Screencasts (${screencasts.length})`,
         commands,
       });
     }

package/src/config.ts

@@ -107,8 +107,14 @@ interface PlannerAgentConfig extends AgentConfig {
   stylesDir?: string;
 }
 
+interface ScreencastConfig {
+  size?: { width: number; height: number };
+  quality?: number;
+}
+
 interface HistorianAgentConfig extends AgentConfig {
   framework?: 'codeceptjs' | 'playwright';
+  screencast?: boolean | ScreencastConfig;
 }
 
 interface AgentsConfig {

package/src/explorbot.ts

@@ -262,7 +262,10 @@ export class ExplorBot {
     return (this.agents.historian ||= this.createAgent(({ ai, explorer, config }) => {
       const experienceTracker = explorer.getStateManager().getExperienceTracker();
       const reporter = explorer.getReporter();
-      return new Historian(ai, experienceTracker, reporter, explorer.getStateManager(), config, explorer.getPlaywrightRecorder());
+      return new Historian(ai, experienceTracker, reporter, explorer.getStateManager(), config, {
+        recorder: explorer.getPlaywrightRecorder(),
+        helper: explorer.playwrightHelper,
+      });
     }));
   }
 

package/src/explorer.ts

@@ -714,6 +714,7 @@ function toCodeceptjsTest(test: Test): any {
   codeceptjsTest.fullTitle = () => `${parent.title} ${test.scenario}`;
   codeceptjsTest.state = 'pending';
   codeceptjsTest.notes = test.getPrintableNotes();
+  codeceptjsTest._explorbotTest = test;
   return codeceptjsTest;
 }
 
@@ -733,7 +734,7 @@ function parseAriaRefs(ariaSnapshot: string): Array<{ role: string; name: string
 }
 
 export async function annotatePageElements(page: any): Promise<{ ariaSnapshot: string; elements: WebElement[] }> {
-  const ariaSnapshot: string = await page.locator('body').ariaSnapshot({ forAI: true });
+  const ariaSnapshot: string = await page.locator('body').ariaSnapshot({ mode: 'ai' });
   const refEntries = parseAriaRefs(ariaSnapshot);
 
   const byRole = new Map<string, Array<{ name: string; ref: string }>>();

package/src/reporter.ts

@@ -104,6 +104,7 @@ export class Reporter {
     const noteEntries = Object.entries(test.notes)
       .map(([timestampKey, note]) => ({
         startTime: note.startTime,
+        endTime: note.endTime,
         message: note.message,
         status: note.status,
         screenshot: note.screenshot,
@@ -135,7 +136,7 @@ export class Reporter {
       const step: Step = {
         category: 'user',
         title: noteEntry.message,
-        duration: 0,
+        duration: Math.max(0, Math.round(noteEntry.endTime - noteEntry.startTime)),
         status: noteEntry.status || 'none',
         steps: noteSteps.length > 0 ? noteSteps : undefined,
       };
@@ -182,6 +183,7 @@ export class Reporter {
       }
 
       const steps = this.combineStepsAndNotes(test, screenshotFile);
+      const durationMs = test.getDurationMs();
 
       const testData = {
         rid: test.id,
@@ -197,6 +199,7 @@ export class Reporter {
         files: Object.values(test.artifacts) || [],
         message: test.summary || this.extractLastNoteMessage(test) || '',
         meta,
+        time: durationMs != null ? Math.round(durationMs) : 0,
       };
 
       debugLog(testData);

package/src/utils/strings.ts

@@ -1,3 +1,5 @@
+import { createHash } from 'node:crypto';
+
 export function truncateJson(input: any): string {
   if (!input) return '';
   const str = JSON.stringify(input);
@@ -11,3 +13,18 @@ export function sanitizeFilename(name: string): string {
     .replace(/^_+|_+$/g, '')
     .slice(0, 50);
 }
+
+export function safeFilename(name: string, ext = '', maxBytes = 240): string {
+  const sanitized = name.replace(/[^a-zA-Z0-9]/g, '_').toLowerCase();
+  const extBytes = Buffer.byteLength(ext, 'utf8');
+  const budget = maxBytes - extBytes;
+  if (Buffer.byteLength(sanitized, 'utf8') <= budget) return sanitized + ext;
+
+  const hash = createHash('sha1').update(name).digest('hex').slice(0, 8);
+  const suffix = `_${hash}`;
+  let truncated = sanitized;
+  while (Buffer.byteLength(truncated + suffix, 'utf8') > budget && truncated.length > 0) {
+    truncated = truncated.slice(0, -1);
+  }
+  return truncated + suffix + ext;
+}