@buley/hexgrid-3d 1.0.0

package/.eslintrc.json

@@ -0,0 +1,28 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 2020,
+    "sourceType": "module",
+    "ecmaFeatures": {
+      "jsx": true
+    }
+  },
+  "settings": {
+    "react": {
+      "version": "detect"
+    }
+  },
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:react/recommended",
+    "plugin:react-hooks/recommended"
+  ],
+  "rules": {
+    "@typescript-eslint/no-explicit-any": "warn",
+    "@typescript-eslint/explicit-module-boundary-types": "off",
+    "react/react-in-jsx-scope": "off",
+    "react/prop-types": "off"
+  }
+}

package/LICENSE

@@ -0,0 +1,39 @@
+Personal Use Only License
+
+Copyright (c) 2026 buley
+
+All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use
+the Software for personal, non-commercial purposes only, subject to the
+following conditions:
+
+1. Personal Use Only: The Software may be used for personal, non-commercial
+   purposes only. Commercial use, including but not limited to use in
+   commercial products, services, or applications, is strictly prohibited.
+
+2. No Redistribution: You may not distribute, publish, or sublicense the
+   Software or any derivative works based on the Software.
+
+3. No Modification for Distribution: You may modify the Software for your
+   personal use, but you may not distribute, publish, or sublicense any
+   modified versions.
+
+4. Intellectual Property: All intellectual property rights in the Software
+   remain with the copyright holder. This license does not grant any rights
+   to patents, trademarks, or other intellectual property.
+
+5. Viewing and Learning: You may view, study, and learn from the Software's
+   source code for educational purposes, but you may not use it in any
+   commercial capacity.
+
+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.
+
+For commercial licensing inquiries, please contact the copyright holder.

package/README.md

