@vhyxseal/react is a thin adapter on top of @vhyxseal/core. It provides six headless UI components, three hooks, a context provider, and a higher-order component for wrapping existing components. All business logic lives in core — this package is pure React plumbing.
What the Adapter Provides
SealProvider — context provider that collects contracts and generates the manifest
withAgentContract() — HOC to add a contract to any existing component without modifying it
useContract(id) — reads a registered contract by component id
useCapability() — reads the full capability map with counts
useAgentAction() — tracks agent action lifecycle (standalone, no provider needed)
Button, Input, Form, Nav, Display, Confirmation — headless components with contract registration built in
Installation
npm install @vhyxseal/react @vhyxseal/core
React ≥ 18 required. Works with React 19. Fully compatible with Next.js App Router (including Server Components) and Pages Router.
Full Setup
Place SealProvider at the root of your component tree. Every VhyxSeal component in the subtree automatically registers its contract.
app/layout.tsx
// app/layout.tsx — wrap your applicationimport { SealProvider } from '@vhyxseal/react'import type { ManifestConfig } from '@vhyxseal/core'const config: ManifestConfig = { domain: "example.com", domainVerified: false, verificationToken: "", // Optional — all have defaults agentPolicy: { allowedAgents: ["*"], requiresConfirmation: ["place-order", "delete-account"], }, cacheDurationSeconds: 3600, schemaVersion: "1.0.0",}export default function RootLayout({ children }: { children: React.ReactNode }) { return ( <html lang="en"> <body> <SealProvider config={config} onManifestGenerated={(manifest) => { console.log('[VhyxSeal] Manifest updated:', manifest.fingerprint) }} > {children} </SealProvider> </body> </html> )}
SealProvider Configuration
The SealProvider config maps directly to ManifestConfig from @vhyxseal/core.
Prop
Type
Description
config
ManifestConfig
Required. domain, domainVerified, verificationToken, and optional policy/cache
dev
boolean
Optional. Enable verbose logging. Defaults to NODE_ENV !== production
onManifestGenerated
(manifest) => void
Optional. Called each time a new manifest is generated
children
ReactNode
Required. The component tree that can register contracts
withAgentContract HOC
Wraps any existing component without modifying it. The contract is a completely separate concern — existing component code is untouched.
// HOC — wrap any existing componentimport { withAgentContract } from '@vhyxseal/react'import { defineContract } from '@vhyxseal/core'const contract = defineContract({ id: "checkout-submit-btn", type: "action", intent: "place-order", description: "Submits the cart as a purchase order", requires: [ { field: "user.authenticated", operator: "===", value: true, description: "Must be logged in" }, { field: "cart.hasItems", operator: "===", value: true, description: "Cart must have items" }, { field: "user.hasPaymentMethod", operator: "===", value: true, description: "Payment method required" }, ], requiredPermissions: ["write:orders"], consequence: "Creates order, charges payment method, triggers fulfillment", affects: ["cart", "orders", "payment", "inventory"], reversible: true, reversibleWindow: 300, safetyLevel: "high", requiresConfirmation: true, destructive: false, contractVersion: "1.0.0",})// Wrap any existing component without modifying itexport const CheckoutButton = withAgentContract( ({ onClick, disabled }: { onClick: () => void; disabled?: boolean }) => ( <button onClick={onClick} disabled={disabled}> Place Order </button> ), contract,)
// VhyxSeal components — drop-in replacements with contract supportimport { Button, Input, Form, Nav, Display, Confirmation } from '@vhyxseal/react'import { defineContract } from '@vhyxseal/core'const searchContract = defineContract({ id: "site-search-input", type: "input", intent: "search", description: "Search across all site content", requires: [], requiredPermissions: [], consequence: "Filters visible content to match query", affects: ["search-results"], reversible: true, safetyLevel: "low", requiresConfirmation: false, destructive: false, contractVersion: "1.0.0",})export function SearchBar() { return ( <Input contract={searchContract} placeholder="Search..." onChange={(e) => performSearch(e.target.value)} /> )}
TypeScript Types
// Key TypeScript types exported from @vhyxseal/reactimport type { SealProviderProps, // Props for <SealProvider /> SealContextValue, // Value of SealContext — accessed via hooks ButtonProps, // Props for <Button /> InputProps, // Props for <Input /> FormProps, // Props for <Form /> NavProps, // Props for <Nav /> DisplayProps, // Props for <Display /> ConfirmationProps, // Props for <Confirmation /> ConfirmationState, // State passed to Confirmation render prop CapabilityMap, // Return type of useCapability() AgentActionStatus, // "idle" | "initiated" | "confirmed" | "completed" | "failed" | "cancelled" AgentActionRecord, // Full record with timestamps and metadata UseAgentActionReturn, // Return type of useAgentAction()} from '@vhyxseal/react'
Server Components cannot use hooks — use withAgentContract or component-level contract prop for RSC-compatible components
SealProvider uses React Context — wrap it in a Client Component boundary in App Router
useAgentAction is standalone and does not require SealProvider
All six components (Button, Input, Form, Nav, Display, Confirmation) gracefully degrade outside SealProvider — they render without contract registration and do not throw