@buley/hexgrid-3d 1.0.0 → 1.1.0

package/src/note-adapter.ts

@@ -1,53 +1,53 @@
 /**
  * Adapter for embedding notes directly in the grid
- * 
+ *
  * This adapter allows notes (Cyrano's internal notes, user notes, etc.)
  * to be embedded directly in GridItems with full metadata preservation.
  */
 
-import type { GridItem } from './types'
-import type { ItemAdapter, AdapterOptions } from './adapters'
+import type { GridItem } from './types';
+import type { ItemAdapter, AdapterOptions } from './adapters';
 
 /**
  * Note content structure
  */
 export interface NoteContent {
-  title?: string
-  text: string
-  summary?: string
+  title?: string;
+  text: string;
+  summary?: string;
 }
 
 /**
  * Note metadata structure
  */
 export interface NoteMetadata {
-  type?: string
-  category?: string
-  subcategory?: string
-  tags?: string[]
-  targetUserId?: string
-  status?: 'active' | 'archived' | 'draft'
-  priority?: 'low' | 'medium' | 'high' | 'urgent'
-  context?: string
-  permissions?: 'private' | 'shared' | 'public'
-  sharedWith?: string[]
+  type?: string;
+  category?: string;
+  subcategory?: string;
+  tags?: string[];
+  targetUserId?: string;
+  status?: 'active' | 'archived' | 'draft';
+  priority?: 'low' | 'medium' | 'high' | 'urgent';
+  context?: string;
+  permissions?: 'private' | 'shared' | 'public';
+  sharedWith?: string[];
 }
 
 /**
  * Note structure matching Affectively's note format
  */
 export interface Note {
-  id: string
-  content: NoteContent
-  metadata?: NoteMetadata
-  date: string
+  id: string;
+  content: NoteContent;
+  metadata?: NoteMetadata;
+  date: string;
 }
 
 /**
  * Calculate velocity for a note based on recency, priority, and metadata richness
  */
 function calculateNoteVelocity(note: Note): number {
-  let velocity = 0.1 // Base minimum
+  let velocity = 0.1; // Base minimum
 
   // Priority contribution (0-0.3)
   const priorityMap: Record<string, number> = {
@@ -55,29 +55,30 @@ function calculateNoteVelocity(note: Note): number {
     high: 0.2,
     medium: 0.1,
     low: 0.05,
-  }
+  };
   if (note.metadata?.priority) {
-    velocity += priorityMap[note.metadata.priority] || 0.1
+    velocity += priorityMap[note.metadata.priority] || 0.1;
   }
 
   // Recency contribution (0-0.4)
   if (note.date) {
-    const ageMs = Date.now() - new Date(note.date).getTime()
-    const ageHours = ageMs / (1000 * 60 * 60)
-    const recencyFactor = Math.max(0, 1 - ageHours / 168) // Decay over 1 week
-    velocity += recencyFactor * 0.4
+    const ageMs = Date.now() - new Date(note.date).getTime();
+    const ageHours = ageMs / (1000 * 60 * 60);
+    const recencyFactor = Math.max(0, 1 - ageHours / 168); // Decay over 1 week
+    velocity += recencyFactor * 0.4;
   }
 
   // Metadata richness contribution (0-0.2)
-  let contextScore = 0
-  if (note.metadata?.type) contextScore += 0.05
-  if (note.metadata?.category) contextScore += 0.05
-  if (note.metadata?.tags && note.metadata.tags.length > 0) contextScore += 0.05
-  if (note.metadata?.context) contextScore += 0.05
-  velocity += Math.min(contextScore, 0.2)
+  let contextScore = 0;
+  if (note.metadata?.type) contextScore += 0.05;
+  if (note.metadata?.category) contextScore += 0.05;
+  if (note.metadata?.tags && note.metadata.tags.length > 0)
+    contextScore += 0.05;
+  if (note.metadata?.context) contextScore += 0.05;
+  velocity += Math.min(contextScore, 0.2);
 
   // Clamp to [0.1, 1.0]
-  return Math.max(0.1, Math.min(1.0, velocity))
+  return Math.max(0.1, Math.min(1.0, velocity));
 }
 
 /**
@@ -85,7 +86,7 @@ function calculateNoteVelocity(note: Note): number {
  */
 export const noteAdapter: ItemAdapter<Note> = {
   toGridItem(note: Note, options?: AdapterOptions): GridItem<Note> {
-    const velocity = options?.velocity ?? calculateNoteVelocity(note)
+    const velocity = options?.velocity ?? calculateNoteVelocity(note);
 
     return {
       id: note.id,
@@ -100,25 +101,32 @@ export const noteAdapter: ItemAdapter<Note> = {
       category: note.metadata?.category,
       // Store metadata in metrics for filtering/sorting
       metrics: {
-        priority: note.metadata?.priority === 'urgent' ? 4 : note.metadata?.priority === 'high' ? 3 : note.metadata?.priority === 'medium' ? 2 : 1,
+        priority:
+          note.metadata?.priority === 'urgent'
+            ? 4
+            : note.metadata?.priority === 'high'
+            ? 3
+            : note.metadata?.priority === 'medium'
+            ? 2
+            : 1,
         tagCount: note.metadata?.tags?.length || 0,
       },
-    }
+    };
   },
 
   fromGridItem(item: GridItem<Note>): Note {
     if (!item.data) {
-      throw new Error('GridItem missing note data')
+      throw new Error('GridItem missing note data');
     }
-    return item.data
+    return item.data;
   },
 
   calculateVelocity(note: Note): number {
-    return calculateNoteVelocity(note)
+    return calculateNoteVelocity(note);
   },
 
   extractVisualUrl(note: Note): string | undefined {
     // Notes can have generated visualizations
-    return `/api/notes/${note.id}/visualization`
+    return `/api/notes/${note.id}/visualization`;
   },
-}
+};

