@thehoneyjar/sigil-hud 0.1.0

package/src/hooks/useDataSource.ts

@@ -0,0 +1,324 @@
+/**
+ * Data Source Hook
+ *
+ * Track data source and staleness for displayed values.
+ * Implements TASK-202: State source tracing.
+ */
+
+import { useState, useCallback, useEffect, useRef } from 'react'
+import type { DataSourceType } from '../components/DataSourceIndicator'
+
+/**
+ * Data source metadata
+ */
+export interface DataSourceMeta {
+  /** Data source type */
+  source: DataSourceType
+  /** When the data was fetched */
+  fetchedAt: number
+  /** Block number (for on-chain data) */
+  blockNumber?: number
+  /** Current block (for staleness calculation) */
+  currentBlock?: number
+  /** Whether the data is stale */
+  isStale: boolean
+  /** Staleness level */
+  stalenessLevel: 'fresh' | 'stale' | 'very-stale'
+  /** Human-readable staleness label */
+  stalenessLabel: string
+}
+
+/**
+ * Props for useDataSource
+ */
+export interface UseDataSourceProps {
+  /** Data source type */
+  source: DataSourceType
+  /** Block number for on-chain data */
+  blockNumber?: number
+  /** Interval to check staleness (ms) */
+  pollInterval?: number
+  /** Threshold for "stale" in seconds (for time-based) */
+  staleThresholdSeconds?: number
+  /** Threshold for "very stale" in seconds (for time-based) */
+  veryStaleThresholdSeconds?: number
+  /** Threshold for "stale" in blocks (for block-based) */
+  staleThresholdBlocks?: number
+  /** Threshold for "very stale" in blocks (for block-based) */
+  veryStaleThresholdBlocks?: number
+  /** Callback when data becomes stale */
+  onStale?: () => void
+}
+
+/**
+ * Default staleness thresholds
+ */
+const DEFAULT_STALE_SECONDS = 60 // 1 minute
+const DEFAULT_VERY_STALE_SECONDS = 300 // 5 minutes
+const DEFAULT_STALE_BLOCKS = 5
+const DEFAULT_VERY_STALE_BLOCKS = 20
+const DEFAULT_POLL_INTERVAL = 10000 // 10 seconds
+
+/**
+ * Calculate staleness for time-based data
+ */
+function calculateTimeStaleness(
+  fetchedAt: number,
+  staleThreshold: number,
+  veryStaleThreshold: number
+): { isStale: boolean; level: 'fresh' | 'stale' | 'very-stale'; label: string } {
+  const secondsAgo = Math.floor((Date.now() - fetchedAt) / 1000)
+
+  if (secondsAgo < 30) {
+    return { isStale: false, level: 'fresh', label: 'just now' }
+  }
+  if (secondsAgo < 60) {
+    return { isStale: false, level: 'fresh', label: `${secondsAgo}s ago` }
+  }
+  if (secondsAgo < staleThreshold) {
+    return { isStale: false, level: 'fresh', label: `${Math.floor(secondsAgo / 60)}m ago` }
+  }
+  if (secondsAgo < veryStaleThreshold) {
+    return { isStale: true, level: 'stale', label: `${Math.floor(secondsAgo / 60)}m ago` }
+  }
+  return { isStale: true, level: 'very-stale', label: `${Math.floor(secondsAgo / 60)}m ago` }
+}
+
+/**
+ * Calculate staleness for block-based data
+ */
+function calculateBlockStaleness(
+  blockNumber: number,
+  currentBlock: number,
+  staleThreshold: number,
+  veryStaleThreshold: number
+): { isStale: boolean; level: 'fresh' | 'stale' | 'very-stale'; label: string } {
+  const blocksBehind = currentBlock - blockNumber
+
+  if (blocksBehind <= 1) {
+    return { isStale: false, level: 'fresh', label: 'current' }
+  }
+  if (blocksBehind <= staleThreshold) {
+    return { isStale: false, level: 'fresh', label: `${blocksBehind} blocks behind` }
+  }
+  if (blocksBehind <= veryStaleThreshold) {
+    return { isStale: true, level: 'stale', label: `${blocksBehind} blocks behind` }
+  }
+  return { isStale: true, level: 'very-stale', label: `${blocksBehind} blocks behind` }
+}
+
+/**
+ * Hook to track data source and staleness
+ */
+export function useDataSource({
+  source,
+  blockNumber,
+  pollInterval = DEFAULT_POLL_INTERVAL,
+  staleThresholdSeconds = DEFAULT_STALE_SECONDS,
+  veryStaleThresholdSeconds = DEFAULT_VERY_STALE_SECONDS,
+  staleThresholdBlocks = DEFAULT_STALE_BLOCKS,
+  veryStaleThresholdBlocks = DEFAULT_VERY_STALE_BLOCKS,
+  onStale,
+}: UseDataSourceProps) {
+  const [meta, setMeta] = useState<DataSourceMeta>(() => ({
+    source,
+    fetchedAt: Date.now(),
+    blockNumber,
+    currentBlock: blockNumber,
+    isStale: false,
+    stalenessLevel: 'fresh',
+    stalenessLabel: 'just now',
+  }))
+
+  const wasStaleRef = useRef(false)
+  const onStaleRef = useRef(onStale)
+  onStaleRef.current = onStale
+
+  /**
+   * Mark data as refreshed
+   */
+  const markRefreshed = useCallback(
+    (newBlockNumber?: number) => {
+      setMeta((prev) => ({
+        ...prev,
+        fetchedAt: Date.now(),
+        blockNumber: newBlockNumber ?? prev.blockNumber,
+        currentBlock: newBlockNumber ?? prev.currentBlock,
+        isStale: false,
+        stalenessLevel: 'fresh',
+        stalenessLabel: 'just now',
+      }))
+      wasStaleRef.current = false
+    },
+    []
+  )
+
+  /**
+   * Update current block (for on-chain data)
+   */
+  const updateCurrentBlock = useCallback((newCurrentBlock: number) => {
+    setMeta((prev) => ({
+      ...prev,
+      currentBlock: newCurrentBlock,
+    }))
+  }, [])
+
+  /**
+   * Recalculate staleness
+   */
+  const recalculateStaleness = useCallback(() => {
+    setMeta((prev) => {
+      let staleness: { isStale: boolean; level: 'fresh' | 'stale' | 'very-stale'; label: string }
+
+      if (source === 'on-chain' && prev.blockNumber && prev.currentBlock) {
+        staleness = calculateBlockStaleness(
+          prev.blockNumber,
+          prev.currentBlock,
+          staleThresholdBlocks,
+          veryStaleThresholdBlocks
+        )
+      } else {
+        staleness = calculateTimeStaleness(
+          prev.fetchedAt,
+          staleThresholdSeconds,
+          veryStaleThresholdSeconds
+        )
+      }
+
+      // Trigger callback when becoming stale
+      if (staleness.isStale && !wasStaleRef.current) {
+        wasStaleRef.current = true
+        onStaleRef.current?.()
+      }
+
+      return {
+        ...prev,
+        isStale: staleness.isStale,
+        stalenessLevel: staleness.level,
+        stalenessLabel: staleness.label,
+      }
+    })
+  }, [
+    source,
+    staleThresholdSeconds,
+    veryStaleThresholdSeconds,
+    staleThresholdBlocks,
+    veryStaleThresholdBlocks,
+  ])
+
+  // Poll for staleness updates
+  useEffect(() => {
+    const interval = setInterval(recalculateStaleness, pollInterval)
+    return () => clearInterval(interval)
+  }, [recalculateStaleness, pollInterval])
+
+  // Recalculate when source changes
+  useEffect(() => {
+    setMeta((prev) => ({
+      ...prev,
+      source,
+      blockNumber: blockNumber ?? prev.blockNumber,
+    }))
+    recalculateStaleness()
+  }, [source, blockNumber, recalculateStaleness])
+
+  return {
+    meta,
+    markRefreshed,
+    updateCurrentBlock,
+    recalculateStaleness,
+  }
+}
+
+/**
+ * Props for multiple data sources
+ */
+export interface DataSourceEntry {
+  /** Unique key for this data source */
+  key: string
+  /** Data source type */
+  source: DataSourceType
+  /** Block number (for on-chain) */
+  blockNumber?: number
+  /** Label for display */
+  label?: string
+}
+
+/**
+ * Hook to track multiple data sources
+ */
+export function useMultipleDataSources(entries: DataSourceEntry[]) {
+  const [sources, setSources] = useState<Map<string, DataSourceMeta>>(new Map())
+
+  // Initialize sources
+  useEffect(() => {
+    const newSources = new Map<string, DataSourceMeta>()
+    const now = Date.now()
+
+    for (const entry of entries) {
+      newSources.set(entry.key, {
+        source: entry.source,
+        fetchedAt: now,
+        blockNumber: entry.blockNumber,
+        currentBlock: entry.blockNumber,
+        isStale: false,
+        stalenessLevel: 'fresh',
+        stalenessLabel: 'just now',
+      })
+    }
+
+    setSources(newSources)
+  }, [entries])
+
+  /**
+   * Mark a specific source as refreshed
+   */
+  const markRefreshed = useCallback((key: string, newBlockNumber?: number) => {
+    setSources((prev) => {
+      const newMap = new Map(prev)
+      const existing = newMap.get(key)
+      if (existing) {
+        newMap.set(key, {
+          ...existing,
+          fetchedAt: Date.now(),
+          blockNumber: newBlockNumber ?? existing.blockNumber,
+          currentBlock: newBlockNumber ?? existing.currentBlock,
+          isStale: false,
+          stalenessLevel: 'fresh',
+          stalenessLabel: 'just now',
+        })
+      }
+      return newMap
+    })
+  }, [])
+
+  /**
+   * Get metadata for a specific source
+   */
+  const getMeta = useCallback(
+    (key: string): DataSourceMeta | undefined => {
+      return sources.get(key)
+    },
+    [sources]
+  )
+
+  /**
+   * Get all stale sources
+   */
+  const getStaleSources = useCallback((): string[] => {
+    const stale: string[] = []
+    sources.forEach((meta, key) => {
+      if (meta.isStale) {
+        stale.push(key)
+      }
+    })
+    return stale
+  }, [sources])
+
+  return {
+    sources,
+    markRefreshed,
+    getMeta,
+    getStaleSources,
+  }
+}

