npm - @bitovi/vybit - Versions diffs - 0.11.7 → 0.12.0 - Mend

@bitovi/vybit 0.11.7 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/README.md +3 -2
package/overlay/dist/overlay.js +5480 -2569
package/package.json +4 -1
package/panel/dist/assets/{DesignMode-Yfq3lye8.js → DesignMode-MoLVGcFD.js} +15 -15
package/panel/dist/assets/index-By_WWRF6.css +1 -0
package/panel/dist/assets/index-C4LjGBfX.js +63 -0
package/panel/dist/index.html +2 -2
package/server/mcp-tools.ts +114 -3
package/server/queue.ts +38 -0
package/server/storybook.ts +4 -1
package/server/websocket.ts +11 -1
package/shared/types.ts +251 -3
package/panel/dist/assets/index-0eiAXBf9.js +0 -62
package/panel/dist/assets/index-BWp0wXqx.css +0 -1

package/panel/dist/index.html CHANGED Viewed

@@ -16,8 +16,8 @@
       font-size: 12px;
     }
   </style>
-  <script type="module" crossorigin src="/panel/assets/index-0eiAXBf9.js"></script>
-  <link rel="stylesheet" crossorigin href="/panel/assets/index-BWp0wXqx.css">
+  <script type="module" crossorigin src="/panel/assets/index-C4LjGBfX.js"></script>
+  <link rel="stylesheet" crossorigin href="/panel/assets/index-By_WWRF6.css">
 </head>
 <body>
   <div id="root"></div>

package/server/mcp-tools.ts CHANGED Viewed