package/src/ontology-adapter.ts

@@ -1,49 +1,53 @@
 /**
  * Adapter for embedding ontology entities directly in the grid
- * 
+ *
  * This adapter allows ontology entities from @emotions-app/shared-utils/ontology
  * to be embedded directly in GridItems with full metadata preservation.
  */
 
-import type { OntologyEntity } from '@emotions-app/shared-utils/ontology/types'
-import type { GridItem } from './types'
-import type { ItemAdapter, AdapterOptions } from './adapters'
+import type { OntologyEntity } from '@emotions-app/shared-utils/ontology/types';
+import type { GridItem } from './types';
+import type { ItemAdapter, AdapterOptions } from './adapters';
 
 /**
  * Calculate velocity for an ontology entity based on provenance confidence
  * and recency
  */
 function calculateEntityVelocity(entity: OntologyEntity): number {
-  let velocity = 0.1 // Base minimum
+  let velocity = 0.1; // Base minimum
 
   // Use provenance confidence (0-1) as primary factor
-  const confidence = entity.metadata.provenance.confidence
-  velocity += confidence * 0.5
+  const confidence = entity.metadata.provenance.confidence;
+  velocity += confidence * 0.5;
 
   // Recency factor based on lastModified
   if (entity.metadata.lastModified) {
-    const ageMs = Date.now() - new Date(entity.metadata.lastModified).getTime()
-    const ageHours = ageMs / (1000 * 60 * 60)
-    const recencyFactor = Math.max(0, 1 - ageHours / 168) // Decay over 1 week
-    velocity += recencyFactor * 0.4
+    const ageMs = Date.now() - new Date(entity.metadata.lastModified).getTime();
+    const ageHours = ageMs / (1000 * 60 * 60);
+    const recencyFactor = Math.max(0, 1 - ageHours / 168); // Decay over 1 week
+    velocity += recencyFactor * 0.4;
   }
 
   // Clamp to [0.1, 1.0]
-  return Math.max(0.1, Math.min(1.0, velocity))
+  return Math.max(0.1, Math.min(1.0, velocity));
 }
 
 /**
  * Adapter for embedding ontology entities directly
  */
 export const ontologyEntityAdapter: ItemAdapter<OntologyEntity> = {
-  toGridItem(entity: OntologyEntity, options?: AdapterOptions): GridItem<OntologyEntity> {
-    const velocity = options?.velocity ?? calculateEntityVelocity(entity)
+  toGridItem(
+    entity: OntologyEntity,
+    options?: AdapterOptions
+  ): GridItem<OntologyEntity> {
+    const velocity = options?.velocity ?? calculateEntityVelocity(entity);
 
     return {
       id: entity['@id'],
       type: 'ontology-entity',
       title: entity.label,
-      description: (entity.properties.description as string | undefined) || entity.label,
+      description:
+        (entity.properties.description as string | undefined) || entity.label,
       data: entity,
       ontologyMetadata: {
         entityId: entity['@id'],
@@ -54,24 +58,27 @@ export const ontologyEntityAdapter: ItemAdapter<OntologyEntity> = {
         provenance: entity.metadata.provenance,
       },
       velocity,
-      createdAt: entity.metadata.lastModified || entity.metadata.provenance.extractedAt,
+      createdAt:
+        entity.metadata.lastModified || entity.metadata.provenance.extractedAt,
       // Extract visual URL if available in properties
-      imageUrl: options?.visualUrl || (entity.properties.imageUrl as string | undefined),
-    }
+      imageUrl:
+        options?.visualUrl ||
+        (entity.properties.imageUrl as string | undefined),
+    };
   },
 
   fromGridItem(item: GridItem<OntologyEntity>): OntologyEntity {
     if (!item.data) {
-      throw new Error('GridItem missing ontology entity data')
+      throw new Error('GridItem missing ontology entity data');
     }
-    return item.data
+    return item.data;
   },
 
   calculateVelocity(entity: OntologyEntity): number {
-    return calculateEntityVelocity(entity)
+    return calculateEntityVelocity(entity);
   },
 
   extractVisualUrl(entity: OntologyEntity): string | undefined {
-    return entity.properties.imageUrl as string | undefined
+    return entity.properties.imageUrl as string | undefined;
   },
-}
+};

