@buley/hexgrid-3d 1.0.0

package/src/components/NarrationOverlay.tsx

@@ -0,0 +1,221 @@
+/**
+ * Narration Overlay Component
+ * 
+ * Displays play-by-play narration messages with sparklines in a NOC dashboard style.
+ */
+
+import React, { useEffect, useRef } from 'react'
+import { NarrationMessage } from '@/lib/narration'
+import { StatsTracker } from '@/lib/stats-tracker'
+import { getAccentRgba, getAccentHex } from '@/lib/theme-colors'
+
+export interface NarrationOverlayProps {
+  messages: NarrationMessage[]
+  statsTracker: StatsTracker | null
+  isVisible: boolean
+  onClose: () => void
+}
+
+export const NarrationOverlay: React.FC<NarrationOverlayProps> = ({
+  messages,
+  statsTracker,
+  isVisible,
+  onClose
+}) => {
+  const messagesEndRef = useRef<HTMLDivElement>(null)
+  const scrollContainerRef = useRef<HTMLDivElement>(null)
+
+  // Auto-scroll to latest message
+  useEffect(() => {
+    if (messagesEndRef.current && scrollContainerRef.current) {
+      scrollContainerRef.current.scrollTop = scrollContainerRef.current.scrollHeight
+    }
+  }, [messages])
+
+  // Always render the overlay so fade-out can animate smoothly.
+  // Toggle visibility via styles.
+
+  const currentStats = statsTracker?.getCurrentStats()
+  const allTimeRecords = statsTracker?.getAllTimeRecords()
+  const leaderboard = statsTracker?.getLeaderboard(10)
+
+  return (
+    <div
+      style={{
+        position: 'fixed',
+        right: 12,
+        top: 80,
+        width: 400,
+        maxHeight: 'calc(100vh - 100px)',
+        background: 'rgba(0, 0, 0, 0.85)',
+        border: `1px solid ${getAccentRgba(0.3)}`,
+        borderRadius: 8,
+        padding: '12px',
+        zIndex: 10000,
+        display: 'flex',
+        flexDirection: 'column',
+        fontFamily: "'Courier New', monospace",
+        fontSize: 12,
+        color: getAccentHex(),
+        boxShadow: `0 0 20px ${getAccentRgba(0.2)}`,
+        // Fade transition
+        transition: 'opacity 220ms ease, transform 220ms ease',
+        opacity: isVisible ? 1 : 0,
+        transform: isVisible ? 'translateY(0px)' : 'translateY(-6px)',
+        pointerEvents: isVisible ? 'auto' as const : 'none' as const
+      }}
+    >
+      {/* Header */}
+      <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 8 }}>
+        <div style={{ fontWeight: 'bold', fontSize: 14 }}>Play-by-Play Narration</div>
+        <button
+          onClick={onClose}
+          style={{
+            background: 'transparent',
+            border: '1px solid rgba(0, 255, 255, 0.3)',
+            color: '#00ffff',
+            cursor: 'pointer',
+            padding: '4px 8px',
+            borderRadius: 4,
+            fontSize: 11
+          }}
+        >
+          ×
+        </button>
+      </div>
+
+      {/* Stats Dashboard (Collapsible) */}
+      {currentStats && (
+        <details style={{ marginBottom: 8, fontSize: 11 }}>
+          <summary style={{ cursor: 'pointer', color: '#00ffff', marginBottom: 4 }}>
+            Stats Dashboard
+          </summary>
+          <div style={{ padding: '8px', background: 'rgba(0, 255, 255, 0.05)', borderRadius: 4 }}>
+            <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: 4 }}>
+              <span>Generation:</span>
+              <span style={{ fontVariantNumeric: 'tabular-nums' }}>{currentStats.generation}</span>
+            </div>
+            <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: 4 }}>
+              <span>Active Memes:</span>
+              <span style={{ fontVariantNumeric: 'tabular-nums' }}>{currentStats.activeMemesCount}</span>
+            </div>
+            <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: 4 }}>
+              <span>Total Hexes:</span>
+              <span style={{ fontVariantNumeric: 'tabular-nums' }}>{currentStats.totalHexesInfected}</span>
+            </div>
+            <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: 4 }}>
+              <span>Birth/Death Ratio:</span>
+              <span style={{ fontVariantNumeric: 'tabular-nums' }}>
+                {currentStats.populationStability.toFixed(2)}
+              </span>
+            </div>
+            {allTimeRecords && (
+              <div style={{ marginTop: 8, paddingTop: 8, borderTop: '1px solid rgba(0, 255, 255, 0.2)' }}>
+                <div style={{ fontSize: 10, color: '#00ffff', marginBottom: 4 }}>All-Time Records:</div>
+                <div style={{ fontSize: 10, marginBottom: 2 }}>
+                  Highest Territory: {allTimeRecords.highestTerritory.value}
+                </div>
+                <div style={{ fontSize: 10, marginBottom: 2 }}>
+                  Longest Streak: {allTimeRecords.longestSurvivalStreak.value}
+                </div>
+              </div>
+            )}
+          </div>
+        </details>
+      )}
+
+      {/* Leaderboard (Collapsible) */}
+      {leaderboard && leaderboard.length > 0 && (
+        <details style={{ marginBottom: 8, fontSize: 11 }}>
+          <summary style={{ cursor: 'pointer', color: '#00ffff', marginBottom: 4 }}>
+            Top 10 Leaderboard
+          </summary>
+          <div style={{ padding: '8px', background: 'rgba(0, 255, 255, 0.05)', borderRadius: 4 }}>
+            {leaderboard.map((entry, i) => (
+              <div
+                key={entry.photoId}
+                style={{
+                  display: 'flex',
+                  justifyContent: 'space-between',
+                  marginBottom: 2,
+                  fontSize: 10,
+                  color: i < 3 ? '#00ff00' : '#00ffff'
+                }}
+              >
+                <span>
+                  {i + 1}. {entry.photoId.slice(0, 20)}...
+                </span>
+                <span style={{ fontVariantNumeric: 'tabular-nums' }}>{entry.territory} hexes</span>
+              </div>
+            ))}
+          </div>
+        </details>
+      )}
+
+      {/* Messages Feed */}
+      <div
+        ref={scrollContainerRef}
+        style={{
+          flex: 1,
+          overflowY: 'auto',
+          maxHeight: '400px',
+          padding: '8px',
+          background: 'rgba(0, 0, 0, 0.3)',
+          borderRadius: 4
+        }}
+      >
+        {messages.length === 0 ? (
+          <div style={{ color: 'rgba(0, 255, 255, 0.5)', fontStyle: 'italic', textAlign: 'center', padding: '20px' }}>
+            No narration yet. Evolution in progress...
+          </div>
+        ) : (
+          messages.map((msg, index) => (
+            <div
+              key={`${msg.generation}-${index}`}
+              style={{
+                marginBottom: 8,
+                padding: '6px',
+                background: msg.priority >= 8 ? 'rgba(255, 165, 0, 0.1)' : 'rgba(0, 255, 255, 0.05)',
+                borderRadius: 4,
+                borderLeft: `2px solid ${msg.priority >= 8 ? '#ffaa00' : '#00ffff'}`,
+                fontSize: 11,
+                lineHeight: 1.4
+              }}
+            >
+              <div style={{ display: 'flex', justifyContent: 'space-between', marginBottom: 2 }}>
+                <span style={{ color: 'rgba(0, 255, 255, 0.7)', fontSize: 10 }}>
+                  Gen {msg.generation}
+                </span>
+                <span style={{ color: 'rgba(0, 255, 255, 0.5)', fontSize: 9 }}>
+                  {new Date(msg.timestamp).toLocaleTimeString()}
+                </span>
+              </div>
+              <div style={{ fontFamily: "'Courier New', monospace" }}>
+                {msg.text}
+                {msg.sparkline && (
+                  <div
+                    style={{
+                      marginTop: 4,
+                      fontFamily: "'Courier New', monospace",
+                      fontSize: 14,
+                      color: msg.eventType === 'slam_dunk' || msg.eventType === 'on_fire' 
+                        ? '#00ff00' 
+                        : msg.eventType === 'decline' || msg.eventType === 'missed_shot'
+                        ? '#ff4444'
+                        : '#00ffff',
+                      letterSpacing: '2px'
+                    }}
+                  >
+                    {msg.sparkline}
+                  </div>
+                )}
+              </div>
+            </div>
+          ))
+        )}
+        <div ref={messagesEndRef} />
+      </div>
+    </div>
+  )
+}
+

