Installation

Requirements

• Node.js ≥ 18.0.0 (uses native fetch, crypto, streams)
• npm ≥ 8, yarn ≥ 3, pnpm ≥ 7, or bun ≥ 1.0
• TypeScript 5+ (optional — ships full .d.ts types, no @types/* needed)

Package Managers

# npm
npm install @hyperbridge/forge

# yarn
yarn add @hyperbridge/forge

# pnpm
pnpm add @hyperbridge/forge

# bun
bun add @hyperbridge/forge

Verify Installation

node -e "const forge = require('@hyperbridge/forge'); console.log(forge.VERSION);"
# → 3.2.1

Subpath Imports (Recommended)

Each module is a separate subpath entry. Import only what you need — the rest is never loaded. All subpaths are defined in package.json#exports and work with Node.js, bundlers (Vite, webpack, esbuild, Rollup), and TypeScript.

// ── UI Layer (Browser) ─────────────────────────────────────
// React-like component system, hooks, router, signals, SSR
import { createElement, Component, useState, useEffect, useRef,
         useContext, createContext, useMemo, useCallback, useSignal,
         useComputed, Router, Route, Link, render } from '@hyperbridge/forge/client';

// SVG/Canvas charts — line, bar, pie, scatter, radar, heatmap, etc.
import { ChartForge, ChartDashboard, ChartBrush } from '@hyperbridge/forge/chart';

// Tween, spring, scroll, FLIP, stagger, timeline animations
import { Tween, Spring, Timeline, onScroll, stagger, flip } from '@hyperbridge/forge/animate';

// Form management with async/cross-field validation and file upload
import { Form, Controller, DragDropUpload, RepeatingGroup,
         AccessibleForm, fromSchema } from '@hyperbridge/forge/form';

// ICU MessageFormat, formatters, lazy namespaces, RTL support
import { I18n, RTLManager, NumberFormatterEx } from '@hyperbridge/forge/i18n';

// ── Server Layer (Node.js) ──────────────────────────────────
// HTTP/HTTPS server, routing, middleware, WebSockets, cron
import { Forge, Router, WebSocketServer, CronJob, TaskQueue,
         rateLimit, cors, compress, staticFiles } from '@hyperbridge/forge/server';

// Password, JWT, OAuth2, MagicLink, TOTP, WebAuthn, RBAC, MFA
import { Password, JWT, OAuth2Provider, TOTP, BackupCodes,
         MagicLink, RBAC, SessionManager, WebAuthn, OAuth2PKCE,
         AdaptiveMFA, SAMLProvider, IPAllowList, AuditTrail,
         DeviceManager } from '@hyperbridge/forge/auth';

// PostgreSQL ORM, query builder, migrations, seeding, transactions
import { Pool, PgConnection, Model, QueryBuilder, Migrator,
         SchemaBuilder, ReadReplica, QueryCache, AuditPlugin,
         SeedFactory } from '@hyperbridge/forge/data';

// Multi-channel notifications (toast, WebSocket, email, SMS)
import { NotificationManager, ToastManager, RetryQueue,
         DedupeFilter, NotificationCenter, QuietHours } from '@hyperbridge/forge/notify';

// SMTP client with DKIM, templates, queue, tracking, calendar
import { SMTPClient, EmailTemplate, MailQueue, MailTracker,
         BounceList, CalendarInvite, ABTest } from '@hyperbridge/forge/mail';

// ── Platform Layer ──────────────────────────────────────────
// Service Workers, Cache API, Web Push, Background Sync
import { PWAForge, CacheStrategy, PrecacheManager, PushManager,
         BackgroundSync, OfflineManager, AppShell, BadgeManager,
         UpdateManager, generateVAPIDKeys } from '@hyperbridge/forge/pwa';

// DPR/Retina/4K detection, quality tiers, canvas scaling
import { getDPR, isRetina, is4K, qualityTier, qualityScore,
         snapshot, scaleCanvas, setupWebGLViewport,
         createVariant, createVariants, onDPRChange } from '@hyperbridge/forge/display';

// WebGL2 3D engine — scene graph, geometry, materials, post-fx
import { Scene, WebGLRenderer, PerspectiveCamera, Mesh,
         BoxGeometry, SphereGeometry, StandardMaterial,
         DirectionalLight, PointLight, AnimationMixer,
         ParticleSystem, Raycaster } from '@hyperbridge/forge/3d';

// ── Tooling Layer ───────────────────────────────────────────
// Test runner, matchers, mocking, DOM/HTTP testing, snapshots
import { TestRunner, expect, fn, spyOn, bench } from '@hyperbridge/forge/test';

// CLI framework, prompts, spinners, progress bars, task runner
import { CLI, Command, Prompt, Spinner, ProgressBar,
         TaskRunner, Logger, c } from '@hyperbridge/forge/cli';

// PDF generation with tables, fonts, encryption, QR codes
import { PDFForge, PDFReader, QRCode, Barcode } from '@hyperbridge/forge/pdf';

// Full-text BM25 search, autocomplete, facets, analytics
import { SearchForge, Autocomplete, FacetedSearch,
         SearchAnalytics, Highlighter, RelevanceTuner } from '@hyperbridge/forge/search';

// Zod-compatible schema validation with OpenAPI generation
import { z, Schema } from '@hyperbridge/forge/schema';

CommonJS (require)

// Full bundle (lazy-loaded per module)
const forge = require('@hyperbridge/forge');
console.log(forge.VERSION); // 3.2.1

// Specific modules
const { Password, JWT } = require('@hyperbridge/forge/auth');
const { Pool, Model }   = require('@hyperbridge/forge/data');
const { Forge, Router } = require('@hyperbridge/forge/server');
const { PDFForge }      = require('@hyperbridge/forge/pdf');
const { z }             = require('@hyperbridge/forge/schema');

TypeScript Setup

No extra packages required — all types ship with the package. Recommended tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "strict": true,
    "types": []    // no @types/* needed
  }
}

// Types are inferred automatically
import { z } from '@hyperbridge/forge/schema';

const UserSchema = z.object({
  id:    z.number(),
  email: z.string().email(),
  role:  z.enum(['admin', 'user']),
});

type User = z.infer<typeof UserSchema>;
// → { id: number; email: string; role: 'admin' | 'user' }

ESM in Browsers (CDN)

Client-side modules work in modern browsers via ESM CDN (available at GA on June 25, 2026):

<!-- Via CDN (GA June 2026) -->
<script type="module">
  import { createElement, useState, render }
    from 'https://cdn.hbforge.dev/v3/client/index.js';
  import { Tween }
    from 'https://cdn.hbforge.dev/v3/animate/index.js';
</script>

Quick Start

One working example per module. Each snippet is self-contained — copy, paste, run.

Browser UI — forge/client

import { createElement as h, useState, useEffect, render } from '@hyperbridge/forge/client';

function Counter() {
  const [count, setCount] = useState(0);

  useEffect(() => {
    document.title = `Count: ${count}`;
  }, [count]);

  return h('div', { style: { padding: '20px' } },
    h('h1', null, `Count: ${count}`),
    h('button', { onClick: () => setCount(c => c + 1) }, 'Increment'),
    h('button', { onClick: () => setCount(0), style: { marginLeft: 8 } }, 'Reset')
  );
}

render(h(Counter), document.getElementById('root'));

HTTP Server — forge/server

import { Forge, Router, rateLimit, cors } from '@hyperbridge/forge/server';

const app   = new Forge();
const users = new Router({ prefix: '/users' });

app.use(cors({ origin: '*' }));
app.use(rateLimit({ max: 100, windowMs: 60_000 }));

users.get('/',    async (req, res) => res.json(await db.all()));
users.get('/:id', async (req, res) => res.json(await db.find(req.params.id)));
users.post('/',   async (req, res) => {
  const body = await req.json();
  res.status(201).json(await db.insert(body));
});

app.use(users);
app.listen(3000, () => console.log('Server on :3000'));

Schema Validation — forge/schema

import { z } from '@hyperbridge/forge/schema';

const UserSchema = z.object({
  id:       z.number().int().positive(),
  email:    z.string().email(),
  role:     z.enum(['admin', 'editor', 'viewer']).default('viewer'),
  age:      z.number().min(13).max(120).optional(),
  tags:     z.array(z.string()).max(10).default([]),
  settings: z.record(z.string(), z.unknown()).optional(),
});

// Parse (throws on failure)
const user = UserSchema.parse({ id: 1, email: 'a@b.com' });

// Safe parse (returns result object)
const { success, data, error } = UserSchema.safeParse(rawInput);

// Infer TypeScript type
type User = z.infer<typeof UserSchema>;

// Generate OpenAPI schema
const openApiSchema = UserSchema.toOpenAPI();

Forms — forge/form

import { Form, fromSchema } from '@hyperbridge/forge/form';
import { z } from '@hyperbridge/forge/schema';

const schema = z.object({
  email:    z.string().email('Invalid email'),
  password: z.string().min(8, 'Min 8 characters'),
  name:     z.string().min(1),
});

// Build form from schema — field types inferred automatically
const form = fromSchema(schema, {
  onSubmit: async (data) => {
    const res = await fetch('/api/register', {
      method: 'POST',
      body: JSON.stringify(data),
    });
    return res.json();
  },
});

// Use in UI
form.mount('#register-form');

// Access state programmatically
form.on('change', ({ field, value, errors }) => {
  console.log(field, 'changed to', value, 'errors:', errors);
});

form.on('submit', ({ data }) => console.log('Submitted:', data));
form.on('error',  ({ errors }) => console.warn('Errors:', errors));

Database ORM — forge/data

import { Pool, Model, QueryBuilder } from '@hyperbridge/forge/data';

const pool = new Pool({
  host: 'localhost', database: 'myapp',
  user: 'postgres',  password: 'secret',
  max: 10,
});

// Declare a model
class User extends Model {
  static table    = 'users';
  static pool     = pool;
  static fillable = ['email', 'name', 'role'];
  static hidden   = ['password_hash'];

  static scopes = {
    active: qb => qb.where('active', true),
    admins: qb => qb.where('role', 'admin'),
  };
}

// CRUD
const user = await User.create({ email: 'a@b.com', name: 'Alex' });
const all  = await User.scope('active').orderBy('name').limit(20).get();
const one  = await User.where('email', 'a@b.com').first();
await one.update({ name: 'Alexandra' });
await one.delete();

// Raw query builder
const rows = await new QueryBuilder(pool)
  .table('orders')
  .join('users', 'users.id', 'orders.user_id')
  .where('orders.total', '>', 100)
  .orderBy('orders.created_at', 'desc')
  .select('orders.*', 'users.email')
  .get();

Authentication — forge/auth

import { Password, JWT, TOTP, RBAC } from '@hyperbridge/forge/auth';

// Hash & verify passwords (PBKDF2-SHA-256, 310,000 iterations)
const hash  = await Password.hash('mypassword');
const valid = await Password.verify('mypassword', hash); // true

// JWT — sign, verify, refresh
const secret = process.env.JWT_SECRET;
const token  = await JWT.sign({ userId: 42, role: 'admin' }, secret, { expiresIn: '15m' });
const claims = await JWT.verify(token, secret);
// { userId: 42, role: 'admin', iat: ..., exp: ... }

const refreshed = await JWT.refresh(token, secret, { expiresIn: '15m' });

// TOTP (Google Authenticator compatible)
const { secret: totpSecret, qrDataUrl } = await TOTP.generateSecret('user@app.com', 'MyApp');
const isValid = TOTP.verify('123456', totpSecret);

// RBAC
const rbac = new RBAC({
  roles: {
    admin:  { permissions: ['*'] },
    editor: { permissions: ['posts:read', 'posts:write'] },
    viewer: { permissions: ['posts:read'] },
  },
});

rbac.can('editor', 'posts:write'); // true
rbac.can('viewer', 'posts:write'); // false

Animations — forge/animate

import { Tween, Spring, Timeline, onScroll, stagger } from '@hyperbridge/forge/animate';

// Tween with easing
const tween = new Tween({
  target:   document.querySelector('.card'),
  duration: 400,
  values:   { opacity: [0, 1], translateY: [20, 0] },
  easing:   'easeOutCubic',
});
tween.play();

// Physics spring
const spring = new Spring({
  target:  document.querySelector('.modal'),
  values:  { scale: [0.9, 1], opacity: [0, 1] },
  tension: 280, friction: 20, mass: 1,
});
spring.play();

// Chained timeline
const tl = new Timeline();
tl.add(new Tween({ target: logo, values: { opacity: [0, 1] }, duration: 300 }))
  .add(new Tween({ target: nav,  values: { translateY: [-20, 0] }, duration: 200 }), 150)
  .add(new Tween({ target: hero, values: { scale: [0.95, 1] }, duration: 400 }), 250)
  .play();

// Scroll-driven animation
onScroll(({ progress, element }) => {
  element.style.opacity  = progress;
  element.style.transform = `translateY(${(1 - progress) * 30}px)`;
}, { target: document.querySelector('.section'), threshold: 0.1 });

// Stagger list items
stagger(document.querySelectorAll('.list-item'), { delay: 60, duration: 300, values: { opacity: [0, 1], translateX: [-20, 0] } });

Charts — forge/chart

import { ChartForge } from '@hyperbridge/forge/chart';

const chart = new ChartForge({
  container: '#sales-chart',
  type:      'line',
  width:     800,
  height:    400,
  theme:     'dark',
});

chart.setData({
  labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
  datasets: [
    { label: 'Revenue', data: [42, 58, 39, 71, 63, 88], color: '#6366f1' },
    { label: 'Expenses', data: [30, 35, 28, 45, 50, 60], color: '#f43f5e' },
  ],
});

chart.render();

// Live streaming updates
const ws = new WebSocket('/api/metrics');
ws.onmessage = ({ data }) => {
  chart.push(JSON.parse(data));
};

// Export
const pngBlob = await chart.export('png', { scale: 2 });
const svgStr  = chart.export('svg');

PDF Generation — forge/pdf

import { PDFForge, QRCode } from '@hyperbridge/forge/pdf';

const doc = new PDFForge({ pageSize: 'A4', margin: { top: 40, left: 40, right: 40, bottom: 40 } });

// Page 1 — invoice
doc.setFont('Helvetica-Bold', 18);
doc.text('INVOICE #1042', { x: 40, y: 40 });
doc.setFont('Helvetica', 11);
doc.text('HyperBridge Digital · Chennai, India', { x: 40, y: 65 });
doc.text(`Date: ${new Date().toLocaleDateString()}`,      { x: 420, y: 40 });

// Draw divider
doc.line({ x1: 40, y1: 90, x2: 555, y2: 90, width: 0.5, color: '#cccccc' });

// Table
doc.table({
  x: 40, y: 105,
  columns: [
    { header: 'Item',     width: 250 },
    { header: 'Qty',      width: 60,  align: 'right' },
    { header: 'Rate',     width: 90,  align: 'right' },
    { header: 'Amount',   width: 105, align: 'right' },
  ],
  rows: [
    ['HBForge Enterprise License', '1', '$2,400.00', '$2,400.00'],
    ['Setup & Onboarding',         '3', '  $150.00', '  $450.00'],
  ],
  headerStyle: { fillColor: '#f5f5f5', bold: true },
  cellPadding: 8,
});

// QR code embedded in PDF
const qr = QRCode.generate('https://hbforge.dev', { size: 80 });
doc.image(qr, { x: 450, y: 680 });

const pdfBytes = doc.build();
// Node.js: await fs.writeFile('invoice.pdf', pdfBytes)
// Browser: const url = URL.createObjectURL(new Blob([pdfBytes], { type: 'application/pdf' }))

Full-Text Search — forge/search

import { SearchForge, Autocomplete, FacetedSearch } from '@hyperbridge/forge/search';

// Build an index
const search = new SearchForge({
  fields:  ['title', 'body', 'author'],
  weights: { title: 3, author: 2, body: 1 },
});

search.addDocuments([
  { id: 1, title: 'Getting Started with HBForge', body: 'A complete guide...', author: 'HyperBridge', category: 'tutorial' },
  { id: 2, title: 'forge/auth deep dive',           body: 'JWT, OAuth2, TOTP...', author: 'HyperBridge', category: 'guide' },
  { id: 3, title: 'Building REST APIs',              body: 'forge/server routing...', author: 'HyperBridge', category: 'guide' },
]);

// BM25 search
const results = search.search('jwt auth tokens');
// [{ id: 2, score: 4.82, title: 'forge/auth deep dive', ... }, ...]

// Autocomplete (prefix matching)
const ac = new Autocomplete(search);
const suggestions = ac.suggest('forg'); // ['forge/auth deep dive', 'Getting Started with HBForge', ...]

// Faceted search
const faceted = new FacetedSearch(search, { facets: ['category'] });
const { hits, facets } = faceted.search('guide', { filters: { category: 'guide' } });
// hits = [...], facets = { category: { tutorial: 1, guide: 2 } }

Notifications — forge/notify

import { ToastManager, NotificationManager, NotificationCenter } from '@hyperbridge/forge/notify';

// DOM toasts (browser)
const toast = new ToastManager({ position: 'top-right', maxStack: 5 });

toast.success('File uploaded successfully');
toast.error('Connection failed — retrying…');
toast.warning('Your session expires in 5 minutes');
toast.info('New version available');

// Async toast (shows loading, resolves to success/error)
await toast.promise(
  fetch('/api/upload', { method: 'POST', body: formData }),
  { loading: 'Uploading…', success: 'Done!', error: 'Upload failed' }
);

// Multi-channel notification manager (Node.js)
const nm = new NotificationManager({
  channels: {
    email: { type: 'smtp', host: 'smtp.example.com', from: 'noreply@app.com' },
    sms:   { type: 'twilio', accountSid: '...', authToken: '...', from: '+1555...' },
  },
});

await nm.send({
  to:       'user@example.com',
  channels: ['email', 'sms'],
  subject:  'Password changed',
  body:     'Your password was changed. If this wasn\'t you, contact support.',
});

// Notification center with persistence
const center = new NotificationCenter({ maxHistory: 100 });
center.add({ id: '1', title: 'New comment', body: 'Alex replied to your post', read: false });
const unread = center.getUnread();

Email — forge/mail

import { SMTPClient, EmailTemplate, MailQueue } from '@hyperbridge/forge/mail';

// SMTP client with DKIM signing
const smtp = new SMTPClient({
  host:     'smtp.postmarkapp.com',
  port:     587,
  secure:   false,
  auth:     { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS },
  dkim:     { domain: 'hyperbridge.digital', keySelector: 'default', privateKey: DKIM_KEY },
  pool:     true,  // connection pooling
  maxConns: 5,
});

// HTML templates with variable substitution
const tmpl = new EmailTemplate({
  subject:  'Welcome to {{appName}}, {{firstName}}!',
  html:     '
Hi {{firstName}},
Your account is ready.
',
  text:     'Hi {{firstName}}, your account is ready.',
});

await smtp.send({
  to:   'user@example.com',
  from: 'welcome@hyperbridge.digital',
  ...tmpl.render({ appName: 'HBForge', firstName: 'Alex' }),
});

// Queue for bulk sending with rate limiting
const queue = new MailQueue(smtp, { rateLimit: 50, rateLimitInterval: 1000 });

for (const subscriber of subscribers) {
  queue.enqueue({ to: subscriber.email, ...newsletter.render(subscriber) });
}

await queue.flush(); // sends all queued emails respecting rate limits

Internationalization — forge/i18n

import { I18n, NumberFormatterEx } from '@hyperbridge/forge/i18n';

const i18n = new I18n({
  locale:   'en',
  fallback: 'en',
  messages: {
    en: {
      'greeting':            'Hello, {name}!',
      'unread':              'You have {count, plural, one {# message} other {# messages}}',
      'appointment':         'Your appointment is on {date, date, long} at {time, time, short}',
      'balance':             'Balance: {amount, number, ::currency/USD}',
      'progress':            '{pct, number, ::percent}',
    },
    ta: {
      'greeting':  'வணக்கம், {name}!',
      'unread':    '{count} செய்திகள் உள்ளன',
    },
  },
});

i18n.t('greeting', { name: 'Alex' });
// en → "Hello, Alex!"

i18n.t('unread', { count: 3 });
// en → "You have 3 messages"

i18n.t('appointment', { date: new Date(), time: new Date() });
// en → "Your appointment is on April 14, 2026 at 9:00 AM"

// Locale negotiation
I18n.negotiate(['ta-IN', 'en-US'], ['en', 'ta', 'fr']); // → 'ta'

// Extended number formatting
const fmt = new NumberFormatterEx('en-US');
fmt.currency(2400, 'USD');   // "$2,400.00"
fmt.compact(81954);          // "82K"
fmt.percent(0.876);          // "87.6%"
fmt.ordinal(3);              // "3rd"

CLI Tools — forge/cli

import { CLI, Command, Prompt, Spinner, TaskRunner, c } from '@hyperbridge/forge/cli';

const cli = new CLI({ name: 'myapp', version: '1.0.0' });

cli.add(new Command({
  name:    'deploy',
  desc:    'Deploy to production',
  options: [
    { flag: '--env, -e', desc: 'Environment', default: 'staging' },
    { flag: '--dry-run', desc: 'Simulate without deploying', boolean: true },
  ],
  action: async ({ env, dryRun }) => {
    // Interactive confirmation
    const confirm = await Prompt.confirm(`Deploy to ${c.red(env)}?`);
    if (!confirm) return;

    const spinner = new Spinner('Building…').start();

    const runner = new TaskRunner([
      { name: 'Build',    run: () => build() },
      { name: 'Test',     run: () => test() },
      { name: 'Upload',   run: () => upload(), skip: dryRun },
      { name: 'Migrate',  run: () => migrate(), skip: dryRun },
    ]);

    runner.on('task:done',   ({ name }) => console.log(c.green('✔') + ' ' + name));
    runner.on('task:failed', ({ name, error }) => console.error(c.red('✖') + ' ' + name, error));

    await runner.run();
    spinner.succeed('Deployed to ' + c.cyan(env));
  },
}));

cli.run(process.argv.slice(2));

Testing — forge/test

import { TestRunner, expect, fn, spyOn, bench } from '@hyperbridge/forge/test';

const runner = new TestRunner({ timeout: 5000, bail: false });

runner.describe('User service', () => {
  runner.it('creates a user', async () => {
    const user = await createUser({ email: 'a@b.com', name: 'Alex' });
    expect(user.id).toBeGreaterThan(0);
    expect(user.email).toBe('a@b.com');
    expect(user.createdAt).toBeInstanceOf(Date);
  });

  runner.it('hashes password', async () => {
    const mockHash = fn().mockResolvedValue('hashed_pw');
    const user = await createUser({ email: 'b@c.com', password: 'secret' }, { hashFn: mockHash });
    expect(mockHash).toHaveBeenCalledWith('secret');
    expect(user.passwordHash).toBe('hashed_pw');
  });

  runner.it('throws on duplicate email', async () => {
    await createUser({ email: 'dup@b.com' });
    await expect(createUser({ email: 'dup@b.com' })).rejects.toThrow('Email already exists');
  });
});

// Benchmark
runner.describe('Performance', () => {
  bench('schema parse', () => UserSchema.parse(rawUser), { iterations: 10_000 });
});

await runner.run();

Display & Device Detection — forge/display

import {
  getDPR, isRetina, is4K, qualityTier, qualityScore, snapshot,
  scaleCanvas, setupWebGLViewport, createVariants, onDPRChange,
} from '@hyperbridge/forge/display';

// Device capabilities
console.log(getDPR());        // 2 (on a Retina display)
console.log(isRetina());      // true  (DPR >= 2)
console.log(is4K());          // false (viewport < 3840)
console.log(qualityScore());  // 72  (0–100)
console.log(qualityTier());   // 'high' ('low'|'medium'|'high'|'ultra')

// Full capability snapshot
const caps = snapshot();
// { dpr: 2, tier: 'high', score: 72, gpu: 'high', width: 1920,
//   height: 1080, hdr: false, saveData: false, webgl2: true, ... }

// Pixel-perfect canvas scaling
const canvas = document.getElementById('my-canvas');
const ctx = scaleCanvas(canvas, 800, 600);
// canvas is now 1600×1200 px (Retina), CSS size is 800×600

// WebGL DPR-aware viewport
const gl = canvas.getContext('webgl2');
setupWebGLViewport(gl, canvas);

// Adaptive asset variants
const { src, srcset } = createVariants('/hero', {
  low:    { suffix: '@1x', ext: 'webp' },
  medium: { suffix: '@1.5x', ext: 'webp' },
  high:   { suffix: '@2x', ext: 'webp' },
  ultra:  { suffix: '@3x', ext: 'avif' },
});
// On a Retina high-tier device: src='/hero@2x.webp'

// React to DPR changes (e.g. drag to external monitor)
onDPRChange(({ from, to }) => {
  console.log(`DPR changed ${from} → ${to}`);
  scaleCanvas(canvas, 800, 600);  // rescale
});

Progressive Web App — forge/pwa

// service-worker.js  (register with navigator.serviceWorker.register('/sw.js'))
import { PWAForge, CacheStrategy, PrecacheManager,
         PushManager, BackgroundSync } from '@hyperbridge/forge/pwa';

const pwa = new PWAForge({ version: '1.0.0', debug: false });

// Precache app shell at install time
const precache = new PrecacheManager(pwa);
precache.add([
  '/', '/app.js', '/app.css', '/offline.html',
  '/icons/icon-192.png', '/icons/icon-512.png',
]);

// Route-level caching strategies
pwa.route('/api/*',   CacheStrategy.NetworkFirst({ timeout: 3000, cacheName: 'api-v1' }));
pwa.route('/images/*', CacheStrategy.CacheFirst({ cacheName: 'images-v1', maxAge: 86400 }));
pwa.route('/*',       CacheStrategy.StaleWhileRevalidate({ cacheName: 'pages-v1' }));

// Web Push
const push = new PushManager(pwa, { vapidPublicKey: VAPID_KEY });
push.onMessage(payload => {
  self.registration.showNotification(payload.title, { body: payload.body, icon: '/icon.png' });
});

// Background Sync — replay failed requests when back online
const sync = new BackgroundSync('api-queue');
sync.register(failedFetchRequest);  // queues the request
// → replayed automatically when connection restores

pwa.install();

forge/client

Fiber-based concurrent UI framework with VDOM, 146+ APIs, priority lanes, hooks, signals, atoms, routing, CSS-in-JS, SSR, and more. Zero dependencies. 12,276 lines.

Core Rendering

import { h, render, Fragment } from '@hyperbridge/forge/client';

function App() {
  return h(Fragment, null,
    h('h1', null, 'Hello HBForge'),
    h('p', null, 'Fiber-based concurrent rendering')
  );
}

render(h(App), document.getElementById('root'));

Hooks

import { h, useState, useEffect, useRef } from '@hyperbridge/forge/client';

function Timer() {
  const [seconds, setSeconds] = useState(0);
  const intervalRef = useRef(null);

  useEffect(() => {
    intervalRef.current = setInterval(() => {
      setSeconds(s => s + 1);
    }, 1000);
    return () => clearInterval(intervalRef.current);
  }, []);

  return h('p', null, `Elapsed: ${seconds}s`);
}

Signals & Reactive State

Signals provide fine-grained reactivity outside the VDOM. Unlike hooks, which schedule a component re-render, a signal update surgically patches the DOM node it is bound to. This makes signals ideal for high-frequency updates like counters, progress bars, and real-time data feeds.

import { h, signal, computed, useSignal, bindSignalToText } from '@hyperbridge/forge/client';

const count = signal(0);
const doubled = computed(() => count.value * 2);

function Display() {
  const val = useSignal(doubled);
  return h('p', null, `Doubled: ${val}`);
}

// Direct DOM binding — bypasses VDOM entirely
const el = document.getElementById('counter');
bindSignalToText(count, el);
count.value = 5; // el.textContent instantly becomes "5"

Atoms & Global State

import { h, atom, derived, useAtom } from '@hyperbridge/forge/client';

const todosAtom = atom([]);
const countAtom = derived([todosAtom], ([todos]) => todos.length);

function TodoList() {
  const [todos, setTodos] = useAtom(todosAtom);
  const [count] = useAtom(countAtom);

  const add = () => setTodos(t => [...t, { text: 'New', done: false }]);

  return h('div', null,
    h('p', null, `${count} items`),
    h('button', { onClick: add }, 'Add Todo'),
    ...todos.map(t => h('p', null, t.text))
  );
}

Async Data & Mutations

import { h, useAsync, useMutation, invalidateCache } from '@hyperbridge/forge/client';

function UserProfile({ userId }) {
  const { data: user, loading, error } = useAsync(
    () => fetch(`/api/users/${userId}`).then(r => r.json()),
    [userId]
  );
  const { mutate: updateName, loading: saving } = useMutation(
    (name) => fetch(`/api/users/${userId}`, {
      method: 'PATCH', body: JSON.stringify({ name }),
    })
  );

  if (loading) return h('p', null, 'Loading...');
  if (error) return h('p', null, `Error: ${error.message}`);

  return h('div', null,
    h('h2', null, user.name),
    h('button', {
      onClick: () => updateName('New Name').then(() => invalidateCache()),
      disabled: saving,
    }, saving ? 'Saving...' : 'Rename')
  );
}

Router & Navigation

import { h, render, Router, Route, Link, useRouter } from '@hyperbridge/forge/client';

function Home() {
  return h('div', null,
    h('h1', null, 'Home'),
    h(Link, { to: '/users/42' }, 'View User')
  );
}

function UserPage() {
  const { params, back } = useRouter();
  return h('div', null,
    h('h1', null, `User #${params.id}`),
    h('button', { onClick: back }, 'Go Back')
  );
}

const router = new Router([
  new Route('/', Home),
  new Route('/users/:id', UserPage),
]);

// Navigation guards
router.beforeEach((to, from) => {
  if (to.path.startsWith('/admin') && !isLoggedIn()) return false;
});

render(h(router), document.getElementById('root'));

Context & Selectors

import { h, createContext, useContextSelector } from '@hyperbridge/forge/client';

const AppContext = createContext({ user: null, theme: 'dark', lang: 'en' });

// Only re-renders when user.name changes — not on theme/lang changes
function UserName() {
  const name = useContextSelector(AppContext, ctx => ctx.user?.name);
  return h('span', null, name || 'Guest');
}

Forms & Validation

CSS-in-JS

import { h, css, styled, keyframes, globalStyles } from '@hyperbridge/forge/client';

globalStyles(`body { margin: 0; font-family: system-ui; }`);

const fadeIn = keyframes(`
  from { opacity: 0; transform: translateY(10px); }
  to   { opacity: 1; transform: translateY(0); }
`);

const cardClass = css(`
  padding: 24px;
  border-radius: 12px;
  background: #1a1a2e;
  animation: ${fadeIn} 0.3s ease-out;
`);

const Button = styled('button', `
  padding: 10px 20px;
  border: none;
  border-radius: 6px;
  background: #6366f1;
  color: white;
  cursor: pointer;
  &:hover { background: #4f46e5; }
`);

function Card() {
  return h('div', { className: cardClass },
    h(Button, { onClick: () => alert('Clicked') }, 'Click Me')
  );
}

Animation Hooks

import { h, useSpring, Animated } from '@hyperbridge/forge/client';

function BouncyCard() {
  const [style, api] = useSpring({ scale: 1, opacity: 1 });

  return h(Animated.div, {
    style,
    onMouseEnter: () => api.start({ scale: 1.05 }),
    onMouseLeave: () => api.start({ scale: 1 }),
  }, 'Hover me!');
}

Transitions

Batching & Concurrent

use() Hook

import { h, use, Suspense } from '@hyperbridge/forge/client';

const dataPromise = fetch('/api/data').then(r => r.json());

function DataView() {
  const data = use(dataPromise); // suspends until resolved
  return h('pre', null, JSON.stringify(data, null, 2));
}

function App() {
  return h(Suspense, { fallback: h('p', null, 'Loading...') },
    h(DataView)
  );
}

SSR & Server Components

Error Boundaries

import { h, createRecoverableErrorBoundary } from '@hyperbridge/forge/client';

const SafeZone = createRecoverableErrorBoundary({
  maxRetries: 3,
  fallback: (error, retry) => h('div', null,
    h('p', null, `Error: ${error.message}`),
    h('button', { onClick: retry }, 'Retry')
  ),
  onError: (error) => console.error('Boundary caught:', error),
});

function App() {
  return h(SafeZone, null, h(RiskyComponent));
}

Events & EventBus

Internationalization (i18n)

Head & Meta Management

Theme & Accessibility

import { h, createTheme, ThemeProvider, useTheme } from '@hyperbridge/forge/client';

const lightTheme = createTheme({
  bg: '#ffffff', text: '#1a202c', primary: '#6366f1',
});
const darkTheme = createTheme({
  bg: '#0a0a0f', text: '#f1f5f9', primary: '#818cf8',
});

function ThemeToggle() {
  const { theme, setTheme } = useTheme();
  return h('button', {
    onClick: () => setTheme(theme === lightTheme ? darkTheme : lightTheme),
  }, 'Toggle Theme');
}

function App() {
  return h(ThemeProvider, { theme: darkTheme }, h(ThemeToggle));
}

Fetch Client

import { createFetchClient } from '@hyperbridge/forge/client';

const api = createFetchClient({
  baseURL: 'https://api.example.com',
  timeout: 5000,
  retry: 3,
  interceptors: {
    request: (config) => {
      config.headers.Authorization = `Bearer ${getToken()}`;
      return config;
    },
    response: (response) => {
      if (response.status === 401) refreshToken();
      return response;
    },
  },
});

const users = await api.get('/users');
await api.post('/users', { name: 'Alice' });

Multi-Tab Sync & Web Vitals

import { h, useSyncedState, reportWebVitals } from '@hyperbridge/forge/client';

// Sync cart state across tabs
function CartIcon() {
  const [cartCount, setCartCount] = useSyncedState('cart-count', 0);
  // Updates in one tab instantly reflect in all other tabs
  return h('span', null, `Cart (${cartCount})`);
}

// Report metrics to analytics
reportWebVitals((metric) => {
  console.log(metric.name, metric.value); // "LCP" 1234
  navigator.sendBeacon('/analytics', JSON.stringify(metric));
});

Utility Hooks

import { h, useLocalStorage, useMediaQuery, useOnClickOutside, useRef }
  from '@hyperbridge/forge/client';

function Dropdown() {
  const ref = useRef(null);
  const [open, setOpen] = useLocalStorage('dropdown-open', false);
  const isMobile = useMediaQuery('(max-width: 768px)');

  useOnClickOutside(ref, () => setOpen(false));

  return h('div', { ref },
    h('button', { onClick: () => setOpen(o => !o) },
      isMobile ? 'Menu' : 'Options'
    ),
    open && h('ul', { className: 'dropdown' },
      h('li', null, 'Profile'),
      h('li', null, 'Settings'),
      h('li', null, 'Logout')
    )
  );
}

Advanced APIs

DevTools

Form Actions

import { h, useFormState, useFormAction, ProgressiveForm } from '@hyperbridge/forge/client';

function CreatePost() {
  const [state, formAction] = useFormState('/api/posts', { error: null, success: false });
  const { pending } = useFormAction(formAction);

  return h(ProgressiveForm, { action: formAction },
    h('input', { name: 'title', placeholder: 'Post title', required: true }),
    h('textarea', { name: 'body', placeholder: 'Write your post...' }),
    h('button', { type: 'submit', disabled: pending }, pending ? 'Saving...' : 'Publish'),
    state.error && h('p', { class: 'error' }, state.error),
    state.success && h('p', { class: 'success' }, 'Post created!')
  );
}

Hydration Mismatch Detection

import { h, hydrateWithMismatchDetection, configureHydration } from '@hyperbridge/forge/client';

configureHydration({
  mode: 'strict',                     // 'strict' | 'warn' | 'silent'
  onMismatch(path, expected, actual) {
    reportToMonitoring({ path, expected, actual });
  }
});

function App() {
  return h('div', null,
    h('h1', null, 'My App'),
    h('span', { suppressHydrationWarning: true }, new Date().toLocaleTimeString())
  );
}

hydrateWithMismatchDetection(h(App), document.getElementById('root'));

Enhanced Server Components

import { h, createServerAction, ServerBoundary, registerClientComponent } from '@hyperbridge/forge/client';

// Server action — runs on the server, callable from client
const saveUser = createServerAction(async (formData) => {
  const user = await db.users.update(formData.id, {
    name: formData.name,
    email: formData.email
  });
  return { success: true, user };
});

// Client island inside a server-rendered page
const LikeButton = registerClientComponent(function LikeButton({ postId }) {
  const [liked, setLiked] = useState(false);
  return h('button', { onClick: () => setLiked(!liked) }, liked ? 'Liked' : 'Like');
});

function UserProfile({ userId }) {
  return h(ServerBoundary, { fallback: h('p', null, 'Loading profile...') },
    h('div', { class: 'profile' },
      h('h2', null, 'User Profile'),
      h(LikeButton, { postId: userId })
    )
  );
}

Auto-Memoization

import { h, render, enableAutoMemo, disableAutoMemo, AutoMemoProvider } from '@hyperbridge/forge/client';

// Enable globally — all components are auto-memoized
enableAutoMemo();

function ExpensiveList({ items }) {
  return h('ul', null, items.map(item =>
    h('li', { key: item.id }, item.name)
  ));
}

function App() {
  return h('div', null,
    h(ExpensiveList, { items: data }),            // auto-memoized
    h(AutoMemoProvider, { enabled: false },
      h(AlwaysRerenderWidget, null)               // opts out of auto-memo
    )
  );
}

render(h(App), document.getElementById('root'));

Enhanced useOptimistic

import { h, useOptimisticAction, useOptimisticMutation } from '@hyperbridge/forge/client';

function TodoList() {
  const [todos, addTodo] = useOptimisticMutation('/api/todos', {
    add(current, newTodo) {
      return [...current, { ...newTodo, id: 'temp-' + Date.now(), pending: true }];
    },
    rollback(current, failedTodo) {
      return current.filter(t => t.id !== failedTodo.id);
    }
  });

  const [likeState, likeAction] = useOptimisticAction(
    '/api/like',
    (prev, postId) => ({ ...prev, [postId]: (prev[postId] || 0) + 1 })
  );

  return h('div', null,
    h('button', { onClick: () => addTodo({ title: 'New task' }) }, 'Add Todo'),
    h('ul', null, todos.map(todo =>
      h('li', { key: todo.id, class: todo.pending ? 'pending' : '' }, todo.title)
    ))
  );
}

Test Utilities

import { h } from '@hyperbridge/forge/client';
import { renderForTest, screen, fireEvent, waitForUpdate, act } from '@hyperbridge/forge/client/test';

function Counter() {
  const [count, setCount] = useState(0);
  return h('div', null,
    h('span', { 'data-testid': 'count' }, String(count)),
    h('button', { onClick: () => setCount(c => c + 1) }, 'Increment')
  );
}

// Test
const { cleanup } = renderForTest(h(Counter));

expect(screen.getByTestId('count').textContent).toBe('0');

await act(async () => {
  fireEvent.click(screen.getByText('Increment'));
  await waitForUpdate();
});

expect(screen.getByTestId('count').textContent).toBe('1');
cleanup();

Hot Module Replacement

import { h, render, preserveStateOnHMR } from '@hyperbridge/forge/client';
import { createHMRClient } from '@hyperbridge/forge/client/hmr';

const hmr = createHMRClient({ port: 3001 });

const App = preserveStateOnHMR('App', function App() {
  const [count, setCount] = useState(0);
  return h('div', null,
    h('p', null, `Count: ${count}`),
    h('button', { onClick: () => setCount(c => c + 1) }, '+1')
  );
});

render(h(App), document.getElementById('root'));

// Accept hot updates and re-render
if (hmr.hot) {
  hmr.hot.accept('./App', (updatedModule) => {
    render(h(updatedModule.default), document.getElementById('root'));
  });

  hmr.hot.dispose(() => {
    console.log('Cleaning up before hot reload...');
  });
}

forge/server

Full-featured HTTP framework — radix-trie router, 20+ built-in middleware, WebSocket (RFC 6455), GraphQL engine, cron scheduler, task queue, JWT auth, circuit breaker, LRU cache, HTTP client, PubSub, plugin system, DI container, OpenTelemetry tracing, Prometheus metrics, HTTP/2, cluster mode, and more. 120+ APIs, zero dependencies, 11,177 lines.

1. Core

import { Forge } from '@hyperbridge/forge/server';

const app = new Forge();
app.set('env', 'production');

app.onShutdown(async () => {
  await db.close();
  console.log('Cleanup complete');
});

app.get('/api/status', (req, res) => {
  res.json({ status: 'ok', uptime: process.uptime() });
});

app.listen(3000, () => console.log('Running'));

// Cluster mode — spawns one worker per CPU core
Forge.cluster(() => {
  const app = new Forge();
  app.get('/', (req, res) => res.json({ pid: process.pid }));
  app.listen(3000);
}, { workers: 4 });

2. Router

const app = new Forge();

// Route params
app.get('/users/:id', (req, res) => {
  res.json({ userId: req.params.id });
});

// Wildcard catch-all
app.get('/files/*', (req, res) => {
  res.json({ path: req.params['*'] });
});

// Route groups with shared auth middleware
app.group('/api/v1', (g) => {
  g.use(authMiddleware);
  g.get('/users', listUsers);
  g.post('/users', createUser);
  g.group('/admin', (admin) => {
    admin.get('/stats', getStats);
  });
});

app.listen(3000);

3. Middleware (21+)

import { Forge, bodyParser, cors, helmet, logger, rateLimit,
         compression, serveStatic, timeout } from '@hyperbridge/forge/server';

const app = new Forge();

// Middleware stack
app.use(logger({ level: 'info' }));
app.use(cors({ origin: 'https://myapp.com', credentials: true }));
app.use(helmet({ csp: "default-src 'self'" }));
app.use(compression({ threshold: 512 }));
app.use(rateLimit({ windowMs: 60000, max: 100 }));
app.use(timeout(30000));
app.use(bodyParser.json({ limit: '2mb' }));
app.use(serveStatic('./public', { maxAge: 86400 }));

app.get('/api/data', (req, res) => res.json({ ok: true }));
app.listen(3000);

rateLimit Options

4. WebSocket

import { Forge, WebSocketServer } from '@hyperbridge/forge/server';

const app = new Forge();

app.ws((wss) => {
  wss.on('connection', (client, req) => {
    console.log(`Client ${client.id} connected`);

    wss.join(client, 'lobby');

    client.on('message', (data) => {
      // Broadcast to room
      wss.to('lobby').emit({ type: 'chat', ...data });
    });

    client.on('close', () => {
      wss.leave(client, 'lobby');
    });
  });
});

app.listen(3000);

5. GraphQL Engine

import { Forge, DataLoader } from '@hyperbridge/forge/server';

const app = new Forge();

const schema = `
  type User { id: ID!, name: String!, email: String }
  type Query {
    user(id: ID!): User
    users: [User!]!
  }
  type Mutation {
    createUser(name: String!, email: String!): User!
  }
`;

const userLoader = new DataLoader(async (ids) => {
  const users = await db.findByIds(ids);
  return ids.map(id => users.find(u => u.id === id) || null);
});

app.graphql(schema, {
  Query: {
    user: (_, { id }) => userLoader.load(id),
    users: () => db.allUsers(),
  },
  Mutation: {
    createUser: (_, { name, email }) => db.createUser({ name, email }),
  },
});

app.listen(3000); // GraphQL at POST /graphql

6. CronScheduler

import { Forge } from '@hyperbridge/forge/server';

const app = new Forge();

// Run every day at 2:00 AM
app.cron('cleanup', '0 2 * * *', async () => {
  await db.cleanup();
  console.log('Daily maintenance complete');
});

// Run every 5 minutes
app.cron('sync', '*/5 * * * *', async () => {
  await syncExternalData();
});