package/src/stores/uiStore.ts

@@ -1,85 +1,85 @@
 type UIState = {
-  debugOpen: boolean
-  showStats: boolean
-  cameraOpen?: boolean
-  showNarration?: boolean
-}
+  debugOpen: boolean;
+  showStats: boolean;
+  cameraOpen?: boolean;
+  showNarration?: boolean;
+};
 
 // Safe localStorage helpers that never throw
 const safeGetItem = (key: string): string | null => {
   // istanbul ignore next
-  if (typeof window === 'undefined') return null
+  if (typeof window === 'undefined') return null;
   try {
-    return window.localStorage.getItem(key)
+    return window.localStorage.getItem(key);
   } catch {
     // istanbul ignore next
-    return null
+    return null;
   }
-}
+};
 
 const safeSetItem = (key: string, value: string): void => {
   // istanbul ignore next
-  if (typeof window === 'undefined') return
+  if (typeof window === 'undefined') return;
   try {
-    window.localStorage.setItem(key, value)
+    window.localStorage.setItem(key, value);
   } catch {
     // istanbul ignore next - private browsing, quota exceeded
   }
-}
+};
 
 // Initialize showNarration from localStorage if available
-const savedNarration = safeGetItem('hexgrid.showNarration')
-const initialShowNarration = savedNarration === 'true'
+const savedNarration = safeGetItem('hexgrid.showNarration');
+const initialShowNarration = savedNarration === 'true';
 
 const state: UIState = {
   debugOpen: false,
   showStats: false,
   cameraOpen: false,
-  showNarration: initialShowNarration
-}
+  showNarration: initialShowNarration,
+};
 
-const listeners = new Set<(s: UIState) => void>()
+const listeners = new Set<(s: UIState) => void>();
 
 const uiStore = {
   getState(): UIState {
-    return { ...state }
+    return { ...state };
   },
   set(partial: Partial<UIState>) {
-    let changed = false
+    let changed = false;
     for (const k of Object.keys(partial) as (keyof UIState)[]) {
       if (partial[k] !== undefined && state[k] !== partial[k]) {
         // @ts-ignore
-        state[k] = partial[k]
-        changed = true
+        state[k] = partial[k];
+        changed = true;
       }
     }
     if (changed) {
       // Persist showNarration to localStorage for cross-refresh consistency
       if (partial.showNarration !== undefined) {
-        safeSetItem('hexgrid.showNarration', String(!!partial.showNarration))
+        safeSetItem('hexgrid.showNarration', String(!!partial.showNarration));
       }
-      for (const cb of Array.from(listeners)) cb({ ...state })
+      for (const cb of Array.from(listeners)) cb({ ...state });
     }
   },
   subscribe(cb: (s: UIState) => void) {
-    listeners.add(cb)
+    listeners.add(cb);
     // emit current immediately
-    cb({ ...state })
-    return () => listeners.delete(cb)
+    cb({ ...state });
+    return () => listeners.delete(cb);
   },
   toggleDebug() {
-    this.set({ debugOpen: !state.debugOpen })
+    this.set({ debugOpen: !state.debugOpen });
   },
   toggleStats() {
-    this.set({ showStats: !state.showStats })
+    this.set({ showStats: !state.showStats });
   },
   toggleCamera() {
-    this.set({ cameraOpen: !state.cameraOpen })
+    this.set({ cameraOpen: !state.cameraOpen });
   },
   toggleNarration() {
-    this.set({ showNarration: !state.showNarration })
-  }
-}
+    this.set({ showNarration: !state.showNarration });
+  },
+};
 
