markupr 2.1.8

package/src/main/output/MarkdownPatcher.ts

@@ -0,0 +1,299 @@
+/**
+ * MarkdownPatcher
+ *
+ * Post-processing utilities for patching generated markdown reports with
+ * extracted frame links, metadata sync, and processing traces. Extracted
+ * from index.ts for separation of concerns.
+ */
+
+import * as fs from 'fs/promises';
+import { join, basename } from 'path';
+import type { TranscriptSegment, KeyMoment } from '../pipeline';
+
+// =============================================================================
+// Text Normalization Helpers
+// =============================================================================
+
+export function formatSecondsAsTimestamp(seconds: number): string {
+  const total = Math.max(0, Math.floor(seconds));
+  const mins = Math.floor(total / 60);
+  const secs = total % 60;
+  return `${mins.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`;
+}
+
+function normalizeForMatch(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[`*_~[\]().,!?;:'"\\/|-]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function buildTokenSet(value: string): Set<string> {
+  const tokens = normalizeForMatch(value)
+    .split(' ')
+    .map((token) => token.trim())
+    .filter((token) => token.length >= 3);
+  return new Set(tokens);
+}
+
+function overlapScore(a: Set<string>, b: Set<string>): number {
+  if (a.size === 0 || b.size === 0) {
+    return 0;
+  }
+  let overlap = 0;
+  for (const token of a) {
+    if (b.has(token)) {
+      overlap += 1;
+    }
+  }
+  return overlap / Math.min(a.size, b.size);
+}
+
+// =============================================================================
+// AI Frame Hint Extraction
+// =============================================================================
+
+/**
+ * Parse AI-generated markdown to extract frame extraction hints.
+ * Matches **Timestamp:** annotations and blockquote references back
+ * to transcript segments for accurate frame timing.
+ */
+export function extractAiFrameHintsFromMarkdown(
+  markdown: string,
+  transcriptSegments: TranscriptSegment[]
+): KeyMoment[] {
+  if (!markdown) {
+    return [];
+  }
+
+  const parseTimestampToSeconds = (value: string): number | null => {
+    const trimmed = value.trim();
+    const parts = trimmed.split(':').map((part) => Number.parseInt(part, 10));
+    if (parts.some((part) => !Number.isFinite(part) || part < 0)) {
+      return null;
+    }
+    if (parts.length === 2) {
+      return parts[0] * 60 + parts[1];
+    }
+    if (parts.length === 3) {
+      return parts[0] * 3600 + parts[1] * 60 + parts[2];
+    }
+    return null;
+  };
+
+  const timestampHints = Array.from(markdown.matchAll(/\*\*Timestamp:\*\*\s*([0-9]{1,2}:[0-9]{2}(?::[0-9]{2})?)/g))
+    .map((match) => parseTimestampToSeconds(match[1]))
+    .filter((value): value is number => value !== null)
+    .map((seconds) => ({
+      timestamp: Math.max(0, seconds),
+      reason: 'AI-timestamped issue context',
+      confidence: 0.96,
+    }));
+
+  const quoteLines = Array.from(markdown.matchAll(/^\s*>\s+(.+)$/gm))
+    .map((match) => match[1].trim())
+    .filter((line) => line.length >= 10);
+  if (quoteLines.length === 0 && timestampHints.length === 0) {
+    return [];
+  }
+
+  const normalizedSegments = transcriptSegments.map((segment) => ({
+    segment,
+    normalized: normalizeForMatch(segment.text || ''),
+    tokens: buildTokenSet(segment.text || ''),
+  }));
+
+  const hints: KeyMoment[] = [...timestampHints];
+  const seenQuotes = new Set<string>();
+
+  for (const quote of quoteLines) {
+    const normalizedQuote = normalizeForMatch(quote);
+    if (!normalizedQuote || seenQuotes.has(normalizedQuote)) {
+      continue;
+    }
+    seenQuotes.add(normalizedQuote);
+
+    const quoteTokens = buildTokenSet(quote);
+    let bestMatch: { score: number; segment: TranscriptSegment } | null = null;
+
+    for (const candidate of normalizedSegments) {
+      if (!candidate.normalized) {
+        continue;
+      }
+
+      let score = overlapScore(quoteTokens, candidate.tokens);
+      if (
+        normalizedQuote.length >= 16 &&
+        (candidate.normalized.includes(normalizedQuote) || normalizedQuote.includes(candidate.normalized))
+      ) {
+        score = Math.max(score, 0.9);
+      }
+
+      if (!bestMatch || score > bestMatch.score) {
+        bestMatch = { score, segment: candidate.segment };
+      }
+    }
+
+    if (!bestMatch || bestMatch.score < 0.34) {
+      continue;
+    }
+
+    const midpoint =
+      bestMatch.segment.startTime +
+      Math.max(0, (bestMatch.segment.endTime - bestMatch.segment.startTime) / 2);
+    hints.push({
+      timestamp: Math.max(0, midpoint),
+      reason: 'AI-highlighted context',
+      confidence: Math.min(0.98, 0.58 + bestMatch.score * 0.35),
+    });
+  }
+
+  if (hints.length === 0) {
+    return [];
+  }
+
+  const sorted = hints.sort((a, b) => a.timestamp - b.timestamp);
+  const deduped: KeyMoment[] = [];
+  for (const hint of sorted) {
+    const previous = deduped[deduped.length - 1];
+    if (!previous || Math.abs(previous.timestamp - hint.timestamp) >= 1.0) {
+      deduped.push(hint);
+      continue;
+    }
+    if (hint.confidence > previous.confidence) {
+      deduped[deduped.length - 1] = hint;
+    }
+  }
+
+  return deduped.slice(0, 12);
+}
+
+// =============================================================================
+// Report Patching
+// =============================================================================
+
+/**
+ * Append extracted video frames to the markdown report.
+ * Verifies each frame path exists before linking to avoid broken images.
+ */
+export async function appendExtractedFramesToReport(
+  markdownPath: string,
+  extractedFrames: Array<{ path: string; timestamp: number; reason: string }>
+): Promise<void> {
+  if (!extractedFrames.length) {
+    return;
+  }
+
+  const verifiedFrames: Array<{ path: string; timestamp: number; reason: string }> = [];
+  for (const frame of extractedFrames) {
+    try {
+      await fs.access(frame.path);
+      verifiedFrames.push(frame);
+    } catch {
+      // Skip stale frame references so markdown never links missing files.
+    }
+  }
+  if (!verifiedFrames.length) {
+    return;
+  }
+
+  let markdown = await fs.readFile(markdownPath, 'utf-8');
+  if (markdown.includes('## Auto-Extracted Screenshots')) {
+    return;
+  }
+
+  const lines = verifiedFrames
+    .slice()
+    .sort((a, b) => a.timestamp - b.timestamp)
+    .map((frame, index) => {
+      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';
+      return `### [${timestamp}] ${reason}\n\n![${reason}](./screenshots/${filename})`;
+    })
+    .join('\n\n');
+
+  markdown += `\n## Auto-Extracted Screenshots\n\n${lines}\n`;
+
+  // Keep report header/session info counts aligned with the post-processed frame output.
+  const screenshotCount = verifiedFrames.length;
+  markdown = markdown.replace(
+    /(\|\s*Duration:\s*[^|]+\|\s*)\d+\s+screenshots(\s*\|\s*\d+\s+items identified\s*\n)/,
+    `$1${screenshotCount} screenshots$2`
+  );
+  markdown = markdown.replace(
+    /(-\s*\*\*Screenshots:\*\*\s*)\d+/,
+    `$1${screenshotCount}`
+  );
+
+  await fs.writeFile(markdownPath, markdown, 'utf-8');
+}
+
+/**
+ * Sync extracted frame count into session metadata.json.
+ */
+export async function syncExtractedFrameMetadata(
+  sessionDir: string,
+  screenshotCount: number
+): Promise<void> {
+  const metadataPath = join(sessionDir, 'metadata.json');
+  try {
+    const raw = await fs.readFile(metadataPath, 'utf-8');
+    const metadata = JSON.parse(raw) as { screenshotCount?: number };
+    metadata.screenshotCount = Math.max(
+      Number.isFinite(metadata.screenshotCount) ? Number(metadata.screenshotCount) : 0,
+      screenshotCount
+    );
+    await fs.writeFile(metadataPath, JSON.stringify(metadata, null, 2), 'utf-8');
+  } catch (error) {
+    console.warn('[Main] Failed to sync extracted frame metadata:', error);
+  }
+}
+
+/**
+ * Sync extracted frame count into feedback-summary.md.
+ */
+export async function syncExtractedFrameSummary(
+  sessionDir: string,
+  screenshotCount: number
+): Promise<void> {
+  const summaryPath = join(sessionDir, 'feedback-summary.md');
+  try {
+    const raw = await fs.readFile(summaryPath, 'utf-8');
+    const updated = raw.replace(/(\*\*Screenshots:\*\*\s*)\d+/, `$1${screenshotCount}`);
+    if (updated !== raw) {
+      await fs.writeFile(summaryPath, updated, 'utf-8');
+    }
+  } catch (error) {
+    console.warn('[Main] Failed to sync extracted frame summary:', error);
+  }
+}
+
+/**
+ * Write a processing trace JSON file for debugging/diagnostics.
+ */
+export async function writeProcessingTrace(
+  sessionDir: string,
+  trace: {
+    reportPath: string;
+    totalMs: number;
+    aiMs: number;
+    saveMs: number;
+    postProcessMs: number;
+    audioBytes: number;
+    recordingBytes: number;
+    transcriptBufferEvents: number;
+    providedTranscriptSegments: number;
+    aiFrameHints: number;
+    postProcessSegments: number;
+    extractedFrames: number;
+    aiTier: 'free' | 'byok' | 'premium';
+    aiEnhanced: boolean;
+    aiFallbackReason?: string;
+    completedAt: string;
+  }
+): Promise<void> {
+  const tracePath = join(sessionDir, 'processing-trace.json');
+  await fs.writeFile(tracePath, JSON.stringify(trace, null, 2), 'utf-8');
+}