package/src/hooks/useKeyboardShortcuts.ts

@@ -0,0 +1,125 @@
+/**
+ * Keyboard Shortcuts Hook
+ *
+ * Handle keyboard shortcuts for HUD navigation.
+ */
+
+import { useEffect, useCallback } from 'react'
+import { useHudStore } from '../store'
+import type { HudPanelType } from '../types'
+
+/**
+ * Default keyboard shortcuts
+ */
+const DEFAULT_SHORTCUTS: Record<string, () => void> = {}
+
+/**
+ * Props for useKeyboardShortcuts
+ */
+export interface UseKeyboardShortcutsProps {
+  /** Whether shortcuts are enabled */
+  enabled?: boolean
+  /** Custom shortcuts to add */
+  customShortcuts?: Record<string, () => void>
+}
+
+/**
+ * Hook to handle keyboard shortcuts for HUD
+ */
+export function useKeyboardShortcuts({
+  enabled = true,
+  customShortcuts = {},
+}: UseKeyboardShortcutsProps = {}) {
+  const toggle = useHudStore((state) => state.toggle)
+  const setActivePanel = useHudStore((state) => state.setActivePanel)
+  const isOpen = useHudStore((state) => state.isOpen)
+
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent) => {
+      if (!enabled) return
+
+      // Ignore if typing in an input
+      const target = event.target as HTMLElement
+      if (
+        target.tagName === 'INPUT' ||
+        target.tagName === 'TEXTAREA' ||
+        target.isContentEditable
+      ) {
+        return
+      }
+
+      // Cmd/Ctrl + Shift + D: Toggle HUD
+      if ((event.metaKey || event.ctrlKey) && event.shiftKey && event.key === 'd') {
+        event.preventDefault()
+        toggle()
+        return
+      }
+
+      // Only handle panel shortcuts when HUD is open
+      if (!isOpen) return
+
+      // Number keys for panels when HUD is open
+      const panelMap: Record<string, HudPanelType> = {
+        '1': 'lens',
+        '2': 'simulation',
+        '3': 'diagnostics',
+        '4': 'state',
+        '5': 'signals',
+      }
+
+      if (panelMap[event.key]) {
+        event.preventDefault()
+        setActivePanel(panelMap[event.key])
+        return
+      }
+
+      // Escape to close
+      if (event.key === 'Escape') {
+        event.preventDefault()
+        toggle()
+        return
+      }
+
+      // Custom shortcuts
+      const shortcutKey = getShortcutKey(event)
+      if (customShortcuts[shortcutKey]) {
+        event.preventDefault()
+        customShortcuts[shortcutKey]()
+      }
+    },
+    [enabled, toggle, setActivePanel, isOpen, customShortcuts]
+  )
+
+  useEffect(() => {
+    if (!enabled) return
+
+    window.addEventListener('keydown', handleKeyDown)
+    return () => window.removeEventListener('keydown', handleKeyDown)
+  }, [enabled, handleKeyDown])
+}
+
+/**
+ * Get shortcut key string from event
+ */
+function getShortcutKey(event: KeyboardEvent): string {
+  const parts: string[] = []
+
+  if (event.metaKey) parts.push('cmd')
+  if (event.ctrlKey) parts.push('ctrl')
+  if (event.altKey) parts.push('alt')
+  if (event.shiftKey) parts.push('shift')
+  parts.push(event.key.toLowerCase())
+
+  return parts.join('+')
+}
+
+/**
+ * Get keyboard shortcut help text
+ */
+export function getShortcutHelp(): Array<{ keys: string; description: string }> {
+  return [
+    { keys: '⌘⇧D', description: 'Toggle HUD' },
+    { keys: '1-5', description: 'Switch panels (when open)' },
+    { keys: 'Esc', description: 'Close HUD' },
+  ]
+}

