markupr 2.6.4 → 2.6.5

package/dist/cli/index.mjs

@@ -1308,6 +1308,12 @@ ${REPORT_SUPPORT_LINE}
           md += `![Frame at ${frameTimestamp}](${relativePath})
 
 `;
+          const contextLine = this.formatCaptureContextLine(frame.captureContext);
+          if (contextLine) {
+            md += `> ${contextLine}
+
+`;
+          }
         }
       }
     }
@@ -1359,6 +1365,16 @@ ${REPORT_SUPPORT_LINE}
     }
     return path.relative(sessionDir, framePath);
   }
+  formatCaptureContextLine(context) {
+    if (!context) {
+      return void 0;
+    }
+    const cursor = context.cursor ? `Cursor: ${Math.round(context.cursor.x)}, ${Math.round(context.cursor.y)}` : void 0;
+    const app = context.activeWindow?.appName || context.activeWindow?.sourceName;
+    const focus = context.focusedElement?.textPreview || context.focusedElement?.label || context.focusedElement?.role;
+    const parts = [cursor, app ? `App: ${app}` : void 0, focus ? `Focus: ${focus}` : void 0].filter((part) => Boolean(part));
+    return parts.length ? parts.join(" | ") : void 0;
+  }
   /**
    * Format a timestamp in seconds to M:SS format for post-process output.
    * Examples: 0 -> "0:00", 15.3 -> "0:15", 125 -> "2:05"
@@ -2338,6 +2354,15 @@ var markdownTemplate = {
           md += `![Frame at ${frameTimestamp}](${relativePath})
 
 `;
+          const cursor = frame.captureContext?.cursor ? `Cursor: ${Math.round(frame.captureContext.cursor.x)}, ${Math.round(frame.captureContext.cursor.y)}` : void 0;
+          const app = frame.captureContext?.activeWindow?.appName || frame.captureContext?.activeWindow?.sourceName;
+          const focus = frame.captureContext?.focusedElement?.textPreview || frame.captureContext?.focusedElement?.label || frame.captureContext?.focusedElement?.role;
+          const contextLine = [cursor, app ? `App: ${app}` : void 0, focus ? `Focus: ${focus}` : void 0].filter(Boolean).join(" | ");
+          if (contextLine) {
+            md += `> ${contextLine}
+
+`;
+          }
         }
       }
     }
@@ -2377,7 +2402,8 @@ var jsonTemplate = {
           frames: frames.map((f) => ({
             path: computeRelativeFramePath(f.path, sessionDir),
             timestamp: f.timestamp,
-            reason: f.reason
+            reason: f.reason,
+            captureContext: f.captureContext
           }))
         };
       })
@@ -2668,8 +2694,15 @@ var CLIPipeline = class _CLIPipeline {
     const result = {
       transcriptSegments: segments,
       extractedFrames,
-      reportPath: this.options.outputDir
+      reportPath: this.options.outputDir,
+      captureContexts: this.normalizeCaptureContexts(this.options.captureContexts || [])
     };
+    if (result.captureContexts && result.captureContexts.length > 0 && result.extractedFrames.length > 0) {
+      result.extractedFrames = this.attachCaptureContextsToFrames(
+        result.extractedFrames,
+        result.captureContexts
+      );
+    }
     let reportContent;
     let reportExtension = ".md";
     const templateName = this.options.template;
@@ -2755,6 +2788,38 @@ var CLIPipeline = class _CLIPipeline {
       this.activeProcesses.add(child);
     });
   }
+  normalizeCaptureContexts(contexts) {
+    return contexts.filter((context) => Number.isFinite(context.recordedAt)).slice().sort((a, b) => a.recordedAt - b.recordedAt);
+  }
+  attachCaptureContextsToFrames(frames, contexts) {
+    const earliestContext = contexts[0]?.recordedAt;
+    if (!Number.isFinite(earliestContext)) {
+      return frames;
+    }
+    const maxDistanceMs = 5e3;
+    return frames.map((frame) => {
+      const frameAtMs = Number(earliestContext) + Math.round(frame.timestamp * 1e3);
+      let bestMatch;
+      let bestDistance = Number.POSITIVE_INFINITY;
+      for (const context of contexts) {
+        const distance = Math.abs(frameAtMs - context.recordedAt);
+        if (distance < bestDistance) {
+          bestDistance = distance;
+          bestMatch = context;
+        }
+        if (context.recordedAt > frameAtMs && distance > bestDistance) {
+          break;
+        }
+      }
+      if (!bestMatch || bestDistance > maxDistanceMs) {
+        return frame;
+      }
+      return {
+        ...frame,
+        captureContext: bestMatch
+      };
+    });
+  }
   /**
    * Validate the video file is a real, non-empty file with a video stream.
    */
@@ -3558,7 +3623,7 @@ async function runInit(options) {
 }
 
 // src/cli/index.ts