app.listen(3000);

7. TaskQueue

import { TaskQueue } from '@hyperbridge/forge/server';

const queue = new TaskQueue({ concurrency: 10 });
queue.persist('./data/jobs.json').restore();

queue.register('sendEmail', async (data) => {
  await emailService.send(data.to, data.subject, data.body);
});

queue.on('failed', (task, err) => {
  console.error(`Task ${task.id} failed: ${err.message}`);
});

await queue.add('sendEmail', {
  to: 'user@example.com',
  subject: 'Welcome',
  body: 'Hello!'
}, { priority: 10, maxRetries: 5 });

8. JWT

import { Forge, JWT } from '@hyperbridge/forge/server';

const jwt = new JWT(process.env.JWT_SECRET, { expiresIn: 7200 });
const app = new Forge();

app.post('/auth/login', async (req, res) => {
  const user = await authenticate(req.body);
  const token = jwt.sign({ id: user.id, role: user.role });
  res.json({ token });
});

// Protected route
app.get('/api/profile', jwt.middleware(), (req, res) => {
  res.json({ user: req.user });
});

app.listen(3000);

9. Validator & Schema

import { Forge, v } from '@hyperbridge/forge/server';

const app = new Forge();

const createUserSchema = v.object({
  name: v.string().min(2).max(100),
  email: v.string().email(),
  age: v.number().int().min(18).optional(),
  role: v.enum(['admin', 'user']).default('user'),
});

