chore: clean up repo for open source release

- Replace CRA boilerplate README with proper project documentation
- Add MIT LICENSE
- Clean package.json (name, description, author, license, repository)
- Remove CRA boilerplate files (logo.svg, App.test.js, setupTests.js, reportWebVitals.js)
- Remove dev artifacts (font-names-results/, scripts/, yarn.lock)
- Clean up index.html title and meta description
- Simplify .gitignore

Co-authored-by: Cursor <cursoragent@cursor.com>

.gitignore

@@ -1,34 +1,31 @@
-# dependencies
+# Dependencies
 /node_modules
 src/typography/new-pipe/node_modules
-src/typography/generated/
-/.pnp
-.pnp.js
-
-# testing
-/coverage
 
-# production
+# Build output
 /build
+/coverage
 
-# misc
-.DS_Store
+# Environment
 .env.local
 .env.development.local
 .env.test.local
 .env.production.local
 
+# OS
+.DS_Store
+
+# Logs
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 
+# Pipeline working directories
 src/typography/new-pipe/input
 src/typography/new-pipe/output
 src/typography/new-pipe/public
+src/typography/generated/
 
-# Large generated data (not needed for app)
+# Large generated data (regenerate with pipeline)
 public/data/embeddings.json
 public/data/font-map.json
-
-# Temp docs
-TEST_LIVE_UMAP.md

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Thibaud Frere
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -9,3 +9,132 @@ pinned: false
 app_build_command: "CI=false npm run build"
 app_file: "build/index.html"
 ---