-var VERSION = true ? "2.6.4" : "0.0.0-dev";
+var VERSION = true ? "2.6.5" : "0.0.0-dev";
 var SYMBOLS = {
   check: "\u2714",
   // checkmark

package/dist/main/index.mjs

@@ -3696,18 +3696,44 @@ class SessionController {
     this.emitStatus();
     return true;
   }
-  registerCaptureCue(trigger = "manual") {
+  registerCaptureCue(trigger = "manual", context) {
     if (this.state !== "recording" || this.isPaused || !this.session) {
       return null;
     }
     this.captureCount += 1;
+    const timestamp = Date.now();
+    const sourceType = this.session.sourceId.startsWith("window") ? "window" : "screen";
+    const mergedContext = {
+      recordedAt: timestamp,
+      trigger,
+      activeWindow: {
+        sourceId: this.session.sourceId,
+        sourceName: this.session.metadata?.sourceName,
+        sourceType
+      }
+    };
+    if (context) {
+      Object.assign(mergedContext, context);
+      mergedContext.trigger = context.trigger || trigger;
+      mergedContext.recordedAt = context.recordedAt ?? timestamp;
+      mergedContext.activeWindow = {
+        sourceId: this.session.sourceId,
+        sourceName: this.session.metadata?.sourceName,
+        sourceType,
+        ...context.activeWindow || {}
+      };
+    }
+    const existingContexts = this.session.metadata.captureContexts || [];
+    this.session.metadata.captureContexts = [...existingContexts, mergedContext].slice(-400);
     const payload = {
       id: randomUUID(),
-      timestamp: Date.now(),
+      timestamp,
       count: this.captureCount,
-      trigger
+      trigger,
+      context: mergedContext
     };
     this.emitToRenderer(IPC_CHANNELS.SCREENSHOT_CAPTURED, payload);
+    this.persistSession();
     this.emitStatus();
     return payload;
   }
@@ -5190,7 +5216,8 @@ class FileManager {
       environment: {
         os: process.platform,
         version: app.getVersion()
-      }
+      },
+      captureContexts: session.metadata?.captureContexts?.slice(-400)
     };
     await fs.writeFile(metadataPath, JSON.stringify(metadata, null, 2), "utf-8");
   }
@@ -5441,6 +5468,12 @@ ${REPORT_SUPPORT_LINE}
           md += `![Frame at ${frameTimestamp}](${relativePath})
 
 `;
+          const contextLine = this.formatCaptureContextLine(frame.captureContext);
+          if (contextLine) {
+            md += `> ${contextLine}
+
+`;
+          }
         }
       }
     }
@@ -5492,6 +5525,16 @@ ${REPORT_SUPPORT_LINE}
     }
     return path.relative(sessionDir, framePath);
   }
