@tangle-network/browser-agent-driver 0.10.0 → 0.12.0

package/dist/showcase/assemble.js

@@ -0,0 +1,107 @@
+/**
+ * Frame assembly — combine screenshot sequence into GIF or video.
+ *
+ * Uses ffmpeg-static which is already a dependency (unused until now).
+ * Falls back gracefully if ffmpeg is not available.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+let ffmpegPath = null;
+function getFfmpeg() {
+    if (ffmpegPath !== null)
+        return ffmpegPath;
+    try {
+        // ffmpeg-static exports the path to the binary
+        ffmpegPath = require('ffmpeg-static');
+        if (!fs.existsSync(ffmpegPath))
+            ffmpegPath = null;
+    }
+    catch {
+        // Try system ffmpeg
+        try {
+            execFileSync('ffmpeg', ['-version'], { stdio: 'ignore' });
+            ffmpegPath = 'ffmpeg';
+        }
+        catch {
+            ffmpegPath = null;
+        }
+    }
+    return ffmpegPath;
+}
+/**
+ * Assemble PNG frames into an animated GIF.
+ *
+ * @param frames - Ordered screenshot frames
+ * @param outputPath - Where to write the GIF
+ * @param opts - Frame rate, loop count
+ * @returns true if successful, false if ffmpeg unavailable
+ */
+export function assembleGif(frames, outputPath, opts) {
+    const ffmpeg = getFfmpeg();
+    if (!ffmpeg || frames.length === 0)
+        return false;
+    const fps = opts?.fps ?? 1;
+    const loop = opts?.loop ?? 0;
+    const maxWidth = opts?.maxWidth ?? 1200;
+    // Write frames to temp dir
+    const tmpDir = path.join(path.dirname(outputPath), '.gif-frames');
+    fs.mkdirSync(tmpDir, { recursive: true });
+    for (let i = 0; i < frames.length; i++) {
+        fs.writeFileSync(path.join(tmpDir, `frame-${String(i).padStart(4, '0')}.png`), frames[i].buffer);
+    }
+    try {
+        execFileSync(ffmpeg, [
+            '-y',
+            '-framerate', String(fps),
+            '-i', path.join(tmpDir, 'frame-%04d.png'),
+            '-vf', `scale='min(${maxWidth},iw)':-1:flags=lanczos,split[s0][s1];[s0]palettegen=max_colors=256:stats_mode=diff[p];[s1][p]paletteuse=dither=bayer:bayer_scale=5`,
+            '-loop', String(loop),
+            outputPath,
+        ], { stdio: 'pipe', timeout: 60_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        // Clean up temp frames
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+/**
+ * Assemble PNG frames into a WebM video.
+ */
+export function assembleVideo(frames, outputPath, opts) {
+    const ffmpeg = getFfmpeg();
+    if (!ffmpeg || frames.length === 0)
+        return false;
+    const fps = opts?.fps ?? 1;
+    const maxWidth = opts?.maxWidth ?? 1440;
+    const tmpDir = path.join(path.dirname(outputPath), '.video-frames');
+    fs.mkdirSync(tmpDir, { recursive: true });
+    for (let i = 0; i < frames.length; i++) {
+        fs.writeFileSync(path.join(tmpDir, `frame-${String(i).padStart(4, '0')}.png`), frames[i].buffer);
+    }
+    try {
+        execFileSync(ffmpeg, [
+            '-y',
+            '-framerate', String(fps),
+            '-i', path.join(tmpDir, 'frame-%04d.png'),
+            '-vf', `scale='min(${maxWidth},iw)':-2`,
+            '-c:v', 'libvpx-vp9',
+            '-crf', '30',
+            '-b:v', '0',
+            '-pix_fmt', 'yuva420p',
+            outputPath,
+        ], { stdio: 'pipe', timeout: 60_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=assemble.js.map

package/dist/showcase/assemble.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assemble.js","sourceRoot":"","sources":["../../src/showcase/assemble.ts"],"names":[],"mappings":"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"}

package/dist/showcase/demo-player.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Interactive demo player generator.
+ *
+ * Takes showcase walkthrough results (screenshots + step metadata) and produces
+ * a self-contained HTML file with an interactive step-by-step player.
+ *
+ * Features:
+ * - Click-through slideshow of annotated screenshots
+ * - Pulsing hotspot circles at click targets
+ * - Step description tooltips
+ * - Progress bar and step counter
+ * - Keyboard navigation (← →)
+ * - Self-contained — single HTML file, images base64-inlined
+ */
+import type { ShowcaseStep } from './types.js';
+export interface DemoStep {
+    /** Screenshot as base64 PNG. */
+    imageBase64: string;
+    /** Width of the screenshot. */
+    width: number;
+    /** Height of the screenshot. */
+    height: number;
+    /** Description shown as tooltip. */
+    description?: string;
+    /** Click hotspot position (percentage of image dimensions). */
+    hotspot?: {
+        xPercent: number;
+        yPercent: number;
+        label?: string;
+    };
+    /** Action that was taken at this step. */
+    action: string;
+}
+export interface DemoConfig {
+    title: string;
+    steps: DemoStep[];
+    /** Brand color for hotspots and UI. Default: #8e59ff */
+    accentColor?: string;
+    /** Auto-advance interval in ms. 0 = manual only. Default: 0 */
+    autoAdvance?: number;
+}
+/**
+ * Generate a self-contained HTML demo player.
+ */
+export declare function generateDemoHtml(config: DemoConfig): string;
+/**
+ * Build DemoSteps from showcase results + original walkthrough steps.
+ *
+ * Reads screenshot PNGs from disk, converts to base64, and maps
+ * step actions to hotspot positions.
+ */
+export declare function buildDemoSteps(screenshotDir: string, walkthroughSteps: ShowcaseStep[], page?: import('playwright').Page): Promise<DemoStep[]>;
+//# sourceMappingURL=demo-player.d.ts.map

package/dist/showcase/demo-player.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo-player.d.ts","sourceRoot":"","sources":["../../src/showcase/demo-player.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,MAAM,WAAW,QAAQ;IACvB,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAA;IACnB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,+DAA+D;IAC/D,OAAO,CAAC,EAAE;QACR,QAAQ,EAAE,MAAM,CAAA;QAChB,QAAQ,EAAE,MAAM,CAAA;QAChB,KAAK,CAAC,EAAE,MAAM,CAAA;KACf,CAAA;IACD,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,QAAQ,EAAE,CAAA;IACjB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAiQ3D;AAMD;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,aAAa,EAAE,MAAM,EACrB,gBAAgB,EAAE,YAAY,EAAE,EAChC,IAAI,CAAC,EAAE,OAAO,YAAY,EAAE,IAAI,GAC/B,OAAO,CAAC,QAAQ,EAAE,CAAC,CA2CrB"}

package/dist/showcase/demo-player.js

@@ -0,0 +1,325 @@
+/**
+ * Interactive demo player generator.
+ *
+ * Takes showcase walkthrough results (screenshots + step metadata) and produces
+ * a self-contained HTML file with an interactive step-by-step player.
+ *
+ * Features:
+ * - Click-through slideshow of annotated screenshots
+ * - Pulsing hotspot circles at click targets
+ * - Step description tooltips
+ * - Progress bar and step counter
+ * - Keyboard navigation (← →)
+ * - Self-contained — single HTML file, images base64-inlined
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+/**
+ * Generate a self-contained HTML demo player.
+ */
+export function generateDemoHtml(config) {
+    const accent = config.accentColor ?? '#8e59ff';
+    const steps = JSON.stringify(config.steps.map(s => ({
+        image: s.imageBase64,
+        description: s.description ?? '',
+        hotspot: s.hotspot ?? null,
+        action: s.action,
+    })));
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(config.title)}</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    background: #0a0a0a;
+    color: #fff;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    min-height: 100vh;
+    padding: 1rem;
+  }
+
+  .demo-container {
+    position: relative;
+    max-width: 1200px;
+    width: 100%;
+    border-radius: 12px;
+    overflow: hidden;
+    border: 1px solid rgba(255,255,255,0.1);
+    background: #111;
+    box-shadow: 0 20px 60px rgba(0,0,0,0.5);
+  }
+
+  /* Browser chrome */
+  .demo-chrome {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 10px 16px;
+    background: #1a1a1a;
+    border-bottom: 1px solid rgba(255,255,255,0.06);
+  }
+  .demo-dot { width: 12px; height: 12px; border-radius: 50%; }
+  .demo-dot.r { background: rgba(255,95,87,0.8); }
+  .demo-dot.y { background: rgba(254,188,46,0.8); }
+  .demo-dot.p { background: ${accent}cc; }
+  .demo-title {
+    margin-left: 12px;
+    font-size: 13px;
+    color: rgba(255,255,255,0.4);
+    font-family: monospace;
+  }
+
+  /* Image viewport */
+  .demo-viewport {
+    position: relative;
+    width: 100%;
+    overflow: hidden;
+    cursor: pointer;
+  }
+  .demo-viewport img {
+    width: 100%;
+    display: block;
+    transition: opacity 0.3s ease;
+  }
+
+  /* Hotspot */
+  .hotspot {
+    position: absolute;
+    transform: translate(-50%, -50%);
+    pointer-events: none;
+    z-index: 10;
+  }
+  .hotspot-ring {
+    width: 40px;
+    height: 40px;
+    border-radius: 50%;
+    border: 2px solid ${accent};
+    animation: pulse 2s ease-in-out infinite;
+  }
+  .hotspot-dot {
+    position: absolute;
+    top: 50%;
+    left: 50%;
+    transform: translate(-50%, -50%);
+    width: 12px;
+    height: 12px;
+    border-radius: 50%;
+    background: ${accent};
+  }
+  .hotspot-label {
+    position: absolute;
+    top: -32px;
+    left: 50%;
+    transform: translateX(-50%);
+    background: ${accent};
+    color: white;
+    font-size: 12px;
+    font-weight: 600;
+    padding: 4px 12px;
+    border-radius: 6px;
+    white-space: nowrap;
+    font-family: -apple-system, sans-serif;
+  }
+
+  @keyframes pulse {
+    0%, 100% { transform: translate(-50%, -50%) scale(1); opacity: 1; }
+    50% { transform: translate(-50%, -50%) scale(1.5); opacity: 0.5; }
+  }
+
+  /* Controls */
+  .demo-controls {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 12px 16px;
+    background: #1a1a1a;
+    border-top: 1px solid rgba(255,255,255,0.06);
+  }
+
+  .demo-step-info {
+    font-size: 13px;
+    color: rgba(255,255,255,0.5);
+  }
+
+  .demo-description {
+    font-size: 14px;
+    color: rgba(255,255,255,0.8);
+    text-align: center;
+    flex: 1;
+    padding: 0 1rem;
+  }
+
+  .demo-nav {
+    display: flex;
+    gap: 8px;
+  }
+  .demo-nav button {
+    background: rgba(255,255,255,0.06);
+    border: 1px solid rgba(255,255,255,0.1);
+    color: white;
+    padding: 6px 16px;
+    border-radius: 6px;
+    cursor: pointer;
+    font-size: 13px;
+    transition: background 0.2s;
+  }
+  .demo-nav button:hover {
+    background: ${accent}33;
+    border-color: ${accent}66;
+  }
+  .demo-nav button:disabled {
+    opacity: 0.3;
+    cursor: not-allowed;
+  }
+
+  /* Progress bar */
+  .demo-progress {
+    height: 3px;
+    background: rgba(255,255,255,0.06);
+    position: relative;
+  }
+  .demo-progress-fill {
+    height: 100%;
+    background: ${accent};
+    transition: width 0.3s ease;
+  }
+</style>
+</head>
+<body>
+
+<div class="demo-container">
+  <div class="demo-chrome">
+    <div class="demo-dot r"></div>
+    <div class="demo-dot y"></div>
+    <div class="demo-dot p"></div>
+    <span class="demo-title">${escapeHtml(config.title)}</span>
+  </div>
+
+  <div class="demo-progress">
+    <div class="demo-progress-fill" id="progress"></div>
+  </div>
+
+  <div class="demo-viewport" id="viewport" onclick="next()">
+    <img id="screenshot" alt="Demo step" />
+    <div class="hotspot" id="hotspot" style="display:none;">
+      <div class="hotspot-ring"></div>
+      <div class="hotspot-dot"></div>
+      <div class="hotspot-label" id="hotspot-label"></div>
+    </div>
+  </div>
+
+  <div class="demo-controls">
+    <div class="demo-step-info" id="step-info">Step 1 of N</div>
+    <div class="demo-description" id="description"></div>
+    <div class="demo-nav">
+      <button onclick="prev()" id="prev-btn">&larr; Back</button>
+      <button onclick="next()" id="next-btn">Next &rarr;</button>
+    </div>
+  </div>
+</div>
+
+<script>
+const steps = ${steps};
+let current = 0;
+
+function render() {
+  const step = steps[current];
+  document.getElementById('screenshot').src = 'data:image/png;base64,' + step.image;
+  document.getElementById('step-info').textContent = 'Step ' + (current + 1) + ' of ' + steps.length;
+  document.getElementById('description').textContent = step.description || '';
+  document.getElementById('progress').style.width = ((current + 1) / steps.length * 100) + '%';
+  document.getElementById('prev-btn').disabled = current === 0;
+  document.getElementById('next-btn').disabled = current === steps.length - 1;
+  document.getElementById('next-btn').textContent = current === steps.length - 1 ? 'Done ✓' : 'Next →';
+
+  const hotspot = document.getElementById('hotspot');
+  const label = document.getElementById('hotspot-label');
+  if (step.hotspot) {
+    hotspot.style.display = 'block';
+    hotspot.style.left = step.hotspot.xPercent + '%';
+    hotspot.style.top = step.hotspot.yPercent + '%';
+    if (step.hotspot.label) {
+      label.textContent = step.hotspot.label;
+      label.style.display = 'block';
+    } else {
+      label.style.display = 'none';
+    }
+  } else {
+    hotspot.style.display = 'none';
+  }
+}
+
+function next() {
+  if (current < steps.length - 1) { current++; render(); }
+}
+function prev() {
+  if (current > 0) { current--; render(); }
+}
+
+document.addEventListener('keydown', (e) => {
+  if (e.key === 'ArrowRight' || e.key === ' ') { e.preventDefault(); next(); }
+  if (e.key === 'ArrowLeft') { e.preventDefault(); prev(); }
+});
+
+render();
+</script>
+
+</body>
+</html>`;
+}
+function escapeHtml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+/**
+ * Build DemoSteps from showcase results + original walkthrough steps.
+ *
+ * Reads screenshot PNGs from disk, converts to base64, and maps
+ * step actions to hotspot positions.
+ */
+export async function buildDemoSteps(screenshotDir, walkthroughSteps, page) {
+    const demoSteps = [];
+    const pngFiles = fs.readdirSync(screenshotDir)
+        .filter(f => f.endsWith('.png') && !f.includes('full-page'))
+        .sort();
+    for (let i = 0; i < pngFiles.length; i++) {
+        const filePath = path.join(screenshotDir, pngFiles[i]);
+        const buffer = fs.readFileSync(filePath);
+        const base64 = buffer.toString('base64');
+        const step = walkthroughSteps[i];
+        let hotspot = undefined;
+        // If the next step has a click action with a selector, calculate hotspot position
+        const nextStep = walkthroughSteps[i + 1];
+        if (nextStep?.action === 'click' && nextStep.selector && page) {
+            try {
+                const el = page.locator(nextStep.selector).first();
+                const box = await el.boundingBox();
+                const viewport = page.viewportSize();
+                if (box && viewport) {
+                    hotspot = {
+                        xPercent: ((box.x + box.width / 2) / viewport.width) * 100,
+                        yPercent: ((box.y + box.height / 2) / viewport.height) * 100,
+                        label: nextStep.capture?.name ?? `Click ${nextStep.selector}`,
+                    };
+                }
+            }
+            catch { /* element not found — skip hotspot */ }
+        }
+        demoSteps.push({
+            imageBase64: base64,
+            width: 1200, // Will be overridden by actual image dimensions if available
+            height: 800,
+            description: step?.capture?.name?.replace(/-/g, ' ').replace(/^\d+-/, '') ?? `Step ${i + 1}`,
+            hotspot,
+            action: step?.action ?? 'screenshot',
+        });
+    }
+    return demoSteps;
+}
+//# sourceMappingURL=demo-player.js.map

package/dist/showcase/demo-player.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo-player.js","sourceRoot":"","sources":["../../src/showcase/demo-player.ts"],"names":[],"mappings":"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"}

package/dist/showcase/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Showcase — deterministic walkthrough capture for marketing assets.
+ *
+ * Unlike `bad run` (LLM-driven exploration) or `bad design-audit` (quality assessment),
+ * showcase executes a pre-scripted walkthrough and captures polished screenshots,
+ * GIFs, and videos. No LLM calls. No quality judgement. Just beautiful captures.
+ *
+ * Reuses:
+ *   - page-interaction.ts: dismissModals() for cookie/popup cleanup
+ *   - browser-launch.ts: buildBrowserLaunchPlan() for consistent browser config
+ *   - cli-ui.ts: CliRenderer for progress output
+ */
+import type { ShowcaseConfig, ShowcaseResult, QuickCaptureConfig } from './types.js';
+export declare function runShowcase(config: ShowcaseConfig): Promise<ShowcaseResult>;
+/**
+ * Quick capture mode — no script file needed.
+ * Captures named positions: 'hero' (viewport), 'full' (full page), 'scroll:N' (scroll N px first).
+ */
+export declare function quickCapture(config: QuickCaptureConfig): Promise<ShowcaseResult>;
+export type { ShowcaseConfig, ShowcaseStep, ShowcaseFrame, ShowcaseResult, QuickCaptureConfig } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/showcase/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/showcase/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EACV,cAAc,EAGd,cAAc,EACd,kBAAkB,EACnB,MAAM,YAAY,CAAA;AAOnB,wBAAsB,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAgIjF;AAID;;;GAGG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CA0DtF;AAmHD,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA"}