-export { uiStore }
-export default uiStore
+export { uiStore };
+export default uiStore;

package/src/types.ts

@@ -2,68 +2,68 @@
  * Type definitions for HexGrid Visualization
  */
 
-import type { RefObject } from 'react'
-import type { HexGridFeatureFlags } from './features'
+import type { RefObject } from 'react';
+import type { HexGridFeatureFlags } from './features';
 
 /**
  * Photo type for HexGrid visualization
- * 
+ *
  * This is the unified Photo type used throughout the hexgrid-3d package.
  * It includes all fields needed for display, media playback, and analytics.
  */
 export interface Photo {
-  id: string
-  title: string
-  
+  id: string;
+  title: string;
+
   // Image URLs - imageUrl is primary, url is for backward compatibility
-  imageUrl: string
-  url?: string  // Alias for imageUrl (backward compatibility)
-  thumbnailUrl?: string
-  
+  imageUrl: string;
+  url?: string; // Alias for imageUrl (backward compatibility)
+  thumbnailUrl?: string;
+
   // Display metadata
-  alt: string
-  category: string
-  description?: string
-  
+  alt: string;
+  category: string;
+  description?: string;
+
   // Source information
-  source: string
-  sourceUrl?: string
-  createdAt?: string
-  
+  source: string;
+  sourceUrl?: string;
+  createdAt?: string;
+
   // Shop integration
-  shopUrl?: string
-  location?: string
-  
+  shopUrl?: string;
+  location?: string;
+
   // Media type flags
-  isVideo?: boolean
-  videoUrl?: string
-  isTweet?: boolean
-  tweetUrl?: string
-  redditUrl?: string
-  durationSeconds?: number
-  
+  isVideo?: boolean;
+  videoUrl?: string;
+  isTweet?: boolean;
+  tweetUrl?: string;
+  redditUrl?: string;
+  durationSeconds?: number;
+
   // Competition/ranking system
-  velocity?: number  // Normalized velocity [0.1, 1.0] for meritocratic competition
-  
+  velocity?: number; // Normalized velocity [0.1, 1.0] for meritocratic competition
+
   // User info
-  userId?: string
-  username?: string
-  platform?: string
-  author?: string
-  authorUrl?: string
-  
+  userId?: string;
+  username?: string;
+  platform?: string;
+  author?: string;
+  authorUrl?: string;
+
   // Metrics for analytics
-  views?: number
-  likes?: number
-  comments?: number
-  shares?: number
-  upvotes?: number
-  retweets?: number
-  replies?: number
-  age_in_hours?: number
-  
+  views?: number;
+  likes?: number;
+  comments?: number;
+  shares?: number;
+  upvotes?: number;
+  retweets?: number;
+  replies?: number;
+  age_in_hours?: number;
+
   // Visual
-  dominantColor?: string
+  dominantColor?: string;
 }
 
 /**
@@ -72,81 +72,92 @@ export interface Photo {
  */
 export interface GridItem<T = unknown> {
   // Core identification
-  id: string
-  type: string // 'photo' | 'note' | 'emotion' | 'ontology-entity' | 'custom'
+  id: string;
+  type: string; // 'photo' | 'note' | 'emotion' | 'ontology-entity' | 'custom'
 
   // Visual representation (optional - allows non-visual items)
-  imageUrl?: string
-  thumbnailUrl?: string
-  videoUrl?: string
+  imageUrl?: string;
+  thumbnailUrl?: string;
+  videoUrl?: string;
 
   // Display metadata
-  title?: string
-  alt?: string
-  description?: string
-  category?: string
+  title?: string;
+  alt?: string;
+  description?: string;
+  category?: string;
 
   // Embedded data object (preserves original type)
-  data?: T
+  data?: T;
 
   // Ontology metadata (optional, for ontology-aware items)
   ontologyMetadata?: {
-    entityId?: string
-    entityType?: string | string[]
-    properties?: Record<string, unknown>
+    entityId?: string;
+    entityType?: string | string[];
+    properties?: Record<string, unknown>;
     provenance?: {
-      source: string
-      extractedAt: string
-      confidence: number
-    }
-  }
+      source: string;
+      extractedAt: string;
+      confidence: number;
+    };
+  };
 
   // Grid behavior