+  formatCaptureContextLine(context) {
+    if (!context) {
+      return void 0;
+    }
+    const cursor = context.cursor ? `Cursor: ${Math.round(context.cursor.x)}, ${Math.round(context.cursor.y)}` : void 0;
+    const app2 = context.activeWindow?.appName || context.activeWindow?.sourceName;
+    const focus = context.focusedElement?.textPreview || context.focusedElement?.label || context.focusedElement?.role;
+    const parts = [cursor, app2 ? `App: ${app2}` : void 0, focus ? `Focus: ${focus}` : void 0].filter((part) => Boolean(part));
+    return parts.length ? parts.join(" | ") : void 0;
+  }
   /**
    * Format a timestamp in seconds to M:SS format for post-process output.
    * Examples: 0 -> "0:00", 15.3 -> "0:15", 125 -> "2:05"
@@ -6178,7 +6221,8 @@ function adaptSessionForMarkdown(session) {
     metadata: {
       os: process.platform,
       sourceName: session.metadata?.sourceName || "Screen",
-      sourceType: session.sourceId.startsWith("screen") ? "screen" : "window"
+      sourceType: session.sourceId.startsWith("screen") ? "screen" : "window",
+      captureContexts: session.metadata?.captureContexts
     }
   };
 }
@@ -8310,7 +8354,7 @@ const FFMPEG_FAST_FRAME_TIMEOUT_MS = 1e4;
 const FFMPEG_CHECK_TIMEOUT_MS = 5e3;
 const FRAME_EDGE_MARGIN_SECONDS = 0.35;
 const TIMESTAMP_DEDUPE_WINDOW_SECONDS = 0.15;
-const SAFE_CHILD_ENV = {
+const SAFE_CHILD_ENV$1 = {
   PATH: process.env.PATH,
   HOME: process.env.HOME || process.env.USERPROFILE,
   USERPROFILE: process.env.USERPROFILE,
@@ -8334,7 +8378,7 @@ class FrameExtractor {
     try {
       await execFile(this.ffmpegPath, ["-version"], {
         timeout: FFMPEG_CHECK_TIMEOUT_MS,
-        env: SAFE_CHILD_ENV
+        env: SAFE_CHILD_ENV$1
       });
       this.ffmpegAvailable = true;
       this.log("ffmpeg is available");
@@ -8433,7 +8477,7 @@ class FrameExtractor {
     ];
     await execFile(this.ffmpegPath, args, {
       timeout: FFMPEG_ACCURATE_FRAME_TIMEOUT_MS,
-      env: SAFE_CHILD_ENV
+      env: SAFE_CHILD_ENV$1
     });
   }
   async extractSingleFrameFast(videoPath, timestamp, outputPath) {
@@ -8454,7 +8498,7 @@ class FrameExtractor {
     ];
     await execFile(this.ffmpegPath, args, {
       timeout: FFMPEG_FAST_FRAME_TIMEOUT_MS,
-      env: SAFE_CHILD_ENV
+      env: SAFE_CHILD_ENV$1
     });
   }
   /**
@@ -8493,7 +8537,7 @@ class FrameExtractor {
           "default=noprint_wrappers=1:nokey=1",
           videoPath
         ],
-        { timeout: FFMPEG_CHECK_TIMEOUT_MS, env: SAFE_CHILD_ENV }
+        { timeout: FFMPEG_CHECK_TIMEOUT_MS, env: SAFE_CHILD_ENV$1 }
       );
       const parsed = Number.parseFloat(String(stdout).trim());
       if (Number.isFinite(parsed) && parsed > 0) {
@@ -10584,6 +10628,162 @@ function registerSessionHandlers(ctx, actions) {
     }
   });
 }
+const SAFE_CHILD_ENV = {
+  PATH: process.env.PATH,
+  HOME: process.env.HOME || process.env.USERPROFILE,
+  USERPROFILE: process.env.USERPROFILE,
+  LANG: process.env.LANG,
+  TMPDIR: process.env.TMPDIR || process.env.TEMP,
+  TEMP: process.env.TEMP
+};
+const MAC_CONTEXT_PROBE_JXA = `
+ObjC.import('AppKit');
+ObjC.import('CoreGraphics');
+ObjC.import('ApplicationServices');
+
+function unwrap(v) {
+  try { return ObjC.unwrap(v); } catch (_) { return null; }
+}
+
+function readAttr(el, attr) {
+  var ref = Ref();
+  var err = $.AXUIElementCopyAttributeValue(el, attr, ref);
+  if (err !== 0) return null;
+  return unwrap(ref[0]);
+}
+
+var out = {};
+var event = $.CGEventCreate(null);
+if (event) {
+  var p = $.CGEventGetLocation(event);
+  out.cursor = { x: Math.round(p.x), y: Math.round(p.y) };
+}
+
+var front = $.NSWorkspace.sharedWorkspace.frontmostApplication;
+if (front) {
+  var pid = Number(front.processIdentifier);
+  out.activeWindow = {
+    appName: unwrap(front.localizedName) || undefined,
+    pid: pid
+  };
+
+  var appEl = $.AXUIElementCreateApplication(pid);
+  var focusedWindow = readAttr(appEl, $.kAXFocusedWindowAttribute);
+  if (focusedWindow) {
+    var winTitle = readAttr(focusedWindow, $.kAXTitleAttribute);
+    if (winTitle) out.activeWindow.title = String(winTitle);
+  }
+
+  var focused = readAttr(appEl, $.kAXFocusedUIElementAttribute);
+  if (focused) {
+    out.focusedElement = {
+      role: readAttr(focused, $.kAXRoleAttribute) || undefined,
+      subrole: readAttr(focused, $.kAXSubroleAttribute) || undefined,
+      title: readAttr(focused, $.kAXTitleAttribute) || undefined,
+      description: readAttr(focused, $.kAXDescriptionAttribute) || undefined,
+      value: readAttr(focused, $.kAXValueAttribute) || undefined,
+    };
+  }
+}
+
+JSON.stringify(out);
+`;
+function runMacContextProbe(timeoutMs) {
+  return new Promise((resolve2) => {
+    execFile$1(
+      "osascript",
+      ["-l", "JavaScript", "-e", MAC_CONTEXT_PROBE_JXA],
+      { env: SAFE_CHILD_ENV, timeout: timeoutMs },
+      (error, stdout) => {
+        if (error) {
+          resolve2(null);
+          return;
+        }
+        try {
+          const parsed = JSON.parse(stdout.toString().trim());
+          resolve2(parsed);
+        } catch {
+          resolve2(null);
+        }
+      }
+    );
+  });
+}
+function sanitizeText(value, maxLength = 140) {
+  if (!value) return void 0;
+  const normalized = value.replace(/\s+/g, " ").trim();
+  if (!normalized) return void 0;
+  return normalized.slice(0, maxLength);
+}
+function mergeFocusedHints(osHint, rendererHint) {
+  if (!osHint && !rendererHint) return void 0;
+  if (!osHint && rendererHint) return rendererHint;
+  if (osHint && !rendererHint) return osHint;
+  return {
+    ...rendererHint,
+    ...osHint,
+    source: osHint?.source || rendererHint?.source || "unknown"
+  };
+}
+async function probeCaptureContext(input) {
+  const cursorPoint = screen.getCursorScreenPoint();
+  const nearestDisplay = screen.getDisplayNearestPoint(cursorPoint);
+  const sourceType = input.sourceId?.startsWith("window") ? "window" : "screen";
+  const baseContext = {
+    recordedAt: Date.now(),
+    trigger: input.trigger,
+    cursor: {
+      x: cursorPoint.x,
+      y: cursorPoint.y,
+      displayId: String(nearestDisplay.id),
+      displayLabel: nearestDisplay.label || void 0,
+      relativeX: cursorPoint.x - nearestDisplay.bounds.x,
+      relativeY: cursorPoint.y - nearestDisplay.bounds.y
+    },
+    activeWindow: {
+      sourceId: input.sourceId,
+      sourceName: input.sourceName,
+      sourceType
+    }
+  };
+  if (process.platform !== "darwin") {
+    baseContext.focusedElement = mergeFocusedHints(void 0, input.focusedElementHint);
+    return baseContext;
+  }
+  const macProbe = await runMacContextProbe(550);
+  if (macProbe?.cursor) {
+    baseContext.cursor = {
+      ...baseContext.cursor,
+      x: Number.isFinite(macProbe.cursor.x) ? Number(macProbe.cursor.x) : baseContext.cursor?.x ?? 0,
+      y: Number.isFinite(macProbe.cursor.y) ? Number(macProbe.cursor.y) : baseContext.cursor?.y ?? 0
+    };
+  }
+  if (macProbe?.activeWindow) {
+    baseContext.activeWindow = {
+      ...baseContext.activeWindow,
+      appName: sanitizeText(macProbe.activeWindow.appName, 120),
+      title: sanitizeText(macProbe.activeWindow.title, 160),
+      pid: Number.isFinite(macProbe.activeWindow.pid) ? Number(macProbe.activeWindow.pid) : void 0
+    };
+  }
+  const osFocusedHint = macProbe?.focusedElement ? {
+    source: "os-accessibility",
+    role: sanitizeText(macProbe.focusedElement.role, 80),
+    textPreview: sanitizeText(macProbe.focusedElement.value, 120) || sanitizeText(macProbe.focusedElement.title, 120) || sanitizeText(macProbe.focusedElement.description, 120),
+    appName: baseContext.activeWindow?.appName,
+    windowTitle: baseContext.activeWindow?.title
+  } : void 0;
+  baseContext.focusedElement = mergeFocusedHints(osFocusedHint, input.focusedElementHint);
+  if (!baseContext.focusedElement && (baseContext.activeWindow?.title || baseContext.activeWindow?.appName)) {
+    baseContext.focusedElement = {
+      source: "window-title",
+      textPreview: baseContext.activeWindow?.title || baseContext.activeWindow?.appName,
+      appName: baseContext.activeWindow?.appName,
+      windowTitle: baseContext.activeWindow?.title
+    };
+  }
+  return baseContext;
+}
 const activeScreenRecordings = /* @__PURE__ */ new Map();
 const finalizedScreenRecordings = /* @__PURE__ */ new Map();
 function sleep$1(ms) {
@@ -10673,8 +10873,15 @@ function registerCaptureHandlers(ctx) {
       return [];
     }
   });