+
+# FontMap
+
+An interactive map of 1,100+ Google Fonts organized by visual similarity, using [FontCLIP](https://github.com/kinit-sk/FontCLIP) embeddings and UMAP dimensionality reduction.
+
+Inspired by [IDEO's Font Map](https://medium.com/ideo-stories/organizing-the-world-of-fonts-with-ai-7d9e49ff2b25) (2017, Kevin Ho) — rebuilt from scratch with modern ML, fully open source, and documented.
+
+**[Live demo](https://huggingface.co/spaces/tfrere/fontmap)**
+
+![FontMap screenshot](https://huggingface.co/spaces/tfrere/fontmap/resolve/main/public/screenshot.png)
+
+## Features
+
+- **Visual similarity map** — fonts that look alike are physically close together
+- **1,192 Google Fonts** — full catalog, family variants merged
+- **Click any font** — see details + 5 nearest visual neighbors
+- **Filter by category** — serif, sans-serif, display, handwriting, monospace
+- **Category colors** — toggle color coding to see how clusters map to official categories
+- **Search** — find any font by name
+- **Zoom & pan** — explore the full map with smooth D3.js navigation
+
+## How it works
+
+```
+Font images ──→ FontCLIP (512D) ──→ PCA (50D) ──→ UMAP (2D) ──→ Interactive map
+                                         ↓
+                                    k-NN (similar fonts)
+```
+
+1. **Render** — each font is rendered as a 224×224 composite glyph image
+2. **Embed** — [FontCLIP](https://github.com/kinit-sk/FontCLIP) (CLIP ViT-B/32 fine-tuned for typography) encodes each image into a 512-dimensional vector
+3. **Reduce** — PCA compresses to 50D, then UMAP with spectral initialization projects to 2D (n_neighbors=12, min_dist=1.0)
+4. **Merge** — font family variants (Regular, Bold, Italic…) are fused into a single representative point
+5. **Neighbors** — k-NN is computed in the original 512D space for "similar fonts" recommendations
+6. **Visualize** — React + D3.js renders all glyphs from a single SVG sprite (zero individual network requests)
+
+## Getting started
+
+### Run locally
+
+```bash
+git clone https://github.com/tfrere/fontmap.git
+cd fontmap
+npm install
+npm start
+```
+
+Open [http://localhost:3000](http://localhost:3000).
+
+### Build for production
+
+```bash
+npm run build
+```
+
+### Deploy to Hugging Face Spaces
+
+The project is configured for [HF Spaces static SDK](https://huggingface.co/docs/hub/spaces-sdks-static) with a build step:
+
+```yaml
+sdk: static
+app_build_command: "CI=false npm run build"
+app_file: "build/index.html"
+```
+
+## Regenerating the map
+
+The embedding pipeline lives in `src/typography/new-pipe/`. See its [README](src/typography/new-pipe/README.md) for full instructions.
+
+**Quick summary:**
+
+```bash
+# 1. Generate FontCLIP embeddings (requires Python + GPU, ~1h one-time)
+cd src/typography/new-pipe/python-pipeline
+python run_fontclip.py
+
+# 2. Test different UMAP configurations
+cd ..
+npm run batch-umap
+npm run copy-to-debug
+# Compare visually at http://localhost:3000/#/debug-umap
+
+# 3. Deploy chosen config to production
+npm run deploy fontclip-spectral
+```
+
+## Project structure
+
+```
+fontmap/
+├── public/
+│   ├── data/
+│   │   ├── char/              # Individual glyph SVGs (~1,200 files)
+│   │   ├── sentences/         # Sentence preview SVGs
+│   │   ├── font-sprite.svg    # All glyphs in a single sprite (3 MB)
+│   │   └── typography_data.json  # Font positions + metadata
+│   └── debug-umap/            # Pre-computed UMAP configs for comparison
+├── src/
+│   ├── components/
+│   │   ├── FontMap/           # Main map component (production)
+│   │   ├── DebugUMAP/         # UMAP comparison tool (development)
+│   │   └── FontMapV2/         # Experimental canvas renderer
+│   ├── hooks/                 # Shared hooks (data loading, dark mode)
+│   ├── store/                 # Zustand state management
+│   └── typography/new-pipe/   # Embedding + UMAP generation pipeline
+│       └── python-pipeline/   # FontCLIP + PCA + UMAP (Python)
+└── package.json
+```
+
+## Tech stack
+
+| Layer | Tech |
+|-------|------|
+| Frontend | React 19, D3.js v7, Zustand |
+| Rendering | SVG sprite + D3 zoom/pan |
+| Embeddings | FontCLIP (CLIP ViT-B/32 fine-tuned for typography) |
+| Dim. reduction | PCA + UMAP (spectral init) via `umap-learn` |
+| Hosting | Hugging Face Spaces (static SDK) |
+
+## Credits
+
+- **[FontCLIP](https://github.com/kinit-sk/FontCLIP)** — Typography-aware CLIP model by KInIT
+- **[IDEO Font Map](https://medium.com/ideo-stories/organizing-the-world-of-fonts-with-ai-7d9e49ff2b25)** — Original inspiration by Kevin Ho (2017)
+- **[Google Fonts](https://fonts.google.com)** — Font catalog
+- **[UMAP](https://umap-learn.readthedocs.io/)** — Dimensionality reduction by Leland McInnes
+
+## License
+
+MIT

package.json

@@ -1,8 +1,14 @@
 {
-  "name": "react-template",
-  "version": "0.1.0",
-  "private": true,
+  "name": "fontmap",
+  "version": "1.0.0",
+  "description": "Interactive map of 1,100+ Google Fonts organized by visual similarity using FontCLIP + UMAP",
+  "author": "Thibaud Frere",
+  "license": "MIT",
   "homepage": ".",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tfrere/fontmap"
+  },
   "dependencies": {
     "@testing-library/dom": "^10.4.0",
     "@testing-library/jest-dom": "^6.6.3",

public/index.html

@@ -5,43 +5,16 @@
     <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="theme-color" content="#000000" />
-    <meta
-      name="description"
-      content="Web site created using create-react-app"
-    />
+    <meta name="description" content="Interactive map of 1,100+ Google Fonts organized by visual similarity using FontCLIP + UMAP" />
     <link rel="apple-touch-icon" href="%PUBLIC_URL%/logo192.png" />
-    <!--
-      manifest.json provides metadata used when your web app is installed on a
-      user's mobile device or desktop. See https://developers.google.com/web/fundamentals/web-app-manifest/
-    -->
     <link rel="manifest" href="%PUBLIC_URL%/manifest.json" />
-    <!-- Google Fonts -->
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
     <link href="https://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@400;600;700&display=swap" rel="stylesheet">
-    <!--
-      Notice the use of %PUBLIC_URL% in the tags above.
-      It will be replaced with the URL of the `public` folder during the build.
-      Only files inside the `public` folder can be referenced from the HTML.
-
-      Unlike "/favicon.ico" or "favicon.ico", "%PUBLIC_URL%/favicon.ico" will
-      work correctly both with client-side routing and a non-root public URL.
-      Learn how to configure a non-root public URL by running `npm run build`.
-    -->
-    <title>React App</title>
+    <title>FontMap</title>
   </head>
   <body>
     <noscript>You need to enable JavaScript to run this app.</noscript>
     <div id="root"></div>
-    <!--
-      This HTML file is a template.
-      If you open it directly in the browser, you will see an empty page.
-
-      You can add webfonts, meta tags, or analytics to this file.
-      The build step will place the bundled scripts into the <body> tag.
-
-      To begin the development, run `npm start` or `yarn start`.
-      To create a production bundle, use `npm run build` or `yarn build`.
-    -->
   </body>
 </html>

src/App.test.js

@@ -1,8 +0,0 @@
-import { render, screen } from '@testing-library/react';
-import App from './App';
-
-test('renders learn react link', () => {
-  render(<App />);
-  const linkElement = screen.getByText(/learn react/i);
-  expect(linkElement).toBeInTheDocument();
-});

src/index.js

@@ -2,7 +2,6 @@ import React from 'react';
 import ReactDOM from 'react-dom/client';
 import './index.css';
 import App from './App';
-import reportWebVitals from './reportWebVitals';
 
 const root = ReactDOM.createRoot(document.getElementById('root'));
 root.render(
@@ -10,8 +9,3 @@ root.render(
     <App />
   </React.StrictMode>
 );
-
-// If you want to start measuring performance in your app, pass a function
-// to log results (for example: reportWebVitals(console.log))
-// or send to an analytics endpoint. Learn more: https://bit.ly/CRA-vitals
-reportWebVitals();

src/reportWebVitals.js

@@ -1,13 +0,0 @@
-const reportWebVitals = onPerfEntry => {
-  if (onPerfEntry && onPerfEntry instanceof Function) {
-    import('web-vitals').then(({ getCLS, getFID, getFCP, getLCP, getTTFB }) => {
-      getCLS(onPerfEntry);
-      getFID(onPerfEntry);
-      getFCP(onPerfEntry);
-      getLCP(onPerfEntry);
-      getTTFB(onPerfEntry);
-    });
-  }
-};
-
-export default reportWebVitals;

src/setupTests.js

@@ -1,5 +0,0 @@
-// jest-dom adds custom jest matchers for asserting on DOM nodes.
-// allows you to do things like:
-// expect(element).toHaveTextContent(/react/i)
-// learn more: https://github.com/testing-library/jest-dom
-import '@testing-library/jest-dom';