@thehoneyjar/sigil-hud 0.1.0

package/src/hooks/useSignalCapture.ts

@@ -0,0 +1,138 @@
+/**
+ * Signal Capture Hook
+ *
+ * Capture taste signals from HUD interactions.
+ */
+
+import { useCallback, useRef } from 'react'
+import type { Signal } from '../types'
+
+/**
+ * Props for useSignalCapture
+ */
+export interface UseSignalCaptureProps {
+  /** Whether signal capture is enabled */
+  enabled?: boolean
+  /** Callback when signal is captured */
+  onSignal?: (signal: Signal) => void
+}
+
+/**
+ * Hook to capture taste signals from HUD
+ */
+export function useSignalCapture({
+  enabled = true,
+  onSignal,
+}: UseSignalCaptureProps = {}) {
+  const signalsRef = useRef<Signal[]>([])
+
+  /**
+   * Append a signal to the taste log
+   */
+  const appendSignal = useCallback(
+    async (signalData: Omit<Signal, 'timestamp' | 'source'>): Promise<void> => {
+      if (!enabled) return
+
+      const signal: Signal = {
+        ...signalData,
+        timestamp: new Date().toISOString(),
+        source: 'hud',
+      }
+
+      // Store locally
+      signalsRef.current.push(signal)
+
+      // Notify callback
+      onSignal?.(signal)
+
+      // In a full implementation, this would write to grimoires/sigil/taste.md
+      // For now, we log to console in development
+      if (process.env.NODE_ENV === 'development') {
+        console.log('[Sigil HUD] Signal captured:', signal)
+      }
+    },
+    [enabled, onSignal]
+  )
+
+  /**
+   * Create an ACCEPT signal
+   */
+  const accept = useCallback(
+    (component: string, effect: string, craftType: Signal['component']['craft_type'] = 'generate') => {
+      return appendSignal({
+        signal: 'ACCEPT',
+        component: {
+          name: component,
+          effect,
+          craft_type: craftType,
+        },
+      })
+    },
+    [appendSignal]
+  )
+
+  /**
+   * Create a MODIFY signal
+   */
+  const modify = useCallback(
+    (
+      component: string,
+      effect: string,
+      change: { from: string; to: string },
+      learning?: { inference: string; recommendation?: string }
+    ) => {
+      return appendSignal({
+        signal: 'MODIFY',
+        component: {
+          name: component,
+          effect,
+          craft_type: 'generate',
+        },
+        change,
+        learning,
+      })
+    },
+    [appendSignal]
+  )
+
+  /**
+   * Create a REJECT signal
+   */
+  const reject = useCallback(
+    (component: string, effect: string, reason: string) => {
+      return appendSignal({
+        signal: 'REJECT',
+        component: {
+          name: component,
+          effect,
+          craft_type: 'generate',
+        },
+        rejection_reason: reason,
+      })
+    },
+    [appendSignal]
+  )
+
+  /**
+   * Get all captured signals
+   */
+  const getSignals = useCallback(() => {
+    return [...signalsRef.current]
+  }, [])
+
+  /**
+   * Clear captured signals
+   */
+  const clearSignals = useCallback(() => {
+    signalsRef.current = []
+  }, [])
+
+  return {
+    appendSignal,
+    accept,
+    modify,
+    reject,
+    getSignals,
+    clearSignals,
+  }
+}

package/src/index.ts

