@buley/hexgrid-3d 1.0.0

package/src/note-adapter.ts

@@ -0,0 +1,124 @@
+/**
+ * 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'
+
+/**
+ * Note content structure
+ */
+export interface NoteContent {
+  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[]
+}
+
+/**
+ * Note structure matching Affectively's note format
+ */
+export interface Note {
+  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
+
+  // Priority contribution (0-0.3)
+  const priorityMap: Record<string, number> = {
+    urgent: 0.3,
+    high: 0.2,
+    medium: 0.1,
+    low: 0.05,
+  }
+  if (note.metadata?.priority) {
+    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
+  }
+
+  // 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)
+
+  // Clamp to [0.1, 1.0]
+  return Math.max(0.1, Math.min(1.0, velocity))
+}
+
+/**
+ * Adapter for embedding notes directly
+ */
+export const noteAdapter: ItemAdapter<Note> = {
+  toGridItem(note: Note, options?: AdapterOptions): GridItem<Note> {
+    const velocity = options?.velocity ?? calculateNoteVelocity(note)
+
+    return {
+      id: note.id,
+      type: 'note',
+      title: note.content.title || 'Untitled Note',
+      description: note.content.summary || note.content.text.substring(0, 200),
+      data: note,
+      createdAt: note.date,
+      velocity,
+      // Notes can have generated visualizations
+      imageUrl: options?.visualUrl || `/api/notes/${note.id}/visualization`,
+      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,
+        tagCount: note.metadata?.tags?.length || 0,
+      },
+    }
+  },
+
+  fromGridItem(item: GridItem<Note>): Note {
+    if (!item.data) {
+      throw new Error('GridItem missing note data')
+    }
+    return item.data
+  },
+
+  calculateVelocity(note: Note): number {
+    return calculateNoteVelocity(note)
+  },
+
+  extractVisualUrl(note: Note): string | undefined {
+    // Notes can have generated visualizations
+    return `/api/notes/${note.id}/visualization`
+  },
+}

package/src/ontology-adapter.ts

@@ -0,0 +1,77 @@
+/**
+ * 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'
+
+/**
+ * Calculate velocity for an ontology entity based on provenance confidence
+ * and recency
+ */
+function calculateEntityVelocity(entity: OntologyEntity): number {
+  let velocity = 0.1 // Base minimum
+
+  // Use provenance confidence (0-1) as primary factor
+  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
+  }
+
+  // Clamp to [0.1, 1.0]
+  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)
+
+    return {
+      id: entity['@id'],
+      type: 'ontology-entity',
+      title: entity.label,
+      description: (entity.properties.description as string | undefined) || entity.label,
+      data: entity,
+      ontologyMetadata: {
+        entityId: entity['@id'],
+        entityType: Array.isArray(entity['@type'])
+          ? entity['@type']
+          : [entity['@type']],
+        properties: entity.properties,
+        provenance: entity.metadata.provenance,
+      },
+      velocity,
+      createdAt: entity.metadata.lastModified || entity.metadata.provenance.extractedAt,
+      // Extract visual URL if available in properties
+      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')
+    }
+    return item.data
+  },
+
+  calculateVelocity(entity: OntologyEntity): number {
+    return calculateEntityVelocity(entity)
+  },
+
+  extractVisualUrl(entity: OntologyEntity): string | undefined {
+    return entity.properties.imageUrl as string | undefined
+  },
+}

package/src/stores/index.ts

@@ -0,0 +1 @@
+export const hexgridStores = {};

package/src/stores/uiStore.ts

