@reftrixmcp/mcp-server 0.1.7

package/dist/services/visual-extractor/pixel-theme-detector.service.js

@@ -0,0 +1,358 @@
+"use strict";
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIGHT_THRESHOLD = exports.DARK_THRESHOLD = void 0;
+exports.createPixelThemeDetectorService = createPixelThemeDetectorService;
+/**
+ * Pixel Theme Detector Service
+ *
+ * Detects light/dark/mixed themes from screenshot images using
+ * WCAG-compliant relative luminance calculation on actual pixel data.
+ *
+ * This service provides more accurate theme detection than class-name based
+ * inference by directly analyzing the rendered pixel values.
+ *
+ * Key Features:
+ * - WCAG 2.1 compliant relative luminance calculation
+ * - Region-based analysis (top/middle/bottom)
+ * - Gamma-corrected sRGB processing
+ * - Dominant color extraction
+ *
+ * Thresholds:
+ * - Dark: luminance < 0.3
+ * - Light: luminance > 0.7
+ * - Mixed: 0.3 <= luminance <= 0.7
+ *
+ * Security features:
+ * - Input size validation (5MB max)
+ * - Processing timeout (30s default)
+ * - Image downscaling for performance
+ *
+ * @module services/visual-extractor/pixel-theme-detector.service
+ */
+const logger_1 = require("../../utils/logger");
+const sharp_1 = __importDefault(require("sharp"));
+const image_utils_1 = require("./image-utils");
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Luminance threshold for dark theme classification
+ * Below this value, the image is considered dark
+ */
+exports.DARK_THRESHOLD = 0.3;
+/**
+ * Luminance threshold for light theme classification
+ * Above this value, the image is considered light
+ */
+exports.LIGHT_THRESHOLD = 0.7;
+/**
+ * Maximum dimension for processing
+ * Images larger than this will be downscaled
+ */
+const MAX_PROCESSING_DIMENSION = 400;
+/**
+ * Number of top colors to extract
+ */
+const MAX_DOMINANT_COLORS = 5;
+// ============================================================================
+// WCAG Luminance Calculation
+// ============================================================================
+/**
+ * Convert sRGB color component to linear RGB (gamma correction)
+ * WCAG 2.1 specification
+ *
+ * @param component - sRGB component (0-255)
+ * @returns Linear RGB value (0-1)
+ */
+function sRGBToLinear(component) {
+    const srgb = component / 255;
+    if (srgb <= 0.04045) {
+        return srgb / 12.92;
+    }
+    else {
+        return Math.pow((srgb + 0.055) / 1.055, 2.4);
+    }
+}
+/**
+ * Calculate WCAG 2.1 relative luminance for RGB values
+ * L = 0.2126 * R + 0.7152 * G + 0.0722 * B
+ *
+ * @param r - Red component (0-255)
+ * @param g - Green component (0-255)
+ * @param b - Blue component (0-255)
+ * @returns Relative luminance (0-1)
+ */
+function calculateRelativeLuminance(r, g, b) {
+    const rLinear = sRGBToLinear(r);
+    const gLinear = sRGBToLinear(g);
+    const bLinear = sRGBToLinear(b);
+    return 0.2126 * rLinear + 0.7152 * gLinear + 0.0722 * bLinear;
+}
+/**
+ * Classify a luminance value as light or dark
+ *
+ * @param luminance - Relative luminance (0-1)
+ * @returns 'light' if above 0.5, 'dark' otherwise
+ */
+function classifyRegionTheme(luminance) {
+    // Use 0.5 as the boundary for region classification
+    // This is different from the overall thresholds to detect
+    // clearly light/dark regions within mixed images
+    return luminance > 0.5 ? "light" : "dark";
+}
+/**
+ * Classify overall theme based on average luminance
+ *
+ * @param luminance - Average luminance (0-1)
+ * @returns Theme classification
+ */
+function classifyOverallTheme(luminance) {
+    if (luminance < exports.DARK_THRESHOLD) {
+        return "dark";
+    }
+    else if (luminance > exports.LIGHT_THRESHOLD) {
+        return "light";
+    }
+    else {
+        return "mixed";
+    }
+}
+/**
+ * Calculate confidence score based on luminance and region agreement
+ *
+ * @param luminance - Average luminance
+ * @param theme - Detected theme
+ * @param regionAgreement - Number of regions that agree (0-3)
+ * @returns Confidence score (0-1)
+ */
+function calculateConfidence(luminance, theme, regionAgreement) {
+    let baseConfidence;
+    if (theme === "dark") {
+        // Confidence increases as luminance decreases from threshold
+        baseConfidence = Math.min(1, (exports.DARK_THRESHOLD - luminance) / exports.DARK_THRESHOLD + 0.5);
+    }
+    else if (theme === "light") {
+        // Confidence increases as luminance increases from threshold
+        baseConfidence = Math.min(1, (luminance - exports.LIGHT_THRESHOLD) / (1 - exports.LIGHT_THRESHOLD) + 0.5);
+    }
+    else {
+        // Mixed theme - confidence based on distance from both thresholds
+        const midpoint = (exports.DARK_THRESHOLD + exports.LIGHT_THRESHOLD) / 2;
+        const distanceFromMid = Math.abs(luminance - midpoint);
+        const maxDistance = (exports.LIGHT_THRESHOLD - exports.DARK_THRESHOLD) / 2;
+        baseConfidence = 0.5 + (1 - distanceFromMid / maxDistance) * 0.3;
+    }
+    // Adjust based on region agreement
+    const regionBonus = regionAgreement === 3 ? 0.1 : regionAgreement === 2 ? 0.05 : -0.1;
+    return Math.min(1, Math.max(0, baseConfidence + regionBonus));
+}
+/**
+ * Extract dominant colors from pixel data using simple quantization
+ *
+ * @param data - Raw RGB pixel data
+ * @param width - Image width
+ * @param height - Image height
+ * @returns Array of dominant colors in HEX format
+ */
+function extractDominantColors(data, width, height) {
+    // Use a simple bucketing approach for fast color extraction
+    const bucketSize = 32; // Reduce color space to 8 values per channel
+    const buckets = new Map();
+    const channels = 3;
+    const totalPixels = width * height;
+    const sampleStep = Math.max(1, Math.floor(totalPixels / 10000)); // Sample up to 10000 pixels
+    for (let i = 0; i < data.length; i += channels * sampleStep) {
+        const r = data[i] ?? 0;
+        const g = data[i + 1] ?? 0;
+        const b = data[i + 2] ?? 0;
+        // Quantize to buckets
+        const qr = Math.floor(r / bucketSize) * bucketSize + Math.floor(bucketSize / 2);
+        const qg = Math.floor(g / bucketSize) * bucketSize + Math.floor(bucketSize / 2);
+        const qb = Math.floor(b / bucketSize) * bucketSize + Math.floor(bucketSize / 2);
+        const key = `${qr},${qg},${qb}`;
+        const existing = buckets.get(key);
+        if (existing) {
+            existing.count++;
+        }
+        else {
+            buckets.set(key, { r: qr, g: qg, b: qb, count: 1 });
+        }
+    }
+    // Sort by count and return top colors
+    const sortedBuckets = Array.from(buckets.values())
+        .sort((a, b) => b.count - a.count)
+        .slice(0, MAX_DOMINANT_COLORS);
+    return sortedBuckets.map((bucket) => (0, image_utils_1.rgbToHex)(bucket.r, bucket.g, bucket.b));
+}
+// ============================================================================
+// Region Analysis
+// ============================================================================
+/**
+ * Calculate average luminance for a region of the image
+ *
+ * @param data - Raw RGB pixel data
+ * @param width - Image width
+ * @param startY - Start row (inclusive)
+ * @param endY - End row (exclusive)
+ * @returns Average luminance for the region
+ */
+function calculateRegionLuminance(data, width, startY, endY) {
+    const channels = 3;
+    let totalLuminance = 0;
+    let pixelCount = 0;
+    for (let y = startY; y < endY; y++) {
+        for (let x = 0; x < width; x++) {
+            const pixelIndex = (y * width + x) * channels;
+            const r = data[pixelIndex] ?? 0;
+            const g = data[pixelIndex + 1] ?? 0;
+            const b = data[pixelIndex + 2] ?? 0;
+            totalLuminance += calculateRelativeLuminance(r, g, b);
+            pixelCount++;
+        }
+    }
+    return pixelCount > 0 ? totalLuminance / pixelCount : 0;
+}
+/**
+ * Analyze three regions of the image (top/middle/bottom)
+ *
+ * @param data - Raw RGB pixel data
+ * @param width - Image width
+ * @param height - Image height
+ * @returns Region themes and luminances
+ */
+function analyzeRegions(data, width, height) {
+    const regionHeight = Math.floor(height / 3);
+    const topEnd = regionHeight;
+    const middleEnd = regionHeight * 2;
+    const topLuminance = calculateRegionLuminance(data, width, 0, topEnd);
+    const middleLuminance = calculateRegionLuminance(data, width, topEnd, middleEnd);
+    const bottomLuminance = calculateRegionLuminance(data, width, middleEnd, height);
+    return {
+        topLuminance,
+        middleLuminance,
+        bottomLuminance,
+        topTheme: classifyRegionTheme(topLuminance),
+        middleTheme: classifyRegionTheme(middleLuminance),
+        bottomTheme: classifyRegionTheme(bottomLuminance),
+    };
+}
+// ============================================================================
+// Service Implementation
+// ============================================================================
+/**
+ * Internal implementation of PixelThemeDetectorService
+ */
+class PixelThemeDetectorServiceImpl {
+    async detectTheme(image) {
+        // Parse and validate input with size check (5MB max)
+        const imageBuffer = (0, image_utils_1.parseAndValidateImageInput)(image);
+        (0, image_utils_1.logSecurityEvent)("PixelThemeDetector", "Processing image", {
+            size: imageBuffer.length,
+            sizeKB: Math.round(imageBuffer.length / 1024),
+        });
+        // Wrap processing with timeout (30s default)
+        return (0, image_utils_1.withTimeout)(this.detectThemeInternal(imageBuffer), image_utils_1.DEFAULT_PROCESSING_TIMEOUT);
+    }
+    async detectThemeInternal(imageBuffer) {
+        try {
+            // Load and process image with Sharp
+            const processedImage = (0, sharp_1.default)(imageBuffer);
+            const metadata = await processedImage.metadata();
+            if (!metadata.width || !metadata.height) {
+                throw new Error("Invalid image: unable to read dimensions");
+            }
+            // Calculate resize dimensions (preserve aspect ratio)
+            const scale = Math.min(1, MAX_PROCESSING_DIMENSION / Math.max(metadata.width, metadata.height));
+            const targetWidth = Math.round(metadata.width * scale);
+            const targetHeight = Math.round(metadata.height * scale);
+            // Resize and get raw RGB data
+            const { data, info } = await processedImage
+                .resize(targetWidth, targetHeight, { fit: "inside" })
+                .flatten({ background: { r: 255, g: 255, b: 255 } })
+                .raw()
+                .toBuffer({ resolveWithObject: true });
+            const width = info.width;
+            const height = info.height;
+            // Calculate average luminance for entire image
+            const averageLuminance = this.calculateAverageLuminance(data, width, height);
+            // Analyze regions
+            const regionAnalysis = analyzeRegions(data, width, height);
+            // Extract dominant colors
+            const dominantColors = extractDominantColors(data, width, height);
+            // Classify theme
+            const theme = classifyOverallTheme(averageLuminance);
+            // Calculate region agreement
+            const expectedTheme = theme === "mixed" ? "dark" : theme; // For mixed, check against dark
+            let regionAgreement = 0;
+            if (regionAnalysis.topTheme === expectedTheme)
+                regionAgreement++;
+            if (regionAnalysis.middleTheme === expectedTheme)
+                regionAgreement++;
+            if (regionAnalysis.bottomTheme === expectedTheme)
+                regionAgreement++;
+            // Calculate confidence
+            const confidence = calculateConfidence(averageLuminance, theme, regionAgreement);
+            const result = {
+                theme,
+                confidence,
+                averageLuminance,
+                dominantColors,
+                analysis: {
+                    topRegionTheme: regionAnalysis.topTheme,
+                    middleRegionTheme: regionAnalysis.middleTheme,
+                    bottomRegionTheme: regionAnalysis.bottomTheme,
+                },
+            };
+            logger_1.logger.debug("[PixelThemeDetector] Theme detection result:", {
+                theme: result.theme,
+                confidence: result.confidence.toFixed(3),
+                averageLuminance: result.averageLuminance.toFixed(4),
+                regions: {
+                    top: `${regionAnalysis.topTheme} (${regionAnalysis.topLuminance.toFixed(4)})`,
+                    middle: `${regionAnalysis.middleTheme} (${regionAnalysis.middleLuminance.toFixed(4)})`,
+                    bottom: `${regionAnalysis.bottomTheme} (${regionAnalysis.bottomLuminance.toFixed(4)})`,
+                },
+                dominantColors: result.dominantColors,
+            });
+            return result;
+        }
+        catch (error) {
+            throw (0, image_utils_1.wrapSharpError)(error);
+        }
+    }
+    /**
+     * Calculate average luminance for the entire image
+     */
+    calculateAverageLuminance(data, width, height) {
+        const channels = 3;
+        let totalLuminance = 0;
+        let pixelCount = 0;
+        // Sample pixels for performance (every nth pixel for large images)
+        const totalPixels = width * height;
+        const sampleStep = Math.max(1, Math.floor(totalPixels / 50000)); // Max 50000 samples
+        for (let i = 0; i < data.length; i += channels * sampleStep) {
+            const r = data[i] ?? 0;
+            const g = data[i + 1] ?? 0;
+            const b = data[i + 2] ?? 0;
+            totalLuminance += calculateRelativeLuminance(r, g, b);
+            pixelCount++;
+        }
+        return pixelCount > 0 ? totalLuminance / pixelCount : 0;
+    }
+}
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create a new PixelThemeDetectorService instance
+ * @returns PixelThemeDetectorService instance
+ */
+function createPixelThemeDetectorService() {
+    return new PixelThemeDetectorServiceImpl();
+}
+//# sourceMappingURL=pixel-theme-detector.service.js.map

