@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

$3

`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();
`

$3

`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();
`

$3

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();
`

$3

`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;
}
`

$3

`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

$3

| 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) |

$3

`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)
}
`

$3

`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 | Full adaptive UI SDK with WASM policy engine |

License

Apache-2.0 - See LICENSE for details.

Copyright 2026 SynHeart AI Inc