@veolab/discoverylab 1.4.4 → 1.6.3

package/dist/infographic-GQAHEOAA.js

@@ -0,0 +1,183 @@
+import "./chunk-R5U7XKVJ.js";
+
+// src/core/export/infographic.ts
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from "fs";
+import { join, dirname, extname } from "path";
+import { fileURLToPath } from "url";
+function findTemplate() {
+  const __dir = dirname(fileURLToPath(import.meta.url));
+  const possiblePaths = [
+    join(__dir, "infographic-template.html"),
+    join(__dir, "..", "export", "infographic-template.html"),
+    join(process.cwd(), "dist", "export", "infographic-template.html"),
+    join(process.cwd(), "src", "core", "export", "infographic-template.html")
+  ];
+  for (const p of possiblePaths) {
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+function imageToBase64(imagePath) {
+  if (!existsSync(imagePath)) return "";
+  const buffer = readFileSync(imagePath);
+  const ext = extname(imagePath).toLowerCase();
+  const mimeTypes = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif"
+  };
+  const mime = mimeTypes[ext] || "image/png";
+  return `data:${mime};base64,${buffer.toString("base64")}`;
+}
+function stripMarkdown(text) {
+  return text.replace(/\*\*(.+?)\*\*/g, "$1").replace(/\*(.+?)\*/g, "$1").replace(/__(.+?)__/g, "$1").replace(/_(.+?)_/g, "$1").replace(/`(.+?)`/g, "$1").replace(/^#{1,3}\s+/gm, "").replace(/^-\s+/gm, "").replace(/^\d+\.\s+/gm, "").replace(/\[(.+?)\]\(.*?\)/g, "$1").trim();
+}
+function collectFrameImages(framesDir, videoPath, projectsDir, projectId) {
+  const imageExts = /\.(png|jpg|jpeg|webp|gif)$/i;
+  const dirs = [
+    framesDir,
+    ...videoPath ? [join(videoPath, "screenshots"), videoPath] : [],
+    ...projectsDir && projectId ? [
+      join(projectsDir, "maestro-recordings", projectId, "screenshots"),
+      join(projectsDir, "web-recordings", projectId, "screenshots")
+    ] : []
+  ];
+  for (const dir of dirs) {
+    if (!existsSync(dir) || !statSync(dir).isDirectory()) continue;
+    const files = readdirSync(dir).filter((f) => imageExts.test(f)).sort().map((f) => join(dir, f));
+    if (files.length > 0) return files;
+  }
+  return [];
+}
+function buildInfographicData(project, frameFiles, frameOcr, annotations) {
+  let flowSteps = [];
+  let uiElements = [];
+  if (project.aiSummary) {
+    const flowMatch = project.aiSummary.match(/## (?:User Flow|Likely User Flow)\n([\s\S]*?)(?=\n##|\n$|$)/);
+    if (flowMatch) {
+      flowSteps = (flowMatch[1].match(/^\d+\.\s+(.+)$/gm) || []).map((s) => s.replace(/^\d+\.\s+/, ""));
+    }
+    const uiMatch = project.aiSummary.match(/## (?:UI Elements Found|Key UI Elements)\n([\s\S]*?)(?=\n##|\n$|$)/);
+    if (uiMatch) {
+      uiElements = (uiMatch[1].match(/^-\s+(.+)$/gm) || []).map((s) => s.replace(/^-\s+/, ""));
+    }
+  }
+  const elementsPerFrame = Math.max(1, Math.ceil(uiElements.length / Math.max(frameFiles.length, 1)));
+  const hotspotColors = ["#818CF8", "#34D399", "#F59E0B", "#EC4899", "#06B6D4", "#8B5CF6"];
+  const hotspotPositions = [
+    { x: 50, y: 8 },
+    // top center (nav bar)
+    { x: 15, y: 30 },
+    // left middle
+    { x: 85, y: 30 },
+    // right middle
+    { x: 50, y: 50 },
+    // center
+    { x: 50, y: 85 },
+    // bottom center (tab bar)
+    { x: 15, y: 70 }
+    // bottom left
+  ];
+  const frames = frameFiles.map((filePath, i) => {
+    const rawStepName = annotations?.[i]?.label || flowSteps[i] || `Step ${i + 1}`;
+    const stepName = stripMarkdown(rawStepName);
+    const ocr = frameOcr[i]?.ocrText || "";
+    const rawDesc = flowSteps[i] || ocr.slice(0, 100) || `Screen ${i + 1}`;
+    const description = stripMarkdown(rawDesc);
+    const hotspots = [];
+    const startIdx = i * elementsPerFrame;
+    const frameElements = uiElements.slice(startIdx, startIdx + elementsPerFrame).slice(0, 4);
+    frameElements.forEach((el, j) => {
+      const cleanEl = stripMarkdown(el);
+      const pos = hotspotPositions[j % hotspotPositions.length];
+      hotspots.push({
+        id: String.fromCharCode(65 + j),
+        x_percent: pos.x,
+        y_percent: pos.y,
+        label: cleanEl.slice(0, 20),
+        title: cleanEl.slice(0, 40),
+        description: cleanEl,
+        color: hotspotColors[j % hotspotColors.length]
+      });
+    });
+    if (hotspots.length === 0 && ocr) {
+      const ocrWords = ocr.split(/\s+/).filter((w) => w.length > 3).slice(0, 3);
+      ocrWords.forEach((w, j) => {
+        const pos = hotspotPositions[j % hotspotPositions.length];
+        hotspots.push({
+          id: String.fromCharCode(65 + j),
+          x_percent: pos.x,
+          y_percent: pos.y,
+          label: w.slice(0, 15),
+          title: w,
+          description: `Text found: "${w}"`,
+          color: hotspotColors[j % hotspotColors.length]
+        });
+      });
+    }
+    return {
+      id: `frame-${i}`,
+      step_name: stepName,
+      description,
+      base64: imageToBase64(filePath),
+      baseline_status: "not_validated",
+      hotspots
+    };
+  });
+  return {
+    name: project.marketingTitle || project.name,
+    platform: project.platform || "unknown",
+    recorded_at: project.createdAt instanceof Date ? project.createdAt.toISOString() : typeof project.createdAt === "string" ? project.createdAt : (/* @__PURE__ */ new Date()).toISOString(),
+    frames
+  };
+}
+function generateInfographicHtmlString(data) {
+  const templatePath = findTemplate();
+  if (!templatePath) return null;
+  let html = readFileSync(templatePath, "utf-8");
+  html = html.replace("__TITLE__", data.name);
+  const dataJson = JSON.stringify(data);
+  html = html.replace(
+    "window.FLOW_DATA || { name: 'Flow', frames: [] }",
+    `window.FLOW_DATA || ${dataJson}`
+  );
+  return html;
+}
+function generateInfographicHtml(data, outputPath) {
+  try {
+    const templatePath = findTemplate();
+    if (!templatePath) {
+      return { success: false, error: "Infographic template not found" };
+    }
+    let html = readFileSync(templatePath, "utf-8");
+    html = html.replace("__TITLE__", data.name);
+    const dataJson = JSON.stringify(data);
+    html = html.replace(
+      "window.FLOW_DATA || { name: 'Flow', frames: [] }",
+      `window.FLOW_DATA || ${dataJson}`
+    );
+    const outDir = dirname(outputPath);
+    if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+    writeFileSync(outputPath, html, "utf-8");
+    const stat = statSync(outputPath);
+    return {
+      success: true,
+      outputPath,
+      size: stat.size,
+      frameCount: data.frames.length
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+export {
+  buildInfographicData,
+  collectFrameImages,
+  generateInfographicHtml,
+  generateInfographicHtmlString
+};

package/dist/{server-QFNKZCOJ.js → server-W3JQ5RG7.js}

@@ -3,7 +3,7 @@ import {
   getServerPort,
   startServer,
   stopServer
-} from "./chunk-2UUMLAVR.js";
+} from "./chunk-IVX2OSOJ.js";
 import "./chunk-34GGYFXX.js";
 import "./chunk-6GK5K6CS.js";
 import "./chunk-7R5YNOXE.js";

package/dist/{setup-6JJYKKBS.js → setup-F7MGEFIM.js}

@@ -2,10 +2,12 @@ import {
   setupCheckTool,
   setupInitTool,
   setupInstallTool,
+  setupReplayStatusTool,
   setupStatusTool,
   setupTools
-} from "./chunk-CUBQRT5L.js";
+} from "./chunk-HFN6BTVO.js";
 import "./chunk-XKX6NBHF.js";
+import "./chunk-GRU332L4.js";
 import "./chunk-6EGBXRDK.js";
 import "./chunk-YYOK2RF7.js";
 import "./chunk-R5U7XKVJ.js";
@@ -13,6 +15,7 @@ export {
   setupCheckTool,
   setupInitTool,
   setupInstallTool,
+  setupReplayStatusTool,
   setupStatusTool,
   setupTools
 };

package/dist/{tools-Q7OZO732.js → tools-VYFNRUS4.js}

@@ -107,16 +107,17 @@ import {
   uiStatusTool,
   uiTools,
   videoInfoTool
-} from "./chunk-HB3YPWF3.js";
+} from "./chunk-5AISGCS4.js";
+import "./chunk-34GGYFXX.js";
 import "./chunk-PMCXEA7J.js";
 import {
   setupCheckTool,
   setupInitTool,
+  setupReplayStatusTool,
   setupStatusTool,
   setupTools
-} from "./chunk-CUBQRT5L.js";
+} from "./chunk-HFN6BTVO.js";
 import "./chunk-XKX6NBHF.js";
-import "./chunk-34GGYFXX.js";
 import "./chunk-7R5YNOXE.js";
 import "./chunk-3ERJNXYM.js";
 import "./chunk-LB3RNE3O.js";
@@ -217,6 +218,7 @@ export {
   projectTools,
   setupCheckTool,
   setupInitTool,
+  setupReplayStatusTool,
   setupStatusTool,
   setupTools,
   startRecordingTool,

package/doc/esvp-protocol.md

@@ -0,0 +1,116 @@
+# ESVP Protocol Integration
+
+DiscoveryLab includes a built-in client for the open [ESVP protocol](https://esvp.dev) by Entropy Lab — enabling reproducible mobile sessions, automated replay, and network-aware validation.
+
+## Configuration
+
+| Mode | How |
+|------|-----|
+| **Remote** | Set `ESVP_BASE_URL=http://your-esvp-host:8787` |
+| **Local** | Leave `ESVP_BASE_URL` unset — DiscoveryLab boots an embedded local runtime |
+| **Dev (custom module)** | Set `DISCOVERYLAB_ESVP_LOCAL_MODULE=/path/to/esvp-server-reference/server.js` |
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `dlab.esvp.status` | Check control-plane health |
+| `dlab.esvp.devices` | List available devices |
+| `dlab.esvp.sessions.list` | List sessions |
+| `dlab.esvp.session.create` | Create session (ios-sim, maestro-ios, adb) |
+| `dlab.esvp.session.get` | Get session details |
+| `dlab.esvp.session.inspect` | Inspect session state |
+| `dlab.esvp.session.transcript` | Get session transcript |
+| `dlab.esvp.session.artifacts.list` | List artifacts |
+| `dlab.esvp.session.artifact.get` | Get specific artifact |
+| `dlab.esvp.session.actions` | Run actions on session |
+| `dlab.esvp.session.checkpoint` | Create checkpoint |
+| `dlab.esvp.session.finish` | Finish session |
+| `dlab.esvp.replay.run` | Replay recording |
+| `dlab.esvp.replay.validate` | Validate replay |
+| `dlab.esvp.session.network` | Get network data |
+| `dlab.esvp.network.configure` | Configure network proxy |
+| `dlab.esvp.network.trace.attach` | Attach network trace |
+| `dlab.project.esvp.current` | Get current project ESVP state |
+| `dlab.project.esvp.validate` | Validate project recording |
+| `dlab.project.esvp.replay` | Replay project recording |
+| `dlab.project.esvp.sync_network` | Sync network traces |
+| `dlab.project.esvp.app_trace_bootstrap` | Bootstrap app tracing |
+
+## CLI Commands
+
+```bash
+discoverylab esvp status
+discoverylab esvp devices
+discoverylab esvp sessions
+discoverylab esvp create
+discoverylab esvp get <sessionId>
+discoverylab esvp inspect <sessionId>
+discoverylab esvp transcript <sessionId>
+discoverylab esvp artifacts <sessionId>
+discoverylab esvp artifact <sessionId> <artifactPath>
+discoverylab esvp actions <sessionId>
+discoverylab esvp checkpoint <sessionId>
+discoverylab esvp finish <sessionId>
+discoverylab esvp replay-run <sessionId>
+discoverylab esvp replay-validate <sessionId>
+discoverylab esvp replay-consistency <sessionId>
+discoverylab esvp network <sessionId>
+discoverylab esvp network-configure <sessionId>
+discoverylab esvp network-clear <sessionId>
+discoverylab esvp trace-attach <sessionId>
+```
+
+## Network Proxy
+
+DiscoveryLab defaults to `external-proxy` mode — the proxy runs locally and ESVP only persists traces.
+
+### Host Rules
+
+| Setup | Proxy Address |
+|-------|--------------|
+| macOS + iOS Simulator | `127.0.0.1` |
+| macOS/Linux + Android Emulator | `10.0.2.2` |
+| Physical Android | Host LAN IP |
+
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `DISCOVERYLAB_NETWORK_PROXY_PORT` | Proxy port |
+| `DISCOVERYLAB_NETWORK_PROXY_HOST` | Proxy host for device |
+| `DISCOVERYLAB_NETWORK_PROXY_BIND_HOST` | Bind address (LAN) |
+| `DISCOVERYLAB_NETWORK_PROXY_PROTOCOL` | Protocol (http/https) |
+| `DISCOVERYLAB_NETWORK_PROXY_BYPASS` | Bypass patterns |
+| `DISCOVERYLAB_NETWORK_PROXY_MAX_DURATION_MS` | Auto-finalize timeout (default: 15min) |
+
+### Safety
+
+- Proxies auto-finalize after 15 minutes to prevent stale proxy state
+- Settings UI has an emergency lock and "Disable Active Proxy Now" button
+- Server shutdown auto-cleans active proxies
+
+## Example Prompts
+
+```
+Check my ESVP control-plane health
+Create an ios-sim ESVP session and take a screenshot
+Replay this iOS recording with an external proxy
+Configure a proxy on this session and attach the HTTP trace
+```
+
+## Programmatic Usage
+
+```ts
+import { createESVPSession, runESVPActions } from '@veolab/discoverylab';
+
+const created = await createESVPSession({
+  executor: 'ios-sim',
+  meta: { source: 'demo' },
+});
+
+await runESVPActions(created.session.id, {
+  actions: [{ name: 'screenshot' }],
+  finish: true,
+});
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veolab/discoverylab",
-  "version": "1.4.4",
+  "version": "1.6.3",
   "description": "AI-powered app testing & evidence generator - Claude Code Plugin",
   "type": "module",
   "main": "dist/index.js",
@@ -10,7 +10,7 @@
   },
   "scripts": {
     "dev": "tsx watch src/cli.ts serve",
-    "build": "tsup src/index.ts src/cli.ts --format esm --dts --clean && cp src/web/index.html dist/index.html && mkdir -p dist/visualizations && cp src/core/visualizations/templates/*.html dist/visualizations/ && node scripts/build-host-runtime.mjs --best-effort",
+    "build": "tsup src/index.ts src/cli.ts --format esm --dts --clean && cp src/web/index.html dist/index.html && mkdir -p dist/visualizations dist/export && cp src/core/visualizations/templates/*.html dist/visualizations/ && cp src/core/export/infographic-template.html dist/export/ && node scripts/build-host-runtime.mjs --best-effort",
     "build:host-runtime": "node scripts/build-host-runtime.mjs",
     "pack:local": "npm run build && npm run build:host-runtime && node scripts/verify-host-runtime-bundle.mjs && npm pack",
     "prepack": "npm run build && npm run build:host-runtime && node scripts/verify-host-runtime-bundle.mjs",
@@ -68,7 +68,7 @@
   "claude-plugin": {
     "name": "DiscoveryLab",
     "description": "AI-powered app testing & evidence generator",
-    "version": "1.4.4",
+    "version": "1.6.3",
     "tools": [
       "dlab.capture.screen",
       "dlab.capture.emulator",

package/skills/knowledge-brain/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: knowledge-brain
-description: Search app knowledge from captured flows - UI, screens, behaviors
+description: Search and visualize app knowledge from captured flows
 context: fork
 agent: general-purpose
 always: true
@@ -11,71 +11,72 @@ tags:
   - app-flow
   - ui
   - screens
+  - brain
 ---
 
 # DiscoveryLab Knowledge Brain
 
-DiscoveryLab captures app recordings and analyzes them with OCR + AI, building a knowledge base of every flow, screen, and UI element. This skill lets you query that knowledge.
+DiscoveryLab captures app recordings and analyzes them with AI, building a knowledge base of every flow, screen, and UI element. This skill lets you query and visualize that knowledge.
 
-## When to Use
+## Default behavior: Visual first
 
-Use this whenever the user asks about:
-- How a specific screen or flow works in their app
-- What UI elements exist on a page (buttons, inputs, labels)
-- The user journey through a feature (onboarding, checkout, settings)
-- Comparing different captures of the same flow
-- Any reference to app screens, recordings, or captured content
-- Context about what was tested or recorded
-
-Also use proactively when:
-- The user is working on code related to a feature that was captured
-- You need visual context about the app to give better answers
-- The user mentions a Jira ticket that might be linked to a project
+When the user asks about an app flow, **show it visually by default** using `dlab.knowledge.open`. The returned HTML renders as an interactive canvas with animated frame player, annotations, and navigation. Only fall back to text if the user explicitly asks for text or if no frames are available.
 
 ## Tools
 
-### `dlab.knowledge.search`
-Semantic search across all captured projects. Matches against: project names, AI analysis summaries, OCR text from every screen, tags, and linked tickets.
+### `dlab.knowledge.open` (primary - visual)
+Opens an interactive infographic of an app flow. Returns self-contained HTML.
 
 ```
-dlab.knowledge.search { query: "login" }
-dlab.knowledge.search { query: "paywall" }
-dlab.knowledge.search { query: "onboarding flow" }
+dlab.knowledge.open { query: "login" }
+dlab.knowledge.open { query: "onboarding flow" }
+dlab.knowledge.open { projectId: "abc123" }
+```
+
+Use when:
+- User asks "how does the login work?"
+- User asks "show me the onboarding"
+- User says "what does the settings screen look like?"
+- Any question about a captured flow where visual context helps
+
+### `dlab.knowledge.search` (text answers)
+Search across all projects. Returns text with overview, flow steps, UI elements.
+
+```
+dlab.knowledge.search { query: "checkout" }
 dlab.knowledge.search { query: "PROJ-123" }
-dlab.knowledge.search { query: "settings profile" }
 ```
 
-Returns per match:
-- App overview (what the screen/flow does)
-- User flow steps (numbered sequence)
-- UI elements found (buttons, inputs, navigation)
-- OCR text sample (actual text visible on screens)
-- Project ID for deeper lookup
+Use when:
+- User asks a specific factual question ("what buttons are on the paywall?")
+- User references a Jira ticket
+- You need quick context without opening a visual
 
-### `dlab.knowledge.summary`
-High-level overview of the entire knowledge base - all projects grouped by app with stats.
+### `dlab.knowledge.summary` (overview)
+Lists all captured knowledge grouped by app.
 
 ```
 dlab.knowledge.summary {}
 ```
 
-Use this when:
-- The user asks "what do we have captured?"
-- You need to orient yourself on what apps/flows exist
-- Starting a new conversation and need context
+Use when:
+- User asks "what do we have captured?"
+- Starting a new conversation
+- Need to orient on available projects
 
-### `dlab.project.get`
-Full details on a specific project found via search. Use when the search result summary is not enough.
+### `dlab.project.import` (sharing)
+Import a shared .applab project file.
 
 ```
-dlab.project.get { projectId: "<id from search results>" }
+dlab.project.import { filePath: "/path/to/project.applab" }
 ```
 
-## How to Respond
+Use when someone shares a .applab file.
+
+## How to respond
 
-1. **Search first** - never say "I don't have information about that" without searching
-2. **No match?** - run `dlab.knowledge.summary` to show the user what's available
-3. **Multiple results** - present the most recent first, note if there are different versions
-4. **Cite the source** - mention which project/recording the information comes from
-5. **Suggest captures** - if the user asks about a flow that doesn't exist, suggest they capture it with DiscoveryLab
-6. **Be specific** - use the OCR text and UI elements from results to give precise answers, not generic ones
+1. **Visual first** - use `dlab.knowledge.open` by default for flow questions
+2. **Search first** - never say "I don't know" without searching
+3. **No match?** - run `dlab.knowledge.summary` to show what's available
+4. **Cite the source** - mention which project the information comes from
+5. **Suggest captures** - if a flow doesn't exist, suggest capturing it