@@ -0,0 +1,112 @@
+/**
+ * @sigil/hud
+ *
+ * Diagnostic HUD for Sigil - composable React components for development.
+ */
+
+// Types
+export type {
+  HudPosition,
+  HudConfig,
+  HudPanelType,
+  HudState,
+  HudActions,
+  HudContextValue,
+  HudProviderProps,
+  Observation,
+  Signal,
+  // Service types (mirrored from optional packages)
+  LensService,
+  LensState,
+  ForkService,
+  ForkState,
+  SimulationService,
+  SimulationState,
+  DiagnosticsService,
+  DiagnosticResult,
+  DiagnosticIssue,
+  EffectType,
+  ComplianceResult,
+  BehavioralCompliance,
+  AnimationCompliance,
+  MaterialCompliance,
+} from './types'
+
+export {
+  DEFAULT_HUD_STATE,
+  DEFAULT_HUD_CONFIG,
+  DEFAULT_LENS_STATE,
+} from './types'
+
+// Store
+export { useHudStore, getHudState } from './store'
+export type { HudStore } from './store'
+
+// Provider
+export { HudProvider, useHud, useHudOptional } from './providers/HudProvider'
+
+// Components
+export { HudPanel } from './components/HudPanel'
+export type { HudPanelProps } from './components/HudPanel'
+
+export { HudTrigger } from './components/HudTrigger'
+export type { HudTriggerProps } from './components/HudTrigger'
+
+export { LensPanel } from './components/LensPanel'
+export type { LensPanelProps } from './components/LensPanel'
+
+export { SimulationPanel } from './components/SimulationPanel'
+export type { SimulationPanelProps } from './components/SimulationPanel'
+
+export { DiagnosticsPanel } from './components/DiagnosticsPanel'
+export type { DiagnosticsPanelProps } from './components/DiagnosticsPanel'
+
+export { PhysicsAnalysis } from './components/PhysicsAnalysis'
+export type { PhysicsAnalysisProps } from './components/PhysicsAnalysis'
+
+export { IssueList } from './components/IssueList'
+export type { IssueListProps } from './components/IssueList'
+
+export { DataSourceIndicator } from './components/DataSourceIndicator'
+export type { DataSourceIndicatorProps, DataSourceType } from './components/DataSourceIndicator'
+
+export { StateComparison } from './components/StateComparison'
+export type { StateComparisonProps } from './components/StateComparison'
+
+export { ObservationCaptureModal } from './components/ObservationCaptureModal'
+export type { ObservationCaptureModalProps } from './components/ObservationCaptureModal'
+
+export { FeedbackPrompt } from './components/FeedbackPrompt'
+export type { FeedbackPromptProps } from './components/FeedbackPrompt'
+
+// Hooks
+export { useKeyboardShortcuts, getShortcutHelp } from './hooks/useKeyboardShortcuts'
+export type { UseKeyboardShortcutsProps } from './hooks/useKeyboardShortcuts'
+
+export { useSignalCapture } from './hooks/useSignalCapture'
+export type { UseSignalCaptureProps } from './hooks/useSignalCapture'
+
+export { useObservationCapture } from './hooks/useObservationCapture'
+export type { UseObservationCaptureProps } from './hooks/useObservationCapture'
+
+export { useDataSource, useMultipleDataSources } from './hooks/useDataSource'
+export type {
+  UseDataSourceProps,
+  DataSourceMeta,
+  DataSourceEntry,
+} from './hooks/useDataSource'
+
+// Theme
+export {
+  colors,
+  typography,
+  spacing,
+  radii,
+  shadows,
+  transitions,
+  zIndex,
+  patterns,
+  effectColors,
+  getEffectColor,
+  createStyles,
+} from './styles/theme'

package/src/providers/HudProvider.tsx

@@ -0,0 +1,115 @@
+/**
+ * HUD Provider
+ *
+ * Context provider for HUD state and services.
+ */
+
+import { createContext, useContext, useMemo } from 'react'
+import type { HudProviderProps, HudContextValue, HudConfig } from '../types'
+import { DEFAULT_HUD_CONFIG, DEFAULT_HUD_STATE } from '../types'
+import { useHudStore } from '../store'
+
+/**
+ * HUD context
+ */
+const HudContext = createContext<HudContextValue | null>(null)
+
+/**
+ * HUD Provider component
+ */
+export function HudProvider({
+  children,
+  config = {},
+  lensService,
+  forkService,
+  simulationService,
+  diagnosticsService,
+  anchorClient,
+}: HudProviderProps) {
+  // Get state and actions from store
+  const isOpen = useHudStore((state) => state.isOpen)
+  const activePanel = useHudStore((state) => state.activePanel)
+  const position = useHudStore((state) => state.position)
+  const isMinimized = useHudStore((state) => state.isMinimized)
+  const open = useHudStore((state) => state.open)
+  const close = useHudStore((state) => state.close)
+  const toggle = useHudStore((state) => state.toggle)
+  const setActivePanel = useHudStore((state) => state.setActivePanel)
+  const setPosition = useHudStore((state) => state.setPosition)
+  const toggleMinimized = useHudStore((state) => state.toggleMinimized)
+
+  // Merge config with defaults
+  const mergedConfig: HudConfig = useMemo(
+    () => ({
+      ...DEFAULT_HUD_CONFIG,
+      ...config,
+    }),
+    [config]
+  )
+
+  // Build context value
+  const value: HudContextValue = useMemo(
+    () => ({
+      // State
+      isOpen,
+      activePanel,
+      position,
+      isMinimized,
+      // Actions
+      open,
+      close,
+      toggle,
+      setActivePanel,
+      setPosition,
+      toggleMinimized,
+      // Services
+      lensService: lensService ?? null,
+      forkService: forkService ?? null,
+      simulationService: simulationService ?? null,
+      diagnosticsService: diagnosticsService ?? null,
+      anchorClient: anchorClient ?? null,
+      // Config
+      config: mergedConfig,
+    }),
+    [
+      isOpen,
+      activePanel,
+      position,
+      isMinimized,
+      open,
+      close,
+      toggle,
+      setActivePanel,
+      setPosition,
+      toggleMinimized,
+      lensService,
+      forkService,
+      simulationService,
+      diagnosticsService,
+      anchorClient,
+      mergedConfig,
+    ]
+  )
+
+  return <HudContext.Provider value={value}>{children}</HudContext.Provider>
+}
+
+/**
+ * Hook to access HUD context
+ *
+ * @throws Error if used outside HudProvider
+ */
+export function useHud(): HudContextValue {
+  const context = useContext(HudContext)
+  if (!context) {
+    throw new Error('useHud must be used within a HudProvider')
+  }
+  return context
+}
+
+/**
+ * Hook to access HUD context (returns null if not in provider)
+ */
+export function useHudOptional(): HudContextValue | null {
+  return useContext(HudContext)
+}

