npm package: @synheart.ai/adapt-core-ts
Description: Browser SDK for Synheart Adaptive UI - on-device human state inference using WASM
Author: Synheart.ai
Latest version: 0.1.1

# @synheart.ai/adapt-core-ts

Browser SDK for Synheart Adaptive UI - on-device human state inference using WebAssembly.

## Features

- **On-device processing** - All computation happens locally via WASM, no data leaves the browser
- **Automatic behavior collection** - Uses `@synheart.ai/behavior-web` to capture scroll, click, typing, and other browser events
- **Adaptive UI modes** - Returns `calm`, `guided`, `focused`, or `power` mode recommendations
- **Type-safe** - Full TypeScript support with typed configuration
- **Framework agnostic** - Works with React, Vue, Next.js, or vanilla JavaScript

## Installation

```bash
npm install @synheart.ai/adapt-core-ts
```

## Quick Start

```typescript
import { createSynheartClient } from '@synheart.ai/adapt-core-ts';

// Behavior-only optimized config (recommended for browser use)
const client = await createSynheartClient({
  engineConfig: {
    confidence: { min_score_confidence: 0.25 },
    thresholds: { high_load: 0.6, high_attention: 0.7 },
    stability: { dwell_time_ms: 30000, max_switches_per_hour: 12 }
  },
  onDecision: (decision) => {
    console.log('Mode:', decision.mode);        // 'calm' | 'guided' | 'focused' | 'power'
    console.log('Axes:', decision.axes);        // density, motion, interruptibility, etc.
    console.log('Notifications:', decision.notification_budget); // per hour
  },
});

// Start automatic behavior collection and processing
client.startAutoMode();

// Later: clean up
client.terminate();
```

## API Overview

### `createSynheartClient(options)`

Creates and initializes the SDK client.

**Options:**
- `engineConfig` - Engine configuration object (see below)
- `wasmUrl` - Custom WASM module URL (auto-detected by default)
- `autoModeIntervalMs` - Processing interval in ms (default: 500)
- `onDecision` - Callback when a new decision is made
- `onError` - Callback on errors

### `client.startAutoMode()`

Starts automatic behavior collection and periodic processing.

### `client.stopAutoMode()`

Stops automatic collection.

### `client.applyOverride(mode)`

Manually override to a specific mode: `'calm'`, `'guided'`, `'focused'`, or `'power'`.

### `client.terminate()`

Clean up resources and terminate the worker.

## Engine Configuration

```typescript
interface EngineConfig {
  confidence?: {
    min_score_confidence?: number;  // Default: 0.5, use 0.25 for behavior-only
  };
  thresholds?: {
    high_load?: number;      // Stress threshold (default: 0.7)
    low_readiness?: number;  // Fatigue threshold (default: 0.3)
    high_attention?: number; // Focus threshold (default: 0.8)
    low_attention?: number;  // Distraction threshold (default: 0.3)
  };
  stability?: {
    dwell_time_ms?: number;          // Min time in mode (default: 300000 = 5min)
    max_switches_per_hour?: number;  // Rate limit (default: 3)
    hysteresis_threshold?: number;   // Change sensitivity (default: 0.1)
  };
}
```

## Policy Decision Output

```typescript
interface PolicyDecision {
  mode: 'calm' | 'guided' | 'focused' | 'power';
  axes: {
    density: 'compact' | 'normal' | 'spacious';
    motion: 'reduced' | 'normal' | 'full';
    interruptibility: 'none' | 'important' | 'normal' | 'all';
    assistance: 'minimal' | 'normal' | 'proactive';
    input_effort: 'minimal' | 'normal' | 'full';
  };
  notification_budget: number;  // Notifications per hour
  confidence: 'low' | 'medium' | 'high';
  reasons: string[];            // Why this decision was made
}
```

## Framework Examples

See the `examples/` directory for:
- **React** - Hooks and context provider
- **Vue** - Composables
- **Next.js** - App router integration
- **Vanilla JS** - No framework

## Full Documentation

See [FRONTEND_INTEGRATION_GUIDE.md](../FRONTEND_INTEGRATION_GUIDE.md) for complete integration instructions.

## License

Apache-2.0