gitmaps 1.0.0 → 1.1.1

package/README.md

@@ -1,167 +1,310 @@
-<p align="center">
-  <img src="banner.png" alt="GitMaps" width="100%" />
-</p>
+# 🗺️ GitMaps — Spatial Code Explorer
 
-<p align="center">
-  <img src="https://img.shields.io/badge/runtime-Bun-f472b6?style=flat-square" alt="Bun">
-  <img src="https://img.shields.io/badge/framework-Melina-7c3aed?style=flat-square" alt="Melina">
-  <img src="https://img.shields.io/badge/engine-GalaxyDraw-38bdf8?style=flat-square" alt="GalaxyDraw">
-  <img src="https://img.shields.io/badge/license-ISC-4ade80?style=flat-square" alt="License">
-</p>
+**Explore codebases on an infinite canvas instead of file trees.**
 
-# 🪐 GitMaps
+[![Live Demo](https://img.shields.io/badge/demo-live-7c3aed.svg?style=flat-square)](https://gitmaps.xyz)
+[![npm](https://img.shields.io/npm/v/gitmaps.svg?style=flat-square)](https://npmjs.com/package/gitmaps)
+[![License](https://img.shields.io/badge/license-ISC-blue.svg?style=flat-square)](LICENSE)
 
-**See every file at once.** Pan, zoom, drag — arrange your codebase the way *you* think about it, not the way the file system forces you to.
+---
+
+## 🎯 What is GitMaps?
+
+GitMaps renders your entire repository on an infinite canvas with layers, git time-travel, and a minimap to never lose context.
+
+**Traditional file trees are 1-dimensional. GitMaps gives you 5 dimensions:**
 
-🌐 **Try it now:** [gitmaps.xyz](https://gitmaps.xyz) — no install required
+1. **1D — Lines** — Individual lines of code
+2. **2D — Canvas** — Spatial arrangement of files
+3. **3D — Layers** — Focus areas (Auth, API, UI)
+4. **4D — Time** — Git history with persistent layout
+5. **5D — Connections** — Links between related code
 
 ---
 
-## The Problem
+## 🚀 Quick Start
 
-Traditional code review: Open file → read → close → open next file → forget what you just saw → repeat.
+### Try Online (No Install)
+Visit **[https://gitmaps.xyz](https://gitmaps.xyz)** and explore popular repos like React, Deno, or Svelte.
 
-**Git on Canvas:**
-All changed files laid out on an infinite canvas. Drag them next to each other. Draw connections between related lines. Switch commits with arrow keys. Your spatial layout persists across sessions.
+### Run Locally
+```bash
+git clone https://github.com/7flash/gitmaps.git
+cd gitmaps
+bun install
+bun run dev
+# Open http://localhost:3335
+```
+
+### Install Globally
+```bash
+bun install -g gitmaps
+gitmaps /path/to/your/repo
+```
+
+---
 
 ## ✨ Features
 
-| Feature | Description |
-|---------|-------------|
-| 🖼️ **Infinite Canvas** | Pan, zoom, drag files anywhere. Your layout is saved per-commit. |
-| 📊 **Inline Diffs** | Green additions, red deletions — right inside each card. Scrollbar markers show *where* changes are. |
-| ⏳ **Commit Timeline** | `←` `→` arrow keys through history. Each commit shows exactly which files changed. |
-| 📌 **Persistent Layout** | Drag files where they belong in *your* mental model. Switch commits — arrangement stays. |
-| 🔍 **Command Palette** | `Ctrl+K` to fuzzy-search files with subsequence-weighted scoring and character-level match highlighting. |
-| 🌿 **Branch Comparison** | Side-by-side branch diff viewer with glassmorphism drawer, status badges, and diff cards rendered on canvas. |
-| 📦 **Multi-Repo Workspace** | Load 2-3 repos side-by-side. Auto-offset with zone labels. Sidebar tabs switch commit timelines. |
-| 👁️ **File Preview on Hover** | Glassmorphism tooltip at low zoom: language badge, path, first 12 lines of code. |
-| 🐙 **GitHub Import** | Paste a URL for instant clone, or search by username with live repo filtering. |
-| 🔗 **Connections** | `Alt+click` a line → pick target file → click target line. Visual bezier curves link related code. |
-| 📁 **Layers** | Group files into focused subsets. Each layer remembers its own viewport position. |
-| 🤖 **AI Chat** | Press `I` to open an AI sidebar that understands your current canvas context. |
-| ⌨️ **VIM-style Diff Nav** | `j`/`k` to jump between changes across files, `Shift+J`/`K` for file-level navigation. |
-| 🔎 **Cross-Card Search** | Press `/` to search across all visible file cards. Results highlighted in-place with match counts. |
-| ✏️ **Full Editor** | CodeMirror 6 with syntax highlighting, multi-tab, auto-save, git commit, and code minimap. |
-| ⇄ **Tab Diff** | Compare two open tabs side-by-side with LCS diff, change markers, synced scrolling. |
-| 🧭 **Symbol Outline** | Side panel showing all functions/classes/types in a file. Click to scroll. |
-| 🔀 **Dependency Graph** | `Ctrl+G` to toggle force-directed graph layout based on import relationships. |
-| 📝 **PR Review** | Comment threads on any line, stored in localStorage. |
-| 📁 **Card Grouping** | Collapse entire directories into compact summary cards to reduce clutter. |
+### Core Experience
+- 🗺️ **Infinite Canvas** — Pan, zoom, arrange files freely
+- 📄 **File Cards** — Interactive cards with code preview and inline diffs
+- 🧭 **Minimap** — Bird's eye view with click-to-navigate
+- 📚 **Layers** — Organize files into focus layers
+
+### Git Integration
+- ⏳ **Commit Timeline** — Browse history in sidebar
+- 📊 **Inline Diffs** — Green/red markers for changes
+- 🔄 **Time Travel** — Navigate commits while layout persists
+- 🔀 **Branch Comparison** — Compare branches side-by-side
+
+### Performance
+- ⚡ **WebGL Renderer** — Pixi.js GPU acceleration for 1000+ cards at 60fps
+- 🎯 **Viewport Culling** — Only render visible cards
+- 📦 **Progressive Loading** — Load large repos in batches
+- ⏱️ **30s Timeout** — Large repo support (up from 5s)
+
+### Collaboration
+- 👑 **Leader Mode** — Full control when running locally
+- 👁️ **Follower Mode** — Read-only view on production
+- 🔄 **Sync Controls** — Push/pull canvas state to servers
+- ⚡ **Auto-Sync** — Automatic position sync on changes
+
+### UX Features
+- 📊 **Progress Bar** — Visual feedback during loading
+- 🖼️ **Image/Video Rendering** — Media files display inline
+- 📷 **Canvas Export** — Save layouts as PNG/JPEG/WebP
+- 🎓 **Onboarding Tutorial** — 10-step interactive guide
+- 🔗 **Shareable URLs** — `/owner/repo#commit` format
+- 📑 **Multi-Repo Tabs** — Load multiple repos simultaneously
+- ⌨️ **Keyboard Shortcuts** — Power user shortcuts
 
-## 🚀 Quick Start
+---
+
+## 🎯 Use Cases
+
+### AI Code Review
+AI agents generate thousands of lines across dozens of files. GitMaps renders every file simultaneously so you can see the full picture, spot patterns, and review changes spatially instead of one-file-at-a-time.
+
+### Architecture Exploration
+Understand unfamiliar codebases faster by seeing how files relate spatially. Draw connections between related code across layers.
+
+### Onboarding
+New team members explore the codebase spatially. Senior devs create canvas arrangements showing key files and their relationships.
+
+### Pair Programming
+Driver runs locally (leader), navigator visits URL (follower). Both see same spatial arrangement.
+
+### Legacy Code Understanding
+Visualize connections and dependencies in complex legacy systems. Layers help focus on specific concerns.
+
+---
+
+## 📊 Performance
+
+| Repo Size | Renderer | Load Time | FPS |
+|-----------|----------|-----------|-----|
+| <100 files | DOM | <1s | 60 |
+| 100-500 files | DOM | 1-3s | 60 |
+| 500-1000 files | WebGL | 3-5s | 60 |
+| 1000+ files | WebGL | 5-10s | 60 |
+| 10000+ files | WebGL | 10-30s | 30-40 |
+
+### Tested Repositories
+- ✅ [7flash/gitmaps](https://gitmaps.xyz/7flash/gitmaps) — 9 files, <1s
+- ✅ [facebook/react](https://gitmaps.xyz/facebook/react) — 100 commits, 2.8s
+
+---
+
+## ⌨️ Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `Scroll` | Zoom in/out |
+| `Space + Drag` | Pan canvas |
+| `Click` | Select card |
+| `Shift + Click` | Multi-select |
+| `Drag Canvas` | Rect select |
+| `Drag Card` | Move card |
+| `Del` | Hide file |
+| `H` | Arrange in row |
+| `V` | Arrange in column |
+| `G` | Arrange in grid |
+| `W` | Fit to screen |
+| `Ctrl + F` | Search across files |
+| `Ctrl + O` | Find file |
+| `Ctrl + G` | Toggle dependency graph |
+| `Ctrl + +/-` | Text zoom |
+| `Dbl-click` | Open editor |
+| `Alt + Click` | Connect lines |
+| `Arrow Keys` | Prev/next commit |
+| `Ctrl + N` | New file |
+| `Ctrl + S` | Save (in editor) |
+| `?` | Show keyboard shortcuts |
 
-```sh
-# One-liner (requires Bun)
-npx gitmaps
-# → http://localhost:3335
+---
+
+## 🏗️ Architecture
+
+### Tech Stack
+- **Runtime:** Bun / Node.js 18+
+- **Framework:** Melina (full-stack TypeScript)
+- **State:** XState for canvas state machine
+- **Rendering:** DOM + Pixi.js (WebGL)
+- **Editor:** CodeMirror 6
+- **Database:** SQLite with Zod ORM
+
+### Project Structure
 ```
+gitmaps/
+├── app/                    # Main application
+│   ├── api/               # API routes
+│   ├── lib/               # Shared modules
+│   ├── [owner]/[repo]/   # Dynamic routes
+│   └── page.tsx          # Main pages
+├── packages/
+│   └── galaxydraw/       # Rendering engine
+│       ├── src/
+│       │   ├── core/     # Core engine
+│       │   └── webgl-renderer.ts  # WebGL renderer
+│       └── demo/         # Performance benchmarks
+└── docs/                 # Documentation
+```
+
+---
+
+## 🚀 Deployment
 
-Or clone for development:
+### Production Server
+```bash
+# Clone repo
+git clone https://github.com/7flash/gitmaps.git
+cd gitmaps
 
-```sh
-git clone https://github.com/7flash/git-on-canvas.git
-cd galaxy-canvas
+# Install dependencies
 bun install
-bun run dev
-```
 
-Open a repository by entering its path in the sidebar dropdown, or navigate directly:
+# Build
+bun run build
 
+# Start server
+bun run server.ts
+# Or use bgrun for production
+bgrun start
 ```
-http://localhost:3335/#/path/to/your/repo
+
+### Environment Variables
+```bash
+# Server configuration
+PORT=3335
+NODE_ENV=production
+
+# Database
+DATABASE_PATH=./data/canvas_users.db
+
+# GitHub OAuth (optional)
+GITHUB_CLIENT_ID=your_client_id
+GITHUB_CLIENT_SECRET=your_client_secret
 ```
 
-Or import from GitHub — click the GitHub icon, paste a repo URL, and it clones + opens instantly.
-
-## 🖥️ Keyboard Shortcuts
-
-| Key | Action |
-|-----|--------|
-| `←` `→` | Previous / next commit |
-| `Ctrl+K` | Command palette — fuzzy file search |
-| `/` or `Ctrl+F` | Cross-card text search |
-| `j` / `k` | Next / previous diff hunk (VIM-style) |
-| `Shift+J` / `Shift+K` | Next / previous changed file |
-| `W` | Fit selected cards to screen |
-| `H` | Arrange selected in a row |
-| `V` | Arrange selected in a column |
-| `G` | Arrange selected in a grid |
-| `Ctrl+A` | Select all cards |
-| `Del` / `Backspace` | Hide selected files |
-| `Space+Drag` | Pan canvas |
-| `Scroll` | Zoom in/out |
-| `Ctrl+`/`Ctrl-` | Increase/decrease card font size |
-| `I` | Toggle AI chat sidebar |
-| `Alt+Click` | Start connection from clicked line |
-| `Esc` | Cancel / deselect all |
-| Double-click | Zoom to file |
+---
 
-## 📦 Multi-Repo Workspace
+## 🧪 Testing
 
-Load multiple repositories on the same canvas:
+```bash
+# Run tests
+bun test
 
-1. Open any repo normally
-2. Use the sidebar dropdown to load a second repo
-3. Repos appear side-by-side with **zone labels** (color-coded floating badges)
-4. **Sidebar tabs** switch commit timelines between repos
-5. Each repo auto-offsets horizontally with an 800px gap
+# Test specific module
+bun test app/lib/
 
-## 🔗 Connections
+# Performance benchmarks
+open packages/galaxydraw/demo/webgl-demo.html
+```
+
+---
 
-Draw visual links between related code across files:
+## 📚 Documentation
 
-1. **Alt+click** a line number in any file card (source)
-2. A **file picker** appears — search and select the target file
-3. **Click a line** in the target file to complete the connection
+- [Getting Started Guide](../GETTING-STARTED.md)
+- [Deployment Checklist](../DEPLOYMENT-CHECKLIST.md)
+- [Launch Kit](../LAUNCH-KIT.md)
+- [Session Report](../SESSION-FINAL-REPORT.md)
 
-Connection markers appear as colored dots on the left side of each card. Click a marker to jump to the other end.
+---
 
-## 📁 Layers
+## 🤝 Contributing
+
+1. Fork the repo
+2. Create a feature branch (`git checkout -b feat/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feat/amazing-feature`)
+5. Open a Pull Request
+
+### Development Setup
+```bash
+git clone https://github.com/7flash/gitmaps.git
+cd gitmaps
+bun install
+bun run dev
+```
 
-Layers let you isolate subsets of files for focused review:
+---
 
-- **Create**: Click `+ New Layer` in the bottom bar
-- **Add files**: Right-click a card → "Add to Layer"  
-- **Switch**: Click any layer tab — canvas shows only that layer's files
-- **Default**: "All Files" layer shows everything
+## 📈 Roadmap
+
+### v1.0.0 (Current) ✅
+- ✅ Infinite canvas with pan/zoom
+- ✅ Git integration with timeline
+- ✅ Layers system
+- ✅ WebGL rendering
+- ✅ Leader/Follower mode
+- ✅ Canvas export
+- ✅ Onboarding tutorial
+
+### v1.1.0 (Planned)
+- [ ] Real-time collaboration (WebSocket cursors)
+- [ ] Canvas snapshots (save/restore layouts)
+- [ ] Advanced search with filters
+- [ ] Plugin system
+- [ ] Custom themes
+
+### v2.0.0 (Future)
+- [ ] AI-powered code analysis
+- [ ] Automated architecture diagrams
+- [ ] Integration with VS Code
+- [ ] Team workspaces
+- [ ] Comments and annotations
 
-Each layer remembers its own viewport position, so switching layers is instant context-switching.
+---
 
-## 🎮 GalaxyDraw Engine
+## 🙏 Acknowledgments
 
-The canvas is powered by **GalaxyDraw** — a zero-dependency infinite 2D canvas engine built for this project:
+Inspired by **Ted Nelson's vision of intertwingularity** — the idea that everything is connected and hierarchical structures hide more relationships than they reveal.
 
-| Capability | Implementation |
-|-----------|----------------|
-| **Viewport culling** | Only creates DOM for visible cards. React repo (6833 files): 9 DOM nodes, 6824 deferred. ~35ms vs 14s. |
-| **Zoom LOD** | Below 25%, cards render as lightweight pills with vertical file names. Smooth fade transitions. |
-| **Throttled materialization** | Max 8 cards per frame with 150ms cooldown — no frame drops. |
-| **Dual control modes** | Simple (drag=pan, scroll=zoom) or Advanced (space+drag=pan, rect select). |
-| **Touch support** | Single-finger pan + pinch-to-zoom on tablets. |
-| **Minimap** | Shows all files including deferred cards. Click to navigate. |
+Built with:
+- [Bun](https://bun.sh/) — Fast JavaScript runtime
+- [Melina](https://github.com/7flash/melina) — Full-stack framework
+- [Pixi.js](https://pixijs.com/) — WebGL rendering
+- [CodeMirror](https://codemirror.net/) — Code editor
+- [XState](https://xstate.js.org/) — State management
 
-GalaxyDraw is also used by [WARMAPS](https://warmaps.xyz) for its intelligence dashboard canvas.
+---
 
-## 🔒 Production Security
+## 📄 License
 
-When deployed as a SaaS (`NODE_ENV=production`):
+ISC © [7flash](https://github.com/7flash)
 
-- Path traversal protection — only `git-canvas/repos/` and `.data/uploads/` are accessible
-- Folder browser endpoint completely blocked
-- All 7 repo API routes validate paths via `validateRepoPath()`
+---
 
-## ⚙️ Stack
+## 🔗 Links
 
-| Component | Technology |
-|-----------|------------|
-| Runtime | [Bun](https://bun.sh) |
-| Framework | [Melina](https://github.com/7flash/melina.js) v2.5 (file-based routing, SSR, hot reload) |
-| State | [XState](https://statemachine.xyz) v5 |
-| Database | [sqlite-zod-orm](https://github.com/7flash/measure-fn) (positions, connections, layers) |
-| Git | [simple-git](https://github.com/steveukx/git-js) |
-| Profiling | [measure-fn](https://github.com/7flash/measure-fn) |
+- **Live Demo:** https://gitmaps.xyz
+- **GitHub:** https://github.com/7flash/gitmaps
+- **npm:** https://npmjs.com/package/gitmaps
+- **jsx-ai:** https://npmjs.com/package/jsx-ai
+- **Twitter:** https://twitter.com/7flash
 
-## License
+---
 
-ISC
+**Built with ❤️ on 

package/app/[...slug]/page.client.tsx

@@ -0,0 +1 @@
+export { default } from '../page.client';

package/app/[...slug]/page.tsx

@@ -0,0 +1,6 @@
+/**
+ * Dynamic catch-all slug route — renders the same canvas page as root.
+ * URL: /foo, /owner/repo, /group/subgroup/repo, etc.
+ * The full slug is read client-side from window.location.pathname.
+ */
+export { default } from '../page';

package/app/[owner]/[repo]/page.client.tsx

@@ -0,0 +1,5 @@
+/**
+ * Dynamic owner/repo route client — re-exports the root page client.
+ * This ensures the client mount script is loaded for /owner/repo URLs.
+ */
+export { default } from '../../page.client';

package/app/[slug]/page.client.tsx

@@ -0,0 +1,5 @@
+/**
+ * Dynamic slug route client — re-exports the root page client.
+ * This ensures the client mount script is loaded for /slug URLs.
+ */
+export { default } from '../page.client';

package/app/api/analytics/route.ts

@@ -0,0 +1,64 @@
+import { Database } from 'bun:sqlite';
+import path from 'path';
+
+const DB_PATH = path.join(process.cwd(), 'app', 'analytics.db');
+const db = new Database(DB_PATH);
+
+db.run(`CREATE TABLE IF NOT EXISTS hits (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    path TEXT NOT NULL,
+    referrer TEXT,
+    ua TEXT,
+    ts INTEGER NOT NULL DEFAULT (unixepoch())
+)`);
+
+db.run(`CREATE INDEX IF NOT EXISTS idx_hits_ts ON hits(ts)`);
+db.run(`CREATE INDEX IF NOT EXISTS idx_hits_path ON hits(path)`);
+
+const insertStmt = db.prepare(`INSERT INTO hits (path, referrer, ua) VALUES (?, ?, ?)`);
+
+/**
+ * POST /api/analytics — log a page hit
+ * Body: { path: string }
+ */
+export async function POST(req: Request) {
+    try {
+        const { path: pagePath } = await req.json() as { path: string };
+        const referrer = req.headers.get('referer') || '';
+        const ua = req.headers.get('user-agent') || '';
+        insertStmt.run(pagePath || '/', referrer, ua.slice(0, 200));
+        return Response.json({ ok: true });
+    } catch {
+        return Response.json({ ok: false }, { status: 400 });
+    }
+}
+
+/**
+ * GET /api/analytics — return stats
+ * Query: ?hours=24 (default 24)
+ */
+export function GET(req: Request) {
+    const url = new URL(req.url);
+    const hours = parseInt(url.searchParams.get('hours') || '24', 10);
+    const since = Math.floor(Date.now() / 1000) - hours * 3600;
+
+    const total = db.prepare(`SELECT COUNT(*) as count FROM hits WHERE ts > ?`).get(since) as any;
+    const byPath = db.prepare(`SELECT path, COUNT(*) as count FROM hits WHERE ts > ? GROUP BY path ORDER BY count DESC LIMIT 20`).all(since);
+    const byHour = db.prepare(`
+        SELECT strftime('%Y-%m-%d %H:00', ts, 'unixepoch') as hour, COUNT(*) as count 
+        FROM hits WHERE ts > ? GROUP BY hour ORDER BY hour
+    `).all(since);
+    const byReferrer = db.prepare(`
+        SELECT referrer, COUNT(*) as count FROM hits 
+        WHERE ts > ? AND referrer != '' 
+        GROUP BY referrer ORDER BY count DESC LIMIT 10
+    `).all(since);
+
+    return Response.json({
+        total: (total as any).count,
+        hours,
+        byPath,
+        byHour,
+        byReferrer,
+    });
+}