@@ -55,9 +55,11 @@ function buildJsx(componentName: string, args?: Record<string, unknown>): string
 function buildCommitInstructions(commit: Commit, remainingCount: number): string {
   const classChanges = commit.patches.filter(p => p.kind === 'class-change');
+  const textChanges = commit.patches.filter(p => p.kind === 'text-change');
   const messages = commit.patches.filter(p => p.kind === 'message');
   const designs = commit.patches.filter(p => p.kind === 'design');
   const componentDrops = commit.patches.filter(p => p.kind === 'component-drop');
+  const bugReports = commit.patches.filter(p => p.kind === 'bug-report');
   const moreText = remainingCount > 0
     ? `${remainingCount} more commit${remainingCount === 1 ? '' : 's'} waiting in the queue after this one.`
     : 'This is the last commit in the queue. After implementing it, call `implement_next_change` again to wait for future changes.';
@@ -149,6 +151,91 @@ ${parentComp ? `\n- **Parent component:** \`${parentComp}\` — edit this compon
 ${context ? `- **Context HTML:**\n\`\`\`html\n${context}\n\`\`\`\n` : ''}
 ⚠️ Do NOT paste rendered HTML. Import and render the React component with the props shown above.
+`;
+    } else if (patch.kind === 'text-change') {
+      const comp = patch.component?.name ?? 'unknown component';
+      const tag = patch.target?.tag ?? 'element';
+      const context = patch.context ?? '';
+      patchList += `### ${stepNum}. Text change \`${patch.id}\`
+- **Component:** \`${comp}\`
+- **Element:** \`<${tag}>\`
+- **Original HTML:**
+\`\`\`html
+${patch.originalHtml ?? ''}
+\`\`\`
+- **New HTML:**
+\`\`\`html
+${patch.newHtml ?? ''}
+\`\`\`
+${context ? `- **Context HTML:**\n\`\`\`html\n${context}\n\`\`\`\n` : ''}
+`;
+    } else if (patch.kind === 'bug-report') {
+      patchList += `### ${stepNum}. Bug report \`${patch.id}\`
+- **Description:** ${patch.bugDescription ?? '(no description)'}
+- **Time range:** ${patch.bugTimeRange ? `${patch.bugTimeRange.start} – ${patch.bugTimeRange.end}` : 'unknown'}
+${patch.bugElement ? `
+- **Related element:** \`${patch.bugElement.selectorPath}\`${patch.bugElement.componentName ? ` (in \`${patch.bugElement.componentName}\`)` : ''}
+- **Element HTML:**
+\`\`\`html
+${patch.bugElement.outerHTML.slice(0, 10000)}
+\`\`\`
+` : ''}
+${patch.bugTimeline && patch.bugTimeline.length > 0 ? (() => {
+  const triggerLabel = (t: import('../shared/types').BugTimelineEntry) => {
+    switch (t.trigger) {
+      case 'click': return `Click${t.elementInfo ? ` on \`<${t.elementInfo.tag}${t.elementInfo.classes ? ` class="${t.elementInfo.classes}"` : ''}>\`` : ''}`;
+      case 'mutation': return 'DOM mutation';
+      case 'error': return 'Error';
+      case 'navigation': return `Navigation${t.navigationInfo ? ` (${t.navigationInfo.method}: ${t.navigationInfo.from} → ${t.navigationInfo.to ?? 'unknown'})` : ''}`;
+      case 'page-load': return 'Page load';
+      default: return t.trigger;
+    }
+  };
+  let screenshotNum = 0;
+  let timeline = `**Timeline** (${patch.bugTimeline!.length} events):\n\n`;
+  for (let i = 0; i < patch.bugTimeline!.length; i++) {
+    const entry = patch.bugTimeline![i];
+    const time = entry.timestamp.replace(/.*T/, '').replace(/Z$/, '');
+    timeline += `#### ${i + 1}. [${time}] ${triggerLabel(entry)}\n`;
+    timeline += `**URL:** ${entry.url}\n`;
+    if (entry.hasScreenshot) {
+      screenshotNum++;
+      timeline += `📸 **Screenshot ${screenshotNum}** (see attached image ${screenshotNum} below)\n`;
+    }
+    if (entry.consoleLogs && entry.consoleLogs.length > 0) {
+      timeline += `\n**Console (${entry.consoleLogs.length}):**\n\`\`\`\n${entry.consoleLogs.map(l => `[${l.level.toUpperCase()}] ${l.args.join(' ')}${l.stack ? `\n${l.stack}` : ''}`).join('\n').slice(0, 3000)}\n\`\`\`\n`;
+    }
+    if (entry.networkErrors && entry.networkErrors.length > 0) {
+      timeline += `\n**Network errors (${entry.networkErrors.length}):**\n${entry.networkErrors.map(e => `- \`${e.status ?? 'ERR'} ${e.method} ${e.url}\`${e.errorMessage ? ` — ${e.errorMessage}` : ''}`).join('\n')}\n`;
+    }
+    if (entry.domChanges && entry.domChanges.length > 0) {
+      timeline += `\n**DOM changes (${entry.domChanges.length}):**\n`;
+      for (const c of entry.domChanges) {
+        const loc = `\`${c.selector}\`${c.componentName ? ` (in \`${c.componentName}\`)` : ''}`;
+        if (c.type === 'attribute') {
+          timeline += `- ${loc}: attribute \`${c.attributeName}\` changed: \`${c.oldValue ?? ''}\` → \`${c.newValue ?? ''}\`\n`;
+        } else if (c.type === 'text') {
+          timeline += `- ${loc}: text changed: "${c.oldText ?? ''}" → "${c.newText ?? ''}"\n`;
+        } else if (c.type === 'childList') {
+          const parts: string[] = [];
+          if (c.addedCount) parts.push(`${c.addedCount} added`);
+          if (c.removedCount) parts.push(`${c.removedCount} removed`);
+          timeline += `- ${loc}: children ${parts.join(', ')}`;
+          if (c.addedHTML) timeline += `\n  Added: \`${c.addedHTML.slice(0, 300)}\``;
+          if (c.removedHTML) timeline += `\n  Removed: \`${c.removedHTML.slice(0, 300)}\``;
+          timeline += `\n`;
+        }
+      }
+    } else if (entry.domDiff) {
+      timeline += `\n**DOM diff:**\n\`\`\`diff\n${entry.domDiff.slice(0, 10000)}\n\`\`\`\n`;
+    }
+    if (entry.domSnapshot && i === 0) {
+      timeline += `\n**Initial DOM state:**\n\`\`\`html\n${entry.domSnapshot.slice(0, 50000)}\n\`\`\`\n`;
+    }
+    timeline += `\n---\n\n`;
+  }
+  return timeline;
+})() : ''}
 `;
     }
     stepNum++;
@@ -157,22 +244,29 @@ ${context ? `- **Context HTML:**\n\`\`\`html\n${context}\n\`\`\`\n` : ''}
   // Build summary parts
   const summaryParts: string[] = [];
   if (classChanges.length) summaryParts.push(`${classChanges.length} class change${classChanges.length === 1 ? '' : 's'}`);