package/src/main/output/index.ts

@@ -0,0 +1,186 @@
+/**
+ * Output Module
+ *
+ * Handles:
+ * - Markdown document generation
+ * - Screenshot embedding (base64)
+ * - Timestamp formatting
+ * - Clipboard integration
+ * - File output management
+ */
+
+import type { FeedbackSession, OutputDocument, Screenshot, TranscriptionSegment } from '../../shared/types';
+import { clipboardService, type ClipboardService } from './ClipboardService';
+import type { Session } from '../SessionController';
+
+export class OutputManager {
+  private clipboard: ClipboardService;
+
+  constructor() {
+    this.clipboard = clipboardService;
+  }
+  /**
+   * Generate a Markdown document from a feedback session
+   */
+  generateMarkdown(session: FeedbackSession): OutputDocument {
+    const { id, screenshots, transcription, startedAt, endedAt } = session;
+
+    // Build markdown content
+    let markdown = '# Feedback Session\n\n';
+
+    // Session metadata
+    markdown += `**Session ID:** ${id}\n`;
+    markdown += `**Started:** ${new Date(startedAt).toISOString()}\n`;
+    if (endedAt) {
+      markdown += `**Ended:** ${new Date(endedAt).toISOString()}\n`;
+      markdown += `**Duration:** ${Math.round((endedAt - startedAt) / 1000)}s\n`;
+    }
+    markdown += '\n---\n\n';
+
+    // Interleave transcription and screenshots by timestamp
+    const timeline = this.buildTimeline(transcription, screenshots);
+
+    for (const item of timeline) {
+      if (item.type === 'text') {
+        markdown += `${item.content}\n\n`;
+      } else if (item.type === 'screenshot') {
+        markdown += `![Screenshot at ${this.formatTimestamp(item.timestamp)}](${item.content})\n\n`;
+      }
+    }
+
+    return {
+      sessionId: id,
+      generatedAt: Date.now(),
+      markdown,
+      screenshots,
+    };
+  }
+
+  /**
+   * Build a timeline interleaving transcription and screenshots
+   */
+  private buildTimeline(
+    transcription: TranscriptionSegment[],
+    screenshots: Screenshot[]
+  ): Array<{ type: 'text' | 'screenshot'; content: string; timestamp: number }> {
+    const timeline: Array<{ type: 'text' | 'screenshot'; content: string; timestamp: number }> = [];
+
+    // Add transcription segments
+    for (const segment of transcription) {
+      timeline.push({
+        type: 'text',
+        content: segment.text,
+        timestamp: segment.startTime,
+      });
+    }
+
+    // Add screenshots
+    for (const screenshot of screenshots) {
+      timeline.push({
+        type: 'screenshot',
+        content: screenshot.base64 || screenshot.imagePath,
+        timestamp: screenshot.timestamp,
+      });
+    }
+
+    // Sort by timestamp
+    timeline.sort((a, b) => a.timestamp - b.timestamp);
+
+    return timeline;
+  }
+
+  /**
+   * Format a timestamp as a readable string
+   */
+  private formatTimestamp(timestamp: number): string {
+    const date = new Date(timestamp);
+    return date.toLocaleTimeString('en-US', {
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+    });
+  }
+
+  /**
+   * Copy a summary of the session to clipboard with notification
+   */
+  async copySessionSummary(
+    session: Session,
+    reportPath?: string
+  ): Promise<boolean> {
+    const summary = this.clipboard.generateClipboardSummary(session, {
+      mode: 'compact',
+      maxLength: 1500,
+      includeReportPath: !!reportPath,
+      reportPath,
+    });
+
+    return this.clipboard.copyWithNotification(
+      summary,
+      'Feedback Captured!'
+    );
+  }
+
+  /**
+   * Copy custom content to clipboard with notification
+   */
+  async copyToClipboard(content: string, title?: string): Promise<boolean> {
+    return this.clipboard.copyWithNotification(content, title);
+  }
+
+  /**
+   * Get the clipboard service for direct access
+   */
+  getClipboardService(): ClipboardService {
+    return this.clipboard;
+  }
+}
+
+// Singleton instance
+export const outputManager = new OutputManager();
+
+export default OutputManager;
+
+// Re-export clipboard service types and instance
+export { clipboardService, type ClipboardService, type SummaryOptions } from './ClipboardService';
+
+// Re-export file manager types and instance
+export { FileManager, fileManager, type SaveResult, type MarkdownDocument } from './FileManager';
+
+// Re-export new llms.txt-inspired markdown generator
+export {
+  markdownGenerator,
+  MarkdownGenerator,
+  adaptFeedbackSession,
+  type IMarkdownGenerator,
+  type Session as MarkdownSession,
+  type FeedbackItem,
+  type FeedbackCategory,
+  type FeedbackSeverity,
+  type GenerateOptions,
+  type MarkdownDocument as EnhancedMarkdownDocument,
+  type SessionMetadata,
+} from './MarkdownGenerator';
+
+// Re-export session adapter for type conversion
+export {
+  adaptSessionForMarkdown,
+  generateDocumentForFileManager,
+  generateClipboardSummary,
+} from './sessionAdapter';
+
+// Re-export export service for multi-format export
+export {
+  exportService,
+  ExportService,
+  generateHtmlDocument,
+  type ExportFormat,
+  type ExportOptions,
+  type ExportResult,
+  type PdfOptions,
+  type HtmlOptions,
+  type JsonOptions,
+  type MarkdownOptions,
+  type JsonExportSchema,
+  type HtmlExportOptions,
+} from './ExportService';

