behavioural-dashboard 0.9.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ricardo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,261 @@
+# behavioural-dashboard
+
+A framework-agnostic TypeScript engine that tracks user interaction patterns and outputs serializable state for adaptive UIs. No DOM manipulation, no CSS, no framework lock-in — just behavioural primitives you wire into your own components.
+
+> **ESM only.** This package ships ES modules exclusively. It requires a bundler or a runtime that supports `"type": "module"`.
+
+## Installation
+
+```bash
+npm install behavioural-dashboard
+```
+
+## Quick start
+
+```typescript
+import { BehaviouralEngine } from 'behavioural-dashboard';
+
+const engine = new BehaviouralEngine({
+  budget: 100,
+  increment: 5,
+  growthRate: 0.2,
+  variants: ['compact', 'standard', 'expanded'],
+});
+
+// Register widgets — optionally with initial scores for a pre-seeded layout
+engine.register('orders', 40);
+engine.register('fleet', 35);
+engine.register('alerts', 25);
+
+// Record an interaction
+engine.record('orders');
+
+// Read state (returned in registration order)
+const states = engine.getState();
+// [
+//   { id: 'orders', score: 43.2, weight: 0.432, clicks: 1, variant: 'standard' },
+//   { id: 'fleet',  score: 32.1, weight: 0.321, clicks: 0, variant: 'compact'  },
+//   { id: 'alerts', score: 24.7, weight: 0.247, clicks: 0, variant: 'compact'  },
+// ]
+
+// Subscribe to changes
+engine.on('change', (states) => {
+  for (const s of states) {
+    const el = document.getElementById(s.id)!;
+    el.className = `widget widget--${s.variant}`;
+    el.style.flexGrow = String(s.weight * states.length);
+  }
+});
+```
+
+## How it works
+
+### Zero-sum budget scoring
+
+A fixed **budget** (default: `100`) is shared across all registered widgets. Scores always sum to exactly the budget. When a widget is interacted with, it gains points drained proportionally from every other widget — widgets that hold more score lose more than those that hold less.
+
+### Proportional drain redistribution
+
+On each `record(id)` call:
+
+1. The engine collects all widgets other than the target.
+2. It drains up to `increment` points from them, taking from each in proportion to its current score.
+3. Those points are added to the target widget's score.
+4. Scores are renormalized so the total stays at `budget`.
+
+Unused widgets shrink only when other widgets are clicked. There is no time-based decay.
+
+### Weight-based variant resolution
+
+Each widget's **weight** is its fraction of the total budget:
+
+```
+weight = score / budget        // range: 0–1
+```
+
+The active variant is chosen by mapping weight through the `growthRate` step:
+
+```
+variantIndex = min(floor(weight / growthRate), variants.length - 1)
+```
+
+With the default `growthRate` of `0.2` and variants `['compact', 'standard', 'expanded']`:
+
+| weight range | variantIndex | variant    |
+|---|---|---|
+| 0.00 – 0.19  | 0            | `compact`  |
+| 0.20 – 0.39  | 1            | `standard` |
+| 0.40 – 1.00  | 2            | `expanded` |
+
+A smaller `growthRate` makes variants unlock at lower weights (faster progression). A larger value requires a widget to hold more of the budget before advancing.
+
+### Pre-seeded default layouts
+
+Registering widgets with explicit initial scores sets a default layout:
+
+```typescript
+engine.register('primary',   50);  // starts prominent
+engine.register('secondary', 30);
+engine.register('tertiary',  20);  // starts small
+```
+
+If no initial scores are given, all widgets start at `0` and receive an equal share on first normalization. `reset()` always returns to those initial values.
+
+## Configuration
+
+| Option       | Default       | Description                                              |
+|---|---|---|
+| `budget`     | `100`         | Total score pool shared across all widgets               |
+| `increment`  | `5`           | Points transferred per interaction                       |
+| `growthRate` | `0.2`         | Weight step per variant level (lower = faster unlock)    |
+| `variants`   | `['default']` | Ordered variant names, least to most prominent           |
+
+All options are optional. The constructor throws if `budget`, `increment`, or `growthRate` are non-positive, or if `variants` is empty.
+
+## API reference
+
+### `new BehaviouralEngine(config?)`
+
+Creates a new engine. All config fields are optional and fall back to defaults.
+
+### `register(id: string, initialScore?: number): void`
+
+Registers a widget. Throws if `id` is already registered. Does not emit a `'change'` event.
+
+If `initialScore` is omitted the widget starts at score `0`. What happens next depends on the mix of registered widgets:
+
+- **All widgets have score 0** (no explicit initial scores anywhere): on first normalization they receive an equal share of the budget.
+- **Some widgets have explicit scores**: the scoreless widget stays at `0` until other widgets are interacted with; it then receives budget share proportionally through normalization, but it does not get an automatic equal slice.
+
+### `record(id: string): void`
+
+Records one interaction on `id`. Redistributes the budget and fires `'change'` listeners. Throws if `id` is not registered.
+
+### `getState(): WidgetState[]`
+
+Returns the current state of all widgets in **registration order**. The array is not sorted by score.
+
+### `getWidget(id: string): WidgetState`
+
+Returns the current state of a single widget. Throws if `id` is not registered.
+
+### `export(): AdaptiveState`
+
+Returns a plain, JSON-serializable snapshot of the engine state. See [Persistence](#persistence).
+
+### `import(state: AdaptiveState): void`
+
+Restores from a snapshot. Widgets in the engine that are absent from the snapshot retain their current scores; the scores are then renormalized. Widgets in the snapshot that are not registered in the engine are ignored. Throws on unsupported `version` values.
+
+### `reset(): void`
+
+Resets all widgets to their initial scores and zeroes click counts. Fires `'change'` listeners.
+
+### `on(event: 'change', cb: (states: WidgetState[]) => void): void`
+
+Subscribes to state changes. `cb` is called after every `record`, `import`, and `reset`.
+
+### `off(event: 'change', cb: (states: WidgetState[]) => void): void`
+
+Unsubscribes a previously registered listener.
+
+### `destroy(): void`
+
+Removes all listeners. Call this when tearing down a component to prevent memory leaks.
+
+## WidgetState shape
+
+```typescript
+interface WidgetState {
+  id: string;      // widget identifier
+  score: number;   // raw score (sums to budget across all widgets)
+  weight: number;  // score / budget, range 0–1
+  clicks: number;  // total interactions recorded since last reset
+  variant: string; // active variant name from your variants array
+}
+```
+
+There is no `order` field. If you need a sorted list, sort `getState()` yourself:
+
+```typescript
+const ranked = engine.getState().sort((a, b) => b.score - a.score);
+```
+
+## Styling
+
+This library produces **data, not DOM**. Wiring state to your UI is your responsibility.
+
+| Engine output | Suggested UI mapping                                                      |
+|---|---|
+| `weight` (0–1)  | Size the widget: `flex-grow`, `grid-column: span N`, width percentage   |
+| `variant`       | Apply a CSS class: `.widget--compact`, `.widget--standard`, etc.        |
+| `clicks > 0`    | Progressive disclosure: reveal detail layers after first interaction    |
+
+Example — flex layout that grows widgets proportionally:
+
+```typescript
+engine.on('change', (states) => {
+  for (const s of states) {
+    const el = document.getElementById(s.id)!;
+    el.className = `widget widget--${s.variant}`;
+    el.style.flexGrow = String(s.weight * states.length);
+  }
+});
+```
+
+Recommended CSS transitions so size and style changes animate smoothly:
+
+```css
+.widget {
+  transition: flex-grow 0.4s ease, min-height 0.4s ease;
+}
+```
+
+## Persistence
+
+`export()` returns an `AdaptiveState` object you can serialize and store anywhere. The type is exported and can be imported directly:
+
+```typescript
+import type { AdaptiveState } from 'behavioural-dashboard';
+```
+
+```typescript
+interface AdaptiveState {
+  version: 1;
+  widgets: Array<{ id: string; score: number; clicks: number }>;
+  lastInteraction: number; // Unix timestamp (ms) of the most recent record() call
+}
+```
+
+Example with `localStorage`:
+
+```typescript
+// Save after every change
+engine.on('change', () => {
+  localStorage.setItem('dashboard', JSON.stringify(engine.export()));
+});
+
+// Restore on page load
+const raw = localStorage.getItem('dashboard');
+if (raw) {
+  engine.import(JSON.parse(raw));
+}
+```
+
+The same pattern works with `IndexedDB`, a REST endpoint, or any other store — `AdaptiveState` is plain JSON with no class instances or circular references.
+
+## Demo
+
+[ricardomonteirosimoes.github.io/behavioural-dashboard](https://ricardomonteirosimoes.github.io/behavioural-dashboard/)
+
+## Attribution
+
+The concept of a behavioural, interaction-adaptive dashboard was designed and demonstrated by [Tanvi Palkar](https://www.linkedin.com/in/tanvi-palkar-ab9b159a/). Her original interactive demo is available at [tanvin-alt.github.io/behavioural-dashboard](https://tanvin-alt.github.io/behavioural-dashboard/) ([source](https://github.com/tanvin-alt/behavioural-dashboard)).
+
+This library extracts and generalises the mechanics from that demo into a framework-agnostic TypeScript package.
+
+Vibe-engineered with Claude (Anthropic).
+
+## License
+
+MIT

package/dist/engine.d.ts

@@ -0,0 +1,51 @@
+import type { AdaptiveState } from './state';
+export interface BehaviouralEngineConfig {
+    /** Total score budget across all widgets. Default: 100 */
+    budget: number;
+    /** Score transferred per interaction. Default: 5 */
+    increment: number;
+    /** Weight threshold step per variant level. A widget needs weight >= (level * growthRate) to reach that variant. With the default of 0.2, variants unlock at weights 0, 0.2, 0.4, 0.6. Default: 0.2 */
+    growthRate: number;
+    /** Ordered variant names, least to most prominent. */
+    variants: string[];
+}
+export interface WidgetState {
+    id: string;
+    score: number;
+    weight: number;
+    clicks: number;
+    variant: string;
+}
+type ChangeListener = (states: WidgetState[]) => void;
+export declare class BehaviouralEngine {
+    private readonly config;
+    private readonly widgets;
+    private readonly listeners;
+    private lastInteraction;
+    private dirty;
+    constructor(config?: Partial<BehaviouralEngineConfig>);
+    register(id: string, initialScore?: number): void;
+    record(id: string): void;
+    getState(): WidgetState[];
+    getWidget(id: string): WidgetState;
+    export(): AdaptiveState;
+    /**
+     * Restores engine state from a previously exported snapshot.
+     *
+     * Partial state is fully supported: widgets registered in this engine that
+     * are absent from the imported snapshot retain their current scores. After
+     * all matching widgets are updated, scores are renormalized to the configured
+     * budget, so the absent widgets participate in that redistribution.
+     */
+    import(state: AdaptiveState): void;
+    reset(): void;
+    on(event: 'change', cb: ChangeListener): void;
+    off(event: 'change', cb: ChangeListener): void;
+    destroy(): void;
+    private toWidgetState;
+    private ensureNormalized;
+    private normalizeScores;
+    private emit;
+}
+export {};
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,WAAW,uBAAuB;IACtC,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,uMAAuM;IACvM,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,KAAK,cAAc,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,IAAI,CAAC;AAiBtD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IACvD,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,KAAK,CAAQ;gBAET,MAAM,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC;IAgBrD,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI;IAsBjD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAgCxB,QAAQ,IAAI,WAAW,EAAE;IAKzB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW;IASlC,MAAM,IAAI,aAAa;IAavB;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IA0BlC,KAAK,IAAI,IAAI;IAWb,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI;IAO7C,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI;IAO9C,OAAO,IAAI,IAAI;IAIf,OAAO,CAAC,aAAa;IAgBrB,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,eAAe;IAwBvB,OAAO,CAAC,IAAI;CAMb"}

package/dist/engine.js

@@ -0,0 +1,206 @@
+const DEFAULTS = {
+    budget: 100,
+    increment: 5,
+    growthRate: 0.2,
+    variants: ['default'],
+};
+export class BehaviouralEngine {
+    config;
+    widgets = new Map();
+    listeners = new Set();
+    lastInteraction = 0;
+    dirty = true;
+    constructor(config) {
+        this.config = { ...DEFAULTS, ...config };
+        if (this.config.variants.length === 0) {
+            throw new Error('variants must contain at least one entry');
+        }
+        if (this.config.budget <= 0) {
+            throw new Error('budget must be positive');
+        }
+        if (this.config.growthRate <= 0) {
+            throw new Error('growthRate must be positive');
+        }
+        if (this.config.increment <= 0) {
+            throw new Error('increment must be positive');
+        }
+    }
+    register(id, initialScore) {
+        if (this.widgets.has(id)) {
+            throw new Error(`Widget "${id}" is already registered`);
+        }
+        if (initialScore !== undefined) {
+            if (!Number.isFinite(initialScore) || initialScore < 0) {
+                throw new Error(`initialScore must be a finite non-negative number, got: ${initialScore}`);
+            }
+        }
+        const score = initialScore ?? 0;
+        this.widgets.set(id, {
+            id,
+            score,
+            clicks: 0,
+            initialScore: score,
+            hasExplicitInitial: initialScore !== undefined,
+        });
+        this.dirty = true;
+    }
+    record(id) {
+        const widget = this.widgets.get(id);
+        if (!widget) {
+            throw new Error(`Widget "${id}" is not registered`);
+        }
+        this.ensureNormalized();
+        widget.clicks++;
+        this.lastInteraction = Date.now();
+        let sumOthers = 0;
+        for (const w of this.widgets.values()) {
+            if (w.id !== id)
+                sumOthers += w.score;
+        }
+        if (sumOthers > 0) {
+            const drain = Math.min(this.config.increment, sumOthers);
+            let actualDrain = 0;
+            for (const other of this.widgets.values()) {
+                if (other.id === id)
+                    continue;
+                const loss = drain * (other.score / sumOthers);
+                const clamped = Math.max(0, other.score - loss);
+                actualDrain += other.score - clamped;
+                other.score = clamped;
+            }
+            widget.score += actualDrain;
+        }
+        this.normalizeScores();
+        this.emit();
+    }
+    getState() {
+        this.ensureNormalized();
+        return [...this.widgets.values()].map((w) => this.toWidgetState(w));
+    }
+    getWidget(id) {
+        this.ensureNormalized();
+        const widget = this.widgets.get(id);
+        if (!widget) {
+            throw new Error(`Widget "${id}" is not registered`);
+        }
+        return this.toWidgetState(widget);
+    }
+    export() {
+        this.ensureNormalized();
+        return {
+            version: 1,
+            widgets: [...this.widgets.values()].map((w) => ({
+                id: w.id,
+                score: w.score,
+                clicks: w.clicks,
+            })),
+            lastInteraction: this.lastInteraction,
+        };
+    }
+    /**
+     * Restores engine state from a previously exported snapshot.
+     *
+     * Partial state is fully supported: widgets registered in this engine that
+     * are absent from the imported snapshot retain their current scores. After
+     * all matching widgets are updated, scores are renormalized to the configured
+     * budget, so the absent widgets participate in that redistribution.
+     */
+    import(state) {
+        if (state.version !== 1) {
+            throw new Error(`Unsupported state version: ${state.version}`);
+        }
+        for (const ws of state.widgets) {
+            const widget = this.widgets.get(ws.id);
+            if (widget) {
+                // Only update widgets that exist in this engine; unknown ids are ignored.
+                if (!Number.isFinite(ws.score) || ws.score < 0)
+                    continue;
+                if (!Number.isFinite(ws.clicks) ||
+                    !Number.isInteger(ws.clicks) ||
+                    ws.clicks < 0)
+                    continue;
+                widget.score = ws.score;
+                widget.clicks = ws.clicks;
+            }
+        }
+        this.lastInteraction = Number.isFinite(state.lastInteraction)
+            ? state.lastInteraction
+            : 0;
+        this.normalizeScores();
+        this.emit();
+    }
+    reset() {
+        for (const widget of this.widgets.values()) {
+            widget.score = widget.initialScore;
+            widget.clicks = 0;
+        }
+        this.lastInteraction = 0;
+        this.dirty = true;
+        this.ensureNormalized();
+        this.emit();
+    }
+    on(event, cb) {
+        if (event !== 'change') {
+            throw new Error(`Unknown event: "${event}"`);
+        }
+        this.listeners.add(cb);
+    }
+    off(event, cb) {
+        if (event !== 'change') {
+            throw new Error(`Unknown event: "${event}"`);
+        }
+        this.listeners.delete(cb);
+    }
+    destroy() {
+        this.listeners.clear();
+    }
+    toWidgetState(entry) {
+        const { budget, growthRate, variants } = this.config;
+        const weight = budget > 0 ? entry.score / budget : 0;
+        const variantIndex = Math.min(Math.floor(weight / growthRate), variants.length - 1);
+        return {
+            id: entry.id,
+            score: entry.score,
+            weight,
+            clicks: entry.clicks,
+            variant: variants[variantIndex],
+        };
+    }
+    ensureNormalized() {
+        if (!this.dirty)
+            return;
+        this.normalizeScores();
+        this.dirty = false;
+    }
+    normalizeScores() {
+        const entries = [...this.widgets.values()];
+        if (entries.length === 0)
+            return;
+        const sum = entries.reduce((s, w) => s + w.score, 0);
+        if (sum === 0) {
+            const equal = this.config.budget / entries.length;
+            for (const entry of entries) {
+                entry.score = equal;
+                // Stamp the equal-share as initialScore so that reset() restores equal
+                // distribution for widgets that were registered without explicit scores.
+                // Widgets registered with an explicit initialScore (even 0) are excluded
+                // because their initialScore was deliberately set at registration time.
+                if (!entry.hasExplicitInitial) {
+                    entry.initialScore = equal;
+                }
+            }
+            return;
+        }
+        const factor = this.config.budget / sum;
+        for (const entry of entries) {
+            entry.score *= factor;
+        }
+    }
+    emit() {
+        const states = this.getState();
+        for (const listener of this.listeners) {
+            listener(states);
+        }
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AA+BA,MAAM,QAAQ,GAA4B;IACxC,MAAM,EAAE,GAAG;IACX,SAAS,EAAE,CAAC;IACZ,UAAU,EAAE,GAAG;IACf,QAAQ,EAAE,CAAC,SAAS,CAAC;CACtB,CAAC;AAEF,MAAM,OAAO,iBAAiB;IACX,MAAM,CAA0B;IAChC,OAAO,GAAG,IAAI,GAAG,EAAuB,CAAC;IACzC,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC/C,eAAe,GAAG,CAAC,CAAC;IACpB,KAAK,GAAG,IAAI,CAAC;IAErB,YAAY,MAAyC;QACnD,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,QAAQ,EAAE,GAAG,MAAM,EAAE,CAAC;QACzC,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAC9D,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;QAC7C,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,IAAI,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;QACjD,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,IAAI,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAED,QAAQ,CAAC,EAAU,EAAE,YAAqB;QACxC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,WAAW,EAAE,yBAAyB,CAAC,CAAC;QAC1D,CAAC;QACD,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAC/B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;gBACvD,MAAM,IAAI,KAAK,CACb,2DAA2D,YAAY,EAAE,CAC1E,CAAC;YACJ,CAAC;QACH,CAAC;QACD,MAAM,KAAK,GAAG,YAAY,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE;YACnB,EAAE;YACF,KAAK;YACL,MAAM,EAAE,CAAC;YACT,YAAY,EAAE,KAAK;YACnB,kBAAkB,EAAE,YAAY,KAAK,SAAS;SAC/C,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,MAAM,CAAC,EAAU;QACf,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,WAAW,EAAE,qBAAqB,CAAC,CAAC;QACtD,CAAC;QAED,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACxB,MAAM,CAAC,MAAM,EAAE,CAAC;QAChB,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAElC,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YACtC,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE;gBAAE,SAAS,IAAI,CAAC,CAAC,KAAK,CAAC;QACxC,CAAC;QAED,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;YAClB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;YACzD,IAAI,WAAW,GAAG,CAAC,CAAC;YACpB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;gBAC1C,IAAI,KAAK,CAAC,EAAE,KAAK,EAAE;oBAAE,SAAS;gBAC9B,MAAM,IAAI,GAAG,KAAK,GAAG,CAAC,KAAK,CAAC,KAAK,GAAG,SAAS,CAAC,CAAC;gBAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;gBAChD,WAAW,IAAI,KAAK,CAAC,KAAK,GAAG,OAAO,CAAC;gBACrC,KAAK,CAAC,KAAK,GAAG,OAAO,CAAC;YACxB,CAAC;YACD,MAAM,CAAC,KAAK,IAAI,WAAW,CAAC;QAC9B,CAAC;QAED,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;IAED,QAAQ;QACN,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACxB,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,SAAS,CAAC,EAAU;QAClB,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACxB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACpC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,WAAW,EAAE,qBAAqB,CAAC,CAAC;QACtD,CAAC;QACD,OAAO,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACxB,OAAO;YACL,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC9C,EAAE,EAAE,CAAC,CAAC,EAAE;gBACR,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,MAAM,EAAE,CAAC,CAAC,MAAM;aACjB,CAAC,CAAC;YACH,eAAe,EAAE,IAAI,CAAC,eAAe;SACtC,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,KAAoB;QACzB,IAAI,KAAK,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,8BAA8B,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACjE,CAAC;QACD,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACvC,IAAI,MAAM,EAAE,CAAC;gBACX,0EAA0E;gBAC1E,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,KAAK,GAAG,CAAC;oBAAE,SAAS;gBACzD,IACE,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,CAAC;oBAC3B,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,CAAC;oBAC5B,EAAE,CAAC,MAAM,GAAG,CAAC;oBAEb,SAAS;gBACX,MAAM,CAAC,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC;gBACxB,MAAM,CAAC,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC;YAC5B,CAAC;QACH,CAAC;QACD,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,eAAe,CAAC;YAC3D,CAAC,CAAC,KAAK,CAAC,eAAe;YACvB,CAAC,CAAC,CAAC,CAAC;QACN,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;IAED,KAAK;QACH,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YAC3C,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,YAAY,CAAC;YACnC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;QACpB,CAAC;QACD,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACxB,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;IAED,EAAE,CAAC,KAAe,EAAE,EAAkB;QACpC,IAAK,KAAgB,KAAK,QAAQ,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,mBAAmB,KAAK,GAAG,CAAC,CAAC;QAC/C,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACzB,CAAC;IAED,GAAG,CAAC,KAAe,EAAE,EAAkB;QACrC,IAAK,KAAgB,KAAK,QAAQ,EAAE,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,mBAAmB,KAAK,GAAG,CAAC,CAAC;QAC/C,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAED,OAAO;QACL,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;IAEO,aAAa,CAAC,KAAkB;QACtC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;QACrD,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QACrD,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAC3B,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,UAAU,CAAC,EAC/B,QAAQ,CAAC,MAAM,GAAG,CAAC,CACpB,CAAC;QACF,OAAO;YACL,EAAE,EAAE,KAAK,CAAC,EAAE;YACZ,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,MAAM;YACN,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC;SAChC,CAAC;IACJ,CAAC;IAEO,gBAAgB;QACtB,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,OAAO;QACxB,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAEO,eAAe;QACrB,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;QAC3C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACjC,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACrD,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC;YACd,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;YAClD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC5B,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC;gBACpB,uEAAuE;gBACvE,yEAAyE;gBACzE,yEAAyE;gBACzE,wEAAwE;gBACxE,IAAI,CAAC,KAAK,CAAC,kBAAkB,EAAE,CAAC;oBAC9B,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC;gBAC7B,CAAC;YACH,CAAC;YACD,OAAO;QACT,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC;QACxC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,KAAK,CAAC,KAAK,IAAI,MAAM,CAAC;QACxB,CAAC;IACH,CAAC;IAEO,IAAI;QACV,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC/B,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACtC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { BehaviouralEngine } from './engine';
+export type { BehaviouralEngineConfig, WidgetState } from './engine';
+export type { AdaptiveState } from './state';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,YAAY,EAAE,uBAAuB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACrE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { BehaviouralEngine } from './engine';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC"}

package/dist/state.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Serializable snapshot of the full engine state.
+ * Designed to be JSON.stringify'd and stored anywhere:
+ * localStorage, IndexedDB, REST API, etc.
+ */
+export interface AdaptiveState {
+    version: 1;
+    widgets: {
+        id: string;
+        score: number;
+        clicks: number;
+    }[];
+    lastInteraction: number;
+}
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,CAAC,CAAC;IACX,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACzD,eAAe,EAAE,MAAM,CAAC;CACzB"}

package/dist/state.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "behavioural-dashboard",
+  "version": "0.9.1",
+  "description": "Framework-agnostic TypeScript engine for self-adapting UI layouts based on user behaviour",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "lint": "eslint src/ demo/",
+    "lint:fix": "eslint src/ demo/ --fix",
+    "format": "prettier --write src/ demo/",
+    "format:check": "prettier --check src/ demo/",
+    "knip": "knip",
+    "duplication": "jscpd src/",
+    "test": "vitest run",
+    "check": "tsc --noEmit && eslint src/ demo/ && prettier --check src/ demo/ && knip && jscpd src/ && vitest run",
+    "demo": "vite",
+    "demo:build": "vite build",
+    "demo:preview": "vite preview",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "behavioural-ui",
+    "adaptive-dashboard",
+    "interaction-tracking",
+    "progressive-disclosure",
+    "zero-sum-budget",
+    "typescript",
+    "framework-agnostic"
+  ],
+  "author": "Ricardo Monteiro Simoes",
+  "license": "MIT",
+  "homepage": "https://ricardomonteirosimoes.github.io/behavioural-dashboard/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RicardoMonteiroSimoes/behavioural-dashboard.git"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.27.0",
+    "eslint": "^9.27.0",
+    "eslint-config-prettier": "^10.1.5",
+    "jscpd": "^4.0.5",
+    "knip": "^5.57.2",
+    "prettier": "^3.5.3",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.32.1",
+    "vite": "^6.3.5",
+    "vitest": "^3.1.4",
+    "happy-dom": "^18.0.1"
+  }
+}