+  if (textChanges.length) summaryParts.push(`${textChanges.length} text change${textChanges.length === 1 ? '' : 's'}`);
   if (messages.length) summaryParts.push(`${messages.length} message${messages.length === 1 ? '' : 's'}`);
   if (designs.length) summaryParts.push(`${designs.length} design${designs.length === 1 ? '' : 's'}`);
   if (componentDrops.length) summaryParts.push(`${componentDrops.length} component drop${componentDrops.length === 1 ? '' : 's'}`);
+  if (bugReports.length) summaryParts.push(`${bugReports.length} bug report${bugReports.length === 1 ? '' : 's'}`);
   const resultsPart = classChanges.map(p => `     { "patchId": "${p.id}", "success": true }`).join(',\n');
+  const textResultsPart = textChanges.map(p => `     { "patchId": "${p.id}", "success": true }`).join(',\n');
   const designResultsPart = designs.map(p => `     { "patchId": "${p.id}", "success": true }`).join(',\n');
   const dropResultsPart = componentDrops.map(p => `     { "patchId": "${p.id}", "success": true }`).join(',\n');
-  const allResultsPart = [resultsPart, designResultsPart, dropResultsPart].filter(Boolean).join(',\n');
+  const bugResultsPart = bugReports.map(p => `     { "patchId": "${p.id}", "success": true }`).join(',\n');
+  const allResultsPart = [resultsPart, textResultsPart, designResultsPart, dropResultsPart, bugResultsPart].filter(Boolean).join(',\n');
   // Build step instructions
   const stepInstructions: string[] = [];
