@synheart/behavior-web

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

Installation

npm install @synheart/behavior-web

Quick Start

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

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

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:

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

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

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

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

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