package/src/hooks/useObservationCapture.ts

@@ -0,0 +1,154 @@
+/**
+ * Observation Capture Hook
+ *
+ * Capture user observations and insights from HUD.
+ */
+
+import { useCallback, useRef } from 'react'
+import type { Observation } from '../types'
+
+/**
+ * Props for useObservationCapture
+ */
+export interface UseObservationCaptureProps {
+  /** Whether observation capture is enabled */
+  enabled?: boolean
+  /** Callback when observation is captured */
+  onObservation?: (observation: Observation) => void
+}
+
+/**
+ * Generate a unique observation ID
+ */
+function generateObservationId(): string {
+  const timestamp = Date.now().toString(36)
+  const random = Math.random().toString(36).substring(2, 7)
+  return `obs-${timestamp}-${random}`
+}
+
+/**
+ * Hook to capture observations from HUD
+ */
+export function useObservationCapture({
+  enabled = true,
+  onObservation,
+}: UseObservationCaptureProps = {}) {
+  const observationsRef = useRef<Observation[]>([])
+
+  /**
+   * Capture a new observation
+   */
+  const capture = useCallback(
+    async (
+      content: string,
+      type: Observation['type'] = 'insight',
+      context?: Observation['context'],
+      tags: string[] = []
+    ): Promise<Observation> => {
+      const observation: Observation = {
+        id: generateObservationId(),
+        timestamp: new Date().toISOString(),
+        type,
+        content,
+        tags,
+        context,
+      }
+
+      if (enabled) {
+        // Store locally
+        observationsRef.current.push(observation)
+
+        // Notify callback
+        onObservation?.(observation)
+
+        // In a full implementation, this would write to grimoires/sigil/observations/
+        if (process.env.NODE_ENV === 'development') {
+          console.log('[Sigil HUD] Observation captured:', observation)
+        }
+      }
+
+      return observation
+    },
+    [enabled, onObservation]
+  )
+
+  /**
+   * Capture a user truth observation
+   */
+  const captureUserTruth = useCallback(
+    (content: string, context?: Observation['context']) => {
+      return capture(content, 'user-truth', context, ['user-truth'])
+    },
+    [capture]
+  )
+
+  /**
+   * Capture an issue observation
+   */
+  const captureIssue = useCallback(
+    (content: string, context?: Observation['context']) => {
+      return capture(content, 'issue', context, ['issue'])
+    },
+    [capture]
+  )
+
+  /**
+   * Capture an insight observation
+   */
+  const captureInsight = useCallback(
+    (content: string, context?: Observation['context']) => {
+      return capture(content, 'insight', context, ['insight'])
+    },
+    [capture]
+  )
+
+  /**
+   * Link an observation to signals
+   */
+  const linkToSignals = useCallback(
+    (observationId: string, signalIds: string[]) => {
+      const observation = observationsRef.current.find(
+        (o) => o.id === observationId
+      )
+      if (observation) {
+        observation.linkedSignals = [
+          ...(observation.linkedSignals ?? []),
+          ...signalIds,
+        ]
+      }
+    },
+    []
+  )
+
+  /**
+   * Get all captured observations
+   */
+  const getObservations = useCallback(() => {
+    return [...observationsRef.current]
+  }, [])
+
+  /**
+   * Get observations by type
+   */
+  const getObservationsByType = useCallback((type: Observation['type']) => {
+    return observationsRef.current.filter((o) => o.type === type)
+  }, [])
+
+  /**
+   * Clear captured observations
+   */
+  const clearObservations = useCallback(() => {
+    observationsRef.current = []
+  }, [])
+
+  return {
+    capture,
+    captureUserTruth,
+    captureIssue,
+    captureInsight,
+    linkToSignals,
+    getObservations,
+    getObservationsByType,
+    clearObservations,
+  }
+}