intellifont-engine 1.0.0 → 2.0.0

package/README.md

@@ -1,173 +1,355 @@
-# intelliFont Engine
-
-**The Ultimate Professional Font Recognition & Suggestion Toolkit.**
-
-`intellifont-engine` is a high-performance, Rust-powered engine designed for mission-critical design applications. Whether you are building a PDF editor, a web builder, or a design tool, this engine ensures that no font ever goes missing and every layout remains pixel-perfect.
-
----
-
-## Why intelliFont?
-
-Traditional font matching relies on exact string comparisons, which fail if the user's system names a font slightly differently (e.g., "HelveticaNeue" vs "Helvetica Neue"). 
-
-**intelliFont** uses **Biometric Metric Matching**—analyzing the physical architecture of the font itself (ascenders, descenders, x-height, and cap-height)—to find the perfect match or the best possible substitute.
-
-### Key Capabilities:
-- **Blazing Speed**: Rust-core execution means sub-1ms response times for local lookups.
-- **Pre-Seeded Database**: Comes with **2,000+ popular font signatures** (Google Fonts, System Standards) embedded in a highly compressed 4.5MB binary asset.
-- **Layout Authority**: Exports precise physical metrics to ensure PDF and Canvas layouts never shift during font substitution.
-- **Hybrid Intelligence**: Scans local OS fonts and queries global CDNs (Google, Fontsource) in parallel.
-- **Legal Guardrails**: Real-time license detection for OFL, Apache, and commercial fonts, protecting users from legal risks.
-
----
-
-## Architecture Overview
-
-The engine is built on a "Service-Core" architecture:
-1.  **The Rust Core**: Handles heavy-duty binary parsing, Brotli decompression of the signature database, and parallel network queries using Tokio.
-2.  **The NAPI-RS Bridge**: Provides a zero-copy memory bridge between Rust and Node.js, ensuring that huge font lists don't cause garbage collection lag.
-3.  **The Metadata Cache**: A dual-layer cache (Memory + Persistent Disk) that learns from every search, making web results instant and offline-ready on the next launch.
-
----
-
-##  Installation
-
-### As a Library (Recommended)
-Add it to your React, Vue, or Node.js project:
-```bash
-npm install intellifont-engine
-```
-
-### As a Global CLI Tool
-Powerful font management directly from your terminal:
-```bash
-npm install -g intellifont-engine
-```
-
----
-
-## 🛠️ CLI Usage (The 'intellifont' command)
-
-Once installed globally, `intellifont` provides a robust set of tools for developers and system administrators.
-
-### Core Commands
-
-| Command | Description |
-| :--- | :--- |
-| `intellifont stats` | Display exhaustive engine metrics: font counts, database compression ratio, and cache health. |
-| `intellifont resolve "Font"` | Performs a high-speed resolution using local assets and the metadata cache. |
-| `intellifont tiered "Font"` | Advanced similarity analysis. Returns results in 90% (Exact) and 80% (Similar) tiers. |
-| `intellifont tiered "Font" --internet` | Activate global CDN lookup (Google Fonts, Fontsource) if local matches are insufficient. |
-| `intellifont find-similar "Font"` | Identify fonts that are visually or metrically similar to a target baseline font. |
-| `intellifont check-license "Font"` | Analyze licensing metadata for commercial safety and provide free equivalents. |
-| `intellifont scan [--detailed]` | Deep recursive scan of system font directories to index new assets. |
-| `intellifont update` | Synchronize local signatures with the global repository and regenerate binary indexes. |
-| `intellifont setup` | Guided 3-step configuration for memory limits and provider priorities. |
-| `intellifont version` | Display engine version, build architecture, and capability flags. |
-
-### Cache Management (`intellifont cache <command>`)
-
-| Subcommand | Description |
-| :--- | :--- |
-| `cache stats` | View hit rates, memory footprint, and disk usage of the local cache. |
-| `cache cleanup` | Remove stale entries. Use `--aggressive` to clear single-use fonts. |
-| `cache pin "Font"` | Lock a font permanently in the cache so it is never evicted. |
-| `cache unpin "Font"` | Release a font from the permanent cache lock. |
-| `cache list` | List all manually and automatically pinned (highly used) fonts. |
-| `cache suggest` | Analyze usage patterns and suggest non-pinned entries for manual removal. |
-
-### Configuration (`intellifont config <command>`)
-
-| Subcommand | Description |
-| :--- | :--- |
-| `config show` | View current engine limits (Memory, Disk, Web Access). |
-| `config set <key> <val>` | Directly modify configuration (e.g., `intellifont config set memory_limit 16`). |
-| `config reset` | Restore all engine settings to factory defaults. |
-| `config export <path>` | Export your current setup to a `.toml` file for team sharing. |
-| `config import <path>` | Load a shared configuration file to synchronize settings across environments. |
-
----
-
-## JavaScript API
-
-`intellifont-engine` provides a simple, Promise-based API for Node.js environments.
-
-### `getEnhancedSuggestions(name, useWebFonts)`
-The primary entry point for building "Suggested Fonts" dropdowns.
-
-```javascript
-const { getEnhancedSuggestions } = require('intellifont-engine');
-
-async function resolveFont(inputName) {
-  // Parallel search: Local System + Global Fontsource/Google
-  const results = await getEnhancedSuggestions(inputName, true);
-  
-  results.forEach(res => {
-    console.log(`Match Found: ${res.family}`);
-    console.log(`Similarity: ${(res.score * 100).toFixed(1)}%`);
-    
-    // License Guardrail
-    if (res.isCriticalLicenseWarning) {
-      console.warn("🚫 Commercial License Required - Consider a free alternative.");
-    }
-  });
-}
-```
-
-### `exportMetrics(fontName)`
-Returns the physical "DNA" of a font. Essential for layout-stable PDF generators.
-
-```javascript
-const { exportMetrics } = require('intellifont-engine');
-
-const metrics = exportMetrics("Inter");
-// Returns:
-// {
-//   family: "Inter",
-//   ascender: 0.72,
-//   descender: -0.21,
-//   capHeight: 0.68,
-//   widthFactor: 1.05
-// }
-```
-
----
-
-## Advanced Features
-
-### Triple-Layer Safety Net
-If a font is missing, intelliFont executes its survival strategy:
-1.  **Direct Local Match**: Scans the user's OS fonts instantly.
-2.  **CDN Deep Search**: Queries Google Fonts and Fontsource in parallel (2-second timeout).
-3.  **Metric Substitution**: If nowhere to be found, it analyzes the missing font's metrics and finds a "Twin" on the local system to prevent layout breaking.
-
-### Learning Mode (Dynamic Caching)
-The engine learns your project's typography. Any font resolved from the web is automatically "fingerprinted" and stored in the **Persistent Disk Cache**. Next time you search for that font, it will be found instantly—even without an internet connection.
-
----
-
-## 💰 Licensing & Support
-
-`intellifont-engine` is dual-licensed:
-- **Software**: The engine code is licensed under **Apache-2.0**.
-- **Data**: The included **Core Font Database** (~2,000 signatures) is free for use. Access to the **Extended Intelligence Database** (20,000+ signatures) requires a Pro license.
-
-For **Enterprise-grade** requirements:
-- 🚀 **20,000+ Certified Font Signatures**
-- 🔒 **Air-gapped Offline Databases** (for secure environments)
-- 🎧 **Premium Support & Custom Provider Integration**
-
-Visit [intellifont.pro](https://intellifont.pro) or contact our enterprise team.
-
----
-
-## Security
-
-Your privacy is paramount. intelliFont's local scanner:
-- Is restricted to common system font directories.
-- Never transmits actual font files; only anonymous biometric signatures (metrics).
-- Uses Rust's memory safety to prevent overflow exploits common in font parsing.
-
----
-
-© 2026 intelliFont Engine
+# Intellifont — AI-Powered Font Recognition Engine
+
+**Identify any font in seconds.** Intellifont uses AI-driven visual matching to recognize fonts from images, documents, websites, and web pages. Completely offline, private, and runs in your browser or Node.js. No internet required, no data sent to servers.
+
+Works on screenshots, PDFs, Word documents, PowerPoint presentations, and images. Returns the top matching fonts with confidence scores.
+
+---
+
+## Where to Get Intellifont
+
+**Choose your platform:**
+
+| Platform | Installation | Use Case |
+|---|---|---|
+| **Chrome Extension** | [Download v2.0.0](https://github.com/magic-emperor/Intellifont/releases/download/v2.0.0/intellifont-chrome-2.0.0.zip) \| [Load unpacked](#browser-extension-setup) | Right-click on any image in Chrome |
+| **Firefox Extension** | [Download v2.0.0](https://github.com/magic-emperor/Intellifont/releases/download/v2.0.0/intellifont-firefox-2.0.0.zip) \| [Load unpacked](#browser-extension-setup) | Right-click on any image in Firefox |
+| **NPM Package** | `npm install intellifont-engine` | Identify fonts in Node.js apps |
+| **WASM** | `npm install intellifont-wasm` | Identify fonts in browsers / serverless |
+| **Server API** | `git clone && npm start` | REST API on localhost:3001 |
+
+---
+
+## What It Can Do
+
+| Input | Method | Accuracy |
+|---|---|---|
+| **Font file** (TTF/OTF/WOFF) | Direct file analysis | ~95% |
+| **Website font** | URL inspection | ~95% |
+| **PDF / Document** | Embedded font extraction | ~95% |
+| **Text in image** | Visual analysis | 92% top-1 \* |
+
+\* *Accuracy varies by image quality. We actively improve this with every release.*
+
+---
+
+## Quick Start
+
+### For Users — Browser Extension
+**Chrome & Firefox** — load unpacked (coming to stores):
+
+1. Clone: `git clone https://github.com/magic-emperor/Intellifont.git`
+2. **Chrome**: `chrome://extensions`  Developer Mode  Load unpacked  select `extension/`
+3. **Firefox**: `about:debugging`  Load Temporary Add-on  select `extension-firefox/manifest.json`
+4. Right-click any image  **"Identify font in image"**
+
+### For Developers — NPM Package
+
+```bash
+npm install intellifont-engine
+```
+
+```javascript
+const intellifont = require('intellifont-engine');
+
+// Identify font from a file
+const matches = intellifont.identifyVisualFont('./sample.ttf', 'Hello');
+console.log(matches);
+// Output:
+// [
+//   { family: 'Roboto', confidence: 0.98 },
+//   { family: 'Open Sans', confidence: 0.94 },
+//   ...
+// ]
+```
+
+### WASM (Browser / Serverless)
+
+```bash
+npm install intellifont-wasm
+```
+
+```javascript
+import init from 'intellifont-wasm';
+
+const engine = await init();
+const results = engine.identifyFont(glyphMetrics, 8);
+```
+
+---
+
+## Browser Extension Setup
+
+### Installing the Chrome Extension
+
+1. **Download** the extension: [intellifont-chrome-2.0.0.zip](https://github.com/magic-emperor/Intellifont/releases/download/v2.0.0/intellifont-chrome-2.0.0.zip)
+2. **Extract** the ZIP file to a folder (e.g., `Downloads/intellifont-chrome`)
+3. Open **Chrome** and go to `chrome://extensions`
+4. Enable **Developer Mode** (toggle in top-right corner)
+5. Click **Load unpacked**
+6. Select the extracted `intellifont-chrome` folder
+7. Extension appears in your toolbar
+8. **Use it**: Right-click any image  "Identify font in image"
+
+### Installing the Firefox Extension
+
+1. **Download** the extension: [intellifont-firefox-2.0.0.zip](https://github.com/magic-emperor/Intellifont/releases/download/v2.0.0/intellifont-firefox-2.0.0.zip)
+2. **Extract** the ZIP file to a folder (e.g., `Downloads/intellifont-firefox`)
+3. Open **Firefox** and go to `about:debugging`
+4. Click **This Firefox** (left sidebar)
+5. Click **Load Temporary Add-on**
+6. Select any file from the extracted `intellifont-firefox` folder (e.g., `manifest.json`)
+7. Extension appears in your toolbar
+8. **Use it**: Right-click any image  "Identify font"
+
+### How to Use the Extension
+
+1. **Right-click on any image** on any webpage
+2. Select **"Identify font in image"** (or "Identify font in image region..." for partial image)
+3. Wait for analysis (usually 1-2 seconds)
+4. A popup appears with:
+   - **Top matching fonts** (confidence % shown)
+   - **Font family, weight, style** for each match
+   - Copy button for easy access
+
+### Known Extension Limitations
+
+- Only works on images you can right-click (no cross-origin restrictions thanks to local processing)
+- Image must contain **readable text** (8px+ font size)
+- Accuracy varies by image quality (see [Accuracy](#accuracy-by-condition))
+- **Rotation**: Deskew images first if heavily tilted
+
+---
+
+## Delivery Channels
+
+###  **Browser Extension** (Chrome & Firefox)
+Right-click on images  identify fonts. Offline first, 100% private.
+
+**Download:**
+- **Chrome**: [Download v2.0.0 ZIP](https://github.com/magic-emperor/Intellifont/releases/download/v2.0.0/intellifont-chrome-2.0.0.zip)
+- **Firefox**: [Download v2.0.0 ZIP](https://github.com/magic-emperor/Intellifont/releases/download/v2.0.0/intellifont-firefox-2.0.0.zip)
+
+**Installation** (see [Browser Extension Setup](#browser-extension-setup) below):
+1. Extract the ZIP file
+2. Load unpacked in Chrome/Firefox Developer Mode
+3. Right-click any image  "Identify font"
+
+**Coming soon**: Chrome Web Store & Firefox Add-ons (submit after testing)
+
+###  **NPM Package** (`intellifont-engine`)
+```bash
+npm install intellifont-engine
+```
+
+20+ functions for font identification, analysis, and caching:
+- `identifyVisualFont()` — Identify from TTF/OTF file
+- `identifyVisualFontBuffer()` — Identify from buffer
+- `aiSuggestSimilar()` — Find similar fonts (ML)
+- `getFontSuggestions()` — Name-based search
+- `analyzeImage()` — Full image processing
+
+**TypeScript types included.**
+
+###  **WASM Module**
+Pure JavaScript, zero native dependencies. Perfect for browsers, serverless, Deno.
+
+```bash
+npm install intellifont-wasm
+```
+
+###  **API Server**
+```bash
+cd server && npm start
+# POST /api/identify — upload image
+# GET /api/identify-url?url=... — scan web page
+# POST /api/identify-document — analyze PDF/DOCX
+# GET /api/similar?font=Roboto — find alternatives
+```
+
+---
+
+## Accuracy by Condition
+
+| Scenario | Accuracy |
+|---|---|
+| Font file (TTF/OTF) | ~95% |
+| Web font (downloaded) | ~95% |
+| PDF/Document embedded font | ~95% |
+| Image: clean text | 92% top-1 |
+| Image: mixed conditions | 57% top-5 |
+
+*Image accuracy depends on text quality, size, contrast, and clarity. Rotation is a known limitation (improving).*
+
+---
+
+## How It Works
+
+```
+Input (Image / Document / Font / URL)
+       
+[Preprocessing]   Binarize, deskew, extract text regions
+       
+[Glyph Analysis]  Compute pixel metrics (density, symmetry, strokes, serif)
+       
+[Visual Matching]  Compare 64—64 thumbnails against 2,042 fonts
+       
+[ML Enhancement]  Optional: CosFace embeddings for better ranking
+       
+[Return Top 8]    Sorted by confidence score
+       
+Output: Font family, weight, confidence %
+```
+
+**Key points:**
+- **Visual matching**: Character-agnostic (label-independent)
+- **ML-powered**: Trained on 2,042 real fonts
+- **Offline**: All data bundled, no network calls
+- **Private**: Images never leave your device
+
+---
+
+## Full API Reference
+
+### Node.js Exports
+
+**Core Identification**
+```javascript
+identifyVisualFont(fontPath: string, characters: string, limit?: number): VisualMatch[]
+identifyVisualFontBuffer(buffer: Buffer, characters: string, limit?: number): VisualMatch[]
+aiSuggestSimilar(fontPath: string, limit?: number): AiSuggestion[]
+getFontSuggestions(fontName: string, includeInternet?: boolean): Promise<Suggestion[]>
+```
+
+**Image Processing**
+```javascript
+analyzeImage(imageSource: string | Buffer): Promise<ImageAnalysisResult>
+extractGlyphSignature(fontPath: string, character: string): GlyphSignature
+compareGlyphSignatures(fontPathA: string, fontPathB: string, character: string): number
+```
+
+**Utilities**
+```javascript
+normalizeFontName(fontName: string): string
+```
+
+**Cache Management**
+```javascript
+pinFont(fontName: string): void
+unpinFont(fontName: string): void
+listPinnedFonts(): string[]
+cleanupCache(aggressive?: boolean): number
+getCacheStats(): CacheStats
+getEngineStats(): EngineStats
+```
+
+Full TypeScript types in `index.d.ts`.
+
+---
+
+## Browser Support
+
+| Browser | Version | Status |
+|---|---|---|
+| Chrome | 80+ |  Full |
+| Firefox | 109+ |  Full |
+| Edge | 80+ |  Full |
+| Safari | 14+ |  Planned |
+
+WASM module works on 99%+ of users' devices.
+
+---
+
+## Database
+
+**2,042 fonts** covering:
+- Google Fonts (complete)
+- System fonts (Windows, macOS, Linux)
+- Popular design fonts
+- Open-source typefaces
+
+**Included in extension and NPM:**
+- Glyph signatures: 2 MB
+- Pixel signatures: 1.7 MB
+- Visual thumbnails: 15 MB
+
+---
+
+## Performance
+
+| Task | Time | Notes |
+|---|---|---|
+| Identify 1 glyph | 5-50ms | CPU-bound |
+| Full image analysis | 100-500ms | Includes preprocessing |
+| ML similarity ranking | 10-100ms | Optional |
+
+No initialization delay. Ready immediately.
+
+---
+
+## Privacy & Security
+
+ **100% Offline** — All processing on your device  
+ **No Tracking** — Zero telemetry  
+ **No Uploads** — Images never leave your computer  
+ **Open Source** — Inspect the code  
+ **Apache 2.0** — Free for commercial use  
+
+---
+
+## Installation
+
+### From NPM
+```bash
+npm install intellifont-engine
+```
+
+### From Source (Development)
+```bash
+git clone https://github.com/magic-emperor/Intellifont.git
+cd Intellifont
+
+# Build Rust bindings
+cd Rust/font-resolver
+cargo build --release
+cd bindings/node
+npm install
+npm run build
+```
+
+---
+
+## Known Limitations
+
+- **Rotation**: Tilted text is difficult (deskew first)
+- **Rare fonts**: Only covers 2,042 fonts (expand DB for your use case)
+- **Stylized text**: Heavily styled/outlined text has lower accuracy
+- **Small text**: < 8px is hard to analyze
+
+---
+
+## Contributing
+
+Found a bug? Want to help? Open an issue or PR on [GitHub](https://github.com/magic-emperor/Intellifont).
+
+---
+
+## License
+
+**Apache License 2.0.** See [LICENSE](LICENSE).
+
+---
+
+## Credits
+
+- **Rust** engine with NAPI-RS bindings
+- **WebAssembly** for browser support
+- **CosFace** ML embeddings
+- **2,042 test fonts** for training
+
+---
+
+** 2026 Intellifont Engine. Built by the Intellifont Team.**
+
+Questions? Email [faizan77603@gmail.com](mailto:faizan77603@gmail.com) or open an issue on [GitHub](https://github.com/magic-emperor/Intellifont).
+