package/src/main/output/sessionAdapter.ts

@@ -0,0 +1,207 @@
+/**
+ * Session Adapter
+ *
+ * Converts between different session types used across the codebase.
+ * This is needed because:
+ * - SessionController uses its own Session/FeedbackItem types
+ * - MarkdownGenerator uses enhanced Session/FeedbackItem types
+ * - FileManager uses its own MarkdownDocument type
+ */
+
+import type { Session as ControllerSession, FeedbackItem as ControllerFeedbackItem } from '../SessionController';
+import type { TranscriptEvent } from '../transcription/types';
+import type {
+  Session as MarkdownSession,
+  FeedbackItem as MarkdownFeedbackItem,
+  FeedbackCategory,
+  FeedbackSeverity,
+  GenerateOptions,
+} from './MarkdownGenerator';
+import type { MarkdownDocument as FileManagerDocument } from './FileManager';
+import { markdownGenerator } from './MarkdownGenerator';
+import { feedbackAnalyzer } from '../analysis';
+
+const NO_TRANSCRIPTION_PLACEHOLDER =
+  '[Narration was recorded but not transcribed. Add an OpenAI API key, or download a Tiny Whisper model for local fallback.]';
+
+/**
+ * Map analyzer category labels to markdown report labels
+ */
+function mapCategory(category: ReturnType<typeof feedbackAnalyzer.analyze>['category']): FeedbackCategory {
+  switch (category) {
+    case 'bug':
+      return 'Bug';
+    case 'ux-issue':
+      return 'UX Issue';
+    case 'suggestion':
+      return 'Suggestion';
+    case 'performance':
+      return 'Performance';
+    case 'question':
+      return 'Question';
+    default:
+      return 'General';
+  }
+}
+
+function mapSeverity(severity: ReturnType<typeof feedbackAnalyzer.analyze>['severity']): FeedbackSeverity {
+  switch (severity) {
+    case 'critical':
+      return 'Critical';
+    case 'high':
+      return 'High';
+    case 'medium':
+      return 'Medium';
+    default:
+      return 'Low';
+  }
+}
+
+/**
+ * Convert SessionController.FeedbackItem to MarkdownGenerator.FeedbackItem
+ */
+function adaptFeedbackItem(item: ControllerFeedbackItem, index: number): MarkdownFeedbackItem {
+  const transcription = item.text.trim() || NO_TRANSCRIPTION_PLACEHOLDER;
+  const analysis = feedbackAnalyzer.analyze(transcription);
+
+  return {
+    id: item.id || `item-${index + 1}`,
+    transcription,
+    timestamp: item.timestamp,
+    category: mapCategory(analysis.category),
+    severity: mapSeverity(analysis.severity),
+    title: analysis.suggestedTitle,
+    keywords: analysis.keywords,
+    screenshots: item.screenshot ? [{
+      id: item.screenshot.id,
+      timestamp: item.screenshot.timestamp,
+      width: item.screenshot.width,
+      height: item.screenshot.height,
+      imagePath: '', // Filled in by FileManager when saving
+      base64: item.screenshot.base64,
+    }] : [],
+  };
+}
+
+function buildTranscriptOnlyItems(session: ControllerSession): MarkdownFeedbackItem[] {
+  const finalTranscripts = session.transcriptBuffer
+    .filter((event) => event.isFinal && event.text.trim().length > 0)
+    .sort((a, b) => a.timestamp - b.timestamp);
+
+  const usableTranscripts = finalTranscripts.length > 0
+    ? finalTranscripts
+    : session.transcriptBuffer
+        .filter((event) => event.text.trim().length > 0)
+        .sort((a, b) => a.timestamp - b.timestamp);
+
+  if (usableTranscripts.length === 0) {
+    return [];
+  }
+
+  const grouped: Array<{ timestampMs: number; transcripts: TranscriptEvent[] }> = [];
+  const GROUP_GAP_MS = 2200;
+
+  for (const transcript of usableTranscripts) {
+    const timestampMs = Math.round(transcript.timestamp * 1000);
+    const previousGroup = grouped[grouped.length - 1];
+
+    if (!previousGroup || timestampMs - previousGroup.timestampMs > GROUP_GAP_MS) {
+      grouped.push({
+        timestampMs,
+        transcripts: [transcript],
+      });
+      continue;
+    }
+
+    previousGroup.transcripts.push(transcript);
+    previousGroup.timestampMs = timestampMs;
+  }
+
+  return grouped.map((group, index) => {
+    const transcription = group.transcripts
+      .map((transcript) => transcript.text.trim())
+      .join(' ')
+      .replace(/\s+/g, ' ')
+      .trim();
+
+    const analysis = feedbackAnalyzer.analyze(transcription);
+
+    return {
+      id: `transcript-only-${index + 1}`,
+      transcription,
+      timestamp: group.timestampMs,
+      category: mapCategory(analysis.category),
+      severity: mapSeverity(analysis.severity),
+      title: analysis.suggestedTitle,
+      keywords: analysis.keywords,
+      screenshots: [],
+    };
+  });
+}
+
+/**
+ * Convert SessionController.Session to MarkdownGenerator.Session
+ */
+export function adaptSessionForMarkdown(session: ControllerSession): MarkdownSession {
+  const adaptedFromScreenshots = session.feedbackItems.map((item, index) => adaptFeedbackItem(item, index));
+  const transcriptOnlyItems = buildTranscriptOnlyItems(session);
+  const hasNarratedScreenshotItems = adaptedFromScreenshots.some(
+    (item) => item.transcription !== NO_TRANSCRIPTION_PLACEHOLDER
+  );
+
+  const adaptedItems =
+    adaptedFromScreenshots.length === 0
+      ? transcriptOnlyItems
+      : hasNarratedScreenshotItems || transcriptOnlyItems.length === 0
+        ? adaptedFromScreenshots
+        : [...adaptedFromScreenshots, ...transcriptOnlyItems];
+
+  return {
+    id: session.id,
+    startTime: session.startTime,
+    endTime: session.endTime,
+    feedbackItems: adaptedItems,
+    metadata: {
+      os: process.platform,
+      sourceName: session.metadata?.sourceName || 'Screen',
+      sourceType: session.sourceId.startsWith('screen') ? 'screen' : 'window',
+    },
+  };
+}
+
+/**
+ * Generate a FileManager-compatible MarkdownDocument from a SessionController session
+ */
+export function generateDocumentForFileManager(
+  session: ControllerSession,
+  options?: Partial<GenerateOptions>
+): FileManagerDocument {
+  const adaptedSession = adaptSessionForMarkdown(session);
+  const fullOptions: GenerateOptions = {
+    projectName: options?.projectName || session.metadata?.sourceName || 'Feedback Session',
+    screenshotDir: options?.screenshotDir || './screenshots',
+  };
+
+  const generatedDoc = markdownGenerator.generateFullDocument(adaptedSession, fullOptions);
+
+  // Convert MarkdownGenerator.MarkdownDocument to FileManager.MarkdownDocument
+  return {
+    content: generatedDoc.content,
+    metadata: {
+      itemCount: generatedDoc.metadata.itemCount,
+      screenshotCount: generatedDoc.metadata.screenshotCount,
+      types: Object.keys(generatedDoc.metadata.types),
+    },
+  };
+}
+
+/**
+ * Generate clipboard summary from a SessionController session
+ */
+export function generateClipboardSummary(session: ControllerSession, projectName?: string): string {
+  const adaptedSession = adaptSessionForMarkdown(session);
+  return markdownGenerator.generateClipboardSummary(
+    adaptedSession,
+    projectName || session.metadata?.sourceName || 'Feedback Session'
+  );
+}