package/src/store.ts

@@ -0,0 +1,60 @@
+/**
+ * HUD Store
+ *
+ * Zustand store for HUD state management.
+ */
+
+import { create } from 'zustand'
+import { persist } from 'zustand/middleware'
+import type { HudState, HudActions, HudPosition, HudPanelType } from './types'
+import { DEFAULT_HUD_STATE } from './types'
+
+/**
+ * Combined HUD store type
+ */
+export type HudStore = HudState & HudActions
+
+/**
+ * Create the HUD store
+ */
+export const useHudStore = create<HudStore>()(
+  persist(
+    (set) => ({
+      ...DEFAULT_HUD_STATE,
+
+      open: () => set({ isOpen: true }),
+
+      close: () => set({ isOpen: false }),
+
+      toggle: () => set((state) => ({ isOpen: !state.isOpen })),
+
+      setActivePanel: (panel: HudPanelType | null) =>
+        set({ activePanel: panel }),
+
+      setPosition: (position: HudPosition) => set({ position }),
+
+      toggleMinimized: () =>
+        set((state) => ({ isMinimized: !state.isMinimized })),
+    }),
+    {
+      name: 'sigil-hud-storage',
+      partialize: (state) => ({
+        position: state.position,
+        isMinimized: state.isMinimized,
+      }),
+    }
+  )
+)
+
+/**
+ * Get HUD store state (for non-React contexts)
+ */
+export function getHudState(): HudState {
+  const state = useHudStore.getState()
+  return {
+    isOpen: state.isOpen,
+    activePanel: state.activePanel,
+    position: state.position,
+    isMinimized: state.isMinimized,
+  }
+}

package/src/styles/theme.ts

