@thehoneyjar/sigil-hud

Diagnostic HUD for Sigil - composable React components for development.

Installation

# Using the official scope
pnpm add @thehoneyjar/sigil-hud

# Optional: Install packages you want to use
pnpm add @thehoneyjar/sigil-lens @thehoneyjar/sigil-fork @thehoneyjar/sigil-simulation @thehoneyjar/sigil-diagnostics

Alias option: If you prefer shorter imports, you can alias the package:

pnpm add @sigil/hud@npm:@thehoneyjar/sigil-hud
pnpm add @sigil/lens@npm:@thehoneyjar/sigil-lens
# etc.

Usage

Basic Setup

import { HudProvider, HudPanel, HudTrigger } from '@thehoneyjar/sigil-hud'
import { createLensService } from '@thehoneyjar/sigil-lens'
import { createDiagnosticsService } from '@thehoneyjar/sigil-diagnostics'

const lensService = createLensService()
const diagnosticsService = createDiagnosticsService()

function App() {
  return (
    <HudProvider
      lensService={lensService}
      diagnosticsService={diagnosticsService}
      config={{
        shortcuts: true,
        position: 'bottom-right',
      }}
    >
      <YourApp />
      <HudTrigger />
      <HudPanel>
        <LensPanel />
        <DiagnosticsPanel />
      </HudPanel>
    </HudProvider>
  )
}

Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | ⌘⇧D | Toggle HUD | | 1-5 | Switch panels (when open) | | Esc | Close HUD |

import { useKeyboardShortcuts } from '@thehoneyjar/sigil-hud'

function MyComponent() {
  useKeyboardShortcuts({ enabled: true })
  // ...
}

Signal Capture

import { useSignalCapture } from '@thehoneyjar/sigil-hud'

function MyComponent() {
  const { accept, modify, reject } = useSignalCapture()

  const handleAccept = () => {
    accept('ClaimButton', 'financial')
  }

  const handleModify = () => {
    modify('ClaimButton', 'financial', {
      from: '800ms',
      to: '500ms',
    })
  }
}

Observation Capture

import { useObservationCapture } from '@thehoneyjar/sigil-hud'

function MyComponent() {
  const { captureUserTruth, captureIssue } = useObservationCapture()

  const handleFeedback = () => {
    captureUserTruth('This button feels too slow for power users', {
      component: 'ClaimButton',
      effect: 'financial',
    })
  }
}

Components

| Component | Description | |-----------|-------------| | HudProvider | Context provider for HUD state and services | | HudPanel | Main panel container | | HudTrigger | Floating button to open HUD | | LensPanel | Address impersonation controls | | SimulationPanel | Transaction simulation info | | DiagnosticsPanel | Physics compliance checking | | StateComparison | Compare real vs impersonated state |

Hooks

| Hook | Description | |------|-------------| | useHud() | Access HUD context | | useKeyboardShortcuts() | Enable keyboard shortcuts | | useSignalCapture() | Capture taste signals | | useObservationCapture() | Capture observations |

Progressive Enhancement

The HUD works with any subset of packages. Features gracefully degrade when packages are not installed:

• No @thehoneyjar/sigil-lens → Lens panel shows "not available" message
• No @thehoneyjar/sigil-simulation → Simulation panel shows "not available" message
• No @thehoneyjar/sigil-diagnostics → Diagnostics panel shows "not available" message

Configuration

interface HudConfig {
  shortcuts?: boolean        // Enable keyboard shortcuts
  position?: HudPosition     // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
  persist?: boolean          // Persist state to localStorage
  observationCapture?: boolean
  signalCapture?: boolean
  defaultPanel?: HudPanelType
}

License

MIT