-  if (classChanges.length || componentDrops.length) {
+  if (classChanges.length || componentDrops.length || textChanges.length) {
     let step1 = '1. For each change above, find the source file and apply it.';
     if (componentDrops.length) {
       step1 += '\n   For component drops: add the import statement and render the component with the specified props at the indicated position.';
     }
+    if (textChanges.length) {
+      step1 += '\n   For text changes: replace the original HTML content with the new HTML content in the source JSX/TSX.';
+    }
     if (messages.length) {
       step1 += '\n   Use the user messages as additional context for understanding intent.';
     }
@@ -182,6 +276,10 @@ ${context ? `- **Context HTML:**\n\`\`\`html\n${context}\n\`\`\`\n` : ''}
     stepInstructions.push(`${stepInstructions.length + 1}. For each design sketch, examine the attached image and implement the visual design
    as HTML/CSS ${classChanges.length ? 'alongside the class changes' : 'in the specified component'}. Insert it ${designs[0].insertMode ?? 'after'} the target element.`);
   }
+  if (bugReports.length) {
+    stepInstructions.push(`${stepInstructions.length + 1}. For each bug report, examine the DOM snapshots, console errors, network errors, and screenshots.
+   Identify the root cause. Implement a fix.${bugReports.some(p => p.bugElement) ? ' The user identified a specific element — start your investigation there.' : ''}`);
+  }
   return `# IMPLEMENT THIS COMMIT — then call implement_next_change again
@@ -203,7 +301,7 @@ ${stepInstructions.length + 1}. Call \`mark_change_implemented\` with:
 ${allResultsPart}
    ]}
    \`\`\`
-   (Only report results for class-change, design, and component-drop patches — messages are informational.)
+   (Only report results for class-change, text-change, design, and component-drop patches — messages are informational.)
 ${stepInstructions.length + 2}. **IMMEDIATELY call \`implement_next_change\` again.** Do NOT summarize, do NOT ask the user, do NOT stop.
 ## CRITICAL — read this
@@ -384,6 +482,19 @@ export function registerMcpTools(mcp: McpServer, deps: McpToolDeps): void {
             });
           }
         }
+        // Add bug report screenshots
+        if (patch.kind === 'bug-report' && patch.bugScreenshots) {
+          for (const screenshot of patch.bugScreenshots.slice(0, 5)) {
+            const match = screenshot.match(/^data:([^;]+);base64,(.+)$/);
+            if (match) {
+              content.push({
+                type: "image" as const,
+                data: match[2],
+                mimeType: match[1],
+              });
+            }
+          }
+        }
       }
       content.push({

package/server/queue.ts CHANGED Viewed

@@ -23,6 +23,9 @@ function toSummary(p: Patch): PatchSummary {
     parentComponent: p.parentComponent,
     targetComponentName: p.targetComponentName,
     targetPatchId: p.targetPatchId,
+    originalHtml: p.originalHtml,
+    newHtml: p.newHtml,
+    bugDescription: p.bugDescription,
   };
 }
@@ -56,12 +59,35 @@ export function addPatch(patch: Patch): Patch {
     if (existingIdx !== -1) {
       draftPatches.splice(existingIdx, 1);
     }
+  } else if (patch.kind === 'text-change') {
+    // Dedup: if a staged text-change exists for the same elementKey, replace it
+    const existingIdx = draftPatches.findIndex(
+      p => p.kind === 'text-change' && p.elementKey === patch.elementKey && p.status === 'staged'
+    );
+    if (existingIdx !== -1) {
+      draftPatches.splice(existingIdx, 1);
+    }
   }
   // Message patches are always appended (no dedup)
   draftPatches.push(patch);
   return patch;
 }
+/** Immediately commit a single patch as its own commit (skips the draft). */
+export function addAndCommit(patch: Patch): Commit {
+  patch.status = 'committed';
+  const commit: Commit = {
+    id: crypto.randomUUID(),
+    patches: [patch],
+    status: 'committed',
+    timestamp: new Date().toISOString(),
+  };
+  patch.commitId = commit.id;
+  commits.push(commit);
+  emitter.emit('committed');
+  return commit;
+}
 export function commitDraft(ids: string[]): Commit {
   const idSet = new Set(ids);
   const commitPatches: Patch[] = [];
@@ -291,6 +317,18 @@ export function discardDraftPatch(id: string): boolean {
   return remaining.length < before;
 }
+/**
+ * Discard a committed (but not yet implementing) commit.
+ * Returns true if the commit was found and removed.
+ * Safe against race conditions: only removes if status is still 'committed'.
+ */
+export function discardCommit(commitId: string): boolean {
+  const idx = commits.findIndex(c => c.id === commitId && c.status === 'committed');
+  if (idx === -1) return false;
+  commits.splice(idx, 1);
+  return true;
+}
 export function clearAll(): { staged: number; committed: number; implementing: number; implemented: number } {
   const counts = getCounts();
   draftPatches.length = 0;

package/server/storybook.ts CHANGED Viewed

@@ -80,7 +80,10 @@ export async function loadStoryArgTypes(
  */
 export async function detectStorybookUrl(): Promise<string | null> {
   if (process.env.STORYBOOK_URL) {
-    return process.env.STORYBOOK_URL;
+    if (await probeStorybookUrl(process.env.STORYBOOK_URL)) {
+      return process.env.STORYBOOK_URL;
+    }
+    // Env var URL is not reachable — fall through to port scan
   }
   for (const port of SCAN_PORTS) {

package/server/websocket.ts CHANGED Viewed

@@ -3,7 +3,7 @@
 import { WebSocketServer, type WebSocket } from "ws";
 import type { Server } from "http";
-import { addPatch, commitDraft, getQueueUpdate, discardDraftPatch } from "./queue.js";
+import { addPatch, addAndCommit, commitDraft, getQueueUpdate, discardDraftPatch, discardCommit } from "./queue.js";
 import type { Patch } from "../shared/types.js";
 export interface WebSocketDeps {
@@ -88,6 +88,12 @@ export function setupWebSocket(httpServer: Server): WebSocketDeps {
           }
           console.error(`[ws] Discarded ${ids.length} draft patch(es)`);
           broadcastPatchUpdate();
+        } else if (msg.type === "DISCARD_COMMIT") {
+          const commitId: string = msg.commitId;
+          if (commitId && discardCommit(commitId)) {
+            console.error(`[ws] Discarded committed commit: ${commitId}`);
+            broadcastPatchUpdate();
+          }
         } else if (msg.type === "PING") {
           ws.send(JSON.stringify({ type: "PONG" }));
         } else if (msg.type === "DESIGN_SUBMIT") {
@@ -126,6 +132,10 @@ export function setupWebSocket(httpServer: Server): WebSocketDeps {
           const patch = addPatch({ ...msg.patch, kind: msg.patch.kind ?? 'component-drop' });
           console.error(`[ws] Component-drop patch staged: #${patch.id}`);
           broadcastPatchUpdate();
+        } else if (msg.type === "BUG_REPORT_STAGE") {
+          const commit = addAndCommit({ ...msg.patch, kind: 'bug-report' });
+          console.error(`[ws] Bug-report auto-committed: commit #${commit.id}`);
+          broadcastPatchUpdate();
         }
       } catch (err) {
         console.error("[ws] Bad message:", err);

package/shared/types.ts CHANGED Viewed

@@ -28,7 +28,7 @@ export interface CanvasComponent {
   height: number;
 }
-export type PatchKind = 'class-change' | 'message' | 'design' | 'component-drop';
+export type PatchKind = 'class-change' | 'message' | 'design' | 'component-drop' | 'text-change' | 'bug-report';
 export type PatchStatus = 'staged' | 'committed' | 'implementing' | 'implemented' | 'error';
@@ -60,10 +60,19 @@ export interface Patch {
   ghostHtml?: string;        // HTML of the dropped component (overlay preview only — stripped from MCP response)
   componentStoryId?: string; // Storybook story ID
   componentPath?: string;    // Source file of the component, e.g. './src/components/Button.tsx'
+  // Text-change fields (used when kind === 'text-change'):
+  originalHtml?: string;     // HTML before text edit
+  newHtml?: string;          // HTML after text edit
   componentArgs?: Record<string, unknown>; // Props the user configured before dropping
   parentComponent?: { name: string }; // React component that contains the drop target
   targetPatchId?: string;    // If target is a ghost from an earlier drop, references that patch
   targetComponentName?: string; // Name of the ghost component being referenced
+  // Bug-report fields (used when kind === 'bug-report'):
+  bugDescription?: string;
+  bugScreenshots?: string[];
+  bugTimeline?: BugTimelineEntry[];
+  bugTimeRange?: { start: string; end: string };
+  bugElement?: BugReportElement | null;
   // Commit reference:
   commitId?: string;         // Set when committed into a Commit
 }
@@ -97,6 +106,11 @@ export interface PatchSummary {
   parentComponent?: { name: string };
   targetComponentName?: string;
   targetPatchId?: string;
+  // Text-change display fields:
+  originalHtml?: string;
+  newHtml?: string;
+  // Bug-report display fields:
+  bugDescription?: string;
 }
 export interface CommitSummary {
@@ -343,6 +357,7 @@ export interface ComponentArmMessage {
   ghostHtml: string;
   componentPath?: string;  // Source file path from Storybook index, e.g. './src/components/Button.tsx'
   args?: Record<string, unknown>; // Current prop values from ArgsForm
+  insertMode?: 'replace';  // When 'replace', arms element-select if no element is selected
 }
 /** Panel → Overlay: user cancelled the armed state (panel click or escape) */
@@ -357,6 +372,41 @@ export interface ComponentDisarmedMessage {
   to: 'panel';
 }
+// ---------------------------------------------------------------------------
+// Mode sync messages
+// ---------------------------------------------------------------------------
+export type AppMode = 'select' | 'insert' | 'bug-report' | null;
+export type SelectTab = 'design' | 'replace';
+export type InsertTab = 'place';
+export type PanelTab = SelectTab | InsertTab;
+/** Bidirectional: panel ↔ overlay mode change */
+export interface ModeChangedMessage {
+  type: 'MODE_CHANGED';
+  to: 'overlay' | 'panel';
+  mode: AppMode;
+}
+/** Bidirectional: panel ↔ overlay tab change */
+export interface TabChangedMessage {
+  type: 'TAB_CHANGED';
+  to: 'overlay' | 'panel';
+  tab: PanelTab;
+}
+/** Overlay → Panel: text editing started on an element */
+export interface TextEditActiveMessage {
+  type: 'TEXT_EDIT_ACTIVE';
+  to: 'panel';
+}
+/** Overlay → Panel: text editing ended */
+export interface TextEditDoneMessage {
+  type: 'TEXT_EDIT_DONE';
+  to: 'panel';
+}
 /** Overlay → Server: component was placed, stage a patch */
 export interface ComponentDroppedMessage {
   type: 'COMPONENT_DROPPED';
@@ -379,7 +429,9 @@ export type PanelToOverlay =
   | CaptureScreenshotMessage
   | ClosePanelMessage
   | ComponentArmMessage
-  | ComponentDisarmMessage;
+  | ComponentDisarmMessage
+  | ModeChangedMessage
+  | TabChangedMessage;
 export type OverlayToServer = PatchStagedMessage | ComponentDroppedMessage | ResetSelectionMessage;
 export type PanelToServer = PatchCommitMessage | MessageStageMessage;
 export type ClientToServer =
@@ -427,5 +479,201 @@ export type AnyMessage =
   | ComponentDisarmedMessage
   | ComponentDroppedMessage
   | ResetSelectionMessage
+  | ModeChangedMessage
+  | TabChangedMessage
+  | TextEditActiveMessage
+  | TextEditDoneMessage
   | PingMessage
-  | PongMessage;
+  | PongMessage
+  | RecordingGetHistoryMessage
+  | RecordingHistoryMessage
+  | RecordingGetSnapshotMessage
+  | RecordingSnapshotMessage
+  | RecordingGetRangeMessage
+  | RecordingRangeMessage
+  | RecordingSnapshotMetaMessage
+  | BugReportPickElementMessage
+  | BugReportElementPickedMessage
+  | BugReportPickCancelledMessage
+  | BugReportStageMessage;
+// ---------------------------------------------------------------------------
+// Recording / Bug Report types
+// ---------------------------------------------------------------------------
+export interface ConsoleEntry {
+  level: 'log' | 'warn' | 'error' | 'info';
+  args: string[];
+  timestamp: string;
+  stack?: string;
+}
+export interface NetworkError {
+  url: string;
+  method: string;
+  status?: number;
+  statusText?: string;
+  errorMessage?: string;
+  timestamp: string;
+}
+export interface BugReportElement {
+  tag: string;
+  id?: string;
+  classes: string;
+  selectorPath: string;
+  componentName?: string;
+  outerHTML: string;
+  boundingBox: { x: number; y: number; width: number; height: number };
+  screenshot?: string;
+}
+export type SnapshotTrigger = 'mutation' | 'click' | 'error' | 'navigation' | 'page-load';
+export interface NavigationInfo {
+  from: string;
+  to: string | null;
+  method: 'pushState' | 'replaceState' | 'popstate' | 'full-page';
+}
+/** A structured description of a single DOM mutation */
+export interface DomChange {
+  type: 'attribute' | 'text' | 'childList';
+  selector: string;
+  componentName?: string;
+  /** attribute changes */
+  attributeName?: string;
+  oldValue?: string;
+  newValue?: string;
+  /** text changes */
+  oldText?: string;
+  newText?: string;
+  /** childList changes */
+  addedCount?: number;
+  removedCount?: number;
+  addedHTML?: string;
+  removedHTML?: string;
+}
+/** A single chronological event in a bug report timeline */
+export interface BugTimelineEntry {
+  timestamp: string;
+  trigger: SnapshotTrigger;
+  url: string;
+  consoleLogs?: ConsoleEntry[];
+  networkErrors?: NetworkError[];
+  domChanges?: DomChange[];
+  domSnapshot?: string;
+  domDiff?: string;
+  hasScreenshot?: boolean;
+  elementInfo?: { tag: string; classes: string; id?: string; innerText?: string; componentName?: string };
+  navigationInfo?: NavigationInfo;
+}
+export interface RecordingSnapshot {
+  id?: number;
+  timestamp: string;
+  trigger: SnapshotTrigger;
+  isKeyframe: boolean;
+  domSnapshot?: string;
+  domDiff?: string;
+  domChanges?: DomChange[];
+  screenshot?: string;
+  thumbnail?: string;
+  consoleLogs: ConsoleEntry[];
+  networkErrors: NetworkError[];
+  url: string;
+  scrollPosition: { x: number; y: number };
+  viewportSize: { width: number; height: number };
+  elementInfo?: { tag: string; classes: string; id?: string; innerText?: string; componentName?: string };
+  navigationInfo?: NavigationInfo;
+}
+export interface SnapshotMeta {
+  id: number;
+  timestamp: string;
+  trigger: SnapshotTrigger;
+  isKeyframe: boolean;
+  thumbnail?: string;
+  elementInfo?: RecordingSnapshot['elementInfo'];
+  consoleErrorCount: number;
+  networkErrorCount: number;
+  url: string;
+}
+// ---------------------------------------------------------------------------
+// Recording / Bug Report WebSocket messages
+// ---------------------------------------------------------------------------
+/** Panel → Overlay (via server relay): request recording history */
+export interface RecordingGetHistoryMessage {
+  type: 'RECORDING_GET_HISTORY';
+  to: 'overlay';
+}
+/** Overlay → Panel (via server relay): recording history response */
+export interface RecordingHistoryMessage {
+  type: 'RECORDING_HISTORY';
+  to: 'panel';
+  snapshots: SnapshotMeta[];
+}
+/** Panel → Overlay (via server relay): request full snapshot by ID */
+export interface RecordingGetSnapshotMessage {
+  type: 'RECORDING_GET_SNAPSHOT';
+  to: 'overlay';
+  snapshotId: number;
+}
+/** Overlay → Panel (via server relay): full snapshot response */
+export interface RecordingSnapshotMessage {
+  type: 'RECORDING_SNAPSHOT';
+  to: 'panel';
+  snapshot: RecordingSnapshot;
+}
+/** Panel → Overlay (via server relay): request range of snapshots */
+export interface RecordingGetRangeMessage {
+  type: 'RECORDING_GET_RANGE';
+  to: 'overlay';
+  ids: number[];
+}
+/** Overlay → Panel (via server relay): range of full snapshots */
+export interface RecordingRangeMessage {
+  type: 'RECORDING_RANGE';
+  to: 'panel';
+  snapshots: RecordingSnapshot[];
+}
+/** Overlay → Panel (via server relay): live push of new snapshot meta */
+export interface RecordingSnapshotMetaMessage {
+  type: 'RECORDING_SNAPSHOT_META';
+  to: 'panel';
+  meta: SnapshotMeta;
+}
+/** Panel → Overlay: enter element pick mode for bug report */
+export interface BugReportPickElementMessage {
+  type: 'BUG_REPORT_PICK_ELEMENT';
+  to: 'overlay';
+}
+/** Overlay → Panel: element was picked for bug report */
+export interface BugReportElementPickedMessage {
+  type: 'BUG_REPORT_ELEMENT_PICKED';
+  to: 'panel';
+  element: BugReportElement;
+}
+/** Overlay → Panel: pick mode was cancelled */
+export interface BugReportPickCancelledMessage {
+  type: 'BUG_REPORT_PICK_CANCELLED';
+  to: 'panel';
+}
+/** Panel → Server: stage a bug-report patch */
+export interface BugReportStageMessage {
+  type: 'BUG_REPORT_STAGE';
+  patch: Patch;
+}