@@ -0,0 +1,256 @@
+/**
+ * HUD Theme Constants
+ *
+ * Shared design tokens for consistent styling across HUD components.
+ * Implements TASK-205 styling requirements.
+ */
+
+/**
+ * Color palette
+ */
+export const colors = {
+  // Brand
+  primary: '#10b981', // emerald-500
+  primaryLight: 'rgba(16, 185, 129, 0.2)',
+  primaryBorder: 'rgba(16, 185, 129, 0.3)',
+
+  // Status
+  success: '#22c55e', // green-500
+  successLight: 'rgba(34, 197, 94, 0.1)',
+  successBorder: 'rgba(34, 197, 94, 0.3)',
+
+  warning: '#eab308', // yellow-500
+  warningLight: 'rgba(234, 179, 8, 0.1)',
+  warningBorder: 'rgba(234, 179, 8, 0.3)',
+
+  error: '#ef4444', // red-500
+  errorLight: 'rgba(239, 68, 68, 0.1)',
+  errorBorder: 'rgba(239, 68, 68, 0.3)',
+
+  info: '#3b82f6', // blue-500
+  infoLight: 'rgba(59, 130, 246, 0.1)',
+  infoBorder: 'rgba(59, 130, 246, 0.3)',
+
+  // Neutral
+  text: '#fff',
+  textMuted: '#888',
+  textDim: '#666',
+  textDisabled: '#555',
+
+  background: 'rgba(0, 0, 0, 0.9)',
+  backgroundElevated: 'rgba(26, 26, 26, 1)',
+  backgroundHover: 'rgba(255, 255, 255, 0.05)',
+  backgroundActive: 'rgba(255, 255, 255, 0.08)',
+  backgroundInput: 'rgba(255, 255, 255, 0.02)',
+
+  border: 'rgba(255, 255, 255, 0.1)',
+  borderSubtle: 'rgba(255, 255, 255, 0.05)',
+  borderStrong: 'rgba(255, 255, 255, 0.2)',
+
+  // Effects
+  financial: '#ef4444',
+  destructive: '#f97316',
+  softDelete: '#eab308',
+  standard: '#22c55e',
+  local: '#3b82f6',
+  navigation: '#8b5cf6',
+  query: '#06b6d4',
+} as const
+
+/**
+ * Typography
+ */
+export const typography = {
+  fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace',
+  fontFamilySans: 'ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, sans-serif',
+
+  // Sizes
+  xs: '10px',
+  sm: '11px',
+  base: '12px',
+  md: '13px',
+  lg: '14px',
+
+  // Weights
+  normal: 400,
+  medium: 500,
+  semibold: 600,
+  bold: 700,
+
+  // Line heights
+  lineHeightTight: 1.25,
+  lineHeightNormal: 1.5,
+  lineHeightRelaxed: 1.6,
+
+  // Letter spacing
+  letterSpacingTight: '-0.02em',
+  letterSpacingNormal: '0',
+  letterSpacingWide: '0.5px',
+} as const
+
+/**
+ * Spacing
+ */
+export const spacing = {
+  xs: '4px',
+  sm: '6px',
+  md: '8px',
+  lg: '12px',
+  xl: '16px',
+  '2xl': '20px',
+  '3xl': '24px',
+} as const
+
+/**
+ * Border radius
+ */
+export const radii = {
+  sm: '4px',
+  md: '6px',
+  lg: '8px',
+  xl: '12px',
+  full: '9999px',
+} as const
+
+/**
+ * Shadows
+ */
+export const shadows = {
+  sm: '0 2px 4px rgba(0, 0, 0, 0.2)',
+  md: '0 4px 12px rgba(0, 0, 0, 0.3)',
+  lg: '0 8px 20px rgba(0, 0, 0, 0.4)',
+  xl: '0 20px 40px rgba(0, 0, 0, 0.5)',
+  primary: '0 4px 12px rgba(16, 185, 129, 0.3)',
+  primaryHover: '0 6px 16px rgba(16, 185, 129, 0.4)',
+} as const
+
+/**
+ * Transitions
+ */
+export const transitions = {
+  fast: '0.1s ease-out',
+  normal: '0.15s ease-out',
+  slow: '0.2s ease-out',
+  spring: '0.3s cubic-bezier(0.34, 1.56, 0.64, 1)',
+} as const
+
+/**
+ * Z-index
+ */
+export const zIndex = {
+  base: 1,
+  dropdown: 100,
+  sticky: 1000,
+  fixed: 5000,
+  modal: 10000,
+  tooltip: 15000,
+} as const
+
+/**
+ * Common style patterns
+ */
+export const patterns = {
+  // Buttons
+  button: {
+    base: {
+      padding: `${spacing.md} ${spacing.lg}`,
+      borderRadius: radii.md,
+      fontSize: typography.sm,
+      fontWeight: typography.medium,
+      cursor: 'pointer',
+      transition: transitions.normal,
+      border: '1px solid',
+    },
+    primary: {
+      backgroundColor: colors.primaryLight,
+      borderColor: colors.primaryBorder,
+      color: colors.primary,
+    },
+    secondary: {
+      backgroundColor: colors.backgroundInput,
+      borderColor: colors.border,
+      color: colors.textMuted,
+    },
+    danger: {
+      backgroundColor: colors.errorLight,
+      borderColor: colors.errorBorder,
+      color: colors.error,
+    },
+  },
+
+  // Inputs
+  input: {
+    base: {
+      padding: spacing.md,
+      backgroundColor: colors.backgroundInput,
+      border: `1px solid ${colors.border}`,
+      borderRadius: radii.md,
+      color: colors.text,
+      fontSize: typography.sm,
+      fontFamily: typography.fontFamily,
+    },
+  },
+
+  // Cards
+  card: {
+    base: {
+      padding: spacing.lg,
+      backgroundColor: 'rgba(0, 0, 0, 0.2)',
+      borderRadius: radii.lg,
+      border: `1px solid ${colors.borderSubtle}`,
+    },
+  },
+
+  // Labels
+  label: {
+    base: {
+      fontSize: typography.xs,
+      fontWeight: typography.semibold,
+      color: colors.textMuted,
+      textTransform: 'uppercase' as const,
+      letterSpacing: typography.letterSpacingWide,
+    },
+  },
+
+  // Badges
+  badge: {
+    base: {
+      padding: `2px ${spacing.sm}`,
+      borderRadius: radii.sm,
+      fontSize: '9px',
+      fontWeight: typography.semibold,
+      border: '1px solid',
+      textTransform: 'uppercase' as const,
+      letterSpacing: '0.3px',
+    },
+  },
+} as const
+
+/**
+ * Effect type to color mapping
+ */
+export const effectColors: Record<string, string> = {
+  financial: colors.financial,
+  destructive: colors.destructive,
+  'soft-delete': colors.softDelete,
+  standard: colors.standard,
+  local: colors.local,
+  navigation: colors.navigation,
+  query: colors.query,
+}
+
+/**
+ * Get effect color
+ */
+export function getEffectColor(effect: string): string {
+  return effectColors[effect] ?? colors.textMuted
+}
+
+/**
+ * Create CSS properties object
+ */
+export function createStyles<T extends Record<string, React.CSSProperties>>(
+  styles: T
+): T {
+  return styles
+}