-  velocity?: number
-  source?: string
-  sourceUrl?: string
-  createdAt?: string
+  velocity?: number;
+  source?: string;
+  sourceUrl?: string;
+  createdAt?: string;
 
   // Metrics (flexible for any data type)
-  metrics?: Record<string, number>
+  metrics?: Record<string, number>;
 
   // Legacy Photo fields (for backward compatibility)
-  url?: string // Maps to imageUrl
-  userId?: string
-  username?: string
-  platform?: string
-  author?: string
-  authorUrl?: string
-  likes?: number
-  views?: number
-  comments?: number
-  dominantColor?: string
+  url?: string; // Maps to imageUrl
+  userId?: string;
+  username?: string;
+  platform?: string;
+  author?: string;
+  authorUrl?: string;
+  likes?: number;
+  views?: number;
+  comments?: number;
+  dominantColor?: string;
 }
 
 export interface HexGridProps {
-  photos: Photo[]
-  onHexClick?: (photo: Photo) => void
-  spacing?: number
-  canvasRef?: RefObject<HTMLCanvasElement>
-  onLeaderboardUpdate?: (leaderboard: any) => void
-  autoplayQueueLimit?: number
-  onAutoplayQueueLimitChange?: (limit: number) => void
-  modalOpen?: boolean
-  userId?: string
-  username?: string
-  featureFlags?: HexGridFeatureFlags
+  photos: Photo[];
+  onHexClick?: (photo: Photo) => void;
+  spacing?: number;
+  canvasRef?: RefObject<HTMLCanvasElement>;
+  onLeaderboardUpdate?: (leaderboard: any) => void;
+  autoplayQueueLimit?: number;
+  onAutoplayQueueLimitChange?: (limit: number) => void;
+  modalOpen?: boolean;
+  userId?: string;
+  username?: string;
+  featureFlags?: HexGridFeatureFlags;
+  enableEnhanced?: boolean;
+  enhancedConfig?: {
+    useWasm?: boolean;
+    enableParticles?: boolean;
+    enableFlowField?: boolean;
+  };
+  onTerritoryEvent?: (event: {
+    type: 'conquest' | 'birth' | 'death';
+    toOwner: number;
+    fromOwner?: number;
+  }) => Promise<void>;
 }
 
 export interface UIState {
-  debugOpen: boolean
-  showStats: boolean
-  cameraOpen: boolean
-  showNarration: boolean
+  debugOpen: boolean;
+  showStats: boolean;
+  cameraOpen: boolean;
+  showNarration: boolean;
 }
 
 export interface WorkerDebug {
-  curveUDeg: number
-  curveVDeg: number
-  batchPerFrame: number
-  [key: string]: any
+  curveUDeg: number;
+  curveVDeg: number;
+  batchPerFrame: number;
+  [key: string]: any;
 }

package/src/utils/image-utils.ts

@@ -12,14 +12,17 @@
  */
 export function getProxiedImageUrl(imageUrl: string): string {
   if (!imageUrl || typeof imageUrl !== 'string') {
-    return imageUrl
+    return imageUrl;
   }
-  
+
   // Only proxy preview.redd.it URLs (they have CORS issues)
   // external-preview.redd.it URLs work fine, so don't proxy them
-  if (imageUrl.includes('preview.redd.it') && !imageUrl.includes('external-preview.redd.it')) {
-    return `/api/proxy-image?url=${encodeURIComponent(imageUrl)}`
+  if (
+    imageUrl.includes('preview.redd.it') &&
+    !imageUrl.includes('external-preview.redd.it')
+  ) {
+    return `/api/proxy-image?url=${encodeURIComponent(imageUrl)}`;
   }
-  
-  return imageUrl
+
+  return imageUrl;
 }