package/dist/services/visual-extractor/pixel-theme-detector.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pixel-theme-detector.service.js","sourceRoot":"","sources":["../../../src/services/visual-extractor/pixel-theme-detector.service.ts"],"names":[],"mappings":"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"}

package/dist/services/visual-extractor/theme-detector.service.d.ts

@@ -0,0 +1,101 @@
+import type { ColorExtractionResult } from "./color-extractor.service";
+import type { ComputedStyleInfo } from "../page-ingest-adapter";
+import { type PixelThemeDetectionResult } from "./pixel-theme-detector.service";
+/**
+ * Result of theme detection from an image or color palette
+ */
+export interface ThemeDetectionResult {
+    /** Detected theme: light, dark, or mixed */
+    theme: "light" | "dark" | "mixed";
+    /** Confidence score (0-1) */
+    confidence: number;
+    /** Estimated background color in HEX format */
+    backgroundColor: string;
+    /** Estimated text color in HEX format */
+    textColor: string;
+    /** WCAG contrast ratio between background and text */
+    contrastRatio: number;
+    /** Luminance values */
+    luminance: {
+        /** Background relative luminance (0-1) */
+        background: number;
+        /** Foreground/text relative luminance (0-1) */
+        foreground: number;
+    };
+}
+/**
+ * Extended theme detection result with computed styles usage flag
+ */
+export interface ThemeDetectionResultWithComputedStyles extends ThemeDetectionResult {
+    /** Whether computed styles were used for detection (true if used, false if fallback to screenshot) */
+    computedStylesUsed: boolean;
+}
+/**
+ * Theme detector service interface
+ */
+export interface ThemeDetectorService {
+    /**
+     * Detect theme from an image
+     * @param image - Image as Buffer or Base64 string
+     * @returns Promise resolving to theme detection result
+     */
+    detectTheme(image: Buffer | string): Promise<ThemeDetectionResult>;
+    /**
+     * Detect theme from color extraction result
+     * @param colors - Color extraction result from ColorExtractorService
+     * @returns Theme detection result
+     */
+    detectThemeFromColors(colors: ColorExtractionResult): ThemeDetectionResult;
+    /**
+     * Detect theme using direct pixel analysis (WCAG-compliant luminance)
+     *
+     * This method provides more accurate theme detection than color palette
+     * extraction by directly analyzing pixel luminance values using WCAG 2.1
+     * gamma-corrected relative luminance calculation.
+     *
+     * Thresholds:
+     * - Dark: luminance < 0.3
+     * - Light: luminance > 0.7
+     * - Mixed: 0.3 <= luminance <= 0.7
+     *
+     * @param screenshot - Screenshot image as Buffer
+     * @returns Promise resolving to pixel-based theme detection result
+     */
+    detectThemeFromPixels(screenshot: Buffer): Promise<PixelThemeDetectionResult>;
+    /**
+     * Detect theme using computed styles from Playwright, with pixel-based fallback
+     *
+     * Detection priority:
+     * 1. Computed backgroundColor from Playwright (if available and non-transparent)
+     * 2. Pixel-based analysis (WCAG-compliant luminance from actual pixels)
+     *
+     * This method prioritizes computed backgroundColor values from actual rendered CSS,
+     * which is more accurate than screenshot-based detection for sites using CSS-in-JS
+     * or Tailwind CSS that apply styles at runtime.
+     *
+     * @param screenshot - Screenshot image as Buffer
+     * @param computedStyles - Computed styles from Playwright (optional)
+     * @returns Promise resolving to theme detection result with computedStylesUsed flag
+     */
+    detectThemeWithComputedStyles(screenshot: Buffer, computedStyles?: ComputedStyleInfo[]): Promise<ThemeDetectionResultWithComputedStyles>;
+    /**
+     * Calculate WCAG 2.1 relative luminance for a color
+     * @param hexColor - Color in HEX format (#RRGGBB or RRGGBB)
+     * @returns Relative luminance (0-1)
+     */
+    calculateLuminance(hexColor: string): number;
+    /**
+     * Calculate WCAG contrast ratio between two colors
+     * @param color1 - First color in HEX format
+     * @param color2 - Second color in HEX format
+     * @returns Contrast ratio (1-21)
+     */
+    calculateContrastRatio(color1: string, color2: string): number;
+}
+/**
+ * Create a new ThemeDetectorService instance
+ * @returns ThemeDetectorService instance
+ */
+export declare function createThemeDetectorService(): ThemeDetectorService;
+export type { PixelThemeDetectionResult };
+//# sourceMappingURL=theme-detector.service.d.ts.map