app.post('/users', createUserSchema.bodyParser(), (req, res) => {
  // req.body is validated and transformed
  res.status(201).json(req.body);
});

app.listen(3000);

10. CircuitBreaker

import { CircuitBreaker } from '@hyperbridge/forge/server';

const breaker = new CircuitBreaker(
  (url) => fetch(url).then(r => r.json()),
  { threshold: 3, timeout: 5000, resetTimeout: 15000 }
);

breaker.on('open', () => console.warn('Circuit opened!'));

try {
  const data = await breaker.fire('https://api.example.com/data');
} catch (err) {
  // Fallback logic when circuit is open
}

11. LRU Cache

import { LRUCache } from '@hyperbridge/forge/server';

const cache = new LRUCache({ max: 500, ttl: 60000 });

cache.set('user:42', { id: 42, name: 'Alice' });
const user = cache.get('user:42'); // { id: 42, name: 'Alice' }
console.log(cache.size); // 1

12. PubSub

import { PubSub } from '@hyperbridge/forge/server';

const pubsub = new PubSub();

// Wildcard pattern
pubsub.subscribe('order.*', (data, topic) => {
  console.log(`Event ${topic}:`, data);
});

pubsub.publish('order.created', { id: 1, total: 99.99 }); // matches
pubsub.publish('order.shipped', { id: 1 });                // matches

13. HTTP Client

import { httpClient } from '@hyperbridge/forge/server';

const { data } = await httpClient.get('https://api.example.com/users', {
  headers: { Authorization: 'Bearer ...' },
  timeout: 5000,
});

await httpClient.post('https://api.example.com/users', {
  name: 'Alice', email: 'alice@example.com'
});

14. Plugin System

import { Forge } from '@hyperbridge/forge/server';

const authPlugin = {
  name: 'auth',
  async register(app, opts) {
    app.decorate('authenticate', (req) => { /* ... */ });
    app.addHook('onRequest', async (req, res) => {
      req.user = await app.authenticate(req);
    });
    app.get('/auth/me', (req, res) => res.json(req.user));
  }
};

const app = new Forge();
await app.register(authPlugin, { secret: 'my-secret' });
app.listen(3000);

15. Dependency Injection

import { createContainer, Forge } from '@hyperbridge/forge/server';

const container = createContainer();
container.register('logger', () => new Logger(), { lifetime: 'singleton' });
container.register('userService', (logger) => new UserService(logger));
container.register('requestCtx', () => new RequestContext(), { lifetime: 'scoped' });

const app = new Forge();
app.use(container.middleware());

app.get('/users', (req, res) => {
  const svc = req.container.resolve('userService');
  res.json(svc.findAll());
});

app.listen(3000);

16. OpenTelemetry Tracing

import { createTracer, Forge } from '@hyperbridge/forge/server';

const tracer = createTracer('my-service');
const app = new Forge();
app.use(tracer.middleware());

app.get('/api/data', async (req, res) => {
  const result = await tracer.trace('fetchData', async (span) => {
    span.setAttribute('db.system', 'postgres');
    const data = await db.query('SELECT * FROM items');
    span.addEvent('query-complete', { rowCount: data.length });
    return data;
  });
  res.json(result);
});

app.listen(3000);

17. Prometheus Metrics

import { createMetrics, Forge } from '@hyperbridge/forge/server';

const metrics = createMetrics({ prefix: 'myapp_' });
const app = new Forge();

app.use(metrics.middleware());
app.use(metrics.endpoint('/metrics'));

const orderCounter = metrics.counter({
  name: 'orders_total',
  help: 'Total orders placed',
});

app.post('/orders', (req, res) => {
  orderCounter.inc({ status: 'created' });
  res.status(201).json({ ok: true });
});

app.listen(3000); // Prometheus scrapes GET /metrics

18. Webhook Verification

import { Forge, verifyWebhook } from '@hyperbridge/forge/server';

const app = new Forge();

app.post('/webhooks/stripe',
  verifyWebhook({
    secret: process.env.STRIPE_SECRET,
    header: 'stripe-signature',
    tolerance: 300,
    parse: (header) => {
      const parts = {};
      header.split(',').forEach(p => {
        const [k, val] = p.split('=');
        parts[k] = val;
      });
      return { timestamp: parts.t, signature: parts.v1 };
    },
  }),
  (req, res) => {
    console.log('Verified webhook:', req.body);
    res.json({ received: true });
  }
);

app.listen(3000);

19. Enhanced Sessions

import { Forge, sessionEnhanced, createRedisSessionStore }
  from '@hyperbridge/forge/server';

const app = new Forge();

app.use(sessionEnhanced({
  secret: 'session-secret',
  maxAge: 86400,
  store: createRedisSessionStore({ host: '127.0.0.1', port: 6379 }),
  rotateInterval: 3600,
}));

app.post('/login', async (req, res) => {
  req.session.userId = user.id;
  await req.session.regenerate(); // new session ID, same data
  res.json({ ok: true });
});

app.get('/dashboard', (req, res) => {
  const error = req.flash('error');
  res.json({ userId: req.session.userId, flashError: error });
});

20. Backpressure

import { Forge, backpressure } from '@hyperbridge/forge/server';

const bp = backpressure({
  maxConcurrent: 50,
  maxQueue: 200,
  queueTimeout: 5000,
  strategy: 'priority',
  getPriority: (req) => req.headers['x-priority'] === 'high' ? 10 : 0,
});

const app = new Forge();
app.use(bp);

app.get('/stats', (req, res) => res.json(bp.stats()));
app.listen(3000);

21. Config Management

import { createConfig } from '@hyperbridge/forge/server';

const config = createConfig({
  port: { type: 'number', default: 3000, env: 'PORT' },
  db: {
    host: { type: 'string', default: 'localhost', env: 'DB_HOST' },
    port: { type: 'number', default: 5432, env: 'DB_PORT' },
    name: { type: 'string', required: true, env: 'DB_NAME' },
  },
  logLevel: { type: 'string', enum: ['debug','info','warn','error'], default: 'info' },
});

config.load({ envFile: '.env', jsonFile: 'config.json' });

console.log(config.get('db.host'));  // 'localhost' or DB_HOST value
console.log(config.isProduction);    // true if NODE_ENV=production

22. Streaming JSON

import { Forge } from '@hyperbridge/forge/server';

const app = new Forge();

// NDJSON streaming from async generator
app.get('/stream', async (req, res) => {
  async function* generate() {
    for (let i = 0; i < 100; i++) {
      yield { id: i, timestamp: Date.now() };
    }
  }
  await res.streamJSON(generate());
});

// Server-Sent Events with typed events
app.get('/events', (req, res) => {
  const sse = res.sseStream({ retry: 5000, keepAlive: 15000 });

  const interval = setInterval(() => {
    sse.event('tick', { time: new Date().toISOString() });
  }, 1000);

  req.on('close', () => {
    clearInterval(interval);
    sse.close();
  });
});

app.listen(3000);

23. Request/Response Interceptors

import { Forge } from '@hyperbridge/forge/server';

const app = new Forge();

// Log every request before parsing
app.addHook('preParsing', async (req, res) => {
  console.log(`Incoming: ${req.method} ${req.url}`);
});

// Transform all JSON responses
app.addHook('preSerialization', async (req, res, data) => {
  return { ...data, timestamp: Date.now(), requestId: req.id };
});

app.get('/api/users', (req, res) => {
  res.json({ users: [] }); // { users: [], timestamp: ..., requestId: ... }
});

app.listen(3000);

24. HTTP/2

import { Forge, createHttp2Server } from '@hyperbridge/forge/server';
import fs from 'fs';

const app = new Forge();

app.get('/', (req, res) => {
  // Push CSS and JS before the client requests them
  if (res.push) {
    res.push('/styles.css', { file: './public/styles.css', contentType: 'text/css' });
    res.push('/app.js', { file: './public/app.js', contentType: 'application/javascript' });
  }
  res.html('<html><head><link rel="stylesheet" href="/styles.css"></head>...</html>');
});

const server = createHttp2Server(app, {
  key: fs.readFileSync('key.pem'),
  cert: fs.readFileSync('cert.pem'),
});
server.listen(3000);

25. OpenAPI

import { Forge, generateOpenAPI } from '@hyperbridge/forge/server';

const app = new Forge();
app.get('/users/:id', (req, res) => { /* ... */ });
app.post('/users', (req, res) => { /* ... */ });

const spec = app.openapi({
  title: 'My API',
  version: '2.0.0',
  description: 'User management API',
});

app.get('/docs/openapi.json', (req, res) => res.json(spec));
app.listen(3000);

26. HTTPS & ACME

import { Forge, createHttpsServer } from '@hyperbridge/forge/server';

const app = new Forge();
app.get('/', (req, res) => res.json({ secure: true }));

// Auto-obtain TLS cert via Let's Encrypt
const server = await createHttpsServer(app, {
  domain: 'api.example.com',
  email: 'admin@example.com',
  certDir: './.forge-certs',
  port: 443,
});

27. Cluster

import { Forge } from '@hyperbridge/forge/server';

Forge.cluster(() => {
  const app = new Forge();

  app.get('/', (req, res) => {
    res.json({ worker: process.pid });
  });

  app.onShutdown(async () => {
    await db.close();
  });

  app.listen(3000);
}, { workers: 8 });

Response Helpers

Request Properties

Type-Safe RPC

import { Forge, createRPCRouter, procedure, mergeRouters } from '@hyperbridge/forge/server';

const userRouter = createRPCRouter({
  getUser: procedure
    .input({ id: 'string' })
    .query(async ({ input, ctx }) => {
      return ctx.db.users.findById(input.id);
    }),

  updateUser: procedure
    .input({ id: 'string', name: 'string', email: 'string?' })
    .mutation(async ({ input, ctx }) => {
      return ctx.db.users.update(input.id, input);
    })
});

const postRouter = createRPCRouter({
  list: procedure.query(async ({ ctx }) => ctx.db.posts.findAll())
});

const appRouter = mergeRouters({ user: userRouter, post: postRouter });

const app = new Forge();
app.use('/rpc', appRouter);   // POST /rpc/user.getUser, /rpc/post.list, etc.
app.listen(3000);

AI/LLM Streaming

import { Forge } from '@hyperbridge/forge/server';

const app = new Forge();

// Stream LLM tokens — OpenAI-compatible SSE
app.post('/api/chat', async (req, res) => {
  const { messages } = req.body;
  const llmStream = await callLLM({ messages, stream: true });

  res.streamTokens(async function* () {
    for await (const chunk of llmStream) {
      yield { content: chunk.text, role: 'assistant' };
    }
  });
});

// Stream arbitrary data chunks
app.get('/api/feed', (req, res) => {
  res.streamChunks(async function* () {
    yield { event: 'status', data: { connected: true } };
    for await (const update of liveUpdates()) {
      yield { event: 'update', data: update, id: update.id };
    }
  }, { retry: 3000 });
});

app.listen(3000);

Content Negotiation

import { Forge, negotiate } from '@hyperbridge/forge/server';

const app = new Forge();
app.use(negotiate());

app.get('/api/users/:id', async (req, res) => {
  const user = await db.users.findById(req.params.id);

  res.vary('Accept');
  res.format({
    'application/json': () => res.json(user),
    'text/html':        () => res.html(`<h1>${user.name}</h1>`),
    'text/csv':         () => res.text(`${user.id},${user.name},${user.email}`),
    default:            () => res.status(406).json({ error: 'Not Acceptable' })
  });
});

app.listen(3000);

Streaming Uploads

import { Forge, streamUpload } from '@hyperbridge/forge/server';
import { createWriteStream } from 'fs';

const app = new Forge();

app.post('/api/upload', streamUpload({
  maxSize: '500mb',
  allowedTypes: ['video/*', 'image/*'],
  onProgress(bytes, total) { console.log(`${Math.round(bytes/total*100)}%`); }
}), async (req, res) => {
  // req.file is a readable stream — pipe directly to storage
  const dest = createWriteStream(`./uploads/${req.file.filename}`);
  await req.file.stream.pipe(dest);

  res.status(201).json({
    filename: req.file.filename,
    size: req.file.size,
    type: req.file.mimetype
  });
});

app.listen(3000);

Test Client

import { Forge } from '@hyperbridge/forge/server';

const app = new Forge();
app.get('/api/health', (req, res) => res.json({ status: 'ok' }));
app.post('/api/users', (req, res) => {
  res.status(201).json({ id: 1, name: req.body.name });
});

// Test without starting a server
const res = await app.inject()
  .get('/api/health')
  .expect(200)
  .expect('content-type', /json/)
  .end();

console.assert(res.body.status === 'ok');

// Test POST with body
const created = await app.inject()
  .post('/api/users')
  .set('Authorization', 'Bearer test-token')
  .send({ name: 'Alice' })
  .expect(201)
  .end();

console.assert(created.body.name === 'Alice');

Dev Mode

import { Forge, devLogger } from '@hyperbridge/forge/server';

const app = new Forge();

if (process.env.NODE_ENV !== 'production') {
  app.enableDevMode({
    errorOverlay: true,          // rich HTML error pages with stack traces
    watchDirs: ['./src'],        // auto-restart on file changes
    openBrowser: true            // open browser on first listen
  });

  app.use(devLogger({
    filter: (req) => !req.path.startsWith('/health'),
    colorize: true,
    showBody: true               // log request/response bodies
  }));
}

app.get('/', (req, res) => res.json({ hello: 'world' }));
app.listen(3000);
// DevLogger output: GET / 200 1.2ms 27B

OpenAPI 3.1

import { Forge, generateOpenAPI31, swaggerUI } from '@hyperbridge/forge/server';

const app = new Forge();

app.get('/api/users', { summary: 'List users', tags: ['Users'] }, (req, res) => {
  res.json([{ id: 1, name: 'Alice' }]);
});

app.post('/api/users', {
  summary: 'Create user',
  tags: ['Users'],
  body: { name: 'string', email: 'string' },
  response: { 201: { id: 'number', name: 'string' } }
}, (req, res) => {
  res.status(201).json({ id: 2, name: req.body.name });
});

// Mount spec + UI
app.swagger({
  path: '/docs',
  info: { title: 'My API', version: '2.0.0' }
});

// Or manually:
// const spec = generateOpenAPI31(app, { info: { title: 'My API', version: '2.0.0' } });
// app.get('/openapi.json', (req, res) => res.json(spec));
// app.use('/docs', swaggerUI({ specUrl: '/openapi.json' }));

app.listen(3000);
// Swagger UI at http://localhost:3000/docs

Enhanced Errors

import { Forge, EnhancedForgeError, notFound, badRequest, unauthorized } from '@hyperbridge/forge/server';

const app = new Forge();

// Typed error handlers — catch specific error codes
app.onError('VALIDATION', (err, req, res) => {
  res.status(400).json({
    code: err.code,
    message: err.message,
    fields: err.details.fields     // per-field validation errors
  });
});

app.onError('NOT_FOUND', (err, req, res) => {
  res.status(404).json({ code: err.code, message: err.message });
});

// Throw enhanced errors from routes
app.get('/api/users/:id', async (req, res) => {
  const user = await db.users.findById(req.params.id);
  if (!user) throw notFound(`User ${req.params.id} not found`);

  res.json(user);
});

app.post('/api/users', async (req, res) => {
  if (!req.body.email) {
    throw badRequest('Validation failed', {
      fields: { email: 'Email is required' }
    });
  }

  // EnhancedForgeError with cause chain
  try {
    const user = await db.users.create(req.body);
    res.status(201).json(user);
  } catch (dbErr) {
    throw new EnhancedForgeError('DB_ERROR', 'Failed to create user', 500, { cause: dbErr });
  }
});

app.listen(3000);

forge/auth

Complete authentication & authorization — Password, JWT, OAuth2, TOTP, WebAuthn, MagicLink, RBAC, Sessions, MFA, SAML, and audit trails. Zero external dependencies.

Password

PBKDF2-SHA-256 with 310,000 iterations (OWASP 2023 minimum). No bcrypt dependency required.

JWT

OAuth2Provider

Built-in presets for Google, GitHub, Microsoft, GitLab, Discord, Facebook, LinkedIn. Pass 'custom' for any OAuth2-compliant provider.

TOTP (2FA)

BackupCodes

RBAC

MagicLink

SessionManager

Example: Password + JWT Auth Middleware

import { Password, JWT } from '@hyperbridge/forge/auth';

// Registration
router.post('/auth/register', async (req, res) => {
  const { email, password } = req.body;
  const hash = await Password.hash(password);
  const user = await db.users.create({ email, passwordHash: hash });
  res.status(201).json({ id: user.id, email: user.email });
});

// Login
router.post('/auth/login', async (req, res) => {
  const { email, password } = req.body;
  const user = await db.users.findByEmail(email);
  if (!user) return res.status(401).json({ error: 'Invalid credentials' });

  const valid = await Password.verify(password, user.passwordHash);
  if (!valid) return res.status(401).json({ error: 'Invalid credentials' });

  // Rehash if iterations are outdated
  if (Password.needsRehash(user.passwordHash)) {
    const newHash = await Password.hash(password);
    await db.users.update(user.id, { passwordHash: newHash });
  }

  const accessToken  = JWT.sign({ sub: user.id, role: user.role }, process.env.JWT_SECRET, { expiresIn: '15m' });
  const refreshToken = JWT.sign({ sub: user.id, type: 'refresh' }, process.env.JWT_SECRET, { expiresIn: '30d' });
  res.json({ accessToken, refreshToken });
});

// Auth middleware
function requireAuth(req, res, next) {
  const token = req.headers.authorization?.replace('Bearer ', '');
  if (!token) return res.status(401).json({ error: 'Missing token' });
  try {
    req.user = JWT.verify(token, process.env.JWT_SECRET);
    next();
  } catch {
    res.status(401).json({ error: 'Invalid or expired token' });
  }
}

Example: TOTP Two-Factor Authentication

import { TOTP, BackupCodes, JWT } from '@hyperbridge/forge/auth';

// Step 1: Generate TOTP secret for user
router.post('/auth/2fa/setup', requireAuth, async (req, res) => {
  const { secret, qrDataUrl, otpauthUrl } = await TOTP.generateSecret(
    req.user.email, 'MyApp'
  );
  // Save secret temporarily (not activated until verified)
  await db.users.update(req.user.sub, { totpSecretPending: secret });
  res.json({ qrDataUrl, otpauthUrl }); // show qrDataUrl as <img>
});

// Step 2: Verify setup (user scans QR and enters first code)
router.post('/auth/2fa/verify-setup', requireAuth, async (req, res) => {
  const { code } = req.body;
  const user = await db.users.find(req.user.sub);
  const valid = TOTP.verify(code, user.totpSecretPending);
  if (!valid) return res.status(400).json({ error: 'Invalid code' });

  // Generate backup codes
  const { codes, hashes } = BackupCodes.generate(10);
  await db.users.update(user.id, {
    totpSecret:        user.totpSecretPending,
    totpSecretPending: null,
    backupCodeHashes:  hashes,
    twoFactorEnabled:  true,
  });
  res.json({ backupCodes: codes }); // show once, never again
});

// Step 3: Login flow
router.post('/auth/login/2fa', async (req, res) => {
  const { tempToken, code } = req.body;
  const { sub } = JWT.verify(tempToken, process.env.JWT_SECRET);
  const user = await db.users.find(sub);

  const validTotp   = TOTP.verify(code, user.totpSecret);
  const backupIndex = BackupCodes.verify(code, user.backupCodeHashes);

  if (!validTotp && backupIndex === -1) {
    return res.status(401).json({ error: 'Invalid 2FA code' });
  }

  // Consume backup code if used
  if (backupIndex !== -1) {
    const newHashes = BackupCodes.consume(backupIndex, user.backupCodeHashes);
    await db.users.update(user.id, { backupCodeHashes: newHashes });
  }

  const accessToken = JWT.sign({ sub: user.id, role: user.role }, process.env.JWT_SECRET, { expiresIn: '15m' });
  res.json({ accessToken });
});

