quickcast-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuickCast Team / Watermark & Resize Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,85 @@
+# QuickCast MCP (Screen-to-Action Protocol)
+
+> **Autonomous AI Protocol for Screen Recordings**  
+> Turn screen recordings directly into structured GitHub bug reports with video timestamps, executable Playwright E2E tests, and Standard Operating Procedure (SOP) documentation.
+
+Part of the **QuickCast Screen-Recorder** & **Watermark & Resize Studio** ecosystem.
+
+---
+
+## ⚡ Features
+
+* **🎥 `get_latest_session`**: Instantly fetches recording metadata, duration, Cloudflare R2 watch URL, and user interaction markers from the latest session.
+* **📋 `list_recent_sessions`**: Inspects recent screen recordings with durations, timestamps, and shareable preview links.
+* **🐛 `format_github_bug_report`**: Formats an engineering-ready GitHub or Jira issue containing timestamped reproduction links (e.g. `[00:15](watchUrl#t=15)`), environment tables (URL, OS, resolution, browser), and failure descriptions.
+* **🎭 `scaffold_playwright_test`**: Automatically outputs an executable Playwright reproduction test (in TypeScript or JavaScript) mirroring the exact interaction flow.
+* **📖 `generate_sop_guide`**: Synthesizes a clean Markdown Standard Operating Procedure (SOP) for team training and workflow documentation.
+* **📥 `ingest_session`**: Allows AI agents or scripts to register and store new recording telemetry into the local profile database (`~/.quickcast/sessions.json`).
+
+---
+
+## 📦 Installation & Setup
+
+### 1. Claude Desktop Configuration
+
+Add the following to your `claude_desktop_config.json`:
+
+* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "quickcast": {
+      "command": "node",
+      "args": [
+        "C:\\Users\\Milmann\\.gemini\\antigravity\\scratch\\quickcast-mcp\\src\\index.js"
+      ]
+    }
+  }
+}
+```
+
+### 2. Cursor Configuration
+
+Add to your project's `.cursor/mcp.json` or global Cursor MCP Settings:
+
+```json
+{
+  "mcpServers": {
+    "quickcast": {
+      "command": "node",
+      "args": [
+        "C:\\Users\\Milmann\\.gemini\\antigravity\\scratch\\quickcast-mcp\\src\\index.js"
+      ]
+    }
+  }
+}
+```
+
+---
+
+## 🛠️ MCP Tools Reference
+
+| Tool | Description | Inputs |
+| :--- | :--- | :--- |
+| `get_latest_session` | Get latest recording details & R2 watch URL | `session_id`, `watch_url`, `session_file` |
+| `list_recent_sessions` | List last 10 recordings with durations & links | `limit`, `session_file` |
+| `format_github_bug_report` | Generate markdown bug report with video timestamps | `issue_title`, `expected_behavior`, `actual_behavior` |
+| `scaffold_playwright_test` | Generate executable Playwright E2E script | `language` (`typescript` / `javascript`), `test_name` |
+| `generate_sop_guide` | Generate SOP documentation | `workflow_name`, `title` |
+| `ingest_session` | Store session telemetry to local DB | `watchUrl`, `durationSeconds`, `markers`, `environment` |
+
+---
+
+## 🔒 Safety & Privacy
+
+* **100% Client-Side & Local**: Runs as a local `stdio` server on your machine.
+* **Zero Cloud Costs**: Uses your existing Cloudflare R2 links or local recording files. No external AI API keys or third-party cloud brokers required.
+* **Decoupled Architecture**: Strictly isolated from extension recording engines and web apps.
+
+---
+
+## 📄 License
+
+MIT © [Watermark & Resize Studio](https://watermarkresizestudio.com)

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "quickcast-mcp",
+  "version": "1.0.0",
+  "description": "High-performance Model Context Protocol (MCP) server for QuickCast Screen-to-Action Protocol: automated bug reporting, Playwright E2E test scaffolding, and SOP generation from QuickCast recordings.",
+  "main": "src/index.js",
+  "bin": {
+    "quickcast-mcp": "src/index.js"
+  },
+  "type": "module",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node test/test_mcp.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "quickcast",
+    "screen-recorder",
+    "screen-to-action",
+    "playwright",
+    "e2e-testing",
+    "bug-reporting",
+    "sop-generator",
+    "claude-desktop",
+    "cursor"
+  ],
+  "author": "QuickCast Team (https://watermarkresizestudio.com)",
+  "license": "MIT",
+  "homepage": "https://watermarkresizestudio.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Miladmet/quickcast-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Miladmet/quickcast-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "zod": "^3.25.76"
+  }
+}

package/src/index.js

@@ -0,0 +1,332 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ErrorCode,
+  McpError
+} from '@modelcontextprotocol/sdk/types.js';
+
+import {
+  loadSessions,
+  saveSession,
+  getLatestSession,
+  formatGithubBugReport,
+  scaffoldPlaywrightTest,
+  generateSopGuide,
+  formatTime
+} from './sessionManager.js';
+
+const server = new Server(
+  {
+    name: 'quickcast-mcp',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// Define tool schemas and capabilities
+const TOOLS = [
+  {
+    name: 'get_latest_session',
+    description: 'Retrieve metadata, duration, markers, and Cloudflare R2 watch URL of the latest or specified QuickCast recording session.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: {
+          type: 'string',
+          description: 'Optional specific QuickCast session ID (e.g., "qc_rec_1740001234"). If omitted, retrieves latest recording.',
+        },
+        watch_url: {
+          type: 'string',
+          description: 'Optional Cloudflare R2 watch URL to search for.',
+        },
+        session_data: {
+          type: 'string',
+          description: 'Optional raw JSON string of a QuickCast session payload to parse directly.',
+        },
+        session_file: {
+          type: 'string',
+          description: 'Optional path to custom quickcast-sessions.json file.',
+        }
+      },
+    },
+  },
+  {
+    name: 'list_recent_sessions',
+    description: 'List recent QuickCast screen recording sessions with IDs, timestamps, durations, and shareable watch URLs.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: {
+          type: 'number',
+          description: 'Maximum number of sessions to return (default: 10).',
+          default: 10,
+        },
+        session_file: {
+          type: 'string',
+          description: 'Optional path to custom quickcast-sessions.json file.',
+        }
+      },
+    },
+  },
+  {
+    name: 'format_github_bug_report',
+    description: 'Format an automated, high-fidelity GitHub/Jira bug reproduction issue markdown document with timestamped video links, environment tables, and failure points from a QuickCast session.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: {
+          type: 'string',
+          description: 'Optional session ID. If omitted, uses latest recording.',
+        },
+        watch_url: {
+          type: 'string',
+          description: 'Optional QuickCast video watch URL.',
+        },
+        issue_title: {
+          type: 'string',
+          description: 'Custom issue title (e.g. "[Bug]: Checkout button unresponsive on Safari").',
+        },
+        expected_behavior: {
+          type: 'string',
+          description: 'What the user expected to happen.',
+        },
+        actual_behavior: {
+          type: 'string',
+          description: 'What actually occurred in the recording.',
+        },
+        notes: {
+          type: 'string',
+          description: 'Additional developer notes or context.',
+        },
+        session_data: {
+          type: 'string',
+          description: 'Optional raw session JSON string.',
+        }
+      },
+    },
+  },
+  {
+    name: 'scaffold_playwright_test',
+    description: 'Generate an executable Playwright (TypeScript or JavaScript) E2E reproduction test based on the interactions, clicks, and URLs captured during the QuickCast recording.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: {
+          type: 'string',
+          description: 'Optional session ID. If omitted, uses latest recording.',
+        },
+        language: {
+          type: 'string',
+          enum: ['typescript', 'javascript'],
+          description: 'Language to output ("typescript" or "javascript"). Default is "typescript".',
+          default: 'typescript',
+        },
+        test_name: {
+          type: 'string',
+          description: 'Name for the Playwright test block.',
+        },
+        target_url: {
+          type: 'string',
+          description: 'Target starting URL (overrides recorded page URL if provided).',
+        },
+        session_data: {
+          type: 'string',
+          description: 'Optional raw session JSON string.',
+        }
+      },
+    },
+  },
+  {
+    name: 'generate_sop_guide',
+    description: 'Generate a clean, structured Standard Operating Procedure (SOP) or training walkthrough document with timestamped video checkpoints from a QuickCast session.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session_id: {
+          type: 'string',
+          description: 'Optional session ID. If omitted, uses latest recording.',
+        },
+        workflow_name: {
+          type: 'string',
+          description: 'Name of the workflow (e.g. "Customer Refund Process in Admin Panel").',
+        },
+        title: {
+          type: 'string',
+          description: 'Optional custom document title.',
+        },
+        session_data: {
+          type: 'string',
+          description: 'Optional raw session JSON string.',
+        }
+      },
+    },
+  },
+  {
+    name: 'ingest_session',
+    description: 'Ingest and store a QuickCast recording session into the local session storage (~/.quickcast/sessions.json) so AI assistants can reference it.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sessionId: {
+          type: 'string',
+          description: 'Unique session identifier (e.g. "qc_rec_1740001234").',
+        },
+        watchUrl: {
+          type: 'string',
+          description: 'Cloudflare R2 watch URL for the recording.',
+        },
+        durationSeconds: {
+          type: 'number',
+          description: 'Total length in seconds.',
+        },
+        filename: {
+          type: 'string',
+          description: 'Original recording filename.',
+        },
+        markers: {
+          type: 'array',
+          description: 'Array of interaction markers with timeSec, label, selector, etc.',
+          items: {
+            type: 'object',
+          },
+        },
+        environment: {
+          type: 'object',
+          description: 'Environment metadata (url, browser, resolution, os).',
+        },
+      },
+      required: ['watchUrl'],
+    },
+  },
+];
+
+// Handle listing tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools: TOOLS };
+});
+
+// Handle calling tools
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params;
+
+  try {
+    switch (name) {
+      case 'get_latest_session': {
+        const session = getLatestSession(args);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(session, null, 2),
+            },
+          ],
+        };
+      }
+
+      case 'list_recent_sessions': {
+        const limit = args.limit || 10;
+        const all = loadSessions(args.session_file);
+        const sliced = all.slice(0, limit).map((s) => ({
+          sessionId: s.sessionId || s.id,
+          createdAt: s.createdAt,
+          duration: `${formatTime(s.durationSeconds || 0)} (${s.durationSeconds || 0}s)`,
+          watchUrl: s.watchUrl || s.videoUrl,
+          filename: s.filename,
+          markerCount: Array.isArray(s.markers) ? s.markers.length : 0,
+        }));
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(sliced, null, 2),
+            },
+          ],
+        };
+      }
+
+      case 'format_github_bug_report': {
+        const session = getLatestSession(args);
+        const report = formatGithubBugReport(session, args);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: report,
+            },
+          ],
+        };
+      }
+
+      case 'scaffold_playwright_test': {
+        const session = getLatestSession(args);
+        const code = scaffoldPlaywrightTest(session, args);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: code,
+            },
+          ],
+        };
+      }
+
+      case 'generate_sop_guide': {
+        const session = getLatestSession(args);
+        const guide = generateSopGuide(session, args);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: guide,
+            },
+          ],
+        };
+      }
+
+      case 'ingest_session': {
+        const saved = saveSession(args);
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Successfully ingested session ${saved.sessionId}. Stored in local QuickCast session database.`,
+            },
+          ],
+        };
+      }
+
+      default:
+        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Error executing ${name}: ${error instanceof Error ? error.message : String(error)}`,
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// Start the server over stdio
+async function run() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('[quickcast-mcp] QuickCast Screen-to-Action Protocol MCP server running on stdio');
+}
+
+run().catch((error) => {
+  console.error('[quickcast-mcp] Fatal error:', error);
+  process.exit(1);
+});

package/src/sessionManager.js

@@ -0,0 +1,346 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+/**
+ * Standard session directory in the user's home directory.
+ */
+export const DEFAULT_QUICKCAST_DIR = path.join(os.homedir(), '.quickcast');
+export const DEFAULT_SESSIONS_FILE = path.join(DEFAULT_QUICKCAST_DIR, 'sessions.json');
+
+/**
+ * Helper to format seconds into mm:ss.
+ */
+export function formatTime(seconds = 0) {
+  const s = Math.max(0, Math.floor(seconds));
+  const mins = Math.floor(s / 60);
+  const secs = s % 60;
+  return `${mins.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`;
+}
+
+/**
+ * Searches candidate locations to locate QuickCast sessions.
+ */
+export function resolveSessionFile(customPath) {
+  if (customPath && fs.existsSync(customPath)) {
+    return customPath;
+  }
+
+  if (process.env.QUICKCAST_SESSION_FILE && fs.existsSync(process.env.QUICKCAST_SESSION_FILE)) {
+    return process.env.QUICKCAST_SESSION_FILE;
+  }
+
+  if (fs.existsSync(DEFAULT_SESSIONS_FILE)) {
+    return DEFAULT_SESSIONS_FILE;
+  }
+
+  // Check current working directory
+  const cwdFile = path.resolve(process.cwd(), 'quickcast-sessions.json');
+  if (fs.existsSync(cwdFile)) {
+    return cwdFile;
+  }
+
+  return DEFAULT_SESSIONS_FILE;
+}
+
+/**
+ * Load all stored sessions.
+ */
+export function loadSessions(customPath) {
+  const filePath = resolveSessionFile(customPath);
+  if (!fs.existsSync(filePath)) {
+    return [];
+  }
+
+  try {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed)) return parsed;
+    if (parsed && Array.isArray(parsed.sessions)) return parsed.sessions;
+    if (parsed && Array.isArray(parsed.recentRecordings)) return parsed.recentRecordings;
+    return [];
+  } catch (err) {
+    console.error(`[QuickCast MCP] Failed to read session file (${filePath}):`, err.message);
+    return [];
+  }
+}
+
+/**
+ * Persists a new or updated session to the sessions store.
+ */
+export function saveSession(sessionData, customPath) {
+  const targetFile = customPath || DEFAULT_SESSIONS_FILE;
+  const dir = path.dirname(targetFile);
+
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const existing = loadSessions(targetFile);
+  const sessionId = sessionData.sessionId || sessionData.id || `qc_rec_${Date.now()}`;
+
+  const entry = {
+    ...sessionData,
+    sessionId,
+    id: sessionId,
+    updatedAt: new Date().toISOString(),
+    createdAt: sessionData.createdAt || new Date().toISOString(),
+  };
+
+  const filtered = existing.filter((s) => (s.sessionId || s.id) !== sessionId);
+  filtered.unshift(entry);
+
+  // Keep up to 50 recent sessions
+  const trimmed = filtered.slice(0, 50);
+
+  fs.writeFileSync(targetFile, JSON.stringify(trimmed, null, 2), 'utf-8');
+  return entry;
+}
+
+/**
+ * Retrieves the latest recorded session or matching session by ID/URL.
+ */
+export function getLatestSession(params = {}) {
+  const sessions = loadSessions(params.session_file);
+
+  if (params.session_data) {
+    try {
+      const parsed = typeof params.session_data === 'string'
+        ? JSON.parse(params.session_data)
+        : params.session_data;
+      return parsed;
+    } catch (_) {}
+  }
+
+  if (params.session_id) {
+    const found = sessions.find((s) => (s.sessionId || s.id) === params.session_id);
+    if (found) return found;
+  }
+
+  if (params.watch_url) {
+    const found = sessions.find((s) => s.watchUrl === params.watch_url || s.videoUrl === params.watch_url);
+    if (found) return found;
+  }
+
+  if (sessions.length > 0) {
+    return sessions[0];
+  }
+
+  // Graceful fallback template when no recordings are registered yet
+  return {
+    isTemplate: true,
+    sessionId: "qc_sample_session",
+    watchUrl: "https://quickcast-r2-uploader.admettre.workers.dev/watch?v=sample-preview",
+    videoUrl: "",
+    durationSeconds: 45,
+    createdAt: new Date().toISOString(),
+    environment: {
+      url: "https://example.com/checkout",
+      browser: "Chrome 130",
+      resolution: "1920x1080",
+      os: process.platform
+    },
+    markers: [
+      { timeSec: 5, label: "Navigated to target page", selector: "body" },
+      { timeSec: 18, label: "Clicked 'Proceed to Checkout' button", selector: "#checkout-btn" },
+      { timeSec: 32, label: "Entered discount code 'SAVE20'", selector: "input#promo-code" },
+      { timeSec: 42, label: "Observed 500 API error in modal", error: "Internal Server Error: 500" }
+    ],
+    message: "No live recordings found in store yet. Displaying sample structure. Use ingest_session or record a video in QuickCast extension to populate."
+  };
+}
+
+/**
+ * Formats a GitHub / Jira reproduction issue from a session recording.
+ */
+export function formatGithubBugReport(session, options = {}) {
+  const title = options.issue_title || `[Bug]: Issue observed during QuickCast recording (${session.sessionId || session.id || 'Session'})`;
+  const watchLink = session.watchUrl || session.videoUrl || "Attached video";
+  const duration = formatTime(session.durationSeconds || 0);
+  const env = session.environment || {};
+  const markers = Array.isArray(session.markers) ? session.markers : [];
+
+  let md = `# ${title}\n\n`;
+
+  md += `## 🎥 Video Recording\n`;
+  if (session.watchUrl) {
+    md += `* **Watch Recording (${duration})**: [${session.watchUrl}](${session.watchUrl})\n`;
+  }
+  if (session.filename) {
+    md += `* **File**: \`${session.filename}\`\n`;
+  }
+  md += `* **Session ID**: \`${session.sessionId || session.id || 'N/A'}\`\n`;
+  md += `* **Recorded At**: ${session.createdAt || new Date().toISOString()}\n\n`;
+
+  md += `## 💻 Environment\n`;
+  md += `| Property | Value |\n`;
+  md += `| :--- | :--- |\n`;
+  md += `| **Target URL** | \`${env.url || env.tabUrl || 'Not specified'}\` |\n`;
+  md += `| **Browser / User Agent** | \`${env.browser || env.userAgent || 'Chrome'}\` |\n`;
+  md += `| **Screen Resolution** | \`${env.resolution || '1920x1080'}\` |\n`;
+  md += `| **OS** | \`${env.os || process.platform}\` |\n\n`;
+
+  md += `## 📋 Steps to Reproduce\n`;
+  if (markers.length > 0) {
+    markers.forEach((m, idx) => {
+      const timestamp = formatTime(m.timeSec || 0);
+      const videoAnchor = session.watchUrl ? `[${timestamp}](${session.watchUrl}#t=${Math.floor(m.timeSec || 0)})` : `\`${timestamp}\``;
+      const selectorText = m.selector ? ` (selector: \`${m.selector}\`)` : '';
+      md += `${idx + 1}. **${videoAnchor}**: ${m.label || m.action || 'User interaction'}${selectorText}\n`;
+      if (m.error) {
+        md += `   > ⚠️ **Error Triggered**: \`${m.error}\`\n`;
+      }
+    });
+  } else {
+    md += `1. Navigate to \`${env.url || 'the application'}\`.\n`;
+    md += `2. Follow interaction flow shown in recording at [${watchLink}](${watchLink}).\n`;
+    md += `3. Observe unintended behavior at end of recording.\n`;
+  }
+  md += `\n`;
+
+  md += `## ❌ Expected vs Actual Behavior\n`;
+  md += `* **Expected**: ${options.expected_behavior || 'Flow should complete smoothly without errors.'}\n`;
+  md += `* **Actual**: ${options.actual_behavior || 'System encountered unexpected state / error shown in recording.'}\n\n`;
+
+  if (options.notes) {
+    md += `## 📝 Additional Notes\n${options.notes}\n\n`;
+  }
+
+  md += `*Generated automatically via [QuickCast Screen-to-Action Protocol](https://watermarkresizestudio.com).*`;
+
+  return md;
+}
+
+/**
+ * Scaffolds an executable Playwright test based on recorded session steps.
+ */
+export function scaffoldPlaywrightTest(session, options = {}) {
+  const language = (options.language || 'typescript').toLowerCase();
+  const testName = options.test_name || `reproduce issue from ${session.sessionId || 'QuickCast recording'}`;
+  const env = session.environment || {};
+  const targetUrl = options.target_url || env.url || env.tabUrl || 'https://example.com';
+  const markers = Array.isArray(session.markers) ? session.markers : [];
+  const watchUrl = session.watchUrl || session.videoUrl || '';
+
+  const isTs = language === 'typescript' || language === 'ts';
+
+  let code = '';
+
+  if (isTs) {
+    code += `import { test, expect, type Page } from '@playwright/test';\n\n`;
+    code += `/**\n`;
+    code += ` * Automated Reproduction Test generated by QuickCast Screen-to-Action Protocol.\n`;
+    if (watchUrl) code += ` * Video Recording: ${watchUrl}\n`;
+    code += ` * Session ID: ${session.sessionId || session.id || 'N/A'}\n`;
+    code += ` */\n`;
+    code += `test.describe('QuickCast Automated Reproduction', () => {\n`;
+    code += `  test('${testName}', async ({ page }: { page: Page }) => {\n`;
+  } else {
+    code += `const { test, expect } = require('@playwright/test');\n\n`;
+    code += `/**\n`;
+    code += ` * Automated Reproduction Test generated by QuickCast Screen-to-Action Protocol.\n`;
+    if (watchUrl) code += ` * Video Recording: ${watchUrl}\n`;
+    code += ` * Session ID: ${session.sessionId || session.id || 'N/A'}\n`;
+    code += ` */\n`;
+    code += `test.describe('QuickCast Automated Reproduction', () => {\n`;
+    code += `  test('${testName}', async ({ page }) => {\n`;
+  }
+
+  code += `    // 1. Initial Navigation\n`;
+  code += `    await page.goto('${targetUrl}');\n`;
+  code += `    await page.waitForLoadState('networkidle');\n\n`;
+
+  if (markers.length > 0) {
+    markers.forEach((m, idx) => {
+      const timeStr = formatTime(m.timeSec || 0);
+      code += `    // Step ${idx + 1} [${timeStr}]: ${m.label || 'Action'}\n`;
+      const sel = m.selector || (m.label && m.label.toLowerCase().includes('button') ? 'button' : null);
+
+      if (m.action === 'click' || (m.label && m.label.toLowerCase().includes('click'))) {
+        if (sel) {
+          code += `    await page.locator('${sel}').click();\n`;
+        } else {
+          code += `    // Click target: ${m.label}\n`;
+          code += `    await page.getByRole('button', { name: /${escapeRegex(m.label)}/i }).click();\n`;
+        }
+      } else if (m.action === 'fill' || (m.label && m.label.toLowerCase().includes('type'))) {
+        code += `    await page.locator('${sel || 'input'}').fill('${m.value || 'test input'}');\n`;
+      } else {
+        code += `    // ${m.label}\n`;
+        if (sel) {
+          code += `    await expect(page.locator('${sel}')).toBeVisible();\n`;
+        }
+      }
+
+      if (m.error) {
+        code += `    // Assert or check error occurrence: ${m.error}\n`;
+        code += `    // await expect(page.locator('.error-banner')).toContainText('${m.error}');\n`;
+      }
+      code += `\n`;
+    });
+  } else {
+    code += `    // TODO: Add recorded selector steps\n`;
+    code += `    await expect(page).toHaveURL(/${escapeRegex(targetUrl)}/);\n`;
+  }
+
+  code += `    // Final verification assertion\n`;
+  code += `    // await expect(page.locator('body')).toBeVisible();\n`;
+  code += `  });\n`;
+  code += `});\n`;
+
+  return code;
+}
+
+/**
+ * Generates a clean SOP (Standard Operating Procedure) markdown document.
+ */
+export function generateSopGuide(session, options = {}) {
+  const docTitle = options.title || `SOP: ${options.workflow_name || 'Standard Operating Procedure'}`;
+  const duration = formatTime(session.durationSeconds || 0);
+  const markers = Array.isArray(session.markers) ? session.markers : [];
+  const watchLink = session.watchUrl || session.videoUrl;
+
+  let md = `# ${docTitle}\n\n`;
+  md += `> **Standard Operating Procedure generated from QuickCast session.**\n\n`;
+
+  md += `## 📌 Overview\n`;
+  md += `* **Author/System**: QuickCast SOP Automation Engine\n`;
+  md += `* **Created**: ${new Date().toLocaleDateString()}\n`;
+  md += `* **Duration of Procedure**: ~${duration}\n`;
+  if (watchLink) {
+    md += `* **Interactive Walkthrough Video**: [Watch Demo (${duration})](${watchLink})\n`;
+  }
+  md += `\n`;
+
+  md += `## 🛠️ Prerequisites\n`;
+  md += `* Access to: \`${session.environment?.url || 'Target Application'}\`\n`;
+  md += `* Modern Web Browser (Chrome, Edge, Firefox, Safari)\n`;
+  md += `* Valid user credentials / permissions\n\n`;
+
+  md += `## 📝 Step-by-Step Instructions\n\n`;
+  if (markers.length > 0) {
+    markers.forEach((m, idx) => {
+      const timeStr = formatTime(m.timeSec || 0);
+      const timeLink = watchLink ? `[${timeStr}](${watchLink}#t=${Math.floor(m.timeSec || 0)})` : `\`${timeStr}\``;
+      md += `### Step ${idx + 1}: ${m.label || 'Action step'}\n`;
+      md += `* **Timestamp**: ${timeLink}\n`;
+      if (m.selector) md += `* **Interface Element**: \`${m.selector}\`\n`;
+      md += `* **Action Required**: Execute action as demonstrated in walkthrough.\n\n`;
+    });
+  } else {
+    md += `1. Review video at [${watchLink || 'attached recording'}](${watchLink || '#'})\n`;
+    md += `2. Replicate operational steps as demonstrated.\n\n`;
+  }
+
+  md += `## ✅ Verification & Quality Check\n`;
+  md += `1. Confirm that output matches expected operational result.\n`;
+  md += `2. Ensure no error dialogs or warnings are displayed.\n`;
+  md += `3. Archive execution record for compliance.\n\n`;
+
+  md += `---\n*Generated by QuickCast Screen-to-Action Protocol.*`;
+  return md;
+}
+
+function escapeRegex(string = '') {
+  return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&').slice(0, 30);
+}