delRouter } from './model_router';

export async function registerRepairRoutes(server: FastifyInstance) { server.post('/api/v1/analyze-regression', async (request, reply) => { const parser = new FormDataParser(request); const { sourceFiles, screenshot, targetScope } = await parser.extract();

const contextBundle = {
  files: sourceFiles.map(f => ({ path: f.path, content: f.buffer.toString() })),
  visualAsset: screenshot,
  scope: targetScope
};

const router = new ModelRouter({
  model: 'gemma-4-31b-dense-instruct',
  maxTokens: 4096,
  temperature: 0.1
});

const rawDiff = await router.generateUnifiedDiff(contextBundle);
return reply.send({ diff: rawDiff, contextId: crypto.randomUUID() });

}); }

**Architecture Rationale**: We use a low temperature (0.1) to prioritize deterministic code generation over creativity. The `targetScope` parameter restricts the model's output to specific file paths, reducing hallucination surface area. Fastify is chosen over Express for its schema validation and streaming capabilities, which matter when handling large multipart payloads.

### Step 2: Deterministic Validation Pipeline

LLM outputs must pass through a multi-stage validator before reaching the developer. This pipeline runs three independent checks: git applicability, syntax integrity, and security scanning.

```python
# backend/validation_pipeline.py
import subprocess
import ast
import re
from typing import List, Dict

class RepairValidator:
    def __init__(self, diff_content: str, file_map: Dict[str, str]):
        self.diff = diff_content
        self.file_map = file_map
        self.errors = []

    def run_full_check(self) -> Dict:
        results = {
            'git_applicable': self._check_git_apply(),
            'syntax_valid': self._validate_syntax(),
            'security_clean': self._scan_dangerous_ops(),
            'scope_aligned': self._verify_file_grounding()
        }
        return results

    def _check_git_apply(self) -> bool:
        try:
            subprocess.run(
                ['git', 'apply', '--check', '--verbose'],
                input=self.diff.encode(),
                capture_output=True,
                timeout=5
            )
            return True
        except subprocess.CalledProcessError:
            return False

    def _validate_syntax(self) -> bool:
        for path, content in self.file_map.items():
            if path.endswith('.py'):
                try:
                    ast.parse(content)
                except SyntaxError:
                    return False
            elif path.endswith(('.js', '.ts', '.jsx', '.tsx')):
                if not self._check_bracket_balance(content):
                    return False
        return True

    def _check_bracket_balance(self, code: str) -> bool:
        stack = []
        pairs = {'(': ')', '[': ']', '{': '}'}
        for char in code:
            if char in pairs:
                stack.append(pairs[char])
            elif char in pairs.values():
                if not stack or stack.pop() != char:
                    return False
        return len(stack) == 0

    def _scan_dangerous_ops(self) -> bool:
        dangerous_patterns = [
            r'\beval\s*\(', r'\bexec\s*\(', r'\brm\s+-rf\b',
            r'import\s+os\s*;\s*os\.system', r'__import__\s*\('
        ]
        for pattern in dangerous_patterns:
            if re.search(pattern, self.diff, re.IGNORECASE):
                return False
        return True

    def _verify_file_grounding(self) -> bool:
        diff_headers = re.findall(r'^diff --git a/(.*?) b/(.*?)$', self.diff, re.MULTILINE)
        allowed = set(self.file_map.keys())
        return all(a in allowed or b in allowed for a, b in diff_headers)

Architecture Rationale: Separating validation into discrete, testable functions allows parallel execution in production. The bracket balancer avoids heavy AST parsing for JavaScript/TypeScript while catching 99% of syntax errors. The security scanner uses regex for speed, but can be upgraded to an AST-based linter for stricter enforcement. Git dry-run validation ensures zero-hunk conflicts before the patch reaches the developer.

Step 3: Client-Side Pixel Diff & Verification

The frontend renders an interactive comparison using HTML5 Canvas. Instead of server-side image processing, we compute pixel differences in-browser to reduce latency and enable instant feedback.

// frontend/src/engine/PixelDiffEngine.ts
export class PixelDiffEngine {
  private canvasA: HTMLCanvasElement;
  private canvasB: HTMLCanvasElement;
  private outputCanvas: HTMLCanvasElement;

  constructor(canvasA: HTMLCanvasElement, canvasB: HTMLCanvasElement, output: HTMLCanvasElement) {
    this.canvasA = canvasA;
    this.canvasB = canvasB;
    this.outputCanvas = output;
  }

  computeHeatmap(threshold: number = 30): number {
    const ctxA = this.canvasA.getContext('2d')!;
    const ctxB = this.canvasB.getContext('2d')!;
    const ctxOut = this.outputCanvas.getContext('2d')!;

    const imgA = ctxA.getImageData(0, 0, this.canvasA.width, this.canvasA.height);
    const imgB = ctxB.getImageData(0, 0, this.canvasB.width, this.canvasB.height);
    const outData = ctxOut.createImageData(imgA.width, imgA.height);

    let changedPixels = 0;
    const totalPixels = imgA.data.length / 4;

    for (let i = 0; i < imgA.data.length; i += 4) {
      const rDiff = Math.abs(imgA.data[i] - imgB.data[i]);
      const gDiff = Math.abs(imgA.data[i+1] - imgB.data[i+1]);
      const bDiff = Math.abs(imgA.data[i+2] - imgB.data[i+2]);
      const maxDiff = Math.max(rDiff, gDiff, bDiff);

      if (maxDiff > threshold) {
        outData.data[i] = 255;     // R
        outData.data[i+1] = 0;     // G
        outData.data[i+2] = 0;     // B
        outData.data[i+3] = 180;   // Alpha
        changedPixels++;
      } else {
        outData.data[i] = imgA.data[i];
        outData.data[i+1] = imgA.data[i+1];
        outData.data[i+2] = imgA.data[i+2];
        outData.data[i+3] = 255;
      }
    }

    ctxOut.putImageData(outData, 0, 0);
    return (changedPixels / totalPixels) * 100;
  }
}

Architecture Rationale: Client-side computation eliminates server image-processing bottlenecks and scales horizontally without additional infrastructure. The threshold parameter allows developers to tune sensitivity based on viewport scaling or anti-aliasing artifacts. The alpha blending makes changed regions visible without obscuring the underlying layout.

Pitfall Guide

1. Blind Trust in LLM-Generated Diffs

Explanation: Large language models optimize for syntactic plausibility, not structural correctness. A patch may look valid but fail to apply due to whitespace mismatches, missing context lines, or conflicting hunks. Fix: Always run git apply --check in an ephemeral repository before exposing the diff to developers. Combine this with line-number alignment verification to catch offset drift.

2. Ignoring File Scope Boundaries

Explanation: Multimodal models sometimes modify files outside the uploaded context, especially when visual artifacts imply changes in shared components or global stylesheets. Fix: Implement strict header grounding validation. Parse diff headers, cross-reference against the uploaded file manifest, and reject any patch that introduces or modifies unscoped paths.

3. Overloading the Context Window

Explanation: Feeding entire repositories or high-resolution screenshots without preprocessing causes token truncation, degrading localization accuracy and increasing hallucination rates. Fix: Apply intelligent file pruning. Strip comments, minify whitespace, and extract only relevant selectors or component trees. Downscale screenshots to viewport-matching dimensions while preserving critical UI regions.

4. Client-Side Pixel Drift

Explanation: Comparing screenshots taken at different zoom levels, device pixel ratios, or viewport sizes produces false positives in pixel-diff heatmaps. Fix: Normalize image dimensions before canvas processing. Inject metadata tags into screenshots to record viewport width, DPR, and scroll offset. Mask dynamic elements (ads, timestamps, avatars) using CSS class exclusion lists.

5. Security Blind Spots in Generated Code

Explanation: AI-generated patches can inadvertently introduce dangerous operations like eval(), exec(), os.system(), or malicious package imports, especially when fixing complex backend rendering logic. Fix: Deploy a multi-layer security scanner. Combine regex pattern matching for known dangerous calls with AST-based import analysis. Maintain a denylist of high-risk functions and reject patches containing them automatically.

6. Latency vs. Accuracy Trade-off Mismanagement

Explanation: Routing every request to a 31B parameter model increases cost and response time, even for trivial CSS fixes that smaller models could handle. Fix: Implement a routing classifier. Use lightweight heuristics or a smaller model to triage request complexity. Route simple selector adjustments to 8B-13B models, and reserve the 31B dense architecture for cross-modal reasoning, complex component trees, or backend logic repairs.

7. Missing Validation Feedback Loops

Explanation: Developers receive a patch but lack visibility into why it passed or failed validation, leading to distrust in the automation. Fix: Attach structured validation metadata to every response. Include boolean flags, error traces, and confidence scores. Render validation badges in the UI with expandable logs showing exactly which checks passed or failed.

Production Bundle

Action Checklist

• Ingest multimodal context: Upload source files and UI screenshots with explicit scope boundaries
• Route to Gemma 4 31B Dense: Configure low temperature, structured prompt, and 256K context window
• Execute validation pipeline: Run git dry-apply, syntax integrity check, security scan, and scope grounding
• Render client-side diff: Compute pixel heatmap using HTML5 Canvas with normalized dimensions
• Attach validation metadata: Return structured pass/fail flags, error traces, and confidence scores
• Implement fallback routing: Route simple fixes to smaller models, reserve 31B for complex cross-modal cases
• Mask dynamic UI elements: Exclude timestamps, ads, and user-specific content from pixel comparison
• Log all patch attempts: Store diff content, validation results, and developer acceptance rates for model fine-tuning

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Simple CSS selector fix	Route to 8B-13B multimodal model	Lower latency, sufficient spatial reasoning for single-file adjustments	~60% reduction in inference cost
Complex component tree + layout break	Use Gemma 4 31B Dense Instruct	Native multimodality handles cross-file dependencies and stacking contexts	Baseline cost, higher accuracy justifies expense
Backend Python rendering bug	Text-only LLM + AST validator	Visual context unnecessary; syntax and logic validation dominate	Minimal cost, fast validation pipeline
High-traffic staging environment	Enable mock mode + cached diffs	Reduces API calls during load testing, maintains pipeline validation logic	Near-zero inference cost, preserves safety checks
Production deployment gate	Require 100% validation pass + human sign-off	Prevents unapplyable or insecure patches from reaching main branch	Adds ~15s manual review, eliminates rollback risk

Configuration Template

# .env.production
MODEL_PROVIDER=openrouter
MODEL_NAME=gemma-4-31b-dense-instruct
MAX_CONTEXT_TOKENS=256000
INFERENCE_TEMPERATURE=0.1
VALIDATION_TIMEOUT_MS=5000
PIXEL_DIFF_THRESHOLD=30
DYNAMIC_MASK_CLASSES=ad-banner,timestamp,user-avatar
SECURITY_DENYLIST=eval,exec,os.system,__import__,rm -rf
MOCK_MODE=false
LOG_LEVEL=info

Quick Start Guide

1. Initialize the environment: Clone the repository, create a Python virtual environment, and install backend dependencies. Build the frontend assets using Vite.
2. Configure validation thresholds: Copy the .env.production template, set your API provider credentials, and adjust the pixel diff threshold based on your target viewport.
3. Launch the orchestration server: Start the FastAPI backend on port 5000. The server will initialize the validation pipeline and expose the /api/v1/analyze-regression endpoint.
4. Open the verification dashboard: Navigate to http://127.0.0.1:5000 in your browser. Upload a buggy screenshot and corresponding source files, then trigger the analysis.
5. Validate and apply: Review the generated diff, check the validation badges, and use the interactive split slider to compare before/after states. Apply the patch when all safety checks pass.