Example: RBAC Middleware

import { RBAC, JWT } from '@hyperbridge/forge/auth';

const rbac = new RBAC({
  roles: {
    admin:  { permissions: ['*'] },
    editor: { permissions: ['posts:read', 'posts:write', 'media:upload'], inherits: ['viewer'] },
    viewer: { permissions: ['posts:read', 'comments:read'] },
  },
});

// Middleware factory
function can(permission) {
  return (req, res, next) => {
    if (!req.user?.role) return res.status(401).json({ error: 'Unauthenticated' });
    if (!rbac.can(req.user.role, permission)) {
      return res.status(403).json({ error: `Permission denied: ${permission}` });
    }
    next();
  };
}

// Apply to routes
router.get('/posts',         can('posts:read'),  listPosts);
router.post('/posts',        can('posts:write'), createPost);
router.delete('/posts/:id',  can('posts:*'),     deletePost);   // wildcard
router.post('/admin/users',  can('*'),           adminAction);  // admin only

Example: OAuth2 PKCE Flow

import { OAuth2PKCE } from '@hyperbridge/forge/auth';

const pkce = new OAuth2PKCE({
  clientId:    process.env.GITHUB_CLIENT_ID,
  redirectUri: 'http://localhost:3000/auth/github/callback',
  provider:    'github',
  scopes:      ['user:email', 'read:user'],
});

// 1. Start login — generates code_verifier + code_challenge
router.get('/auth/github', (req, res) => {
  const { url, state, codeVerifier } = pkce.startFlow();
  req.session.pkceState        = state;
  req.session.pkceCodeVerifier = codeVerifier;
  res.redirect(url);
});

// 2. Handle callback — exchanges code + verifier for token
router.get('/auth/github/callback', async (req, res) => {
  const { code, state } = req.query;
  if (state !== req.session.pkceState) return res.status(400).send('State mismatch');

  const token = await pkce.exchangeCode(code, req.session.pkceCodeVerifier);
  const user  = await pkce.getUserInfo(token);
  // { id, email, name, avatar }

  const jwt = JWT.sign({ sub: user.id, email: user.email }, process.env.JWT_SECRET, { expiresIn: '7d' });
  res.redirect(`/dashboard?token=${jwt}`);
});

forge/data

PostgreSQL ORM — connection pooling, fluent query builder, full ORM with relations & hooks, schema builder, migrations, read replicas, query caching, seeding, and audit logging.

Pool Configuration

QueryBuilder Methods

Model Static Methods

Model Instance Methods

Example: Full ORM Setup

import { Pool, Model } from '@hyperbridge/forge/data';

const pool = new Pool({
  host:     process.env.DB_HOST,
  database: process.env.DB_NAME,
  user:     process.env.DB_USER,
  password: process.env.DB_PASS,
  ssl:      true,
  max:      20,
});

class User extends Model {
  static table    = 'users';
  static pool     = pool;
  static fillable = ['email', 'name', 'role'];
  static hidden   = ['passwordHash'];           // excluded from toJSON()
  static casts    = { createdAt: 'date', settings: 'json' };

  // Named scopes
  static scopes = {
    active:  qb => qb.where('active', true),
    admins:  qb => qb.where('role', 'admin'),
    recent:  qb => qb.orderBy('created_at', 'desc').limit(20),
  };

  // Lifecycle hooks
  static beforeCreate = async (data) => ({
    ...data,
    createdAt: new Date(),
  });

  static afterCreate = async (user) => {
    await EmailQueue.enqueue({ to: user.email, template: 'welcome' });
  };

  // Relations
  static relations = {
    posts:    { type: 'hasMany',    model: () => Post,    foreignKey: 'user_id' },
    profile:  { type: 'hasOne',     model: () => Profile, foreignKey: 'user_id' },
    roles:    { type: 'belongsToMany', model: () => Role, pivot: 'user_roles' },
  };
}

// CRUD
const user  = await User.create({ email: 'a@b.com', name: 'Alex', role: 'editor' });
const found = await User.findOrFail(user.id);
await found.update({ name: 'Alexandra' });

// Scoped query
const admins = await User.scope('active').scope('admins').orderBy('name').get();

// Eager-load relations
const posts = await user.load('posts');

// Pagination
const page = await User.scope('active').paginate(1, 20);
// { data: User[], total: 154, page: 1, perPage: 20, lastPage: 8 }

Example: Migrations

import { Pool, Migrator, SchemaBuilder } from '@hyperbridge/forge/data';

const migrator = new Migrator(pool, {
  directory: './db/migrations',
  tableName: 'schema_migrations',
});

// Create a migration file
await migrator.create('create_posts_table');
// → ./db/migrations/20260414120000_create_posts_table.js

// Migration file content (generated template):
export const up = async (sb) => {
  sb.createTable('posts', (t) => {
    t.serial('id').primaryKey();
    t.string('title', 255).notNull();
    t.text('body').notNull();
    t.string('status', 20).defaultValue('draft');
    t.integer('user_id').references('users.id').onDelete('CASCADE');
    t.boolean('featured').defaultValue(false);
    t.jsonb('metadata').defaultValue('{}');
    t.timestamps(); // created_at, updated_at
    t.index(['status', 'user_id']);
  });
};

export const down = async (sb) => {
  sb.dropTable('posts');
};

// Run migrations
await migrator.latest();        // run pending
await migrator.rollback();      // revert last batch
await migrator.rollback(3);     // revert last 3 batches
const status = await migrator.status(); // list all with run/pending

Example: Transactions with Savepoints

import { Pool } from '@hyperbridge/forge/data';

// Simple transaction
await pool.transaction(async (trx) => {
  const user  = await trx.table('users').insert({ email: 'x@y.com' }).returning('*').first();
  await trx.table('profiles').insert({ userId: user.id, bio: 'Hello' });
  // auto-commit on return, auto-rollback on throw
});

// Nested savepoints
await pool.transaction(async (trx) => {
  await trx.table('orders').insert({ userId: 1, total: 500 });

  await trx.savepoint('sp1', async () => {
    await trx.table('inventory').update({ stock: 0 }, { where: { sku: 'ABC' } });
    // Only this savepoint rolls back on failure, outer transaction continues
  });

  await trx.table('audit_log').insert({ action: 'order_placed', userId: 1 });
});

Example: Read Replica + Query Cache

import { Pool, ReadReplica, QueryCache } from '@hyperbridge/forge/data';

// Primary (writes) + replicas (reads)
const primary  = new Pool({ host: 'primary.db.internal', /* ... */ });
const replica1 = new Pool({ host: 'replica1.db.internal', /* ... */ });
const replica2 = new Pool({ host: 'replica2.db.internal', /* ... */ });

const replica = new ReadReplica(primary, [replica1, replica2], {
  strategy: 'round-robin',  // or 'random', 'least-connections'
});

// Writes go to primary, reads auto-routed to replicas
await replica.query('INSERT INTO events VALUES ($1)', [data]);   // → primary
const rows = await replica.query('SELECT * FROM events');         // → replica

// Query result cache (Redis or in-memory)
const cache = new QueryCache(replica, {
  store:   'memory',    // or { type: 'redis', url: process.env.REDIS_URL }
  default: 60_000,      // 60s default TTL
});

const hot = await cache.query(
  'SELECT * FROM featured_products ORDER BY rank LIMIT 20',
  [],
  { ttl: 300_000 }  // 5-minute TTL for this query
);

forge/form

Headless form management — async & cross-field validation, schema binding, file upload, field arrays, multi-step forms, conditional fields, and accessibility helpers.

Form Constructor Options

Form State

Form Methods

Example: Registration Form with Schema

import { Form, fromSchema } from '@hyperbridge/forge/form';
import { z } from '@hyperbridge/forge/schema';

const RegisterSchema = z.object({
  email:           z.string().email('Invalid email'),
  password:        z.string().min(8, 'At least 8 characters'),
  confirmPassword: z.string(),
  name:            z.string().min(1, 'Name is required'),
  role:            z.enum(['admin', 'editor', 'viewer']).default('viewer'),
  acceptTerms:     z.literal(true, { errorMap: () => ({ message: 'You must accept the terms' }) }),
}).refine(d => d.password === d.confirmPassword, {
  message: 'Passwords do not match',
  path:    ['confirmPassword'],
});

// fromSchema infers initial values and wires validation automatically
const form = fromSchema(RegisterSchema, {
  validateOn: 'blur',
  onSubmit:   async (data) => {
    const res = await fetch('/api/register', { method: 'POST', body: JSON.stringify(data) });
    if (!res.ok) {
      const { errors } = await res.json();
      form.setErrors(errors); // map server errors back to fields
    }
  },
});

// Wire to HTML (vanilla JS example)
document.querySelector('#register-form').addEventListener('submit', async (e) => {
  e.preventDefault();
  form.touchAll(); // show all validation errors
  await form.submit();
});

document.querySelectorAll('input').forEach(input => {
  const props = form.getFieldProps(input.name);
  input.value = props.value;
  input.addEventListener('input', (e) => props.onChange(e.target.value));
  input.addEventListener('blur', props.onBlur);
});

// React to state changes
form.on('change', ({ path, value }) => {
  const errEl = document.querySelector(`[data-error="${path}"]`);
  if (errEl) errEl.textContent = form.errors[path] ?? '';
});

Example: Multi-Step Form

import { Form } from '@hyperbridge/forge/form';

const wizard = new Form({
  steps: [
    {
      name: 'personal',
      fields: ['firstName', 'lastName', 'email'],
      validate: (v) => {
        const e = {};
        if (!v.firstName) e.firstName = 'Required';
        if (!v.email?.includes('@')) e.email = 'Valid email required';
        return e;
      },
    },
    {
      name: 'company',
      fields: ['company', 'role', 'teamSize'],
    },
    {
      name: 'billing',
      fields: ['plan', 'cardholderName'],
      condition: (v) => v.teamSize > 1, // skip if solo
    },
  ],
  initialValues: {
    firstName: '', lastName: '', email: '',
    company: '', role: '', teamSize: 1,
    plan: 'starter', cardholderName: '',
  },
  onSubmit: async (data) => {
    await fetch('/api/onboarding', { method: 'POST', body: JSON.stringify(data) });
  },
});

// Navigation
await wizard.nextStep();       // validate current step, advance if valid
await wizard.prevStep();       // go back (no validation)
wizard.currentStep.name;       // 'personal' | 'company' | 'billing'
wizard.progress;               // 0.0 – 1.0 (for progress bar)
wizard.isLastStep;             // true on final step

Example: DragDropUpload

import { DragDropUpload } from '@hyperbridge/forge/form';

const uploader = new DragDropUpload('#drop-zone', {
  accept:      ['image/jpeg', 'image/png', 'application/pdf'],
  maxSize:     10 * 1024 * 1024,   // 10MB per file
  maxFiles:    5,
  multiple:    true,
  preview:     true,               // show image thumbnails

  onSelect:  (files) => console.log('Selected:', files.map(f => f.name)),
  onError:   (err)   => toast.error(err.message),

  upload: async (file, { onProgress }) => {
    const fd = new FormData();
    fd.append('file', file);
    return fetch('/api/upload', {
      method:    'POST',
      body:      fd,
      onUploadProgress: ({ loaded, total }) => onProgress(loaded / total),
    }).then(r => r.json());
  },
});

// Programmatic control
uploader.open();                   // open file picker
uploader.clear();                  // remove all files
const urls = await uploader.uploadAll(); // upload all selected files

Example: RepeatingGroup (Field Arrays)

import { Form, RepeatingGroup } from '@hyperbridge/forge/form';

const form = new Form({
  initialValues: {
    recipients: [{ name: '', email: '', role: 'viewer' }],
  },
});

const recipients = new RepeatingGroup(form, 'recipients', {
  template:  () => ({ name: '', email: '', role: 'viewer' }),
  min:       1,
  max:       10,
  validate: (item) => {
    const errors = {};
    if (!item.email?.includes('@')) errors.email = 'Valid email required';
    return errors;
  },
});

// API
recipients.add();               // append new row from template
recipients.remove(2);           // remove row at index 2
recipients.move(0, 2);          // reorder (drag-drop support)
recipients.swap(1, 3);          // swap two rows
recipients.items;               // current array value
recipients.errors;              // per-item error objects

forge/animate

Zero-dependency animation engine with spring physics, tweens, gestures, scroll-linked timelines, FLIP layout animations, SVG morphing, text effects, motion paths, and 50+ transition presets. 80+ APIs. 7,528 lines.

Tween & Core Animation

import { Tween, animate } from '@hyperbridge/forge/animate';

// Full Tween API
const tween = new Tween({
  duration: 800,
  easing: 'easeOutCubic',
  values: { opacity: [0, 1], x: [100, 0], y: [-50, 0] },
  onUpdate: (v) => {
    el.style.opacity = v.opacity;
    el.style.transform = `translate(${v.x}px, ${v.y}px)`;
  },
});
tween.play();
tween.pause();
tween.reverse();
tween.seek(0.5); // jump to 50%

// Shorthand
animate('.box', { opacity: 1, transform: 'translateY(0)' }, { duration: 600 });

Spring Physics

import { Spring, springPresets, springChain } from '@hyperbridge/forge/animate';

const spring = new Spring({
  ...springPresets.wobbly,
  values: { scale: [0.8, 1], opacity: [0, 1] },
  onUpdate: (v) => {
    el.style.transform = `scale(${v.scale})`;
    el.style.opacity = v.opacity;
  },
});
spring.play();

// Chain springs: fade in, then scale up, then slide right
springChain([
  { values: { opacity: [0, 1] }, ...springPresets.gentle },
  { values: { scale: [0.9, 1] }, ...springPresets.stiff },
  { values: { x: [0, 100] }, ...springPresets.wobbly },
], (v) => { /* onUpdate for each step */ });

Spring Configuration

Easing Functions

Timeline & Sequencing

import { Timeline, Tween, sequence } from '@hyperbridge/forge/animate';

const tl = new Timeline();
tl.add(new Tween({ duration: 300, values: { opacity: [0, 1] }, onUpdate: ... }));
tl.add(new Tween({ duration: 500, values: { x: [0, 200] }, onUpdate: ... }), 200); // overlap by 100ms
tl.play();

// Or use sequence for strict ordering
sequence([
  animate('.title', { opacity: 1 }, { duration: 400 }),
  animate('.subtitle', { opacity: 1 }, { duration: 300 }),
  animate('.cta', { opacity: 1, transform: 'scale(1)' }, { duration: 500 }),
]);

Stagger Animations

import { stagger, staggerGrid } from '@hyperbridge/forge/animate';

// Simple stagger
stagger(document.querySelectorAll('.card'), {
  duration: 500,
  delay: 80,
  easing: 'easeOutQuad',
  values: { opacity: [0, 1], y: [30, 0] },
});

// Grid stagger — animate from center outward
staggerGrid(document.querySelectorAll('.grid-item'), {
  columns: 4,
  from: 'center',
  duration: 400,
  delay: 60,
  values: { scale: [0, 1], opacity: [0, 1] },
});

Scroll Animations

import { scrollTimeline, parallax, inView } from '@hyperbridge/forge/animate';

// Scroll-linked animation (GSAP ScrollTrigger-style)
scrollTimeline('.progress-bar', {
  trigger: '.section',
  start: 'top center',
  end: 'bottom center',
  animation: { scaleX: [0, 1] },
});

// Parallax layers
parallax('.bg-layer', { speed: 0.3 });
parallax('.fg-layer', { speed: 0.8 });

scrollTimeline Options

Viewport & Reveal

Gesture System

import { gesture, draggable, inertia } from '@hyperbridge/forge/animate';

// Full gesture handling
gesture(card, {
  onDrag: ({ x, y, velocity }) => {
    card.style.transform = `translate(${x}px, ${y}px)`;
  },
  onDragEnd: ({ velocity }) => {
    inertia(card, { velocity, friction: 0.95 });
  },
});

// Simple draggable
draggable('.handle', { axis: 'x', bounds: '.container' });

Layout Animations (FLIP)

import { flip, layoutTransition } from '@hyperbridge/forge/animate';

// Manual FLIP for a layout change
flip(listContainer, () => {
  // DOM mutation happens here
  listContainer.prepend(listContainer.lastChild);
}, { duration: 400, easing: 'easeOutCubic' });

// Auto FLIP — watches for any DOM changes
const cleanup = layoutTransition('.grid', {
  duration: 350,
  easing: 'easeInOutQuad',
});

SVG & Path Animations

Text Animations

import { splitText, typewriter, scrambleText, stagger } from '@hyperbridge/forge/animate';

// Split and stagger characters
const { chars } = splitText('.heading');
stagger(chars, {
  duration: 400, delay: 30,
  values: { opacity: [0, 1], y: [20, 0] },
});

// Typewriter effect
typewriter('.terminal-text', { speed: 50, cursor: true });

// Scramble reveal
scrambleText('.secret-code', { duration: 1500, chars: '!@#$%^&*' });

Presence & Transitions

Motion Values & Reactivity

Performance Utilities

Reduced Motion & Accessibility

import { animate, respectMotionPreference, prefersReducedMotion } from '@hyperbridge/forge/animate';

// Automatically respects user preferences
const safeAnimate = respectMotionPreference(animate);
safeAnimate('.hero', { opacity: 1, y: 0 }, { duration: 600 });
// If reduced motion: instant jump, no animation

// Manual check
if (!prefersReducedMotion()) {
  animate('.fancy-element', { rotate: 360 }, { duration: 2000 });
}

forge/chart

SVG chart library with line, bar, pie, scatter, radar, heatmap, treemap, gauge, and funnel charts.

Quick Start

Every chart follows the same pattern: pick a type, point to a container, pass data, and call render(). The data shape is consistent across all chart types — labels for categories, series for datasets.

Chart Constructor Parameters

Instance Methods

Supported Charts

Example: Line Chart

import { Chart } from '@hyperbridge/forge/chart';

const chart = new Chart({
  type: 'line',
  container: document.getElementById('chart'),
  data: {
    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
    series: [
      { name: 'Sales', data: [120, 150, 200, 180, 220] },
      { name: 'Profit', data: [30, 45, 60, 50, 80] },
    ],
  },
  options: {
    title: 'Monthly Performance',
    responsive: true,
    animation: true,
  },
});

chart.render();

Example: Pie Chart

import { Chart } from '@hyperbridge/forge/chart';

const chart = new Chart({
  type: 'pie',
  container: document.getElementById('chart'),
  data: {
    labels: ['Desktop', 'Mobile', 'Tablet'],
    series: [
      { name: 'Traffic', data: [45, 35, 20] },
    ],
  },
  options: {
    title: 'Traffic by Device',
    colors: ['#6366f1', '#22d3ee', '#f97316'],
  },
});

chart.render();

Example: Real-Time Dashboard

import { Chart } from '@hyperbridge/forge/chart';

// Live-updating gauge
const gauge = new Chart({
  type: 'gauge',
  container: document.getElementById('cpu-gauge'),
  data: { value: 0, min: 0, max: 100, label: 'CPU %' },
  options: {
    colors: ['#22c55e', '#eab308', '#ef4444'], // green → yellow → red
    thresholds: [60, 85],
    animation: { duration: 300 },
  },
});
gauge.render();

// Update every second from WebSocket
ws.on('metrics', (data) => {
  gauge.update({ value: data.cpuPercent });
});

Example: Multi-Series Line + Overlays

import { ChartForge } from '@hyperbridge/forge/chart';

const chart = new ChartForge({
  container: '#revenue-chart',
  type:      'line',
  width:     900,
  height:    420,
  theme:     'dark',
});

chart.setData({
  labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug'],
  datasets: [
    {
      label:  'Revenue',
      data:   [42000, 58000, 39000, 71000, 63000, 88000, 74000, 95000],
      color:  '#6366f1',
      fill:   true,      // area fill
      smooth: true,      // cubic bezier curves
    },
    {
      label: 'Target',
      data:  [50000, 55000, 60000, 65000, 70000, 75000, 80000, 85000],
      color: '#22d3ee',
      dash:  [6, 3],    // dashed line
    },
  ],
});

// Statistical overlays
chart.addOverlay('sma',        { period: 3, color: '#f59e0b' });      // simple moving average
chart.addOverlay('trendline',  { color: '#ef4444', lineWidth: 1.5 }); // least-squares trendline
chart.addOverlay('bollinger',  { period: 5, stdDev: 2, color: 'rgba(99,102,241,0.2)' });

// Annotations
chart.annotate({ x: 'Apr', label: 'Campaign launch', color: '#22c55e' });
chart.annotate({ x: 'Jun', y: 88000, label: 'Record month', type: 'point' });

chart.render();

// Zoom into a date range
chart.zoom({ from: 'Mar', to: 'Jul' });

Example: Real-Time Streaming Chart

import { ChartForge } from '@hyperbridge/forge/chart';

const liveChart = new ChartForge({
  container: '#metrics-chart',
  type:      'line',
  width:     800,
  height:    300,
  streaming: {
    maxPoints:    60,      // rolling 60-point window
    updateInterval: 1000, // redraw every 1000ms
  },
});

liveChart.setData({
  datasets: [
    { label: 'CPU %',    data: [], color: '#6366f1' },
    { label: 'Memory %', data: [], color: '#22d3ee' },
  ],
});
liveChart.render();

// Push new data points from WebSocket
const ws = new WebSocket('/api/metrics');
ws.onmessage = ({ data }) => {
  const { cpu, memory, ts } = JSON.parse(data);
  liveChart.push([
    { label: ts, value: cpu },
    { label: ts, value: memory },
  ]);
};

Example: ChartDashboard — Multiple Charts