package/dist/services/visual-extractor/theme-detector.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-detector.service.d.ts","sourceRoot":"","sources":["../../../src/services/visual-extractor/theme-detector.service.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AASvE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,gCAAgC,CAAC;AAExC;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,4CAA4C;IAC5C,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;IAClC,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,eAAe,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,aAAa,EAAE,MAAM,CAAC;IACtB,uBAAuB;IACvB,SAAS,EAAE;QACT,0CAA0C;QAC1C,UAAU,EAAE,MAAM,CAAC;QACnB,+CAA+C;QAC/C,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,sCAAuC,SAAQ,oBAAoB;IAClF,sGAAsG;IACtG,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAEnE;;;;OAIG;IACH,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,oBAAoB,CAAC;IAE3E;;;;;;;;;;;;;;OAcG;IACH,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC;IAE9E;;;;;;;;;;;;;;OAcG;IACH,6BAA6B,CAC3B,UAAU,EAAE,MAAM,EAClB,cAAc,CAAC,EAAE,iBAAiB,EAAE,GACnC,OAAO,CAAC,sCAAsC,CAAC,CAAC;IAEnD;;;;OAIG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAE7C;;;;;OAKG;IACH,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;CAChE;AA2iBD;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,oBAAoB,CAEjE;AAGD,YAAY,EAAE,yBAAyB,EAAE,CAAC"}