@thehoneyjar/sigil-hud

Diagnostic HUD for Sigil - composable React components for development.

Installation

``bash


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:

`bash
pnpm add @sigil/hud@npm:@thehoneyjar/sigil-hud
pnpm add @sigil/lens@npm:@thehoneyjar/sigil-lens


etc.


`

Usage

$3

`tsx
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 (
lensService={lensService}
diagnosticsService={diagnosticsService}
config={{
shortcuts: true,
position: 'bottom-right',
}}
>







)
}
`

$3

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

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

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

$3

`tsx
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',
})
}
}
`

$3

`tsx
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

`typescript
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