import { ChartDashboard, ChartForge } from '@hyperbridge/forge/chart';

// Manage multiple charts as a synchronized grid
const dashboard = new ChartDashboard('#analytics-dashboard', {
  columns: 2,
  gap:     16,
  theme:   'dark',
});

dashboard.add('revenue',  new ChartForge({ type: 'bar',    /* ... */ }));
dashboard.add('devices',  new ChartForge({ type: 'donut',  /* ... */ }));
dashboard.add('sessions', new ChartForge({ type: 'area',   /* ... */ }));
dashboard.add('funnel',   new ChartForge({ type: 'funnel', /* ... */ }));

dashboard.render();  // renders all charts, coordinates resize events

// Update all from one API response
const { data } = await fetch('/api/analytics').then(r => r.json());
dashboard.updateAll(data);

Example: Candlestick + Volume

import { ChartForge } from '@hyperbridge/forge/chart';

const ohlcv = new ChartForge({
  container: '#price-chart',
  type:      'candlestick',
  width:     1000,
  height:    500,
});

ohlcv.setData({
  datasets: [{
    label: 'BTC/USD',
    data: [
      // { t, o, h, l, c, v }
      { t: '2026-04-01', o: 71000, h: 73500, l: 70200, c: 72800, v: 1240000 },
      { t: '2026-04-02', o: 72800, h: 74100, l: 71500, c: 71900, v: 980000  },
      { t: '2026-04-03', o: 71900, h: 75000, l: 71800, c: 74500, v: 2100000 },
    ],
  }],
});

ohlcv.addOverlay('volume',  { position: 'bottom', height: 100 }); // volume bars below
ohlcv.addOverlay('rsi',     { period: 14, overbought: 70, oversold: 30 });
ohlcv.render();

Example: Export

// SVG string — resolution-independent, embed in HTML or PDF
const svg = chart.toSVG();
document.getElementById('preview').innerHTML = svg;

// PNG blob — for download or attaching to emails/PDFs
const blob = await chart.toImage('png', { scale: 2 }); // 2× for Retina
const url  = URL.createObjectURL(blob);
const a    = document.createElement('a');
a.href = url; a.download = 'chart.png'; a.click();

// Base64 — for embedding in email HTML
const b64 = await chart.toImage('png', { format: 'base64' });
// <img src="data:image/png;base64,${b64}">

forge/schema

Zod-compatible schema validation with TypeScript inference, coercion, transforms, and OpenAPI generation.

Primitive Types

String Validators

Number Validators

Complex Types

Object Methods

Schema Modifiers

Transforms & Custom Validation

Parsing Methods

Coercion

The z.coerce namespace wraps schemas with a type-cast transform, useful for URL params and form data that arrive as strings:

import { z } from '@hyperbridge/forge/schema';

// URL param ?page=3 arrives as string
const querySchema = z.object({
  page:   z.coerce.number().int().positive().default(1),
  limit:  z.coerce.number().int().min(1).max(100).default(20),
  active: z.coerce.boolean().default(true),   // '1','true','yes' → true
  date:   z.coerce.date().optional(),          // ISO string → Date
});

querySchema.parse({ page: '3', limit: '50', active: '1' });
// → { page: 3, limit: 50, active: true }

TypeScript Inference

import { z } from '@hyperbridge/forge/schema';

const PostSchema = z.object({
  id:          z.number().int().positive(),
  title:       z.string().min(1).max(200),
  body:        z.string(),
  status:      z.enum(['draft', 'published', 'archived']).default('draft'),
  tags:        z.array(z.string()).max(10).default([]),
  publishedAt: z.date().optional(),
  author: z.object({
    id:    z.number(),
    email: z.string().email(),
    name:  z.string(),
  }),
});

// Infer the output type
type Post = z.infer<typeof PostSchema>;
// {
//   id: number;
//   title: string;
//   body: string;
//   status: 'draft' | 'published' | 'archived';
//   tags: string[];
//   publishedAt?: Date;
//   author: { id: number; email: string; name: string };
// }

// Input type (before defaults are applied)
type PostInput = z.input<typeof PostSchema>;

Async Validation

import { z } from '@hyperbridge/forge/schema';

const RegisterSchema = z.object({
  email: z.string().email().refine(
    async (email) => {
      const count = await db.count('users', { email });
      return count === 0;
    },
    { message: 'Email already registered' }
  ),
  username: z.string().min(3).max(20).regex(/^[a-z0-9_]+$/).refine(
    async (username) => {
      const taken = await db.exists('users', { username });
      return !taken;
    },
    { message: 'Username taken' }
  ),
  password:        z.string().min(8),
  confirmPassword: z.string(),
}).refine(data => data.password === data.confirmPassword, {
  message: 'Passwords do not match',
  path: ['confirmPassword'],
});

const result = await RegisterSchema.safeParseAsync(req.body);
if (!result.success) {
  return res.status(422).json({ errors: result.error.flatten() });
}

OpenAPI Generation

import { z } from '@hyperbridge/forge/schema';

const ProductSchema = z.object({
  id:       z.number().int().positive().describe('Unique product ID'),
  name:     z.string().min(1).max(100).describe('Product display name'),
  price:    z.number().positive().describe('Price in USD'),
  category: z.enum(['electronics', 'clothing', 'food']).describe('Product category'),
  inStock:  z.boolean().default(true).describe('Whether product is available'),
});

// Generate OpenAPI 3.0 schema component
const openApiSchema = ProductSchema.toOpenAPI({ title: 'Product' });
// {
//   title: 'Product',
//   type: 'object',
//   required: ['id', 'name', 'price', 'category'],
//   properties: {
//     id:       { type: 'integer', minimum: 1, description: 'Unique product ID' },
//     name:     { type: 'string', minLength: 1, maxLength: 100 },
//     price:    { type: 'number', exclusiveMinimum: 0 },
//     category: { type: 'string', enum: ['electronics', 'clothing', 'food'] },
//     inStock:  { type: 'boolean', default: true },
//   },
// }

forge/test

Jest-compatible test runner — describe/it/expect, mocking, spies, DOM testing, HTTP mocking, property-based testing, snapshots, benchmarks, and coverage. Zero config, zero dependencies.

Runner Configuration

Expect Matchers

Mock API (fn / spyOn)

Example: Unit Tests with Lifecycle Hooks

import { describe, it, expect, beforeEach, afterEach, beforeAll, afterAll } from '@hyperbridge/forge/test';
import { UserService } from './user-service.js';

describe('UserService', () => {
  let service;
  let db;

  beforeAll(async () => {
    db = await createTestDatabase();
  });

  afterAll(async () => {
    await db.destroy();
  });

  beforeEach(async () => {
    await db.truncate('users');
    service = new UserService(db);
  });

  it('creates a user', async () => {
    const user = await service.create({ email: 'a@b.com', name: 'Alex' });
    expect(user.id).toBeGreaterThan(0);
    expect(user.email).toBe('a@b.com');
    expect(user.createdAt).toBeInstanceOf(Date);
  });

  it('throws on duplicate email', async () => {
    await service.create({ email: 'dup@b.com' });
    await expect(service.create({ email: 'dup@b.com' })).rejects.toThrowError('Email already exists');
  });

  it('finds by id', async () => {
    const created = await service.create({ email: 'find@b.com', name: 'Find Me' });
    const found   = await service.findById(created.id);
    expect(found).toEqual(expect.objectContaining({ email: 'find@b.com', name: 'Find Me' }));
  });
});

Example: Mocking & Spies

import { describe, it, expect, fn, spyOn, beforeEach } from '@hyperbridge/forge/test';
import { NotificationService } from './notifications.js';
import * as mailer from '@hyperbridge/forge/mail';

describe('NotificationService', () => {
  let sendMailSpy;

  beforeEach(() => {
    sendMailSpy = spyOn(mailer.SMTPClient.prototype, 'sendMail')
      .mockResolvedValue({ messageId: 'test-123' });
  });

  afterEach(() => {
    sendMailSpy.mockRestore();
  });

  it('sends welcome email on registration', async () => {
    const svc = new NotificationService();
    await svc.sendWelcome({ email: 'user@example.com', name: 'Alex' });

    expect(sendMailSpy).toHaveBeenCalledTimes(1);
    expect(sendMailSpy).toHaveBeenCalledWith(
      expect.objectContaining({
        to:      'user@example.com',
        subject: expect.stringContaining('Welcome'),
      })
    );
  });

  it('retries on transient failure', async () => {
    sendMailSpy
      .mockRejectedValueOnce(new Error('SMTP connection refused'))
      .mockResolvedValueOnce({ messageId: 'retry-ok' });

    const svc = new NotificationService({ retries: 2 });
    await svc.sendWelcome({ email: 'retry@example.com', name: 'Retry' });

    expect(sendMailSpy).toHaveBeenCalledTimes(2);
  });
});

Example: DOM / Component Testing

import { describe, it, expect, render, screen, fireEvent, waitFor } from '@hyperbridge/forge/test';
import { Counter, LoginForm, UserList } from './components.js';

describe('Counter', () => {
  it('renders initial count', () => {
    render(Counter, { props: { initial: 5 } });
    expect(screen.getByText('Count: 5')).toBeDefined();
  });

  it('increments on button click', async () => {
    render(Counter);
    fireEvent.click(screen.getByRole('button', { name: 'Increment' }));
    expect(screen.getByText('Count: 1')).toBeDefined();
  });

  it('matches snapshot', () => {
    const { container } = render(Counter);
    expect(container.innerHTML).toMatchSnapshot();
  });
});

describe('LoginForm', () => {
  it('shows error on empty submit', async () => {
    render(LoginForm);
    fireEvent.submit(screen.getByRole('form'));
    await waitFor(() => {
      expect(screen.getByText('Email is required')).toBeDefined();
    });
  });

  it('calls onSubmit with form data', async () => {
    const onSubmit = fn();
    render(LoginForm, { props: { onSubmit } });

    await fireEvent.type(screen.getByLabelText('Email'),    'user@example.com');
    await fireEvent.type(screen.getByLabelText('Password'), 'pass1234');
    fireEvent.submit(screen.getByRole('form'));

    await waitFor(() => {
      expect(onSubmit).toHaveBeenCalledWith({ email: 'user@example.com', password: 'pass1234' });
    });
  });
});

Example: Property-Based Testing

import { describe, it, expect, forAll, gen } from '@hyperbridge/forge/test';
import { sortByAge } from './sort.js';

describe('sortByAge', () => {
  // Runs 100 random inputs automatically
  forAll('is idempotent', gen.array(gen.object({ name: gen.string(), age: gen.integer(0, 120) })), (users) => {
    const once  = sortByAge(users);
    const twice = sortByAge(once);
    expect(once).toEqual(twice); // sorting twice == sorting once
  });

  forAll('output is sorted', gen.array(gen.object({ age: gen.integer(0, 120) }), { minLength: 1 }), (users) => {
    const sorted = sortByAge(users);
    for (let i = 0; i < sorted.length - 1; i++) {
      expect(sorted[i].age).toBeLessThanOrEqual(sorted[i + 1].age);
    }
  });
});

// Available generators
gen.integer(min, max)        // random integer
gen.float(min, max)          // random float
gen.string(minLen?, maxLen?) // random alphanumeric string
gen.boolean()                // random boolean
gen.enum(['a', 'b', 'c'])    // random enum value
gen.array(itemGen, opts?)    // random array
gen.object(shape)            // random object from shape map
gen.nullable(gen)            // randomly null or the generator's value
gen.oneOf([gen1, gen2])      // pick one of multiple generators

Example: HTTP Mocking

import { describe, it, expect, mockFetch, clearFetchMocks } from '@hyperbridge/forge/test';
import { GithubClient } from './github.js';

describe('GithubClient', () => {
  afterEach(clearFetchMocks);

  it('fetches repos', async () => {
    mockFetch('GET https://api.github.com/users/octocat/repos', {
      status: 200,
      body:   [{ id: 1, name: 'Hello-World', stargazers_count: 1000 }],
    });

    const client = new GithubClient({ token: 'test' });
    const repos  = await client.getRepos('octocat');

    expect(repos).toHaveLength(1);
    expect(repos[0].name).toBe('Hello-World');
  });

  it('throws on 404', async () => {
    mockFetch('GET https://api.github.com/users/nobody/repos', { status: 404 });
    const client = new GithubClient({ token: 'test' });
    await expect(client.getRepos('nobody')).rejects.toThrow('Not found');
  });
});

Example: Benchmarks

import { bench, describe } from '@hyperbridge/forge/test';
import { z } from '@hyperbridge/forge/schema';

const UserSchema = z.object({ id: z.number(), email: z.string().email(), name: z.string() });
const user = { id: 1, email: 'a@b.com', name: 'Alex' };

describe('Schema performance', () => {
  bench('z.parse (valid)',   () => UserSchema.parse(user),          { iterations: 50_000 });
  bench('z.safeParse (valid)', () => UserSchema.safeParse(user),    { iterations: 50_000 });
  bench('z.safeParse (invalid)', () => UserSchema.safeParse({ id: 'bad' }), { iterations: 50_000 });
});

// Output:
// z.parse (valid)           ~1,840,000 ops/s  (0.54µs/op)
// z.safeParse (valid)       ~1,750,000 ops/s  (0.57µs/op)
// z.safeParse (invalid)     ~1,200,000 ops/s  (0.83µs/op)

forge/mail

SMTP client with DKIM signing, connection pooling, templating, queuing, open/click tracking, bounce management, calendar invites, and A/B testing. No Nodemailer, no external transport libraries.

SMTPClient Configuration

sendMail Options

Additional Classes

Example: SMTP with DKIM

import { SMTPClient } from '@hyperbridge/forge/mail';
import fs from 'node:fs';

const smtp = new SMTPClient({
  host:   'smtp.postmarkapp.com',
  port:   587,
  auth:   { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS },
  dkim:   {
    domain:     'hyperbridge.digital',
    keySelector: 'default',
    privateKey:  fs.readFileSync('./keys/dkim-private.pem', 'utf8'),
  },
  pool:   true,
  maxConnections: 5,
  rateLimit: 20,  // 20 msgs/sec
});

// Transactional email with attachment
await smtp.sendMail({
  from:    'HyperBridge Digital <noreply@hyperbridge.digital>',
  to:      'user@example.com',
  subject: 'Your invoice is ready',
  html:    `<h1>Invoice #1042</h1><p>See attached.</p>`,
  attachments: [{
    filename:    'invoice-1042.pdf',
    content:     pdfBuffer,
    contentType: 'application/pdf',
  }],
});

Example: EmailTemplate

import { SMTPClient, EmailTemplate } from '@hyperbridge/forge/mail';

// Template with conditionals and loops
const orderTemplate = new EmailTemplate({
  subject: 'Order #{{orderId}} confirmed',
  html: `
    <h1>Hi {{firstName}},</h1>
    <p>Your order #{{orderId}} has been confirmed.</p>

    <table>
      {{#each items}}
      <tr>
        <td>{{name}}</td>
        <td>{{qty}}</td>
        <td>{{price}}</td>
      </tr>
      {{/each}}
    </table>

    <p>Total: {{total}}</p>

    {{#if isPremium}}
    <p>🎁 As a Premium member, you get free shipping!</p>
    {{/if}}
  `,
});

const email = orderTemplate.render({
  firstName: 'Priya',
  orderId:   'ORD-9981',
  items: [
    { name: 'HBForge License', qty: 1, price: '$2,400' },
    { name: 'Support',         qty: 3, price: '$450'   },
  ],
  total:     '$2,850',
  isPremium: true,
});

await smtp.sendMail({ from: 'orders@app.com', to: 'priya@example.com', ...email });

Example: MailQueue — Bulk Newsletter

import { SMTPClient, MailQueue, EmailTemplate, BounceList } from '@hyperbridge/forge/mail';

const bounces = new BounceList();
await bounces.import(await db.getBounces()); // load from DB

const queue = new MailQueue(smtp, {
  rateLimit: 50,           // 50 msgs/sec
  concurrency: 5,
  retries: 2,
  onError: (err, msg) => console.error('Failed:', msg.to, err.message),
});

const newsletter = new EmailTemplate({
  subject: 'HBForge April Update',
  html:    await fs.promises.readFile('./emails/newsletter.html', 'utf8'),
});

for (const subscriber of subscribers) {
  if (bounces.has(subscriber.email)) continue; // skip bounced

  queue.enqueue({
    to:   subscriber.email,
    from: 'newsletter@hyperbridge.digital',
    ...newsletter.render({ name: subscriber.firstName }),
  });
}

const result = await queue.flush();
console.log(`Sent: ${result.sent}, Failed: ${result.failed}`);

Example: CalendarInvite

import { SMTPClient, CalendarInvite } from '@hyperbridge/forge/mail';

const invite = new CalendarInvite({
  uid:         'meet-2026-04-20@hyperbridge.digital',
  summary:     'HBForge Onboarding Call',
  description: 'Welcome call with your HBForge onboarding team.',
  location:    'Google Meet — meet.google.com/abc-defg-hij',
  organizer:   { name: 'HyperBridge Digital', email: 'hello@hyperbridge.digital' },
  attendees:   [{ name: 'Alex', email: 'alex@client.com', rsvp: true }],
  start:       new Date('2026-04-20T10:00:00+05:30'),
  end:         new Date('2026-04-20T11:00:00+05:30'),
  timezone:    'Asia/Kolkata',
  reminders:   [{ minutes: 15 }, { minutes: 1440 }], // 15 min + 1 day before
});

await smtp.sendMail({
  from:        'hello@hyperbridge.digital',
  to:          'alex@client.com',
  subject:     'HBForge Onboarding Call — April 20',
  html:        '<p>You are invited to an onboarding call. See the attached invite.</p>',
  attachments: [invite.toAttachment()], // .ics attachment
});

forge/pdf

Pure JavaScript PDF 1.7 generation — text, tables, images, custom fonts, encryption, QR codes, and streaming output.

Constructor

Drawing API

QR Codes & Barcodes

Example: Professional Invoice

import { PDFForge, QRCode } from '@hyperbridge/forge/pdf';

const doc = new PDFForge({
  pageSize: 'A4',
  margin:   { top: 40, right: 50, bottom: 60, left: 50 },
  metadata: { title: 'Invoice #1042', author: 'HyperBridge Digital' },
});

// Header bar
doc.rect({ x: 0, y: 0, width: 595, height: 80, fill: '#6366f1' });
doc.setFont('Helvetica-Bold', 22);
doc.setColor('#ffffff');
doc.text('HyperBridge Digital', { x: 50, y: 28 });
doc.setFont('Helvetica', 11);
doc.text('hyperbridge.digital · Chennai, India', { x: 50, y: 52 });

// Invoice number (right-aligned)
doc.setFont('Helvetica-Bold', 18);
doc.text('INVOICE #1042', { x: 340, y: 35, align: 'right', maxWidth: 205 });

doc.setColor('#111111');

// Bill to / date block
doc.setFont('Helvetica-Bold', 10);
doc.text('BILL TO', { x: 50, y: 105 });
doc.setFont('Helvetica', 10);
doc.text('Acme Technologies\nMumbai, India\nbilling@acme.example', { x: 50, y: 118, lineHeight: 1.5 });

doc.setFont('Helvetica-Bold', 10);
doc.text('DATE', { x: 380, y: 105 });
doc.setFont('Helvetica', 10);
doc.text('April 14, 2026', { x: 380, y: 118 });
doc.text('DUE: April 28, 2026', { x: 380, y: 132 });

// Horizontal rule
doc.line({ x1: 50, y1: 175, x2: 545, y2: 175, width: 0.5, color: '#cccccc' });

// Items table
doc.table({
  x: 50, y: 185,
  columns: [
    { header: 'Description', width: 260 },
    { header: 'Qty',         width: 55, align: 'right' },
    { header: 'Unit Price',  width: 90, align: 'right' },
    { header: 'Amount',      width: 90, align: 'right' },
  ],
  rows: [
    ['HBForge Enterprise License (Annual)', '1', '$2,400.00', '$2,400.00'],
    ['Onboarding & Setup (hrs)',             '4', '  $150.00', '  $600.00'],
    ['Priority Support (Monthly)',           '3', '  $200.00', '  $600.00'],
  ],
  headerStyle: { fillColor: '#f5f7ff', bold: true, fontSize: 10 },
  cellPadding: 9,
  borderColor: '#e5e7eb',
  stripedRows: true,
});

// Totals
doc.setFont('Helvetica-Bold', 11);
doc.text('Total: $3,600.00', { x: 545, y: 320, align: 'right' });

// QR code for payment URL
const qr = QRCode.generate('https://pay.hyperbridge.digital/inv/1042', { size: 80 });
doc.image(qr, { x: 450, y: 680, width: 80, height: 80 });
doc.setFont('Helvetica', 8);
doc.setColor('#888888');
doc.text('Scan to pay', { x: 490, y: 765, align: 'center', maxWidth: 80 });

// Footer
doc.setFooter(({ page, total }) =>
  `Page ${page} of ${total}  ·  Thank you for your business!`
);

const pdfBytes = doc.build();
await fs.writeFile('invoice-1042.pdf', pdfBytes);

Example: Custom TTF Fonts

import { PDFForge } from '@hyperbridge/forge/pdf';
import fs from 'node:fs';

const doc = new PDFForge({ pageSize: 'A4' });

// Load custom font from TTF buffer
const interBold    = fs.readFileSync('./fonts/Inter-Bold.ttf');
const interRegular = fs.readFileSync('./fonts/Inter-Regular.ttf');

doc.loadFont('Inter-Bold',    interBold);
doc.loadFont('Inter-Regular', interRegular);

doc.setFont('Inter-Bold', 24);
doc.text('Custom Fonts', { x: 50, y: 60 });