@@ -0,0 +1,291 @@
+# HexGrid 3D
+
+A reusable 3D hexagonal grid visualization component for displaying content in an immersive spherical layout.
+
+## Features
+
+- **3D Hexagonal Grid Layout** - Spherical projection with customizable curvature
+- **Interactive Camera Controls** - Pan, zoom, inside/outside views with smooth transitions
+- **Image Texture Mapping** - Automatic texture loading and caching
+- **Real-time Statistics** - Live telemetry and performance metrics
+- **Narration System** - Play-by-play commentary overlay
+- **Web Worker Rendering** - High-performance offloaded calculations
+- **Multi-Input Support** - Touch gestures, mouse, and keyboard controls
+- **Responsive Design** - Adapts to mobile and desktop viewports
+- **Dynamic Theming** - Accent color extraction from images
+- **Autoplay Mode** - Queue-based content cycling
+
+## Installation
+
+```bash
+npm install @buley/hexgrid-3d
+```
+
+## Usage
+
+### Basic Example
+
+```tsx
+import { HexGrid, Photo } from '@buley/hexgrid-3d'
+
+function MyComponent() {
+  const photos: Photo[] = [
+    {
+      id: '1',
+      url: 'https://example.com/photo.jpg',
+      source: 'example',
+      createdAt: new Date().toISOString()
+    }
+  ]
+
+  return (
+    <HexGrid
+      photos={photos}
+      onHexClick={(photo) => console.log('Clicked:', photo)}
+    />
+  )
+}
+```
+
+### Advanced Example with Controls
+
+```tsx
+import { HexGrid, Photo, uiStore } from '@buley/hexgrid-3d'
+import { useRef, useState } from 'react'
+
+function AdvancedExample() {
+  const canvasRef = useRef<HTMLCanvasElement>(null)
+  const [modalOpen, setModalOpen] = useState(false)
+
+  return (
+    <div>
+      {/* Control buttons */}
+      <button onClick={() => uiStore.toggleDebug()}>
+        Toggle Debug
+      </button>
+      <button onClick={() => uiStore.toggleCamera()}>
+        Camera Controls
+      </button>
+      
+      {/* Visualization */}
+      <HexGrid
+        photos={photos}
+        canvasRef={canvasRef}
+        spacing={1.2}
+        modalOpen={modalOpen}
+        onHexClick={(photo) => setModalOpen(true)}
+        autoplayQueueLimit={100}
+      />
+    </div>
+  )
+}
+```
+
+## Components
+
+### HexGrid
+
+Main visualization component that renders a 3D hexagonal grid on a spherical surface.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `photos` | `Photo[]` | `[]` | Array of photos to display in the grid |
+| `onHexClick` | `(photo: Photo) => void` | - | Callback when a hex tile is clicked |
+| `spacing` | `number` | `1.0` | Grid spacing multiplier (affects tile density) |
+| `canvasRef` | `React.RefObject<HTMLCanvasElement>` | - | Optional external canvas reference |
+| `onLeaderboardUpdate` | `(leaderboard: any) => void` | - | Callback for leaderboard statistics updates |
+| `autoplayQueueLimit` | `number` | - | Maximum items in autoplay queue |
+| `onAutoplayQueueLimitChange` | `(limit: number) => void` | - | Callback when autoplay limit changes |
+| `modalOpen` | `boolean` | `false` | Whether a modal is currently open |
+| `userId` | `string` | - | Current user ID for personalization |
+| `username` | `string` | - | Current username for display |
+
+### NarrationOverlay
+
+Displays narration messages and real-time statistics in a dashboard-style overlay.
+
+**Props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `messages` | `NarrationMessage[]` | Array of narration messages to display |
+| `statsTracker` | `StatsTracker` | Statistics tracker instance |
+| `isVisible` | `boolean` | Whether overlay is visible |
+| `onClose` | `() => void` | Callback when overlay is closed |
+
+## Types
+
+### Photo
+
+```typescript
+interface Photo {
+  id: string
+  url: string
+  thumbnailUrl?: string
+  title?: string
+  description?: string
+  source: string
+  createdAt: string
+  userId?: string
+  username?: string
+  videoUrl?: string
+  platform?: string
+  author?: string
+  authorUrl?: string
+  likes?: number
+  views?: number
+  comments?: number
+  dominantColor?: string
+}
+```
+
+## Stores
+
+### uiStore
+
+Global UI state management for visualization components.
+
+**Methods:**
+
+- `uiStore.toggleDebug()` - Toggle debug panel
+- `uiStore.toggleStats()` - Toggle statistics overlay
+- `uiStore.toggleCamera()` - Toggle camera controls
+- `uiStore.toggleNarration()` - Toggle narration overlay
+- `uiStore.set(state)` - Update multiple state values
+- `uiStore.subscribe(callback)` - Subscribe to state changes
+
+**State:**
+
+```typescript
+interface UIState {
+  debugOpen: boolean
+  showStats: boolean
+  cameraOpen: boolean
+  showNarration: boolean
+}
+```
+
+## Camera Controls
+
+### Mouse/Trackpad
+- **Left Click + Drag** - Rotate camera (yaw and pitch)
+- **Scroll** - Zoom in/out
+- **Click on Hex** - Select photo
+
+### Touch
+- **Single Touch Drag** - Rotate camera
+- **Pinch** - Zoom in/out
+- **Tap on Hex** - Select photo
+
+### Keyboard
+- **D** - Toggle debug panel
+- **Escape** - Close debug panel
+
+## Performance
+
+The component uses a Web Worker for heavy calculations to maintain 60fps rendering:
+
+- **Streaming Rendering** - Progressively renders tiles
+- **Texture Caching** - Reuses loaded images
+- **Adaptive Quality** - Adjusts detail based on performance
+- **Low-Res Mode** - Optional reduced quality for slower devices
+
+## Theming
+
+The component integrates with your app's theme system and can extract accent colors from images:
+
+```tsx
+import { getAccentRgba, setCustomAccentColor } from '@/lib/theme-colors'
+
+// Custom accent color from image
+setCustomAccentColor('#ff00ff')
+```
+
+## Dependencies
+
+### Peer Dependencies
+- `react` ^18.0.0
+- `react-dom` ^18.0.0
+- `next` ^14.0.0
+- `three` (Three.js for 3D calculations)
+
+### Internal Dependencies
+- `@/lib/stats-tracker` - Statistics tracking
+- `@/lib/narration` - Narration engine
+- `@/lib/logger` - Logging utilities
+- `@/lib/theme-colors` - Theme system integration
+- `@/lib/html-utils` - HTML utilities
+
+## Development
+
+### Build
+
+```bash
+npm run build
+```
+
+### Watch Mode
+
+```bash
+npm run dev
+```
+
+## Architecture
+
+```
+hexgrid-3d/
+├── src/
+│   ├── components/      # React components
+│   │   ├── HexGrid.tsx
+│   │   └── NarrationOverlay.tsx
+│   ├── stores/          # State management
+│   │   └── uiStore.ts
+│   ├── workers/         # Web Workers
+│   │   └── hexgrid-worker.worker.ts
+│   ├── types.ts         # TypeScript definitions
+│   └── index.ts         # Main exports
+├── public/              # Static assets
+│   └── hexgrid-worker.js
+├── examples/            # Usage examples
+│   └── basic-usage.tsx
+└── tests/              # Test suites
+    ├── unit/
+    ├── integration/
+    └── e2e/
+```
+
+## Testing
+
+### Run Tests
+
+```bash
+npm test
+```
+
+### Run Tests in Watch Mode
+
+```bash
+npm run test:watch
+```
+
+### Run Coverage
+
+```bash
+npm run test:coverage
+```
+
+### Run E2E Tests
+
+```bash
+npm run test:e2e
+```
+
+## License
+
+Personal Use Only - See LICENSE file for full terms.
+
+This software is provided for personal, non-commercial use only. Commercial use,
+redistribution, and sublicensing are prohibited. All intellectual property
+rights are reserved by the copyright holder.

