npm package: @synheart.ai/behavior-web
Description: Browser behavior collection for Synheart Adaptive UI - captures DOM events and emits windowed sessions
Author: Synheart.ai
Latest version: 0.1.0

# @synheart/behavior-web

Browser behavior collection for Synheart Adaptive UI - captures DOM events and emits windowed sessions compatible with the Flux processing pipeline.

## Installation

```bash
npm install @synheart/behavior-web
```

## Quick Start

```typescript
import { BehaviorCollector } from '@synheart/behavior-web';

const collector = new BehaviorCollector();

collector.on('session', (session) => {
  console.log('Session:', session);
  // Send to WASM engine, API, analytics, etc.
});

collector.start();

// Later...
collector.stop();
```

## Usage

### Basic Usage

```typescript
import { BehaviorCollector } from '@synheart/behavior-web';

const collector = new BehaviorCollector();

// Subscribe to session events
collector.on('session', (session) => {
  console.log('Session ID:', session.session_id);
  console.log('Events:', session.events.length);
});

// Start collecting DOM events
collector.start();

// Manually flush current buffer
collector.flush();

// Stop collecting
collector.stop();
```

### With Configuration

```typescript
import { BehaviorCollector } from '@synheart/behavior-web';

const collector = new BehaviorCollector({
  pipeline: {
    bufferSize: 50,      // Max events before auto-flush
    windowMs: 30000,     // Session window duration (30 seconds)
    idleThresholdMs: 5000, // Gap detection threshold
  },
  deviceId: 'custom-device-id', // Optional custom device ID
  persistDeviceId: true,         // Persist device ID to localStorage
});

collector.on('session', (session) => {
  // Handle session
});

collector.start();
```

### With @synheart/adapt-core-ts

For full adaptive UI functionality, use with the adapt-core-ts SDK:

```typescript
import { createSynheartClient } from '@synheart/adapt-core-ts';

const client = await createSynheartClient({
  onDecision: (decision) => {
    console.log('Mode:', decision.mode);
    applyUIAdaptations(decision.axes);
  }
});

client.startAutoMode();
```

### React Integration

```tsx
import { useEffect } from 'react';
import { BehaviorCollector, BehaviorSession } from '@synheart/behavior-web';

export function BehaviorProvider({ onSession }: { onSession: (s: BehaviorSession) => void }) {
  useEffect(() => {
    const collector = new BehaviorCollector();
    collector.on('session', onSession);
    collector.start();
    
    return () => collector.stop();
  }, [onSession]);

  return null;
}
```

### Next.js Integration

```tsx
// app/providers.tsx
"use client";

import { useEffect } from "react";
import { BehaviorCollector } from "@synheart/behavior-web";

export default function Providers({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    const collector = new BehaviorCollector();
    
    collector.on('session', (session) => {
      // Handle session - send to API, process locally, etc.
      console.log('Session:', session);
    });
    
    collector.start();
    
    return () => collector.stop();
  }, []);

  return <>{children}</>;
}
```

## API Reference

### BehaviorCollector

| Method | Description |
|--------|-------------|
| `new BehaviorCollector(options?)` | Create a new collector instance |
| `start()` | Start collecting DOM events |
| `stop()` | Stop collecting and flush remaining events |
| `flush()` | Manually flush current buffer as a session |
| `on(event, listener)` | Subscribe to events ('session' or 'error') |
| `off(event, listener)` | Unsubscribe from events |
| `getDeviceId()` | Get the browser device ID |
| `getStartedAt()` | Get the creation timestamp |
| `running` | Check if collector is running (getter) |

### BehaviorCollectorOptions

```typescript
interface BehaviorCollectorOptions {
  pipeline?: {
    bufferSize?: number;     // Max events before auto-flush (default: 50)
    windowMs?: number;       // Session window in ms (default: 30000)
    idleThresholdMs?: number; // Idle detection in ms (default: 5000)
  };
  deviceId?: string;         // Custom device ID
  persistDeviceId?: boolean; // Persist to localStorage (default: true)
}
```

### BehaviorSession Output

```typescript
interface BehaviorSession {
  session_id: string;   // Unique session identifier
  device_id: string;    // Browser device ID
  timezone: string;     // IANA timezone (e.g., "America/New_York")
  start_time: string;   // ISO8601 session start
  end_time: string;     // ISO8601 session end
  events: BehaviorEvent[]; // Collected events
}
```

## Collected Events

| DOM Event | Mapped To | Description |
|-----------|-----------|-------------|
| `click` | `tap` | Mouse clicks and taps |
| `scroll` | `scroll` | Scroll with direction tracking |
| `keydown` | `typing` | Keyboard input |
| `visibilitychange` | `app_switch` | Tab visibility changes |
| `focus`/`blur` | `app_switch` | Window focus changes |
| `selectionchange` | `tap` | Text selection |
| `copy`/`cut`/`paste` | (filtered) | Clipboard operations |

## Privacy

- All data stays in the browser
- No network requests
- Device ID stored locally (configurable)
- No PII collected - only interaction patterns

## Related Packages

| Package | Description |
|---------|-------------|
| [@synheart/adapt-core-ts](https://github.com/synheart/synheart-adapt-core-ts) | Full adaptive UI SDK with WASM policy engine |

## License

Apache-2.0 - See [LICENSE](LICENSE) for details.

Copyright 2026 SynHeart AI Inc