intellifont-engine 1.0.0 → 2.0.0

package/index.js

@@ -1,194 +1,760 @@
-#!/usr/bin/env node
-const {
-  getFontSuggestions,
-  normalizeFontName,
-  pinFont,
-  unpinFont,
-  removeFromCache,
-  exportMetrics,
-  getEngineStats,
-  getCacheStats,
-  cleanupCache,
-  listPinnedFonts,
-  updateDatabase
-} = require('./intellifont-engine.node');
-
-/**
- * Creates a CSS @font-face string for a given font family and URL.
- */
-function createFontFace(family, url, weight = 400, italic = false) {
-  return `
-@font-face {
-  font-family: '${family}';
-  src: url('${url}') format('woff2');
-  font-weight: ${weight};
-  font-style: ${italic ? 'italic' : 'normal'};
-  font-display: swap;
-}
-  `.trim();
-}
-
-/**
- * Enhanced suggestion helper that includes license advice.
- */
-async function getEnhancedSuggestions(fontName, includeInternet = true) {
-  const suggestions = await getFontSuggestions(fontName, includeInternet);
-
-  return suggestions.map(s => ({
-    ...s,
-    uiAdvice: s.isCriticalLicenseWarning
-      ? "⚠ Warning: Check license before commercial use."
-      : "✔ Safe to use.",
-    fontFace: s.downloadUrl ? createFontFace(s.family, s.downloadUrl, s.weight, s.italic) : null
-  }));
-}
-
-/**
- * CLI Entry Point
- */
-if (require.main === module) {
-  const args = process.argv.slice(2);
-  const command = args[0];
-  const subCommand = args[1];
-  const params = args.slice(command === 'cache' || command === 'config' ? 2 : 1);
-
-  async function runCli() {
-    switch (command) {
-      case 'resolve':
-      case 'suggest':
-        const searchName = params[0] || "Arial";
-        const useWeb = args.includes('--internet') || args.includes('--web');
-        const results = await getEnhancedSuggestions(searchName, useWeb);
-        console.log(`\nSuggestions for "${searchName}":`);
-        results.forEach(r => {
-          const status = r.isCriticalLicenseWarning ? '[RESTRICTED]' : '[OK]';
-          console.log(` ${status} ${r.family} ${r.subfamily} (${r.source}) - Similarity: ${(r.score * 100).toFixed(1)}%`);
-        });
-        break;
-
-      case 'tiered':
-        // For CLI parity, we use the same as suggest but with different UI formatting
-        const tieredName = params[0] || "Arial";
-        const tieredWeb = args.includes('--internet');
-        const tieredResults = await getEnhancedSuggestions(tieredName, tieredWeb);
-        console.log(`\nTiered Analysis for "${tieredName}":`);
-        const exact = tieredResults.filter(r => r.score > 0.95);
-        const similar = tieredResults.filter(r => r.score <= 0.95 && r.score > 0.8);
-
-        if (exact.length) {
-          console.log("\n[90%+ Match Tier]");
-          exact.forEach(r => console.log(` - ${r.family} (Exact match)`));
-        }
-        if (similar.length) {
-          console.log("\n[80%+ Similar Tier]");
-          similar.forEach(r => console.log(` - ${r.family} (${(r.score * 100).toFixed(1)}%)`));
-        }
-        break;
-
-      case 'stats':
-        const eStats = getEngineStats();
-        const cStats = getCacheStats();
-        console.log(`\nENGINE STATUS`);
-        console.log(`  Fonts indexed : ${eStats.fontCount.toLocaleString()}`);
-        console.log(`  Binary size   : ${eStats.compressedSizeMb.toFixed(2)} MB`);
-        console.log(`  Ratio         : ${eStats.compressionRatio.toFixed(1)}%`);
-        console.log(`\nCACHE STATUS`);
-        console.log(`  Memory/Disk   : ${cStats.memoryEntries}/${cStats.diskEntries} entries`);
-        console.log(`  Pinned        : ${cStats.pinnedFonts}`);
-        console.log(`  Disk usage    : ${cStats.diskUsageMb.toFixed(2)} MB`);
-        break;
-
-      case 'cache':
-        switch (subCommand) {
-          case 'stats':
-            const cs = getCacheStats();
-            console.log(`\nCACHE: ${cs.memoryEntries} mem / ${cs.diskEntries} disk (${cs.diskUsageMb.toFixed(2)} MB)`);
-            break;
-          case 'cleanup':
-            const agg = args.includes('--aggressive');
-            const cleaned = cleanupCache(agg);
-            console.log(`Cache cleared. Removed ${cleaned} entries.`);
-            break;
-          case 'list':
-            const pinned = listPinnedFonts();
-            console.log("\nPINNED FONTS");
-            pinned.length ? pinned.forEach(p => console.log(`  - ${p}`)) : console.log("  (None)");
-            break;
-          case 'pin':
-            params.forEach(p => { pinFont(p); console.log(`Pinned: ${p}`); });
-            break;
-          case 'unpin':
-            params.forEach(p => { unpinFont(p); console.log(`Unpinned: ${p}`); });
-            break;
-        }
-        break;
-
-      case 'scan':
-        const sStats = getEngineStats();
-        console.log(`\nScan complete. ${sStats.fontCount} fonts available.`);
-        break;
-
-      case 'update':
-        process.stdout.write("Updating database... ");
-        try {
-          await updateDatabase();
-          console.log("Done.");
-        } catch (e) {
-          console.log("\nFailed.");
-          console.error(`Error: ${e.message}`);
-        }
-        break;
-
-      case 'export-metrics':
-        try {
-          console.log(exportMetrics(params[0] || "Arial"));
-        } catch (e) {
-          console.error(`Error: ${e.message}`);
-        }
-        break;
-
-      case 'setup':
-        console.log("\nintelliFont Setup Wizard");
-        console.log("1. Memory Limit: 16MB (Default)");
-        console.log("2. Web Fonts: Enabled");
-        console.log("3. License Guard: Active");
-        console.log("\nConfiguration optimized for your system.");
-        break;
-
-      case 'normalize':
-        console.log(normalizeFontName(params[0] || "Arial"));
-        break;
-
-      case 'help':
-      default:
-        console.log("\nintelliFont Engine CLI");
-        console.log("Usage:");
-        console.log("  intellifont suggest <name> [--internet]    - Find matching fonts");
-        console.log("  intellifont resolve <name>                 - Fast lookup");
-        console.log("  intellifont stats                          - Engine & Cache metrics");
-        console.log("  intellifont scan                           - Refresh system font index");
-        console.log("  intellifont update                         - Sync with global CDN signatures");
-        console.log("  intellifont cache <stats|list|cleanup>     - Manage local cache");
-        console.log("  intellifont cache <pin|unpin> <name>       - Manage font pinning");
-        console.log("  intellifont export-metrics <name>          - Get binary DNA of a font");
-        break;
-    }
-  }
-  runCli().catch(console.error);
-}
-
-module.exports = {
-  getFontSuggestions,
-  getEnhancedSuggestions,
-  normalizeFontName,
-  createFontFace,
-  pinFont,
-  unpinFont,
-  removeFromCache,
-  exportMetrics,
-  getEngineStats,
-  getCacheStats,
-  cleanupCache,
-  listPinnedFonts,
-  updateDatabase
-};
+#!/usr/bin/env node
+const {
+  getFontSuggestions,
+  normalizeFontName,
+  resolveFontBasic,
+  pinFont,
+  unpinFont,
+  removeFromCache,
+  exportMetrics,
+  getEngineStats,
+  getCacheStats,
+  cleanupCache,
+  listPinnedFonts,
+  updateDatabase,
+  // Visual identification — file-based
+  identifyVisualFont,
+  identifyVisualFontBuffer,
+  aiSuggestSimilar,
+  aiSuggestSimilarBuffer,
+  extractGlyphSignature,
+  compareGlyphSignatures,
+  // Database building
+  buildGlyphDatabase,
+  identifyFromPixelMetrics: nativeIdentifyFromPixelMetrics,
+  // Image OCR preprocessing (Phase 2)
+  preprocessImageForFontId,
+  // Hybrid ML layer (Phase 4)
+  mlAvailable,
+  mlIdentifyGlyphs,
+} = require('./intellifont-engine.node');
+
+/** Normalize browser/API snake_case metrics to native camelCase (JsPixelMetrics). */
+function _normalizePixelMetrics(m) {
+  return {
+    character:    m.character ?? m.char ?? 'R',
+    aspectRatio:  m.aspectRatio  ?? m.aspect_ratio  ?? 0,
+    density:      m.density      ?? 0,
+    quadrantNw:   m.quadrantNw   ?? m.quadrant_nw   ?? 0,
+    quadrantNe:   m.quadrantNe   ?? m.quadrant_ne   ?? 0,
+    quadrantSw:   m.quadrantSw   ?? m.quadrant_sw   ?? 0,
+    quadrantSe:   m.quadrantSe   ?? m.quadrant_se   ?? 0,
+    curveRatio:   m.curveRatio   ?? m.curve_ratio   ?? 0,
+    pointCount:   m.pointCount   ?? m.point_count   ?? 0,
+    xBalance:     m.xBalance     ?? m.x_balance     ?? 0,
+    yBalance:     m.yBalance     ?? m.y_balance     ?? 0,
+    strokeWidth:  m.strokeWidth  ?? m.stroke_width  ?? 0,
+    serifScore:   m.serifScore   ?? m.serif_score   ?? 0,
+  };
+}
+
+// =============================================================================
+// PURE-JS POLYFILL: identifyFromPixelMetrics
+// Reads glyph_signatures.bin and matches pixel metrics via weighted cosine
+// similarity — same algorithm as the Rust MicroSignature matcher.
+// This runs until the Rust binary is rebuilt with the native NAPI function.
+// =============================================================================
+function _findGlyphDbPath() {
+  const path = require('path');
+  const fs   = require('fs');
+  const candidates = [
+    path.join(process.cwd(), 'data', 'glyph_signatures.bin'),
+    path.join(__dirname,    'data', 'glyph_signatures.bin'),
+    path.join(__dirname, '..', '..', 'data', 'glyph_signatures.bin'),
+    path.join(__dirname, '..', '..', '..', 'data', 'glyph_signatures.bin'),
+  ];
+  return candidates.find(p => fs.existsSync(p)) || null;
+}
+
+function _parseGlyphDb(buf) {
+  // Format: b"GLYPHDB1" (8 bytes) + Brotli-compressed bincode(GlyphDatabase)
+  const magic = buf.slice(0, 8).toString('ascii');
+  if (magic !== 'GLYPHDB1') throw new Error('Invalid glyph DB magic: ' + magic);
+
+  // Decompress with Node's built-in Brotli
+  const zlib = require('zlib');
+  const b = zlib.brotliDecompressSync(buf.slice(8));
+
+  let off = 0;
+
+  // ---- helpers ----
+  function readU8()  { return b[off++]; }
+  function readU16() { const v = b.readUInt16LE(off); off += 2; return v; }
+  function readU32() { const v = b.readUInt32LE(off); off += 4; return v; }
+  // bincode u64 as two u32s (JS safe for DB sizes)
+  function readU64() { const lo = b.readUInt32LE(off); const hi = b.readUInt32LE(off+4); off += 8; return lo + hi * 0x100000000; }
+  function readStr() { const len = readU64(); const s = b.slice(off, off+len).toString('utf8'); off += len; return s; }
+  function readOption(readFn) { const tag = readU8(); return tag ? readFn() : null; }
+
+  // ---- DatabaseHeader (34 bytes total) ----
+  const version    = readU32();
+  const font_count = readU32();
+  const char_count = readU8();
+  const flags      = readU8();
+  const lsh_offset        = readU64(); // stored but not used by JS
+  const signatures_offset = readU64();
+  const names_offset      = readU64();
+
+  // ---- LshIndex: Vec<Vec<Vec<u16>>> ----
+  // We just skip it — we’ll do brute-force similarity (DB is small)
+  const ntables = readU64();
+  for (let t = 0; t < ntables; t++) {
+    const nbuckets = readU64();
+    for (let bkt = 0; bkt < nbuckets; bkt++) {
+      const nids = readU64();
+      off += nids * 2; // skip u16 font IDs
+    }
+  }
+
+  // ---- Vec<FontEntry> ----
+  const nfonts = readU64();
+  const fonts = [];
+
+  for (let i = 0; i < nfonts; i++) {
+    const family    = readStr();
+    const subfamily = readOption(readStr);
+
+    // Vec<(char, MicroSignature)>
+    // char is stored as u8 (all ALPHANUMERIC_CHARS are ASCII)
+    // MicroSignature: 12×u8 + u16 (feature_hash) + u16 (reserved) = 16 bytes
+    const nsigs = readU64();
+    const signatures = [];
+    for (let s = 0; s < nsigs; s++) {
+      const charByte = readU8(); // char stored as 1-byte ASCII
+      const sig = {
+        aspect_ratio: readU8(),
+        density:      readU8(),
+        quadrant_nw:  readU8(),
+        quadrant_ne:  readU8(),
+        quadrant_sw:  readU8(),
+        quadrant_se:  readU8(),
+        curve_ratio:  readU8(),
+        point_count:  readU8(),
+        x_balance:    readU8(),
+        y_balance:    readU8(),
+        stroke_width: readU8(),
+        serif_score:  readU8(),
+        feature_hash: readU16(), // u16
+        reserved:     readU16(), // u16 (not u8!)
+      };
+      signatures.push({ char: String.fromCharCode(charByte), sig });
+    }
+    fonts.push({ family, subfamily, signatures });
+  }
+
+  return fonts;
+}
+
+let _cachedDb = null;
+function _loadDb() {
+  if (_cachedDb) return _cachedDb;
+  const dbPath = _findGlyphDbPath();
+  if (!dbPath) return null;
+  try {
+    const buf = require('fs').readFileSync(dbPath);
+    _cachedDb = _parseGlyphDb(buf);
+    return _cachedDb;
+  } catch (e) {
+    return null;
+  }
+}
+
+function _sigSimilarity(query, dbSig) {
+  // Weighted L1 distance — same field weights as Rust implementation
+  const weights = [
+    ['aspect_ratio',  0.15],
+    ['density',       0.15],
+    ['quadrant_nw',   0.08],
+    ['quadrant_ne',   0.08],
+    ['quadrant_sw',   0.08],
+    ['quadrant_se',   0.08],
+    ['curve_ratio',   0.10],
+    ['point_count',   0.05],
+    ['x_balance',     0.06],
+    ['y_balance',     0.06],
+    ['stroke_width',  0.10],
+    ['serif_score',   0.11],
+  ];
+  let dist = 0;
+  for (const [field, w] of weights) {
+    dist += w * Math.abs((query[field] || 0) - (dbSig[field] || 0)) / 255;
+  }
+  return Math.max(0, 1 - dist);
+}
+
+function identifyFromPixelMetrics(metrics, limit) {
+  const normalized = metrics.map(_normalizePixelMetrics);
+
+  // Prefer native matcher — loads DB in Rust (~35 MB RSS), not a JS object graph (~90+ MB).
+  if (typeof nativeIdentifyFromPixelMetrics === 'function') {
+    const dbPath = _findGlyphDbPath();
+    if (dbPath) {
+      const path = require('path');
+      const prevCwd = process.cwd();
+      try {
+        // Native resolves paths relative to cwd (data/glyph_signatures.bin).
+        process.chdir(path.dirname(path.dirname(dbPath)));
+        return nativeIdentifyFromPixelMetrics(normalized, limit);
+      } finally {
+        process.chdir(prevCwd);
+      }
+    }
+    try {
+      return nativeIdentifyFromPixelMetrics(normalized, limit);
+    } catch (err) {
+      const msg = err && err.message ? String(err.message) : '';
+      if (!msg.includes('GLYPH_DB_NOT_FOUND')) throw err;
+    }
+  }
+
+  // Pure-JS fallback (only when native is missing or DB not on disk)
+  const db = _loadDb();
+  if (!db) {
+    throw new Error('GLYPH_DB_NOT_FOUND: Run npx intellifont build-glyph-db <fonts-dir>');
+  }
+
+  const maxResults = (limit || 8);
+
+  // Score every font in the DB against each provided metric (one per char)
+  const familyScores = new Map(); // family+subfamily → { total, count }
+
+  for (const m of metrics) {
+    // Convert camelCase from browser to snake_case for db lookup
+    const query = {
+      aspect_ratio: m.aspectRatio  || m.aspect_ratio  || 0,
+      density:      m.density      || 0,
+      quadrant_nw:  m.quadrantNw   || m.quadrant_nw   || 0,
+      quadrant_ne:  m.quadrantNe   || m.quadrant_ne   || 0,
+      quadrant_sw:  m.quadrantSw   || m.quadrant_sw   || 0,
+      quadrant_se:  m.quadrantSe   || m.quadrant_se   || 0,
+      curve_ratio:  m.curveRatio   || m.curve_ratio   || 0,
+      point_count:  m.pointCount   || m.point_count   || 0,
+      x_balance:    m.xBalance     || m.x_balance     || 0,
+      y_balance:    m.yBalance     || m.y_balance     || 0,
+      stroke_width: m.strokeWidth  || m.stroke_width  || 0,
+      serif_score:  m.serifScore   || m.serif_score   || 0,
+    };
+
+    // Find the matching character entries in the DB
+    const targetChar = m.character || 'R';
+
+    for (const font of db) {
+      const key = `${font.family}\x00${font.subfamily}`;
+      if (!familyScores.has(key)) {
+        familyScores.set(key, { family: font.family, subfamily: font.subfamily, total: 0, count: 0 });
+      }
+      const entry = familyScores.get(key);
+
+      // Find the matching character's signature (or use best available)
+      const charSig = font.signatures.find(s => s.char === targetChar);
+      const sigsToScore = charSig ? [charSig] : font.signatures.slice(0, 3);
+
+      let bestScore = 0;
+      for (const { sig } of sigsToScore) {
+        const score = _sigSimilarity(query, sig);
+        if (score > bestScore) bestScore = score;
+      }
+      entry.total += bestScore;
+      entry.count++;
+    }
+  }
+
+  // Average score per font and sort descending
+  const results = [...familyScores.values()]
+    .map(s => ({
+      family:     s.family,
+      subfamily:  s.subfamily,
+      confidence: s.total / s.count,
+      matchQuality: s.total / s.count >= 0.90 ? 'exact'
+                  : s.total / s.count >= 0.75 ? 'high'
+                  : s.total / s.count >= 0.60 ? 'medium' : 'low',
+      matchedChars: metrics.map(m => m.character || 'R'),
+    }))
+    .filter(r => r.confidence > 0.30)
+    .sort((a, b) => b.confidence - a.confidence)
+    .slice(0, maxResults);
+
+  return results;
+}
+
+/**
+ * Creates a CSS @font-face string for a given font family and URL.
+ */
+function createFontFace(family, url, weight = 400, italic = false) {
+  return `
+@font-face {
+  font-family: '${family}';
+  src: url('${url}') format('woff2');
+  font-weight: ${weight};
+  font-style: ${italic ? 'italic' : 'normal'};
+  font-display: swap;
+}
+  `.trim();
+}
+
+/**
+ * Enhanced suggestion helper that includes license advice.
+ */
+async function getEnhancedSuggestions(fontName, includeInternet = true) {
+  const suggestions = await getFontSuggestions(fontName, includeInternet);
+
+  return suggestions.map(s => ({
+    ...s,
+    uiAdvice: s.isCriticalLicenseWarning
+      ? "⚠ Warning: Check license before commercial use."
+      : "✔ Safe to use.",
+    fontFace: s.downloadUrl ? createFontFace(s.family, s.downloadUrl, s.weight, s.italic) : null
+  }));
+}
+
+/**
+ * CLI Entry Point
+ */
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  const subCommand = args[1];
+  const params = args.slice(command === 'cache' || command === 'config' ? 2 : 1);
+
+  async function runCli() {
+    switch (command) {
+      case 'resolve':
+      case 'suggest':
+        const searchName = params[0] || "Arial";
+        const useWeb = args.includes('--internet') || args.includes('--web');
+        const results = await getEnhancedSuggestions(searchName, useWeb);
+        console.log(`\nSuggestions for "${searchName}":`);
+        results.forEach(r => {
+          const status = r.isCriticalLicenseWarning ? '[RESTRICTED]' : '[OK]';
+          console.log(` ${status} ${r.family} ${r.subfamily} (${r.source}) - Similarity: ${(r.score * 100).toFixed(1)}%`);
+        });
+        break;
+
+      case 'tiered':
+        // For CLI parity, we use the same as suggest but with different UI formatting
+        const tieredName = params[0] || "Arial";
+        const tieredWeb = args.includes('--internet');
+        const tieredResults = await getEnhancedSuggestions(tieredName, tieredWeb);
+        console.log(`\nTiered Analysis for "${tieredName}":`);
+        const exact = tieredResults.filter(r => r.score > 0.95);
+        const similar = tieredResults.filter(r => r.score <= 0.95 && r.score > 0.8);
+
+        if (exact.length) {
+          console.log("\n[90%+ Match Tier]");
+          exact.forEach(r => console.log(` - ${r.family} (Exact match)`));
+        }
+        if (similar.length) {
+          console.log("\n[80%+ Similar Tier]");
+          similar.forEach(r => console.log(` - ${r.family} (${(r.score * 100).toFixed(1)}%)`));
+        }
+        break;
+
+      case 'stats':
+        const eStats = getEngineStats();
+        const cStats = getCacheStats();
+        console.log(`\nENGINE STATUS`);
+        console.log(`  Fonts indexed : ${eStats.fontCount.toLocaleString()}`);
+        console.log(`  Binary size   : ${eStats.compressedSizeMb.toFixed(2)} MB`);
+        console.log(`  Ratio         : ${eStats.compressionRatio.toFixed(1)}%`);
+        console.log(`\nCACHE STATUS`);
+        console.log(`  Memory/Disk   : ${cStats.memoryEntries}/${cStats.diskEntries} entries`);
+        console.log(`  Pinned        : ${cStats.pinnedFonts}`);
+        console.log(`  Disk usage    : ${cStats.diskUsageMb.toFixed(2)} MB`);
+        break;
+
+      case 'cache':
+        switch (subCommand) {
+          case 'stats':
+            const cs = getCacheStats();
+            console.log(`\nCACHE: ${cs.memoryEntries} mem / ${cs.diskEntries} disk (${cs.diskUsageMb.toFixed(2)} MB)`);
+            break;
+          case 'cleanup':
+            const agg = args.includes('--aggressive');
+            const cleaned = cleanupCache(agg);
+            console.log(`Cache cleared. Removed ${cleaned} entries.`);
+            break;
+          case 'list':
+            const pinned = listPinnedFonts();
+            console.log("\nPINNED FONTS");
+            pinned.length ? pinned.forEach(p => console.log(`  - ${p}`)) : console.log("  (None)");
+            break;
+          case 'pin':
+            params.forEach(p => { pinFont(p); console.log(`Pinned: ${p}`); });
+            break;
+          case 'unpin':
+            params.forEach(p => { unpinFont(p); console.log(`Unpinned: ${p}`); });
+            break;
+        }
+        break;
+
+      case 'scan':
+        const sStats = getEngineStats();
+        console.log(`\nScan complete. ${sStats.fontCount} fonts available.`);
+        break;
+
+      case 'update':
+        process.stdout.write("Updating database... ");
+        try {
+          await updateDatabase();
+          console.log("Done.");
+        } catch (e) {
+          console.log("\nFailed.");
+          console.error(`Error: ${e.message}`);
+        }
+        break;
+
+      case 'export-metrics':
+        try {
+          console.log(exportMetrics(params[0] || "Arial"));
+        } catch (e) {
+          console.error(`Error: ${e.message}`);
+        }
+        break;
+
+      case 'setup':
+        console.log("\nintelliFont Setup Wizard");
+        console.log("1. Memory Limit: 16MB (Default)");
+        console.log("2. Web Fonts: Enabled");
+        console.log("3. License Guard: Active");
+        console.log("\nConfiguration optimized for your system.");
+        break;
+
+      case 'normalize':
+        console.log(normalizeFontName(params[0] || "Arial"));
+        break;
+
+      case 'inspect-url': {
+        // Server-side webpage font scraper — no CORS restrictions
+        const targetUrl = params[0];
+        if (!targetUrl) {
+          console.error('Usage: intellifont inspect-url <url>');
+          console.error('Example: intellifont inspect-url https://example.com');
+          process.exit(1);
+        }
+
+        console.log(`\n🔍 Scanning fonts on: ${targetUrl}\n`);
+
+        try {
+          const fetchFn = typeof fetch !== 'undefined' ? fetch : (...a) => import('node-fetch').then(m => m.default(...a)).catch(() => {
+            throw new Error('Node 18+ required or install node-fetch: npm install node-fetch');
+          });
+
+          // 1. Download the page HTML
+          const htmlRes = await fetchFn(targetUrl, { headers: { 'User-Agent': 'intellifont-inspector/1.3' } });
+          const html = await htmlRes.text();
+          const baseUrl = new URL(targetUrl);
+
+          // 2. Find all linked stylesheets + inline <style> blocks
+          const cssTexts = [];
+          const styleTagRe = /<style[^>]*>([\/\s\S]*?)<\/style>/gi;
+          let sm;
+          while ((sm = styleTagRe.exec(html)) !== null) cssTexts.push(sm[1]);
+
+          const linkRe = /<link[^>]+rel=["']stylesheet["'][^>]+href=["']([^"']+)["']/gi;
+          let lm;
+          while ((lm = linkRe.exec(html)) !== null) {
+            try {
+              const cssUrl = new URL(lm[1], baseUrl).href;
+              const cssRes = await fetchFn(cssUrl, { headers: { 'User-Agent': 'intellifont-inspector/1.3' } });
+              if (cssRes.ok) cssTexts.push(await cssRes.text());
+            } catch (_) {}
+          }
+
+          // 3. Extract all @font-face src URLs
+          const allCss = cssTexts.join('\n');
+          const fontFaceRe = /@font-face\s*\{([^}]+)\}/gi;
+          const srcUrlRe = /src:[^;]*url\(["']?([^"')]+\.(?:woff2?|ttf|otf))["']?\)/i;
+          const familyRe = /font-family:\s*["']?([^"';]+)["']?/i;
+
+          const fontJobs = [];
+          let ffm;
+          while ((ffm = fontFaceRe.exec(allCss)) !== null) {
+            const block = ffm[1];
+            const urlMatch = srcUrlRe.exec(block);
+            const famMatch = familyRe.exec(block);
+            if (urlMatch) {
+              fontJobs.push({
+                cssName: famMatch ? famMatch[1].trim() : '(unknown)',
+                url: new URL(urlMatch[1], baseUrl).href,
+              });
+            }
+          }
+
+          if (fontJobs.length === 0) {
+            console.log('  No @font-face declarations found. The page may use only system fonts or embed fonts differently.');
+          } else {
+            console.log(`  Found ${fontJobs.length} font-face declaration(s). Identifying...\n`);
+            for (const job of fontJobs) {
+              process.stdout.write(`  → "${job.cssName}"  (${job.url.split('/').pop()}) ... `);
+              try {
+                const fontRes = await fetchFn(job.url);
+                if (!fontRes.ok) { console.log('(fetch failed)'); continue; }
+                const ab = await fontRes.arrayBuffer();
+                const buffer = Buffer.from(ab);
+                const results = identifyVisualFontBuffer(buffer, 'RQWM', 5);
+                if (results.length > 0) {
+                  const top = results[0];
+                  const pct = (top.confidence * 100).toFixed(0);
+                  const quality = top.confidence >= 0.95 ? '✅' : top.confidence >= 0.80 ? '🟡' : '🔴';
+                  console.log(`${quality} ${top.family} ${top.subfamily || ''} (${pct}% confidence)`);
+                  if (results.length > 1 && args.includes('--verbose')) {
+                    results.slice(1, 3).forEach(r => console.log(`        also: ${r.family} (${(r.confidence*100).toFixed(0)}%)`));
+                  }
+                } else {
+                  console.log('(no match in database — try building a larger glyph DB)');
+                }
+              } catch (e) {
+                console.log(`(error: ${e.message})`);
+              }
+            }
+          }
+
+          // 4. Also list CSS font-family names referenced in the page
+          const inlineRe = /font-family:\s*["']?([A-Za-z][^"';,\n]+)/g;
+          const foundNames = new Set();
+          let im;
+          while ((im = inlineRe.exec(allCss)) !== null) {
+            const n = im[1].trim().replace(/["']/g, '');
+            if (n && !n.startsWith('inherit') && !n.startsWith('var')) foundNames.add(n);
+          }
+          if (foundNames.size > 0) {
+            console.log(`\n  CSS font names referenced: ${[...foundNames].join(', ')}`);
+            if (args.includes('--suggest')) {
+              for (const name of foundNames) {
+                const suggestions = await getFontSuggestions(name, false);
+                if (suggestions.length > 0) {
+                  console.log(`\n  Suggestions for "${name}":`);
+                  suggestions.slice(0, 3).forEach(s => console.log(`    ${s.family} (${(s.score*100).toFixed(0)}%)`));
+                }
+              }
+            }
+          }
+        } catch (e) {
+          console.error(`Error: ${e.message}`);
+          process.exit(1);
+        }
+        break;
+      }
+
+      case 'serve': {
+        // Zero-dependency HTTP server — serves browser files + Canvas DNA API
+        const http = require('http');
+        const fs = require('fs');
+        const path = require('path');
+
+        const portArg = args.find(a => a.startsWith('--port=')) || args[args.indexOf('--port') + 1];
+        const PORT = parseInt(portArg) || 3000;
+        const HOST = args.find(a => a.startsWith('--host='))?.split('=')[1] || 'localhost';
+
+        // Directory where browser assets live (same folder as index.js)
+        const BROWSER_DIR = path.join(__dirname, 'browser');
+
+        // Auto-copy the glyph DB to ./data/ so the precompiled Rust binary can find it
+        {
+          const localDbDir  = path.join(process.cwd(), 'data');
+          const localDbPath = path.join(localDbDir, 'glyph_signatures.bin');
+          if (!fs.existsSync(localDbPath)) {
+            const dbCandidates = [
+              path.join(__dirname, 'data', 'glyph_signatures.bin'),
+              path.join(__dirname, '..', '..', 'data', 'glyph_signatures.bin'),
+              path.join(__dirname, '..', '..', '..', 'data', 'glyph_signatures.bin'),
+            ];
+            const src = dbCandidates.find(p => fs.existsSync(p));
+            if (src) {
+              fs.mkdirSync(localDbDir, { recursive: true });
+              fs.copyFileSync(src, localDbPath);
+              console.log(`  📦 Glyph DB linked from: ${path.relative(process.cwd(), src)}`);
+            }
+          }
+        }
+
+        const MIME = {
+          '.html': 'text/html; charset=utf-8',
+          '.js':   'application/javascript; charset=utf-8',
+          '.json': 'application/json',
+          '.css':  'text/css',
+          '.png':  'image/png',
+          '.ico':  'image/x-icon',
+        };
+
+        const server = http.createServer(async (req, res) => {
+          // CORS headers so the bookmarklet can call from any origin
+          res.setHeader('Access-Control-Allow-Origin', '*');
+          res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+          res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+
+          if (req.method === 'OPTIONS') {
+            res.writeHead(204); res.end(); return;
+          }
+
+          const url = new URL(req.url, `http://${HOST}:${PORT}`);
+          const pathname = url.pathname;
+
+          // ── API: POST /api/identify-from-metrics ─────────────────────────
+          if (req.method === 'POST' && pathname === '/api/identify-from-metrics') {
+            let body = '';
+            req.on('data', chunk => { body += chunk; });
+            req.on('end', () => {
+              try {
+                const { metrics, limit } = JSON.parse(body);
+                if (!Array.isArray(metrics) || metrics.length === 0) {
+                  res.writeHead(400, { 'Content-Type': 'application/json' });
+                  return res.end(JSON.stringify({ error: 'metrics array required' }));
+                }
+                const matches = identifyFromPixelMetrics(metrics, limit || 8);
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: true, matches }));
+              } catch (e) {
+                // Gracefully handle missing glyph database — return 200 with empty matches
+                if (e.message && e.message.includes('GLYPH_DB_NOT_FOUND')) {
+                  res.writeHead(200, { 'Content-Type': 'application/json' });
+                  return res.end(JSON.stringify({
+                    success: true,
+                    matches: [],
+                    databaseNotFound: true,
+                    hint: 'Build the glyph database with: intellifont build-glyph-db <fonts-dir>'
+                  }));
+                }
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: e.message }));
+              }
+            });
+            return;
+          }
+
+          // ── API: POST /api/suggest ────────────────────────────────────────
+          if (req.method === 'POST' && pathname === '/api/suggest') {
+            let body = '';
+            req.on('data', chunk => { body += chunk; });
+            req.on('end', async () => {
+              try {
+                const { fontName, includeInternet } = JSON.parse(body);
+                const suggestions = await getFontSuggestions(fontName || 'Arial', includeInternet || false);
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ success: true, suggestions }));
+              } catch (e) {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: e.message }));
+              }
+            });
+            return;
+          }
+
+          // ── API: GET /api/health ──────────────────────────────────────────
+          if (pathname === '/api/health') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            return res.end(JSON.stringify({ status: 'ok', version: '1.3.0', engine: 'intellifont-engine' }));
+          }
+
+          // ── Static: /browser/* and / → demo.html ─────────────────────────
+          let filePath;
+          if (pathname === '/' || pathname === '/index.html') {
+            filePath = path.join(BROWSER_DIR, 'demo.html');
+          } else if (pathname.startsWith('/browser/')) {
+            filePath = path.join(BROWSER_DIR, pathname.replace('/browser/', ''));
+          } else {
+            filePath = path.join(BROWSER_DIR, pathname.substring(1));
+          }
+
+          const ext = path.extname(filePath);
+          const contentType = MIME[ext] || 'application/octet-stream';
+
+          fs.readFile(filePath, (err, data) => {
+            if (err) {
+              res.writeHead(404, { 'Content-Type': 'text/plain' });
+              return res.end(`Not found: ${pathname}`);
+            }
+            res.writeHead(200, { 'Content-Type': contentType });
+            res.end(data);
+          });
+        });
+
+        server.listen(PORT, HOST, () => {
+          console.log(`\n  ╔════════════════════════════════════════════╗`);
+          console.log(`  ║   🎨  intelliFont Canvas DNA Server         ║`);
+          console.log(`  ╚════════════════════════════════════════════╝`);
+          console.log(`\n  🚀  Server running at: http://${HOST}:${PORT}`);
+          console.log(`  🔬  Demo UI:           http://${HOST}:${PORT}/`);
+          console.log(`  📡  API endpoint:      http://${HOST}:${PORT}/api/identify-from-metrics`);
+          console.log(`  ❤️   Health check:      http://${HOST}:${PORT}/api/health`);
+          console.log(`\n  Press Ctrl+C to stop.\n`);
+        });
+
+        server.on('error', (err) => {
+          if (err.code === 'EADDRINUSE') {
+            console.error(`\n❌ Port ${PORT} is already in use.`);
+            console.error(`   Try: intellifont serve --port 3001`);
+          } else {
+            console.error(`\n❌ Server error: ${err.message}`);
+          }
+          process.exit(1);
+        });
+
+        // Keep process alive
+        process.on('SIGINT', () => {
+          console.log('\n  Shutting down...');
+          server.close(() => process.exit(0));
+        });
+
+        break; // Note: server is async, process stays alive via server.listen
+      }
+
+      case 'help':
+      default:
+        console.log("\nintelliFont Engine CLI");
+        console.log("Usage:");
+        console.log("  intellifont suggest <name> [--internet]    - Find matching fonts");
+        console.log("  intellifont resolve <name>                 - Fast lookup");
+        console.log("  intellifont inspect-url <url>              - [NEW] Identify all fonts on a webpage");
+        console.log("  intellifont inspect-url <url> --verbose    - [NEW] Show top-3 matches per font");
+        console.log("  intellifont serve                          - [NEW] Start Canvas DNA HTTP server (port 3000)");
+        console.log("  intellifont serve --port 8080              - [NEW] Start server on a custom port");
+        console.log("  intellifont stats                          - Engine & Cache metrics");
+        console.log("  intellifont scan                           - Refresh system font index");
+        console.log("  intellifont update                         - Sync with global CDN signatures");
+        console.log("  intellifont cache <stats|list|cleanup>     - Manage local cache");
+        console.log("  intellifont cache <pin|unpin> <name>       - Manage font pinning");
+        console.log("  intellifont export-metrics <name>          - Get binary DNA of a font");
+        console.log("\n  Canvas DNA (browser pixel inspection):");
+        console.log("    1. intellifont serve           → starts server + demo UI");
+        console.log("    2. open http://localhost:3000  → click any font sample");
+        break;
+    }
+  }
+  runCli().catch(console.error);
+}
+
+module.exports = {
+  // Name-based resolution
+  getFontSuggestions,
+  getEnhancedSuggestions,
+  normalizeFontName,
+  resolveFontBasic,
+  createFontFace,
+  // Cache management
+  pinFont,
+  unpinFont,
+  removeFromCache,
+  exportMetrics,
+  getEngineStats,
+  getCacheStats,
+  cleanupCache,
+  listPinnedFonts,
+  updateDatabase,
+  // Visual identification — file-based
+  identifyVisualFont,
+  identifyVisualFontBuffer,
+  aiSuggestSimilar,
+  aiSuggestSimilarBuffer,
+  extractGlyphSignature,
+  compareGlyphSignatures,
+  // Database building
+  buildGlyphDatabase,
+  // Canvas DNA — pixel metrics from browser Canvas API
+  identifyFromPixelMetrics,
+  // Image OCR preprocessing (Phase 2)
+  preprocessImageForFontId,
+  // Hybrid ML layer (Phase 4)
+  mlAvailable,
+  mlIdentifyGlyphs,
+};