-  ipcMain.handle(IPC_CHANNELS.CAPTURE_MANUAL_SCREENSHOT, async () => {
-    const cue = sessionController.registerCaptureCue("manual");
+  ipcMain.handle(IPC_CHANNELS.CAPTURE_MANUAL_SCREENSHOT, async (_, payload) => {
+    const session = sessionController.getSession();
+    const captureContext = await probeCaptureContext({
+      trigger: "manual",
+      sourceId: session?.sourceId,
+      sourceName: session?.metadata?.sourceName,
+      focusedElementHint: payload?.focusedElementHint
+    });
+    const cue = sessionController.registerCaptureCue("manual", captureContext);
     if (!cue) {
       return { success: false, error: "Manual capture is only available while recording and not paused." };
     }
@@ -11903,9 +12110,15 @@ async function appendExtractedFramesToReport(markdownPath, extractedFrames) {
     const filename = basename(frame.path) || `frame-${String(index + 1).padStart(3, "0")}.png`;
     const timestamp = formatSecondsAsTimestamp(frame.timestamp);
     const reason = frame.reason?.trim() || "Auto-extracted frame";
+    const cursor = frame.captureContext?.cursor ? `Cursor: ${Math.round(frame.captureContext.cursor.x)}, ${Math.round(frame.captureContext.cursor.y)}` : void 0;
+    const app2 = frame.captureContext?.activeWindow?.appName || frame.captureContext?.activeWindow?.sourceName;
+    const focused = frame.captureContext?.focusedElement?.textPreview || frame.captureContext?.focusedElement?.label || frame.captureContext?.focusedElement?.role;
+    const contextLine = [cursor, app2 ? `App: ${app2}` : void 0, focused ? `Focus: ${focused}` : void 0].filter(Boolean).join(" | ");
     return `### [${timestamp}] ${reason}
 
-![${reason}](./screenshots/${filename})`;
+![${reason}](./screenshots/${filename})${contextLine ? `
+
+> ${contextLine}` : ""}`;
   }).join("\n\n");
   markdown += `
 ## Auto-Extracted Screenshots
@@ -12377,7 +12590,13 @@ async function handlePauseResume() {
   pauseSession();
 }
 async function handleManualScreenshot() {
-  const cue = sessionController.registerCaptureCue("manual");
+  const session = sessionController.getSession();
+  const captureContext = await probeCaptureContext({
+    trigger: "manual",
+    sourceId: session?.sourceId,
+    sourceName: session?.metadata?.sourceName
+  });
+  const cue = sessionController.registerCaptureCue("manual", captureContext);
   if (!cue) {
     return;
   }
@@ -12443,6 +12662,38 @@ function buildPostProcessTranscriptSegments(session) {
     };
   });
 }
+function getSessionCaptureContexts(session) {
+  const contexts = session.metadata?.captureContexts || [];
+  return contexts.filter((context) => Number.isFinite(context.recordedAt)).slice().sort((a, b) => a.recordedAt - b.recordedAt);
+}
+function attachCaptureContextsToExtractedFrames(session, extractedFrames, captureContexts) {
+  if (!captureContexts.length || !extractedFrames.length) {
+    return extractedFrames;
+  }
+  const maxDistanceMs = 5e3;
+  return extractedFrames.map((frame) => {
+    const frameAtMs = session.startTime + Math.round(frame.timestamp * 1e3);
+    let bestMatch;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const context of captureContexts) {
+      const distance = Math.abs(frameAtMs - context.recordedAt);
+      if (distance < bestDistance) {
+        bestDistance = distance;
+        bestMatch = context;
+      }
+      if (context.recordedAt > frameAtMs && distance > bestDistance) {
+        break;
+      }
+    }
+    if (!bestMatch || bestDistance > maxDistanceMs) {
+      return frame;
+    }
+    return {
+      ...frame,
+      captureContext: bestMatch
+    };
+  });
+}
 async function copyReportPathToClipboard(path2) {
   const maxAttempts = 3;
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
@@ -12733,6 +12984,7 @@ async function stopSession() {
     emitProcessingProgress(71, "preparing");
     let postProcessResult = null;
     const providedTranscriptSegments = buildPostProcessTranscriptSegments(session);
+    const captureContexts = getSessionCaptureContexts(session);
     const aiMomentHints = extractAiFrameHintsFromMarkdown(
       document.content,
       providedTranscriptSegments
@@ -12757,6 +13009,14 @@ async function stopSession() {
             emitProcessingProgress(mappedPercent, progress.step);
           }
         });
+        if (postProcessResult) {
+          postProcessResult.captureContexts = captureContexts;
+          postProcessResult.extractedFrames = attachCaptureContextsToExtractedFrames(
+            session,
+            postProcessResult.extractedFrames,
+            captureContexts
+          );
+        }
         console.log(
           `[Main:stopSession] Step 5/6 complete: post-processing took ${Date.now() - postProcessStartedAt}ms, ${postProcessResult?.transcriptSegments.length ?? 0} segments, ${postProcessResult?.extractedFrames.length ?? 0} frames extracted`
         );

package/dist/mcp/index.mjs

@@ -246,6 +246,141 @@ var SessionStore = class {
 };
 var sessionStore = new SessionStore();
 
+// src/mcp/utils/CaptureContext.ts
+import { execFile as execFileCb2 } from "child_process";
+var SAFE_CHILD_ENV2 = {
+  PATH: process.env.PATH,
+  HOME: process.env.HOME || process.env.USERPROFILE,
+  USERPROFILE: process.env.USERPROFILE,
+  LANG: process.env.LANG,
+  TMPDIR: process.env.TMPDIR || process.env.TEMP,
+  TEMP: process.env.TEMP
+};
+var MAC_CONTEXT_PROBE_JXA = `
+ObjC.import('AppKit');
+ObjC.import('CoreGraphics');
+ObjC.import('ApplicationServices');
+
+function unwrap(v) {
+  try { return ObjC.unwrap(v); } catch (_) { return null; }
+}
+
+function readAttr(el, attr) {
+  var ref = Ref();
+  var err = $.AXUIElementCopyAttributeValue(el, attr, ref);
+  if (err !== 0) return null;
+  return unwrap(ref[0]);
+}
+
+var out = {};
+var event = $.CGEventCreate(null);
+if (event) {
+  var p = $.CGEventGetLocation(event);
+  out.cursor = { x: Math.round(p.x), y: Math.round(p.y) };
+}
+
+var front = $.NSWorkspace.sharedWorkspace.frontmostApplication;
+if (front) {
+  var pid = Number(front.processIdentifier);
+  out.activeWindow = {
+    appName: unwrap(front.localizedName) || undefined,
+    pid: pid
+  };
+
+  var appEl = $.AXUIElementCreateApplication(pid);
+  var focusedWindow = readAttr(appEl, $.kAXFocusedWindowAttribute);
+  if (focusedWindow) {
+    var winTitle = readAttr(focusedWindow, $.kAXTitleAttribute);
+    if (winTitle) out.activeWindow.title = String(winTitle);
+  }
+
+  var focused = readAttr(appEl, $.kAXFocusedUIElementAttribute);
+  if (focused) {
+    out.focusedElement = {
+      role: readAttr(focused, $.kAXRoleAttribute) || undefined,
+      title: readAttr(focused, $.kAXTitleAttribute) || undefined,
+      description: readAttr(focused, $.kAXDescriptionAttribute) || undefined,
+      value: readAttr(focused, $.kAXValueAttribute) || undefined,
+    };
+  }
+}
+
+JSON.stringify(out);
+`;
+function sanitizeText(value, maxLength = 140) {
+  if (!value) return void 0;
+  const normalized = value.replace(/\s+/g, " ").trim();
+  if (!normalized) return void 0;
+  return normalized.slice(0, maxLength);
+}
+function runMacContextProbe(timeoutMs) {
+  return new Promise((resolve4) => {
+    execFileCb2(
+      "osascript",
+      ["-l", "JavaScript", "-e", MAC_CONTEXT_PROBE_JXA],
+      { env: SAFE_CHILD_ENV2, timeout: timeoutMs },
+      (error, stdout) => {
+        if (error) {
+          resolve4(null);
+          return;
+        }
+        try {
+          const parsed = JSON.parse(stdout.toString().trim());
+          resolve4(parsed);
+        } catch {
+          resolve4(null);
+        }
+      }
+    );
+  });
+}
+async function captureContextSnapshot() {
+  const snapshot = {
+    recordedAt: Date.now()
+  };
+  if (process.platform !== "darwin") {
+    return snapshot;
+  }
+  const context = await runMacContextProbe(550);
+  if (!context) {
+    return snapshot;
+  }
+  if (context.cursor && Number.isFinite(context.cursor.x) && Number.isFinite(context.cursor.y)) {
+    snapshot.cursor = {
+      x: Number(context.cursor.x),
+      y: Number(context.cursor.y)
+    };
+  }
+  if (context.activeWindow) {
+    snapshot.activeWindow = {
+      appName: sanitizeText(context.activeWindow.appName, 120),
+      title: sanitizeText(context.activeWindow.title, 160),
+      pid: Number.isFinite(context.activeWindow.pid) ? Number(context.activeWindow.pid) : void 0
+    };
+  }
+  if (context.focusedElement) {
+    const textPreview = sanitizeText(context.focusedElement.value, 120) || sanitizeText(context.focusedElement.title, 120) || sanitizeText(context.focusedElement.description, 120);
+    if (textPreview || context.focusedElement.role) {
+      snapshot.focusedElement = {
+        source: "os-accessibility",
+        role: sanitizeText(context.focusedElement.role, 80),
+        textPreview,
+        appName: snapshot.activeWindow?.appName,
+        windowTitle: snapshot.activeWindow?.title
+      };
+    }
+  }
+  if (!snapshot.focusedElement && (snapshot.activeWindow?.title || snapshot.activeWindow?.appName)) {
+    snapshot.focusedElement = {
+      source: "window-title",
+      textPreview: snapshot.activeWindow?.title || snapshot.activeWindow?.appName,
+      appName: snapshot.activeWindow?.appName,
+      windowTitle: snapshot.activeWindow?.title
+    };
+  }
+  return snapshot;
+}
+
 // src/mcp/tools/captureScreenshot.ts
 function register(server) {
   server.tool(
@@ -265,18 +400,40 @@ function register(server) {
         const index = existing.filter((f) => f.startsWith("screenshot-")).length + 1;
         const filename = `screenshot-${String(index).padStart(3, "0")}.png`;
         const outputPath = join2(screenshotsDir, filename);
+        const context = await captureContextSnapshot();
         log(`Capturing screenshot: display=${display}, label=${label ?? "none"}`);
         await capture({ display, outputPath });
         if (shouldOptimize) {
           await optimize(outputPath);
         }
+        const latestMetadata = await sessionStore.get(session.id);
+        const existingCaptures = latestMetadata?.captures ?? [];
+        await sessionStore.update(session.id, {
+          lastCaptureContext: context,
+          captures: [
+            ...existingCaptures,
+            {
+              file: filename,
+              label,
+              display,
+              capturedAt: context.recordedAt,
+              context
+            }
+          ].slice(-250)
+        });
         const markdownRef = `![${label ?? filename}](screenshots/${filename})`;
+        const contextSummary = [
+          context.cursor ? `Cursor: ${Math.round(context.cursor.x)}, ${Math.round(context.cursor.y)}` : "",
+          context.activeWindow?.appName ? `App: ${context.activeWindow.appName}` : "",
+          context.focusedElement?.textPreview ? `Focus: ${context.focusedElement.textPreview}` : ""
+        ].filter(Boolean).join(" | ");
         return {
           content: [
             {
               type: "text",
               text: `Screenshot saved: ${outputPath}
-${markdownRef}`
+${markdownRef}${contextSummary ? `
+Context: ${contextSummary}` : ""}`
             }
           ]
         };
@@ -295,10 +452,10 @@ import { z as z2 } from "zod";
 import { join as join6 } from "path";
 
 // src/mcp/capture/ScreenRecorder.ts
-import { execFile as execFileCb2 } from "child_process";
+import { execFile as execFileCb3 } from "child_process";
 import { stat as stat2 } from "fs/promises";
 import { resolve as resolve3 } from "path";
-var SAFE_CHILD_ENV2 = {
+var SAFE_CHILD_ENV3 = {
   PATH: process.env.PATH,
   HOME: process.env.HOME || process.env.USERPROFILE,
   USERPROFILE: process.env.USERPROFILE,
@@ -338,10 +495,10 @@ async function record(options) {
   const args = buildFfmpegArgs(outputPath, videoDevice, audioDevice, duration);
   log(`Recording screen+audio: duration=${duration}s, output=${outputPath}`);
   await new Promise((resolve4, reject) => {
-    execFileCb2(
+    execFileCb3(
       "ffmpeg",
       args,
-      { env: SAFE_CHILD_ENV2, timeout: (duration + 30) * 1e3 },
+      { env: SAFE_CHILD_ENV3, timeout: (duration + 30) * 1e3 },
       (error) => {
         if (error) {
           reject(
@@ -366,10 +523,10 @@ function start(options) {
   const audioDevice = options.audioDevice ?? "default";
   const args = buildFfmpegArgs(outputPath, videoDevice, audioDevice);
   log(`Starting long-form recording: output=${outputPath}`);
-  const child = execFileCb2(
+  const child = execFileCb3(
     "ffmpeg",
     args,
-    { env: SAFE_CHILD_ENV2 },
+    { env: SAFE_CHILD_ENV3 },
     (error) => {
       if (error && !error.killed) {
         log(`Recording process exited with error: ${error.message}`);
@@ -422,7 +579,7 @@ Check Screen Recording and Microphone permissions in System Settings \u2192 Priv
 import { existsSync as existsSync3, mkdirSync as mkdirSync2 } from "fs";
 import { stat as stat3, unlink as unlink2, writeFile as writeFile2, chmod as chmod2 } from "fs/promises";
 import { join as join5, basename as basename3 } from "path";
-import { execFile as execFileCb4 } from "child_process";
+import { execFile as execFileCb5 } from "child_process";
 import { tmpdir as tmpdir2 } from "os";
 import { randomUUID as randomUUID2 } from "crypto";
 
@@ -564,19 +721,19 @@ var TranscriptAnalyzer = class {
 var transcriptAnalyzer = new TranscriptAnalyzer();
 
 // src/main/pipeline/FrameExtractor.ts
-import { execFile as execFileCb3 } from "child_process";
+import { execFile as execFileCb4 } from "child_process";
 import { promisify } from "util";
 import { existsSync, mkdirSync } from "fs";
 import { stat as statFile } from "fs/promises";
 import { join as join3 } from "path";
-var execFile = promisify(execFileCb3);
+var execFile = promisify(execFileCb4);
 var DEFAULT_MAX_FRAMES = 20;
 var FFMPEG_ACCURATE_FRAME_TIMEOUT_MS = 2e4;
 var FFMPEG_FAST_FRAME_TIMEOUT_MS = 1e4;
 var FFMPEG_CHECK_TIMEOUT_MS = 5e3;
 var FRAME_EDGE_MARGIN_SECONDS2 = 0.35;
 var TIMESTAMP_DEDUPE_WINDOW_SECONDS = 0.15;
-var SAFE_CHILD_ENV3 = {
+var SAFE_CHILD_ENV4 = {
   PATH: process.env.PATH,
   HOME: process.env.HOME || process.env.USERPROFILE,
   USERPROFILE: process.env.USERPROFILE,
@@ -600,7 +757,7 @@ var FrameExtractor = class {
     try {
       await execFile(this.ffmpegPath, ["-version"], {
         timeout: FFMPEG_CHECK_TIMEOUT_MS,
-        env: SAFE_CHILD_ENV3
+        env: SAFE_CHILD_ENV4
       });
       this.ffmpegAvailable = true;
       this.log("ffmpeg is available");
@@ -699,7 +856,7 @@ var FrameExtractor = class {
     ];
     await execFile(this.ffmpegPath, args, {
       timeout: FFMPEG_ACCURATE_FRAME_TIMEOUT_MS,
-      env: SAFE_CHILD_ENV3
+      env: SAFE_CHILD_ENV4
     });
   }
   async extractSingleFrameFast(videoPath, timestamp, outputPath) {
@@ -720,7 +877,7 @@ var FrameExtractor = class {
     ];
     await execFile(this.ffmpegPath, args, {
       timeout: FFMPEG_FAST_FRAME_TIMEOUT_MS,
-      env: SAFE_CHILD_ENV3
+      env: SAFE_CHILD_ENV4
     });
   }
   /**
@@ -759,7 +916,7 @@ var FrameExtractor = class {
           "default=noprint_wrappers=1:nokey=1",
           videoPath
         ],
-        { timeout: FFMPEG_CHECK_TIMEOUT_MS, env: SAFE_CHILD_ENV3 }
+        { timeout: FFMPEG_CHECK_TIMEOUT_MS, env: SAFE_CHILD_ENV4 }
       );
       const parsed = Number.parseFloat(String(stdout).trim());
       if (Number.isFinite(parsed) && parsed > 0) {
@@ -1005,6 +1162,12 @@ ${REPORT_SUPPORT_LINE}
           md += `![Frame at ${frameTimestamp}](${relativePath})
 
 `;
+          const contextLine = this.formatCaptureContextLine(frame.captureContext);
+          if (contextLine) {
+            md += `> ${contextLine}
+
+`;
+          }
         }
       }
     }
@@ -1056,6 +1219,16 @@ ${REPORT_SUPPORT_LINE}
     }
     return path2.relative(sessionDir, framePath);
   }
+  formatCaptureContextLine(context) {
+    if (!context) {
+      return void 0;
+    }
+    const cursor = context.cursor ? `Cursor: ${Math.round(context.cursor.x)}, ${Math.round(context.cursor.y)}` : void 0;
+    const app = context.activeWindow?.appName || context.activeWindow?.sourceName;
+    const focus = context.focusedElement?.textPreview || context.focusedElement?.label || context.focusedElement?.role;
+    const parts = [cursor, app ? `App: ${app}` : void 0, focus ? `Focus: ${focus}` : void 0].filter((part) => Boolean(part));
+    return parts.length ? parts.join(" | ") : void 0;
+  }
   /**
    * Format a timestamp in seconds to M:SS format for post-process output.
    * Examples: 0 -> "0:00", 15.3 -> "0:15", 125 -> "2:05"
@@ -2035,6 +2208,15 @@ var markdownTemplate = {
           md += `![Frame at ${frameTimestamp}](${relativePath})
 
 `;
+          const cursor = frame.captureContext?.cursor ? `Cursor: ${Math.round(frame.captureContext.cursor.x)}, ${Math.round(frame.captureContext.cursor.y)}` : void 0;
+          const app = frame.captureContext?.activeWindow?.appName || frame.captureContext?.activeWindow?.sourceName;
+          const focus = frame.captureContext?.focusedElement?.textPreview || frame.captureContext?.focusedElement?.label || frame.captureContext?.focusedElement?.role;
+          const contextLine = [cursor, app ? `App: ${app}` : void 0, focus ? `Focus: ${focus}` : void 0].filter(Boolean).join(" | ");
+          if (contextLine) {
+            md += `> ${contextLine}
+
+`;
+          }
         }
       }
     }
@@ -2074,7 +2256,8 @@ var jsonTemplate = {
           frames: frames.map((f) => ({
             path: computeRelativeFramePath(f.path, sessionDir),
             timestamp: f.timestamp,
-            reason: f.reason
+            reason: f.reason,
+            captureContext: f.captureContext
           }))
         };
       })
@@ -2361,8 +2544,15 @@ var CLIPipeline = class _CLIPipeline {
     const result = {
       transcriptSegments: segments,
       extractedFrames,
-      reportPath: this.options.outputDir
+      reportPath: this.options.outputDir,
+      captureContexts: this.normalizeCaptureContexts(this.options.captureContexts || [])
     };
+    if (result.captureContexts && result.captureContexts.length > 0 && result.extractedFrames.length > 0) {
+      result.extractedFrames = this.attachCaptureContextsToFrames(
+        result.extractedFrames,
+        result.captureContexts
+      );
+    }
     let reportContent;
     let reportExtension = ".md";
     const templateName = this.options.template;
@@ -2440,7 +2630,7 @@ var CLIPipeline = class _CLIPipeline {
   };
   execFileTracked(command, args) {
     return new Promise((resolve4, reject) => {
-      const child = execFileCb4(command, args, { env: _CLIPipeline.SAFE_CHILD_ENV }, (error, stdout, stderr) => {
+      const child = execFileCb5(command, args, { env: _CLIPipeline.SAFE_CHILD_ENV }, (error, stdout, stderr) => {
         this.activeProcesses.delete(child);
         if (error) reject(error);
         else resolve4({ stdout: stdout?.toString() ?? "", stderr: stderr?.toString() ?? "" });
@@ -2448,6 +2638,38 @@ var CLIPipeline = class _CLIPipeline {
       this.activeProcesses.add(child);
     });
   }
+  normalizeCaptureContexts(contexts) {
+    return contexts.filter((context) => Number.isFinite(context.recordedAt)).slice().sort((a, b) => a.recordedAt - b.recordedAt);
+  }
+  attachCaptureContextsToFrames(frames, contexts) {
+    const earliestContext = contexts[0]?.recordedAt;
+    if (!Number.isFinite(earliestContext)) {
+      return frames;
+    }
+    const maxDistanceMs = 5e3;
+    return frames.map((frame) => {
+      const frameAtMs = Number(earliestContext) + Math.round(frame.timestamp * 1e3);
+      let bestMatch;
+      let bestDistance = Number.POSITIVE_INFINITY;
+      for (const context of contexts) {
+        const distance = Math.abs(frameAtMs - context.recordedAt);
+        if (distance < bestDistance) {
+          bestDistance = distance;
+          bestMatch = context;
+        }
+        if (context.recordedAt > frameAtMs && distance > bestDistance) {
+          break;
+        }
+      }
+      if (!bestMatch || bestDistance > maxDistanceMs) {
+        return frame;
+      }
+      return {
+        ...frame,
+        captureContext: bestMatch
+      };
+    });
+  }
   /**
    * Validate the video file is a real, non-empty file with a video stream.
    */
@@ -2709,6 +2931,29 @@ var CLIPipelineError = class extends Error {
 };
 
 // src/mcp/tools/captureWithVoice.ts
+function toSharedCaptureContext(context) {
+  if (!context) {
+    return void 0;
+  }
+  return {
+    recordedAt: context.recordedAt,
+    trigger: "manual",
+    cursor: context.cursor,
+    activeWindow: {
+      appName: context.activeWindow?.appName,
+      title: context.activeWindow?.title,
+      pid: context.activeWindow?.pid,
+      sourceType: "screen"
+    },
+    focusedElement: context.focusedElement ? {
+      source: context.focusedElement.source,
+      role: context.focusedElement.role,
+      textPreview: context.focusedElement.textPreview,
+      appName: context.focusedElement.appName,
+      windowTitle: context.focusedElement.windowTitle
+    } : void 0
+  };
+}
 function register2(server) {
   server.tool(
     "capture_with_voice",
@@ -2724,10 +2969,26 @@ function register2(server) {
     async ({ duration, outputDir, skipFrames, template }) => {
       try {
         const session = await sessionStore.create();
+        const startContext = await captureContextSnapshot();
+        await sessionStore.update(session.id, {
+          recordingContextStart: startContext,
+          lastCaptureContext: startContext
+        });
         const sessionDir = sessionStore.getSessionDir(session.id);
         const videoPath = join6(sessionDir, "recording.mp4");
         log(`Starting capture_with_voice: duration=${duration}s`);
         await record({ duration, outputPath: videoPath });
+        const stopContext = await captureContextSnapshot();
+        await sessionStore.update(session.id, {
+          recordingContextStop: stopContext,
+          lastCaptureContext: stopContext
+        });
+        const metadataBeforePipeline = await sessionStore.get(session.id);
+        const captureContexts = [
+          toSharedCaptureContext(metadataBeforePipeline?.recordingContextStart),
+          ...(metadataBeforePipeline?.captures || []).map((capture2) => toSharedCaptureContext(capture2.context)),
+          toSharedCaptureContext(stopContext)
+        ].filter((context) => Boolean(context));
         const pipelineOutputDir = outputDir ?? sessionDir;
         const pipeline = new CLIPipeline(
           {
@@ -2735,7 +2996,8 @@ function register2(server) {
             outputDir: pipelineOutputDir,
             skipFrames,
             template,
-            verbose: false
+            verbose: false,
+            captureContexts
           },
           (msg) => log(msg)
         );
@@ -2744,7 +3006,9 @@ function register2(server) {
           status: "complete",
           endTime: Date.now(),
           videoPath,
-          reportPath: result.outputPath
+          reportPath: result.outputPath,
+          recordingContextStop: stopContext,
+          lastCaptureContext: stopContext
         });
         return {
           content: [
@@ -2991,6 +3255,11 @@ function register5(server) {
           };
         }
         const session = await sessionStore.create(label);
+        const startContext = await captureContextSnapshot();
+        await sessionStore.update(session.id, {
+          recordingContextStart: startContext,
+          lastCaptureContext: startContext
+        });
         const sessionDir = sessionStore.getSessionDir(session.id);
         const videoPath = join8(sessionDir, "recording.mp4");
         log(`Starting long-form recording: session=${session.id}`);
@@ -3021,6 +3290,29 @@ function register5(server) {
 
 // src/mcp/tools/stopRecording.ts
 import { z as z6 } from "zod";
+function toSharedCaptureContext2(context) {
+  if (!context) {
+    return void 0;
+  }
+  return {
+    recordedAt: context.recordedAt,
+    trigger: "manual",
+    cursor: context.cursor,
+    activeWindow: {
+      appName: context.activeWindow?.appName,
+      title: context.activeWindow?.title,
+      pid: context.activeWindow?.pid,
+      sourceType: "screen"
+    },
+    focusedElement: context.focusedElement ? {
+      source: context.focusedElement.source,
+      role: context.focusedElement.role,
+      textPreview: context.focusedElement.textPreview,
+      appName: context.focusedElement.appName,
+      windowTitle: context.focusedElement.windowTitle
+    } : void 0
+  };
+}
 function register6(server) {
   server.tool(
     "stop_recording",
@@ -3050,7 +3342,14 @@ function register6(server) {
         log(`Stopping recording: session=${current.sessionId}`);
         await stop(current.process);
         const { sessionId, videoPath } = activeRecording.stop();
+        const stopContext = await captureContextSnapshot();
         await sessionStore.update(sessionId, { status: "processing" });
+        const metadataBeforePipeline = await sessionStore.get(sessionId);
+        const captureContexts = [
+          toSharedCaptureContext2(metadataBeforePipeline?.recordingContextStart),
+          ...(metadataBeforePipeline?.captures || []).map((capture2) => toSharedCaptureContext2(capture2.context)),
+          toSharedCaptureContext2(stopContext)
+        ].filter((context) => Boolean(context));
         const sessionDir = sessionStore.getSessionDir(sessionId);
         const pipeline = new CLIPipeline(
           {
@@ -3058,7 +3357,8 @@ function register6(server) {
             outputDir: sessionDir,
             skipFrames,
             template,
-            verbose: false
+            verbose: false,
+            captureContexts
           },
           (msg) => log(msg)
         );
@@ -3067,7 +3367,9 @@ function register6(server) {
           status: "complete",
           endTime: Date.now(),
           videoPath,
-          reportPath: result.outputPath
+          reportPath: result.outputPath,
+          recordingContextStop: stopContext,
+          lastCaptureContext: stopContext
         });
         return {
           content: [
@@ -4222,7 +4524,7 @@ function registerResources(server) {
 }
 
 // src/mcp/server.ts
-var VERSION = true ? "2.6.4" : "0.0.0-dev";
+var VERSION = true ? "2.6.5" : "0.0.0-dev";
 function createServer() {
   const server = new McpServer2({
     name: "markupR",
@@ -4242,7 +4544,7 @@ function createServer() {
 }
 
 // src/mcp/index.ts
-var VERSION2 = true ? "2.6.4" : "0.0.0-dev";
+var VERSION2 = true ? "2.6.5" : "0.0.0-dev";
 log(`markupR MCP server v${VERSION2} starting...`);
 process.on("uncaughtException", (error) => {
   log(`Uncaught exception: ${error instanceof Error ? error.message : String(error)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markupr",
-  "version": "2.6.4",
+  "version": "2.6.5",
   "description": "Record your screen, narrate feedback, get structured Markdown with screenshots. Desktop app, CLI, and MCP server for AI coding agents like Claude Code, Cursor, and Windsurf.",
   "type": "module",
   "main": "dist/main/index.mjs",