SAUI

Synheart Adaptive UI (SAUI) is a lightweight React-first toolkit for building adaptive interfaces. It provides:

• A tiny rule engine to compute UI output based on a viewer state
• React hooks and provider to apply those rules in components
• A controls UI (optional) used by the Better YouTube frontend

Installation

Local workspace example:

npm install

If you publish this package, install it normally:

npm install @synheart/saui

Exports

• @synheart/saui -> core types
• @synheart/saui/core -> rule engine utilities
• @synheart/saui/react -> React provider + hooks
• @synheart/saui/controls -> demo controls UI
• @synheart/saui/synheart -> Synheart client hook (WASM)
• @synheart/saui/utils -> cn helper

Quick start

Create your own rules and outputs (app-specific):

import { buildRules, baseOutput, type ViewerState, type YouTubeOutput } from "@/lib/adaptive-ui"

Wrap your app with SAUIProvider:

import { SAUIProvider } from "@synheart/saui/react"

<SAUIProvider state={viewerState} rules={buildRules()} baseOutput={baseOutput}>
  {children}
</SAUIProvider>

Consume outputs in components:

import { useAdaptation } from "@synheart/saui/react"
import type { ViewerState, YouTubeOutput } from "@synheart/saui"

const { output, appliedRules } = useAdaptation<YouTubeOutput, ViewerState>()

Optional controls (provide your own presets + metrics):

import { AdaptiveControls } from "@synheart/saui/react"

<AdaptiveControls
  state={viewerState}
  stateMetrics={[
    { label: "Focus", key: "focus" },
    { label: "Stress", key: "stress" },
  ]}
  presets={viewerPresets}
  activePreset={activePreset}
  isAuto={isAuto}
  autoLabel={autoLabel}
  isMenuOpen={isPresetMenuOpen}
  appliedRules={appliedRules}
  onToggleMenu={toggleMenu}
  onToggleAuto={toggleAuto}
  onSelectPreset={selectPreset}
/>

Core concepts

• ViewerState describes the user context (focus, stress, time, etc.).
• Rules (AdaptiveRule) decide how UI output should change.
• SAUIProvider holds the current state and computes outputs.
• Hooks (useAdaptation, useAdaptiveOutput) expose the computed output.

Notes

• Your app owns the viewer state + rules config (example: lib/adaptive-ui.ts).
• The package expects React 19 in the host app.