package/examples/basic-usage.tsx

@@ -0,0 +1,52 @@
+import React, { useState } from 'react'
+import { HexGrid, Photo } from '@buley/hexgrid-3d'
+
+/**
+ * Example usage of the HexGrid visualization component
+ */
+export default function HexGridExample() {
+  const [photos, setPhotos] = useState<Photo[]>([
+    {
+      id: '1',
+      url: 'https://example.com/photo1.jpg',
+      thumbnailUrl: 'https://example.com/photo1_thumb.jpg',
+      title: 'Example Photo 1',
+      description: 'First example photo',
+      source: 'example',
+      createdAt: new Date().toISOString(),
+      userId: 'user123'
+    },
+    {
+      id: '2',
+      url: 'https://example.com/photo2.jpg',
+      thumbnailUrl: 'https://example.com/photo2_thumb.jpg',
+      title: 'Example Photo 2',
+      description: 'Second example photo',
+      source: 'example',
+      createdAt: new Date().toISOString(),
+      userId: 'user123'
+    }
+  ])
+
+  const handleHexClick = (photo: Photo) => {
+    console.log('Clicked photo:', photo)
+    // Handle photo click - open modal, navigate, etc.
+  }
+
+  const handleLeaderboardUpdate = (leaderboard: any) => {
+    console.log('Leaderboard updated:', leaderboard)
+  }
+
+  return (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <HexGrid
+        photos={photos}
+        onHexClick={handleHexClick}
+        spacing={1.0}
+        onLeaderboardUpdate={handleLeaderboardUpdate}
+        autoplayQueueLimit={100}
+        modalOpen={false}
+      />
+    </div>
+  )
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@buley/hexgrid-3d",
+  "version": "1.0.0",
+  "description": "3D hexagonal grid visualization component for React",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/buley/hexgrid-3d.git"
+  },
+  "author": "buley",
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./components": "./src/components/index.ts",
+    "./stores": "./src/stores/index.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "test:coverage": "bun test --coverage",
+    "test:e2e": "playwright test",
+    "lint": "eslint src/**/*.{ts,tsx}",
+    "type-check": "tsc --noEmit"
+  },
+  "keywords": [
+    "3d",
+    "visualization",
+    "hexgrid",
+    "hexagonal",
+    "grid",
+    "sphere",
+    "react",
+    "canvas",
+    "webgl",
+    "three"
+  ],
+  "peerDependencies": {
+    "next": "^14.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.3.3",
+    "@playwright/test": "^1.40.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^14.3.1",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^18.3.27",
+    "@types/react-dom": "^18.3.7",
+    "happy-dom": "^20.3.3",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.0.0"
+  }
+}