package/src/components/index.ts

@@ -0,0 +1,2 @@
+export { HexGrid } from './HexGrid';
+export type { Photo, HexGridProps } from './HexGrid';

package/src/features.ts

@@ -0,0 +1,125 @@
+/**
+ * Feature flags for HexGrid 3D
+ * 
+ * Allows enabling/disabling features at runtime for different client environments
+ */
+
+export interface HexGridFeatureFlags {
+  /** Enable/disable play-by-play narration overlay */
+  enableNarration?: boolean
+  
+  /** Enable/disable statistics tracking and display */
+  enableStats?: boolean
+  
+  /** Enable/disable debug panel */
+  enableDebugPanel?: boolean
+  
+  /** Enable/disable camera controls UI */
+  enableCameraControls?: boolean
+  
+  /** Enable/disable worker-based rendering */
+  enableWorker?: boolean
+  
+  /** Enable/disable texture/image loading */
+  enableTextures?: boolean
+  
+  /** Enable/disable evolution/animation system */
+  enableEvolution?: boolean
+  
+  /** Enable/disable autoplay functionality */
+  enableAutoplay?: boolean
+  
+  /** Enable/disable user interactions (clicks, drags) */
+  enableInteractions?: boolean
+  
+  /** Enable/disable keyboard shortcuts */
+  enableKeyboardShortcuts?: boolean
+  
+  /** Enable/disable performance telemetry */
+  enableTelemetry?: boolean
+  
+  /** Enable/disable sheen/visual effects */
+  enableVisualEffects?: boolean
+  
+  /** Enable/disable leaderboard system */
+  enableLeaderboard?: boolean
+}
+
+/**
+ * Default feature flags - all features enabled
+ */
+export const DEFAULT_FEATURE_FLAGS: Required<HexGridFeatureFlags> = {
+  enableNarration: true,
+  enableStats: true,
+  enableDebugPanel: true,
+  enableCameraControls: true,
+  enableWorker: true,
+  enableTextures: true,
+  enableEvolution: true,
+  enableAutoplay: true,
+  enableInteractions: true,
+  enableKeyboardShortcuts: true,
+  enableTelemetry: true,
+  enableVisualEffects: true,
+  enableLeaderboard: true,
+}
+
+/**
+ * Minimal feature flags - only core visualization
+ */
+export const MINIMAL_FEATURE_FLAGS: Required<HexGridFeatureFlags> = {
+  enableNarration: false,
+  enableStats: false,
+  enableDebugPanel: false,
+  enableCameraControls: false,
+  enableWorker: true,
+  enableTextures: true,
+  enableEvolution: false,
+  enableAutoplay: false,
+  enableInteractions: true,
+  enableKeyboardShortcuts: false,
+  enableTelemetry: false,
+  enableVisualEffects: false,
+  enableLeaderboard: false,
+}
+
+/**
+ * Performance-focused feature flags
+ */
+export const PERFORMANCE_FEATURE_FLAGS: Required<HexGridFeatureFlags> = {
+  enableNarration: false,
+  enableStats: true,
+  enableDebugPanel: false,
+  enableCameraControls: true,
+  enableWorker: true,
+  enableTextures: true,
+  enableEvolution: true,
+  enableAutoplay: false,
+  enableInteractions: true,
+  enableKeyboardShortcuts: true,
+  enableTelemetry: false,
+  enableVisualEffects: false,
+  enableLeaderboard: false,
+}
+
+/**
+ * Merge user-provided flags with defaults
+ */
+export function mergeFeatureFlags(
+  userFlags?: Partial<HexGridFeatureFlags>
+): Required<HexGridFeatureFlags> {
+  return {
+    ...DEFAULT_FEATURE_FLAGS,
+    ...userFlags,
+  }
+}
+
+/**
+ * Check if a feature is enabled
+ */
+export function isFeatureEnabled(
+  flags: HexGridFeatureFlags,
+  feature: keyof HexGridFeatureFlags
+): boolean {
+  return flags[feature] !== false
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+// Main package exports
+export * from './components'
+export * from './stores'
+export * from './features'
+
+// Export pure mathematical functions
+export * from './workers/hexgrid-math'
+export * from './utils/image-utils'
+
+// Export additional types that aren't in components/stores
+export type { WorkerDebug, Photo, GridItem } from './types'
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ENHANCED HEXGRID EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+// Math library
+export * from './math'
+
+// Algorithms (graph, clustering, flow, particles, fluid)
+export * from './algorithms'
+
+// WASM acceleration layer
+export * from './wasm'
+
+// Unified Snapshot API
+export * from './Snapshot'
+
+// Enhanced HexGrid engine with all features integrated
+export * from './HexGridEnhanced'

package/src/math/HexCoordinates.ts

@@ -0,0 +1,15 @@
+export class Axial {
+  q: number;
+  r: number;
+
+  constructor(q: number, r: number) {
+    this.q = q;
+    this.r = r;
+  }
+
+  static fromPixel(x: number, y: number, hexSize: number): Axial {
+    const q = (Math.sqrt(3) / 3 * x - (1 / 3) * y) / hexSize;
+    const r = ((2 / 3) * y) / hexSize;
+    return new Axial(Math.round(q), Math.round(r));
+  }
+}

package/src/math/Matrix4.ts

@@ -0,0 +1,35 @@
+import { Vector3 } from './Vector3';
+
+export class Matrix4 {
+  private elements: number[];
+
+  constructor(elements?: number[]) {
+    this.elements = elements ?? Matrix4.identity().elements;
+  }
+
+  static identity(): Matrix4 {
+    return new Matrix4([
+      1, 0, 0, 0,
+      0, 1, 0, 0,
+      0, 0, 1, 0,
+      0, 0, 0, 1,
+    ]);
+  }
+
+  static translation(x: number, y: number, z: number): Matrix4 {
+    return new Matrix4([
+      1, 0, 0, x,
+      0, 1, 0, y,
+      0, 0, 1, z,
+      0, 0, 0, 1,
+    ]);
+  }
+
+  transformPoint(point: Vector3): Vector3 {
+    const e = this.elements;
+    const x = point.x * e[0] + point.y * e[1] + point.z * e[2] + e[3];
+    const y = point.x * e[4] + point.y * e[5] + point.z * e[6] + e[7];
+    const z = point.x * e[8] + point.y * e[9] + point.z * e[10] + e[11];
+    return new Vector3(x, y, z);
+  }
+}

package/src/math/Quaternion.ts

@@ -0,0 +1,37 @@
+import { Vector3 } from './Vector3';
+
+export class Quaternion {
+  x: number;
+  y: number;
+  z: number;
+  w: number;
+
+  constructor(x: number = 0, y: number = 0, z: number = 0, w: number = 1) {
+    this.x = x;
+    this.y = y;
+    this.z = z;
+    this.w = w;
+  }
+
+  static identity(): Quaternion {
+    return new Quaternion(0, 0, 0, 1);
+  }
+
+  rotateVector(vector: Vector3): Vector3 {
+    const qx = this.x;
+    const qy = this.y;
+    const qz = this.z;
+    const qw = this.w;
+
+    const ix = qw * vector.x + qy * vector.z - qz * vector.y;
+    const iy = qw * vector.y + qz * vector.x - qx * vector.z;
+    const iz = qw * vector.z + qx * vector.y - qy * vector.x;
+    const iw = -qx * vector.x - qy * vector.y - qz * vector.z;
+
+    return new Vector3(
+      ix * qw + iw * -qx + iy * -qz - iz * -qy,
+      iy * qw + iw * -qy + iz * -qx - ix * -qz,
+      iz * qw + iw * -qz + ix * -qy - iy * -qx
+    );
+  }
+}

package/src/math/SpatialIndex.ts

@@ -0,0 +1,114 @@
+import { Vector2 } from './Vector3';
+
+type Point = [number, number];
+
+export interface KDTreeResult<T> {
+  data: T;
+  distance: number;
+}
+
+export class KDTree<T> {
+  private points: Point[];
+  private data: T[];
+
+  private constructor(points: Point[], data: T[]) {
+    this.points = points;
+    this.data = data;
+  }
+
+  static build<T>(points: Point[], data: T[], _dimensions: number): KDTree<T> {
+    return new KDTree(points, data);
+  }
+
+  kNearest(target: Point, k: number): Array<KDTreeResult<T>> {
+    const results = this.points.map((point, index) => ({
+      data: this.data[index],
+      distance: KDTree.distance(point, target),
+    }));
+
+    return results.sort((a, b) => a.distance - b.distance).slice(0, k);
+  }
+
+  rangeQuery(target: Point, radius: number): Array<KDTreeResult<T>> {
+    return this.points
+      .map((point, index) => ({
+        data: this.data[index],
+        distance: KDTree.distance(point, target),
+      }))
+      .filter((result) => result.distance <= radius);
+  }
+
+  private static distance(a: Point, b: Point): number {
+    const dx = a[0] - b[0];
+    const dy = a[1] - b[1];
+    return Math.sqrt(dx * dx + dy * dy);
+  }
+}
+
+export interface SpatialHashEntry<T> {
+  data: T;
+  position: Point;
+}
+
+export class SpatialHashGrid<T> {
+  private cellSize: number;
+  private grid: Map<string, SpatialHashEntry<T>[]> = new Map();
+
+  constructor(cellSize: number, _dimensions: number) {
+    this.cellSize = cellSize;
+  }
+
+  insert(position: Point, data: T): void {
+    const key = this.keyFor(position);
+    const bucket = this.grid.get(key) ?? [];
+    bucket.push({ data, position });
+    this.grid.set(key, bucket);
+  }
+
+  query(position: Point, radius: number): Array<SpatialHashEntry<T>> {
+    const cellsToCheck = this.nearbyKeys(position, radius);
+    const results: Array<SpatialHashEntry<T>> = [];
+
+    for (const key of cellsToCheck) {
+      const bucket = this.grid.get(key);
+      if (!bucket) continue;
+      for (const entry of bucket) {
+        const distance = Math.hypot(
+          entry.position[0] - position[0],
+          entry.position[1] - position[1]
+        );
+        if (distance <= radius) {
+          results.push(entry);
+        }
+      }
+    }
+
+    return results;
+  }
+
+  private keyFor(position: Point): string {
+    const x = Math.floor(position[0] / this.cellSize);
+    const y = Math.floor(position[1] / this.cellSize);
+    return `${x},${y}`;
+  }
+
+  private nearbyKeys(position: Point, radius: number): string[] {
+    const minX = Math.floor((position[0] - radius) / this.cellSize);
+    const maxX = Math.floor((position[0] + radius) / this.cellSize);
+    const minY = Math.floor((position[1] - radius) / this.cellSize);
+    const maxY = Math.floor((position[1] + radius) / this.cellSize);
+
+    const keys: string[] = [];
+    for (let x = minX; x <= maxX; x++) {
+      for (let y = minY; y <= maxY; y++) {
+        keys.push(`${x},${y}`);
+      }
+    }
+    return keys;
+  }
+}
+
+export interface SpatialNode {
+  position: Vector2;
+  data: unknown;
+}

package/src/math/Vector3.ts

@@ -0,0 +1,69 @@
+export class Vector2 {
+  x: number;
+  y: number;
+
+  constructor(x: number = 0, y: number = 0) {
+    this.x = x;
+    this.y = y;
+  }
+
+  add(other: Vector2): Vector2 {
+    return new Vector2(this.x + other.x, this.y + other.y);
+  }
+
+  subtract(other: Vector2): Vector2 {
+    return new Vector2(this.x - other.x, this.y - other.y);
+  }
+
+  scale(factor: number): Vector2 {
+    return new Vector2(this.x * factor, this.y * factor);
+  }
+
+  length(): number {
+    return Math.sqrt(this.x * this.x + this.y * this.y);
+  }
+
+  normalize(): Vector2 {
+    const len = this.length();
+    if (len === 0) {
+      return new Vector2(0, 0);
+    }
+    return new Vector2(this.x / len, this.y / len);
+  }
+
+  distanceTo(other: Vector2): number {
+    const dx = this.x - other.x;
+    const dy = this.y - other.y;
+    return Math.sqrt(dx * dx + dy * dy);
+  }
+}
+
+export class Vector3 {
+  x: number;
+  y: number;
+  z: number;
+
+  constructor(x: number = 0, y: number = 0, z: number = 0) {
+    this.x = x;
+    this.y = y;
+    this.z = z;
+  }
+
+  static fromLatLng(latitude: number, longitude: number, radius: number = 1): Vector3 {
+    const latRad = (latitude * Math.PI) / 180;
+    const lonRad = (longitude * Math.PI) / 180;
+
+    const x = radius * Math.cos(latRad) * Math.cos(lonRad);
+    const y = radius * Math.cos(latRad) * Math.sin(lonRad);
+    const z = radius * Math.sin(latRad);
+
+    return new Vector3(x, y, z);
+  }
+
+  distanceTo(other: Vector3): number {
+    const dx = this.x - other.x;
+    const dy = this.y - other.y;
+    const dz = this.z - other.z;
+    return Math.sqrt(dx * dx + dy * dy + dz * dz);
+  }
+}

package/src/math/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Math Module Exports
+ * 
+ * @module math
+ */
+
+export * from './Vector3'
+export * from './Matrix4'
+export * from './Quaternion'
+export * from './HexCoordinates'
+export * from './SpatialIndex'