Getting Started

VhyxSeal is a semantic contract layer for web UI. This guide walks you from zero to a live manifest in under three minutes.

Requirements

Node.js	≥ 18.0.0
TypeScript	≥ 5.0 (recommended)
React	≥ 18 (for @vhyxseal/react)

Installation

Install only the packages you need. Start with @vhyxseal/core and add adapters as your project grows.

# Core — zero framework dependency
npm install @vhyxseal/core

# React adapter
npm install @vhyxseal/react

# Next.js integration (automatic manifest route)
npm install @vhyxseal/nextjs

# Development tools
npm install --save-dev @vhyxseal/devtools @vhyxseal/cli

Your First Contract

VhyxSeal has four adoption levels. Each adds more precision for agents. Start at Level 0 — add detail incrementally as your needs grow.

Level 0 — Zero Effort

Use standard HTML and ARIA. VhyxSeal infers the contract automatically. Agents get something useful immediately — no extra code required.

Level 0 — Inferred

// Level 0 — no code required
// VhyxSeal infers intent from HTML semantics and ARIA
<button type="submit">Place Order</button>

Level 1 — Single Intent Prop

Add one intent prop. VhyxSeal looks up the intent in its built-in vocabulary and fills in safety level, confirmation requirements, and reversibility automatically.

Level 1 — Intent vocabulary

// Level 1 — one prop unlocks intent vocabulary defaults
<Button intent="place-order">Place Order</Button>

Level 2 — Partial Contract

Override specific fields. Everything you do not specify still comes from the intent vocabulary defaults. The agent gets a complete contract — you only wrote the parts that differ.

Level 2 — Partial overrides

// Level 2 — override specific fields
<Button
  intent="place-order"
  contract={{
    safetyLevel: "high",
    requiresConfirmation: true,
  }}
>
  Place Order
</Button>

Level 3 — Full Contract

Define the complete contract once outside JSX. Frozen, fingerprinted, and auto-versioned. Agents get the full picture — intent, preconditions, consequences, safety, error recovery, and navigation hints.

Level 3 — Full specification

// Level 3 — complete contract, frozen and fingerprinted
import { defineContract } from '@vhyxseal/core'
import { withAgentContract, Button } from '@vhyxseal/react'

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: 'User must be logged in' },
    { field: 'cart.hasItems', operator: '===', value: true, description: 'Cart must have at least one item' },
    { field: 'user.hasPaymentMethod', operator: '===', value: true, description: 'Payment method must be saved' },
  ],
  requiredPermissions: ['write:orders', 'read:payment'],
  consequence: 'charges payment method and triggers fulfillment',
  affects: ['cart', 'orders', 'payment', 'inventory'],
  reversible: true,
  reversibleWindow: 300,
  safetyLevel: 'high',
  requiresConfirmation: true,
  destructive: false,
  contractVersion: '1.0.0',
})

export const CheckoutButton = withAgentContract(Button, contract)

Your First Manifest

Wrap your app in SealProvider. VhyxSeal collects contracts from the component tree and auto-generates /__agent__/manifest.json whenever components mount or update.

app/layout.tsx

// app/layout.tsx
import { SealProvider } from '@vhyxseal/react'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <SealProvider
          config={{
            domain: "your-site.com",
            domainVerified: false,
            verificationToken: "",
          }}
        >
          {children}
        </SealProvider>
      </body>
    </html>
  )
}

The manifest is generated automatically. Here is a minimal example with one registered contract:

/__agent__/manifest.json

// GET /__agent__/manifest.json
{
  "vhyxseal": "1.0.0",
  "schemaUrl": "https://vhyxseal.dev/schema/1.0.0",
  "domain": "your-site.com",
  "domainVerified": false,
  "verificationToken": "",
  "signature": "unsigned",
  "signedAt": "2026-05-27T10:00:00.000Z",
  "fingerprint": "vhyxs_a3f8b2c1",
  "capabilities": [],
  "components": [
    {
      "id": "checkout-submit-btn",
      "type": "action",
      "intent": "place-order",
      "description": "Submits the cart as a purchase order",
      "safetyLevel": "high",
      "requiresConfirmation": true,
      "reversible": true,
      "reversibleWindow": 300,
      "destructive": false,
      "contractVersion": "1.0.0",
      "fingerprint": "vhyxs_d4e5f6a7",
      "verifiedBy": "auto"
    }
  ],
  "relationships": [],
  "agentPolicy": {
    "allowedAgents": ["*"],
    "blockedAgents": [],
    "allowedActions": ["*"]
  },
  "generatedAt": "2026-05-27T10:00:00.000Z",
  "expiresAt": "2026-05-27T11:00:00.000Z"
}

Verify It Works

Use the VhyxSeal CLI to simulate what an AI agent sees when it visits your app. Run this against your local development server.

# Point the CLI simulator at your running app
npx vhyxseal simulate http://localhost:3000

# Expected output:
# ✅ Manifest found at /__agent__/manifest.json
# ✅ Schema version: 1.0.0
# ✅ Components: 12 registered
# ✅ Capabilities: 3 defined
# ⚠️  4 components using inferred contracts — consider upgrading

Components using Level 0 (inferred) contracts show as warnings. Upgrade to Level 1–3 to eliminate them.