doc.setFont('Inter-Regular', 12);
doc.text(
  'This paragraph uses the Inter typeface, loaded from a .ttf file. ' +
  'forge/pdf subsets the font automatically — only the glyphs actually ' +
  'used in the document are embedded, keeping file size minimal.',
  { x: 50, y: 100, maxWidth: 495, lineHeight: 1.6 }
);

const pdf = doc.build();
await fs.promises.writeFile('custom-font.pdf', pdf);

Example: Password-Protected PDF

import { PDFForge } from '@hyperbridge/forge/pdf';

const doc = new PDFForge({
  pageSize: 'A4',
  encrypt: {
    userPassword:  'view-password',   // required to open
    ownerPassword: 'admin-password',  // required to change permissions
    permissions: ['print'],           // allow printing, disallow copy/edit
  },
});

doc.setFont('Helvetica-Bold', 18);
doc.text('Confidential Report', { x: 50, y: 50 });
doc.setFont('Helvetica', 12);
doc.text('This document is encrypted. Copying is disabled.', { x: 50, y: 80 });

const pdf = doc.build();
await fs.promises.writeFile('confidential.pdf', pdf);

Example: Streaming to HTTP Response

import { PDFForge } from '@hyperbridge/forge/pdf';

// forge/server route — streams PDF directly to client
router.get('/invoices/:id/pdf', async (req, res) => {
  const invoice = await Invoice.findById(req.params.id);
  const doc = new PDFForge({ pageSize: 'A4' });

  buildInvoiceContent(doc, invoice);

  const stream = doc.build('stream');

  res.setHeader('Content-Type', 'application/pdf');
  res.setHeader('Content-Disposition', `attachment; filename="invoice-${invoice.id}.pdf"`);
  stream.pipe(res);
});

Example: PDFReader — Extract Text

import { PDFReader } from '@hyperbridge/forge/pdf';

const reader = new PDFReader(pdfBuffer);

// Extract all text
const text = await reader.extractText();

// Get page count
const pageCount = reader.pageCount;

// Extract text per page
for (let p = 1; p <= pageCount; p++) {
  const pageText = await reader.extractText({ page: p });
  console.log(`Page ${p}:`, pageText);
}

// Read metadata
const meta = reader.metadata;
// { title, author, creator, createdAt, modifiedAt, pageCount }

forge/search

In-process full-text search engine with BM25 ranking, autocomplete, facets, highlights, and persistence.

SearchForge Constructor

Search Options

Core API Reference

Example: Documentation Search

import { SearchForge, Highlighter } from '@hyperbridge/forge/search';

const docs = new SearchForge({
  fields:  ['title', 'body', 'section'],
  weights: { title: 4, section: 2, body: 1 },
  stemming: true,
  persistence: './data/search-index.json',  // saved across restarts
});

// Index at startup
docs.addDocuments([
  { id: 'forge-client',  title: 'forge/client', section: 'UI', body: 'React-like component system...' },
  { id: 'forge-server',  title: 'forge/server', section: 'Backend', body: 'HTTP server with routing...' },
  { id: 'forge-auth',    title: 'forge/auth',   section: 'Backend', body: 'Password, JWT, OAuth2...' },
  { id: 'forge-display', title: 'forge/display',section: 'Platform', body: 'DPR detection, quality tiers...' },
  // ... all 22 modules
]);

// Full-text search with highlights
const results = docs.search('jwt authentication', {
  limit:     5,
  highlight: { fields: ['title', 'body'], contextChars: 80 },
  facets:    ['section'],
});

// results[0] →
// {
//   id: 'forge-auth',
//   score: 4.82,
//   doc: { id, title, section, body },
//   highlights: {
//     title: 'authentication',
//     body:  '...validate a JWT token with JWT.verify()...',
//   },
// }

// results.facets →
// { section: { Backend: 2, UI: 1, Platform: 1 } }

// Autocomplete for search-as-you-type
docs.suggest('jw');  // ['jwt', 'jwt.sign', 'jwt.verify']
docs.suggest('an');  // ['animate', 'animation', 'and', 'api']

Example: Boolean & Faceted Search

import { SearchForge, FacetedSearch, Pagination } from '@hyperbridge/forge/search';

const index = new SearchForge({
  fields:  ['name', 'description', 'category', 'tags'],
  weights: { name: 3, description: 1 },
});

index.addDocuments(products); // your product catalog

// Boolean query syntax
index.search('(laptop OR notebook) AND -refurbished');     // AND, OR, NOT
index.search('"wireless mouse"');                           // exact phrase
index.search('title:animation');                            // field-specific
index.search('price:>100 AND category:electronics');        // range filter

// Faceted search with filters
const faceted = new FacetedSearch(index, {
  facets: ['category', 'brand', 'rating'],
});

const { hits, facets, total } = faceted.search('bluetooth headphones', {
  filters: { category: 'electronics', rating: '5' },
  limit: 20,
  offset: 0,
});

// hits  = [{ id, score, doc, highlights }, ...]
// facets = {
//   category: { electronics: 45, accessories: 12 },
//   brand:    { Sony: 8, Bose: 6, JBL: 4 },
//   rating:   { '5': 14, '4': 18, '3': 9 },
// }
// total = 31

Example: RelevanceTuner

import { SearchForge, RelevanceTuner } from '@hyperbridge/forge/search';

const index = new SearchForge({ fields: ['title', 'body'] });
index.addDocuments(articles);

// Boost documents clicked/opened more often
const tuner = new RelevanceTuner(index);

// Record user interactions
tuner.recordClick({ query: 'react hooks', docId: 'forge-client-hooks' });
tuner.recordClick({ query: 'react hooks', docId: 'forge-client-hooks' });  // clicked twice

// Tuner blends BM25 score with engagement signals
const results = tuner.search('react hooks', { limit: 10 });
// 'forge-client-hooks' is boosted compared to raw BM25

// Decay over time — older clicks count less
tuner.setDecay({ halfLife: 7 * 86400 * 1000 }); // 7-day half-life

forge/notify

Unified notification system — DOM toasts, multi-channel delivery (email, SMS, push, WebSocket), retry queue, deduplication, and notification center.

ToastManager

ToastManager handles DOM toast notifications in the browser. It injects its own CSS and manages the toast container automatically.

ToastManager Methods

NotificationManager

NotificationManager is the server-side multi-channel dispatcher. Configure channels once, then .send() routes to all of them.

NotificationCenter

A persistent in-memory notification inbox — track read/unread state, pin, archive, group, and paginate notifications.

RetryQueue

Automatically retries failed notification deliveries with exponential backoff.

Example: Toast Notifications

import { ToastManager } from '@hyperbridge/forge/notify';

const toast = new ToastManager({ position: 'top-right', maxStack: 5 });

// Basic types
toast.success('File uploaded successfully');
toast.error('Connection failed — please retry');
toast.warning('Your session expires in 5 minutes');
toast.info('New version available — reload to update');

// Custom duration + action button
toast.success('3 files deleted', {
  duration: 6000,
  action: { label: 'Undo', onClick: () => restoreFiles() },
});

// Loading → result (the most common pattern)
await toast.promise(
  fetch('/api/data', { method: 'POST', body: payload }),
  {
    loading: 'Saving changes…',
    success: (data) => `Saved ${data.count} records`,
    error:   (err)  => `Save failed: ${err.message}`,
  }
);

// Update an existing toast
const id = toast.loading('Processing…');
await runHeavyTask();
toast.update(id, { type: 'success', message: 'Done!' });

Example: Multi-Channel NotificationManager

import { NotificationManager, RetryQueue } from '@hyperbridge/forge/notify';

const nm = new NotificationManager({
  channels: {
    email: {
      type: 'smtp',
      host: 'smtp.postmarkapp.com',
      port: 587,
      auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS },
      from: 'noreply@myapp.com',
    },
    sms: {
      type: 'twilio',
      accountSid: process.env.TWILIO_SID,
      authToken:  process.env.TWILIO_TOKEN,
      from:       '+15551234567',
    },
  },
  retry: new RetryQueue({ maxAttempts: 3, backoffFactor: 2 }),
});

// Route to all configured channels
await nm.send({
  to:       { email: 'user@example.com', phone: '+919876543210' },
  channels: ['email', 'sms'],
  subject:  'Security alert',
  body:     'A new login was detected from Chennai, India.',
  type:     'warning',
  priority: 'urgent',
});

// Channel events — track delivery status
nm.on('delivered', ({ channel, notification }) =>
  console.log(`Delivered via ${channel}:`, notification.id));
nm.on('failed', ({ channel, error, attempt }) =>
  console.error(`Channel ${channel} failed (attempt ${attempt}):`, error));

Example: NotificationCenter

import { NotificationCenter, QuietHours } from '@hyperbridge/forge/notify';

const center = new NotificationCenter({ maxHistory: 200 });

// Add notifications (typically from server events or WebSocket)
center.add({ id: '1', title: 'PR merged',     body: 'main ← feature/auth',       type: 'success' });
center.add({ id: '2', title: 'Build failed',   body: 'deploy-prod failed at step 3', type: 'error' });
center.add({ id: '3', title: 'New comment',    body: 'Alex replied to your post',  type: 'info' });

// Badge count (for notification bell icon)
center.unreadCount(); // 3

// Mark interactions
center.markRead('1');
center.pin('2');       // always at top
center.archive('3');   // hide from default view

// Paginated listing
const page1 = center.getAll({ page: 1, limit: 20 });
const unread = center.getUnread();

// Quiet hours — suppress delivery between 22:00 and 08:00
const quiet = new QuietHours({ start: '22:00', end: '08:00', timezone: 'Asia/Kolkata' });
quiet.isSilent(new Date()); // true if currently in quiet window

// Subscribe to changes (update badge in UI)
center.on('add',     () => updateBadge(center.unreadCount()));
center.on('read',    () => updateBadge(center.unreadCount()));
center.on('archive', () => updateBadge(center.unreadCount()));

forge/cli

CLI framework with commands, options, prompts, colors, spinners, and config management.

CLI Constructor

Command Definition

Interactive Prompts

Core APIs

• CLI - Main CLI class
• command(name, fn) - Define command
• option(name, config) - Add option/flag
• argument(name, config) - Add argument
• Prompt - Interactive prompts
• Spinner - Loading spinner
• ProgressBar - Progress visualization
• colors - Terminal colors
• table - Format data tables
• log - Logging utilities

Example: CLI Application

import { CLI, Prompt, Spinner, colors } from '@hyperbridge/forge/cli';

const cli = new CLI({
  name: 'myapp',
  version: '1.0.0',
  description: 'My awesome CLI tool',
});

// Define command
cli.command('create', async (args, options) => {
  const name = await Prompt.input('Project name:');

  const spinner = new Spinner(`Creating ${name}...`);
  spinner.start();

  // Do work...
  await new Promise(r => setTimeout(r, 2000));

  spinner.succeed(`Project created: ${colors.green(name)}`);
});

// Define another command
cli.command('build', async (args, options) => {
  const watch = options.watch || false;
  console.log(`Building${watch ? ' (watch)' : ''}...`);
  // Build logic...
});

