intellifont-engine 1.0.0 → 2.0.0

package/browser/intellifont-inspector.js

@@ -0,0 +1,299 @@
+/**
+ * intelliFont Web Inspector
+ * 
+ * Click-to-inspect browser module. Given a DOM element (or a CSS font name),
+ * computes Canvas DNA metrics and queries the intelliFont backend to identify
+ * the font and return ranked suggestions.
+ * 
+ * Usage (in your web app):
+ *   import { IntellifontInspector } from 'intellifont-engine/browser/intellifont-inspector.js';
+ *   const inspector = new IntellifontInspector({ serverUrl: 'http://localhost:3000' });
+ *   const result = await inspector.inspectElement(document.querySelector('h1'));
+ *   // result.matches → [{ family: "Inter", confidence: 0.95, matchQuality: "exact" }, ...]
+ * 
+ * Usage (bookmarklet / standalone — no backend needed):
+ *   Paste the contents of intellifont-bookmarklet.js into your browser console.
+ *   Click any text on the page. Results shown as an overlay.
+ */
+
+'use strict';
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+const DEFAULT_SERVER_URL = 'http://localhost:3000';
+const DEFAULT_CHARS = 'RQWM';
+const DEFAULT_LIMIT = 8;
+
+// =============================================================================
+// MAIN INSPECTOR CLASS
+// =============================================================================
+class IntellifontInspector {
+  /**
+   * @param {object} options
+   * @param {string} [options.serverUrl='http://localhost:3000'] - intellifont serve endpoint
+   * @param {string} [options.characters='RQWM'] - Characters to analyze
+   * @param {number} [options.limit=8] - Max suggestions to return
+   * @param {boolean} [options.showOverlay=true] - Show built-in result overlay
+   */
+  constructor(options = {}) {
+    this.serverUrl = options.serverUrl || DEFAULT_SERVER_URL;
+    this.characters = options.characters || DEFAULT_CHARS;
+    this.limit = options.limit || DEFAULT_LIMIT;
+    this.showOverlay = options.showOverlay !== false;
+    this._overlay = null;
+    this._canvasDNA = null;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Load canvas-dna module lazily
+  // ---------------------------------------------------------------------------
+  async _getCanvasDNA() {
+    if (this._canvasDNA) return this._canvasDNA;
+    if (typeof CanvasDNA !== 'undefined') {
+      this._canvasDNA = CanvasDNA;
+      return this._canvasDNA;
+    }
+    // Dynamic import if available
+    const mod = await import('./canvas-dna.js');
+    this._canvasDNA = mod.default || mod;
+    return this._canvasDNA;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Core inspection function — given a DOM element
+  // ---------------------------------------------------------------------------
+  async inspectElement(element) {
+    const dna = await this._getCanvasDNA();
+    const { fontFamily, cssRaw, metrics } = dna.analyzeElement(element, this.characters);
+
+    if (metrics.length === 0) {
+      return {
+        cssName: cssRaw,
+        resolvedName: fontFamily,
+        matches: [],
+        error: 'Could not extract any glyph metrics for this font.'
+      };
+    }
+
+    return this._queryBackend(fontFamily, cssRaw, metrics);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Inspect using a CSS font name string (e.g. from computed style)
+  // ---------------------------------------------------------------------------
+  async inspectFromCssName(cssName) {
+    const dna = await this._getCanvasDNA();
+    const fontFamily = cssName.split(',')[0].trim().replace(/['"]/g, '');
+    const metrics = dna.analyzeFont(fontFamily, this.characters);
+
+    return this._queryBackend(fontFamily, cssName, metrics);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Send metrics to the intellifont backend
+  // ---------------------------------------------------------------------------
+  async _queryBackend(fontFamily, cssRaw, metrics) {
+    const url = `${this.serverUrl}/api/identify-from-metrics`;
+
+    let matches = [];
+    let backendError = null;
+
+    try {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ metrics, limit: this.limit }),
+      });
+
+      if (!response.ok) {
+        throw new Error(`Backend responded ${response.status}`);
+      }
+
+      const data = await response.json();
+      matches = data.matches || [];
+    } catch (err) {
+      backendError = err.message;
+      // Graceful degradation: return the raw computed metrics so they're useful
+    }
+
+    const result = {
+      cssName: cssRaw,
+      resolvedName: fontFamily,
+      matches,
+      metrics,
+      backendError: backendError || undefined,
+    };
+
+    if (this.showOverlay) {
+      this._renderOverlay(result);
+    }
+
+    return result;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Built-in result overlay
+  // ---------------------------------------------------------------------------
+  _renderOverlay(result) {
+    this._removeOverlay();
+
+    const overlay = document.createElement('div');
+    overlay.id = 'intellifont-overlay';
+    overlay.setAttribute('style', `
+      position: fixed;
+      top: 20px;
+      right: 20px;
+      width: 320px;
+      max-height: 480px;
+      overflow-y: auto;
+      background: linear-gradient(135deg, #0f0f1a 0%, #1a1a2e 100%);
+      border: 1px solid rgba(99, 102, 241, 0.4);
+      border-radius: 16px;
+      padding: 20px;
+      font-family: 'Inter', 'Segoe UI', system-ui, sans-serif;
+      font-size: 13px;
+      color: #e2e8f0;
+      box-shadow: 0 25px 60px rgba(0,0,0,0.6), 0 0 0 1px rgba(255,255,255,0.05);
+      z-index: 2147483647;
+      animation: intellifont-slide-in 0.3s cubic-bezier(0.34, 1.56, 0.64, 1);
+    `);
+
+    // Inject animation keyframes
+    if (!document.getElementById('intellifont-styles')) {
+      const style = document.createElement('style');
+      style.id = 'intellifont-styles';
+      style.textContent = `
+        @keyframes intellifont-slide-in {
+          from { opacity: 0; transform: translateY(-12px) scale(0.96); }
+          to   { opacity: 1; transform: translateY(0) scale(1); }
+        }
+        #intellifont-overlay .if-match:hover {
+          background: rgba(99, 102, 241, 0.12) !important;
+        }
+      `;
+      document.head.appendChild(style);
+    }
+
+    const confidence_color = (score) => {
+      if (score >= 0.90) return '#6ee7b7'; // green
+      if (score >= 0.75) return '#fbbf24'; // yellow
+      return '#f87171'; // red
+    };
+
+    const matchHtml = result.matches.length > 0
+      ? result.matches.map((m, i) => `
+          <div class="if-match" style="
+            display: flex; align-items: center; justify-content: space-between;
+            padding: 10px 12px; margin: 6px 0;
+            background: rgba(255,255,255,0.04);
+            border-radius: 10px; cursor: default;
+            border: 1px solid rgba(255,255,255,0.06);
+            transition: background 0.15s;
+          ">
+            <div>
+              <div style="font-weight: 600; color: #f1f5f9; font-size: 13.5px;">
+                ${i === 0 ? '🏆 ' : ''}${m.family}
+              </div>
+              <div style="color: #94a3b8; font-size: 11px; margin-top: 2px;">
+                ${m.subfamily || 'Regular'} · ${m.matchQuality || ''}
+              </div>
+            </div>
+            <div style="
+              font-weight: 700; font-size: 14px;
+              color: ${confidence_color(m.confidence || m.score || 0)};
+            ">
+              ${((m.confidence || m.score || 0) * 100).toFixed(0)}%
+            </div>
+          </div>`)
+      .join('')
+      : `<div style="color: #64748b; padding: 12px 0; text-align: center;">
+           ${result.backendError
+             ? `⚠️ Could not reach intelliFont server.<br><span style="font-size:11px;">${result.backendError}</span>`
+             : 'No matches found in database.'}
+         </div>`;
+
+    overlay.innerHTML = `
+      <div style="display: flex; align-items: center; justify-content: space-between; margin-bottom: 16px;">
+        <div style="display: flex; align-items: center; gap: 8px;">
+          <div style="
+            width: 28px; height: 28px; border-radius: 8px;
+            background: linear-gradient(135deg, #6366f1, #8b5cf6);
+            display: flex; align-items: center; justify-content: center;
+            font-size: 14px;
+          ">𝔽</div>
+          <span style="font-weight: 700; font-size: 15px; color: #f8fafc;">intelliFont</span>
+        </div>
+        <button onclick="document.getElementById('intellifont-overlay').remove()" style="
+          background: none; border: none; color: #64748b; font-size: 18px;
+          cursor: pointer; padding: 0; line-height: 1;
+        ">✕</button>
+      </div>
+
+      <div style="margin-bottom: 12px;">
+        <div style="color: #64748b; font-size: 11px; text-transform: uppercase; letter-spacing: 0.05em; margin-bottom: 4px;">Detected CSS Font</div>
+        <div style="
+          background: rgba(255,255,255,0.06); border-radius: 8px;
+          padding: 8px 12px; font-family: monospace; font-size: 12px; color: #a5b4fc;
+        ">${result.cssName || result.resolvedName}</div>
+      </div>
+
+      <div style="color: #64748b; font-size: 11px; text-transform: uppercase; letter-spacing: 0.05em; margin-bottom: 8px;">
+        Canvas DNA Matches
+      </div>
+
+      ${matchHtml}
+
+      <div style="
+        margin-top: 14px; padding-top: 12px;
+        border-top: 1px solid rgba(255,255,255,0.08);
+        color: #475569; font-size: 10px; text-align: center;
+      ">
+        Analyzed via pixel metrics · ${result.metrics?.length || 0} glyphs
+      </div>
+    `;
+
+    document.body.appendChild(overlay);
+    this._overlay = overlay;
+  }
+
+  _removeOverlay() {
+    const existing = document.getElementById('intellifont-overlay');
+    if (existing) existing.remove();
+    this._overlay = null;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Enable click-to-inspect mode on the current page
+  // ---------------------------------------------------------------------------
+  enableClickInspect() {
+    this._clickHandler = async (e) => {
+      e.preventDefault();
+      e.stopPropagation();
+      const element = e.target;
+      element.style.outline = '2px solid rgba(99,102,241,0.8)';
+      setTimeout(() => { element.style.outline = ''; }, 1200);
+      await this.inspectElement(element);
+    };
+    document.addEventListener('click', this._clickHandler, true);
+    console.log('[intelliFont] Click any text to inspect its font. Call disableClickInspect() to stop.');
+    return this;
+  }
+
+  disableClickInspect() {
+    if (this._clickHandler) {
+      document.removeEventListener('click', this._clickHandler, true);
+      this._clickHandler = null;
+    }
+    return this;
+  }
+}
+
+// =============================================================================
+// EXPORTS
+// =============================================================================
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { IntellifontInspector };
+} else if (typeof window !== 'undefined') {
+  window.IntellifontInspector = IntellifontInspector;
+}

package/index.d.ts

@@ -41,3 +41,180 @@ export declare function getCacheStats(): JsCacheStats
 export declare function cleanupCache(aggressive: boolean): number
 export declare function listPinnedFonts(): Array<string>
 export declare function updateDatabase(): Promise<void>
+export interface JsVisualMatch {
+  family: string
+  subfamily?: string
+  confidence: number
+  matchedChars: Array<string>
+}
+export interface JsGlyphSignature {
+  character: string
+  aspectRatio: number
+  density: number
+  curveRatio: number
+  pointCount: number
+  xBalance: number
+  yBalance: number
+}
+export interface JsGlyphDbStats {
+  fontCount: number
+  charCount: number
+  uncompressedSizeMb: number
+  compressedSizeMb: number
+  compressionRatio: number
+  buildTimeSeconds: number
+}
+/**
+ * Identify a font visually by analyzing glyph shapes
+ *
+ * Uses the pre-built glyph signature database to find matching fonts.
+ * Pass multiple characters (e.g., "RQWM") for higher accuracy.
+ */
+export declare function identifyVisualFont(fontPath: string, characters: string, limit?: number | undefined | null): Array<JsVisualMatch>
+/**
+ * Identify a font visually from a memory buffer (e.g. file upload)
+ *
+ * Excellent for web servers where the font file is in memory.
+ */
+export declare function identifyVisualFontBuffer(fontData: Buffer, characters: string, limit?: number | undefined | null): Array<JsVisualMatch>
+/** AI-powered result for font similarity suggestions */
+export interface JsAiSuggestion {
+  /** The matched font family name */
+  family: string
+  /** The matched font subfamily (e.g., "Regular", "Bold") */
+  subfamily: string
+  /** AI confidence score (0.0 to 1.0) */
+  confidence: number
+  /** Similarity category: "exact", "high", "medium", "low" */
+  matchQuality: string
+}
+/**
+ * AI-powered font similarity suggestion
+ *
+ * Analyzes the visual DNA of a font file and finds similar fonts
+ * from the signature database using pattern recognition.
+ */
+export declare function aiSuggestSimilar(fontPath: string, limit?: number | undefined | null): Array<JsAiSuggestion>
+/** AI-powered font similarity from memory buffer */
+export declare function aiSuggestSimilarBuffer(fontData: Buffer, limit?: number | undefined | null): Array<JsAiSuggestion>
+/**
+ * Extract glyph signature from a font file
+ *
+ * Returns detailed signature information for a specific character.
+ */
+export declare function extractGlyphSignature(fontPath: string, character: string): JsGlyphSignature
+/**
+ * Build a glyph signature database from font files
+ *
+ * Indexes the specified font files with Brotli-11 compression.
+ */
+export declare function buildGlyphDatabase(fontPaths: Array<string>, outputPath: string): JsGlyphDbStats
+/**
+ * Pixel-derived glyph metrics computed by the browser's Canvas API.
+ *
+ * These fields match the Rust MicroSignature format (all u8 range 0-255).
+ * Computed by canvas-dna.js from rendered glyph pixel bitmaps.
+ */
+export interface JsPixelMetrics {
+  /** The character that was analyzed (e.g. "R") */
+  character: string
+  /** Width ÷ Height × 64 (0-255) */
+  aspectRatio: number
+  /** Ink pixel density in bounding box (0-255) */
+  density: number
+  /** Ink density in NW quadrant (0-255) */
+  quadrantNw: number
+  /** Ink density in NE quadrant (0-255) */
+  quadrantNe: number
+  /** Ink density in SW quadrant (0-255) */
+  quadrantSw: number
+  /** Ink density in SE quadrant (0-255) */
+  quadrantSe: number
+  /** Estimated curviness of strokes (0=straight, 255=very curved) */
+  curveRatio: number
+  /** Outline complexity / direction changes (0-255) */
+  pointCount: number
+  /** Horizontal center of mass (0=left, 128=center, 255=right) */
+  xBalance: number
+  /** Vertical center of mass (0=top, 128=center, 255=bottom) */
+  yBalance: number
+  /** Estimated stroke thickness (0-255) */
+  strokeWidth: number
+  /** Serif vs sans classification (0=sans, 255=strong serif) */
+  serifScore: number
+}
+/**
+ * Identify a font from pixel metrics computed by the browser Canvas API.
+ *
+ * This is the core of the "Canvas DNA" approach — the browser renders
+ * characters using the web font and measures their pixel geometry. Those
+ * measurements are sent here to be matched against the signature database,
+ * without ever needing to fetch or upload the font file.
+ *
+ * Accepts an array of JsPixelMetrics (one per analyzed character, e.g. R/Q/W/M)
+ * for higher accuracy multi-character matching.
+ */
+export declare function identifyFromPixelMetrics(metrics: Array<JsPixelMetrics>, limit?: number | undefined | null): Array<JsVisualMatch>
+/**
+ * Compare the visual similarity of two font glyphs
+ *
+ * Returns a similarity score from 0.0 (different) to 1.0 (identical).
+ */
+export declare function compareGlyphSignatures(fontPathA: string, fontPathB: string, character: string): number
+
+// =============================================================================
+// Image Pipeline (browser) — browser/image-pipeline.js
+// Identifies fonts from arbitrary raster images without uploading them.
+// =============================================================================
+
+/** Detected style properties for the text in an image. */
+export interface DetectedStyle {
+  /** True if the text appears to be italic (slant angle > 8°) */
+  italic: boolean
+  /** Measured slant angle in degrees (0 = upright, positive = slants right) */
+  italicAngle: number
+  /** Estimated CSS font-weight: 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 */
+  cssWeight: number
+  /** Human-readable weight label e.g. "Regular", "Bold", "Light" */
+  weightLabel: string
+}
+
+/** Result of analyzing an image for font identification. */
+export interface ImagePipelineResult {
+  /** JsPixelMetrics[] ready to pass to identifyFromPixelMetrics() */
+  metrics: JsPixelMetrics[]
+  /** Detected italic/bold/weight style aggregated across all glyph crops */
+  style: DetectedStyle
+  /** Laplacian variance sharpness score — higher is sharper */
+  quality: number
+  /** Degrees the image was rotated to straighten text (negative = clockwise) */
+  deskewAngle: number
+  /** Total text regions found before the MAX_GLYPHS cap */
+  regionCount: number
+  /** User-facing warning if image quality is too low, or null */
+  warning: string | null
+}
+
+/** Any image source accepted by the ImagePipeline */
+export type ImageSource =
+  | string                // URL or data URL
+  | File
+  | Blob
+  | HTMLImageElement
+  | HTMLCanvasElement
+
+/**
+ * Identify fonts from any raster image (screenshot, photo, PDF frame).
+ * Runs entirely in the browser — no upload required.
+ *
+ * @example
+ * const { metrics, warning } = await analyzeImage(file);
+ * if (warning) console.warn(warning);
+ * const matches = identifyFromPixelMetrics(metrics, 8);
+ */
+export declare function analyzeImage(imageSource: ImageSource): Promise<ImagePipelineResult>
+
+/** Full pipeline class for advanced usage (e.g. reusing across multiple images) */
+export declare class ImagePipeline {
+  analyze(imageSource: ImageSource): Promise<ImagePipelineResult>
+}