adaptive-experience-library

v0.1.1

Published

3 months ago

Turn any website into an adaptive experience that reacts to real user behaviour. SimpleModes observes motion, clicks, and scroll patterns, sends them through a lightweight TensorFlow.js model, and seamlessly swaps between **Simple**, **Normal**, and **Adv

0High
0Medium
0Low

mebishnusahu0595

Adaptive Experience Library (SimpleModes)

✨ Features

Three modes out of the box: sizeable UI for newcomers, balanced defaults for the average visitor, and dense layouts for power users.
Real-time inference: TensorFlow.js model runs in the browser, so no network calls or data sharing.
Typing warm-up gate: optional pre-entry overlay gauges typing speed to seed the starting mode.
Richer telemetry: pointer velocity, scroll depth, click rate, and keyboard cadence feed a smoothed classifier for steadier decisions.
Zero-config onboarding: drop the CDN script and get automatic mode detection instantly.
Flexible API: override styles, hook into predictions, or drive your own UI responses.
Dev playground: a Vite-powered demo showcases mode switching, probabilities, and an advanced-only icon explorer.

🚀 Quick start (CDN)

<!doctype html>
<html>
  <head>
    <script
      src="https://cdn.jsdelivr.net/npm/[email protected]/dist/simplemodes.min.js"
      defer
    ></script>
  </head>
  <body>
    <!-- Your content -->
  </body>
</html>

With the script loaded, the library boots automatically and toggles CSS classes on <html>:

ae-mode-simple
ae-mode-normal
ae-mode-advanced

Use attribute selectors to fine-tune layouts:

html[data-simplemodes-mode="simple"] nav { font-size: 1.1rem; }
html[data-simplemodes-mode="advanced"] .tutorial-banner { display: none; }

📦 Package usage (ES modules)

npm install adaptive-experience-library @tensorflow/tfjs

import { initAdaptiveExperience } from 'adaptive-experience-library';

const adaptive = initAdaptiveExperience({
  debug: true,
  onModeChange: ({ mode, probabilities }) => {
    console.info('Mode switched to', mode, probabilities);
  },
});

⚙️ Configuration

| Option | Type | Default | Description | | --- | --- | --- | --- | | autoStart | boolean | true | Start listeners immediately. Set false to control manually. | | initialMode | "simple" \| "normal" \| "advanced" | 'normal' | Mode applied before the first prediction. | | initialModeGracePeriodMs | number | 12000 | Milliseconds to protect the initial mode before the classifier can change it. | | evaluationIntervalMs | number | 8000 | How frequently the classifier runs (ms). | | observationWindowMs | number | 20000 | Rolling window of interaction history in milliseconds. | | minEventSamples | number | 4 | Minimum interactions before predictions run. | | debug | boolean | false | Enables verbose console logging. | | customModeClasses | Partial<Record<ExperienceMode, string>> | – | Supply your own CSS class names per mode. | | additionalCSS | string | – | Extra CSS that will be injected with the defaults. | | onModeChange | (prediction) => void | () => undefined | Callback fired whenever the predicted mode changes. | | freezeAfterFirstChange | boolean | true | Lock the interface after the first AI-driven mode switch to keep the experience stable. | | minimumConfidence | number | 0.45 | Required confidence for the new mode before switching (0–1). | | minimumConfidenceDelta | number | 0.1 | Minimum margin the new mode must beat the current mode by before switching. | | probabilitySmoothing | number | 0.35 | Exponential smoothing factor (0–1] that blends raw predictions for stability. Set to 1 for no smoothing. |

The callback receives:

interface ModePrediction {
  mode: 'simple' | 'normal' | 'advanced';
  confidence: number;
  probabilities: { simple: number; normal: number; advanced: number };
  features: {
    pointerSpeed: number;
    clickRate: number;
    scrollEngagement: number;
    keyboardCadence: number;
  };
  evaluatedAt: number; // DOMHighResTimeStamp
}

🌐 Global API

When loaded via CDN, the library attaches window.SimpleModes:

interface SimpleModesGlobal {
  init(config?): AdaptiveExperienceHandle;
  configure(config): AdaptiveExperienceHandle;
  getInstance(): AdaptiveExperienceHandle | null;
  getCurrentMode(): ExperienceMode;
  getPrediction(): ModePrediction | null;
  stop(): void;
  destroy(): void;
}

The returned AdaptiveExperienceHandle exposes:

interface AdaptiveExperienceHandle {
  start(): void;
  stop(): void;
  destroy(): void;
  getCurrentMode(): ExperienceMode;
  getLastPrediction(): ModePrediction | null;
  updateConfig(options: Partial<AdaptiveExperienceConfig>): void;
}

☁️ CDN usage

Want to drop SimpleModes into any existing site without a bundler? Use the jsDelivr CDN:

<script
  src="https://cdn.jsdelivr.net/npm/[email protected]/dist/simplemodes.min.js"
  defer
></script>
<script>
  window.SimpleModes?.init({
    initialMode: 'normal',
    probabilitySmoothing: 0.35,
    onModeChange({ mode, probabilities }) {
      console.log('Mode changed to', mode, probabilities);
    },
  });
</script>

The UMD build already bundles TensorFlow.js and exposes window.SimpleModes, so developers only need the single script tag. Configure the helper exactly as you would in a module-based project, or call window.SimpleModes.configure(...) later to tweak settings.

🚢 Publishing to npm

When you’re ready to cut a public release (which automatically makes the bundle available on jsDelivr/unpkg), follow this checklist:

Build fresh artifacts

npm run build

Inspect the package contents locally (optional but recommended)

npm pack --dry-run

or create a tarball with npm pack and inspect it. 3. Version bump using semver (patch/minor/major as appropriate)

npm version patch

This updates package.json and creates a git tag. 4. Publish (requires npm login beforehand)

npm publish

If you run into an ENEEDAUTH error, authenticate this machine with npm login (or npm adduser) and verify with npm whoami before retrying. Accounts with 2FA enabled will be prompted for either an OTP code or a one-time password generated via npm token.

Within a few minutes the new version is reachable via the CDN URL format:

https://cdn.jsdelivr.net/npm/adaptive-experience-library@<version>/dist/simplemodes.min.js

Share that URL (pinning <version> or using @latest) with integrators so they can drop the script tag into their sites.

🎨 Styling hooks

The library injects default styles covering font sizes, button padding, and helper utility classes:

.sm-simple-only, .sm-normal-only, .sm-advanced-only
.sm-compact-only (hidden in Simple mode, visible in Advanced)

Customize by overriding variables or supplying additionalCSS:

initAdaptiveExperience({
  additionalCSS: `
    html.ae-mode-advanced body { background: #0f172a; color: #f8fafc; }
  `,
});

🧪 Demo playground

Run the interactive dashboard:

npm install
npm run dev

Visit http://localhost:5173 and complete the 3-word warm-up to seed your initial mode. Try typing slowly vs. quickly to see how the dashboard opens in Simple, Normal, or Advanced mode before the AI resumes control. Buttons let you freeze modes or resume AI-driven switching.

🏗️ Build & type definitions

npm run typecheck   # Strict TypeScript diagnostics
npm run build       # Emits dist/simplemodes.min.js + dist/types

Artifacts include both a UMD bundle for CDN usage and an ES module for bundlers, alongside generated TypeScript declarations under dist/types.

🧭 Project layout

src/
├─ adaptiveExperience.ts  # Core engine and TensorFlow.js inference
├─ styleManager.ts        # Mode class management + default CSS
├─ index.ts               # Public API + window.SimpleModes bridge
├─ demo.ts / demo.css     # Developer playground
└─ types.ts               # Shared type definitions

🔮 Next ideas

Train a personalised model per vertical (commerce, education, productivity).
Persist behavioural scores across sessions using localStorage.
Stream anonymised telemetry to refine model weights server-side.

Questions or improvement ideas? Pop them in the repo issues and let’s evolve adaptive UX together.