cli.command('serve', async (args, options) => {
  const port = options.port || 3000;
  console.log(`Server running on ${colors.cyan(`http://localhost:${port}`)}`);
});

// Parse and execute
cli.parse(process.argv);

Example: Interactive Prompts

import { Prompt, colors } from '@hyperbridge/forge/cli';

// Text input
const name = await Prompt.input('Your name:');

// Confirmation
const proceed = await Prompt.confirm('Continue?');

// Select from options
const choice = await Prompt.select('Choose one:', [
  { label: 'Option A', value: 'a' },
  { label: 'Option B', value: 'b' },
  { label: 'Option C', value: 'c' },
]);

// Multi-select
const tags = await Prompt.multiSelect('Select tags:', [
  'important',
  'urgent',
  'feature',
  'bugfix',
]);

// Display results
console.log(`${colors.green('✓')} Name: ${name}`);
console.log(`${colors.blue('ℹ')} Choice: ${choice}`);
console.log(`${colors.yellow('⚠')} Tags: ${tags.join(', ')}`);

forge/i18n

Internationalization with translations, formatting, and locale management.

I18n Constructor

Translation API

Formatting API

Core APIs

• I18n - Main i18n class
• t(key, context) - Translate key
• setLocale(locale) - Set current locale
• getLocale() - Get current locale
• formatDate(date, locale) - Format date
• formatTime(date, locale) - Format time
• formatNumber(num, locale) - Format number
• formatCurrency(amount, currency) - Format currency
• formatList(items) - Format list
• formatRelative(date) - Relative time (e.g., "2 hours ago")
• pluralize(count, keys) - Plural handling
• isRTL(locale) - Check RTL language

Example: Setup & Usage

import { I18n } from '@hyperbridge/forge/i18n';

const i18n = new I18n({
  defaultLocale: 'en',
  fallbackLocale: 'en',
});

// Register translations
i18n.addMessages('en', {
  'greeting': 'Hello, {name}!',
  'items.one': 'You have 1 item',
  'items.other': 'You have {count} items',
  'welcome': 'Welcome to {app}',
});

i18n.addMessages('es', {
  'greeting': '¡Hola, {name}!',
  'items.one': 'Tienes 1 artículo',
  'items.other': 'Tienes {count} artículos',
  'welcome': 'Bienvenido a {app}',
});

// Translate
console.log(i18n.t('greeting', { name: 'John' }));
// en: "Hello, John!"
// es: "¡Hola, John!"

// Pluralize
console.log(i18n.t('items', { count: 1 }));
// "You have 1 item" (en) / "Tienes 1 artículo" (es)

console.log(i18n.t('items', { count: 5 }));
// "You have 5 items" (en) / "Tienes 5 artículos" (es)

Example: Formatting

import { I18n } from '@hyperbridge/forge/i18n';

const i18n = new I18n({ defaultLocale: 'en-US' });

// Date formatting
const date = new Date('2026-03-15');
console.log(i18n.formatDate(date)); // "3/15/2026"
console.log(i18n.formatDate(date, 'es-ES')); // "15/3/2026"

// Number formatting
console.log(i18n.formatNumber(1234.56)); // "1,234.56" (en-US)
console.log(i18n.formatNumber(1234.56, 'de-DE')); // "1.234,56"

// Currency formatting
console.log(i18n.formatCurrency(99.99, 'USD')); // "$99.99"
console.log(i18n.formatCurrency(99.99, 'EUR', 'de-DE')); // "99,99 €"

// Relative time
console.log(i18n.formatRelative(new Date() - 3600000)); // "1 hour ago"
console.log(i18n.formatRelative(new Date() + 86400000)); // "in 1 day"

// List formatting
const items = ['Apple', 'Banana', 'Orange'];
console.log(i18n.formatList(items)); // "Apple, Banana, and Orange"
console.log(i18n.formatList(items, 'es-ES')); // "Apple, Banana y Orange"

forge/pwa

Progressive Web App toolkit — Service Workers, offline caching, Web Push (RFC 8291/8292), Background Sync, App Shell, and install management. Replaces workbox, web-push, next-pwa, and vite-plugin-pwa with zero dependencies.

PWAForge — Manifest & Service Worker

CacheStrategy

Five built-in strategies matching Workbox's patterns, each with configurable options:

PushManager

Key API Reference

Example: Full PWA Setup

// build-sw.js — run during build to generate /public/sw.js
import { PWAForge, CacheStrategy, AppShell } from '@hyperbridge/forge/pwa';
import fs from 'node:fs';

const pwa = new PWAForge({
  name:            'HBForge Docs',
  shortName:       'HBForge',
  themeColor:      '#6366f1',
  backgroundColor: '#0a0a0f',
  display:         'standalone',
  startUrl:        '/',
  icons: [
    { src: '/icons/icon-192.png', sizes: '192x192', type: 'image/png' },
    { src: '/icons/icon-512.png', sizes: '512x512', type: 'image/png', purpose: 'maskable' },
  ],
});

// 1. Serve manifest.json
fs.writeFileSync('./public/manifest.json', JSON.stringify(pwa.generateManifest(), null, 2));

// 2. Generate service worker
const sw = pwa.generateServiceWorkerCode({
  version:         '1.2.0',
  offlineFallback: '/offline.html',

  // Precache app shell
  precacheUrls: ['/', '/app.js', '/app.css', '/offline.html', '/icons/icon-192.png'],

  // Route-level strategies
  routes: [
    { match: '/api/*',    strategy: CacheStrategy.NetworkFirst({ timeout: 3000, cacheName: 'api-v1' }) },
    { match: '/images/*', strategy: CacheStrategy.CacheFirst({ cacheName: 'images-v1', maxEntries: 200, maxAge: 30 * 86400 }) },
    { match: '/*',        strategy: CacheStrategy.StaleWhileRevalidate({ cacheName: 'pages-v1' }) },
  ],

  // SPA — serve index.html for all navigation
  appShell: AppShell.generateShellCode({ shell: '/index.html' }),
});

fs.writeFileSync('./public/sw.js', sw);
console.log('Service worker generated.');

Example: Web Push

// 1. GENERATE VAPID KEYS ONCE (store in environment variables)
import { generateVAPIDKeys } from '@hyperbridge/forge/pwa';
const keys = generateVAPIDKeys();
// { publicKey: 'BN...', privateKey: 'k2...' }
// → VAPID_PUBLIC_KEY=BN...   VAPID_PRIVATE_KEY=k2...

// 2. CLIENT — subscribe the browser
const registration = await navigator.serviceWorker.ready;
const subscription = await registration.pushManager.subscribe({
  userVisibleOnly:      true,
  applicationServerKey: process.env.VAPID_PUBLIC_KEY,
});
await fetch('/api/push/subscribe', {
  method: 'POST',
  body:   JSON.stringify(subscription),
});

// 3. SERVER — send notifications
import { PushManager } from '@hyperbridge/forge/pwa';

const push = new PushManager({
  vapidPublicKey:  process.env.VAPID_PUBLIC_KEY,
  vapidPrivateKey: process.env.VAPID_PRIVATE_KEY,
  subject:         'mailto:hello@hyperbridge.digital',
});

// Send to one subscriber
await push.sendNotification(subscription, {
  title: 'New message',
  body:  'You have 3 unread messages',
  icon:  '/icons/icon-192.png',
  badge: '/icons/badge-72.png',
  url:   '/messages',
  actions: [
    { action: 'view',    title: 'View' },
    { action: 'dismiss', title: 'Dismiss' },
  ],
});

// Bulk send (e.g. broadcast to all users)
const results = await push.sendBatch(allSubscriptions, payload, { concurrency: 50 });
console.log(`Sent: ${results.sent}, Failed: ${results.failed}`);

Example: Background Sync

// In your app code — queue a request when offline
import { BackgroundSync } from '@hyperbridge/forge/pwa';

const sync = new BackgroundSync({ queueName: 'form-submissions' });

async function submitForm(data) {
  try {
    await fetch('/api/submit', { method: 'POST', body: JSON.stringify(data) });
  } catch (err) {
    // Network failed — queue for later
    await sync.enqueue({ url: '/api/submit', method: 'POST', body: JSON.stringify(data) });
    console.log('Queued for background sync when connection restores');
  }
}

// In service-worker.js — replay queued requests on sync event
self.addEventListener('sync', (event) => {
  if (event.tag === 'form-submissions') {
    event.waitUntil(sync.replay());
  }
});

Example: UpdateManager

// In your app — prompt user when a new SW version is available
import { UpdateManager } from '@hyperbridge/forge/pwa';

const updater = new UpdateManager('/sw.js');

updater.onUpdateFound(() => {
  // Show a toast or banner
  const banner = document.createElement('div');
  banner.textContent = 'App updated — reload to apply';
  const btn = document.createElement('button');
  btn.textContent = 'Reload';
  btn.onclick = () => updater.applyUpdate(); // skipWaiting + reload
  banner.appendChild(btn);
  document.body.prepend(banner);
});

// Check on focus (catches updates while tab was in background)
window.addEventListener('focus', () => updater.checkForUpdates());

forge/3d

WebGL2-based 3D engine — scene graph, PBR materials, cameras, lights, post-processing, particle systems, animation, and controls. A zero-dependency Three.js alternative with 368 APIs in 5,400 lines.

Installation

import {
  Scene, WebGLRenderer, PerspectiveCamera, OrthographicCamera,
  Mesh, BoxGeometry, SphereGeometry, PlaneGeometry, StandardMaterial,
  AmbientLight, DirectionalLight, PointLight,
  OrbitControls, AnimationMixer, EffectComposer
} from '@hyperbridge/forge/3d';

Quick Start — Rotating Cube

import {
  Scene, WebGLRenderer, PerspectiveCamera,
  Mesh, BoxGeometry, StandardMaterial,
  AmbientLight, DirectionalLight, Clock
} from '@hyperbridge/forge/3d';

// Create scene
const scene = new Scene();
const camera = new PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
camera.position.set(0, 2, 5);
camera.lookAt(0, 0, 0);

// Create renderer
const renderer = new WebGLRenderer({ canvas: document.getElementById('canvas'), antialias: true });
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setClearColor(0x0a0a0f);

// Add lights
scene.add(new AmbientLight(0x404040, 0.5));
const dirLight = new DirectionalLight(0xffffff, 1.0);
dirLight.position.set(5, 10, 7);
scene.add(dirLight);

// Create cube
const cube = new Mesh(
  new BoxGeometry(1, 1, 1),
  new StandardMaterial({ color: 0x6366f1, metalness: 0.3, roughness: 0.4 })
);
scene.add(cube);

// Animation loop
const clock = new Clock();
function animate() {
  requestAnimationFrame(animate);
  const dt = clock.getDelta();
  cube.rotation.x += 0.5 * dt;
  cube.rotation.y += 0.8 * dt;
  renderer.render(scene, camera);
}
animate();

Math Primitives

Full linear algebra library for 3D math — vectors, matrices, quaternions, rays, and bounding volumes.

import { Vec3, Mat4, Quat, Color } from '@hyperbridge/forge/3d';

const v = new Vec3(1, 2, 3);
const n = v.normalize();              // unit vector
const d = v.dot(new Vec3(0, 1, 0));   // dot product

const m = Mat4.perspective(Math.PI / 4, 16 / 9, 0.1, 100);
const q = Quat.fromAxisAngle(new Vec3(0, 1, 0), Math.PI / 2);

const c = new Color(0x6366f1);
const lighter = c.lerp(new Color(0xffffff), 0.3);

Geometry

Built-in geometry primitives with customizable segments, plus a base class for custom geometry.

import { BoxGeometry, SphereGeometry, CylinderGeometry, InstancedMesh, Mesh, StandardMaterial } from '@hyperbridge/forge/3d';

const box = new BoxGeometry(2, 2, 2);
const sphere = new SphereGeometry(1, 32, 32);
const cylinder = new CylinderGeometry(0.5, 0.5, 3, 16);

// Instanced rendering — 10,000 cubes in one draw call
const instanced = new InstancedMesh(box, new StandardMaterial({ color: 0x22d3ee }), 10000);
for (let i = 0; i < 10000; i++) {
  instanced.setMatrixAt(i, Mat4.translation(Math.random() * 100, Math.random() * 100, Math.random() * 100));
}
scene.add(instanced);

Materials

PBR and non-PBR material types for every rendering need — from wireframe debugging to physically-based metallic/roughness workflows.

import { StandardMaterial, ShaderMaterial } from '@hyperbridge/forge/3d';

const pbr = new StandardMaterial({
  color: 0x6366f1,
  metalness: 0.8,
  roughness: 0.2,
  emissive: 0x111111,
});

const custom = new ShaderMaterial({
  vertexShader: `
    attribute vec3 position;
    uniform mat4 projectionMatrix, modelViewMatrix;
    void main() { gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }
  `,
  fragmentShader: `
    precision mediump float;
    uniform float time;
    void main() { gl_FragColor = vec4(sin(time), 0.4, 0.9, 1.0); }
  `,
  uniforms: { time: { value: 0 } }
});

Scene Graph

Hierarchical scene graph with parent-child transforms, groups, and visibility control.

import { Scene, Group, Mesh, BoxGeometry, StandardMaterial } from '@hyperbridge/forge/3d';

const scene = new Scene();
scene.background = new Color(0x0a0a0f);

const group = new Group();
group.position.set(0, 1, 0);

const mesh = new Mesh(new BoxGeometry(1, 1, 1), new StandardMaterial({ color: 0x22d3ee }));
group.add(mesh);
scene.add(group);

group.rotation.y = Math.PI / 4;  // rotates all children

Cameras

import { PerspectiveCamera, OrthographicCamera } from '@hyperbridge/forge/3d';

const cam = new PerspectiveCamera(60, 16 / 9, 0.1, 1000);
cam.position.set(0, 5, 10);
cam.lookAt(0, 0, 0);

const ortho = new OrthographicCamera(-10, 10, 10, -10, 0.1, 100);

Lights

import { AmbientLight, DirectionalLight, PointLight, SpotLight, HemisphereLight } from '@hyperbridge/forge/3d';

scene.add(new AmbientLight(0x404040, 0.4));

const sun = new DirectionalLight(0xffffff, 1.0);
sun.position.set(10, 20, 10);
scene.add(sun);

const bulb = new PointLight(0xff9900, 1.0, 50, 2);
bulb.position.set(0, 3, 0);
scene.add(bulb);

const spot = new SpotLight(0xffffff, 1.0, 100, Math.PI / 6, 0.5, 2);
spot.position.set(0, 10, 0);
scene.add(spot);

scene.add(new HemisphereLight(0x87ceeb, 0x362907, 0.6));

Renderer

import { WebGLRenderer } from '@hyperbridge/forge/3d';

const renderer = new WebGLRenderer({
  canvas: document.getElementById('canvas'),
  antialias: true,
  alpha: false,
  stencil: true,
});
renderer.setSize(window.innerWidth, window.innerHeight);
renderer.setPixelRatio(window.devicePixelRatio);
renderer.setClearColor(0x0a0a0f, 1);
renderer.shadowMap.enabled = true;
renderer.toneMapping = 'aces';
renderer.render(scene, camera);

Animation

Keyframe animation system with mixers, clips, actions, and blending — animate any property over time.

import { AnimationMixer, AnimationClip, KeyframeTrack, Clock } from '@hyperbridge/forge/3d';

const times = [0, 1, 2];
const values = [0, 0, 0, 0, 3, 0, 0, 0, 0];  // Vec3 keyframes
const track = new KeyframeTrack('.position', times, values);
const clip = new AnimationClip('bounce', 2, [track]);

const mixer = new AnimationMixer(cube);
const action = mixer.clipAction(clip);
action.setLoop('repeat');
action.play();

const clock = new Clock();
function animate() {
  requestAnimationFrame(animate);
  mixer.update(clock.getDelta());
  renderer.render(scene, camera);
}
animate();

Post-Processing

Multi-pass post-processing pipeline — bloom, SSAO, glitch, film grain, and more via composable passes.

import { EffectComposer, RenderPass, UnrealBloomPass, SSAOPass } from '@hyperbridge/forge/3d';

const composer = new EffectComposer(renderer);
composer.addPass(new RenderPass(scene, camera));
composer.addPass(new UnrealBloomPass({ threshold: 0.8, strength: 1.5, radius: 0.4 }));
composer.addPass(new SSAOPass(scene, camera, { radius: 0.5, minDistance: 0.001, maxDistance: 0.1 }));

// Replace renderer.render() with:
function animate() {
  requestAnimationFrame(animate);
  composer.render();
}
animate();

Controls

Camera and object interaction — orbit, fly, pointer lock, drag, and first-person controls.

import { OrbitControls, FlyControls } from '@hyperbridge/forge/3d';

const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true;
controls.dampingFactor = 0.05;
controls.minDistance = 2;
controls.maxDistance = 50;
controls.target.set(0, 1, 0);

function animate() {
  requestAnimationFrame(animate);
  controls.update();
  renderer.render(scene, camera);
}

Particle Systems

CPU and GPU particle emitters with trail rendering and configurable force fields.

import { ParticleEmitter, GPUParticleSystem, TrailRenderer } from '@hyperbridge/forge/3d';

const emitter = new ParticleEmitter({
  maxParticles: 5000,
  rate: 200,
  lifetime: [1, 3],
  velocity: { x: [-1, 1], y: [2, 5], z: [-1, 1] },
  color: [0x6366f1, 0x22d3ee],
  size: [0.1, 0.5],
  gravity: -9.8,
});
scene.add(emitter);

const trail = new TrailRenderer({ width: 0.2, length: 20, color: 0x6366f1, fade: true });
trail.attach(movingObject);
scene.add(trail);

Raycaster & Helpers

import { Raycaster, AxesHelper, GridHelper } from '@hyperbridge/forge/3d';

scene.add(new AxesHelper(5));
scene.add(new GridHelper(20, 20));

const raycaster = new Raycaster();
canvas.addEventListener('click', (event) => {
  const x = (event.clientX / window.innerWidth) * 2 - 1;
  const y = -(event.clientY / window.innerHeight) * 2 + 1;
  raycaster.setFromCamera({ x, y }, camera);
  const hits = raycaster.intersectObjects(scene.children);
  if (hits.length > 0) console.log('Hit:', hits[0].object, 'at', hits[0].point);
});

Curves & Loaders

import { CatmullRomCurve3, Vec3, TextureLoader } from '@hyperbridge/forge/3d';

const curve = new CatmullRomCurve3([
  new Vec3(-5, 0, 0), new Vec3(-2, 3, 0),
  new Vec3(2, -1, 0), new Vec3(5, 2, 0)
]);
const points = curve.getPoints(50);  // 50 sample points along the spline

const texture = await new TextureLoader().load('/textures/brick.jpg');
const wall = new Mesh(
  new PlaneGeometry(10, 5),
  new StandardMaterial({ map: texture, roughness: 0.9 })
);

Key APIs

forge/display

Retina, 4K, and device capability detection with an adaptive quality tier system. Pixel-perfect canvas scaling, WebGL DPR setup, per-tier variant resolution, and deep integration with forge/3d, forge/animate, and forge/client. 60+ APIs. 955 lines. Zero dependencies.

Installation & Import

// Named import (tree-shakeable)
import Display from '@hyperbridge/forge/display';

// Or via the full bundle
import forge from '@hyperbridge/forge';
const Display = forge.Display;

Quality Tier & Scoring

Score breakdown

const tier  = Display.qualityTier();   // 'ultra'
const score = Display.qualityScore();  // 87
console.log(Display.profileString());
// "ultra|4k|p3|hdr|retina|2x|gpu:high|ram:16|cores:12|score:87"

Device Pixel Ratio

if (Display.is4K()) {
  loadTexture('/assets/hero@4x.webp');
} else if (Display.isRetina()) {
  loadTexture('/assets/hero@2x.webp');
} else {
  loadTexture('/assets/hero.webp');
}

Color Gamut & HDR

if (Display.colorGamut() === 'p3') {
  canvas.style.colorSpace = 'display-p3';
  ctx = canvas.getContext('2d', { colorSpace: 'display-p3' });
}

GPU Detection

const gpu = Display.getGPUInfo();
console.log(gpu.renderer); // "Apple M3 Pro"
console.log(gpu.tier);     // "high"
console.log(gpu.api);      // "webgl2"

Hardware: Memory & CPU

Network & Connection

Accessibility Preferences

Variant System

The variant system is the primary way to branch logic per tier. Pass a config map, get back the right value for the current device.

// Single value
const particles = Display.createVariant({ low: 50, medium: 500, high: 2000, ultra: 8000 });

// Full config object — the recommended pattern
const cfg = Display.createVariants({
  shadows:   { low: false,  medium: 'simple', high: 'pcf',  ultra: 'pcss' },
  particles: { low: 50,     medium: 500,       high: 2000,  ultra: 8000   },
  antialias: { low: false,  medium: false,     high: true,  ultra: true   },
  texSize:   { low: 512,    medium: 1024,      high: 2048,  ultra: 4096   },
});
// On a Retina MacBook Pro (ultra): { shadows:'pcss', particles:8000, antialias:true, texSize:4096 }
// On a budget Android phone (low):  { shadows:false,  particles:50,   antialias:false, texSize:512  }

Canvas Scaling (Pixel-Perfect)

const canvas = document.getElementById('chart');
const ctx    = canvas.getContext('2d');

// One call — pixel-perfect on Retina, 4K, anything
Display.scaleCanvas(canvas, ctx);
ctx.fillText('Crisp on every display', 10, 20);

// Auto re-scale when container resizes
const observer = Display.observeCanvas(canvas, ctx, ({ dpr, width, height }) => {
  redraw(); // your draw function
});
// cleanup: observer.disconnect()

WebGL Viewport Setup

const canvas = document.getElementById('scene');
const gl     = canvas.getContext('webgl2');

// Auto-caps DPR by tier — sharp but performant
Display.setupWebGLViewport(canvas, gl);

// Or pass into forge/3d renderer
import { createRenderer } from '@hyperbridge/forge/3d';
const renderer = createRenderer(canvas, { dpr: Display.get3DDPR() });

Adaptive Images

// Explicit variant map
const src = Display.adaptiveImageSrc('/img/hero.webp', {
  x2: '/img/hero@2x.webp',
  x3: '/img/hero@3x.webp',
  x4: '/img/hero@4x.webp',
});
img.src = src;

// Auto-generated srcset (derives @2x/@3x filenames)
img.srcset = Display.adaptiveSrcset('/img/banner.webp');
// → "/img/banner.webp 1x, /img/banner@2x.webp 2x, /img/banner@3x.webp 3x"

CSS Variable Injection

Call Display.injectCSS() once at app startup. It adds CSS custom properties and data-* attributes to <html> that you can use in stylesheets:

// app entry point
Display.injectCSS();

/* your stylesheet */
.hero-gradient {
  background: linear-gradient(135deg, oklch(70% 0.25 264), oklch(60% 0.3 310));
  animation-duration: calc(0.4s * var(--anim-scale));
}

[data-tier="low"] .hero-gradient { animation: none; }
[data-hdr="true"] .hero-gradient { /* wide-gamut override */ }
[data-retina="true"] .logo       { image-rendering: -webkit-optimize-contrast; }

forge/3d Integration

import { createRenderer } from '@hyperbridge/forge/3d';
import Display from '@hyperbridge/forge/display';

const cfg      = Display.get3DConfig();
const renderer = createRenderer(canvas, cfg);

/* cfg on ultra tier:
{
  antialias: true,  shadows: 'pcss',  shadowMapSize: 4096,
  textureMaxSize: 4096,  maxParticles: 20000,
  postFX: ['bloom','ssao','dof','ssr'],
  dpr: 2,  instanceLimit: 10000,  anisotropy: 16,  mipmap: true
}
cfg on low tier:
{
  antialias: false, shadows: false, shadowMapSize: 512,
  textureMaxSize: 512, maxParticles: 100,
  postFX: [], dpr: 1, instanceLimit: 100, anisotropy: 1, mipmap: false
} */

forge/animate Integration

import { animate } from '@hyperbridge/forge/animate';
import Display     from '@hyperbridge/forge/display';

const aCfg = Display.getAnimateConfig();

animate(el, { opacity: [0, 1], y: [20, 0] }, {
  duration:  aCfg.duration,
  stagger:   aCfg.stagger,
  easing:    aCfg.springs ? 'spring' : 'ease-out',
});

// On a low-end device: duration 0.15s, no parallax, no blur
// With reduced-motion: duration 0, instant resolve

forge/client Integration

Pixel-Perfect Utilities

// Hairline border — 0.5px on Retina, 1px on standard
el.style.borderWidth = Display.hairlineWidth() + 'px';

// Snap a shadow offset to physical pixels (no blurry sub-pixel shadows)
const offset = Display.snapToPhysical(8);
ctx.shadowOffsetX = offset;
ctx.shadowOffsetY = offset;

DPR Change Events

Fires when the user drags a window to a different monitor (e.g. from a Retina display to a standard external monitor).

const unsub = Display.onDPRChange(({ dpr, prev }) => {
  console.log(`DPR changed: ${prev} → ${dpr}`);
  Display.scaleCanvas(canvas, ctx);
  redraw();
});

Display.onTierChange(({ tier, prev }) => {
  console.log(`Tier: ${prev} → ${tier}`);
  Display.injectCSS({ force: true }); // re-inject CSS vars
  renderer.setPixelRatio(Display.get3DDPR());
});

Debug & Analytics

Display.logCapabilities();
// ─────────────────────────────────────────────────────
//   Quality tier    : ultra (87/100)
//   DPR             : 2 → clamped 2
//   Display         : 4K 3840×2160px
//   Color gamut     : p3 + HDR
//   GPU tier        : high (Apple M3 Pro)
//   WebGL 2         : true
//   RAM / CPU       : 16 GB / 12 cores
//   Connection      : 4g fast
//   Reduced motion  : false
// ─────────────────────────────────────────────────────

// Send to analytics
analytics.track('display_profile', { profile: Display.profileString() });

forge/prime

Web7 compliance bridge — DID-based identity, intent-first APIs, AMP envelope routing, Proof-of-Outcome, Vigil audit trail, and Kynetra Prime agent delegation. 1,200 lines. 32+ APIs. Three tiers: Lite (free) · Pro (hosted) · Enterprise (PoO + ZK-ML).

Installation

import { prime, vigil, KynetraPrime } from '@hyperbridge/forge/prime';

Tier Overview

KynetraPrime Constructor

Core API Reference

delegate() Options

Example: Lite — DID Login + Intent API

import { prime } from '@hyperbridge/forge/prime';
import { JWT }   from '@hyperbridge/forge/auth';

const p = new KynetraPrime({ token: process.env.KP_TOKEN, tier: 'lite' });

// DID login — no password, no session cookie
app.post('/auth/login', async (req, res) => {
  const { did, signature, nonce } = req.body;
  const ok = await p.identity.verify({ did, signature, nonce });
  if (!ok) return res.status(401).json({ error: 'invalid DID' });

  const token = JWT.sign(
    { sub: did, scope: ['read', 'delegate'] },
    { secret: process.env.JWT_SECRET, expiresIn: '8h' }
  );
  res.json({ token, did });
});

// Intent-first route — declare what the user wants
app.post('/generate-invoice', jwtMiddleware, async (req, res) => {
  const result = await p.delegate({
    from:   req.user.did,
    to:     'skill:generate-invoice',
    intent: { action: 'generate-invoice', params: req.body },
    budget: '5 USD',
    policy: 'org:acme:billing',
  });
  res.json({ ok: true, aig: result.aigNodeId });
});

// Well-known manifest
app.get('/.well-known/web7.json', (req, res) => res.json(p.manifest()));

Example: BYOA — Register Custom Agent

import { KynetraPrime } from '@hyperbridge/forge/prime';
import { Pool } from '@hyperbridge/forge/data';

const prime = new KynetraPrime({ token: process.env.KP_TOKEN });

// 1. Define your agent class
class InvoiceAgent {
  async run({ input, memory, model }) {
    const client = await memory.recall(input.clientId);
    const draft  = await model.generate('invoice-v1', client);
    return { invoice: draft, status: 'draft' };
  }
}

// 2. Register — gets full Prime infrastructure for free
prime.registerAgent('INVOICE', InvoiceAgent, {
  token:     { scope: ['invoices:write'] },
  telemetry: true,
  trainable: true,  // PRIME learns from every run
});

// 3. Run — identical API to built-in agents
const result = await prime.run('INVOICE', { clientId: 'c_123' });

Example: Pro — Hosted Prime + Vigil Audit

import { KynetraPrime, vigil } from '@hyperbridge/forge/prime';

const prime = new KynetraPrime({
  token:    process.env.KP_TOKEN,
  tier:     'pro',
  endpoint: 'https://prime.kynetra.ai',
  agents:   ['FORGE', 'SHIELD'],
});

// Delegate to a hosted agent with full audit trail
const result = await prime.delegate({
  from:   req.user.did,
  to:     'skill:ledger-close',
  intent: { action: 'ledger-close', params: { month: '2026-04' } },
  budget: '10 USD',
  policy: 'org:acme:finance',
});

// result.aigNodeId — committed AIG node (queryable)
console.log(result.aigNodeId);  // 'aig:abc123'

// Retrieve the full audit trace
const trace = await vigil.trace(result.intentId);
// Returns: intent → delegation → inference → outcome graph
// With all signatures, timestamps, model used, cost

// Export for internal audit
const blob = JSON.stringify(trace);

Example: Enterprise — Proof-of-Outcome + L0 Settlement

import { KynetraPrime, vigil } from '@hyperbridge/forge/prime';

const prime = new KynetraPrime({
  token: process.env.KP_TOKEN,
  tier:  'enterprise',
});

// Delegate with ZK-ML requirement + escrow settlement
const result = await prime.delegate({
  from:    req.user.did,
  to:      'skill:tax-filing',
  intent:  { action: 'file-tax', params: req.body, constraints: { jurisdiction: 'IN' } },
  budget:  '50 USD',
  policy:  'org:acme:compliance',
  settle:  { rail: 'amp-outcome' },  // pay only on verified success
  require: { zkml: true },           // demand ZK-ML proof of inference
});

// Verify PoO before trusting the result
const poo = await prime.poo.verify({
  intentId: result.intentId,
  agentDid: result.agentDid,
  outcome:  result.outcome,
});

if (!poo.verified) throw new Error('PoO failed — do not settle');

// Trigger L0 settlement (funds released from escrow to agent)
const settlement = await prime.settle(result.intentId, 'amp-outcome');
console.log(settlement.status);   // 'settled'
console.log(settlement.receipt);  // signed receipt (self-verifying)

// Export audit blob for regulator
const auditBlob = await vigil.export(result.intentId);
// Self-verifying: contains all sigs + ZK-ML proof + L0 anchor hash

Web7 Conformance Checklist

// Run local conformance check (Lite tier)
const report = await prime.conform();
// {
//   did_token_auth:    true,   // JWT sub is a DID
//   intent_first_api:  true,   // at least one prime.delegate() call
//   amp_envelope:      true,   // AMP message format valid
//   well_known:        true,   // /.well-known/web7.json accessible
//   vigil_logging:     true,   // at least one vigil.record() call
//   budget_caps:       true,   // all delegations have budget set
//   byoa_registered:   true,   // custom agents registered
//   poo_verified:      false,  // Enterprise only
//   zkml_proofs:       false,  // Enterprise only
//   l0_settlement:     false,  // Enterprise only
// }

// Full conformance suite (Enterprise — run in CI)
// w7 test conformance --endpoint https://my-app.com

forge/wasm Web7 ✦

Universal WebAssembly loader. forge/wasm is how HBForge apps instantiate KYRx (L1 settlement) and ClearScript (L5 contract) modules, plus any other WASM payload — with zero external tooling (no wabt, no wasm-bindgen, no wasmtime).

Installation

import {
  loadModule, loadStreaming,
  MemoryManager, WorkerPool,
  WASIBridge, HostImports,
  parseWasm, validateWasm,
  hotReload, typeBridge
} from '@hyperbridge/forge/wasm';

What it does

• Module loading — loadModule(bytes) / loadStreaming(url) with caching and streaming compilation.
• Memory manager — typed-array views on linear memory, bounds-checked read/write helpers.
• WASI-lite — enough of the WASI filesystem/stdio API to run Rust or AssemblyScript compiled output.
• Worker pool — run heavy WASM workloads off the main thread with transferable memory buffers.
• Host imports — preconfigured namespaces for web7/prime, vigil (audit trail), auth, amp (agent mesh).
• Hot-reload — development-only module swap without losing app state.
• Type bridge — automatic conversion between JS and WASM primitives; stringRef, arrayBuffer, bigint, struct layouts.
• Parser / validator — LEB128 varint decode of WASM sections (via _internal/binary); catches malformed payloads before instantiation.

Example

// Load a Rust-compiled KYRx module and call its exports
const bytes = await fetch('/kyrx.wasm').then(r => r.arrayBuffer());
const mod   = await loadModule(bytes, {
  imports: HostImports.web7Prime({ did: 'did:hb:42' })
});

const balance = mod.exports.balance_of('0xabc');
console.log('KYRx balance:', balance);

// Long-running compute? Move it to a worker
const pool = new WorkerPool({ size: 4, module: bytes });
const results = await pool.runAll(inputs, 'process');

forge/memory Web7 ✦ new in v4.1.0

Scoped agent memory store. Four nested scopes — task → session → principal → global — with fall-through reads, TTL sweep, trigram search, and snapshot/restore. Implements the Web7 L6 agent memory primitive.

Installation

import { MemoryStore, SCOPES } from '@hyperbridge/forge/memory';

What it does

• Four scopes — global (app-wide), principal (per DID / user), session (per sign-in), task (per agent run).
• Fall-through reads — get(principal, key) looks in task first, then session, then principal, then global. Write to a scope, read it from a narrower one.
• TTL sweep — set a per-key TTL; sweep() garbage-collects expired entries.
• Trigram search — search(q) ranks stored keys/values by Jaccard similarity, no vector store needed.
• Promote / snapshot — lift a value up a scope (promote('task'→'session')), or serialize the whole store for persistence.

Example

const mem = new MemoryStore();

// Global knowledge
mem.set(null, 'org-name', 'HyperBridge Digital', { scope: 'global' });

// Per-principal preference
mem.set('did:w7:alice', 'lang', 'en-IN', { scope: 'principal' });

// Per-task scratch with 5-min TTL
mem.set('did:w7:alice', 'draft', 'reply-text',
  { scope: 'task', taskId: 'run-42', ttlMs: 300_000 });

// Read falls through: task → session → principal → global
mem.get('did:w7:alice', 'org-name', { taskId: 'run-42' });
// → 'HyperBridge Digital'  (resolved from global)

// Cleanup
mem.sweep();
const blob = mem.snapshot();   // serializable

forge/consent Web7 ✦ new in v4.1.0

Hash-chained, tamper-evident consent ledger. GDPR-aligned purposes, grant / revoke / amend / query verbs, isPermitted() checks, daily Merkle roots. Implements the Web7 L6 consent primitive.

Installation

import { ConsentLedger, ConsentGrant, PURPOSES, checkConsent }
  from '@hyperbridge/forge/consent';

Standard purposes

GDPR-aligned PURPOSES enum covers the common lawful bases:

• NECESSARY — strictly required for service delivery.
• CONSENT — generic opt-in.
• MODEL_TRAIN — user content may be used to train models.
• MODEL_INFER — user content may be sent to a model at inference time.
• ANALYTICS, MARKETING, PERSONALIZATION, PROFILING, THIRD_PARTY_SHARE, CROSS_BORDER.

Example

const ledger = new ConsentLedger();

// Grant consent for inference with a 90-day expiry
ledger.grant({
  principal: 'did:w7:alice',
  processor: 'did:w7:hbforge-ai',
  purpose:   PURPOSES.MODEL_INFER,
  scope:     ['chat', 'support'],
  expiresAt: Date.now() + 90 * 86_400_000,
});

// Before calling the model, check
if (!ledger.isPermitted({
      principal: 'did:w7:alice',
      processor: 'did:w7:hbforge-ai',
      purpose:   PURPOSES.MODEL_INFER,
      scope:     'chat',
    })) {
  throw new Error('Consent not granted');
}

// Revoke is a ledger append — never a delete
ledger.revoke({
  principal: 'did:w7:alice',
  processor: 'did:w7:hbforge-ai',
  purpose:   PURPOSES.MODEL_INFER,
});

// Tamper-evidence: every entry chains a SHA-256 of the previous head
const head = ledger.chainHead();
const ok   = ledger.verify();        // re-walks + re-hashes the whole chain
const days = ledger.dailyRoots();    // Merkle root per UTC day for external anchoring

forge/provenance Web7 ✦ new in v4.1.0

C2PA 2.0 style content provenance. Signed assertion boxes (c2pa.* + w7.* labels), parent manifests, selective disclosure. Implements the Web7 L6 provenance primitive and pairs with forge/zkml for model-output manifests.

Installation

import { Manifest, Assertion, LABELS, buildInferenceManifest }
  from '@hyperbridge/forge/provenance';

What it does

• Manifests — an ordered list of signed assertion boxes with a final seal over the whole manifest.
• Assertions — labelled records (c2pa.hash.data, c2pa.actions, w7.inference, w7.attestation, …) individually signed with HMAC-SHA-256.
• Parent linkage — a new manifest can reference a prior manifest's hash, chaining provenance across edits.
• Selective disclosure — manifest.select([labels]) returns a compact manifest exposing only chosen assertions while keeping the seal valid.
• Inference helper — buildInferenceManifest({ model, inputHash, outputHash, attestations }) constructs a ready-to-sign Web7 inference manifest in one call.

Example

const m = new Manifest({ issuer: 'did:w7:hbforge' });

m.addAssertion(new Assertion({
  label: LABELS.C2PA_HASH_DATA,
  data:  { algo: 'sha256', value: '0x7f12…' },
}));

m.addAssertion(new Assertion({
  label: LABELS.W7_INFERENCE,
  data:  { model: 'gpt-local-7b', inputHash: '0xaa…', outputHash: '0xbb…' },
}));

m.linkParent('0xparent-manifest-hash');
const sealed = m.seal(secretKey);

// Selective disclosure: share hash + inference, hide other boxes
const trimmed = sealed.select([LABELS.C2PA_HASH_DATA, LABELS.W7_INFERENCE]);
trimmed.verify(publicKey);           // still valid

const wire = sealed.toJSON();
const back = Manifest.fromJSON(wire);

forge/zkml Web7 ✦ new in v4.1.0

ZK-ML multi-attestor MVP — M-of-N threshold attestations over (model, inputHash, outputHash) tuples. Swappable proof backend via registerProofBackend() so you can drop in a real SNARK/STARK later without changing callers. Implements the Web7 L6 zk-ml primitive.

Installation

import {
  ZKMLClaim, Attestor, AttestationBundle,
  verifyBundle, collectAttestations,
  registerProofBackend, getProofBackend,
} from '@hyperbridge/forge/zkml';

Why multi-attestor, not a proof

A cryptographic zero-knowledge proof of ML inference is research-grade today — slow, costly, and model-shape-specific. A multi-attestor bundle is the deployable approximation: N independent operators (you + partners + third-party auditors) each attest to having observed the same (inputHash → outputHash) transition; a client accepts if M-of-N signatures verify. When real SNARK backends become practical, register one via registerProofBackend() and callers switch over transparently.

Example

const claim = new ZKMLClaim({
  model:      'gpt-local-7b',
  inputHash:  '0xaa…',
  outputHash: '0xbb…',
});

// Three independent attestors (each with its own HMAC key)
const attestors = [
  new Attestor({ id: 'att-1', secret: s1 }),
  new Attestor({ id: 'att-2', secret: s2 }),
  new Attestor({ id: 'att-3', secret: s3 }),
];

// Require 2-of-3 threshold
const bundle = await collectAttestations(claim, attestors, { threshold: 2 });

// Anyone with the attestor pubkeys (here: HMAC secrets) can verify
const res = verifyBundle(bundle, { 'att-1': s1, 'att-2': s2, 'att-3': s3 });
// → { ok: true, threshold: 2, signed: 3 }

// Later: swap in a SNARK backend
registerProofBackend('groth16', { prove, verify });
const be = getProofBackend('groth16');

forge/conformance Web7 ✦ new in v4.1.0

Web7-L6 conformance suite v1.0.0. 30 tests across 12 categories. Runs in ~8 ms. Grade AAA / AA / A / B / C / FAIL. Zero deps.

Installation

import { runConformance, formatReport, SUITE_VERSION, CATEGORIES }
  from '@hyperbridge/forge/conformance';

const report = await runConformance();
console.log(formatReport(report));

Coverage

Grading

• AAA — ≥98% (≥29/30)
• AA — ≥95% (≥28/30)
• A — ≥90% (≥27/30)
• B — ≥80%
• C — ≥70%
• FAIL — below 70%

Current baseline for @hyperbridge/forge@4.2.2: AAA · 30 / 30 · ~8 ms · 0 deps.

Example report

Web7-L6 Conformance v1.0.0 — @hyperbridge/forge@4.2.2
────────────────────────────────────────────────────────
identity       ██████████  4/4
amp            ██████████  6/6
aig            ██████████  2/2
poo            ██████████  2/2
settlement     ██████████  3/3
consent        ██████████  2/2
provenance     ██████████  2/2
zkml           ██████████  2/2
memory         ██████████  3/3
reputation     ██████████  2/2
revocation     ██████████  1/1
negotiation    ██████████  1/1
────────────────────────────────────────────────────────
TOTAL          30 / 30  (100.0%)   Grade: AAA   8 ms

forge/policy ✦ new in v4.2.2

OPA-style declarative policy engine — evaluate rule sets, gate HTTP handlers, enforce jurisdiction / budget / data-class / reputation constraints with zero deps. Web7 L6 ambient-authority primitive.

Installation

import {
  PolicyEngine, PolicySet, PolicyRule,
  PolicyDeniedError, policyGate, buildStandardSet,
  EFFECT, COMBINER, getPolicy,
} from '@hyperbridge/forge/policy';

Concepts

Combiners

Example — HTTP gate

import { getPolicy, buildStandardSet, policyGate } from '@hyperbridge/forge/policy';
import { createServer } from '@hyperbridge/forge/server';

const engine = getPolicy();

// Register a policy set for the /pay endpoint
buildStandardSet('pay-policy', {
  allowedJurisdictions: ['US', 'EU', 'IN'],
  maxBudget:            500,
  allowedDataClasses:   ['financial'],
  minReputation:        0.6,
  maxRiskTier:          2,
}, engine);

const server = createServer();

server.use(policyGate(engine, ctx => ({
  setId:        'pay-policy',
  jurisdiction: ctx.headers['x-jurisdiction'] ?? 'US',
  budget:       Number(ctx.headers['x-budget'] ?? 0),
  dataClass:    ctx.headers['x-data-class'] ?? 'public',
  reputation:   Number(ctx.headers['x-reputation'] ?? 1),
  riskTier:     Number(ctx.headers['x-risk-tier'] ?? 0),
})));

server.post('/pay', async ctx => {
  // ctx.policy → { effect: 'allow', reasons: [...] }
  ctx.body = { ok: true };
});

server.listen(3000);

Custom rules

const set = new PolicySet('custom', { combiner: 'deny-overrides', defaultEffect: EFFECT.ALLOW });

set.addRule(new PolicyRule({
  id:     'no-weekend-writes',
  type:   'custom',
  effect: EFFECT.DENY,
  params: { fn: ctx => new Date().getDay() % 6 === 0 && ctx.method === 'write' },
  reason: 'Write operations disabled on weekends',
}));

engine.addSet(set);
const result = engine.evaluate({ method: 'write' }, 'custom');
// → { effect: 'deny', reasons: ['Write operations disabled on weekends'] }

forge/trace ✦ new in v4.2.2

OpenTelemetry-compatible distributed tracing — W3C Trace Context, Span/Tracer/TraceProvider, OTLP/HTTP export, Jaeger/Grafana/Vigil integration. Zero external deps.

Installation

import {
  TraceProvider, TraceContext, Span, Tracer,
  ConsoleExporter, JsonLineExporter, OtlpHttpExporter, VigilExporter,
  traceMiddleware, tracePrime,
  getProvider, setProvider, getTracer,
  SpanStatus, SpanKind,
} from '@hyperbridge/forge/trace';

Exporters

Quick start

import { getProvider, getTracer, OtlpHttpExporter } from '@hyperbridge/forge/trace';
import { createServer } from '@hyperbridge/forge/server';
import { traceMiddleware } from '@hyperbridge/forge/trace';

// Wire up an OTLP exporter (Grafana Cloud / Jaeger)
getProvider().addExporter(new OtlpHttpExporter(
  'http://localhost:4318/v1/traces',
  { Authorization: 'Bearer ' }
));

const tracer = getTracer('my-app', '1.0.0');
const server = createServer();

// Reads W3C traceparent from requests, propagates it downstream
server.use(traceMiddleware(tracer));

server.get('/users/:id', async ctx => {
  await tracer.trace('db.getUser', async span => {
    span.setAttribute('db.user_id', ctx.params.id);
    ctx.body = await db.getUser(ctx.params.id);
  });
});

Manual spans

const span = tracer.startSpan('payment.process', {
  kind: SpanKind.CLIENT,
  attributes: { 'payment.amount': 99.99, 'payment.currency': 'USD' },
});

try {
  const result = await stripe.charge({ amount: 9999 });
  span.addEvent('charge.created', { id: result.id });
  span.ok();
  return result;
} catch (err) {
  span.error(err.message);
  throw err;
} finally {
  span.end();
}

W3C Trace Context

// Parse incoming traceparent header
const ctx = TraceContext.fromTraceparent(req.headers['traceparent']);
// → TraceContext { traceId: '4bf92f3577b34da6...', spanId: 'a2fb4a1d...', sampled: true }

// Serialise for outgoing calls
const childCtx = ctx.child();
outboundHeaders['traceparent'] = childCtx.toTraceparent();
// → '00-4bf92f3577b34da6...-newSpanId-01'

forge/replay ✦ new in v4.2.2

Time-travel debugger for HTTP + database layers. Record every request and query into a deterministic NDJSON tape; replay it identically without touching live services. Zero deps.

Installation

import {
  RecordingSession, ReplaySession, Tape, TraceEvent, EVENT,
  httpRecorder, dbRecorder,
  httpReplayer, dbReplayer,
  replayAll, diffTapes,
} from '@hyperbridge/forge/replay';

Architecture

Record a session

import { RecordingSession, httpRecorder, dbRecorder } from '@hyperbridge/forge/replay';
import { createServer } from '@hyperbridge/forge/server';
import { Pool } from '@hyperbridge/forge/data';

const pool = new Pool({ connectionString: process.env.DB_URL });
const session = new RecordingSession({ label: 'checkout-flow' });

const server = createServer();
server.use(httpRecorder(session));  // record HTTP layer

// Wrap pool — all queries are recorded transparently
const recordedPool = dbRecorder(pool, session);

server.post('/checkout', async ctx => {
  const items = await recordedPool.query('SELECT * FROM cart WHERE user_id = $1', [ctx.user.id]);
  ctx.body = { items: items.rows };
});

await server.listen(3000);
// After your test scenario runs:
const tape = session.stop();
await tape.save('./fixtures/checkout.ndjson');

Replay without live services

import { Tape, replayAll } from '@hyperbridge/forge/replay';

const tape = await Tape.load('./fixtures/checkout.ndjson');

const { results, stats } = await replayAll(tape, async (mockPool, mockHttp, requests) => {
  // mockPool.query() returns recorded rows — no database
  const items = await mockPool.query('SELECT * FROM cart WHERE user_id = $1', ['user-123']);
  return items.rows;
});

console.log(stats);
// → { total: 4, counts: { 'http:req': 1, 'http:res': 1, 'db:query': 1, 'db:result': 1 }, duration: 42 }

Regression diff

import { diffTapes, Tape } from '@hyperbridge/forge/replay';

const baseline  = await Tape.load('./fixtures/checkout-v1.ndjson');
const candidate = await Tape.load('./fixtures/checkout-v2.ndjson');

const { hasDiff, diffs } = diffTapes(baseline, candidate);
if (hasDiff) {
  console.error('Regression detected:', diffs);
  process.exit(1);
}

forge/simulator ✦ new in v4.2.2

In-process agent-mesh scenario simulator — simulate slashing, escrow unwind, SLA breach, reputation cascade, and double-spend scenarios without touching live infrastructure. Six built-in scenarios; fully composable.

Installation

import {
  Simulator, SimAgent, SimEscrow, SimResult,
  happyPath, agentSlashed, slaBreached,
  reputationCascade, escrowUnwind, doubleSpend,
  runSuite,
} from '@hyperbridge/forge/simulator';

Built-in scenarios

Run the full suite

import { runSuite } from '@hyperbridge/forge/simulator';

const results = await runSuite({
  agentStake:   1000,
  escrowAmount: 500,
  slaDurationMs: 60_000,
  slashPenalty: 0.2,     // 20% of stake per infraction
});

for (const r of results) {
  console.log(r.summary());
}
// happyPath          ✓  3 assertions  0 failures
// agentSlashed       ✓  4 assertions  0 failures
// slaBreached        ✓  3 assertions  0 failures
// reputationCascade  ✓  5 assertions  0 failures
// escrowUnwind       ✓  2 assertions  0 failures
// doubleSpend        ✓  2 assertions  0 failures

Custom scenario

import { Simulator } from '@hyperbridge/forge/simulator';

const sim = new Simulator({ slashPenalty: 0.15 });
const agent = sim.addAgent('provider-1', { stake: 800, reputation: 90 });
const escrow = sim.createEscrow('req-1', agent.did, 300, { slaDurationMs: 5_000 });

const result = await sim.run('partial-delivery', async () => {
  // Agent delivers late — partial payout at 50%
  const { payout, refund } = escrow.release(0.5);
  sim.assert('partial payout correct', payout === 150);
  sim.assert('remaining refunded',     refund === 150);

  agent.earn(payout);
  sim.assert('balance updated', agent.balance === payout);
});

console.log(result.summary());
// partial-delivery  ✓  3 assertions  0 failures

SimAgent API

agent.slash('badZkml');           // reduces reputation, emits slash event
agent.earn(amount);               // increases balance
agent.reputation;                 // 0–100 score
agent.balance;                    // current token balance
agent.did;                        // 'did:w7:provider-1'
agent.behaviour;                  // 'honest' | 'lazy' | 'malicious'

forge/_internal Shared Primitives

Three tiny modules that host the primitives several other modules used to reinvent — cryptography, byte-level encoding, and timing. The underscore prefix is advisory: signatures are stable, internals may improve between minor versions.

_internal/crypto

import {
  hmacSha256, hmacSha256Async,
  sha256, sha256Async,
  timingSafeEqual,
  randomBytes, randomId,
  toHex, fromHex, toBase64, fromBase64
} from '@hyperbridge/forge/_internal/crypto';

// Node: sync, backed by node:crypto
const sig = hmacSha256('secret', 'payload');         // hex
const mac = hmacSha256('secret', 'payload', { encoding: 'base64' });

// Browser: use async variant (WebCrypto is async-only)
const sig = await hmacSha256Async('secret', 'payload');

// Timing-safe compare — constant-time even in the fallback
timingSafeEqual(expectedSig, receivedSig);

// Cryptographically-random IDs
const id = randomId(16);  // 32-char hex string

_internal/binary

import {
  encodeUtf8, decodeUtf8,
  readULEB128, writeULEB128, readSLEB128,
  concatBytes,
  readCStr, writeCStr
} from '@hyperbridge/forge/_internal/binary';

// UTF-8 with TextEncoder/TextDecoder when present, manual fallback otherwise
const bytes = encodeUtf8('héllo 🌍');
const str   = decodeUtf8(bytes);

// LEB128 varints — used by the WASM parser
const { value, nextOffset } = readULEB128(bytes, 0);
const encoded = writeULEB128(624485);

// Concatenate chunks without the BufferList overhead
const all = concatBytes([header, body, footer]);

_internal/time

import {
  now, nowNs,
  parseDuration, formatDuration,
  sleep, withTimeout
} from '@hyperbridge/forge/_internal/time';

// Monotonic clock — performance.now() with Date.now fallback
const t0 = now();
await doWork();
const elapsed = now() - t0;
console.log(formatDuration(elapsed));  // "1.23 s"

// Parse human-readable durations
parseDuration('1h30m');    // → 5_400_000
parseDuration('500ms');    // → 500
parseDuration('7d');       // → 604_800_000

// Deadline-bounded promise race
const result = await withTimeout(fetch(url), 3000, 'fetch');
// → rejects with "withTimeout: fetch exceeded 3000ms" on overrun

Who uses what

Bundle Size

HBForge ships dual CJS + ESM, with 1,400+ named exports, deep subpath imports, browser/Node conditional exports, and a sideEffects: false declaration — so modern bundlers can cut the tree aggressively.

Five phases of splitting

Versions 3.4.0 → 3.4.4 were a phased rollout, each shipped independently so apps can adopt incrementally. Full release notes →

What a typical app imports

// ❌ Pre-3.4: pulls everything from forge root
import forge from '@hyperbridge/forge';
forge.signal(0);

// ✅ Subpath: pulls one module
import { signal } from '@hyperbridge/forge/client';

// ✅✅ Deep path: pulls one export
import { signal } from '@hyperbridge/forge/client/signal';

// ✅ Browser-side Next.js page: mail/pdf/cli/test/server auto-stub
import { sendMail } from '@hyperbridge/forge/mail';   // → 1.4 KB stub in browser bundle
// (same code in a Node API route pulls the full 223 KB implementation)

Bundler compatibility

• Rollup / Vite / esbuild / Webpack 5+ / Parcel 2+ — honour sideEffects, conditional exports, and wildcard subpaths. Full benefit.
• Next.js 13+ / SvelteKit / Remix / Astro — set platform: "browser" on client bundles. Phase 4 browser stubs apply automatically.
• Webpack 4 — reads sideEffects, ignores conditional exports. Subpath imports still work via main.
• Node 18+ — native conditional exports, deep paths, and import / require both honoured.