@@ -0,0 +1,85 @@
+type UIState = {
+  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
+  try {
+    return window.localStorage.getItem(key)
+  } catch {
+    // istanbul ignore next
+    return null
+  }
+}
+
+const safeSetItem = (key: string, value: string): void => {
+  // istanbul ignore next
+  if (typeof window === 'undefined') return
+  try {
+    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 state: UIState = {
+  debugOpen: false,
+  showStats: false,
+  cameraOpen: false,
+  showNarration: initialShowNarration
+}
+
+const listeners = new Set<(s: UIState) => void>()
+
+const uiStore = {
+  getState(): UIState {
+    return { ...state }
+  },
+  set(partial: Partial<UIState>) {
+    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
+      }
+    }
+    if (changed) {
+      // Persist showNarration to localStorage for cross-refresh consistency
+      if (partial.showNarration !== undefined) {
+        safeSetItem('hexgrid.showNarration', String(!!partial.showNarration))
+      }
+      for (const cb of Array.from(listeners)) cb({ ...state })
+    }
+  },
+  subscribe(cb: (s: UIState) => void) {
+    listeners.add(cb)
+    // emit current immediately
+    cb({ ...state })
+    return () => listeners.delete(cb)
+  },
+  toggleDebug() {
+    this.set({ debugOpen: !state.debugOpen })
+  },
+  toggleStats() {
+    this.set({ showStats: !state.showStats })
+  },
+  toggleCamera() {
+    this.set({ cameraOpen: !state.cameraOpen })
+  },
+  toggleNarration() {
+    this.set({ showNarration: !state.showNarration })
+  }
+}
+
+export { uiStore }
+export default uiStore

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export interface WorkerDebug {
+  enabled: boolean;
+}

package/src/types.ts

@@ -0,0 +1,152 @@
+/**
+ * Type definitions for HexGrid Visualization
+ */
+
+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
+  
+  // Image URLs - imageUrl is primary, url is for backward compatibility
+  imageUrl: string
+  url?: string  // Alias for imageUrl (backward compatibility)
+  thumbnailUrl?: string
+  
+  // Display metadata
+  alt: string
+  category: string
+  description?: string
+  
+  // Source information
+  source: string
+  sourceUrl?: string
+  createdAt?: string
+  
+  // Shop integration
+  shopUrl?: string
+  location?: string
+  
+  // Media type flags
+  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
+  
+  // User info
+  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
+  
+  // Visual
+  dominantColor?: string
+}
+
+/**
+ * Generic item that can represent any data object in the grid
+ * Extends Photo for backward compatibility while adding generic data support
+ */
+export interface GridItem<T = unknown> {
+  // Core identification
+  id: string
+  type: string // 'photo' | 'note' | 'emotion' | 'ontology-entity' | 'custom'
+
+  // Visual representation (optional - allows non-visual items)
+  imageUrl?: string
+  thumbnailUrl?: string
+  videoUrl?: string
+
+  // Display metadata
+  title?: string
+  alt?: string
+  description?: string
+  category?: string
+
+  // Embedded data object (preserves original type)
+  data?: T
+
+  // Ontology metadata (optional, for ontology-aware items)
+  ontologyMetadata?: {
+    entityId?: string
+    entityType?: string | string[]
+    properties?: Record<string, unknown>
+    provenance?: {
+      source: string
+      extractedAt: string
+      confidence: number
+    }
+  }
+
+  // Grid behavior
+  velocity?: number
+  source?: string
+  sourceUrl?: string
+  createdAt?: string
+
+  // Metrics (flexible for any data type)
+  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
+}
+
+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
+}
+
+export interface UIState {
+  debugOpen: boolean
+  showStats: boolean
+  cameraOpen: boolean
+  showNarration: boolean
+}
+
+export interface WorkerDebug {
+  curveUDeg: number
+  curveVDeg: number
+  batchPerFrame: number
+  [key: string]: any
+}

package/src/utils/image-utils.ts

@@ -0,0 +1,25 @@
+/**
+ * Pure utility functions for HexGrid component.
+ * These functions have NO side effects and are deterministic.
+ */
+
+/**
+ * Get proxied image URL for preview.redd.it images (CORS issues).
+ * External preview URLs work fine without proxying.
+ * @pure - No side effects, deterministic
+ * @param imageUrl Original image URL
+ * @returns Proxied URL if needed, otherwise original URL
+ */
+export function getProxiedImageUrl(imageUrl: string): string {
+  if (!imageUrl || typeof imageUrl !== 'string') {
+    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)}`
+  }
+  
+  return imageUrl
+}