@winkjs/composer 0.0.2 → 0.4.0

package/LICENSE

@@ -1,6 +1,6 @@
                            The MIT License
 
-Copyright (c) 2024-25  GRAYPE Systems Private Limited
+Copyright (c) 2024-26  GRAYPE Systems Private Limited
 
 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

package/README.md

@@ -1,132 +1,71 @@
-# wink-composer ♫
+# winkComposer
 
-### [![Stability](https://img.shields.io/badge/stability-1--experimental-orange.svg)](https://nodejs.org/api/documentation.html#documentation_stability_index)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## ✨ Real-time analytics that sparks joy
+## Composable Streaming Intelligence
+[<img align="right" src="https://decisively.github.io/wink-logos/logo-title.png" width="100px" >](https://winkjs.org/)
 
-[<img align="right" src="https://decisively.github.io/wink-logos/logo-title.png" width="100px" >](http://winkjs.org/)
+A sensor spikes. An engine runs hot. A building's energy use surges. A server degrades. A cold chain breaks.
 
-WinkComposer is an upcoming open-source framework that makes building streaming intelligence playfully simple. Connect intuitive nodes, experiment freely, perfect it in an iteration or two. From edge-ready AI algorithms to built-in resilience, everything you need for production comes standard. No complexity, no black boxes - just the joy of creating exactly what you need.
+winkComposer turns live data streams into clear, actionable insights by composing small, focused building blocks — signal conditioning, anomaly detection, and health assessment — into pipelines underpinned by neural-network intelligence.
 
-## Why Composability Matters
+A high-performance JavaScript framework for IIoT and beyond. Runs on a Raspberry Pi or a production server or k8 cluster on cloud. Purpose-built for SMBs and MSMEs. Integrates with QuestDB, Grafana, and Mosquitto — open source, end to end.
 
-**🎯 Create What You Need** — With composability, you're the inventor: Correlate vibration with weather? Done. Detect micro-trends before they become macro? Built. 
+winkComposer calls its building blocks nodes — each with a single responsibility, wired through a declarative flow language. Small vocabulary, unbounded composition — the same nodes that detect bearing wear also catch server latency degradation and process yield drift.
 
-**💫 Countless Possibilities** — Dozens of nodes → Endless pipelines. Like few music notes creating captivating symphonies.
+> [!NOTE]
+> The [documentation site](https://composer.winkjs.org) is live and growing — interactive demos run real winkComposer nodes in your browser, no installation or sign-up required. The full source now lives in this repository, MIT-licensed. MCP integration for AI-driven queries over pre-computed insights is in active development.
 
-**🌱 Evolve Naturally** — Start: `sensor → threshold → alert`. Grow: Add intelligence: `sensor → normalize → smooth → detect → confirm → alert`. Unconstrained by vendor feature lists.
 
-**🔍 Total Transparency** — See which node triggered, what threshold crossed, why it alerted. Every decision is explainable.
+## Explore Possibilities
 
-## Build Exactly What You Need
+Real data. Real insight. Each demo runs the same winkComposer core that powers edge-to-cloud deployments — right here in your browser.
 
-Build precise analytics for your unique patterns:
+| [![Bearing Health](https://composer.winkjs.org/readme-bearing-health.png)](https://composer.winkjs.org/docs/use-cases/bearing-health) | [![Server Health](https://composer.winkjs.org/readme-server-health.png)](https://composer.winkjs.org/docs/use-cases/server-health) | [![Process Quality](https://composer.winkjs.org/readme-process-quality.png)](https://composer.winkjs.org/docs/use-cases/process-quality) |
+|:---:|:---:|:---:|
+| [**Detecting Bearing Failure**](https://composer.winkjs.org/docs/use-cases/bearing-health) | [**Detecting Server Latency Degradation**](https://composer.winkjs.org/docs/use-cases/server-health) | [**Catching Process Drift**](https://composer.winkjs.org/docs/use-cases/process-quality) |
+| Predictive Maintenance | AIOps | Process Control |
 
-```javascript
-// Detect bearing failure in rotating equipment
-vibration → isolateSignal → extractPeaks → measureIntensity →
-      trackChanges → triggerAlert
 
-// Monitor chemical process quality
-temperature → removeNoise → smoothFast → smoothSlow → findDivergence →
-      detectChange → waitForPersistence
+## Documentation
 
-// Find correlated sensor behaviors
-[sensor1, sensor2] → trackCorrelation → compareToNormal → raiseFlag
+| Resource | What it covers |
+|---|---|
+| [**Hello Flow!**](https://composer.winkjs.org/docs/playground/hello-flow) | Build a 4-node temperature monitor from scratch — smooth, detect, confirm, broadcast — with an interactive demo running real nodes in your browser. The natural starting point. |
+| [**Recipes**](https://composer.winkjs.org/docs/playground/recipes) | Focused, runnable patterns for common detection problems: gradual drift (fast/slow esMean crossover with Page-Hinkley), sudden shifts (Kalman filter), sensor freeze (collapsed standard deviation), and subtle process shifts (Western Electric run rules). Each runs in the browser. |
+| [**Explore Nodes**](https://composer.winkjs.org/docs/playground/explore-nodes) | Single-node sandboxes — drag a slider, watch the node respond in real time. Covers the Kalman 1D filter and the kernel convolution node, with more to come. |
+| [**Under the Hood**](https://composer.winkjs.org/docs/concepts/under-the-hood) | How messages flow and get enriched node by node, how bad data and throwing functions are handled without crashing the pipeline, how per-asset isolation works, and timestamp requirements. |
+| [**Flow Language**](https://composer.winkjs.org/docs/concepts/flow-language) | The complete DSL reference — flow anatomy, node call signatures, dynamic options (tunables), single vs. multi-field processing, naming policies, and node processing types. |
+| [**Composition Patterns**](https://composer.winkjs.org/docs/concepts/composition-patterns) | Proven node combinations for recurring problems: noise-tolerant alarms, drift detection, adaptive diagnostics, layered flows, and downsampling for storage. Includes clear guidance on when to use passIf, emitIf, or controller/disable. |
+| [**Semantics**](https://composer.winkjs.org/docs/concepts/semantics) | How to define what computed values mean — types, units, physical ranges, operational limits — as a single source of truth shared by storage, dashboards, and query engines. Covers the facts-vs-decisions design principle. |
+| [**Node Index**](https://composer.winkjs.org/docs/reference/node-index) | Every node grouped by category — Signal Conditioning, Detection, Feature Extraction, Intelligence, and more — with what each computes and what it adds to the message. |
 
-// Calculate real-time OEE
-machine → trackState → sumTime → countOutput →
-      checkQuality → calculateScore
-```
 
-Each node is simple:
-- `removeNoise`: Median of last few values (removes sensor spikes).
-- `smoothFast`: Average of last 10 values (recent trend).
-- `smoothSlow`: Average of last 100 values (baseline trend).
-- `findDivergence`: Fast trend - slow trend (unusual behavior?).
-- `trackCorrelation`: Smart correlation (learns relationships between sensors)
+## Performance
 
-_Node names and details are illustrative - actual implementations may vary._
+A pure compute benchmark — every step a live message takes, from arrival through all 8 nodes to final computed output, with no I/O. Asset pipelines are created dynamically as each new asset is first encountered; the benchmark runs 10 such pipelines concurrently, interleaved in random order to reflect real multi-asset deployment. Measured with `process.hrtime.bigint()` across 4.5 million messages (10 pipelines × 900 data points × 500 iterations). Storage and MQTT I/O are excluded.
 
-Every arrow is a conscious choice. Every node has a purpose. No magic, just simple intuitive math.
+| Configuration        | Throughput              |
+|----------------------|-------------------------|
+| Raspberry Pi 5       | ~100K messages/second   |
+| Modern server        | ~1.2M messages/second   |
+| Tracking 200K assets | ~300K messages/second   |
 
+The same pipeline [runs in your browser](https://composer.winkjs.org/docs/benchmark) — browser results are typically 30–60% of native Node.js throughput due to JIT differences.
 
-## Your Analytics Journey
 
-**Start Simple**  
-`sensor → threshold → alert`
+## Built for the Real World
 
-**Evolve Naturally**  
-`sensor → validate → normalize → threshold → debounce → alert`
+Each asset runs in its own isolated state — a fault in one never affects another. Messages queue locally when the network drops and drain cleanly on reconnect. The same pipeline code runs unchanged from edge to cloud. Shutdown is ordered and deterministic: sources close first, storage last, with no data corruption.
 
-**Scale Intelligently**  
-`sensor → [parallel: statistics | patterns | anomalies] → correlate → decide → act`
 
-Your analytics grow with your understanding, and are never limited by any tool's feature list.
-
-## Designed for the Real World
-
-### Industrial IoT
-From simple threshold monitoring to complex predictive maintenance - compose what fits your equipment, your patterns, your physics. **Move intelligence to the edge** with analytics that run on industrial Raspberry Pis. Works alongside your existing systems to handle your unique requirements.
-
-### Financial Services  
-Build fraud detection you can explain to auditors. Every decision traceable, every threshold justified.
-
-### Smart Infrastructure
-Energy optimization with transparent logic. See why the system made each decision.
-
-## Production-Grade Resilience
-Real streams have noise. Sensors fail. Networks hiccup. WinkComposer handles it all:
-
-- **Node-level fault isolation** - One bad reading doesn't crash your pipeline
-- **Automatic state recovery** - Snapshot and restore without missing a beat
-- **Built-in observability** - Know what's happening in every node, every partition
-- **Adaptive execution** - Maintains responsiveness under varying load
-
-
-## Core Principles
-
-| Principle | What it means |
-|-----------|---------------|
-| **Atomic Operations** | Each node does one thing perfectly |
-| **Pure Functions** | Predictable, testable, composable |
-| **Transparent Logic** | Understand every decision |
-| **Production Ready** | Built for high-throughput streaming with microsecond-scale latency |
-| **AI-Native Intelligence** | From statistical learning nodes to LLM reasoning - intelligence at every level |
-| **Built for Reality** | Node-level fault isolation, automatic recovery, and comprehensive observability |
-
-## What's Coming
-
-### 🎉 **Opening Our Doors in 2025**
-WinkComposer is transitioning to open source development in 2025. Join the [early conversation](https://github.com/winkjs/composer/discussions) and help shape the future of composable streaming analytics. You can even reach out directly at wink@graype.in.
-
-**Together, we're building:**
-
-- **Rich Node Library**: Statistical, filtering, detection, transformation, and control nodes
-- **Edge-Ready Intelligence**: Advanced algorithms like smart correlation, change point detection, and regression inference - AI-like capabilities without heavyweight frameworks
-- **Pipeline Builder**: Define your analytics flows declaratively (visual tools planned)
-- **Edge-Ready Performance**: Process data efficiently, even on resource-constrained devices (**tested on Raspberry Pi**)
-- **Knowledge Graph Integration**: Build digital twins with Neo4j/ArangoDB for contextual intelligence
-- **AI-Native Reasoning**: When patterns emerge, LLMs explain why. When anomalies occur, get actionable recommendations. Open-source models keep intelligence at the edge.
-
-
-## The Vision
-
-Finally, build solutions that fit your exact problems, not the other way around.
-
-Every industry has unique patterns. Every process has specific physics. Every business has particular rules. WinkComposer gives you the building blocks to create exactly what you need.
-
-Domain-specific platforms excel at standard use cases. WinkComposer shines when you need something unique, beyond standard use cases. Standard use cases always included - they're just the beginning of what's possible!
+## Get Involved
 
+| [**Star winkComposer**](https://github.com/winkjs/composer) | [**Follow @winkjs**](https://github.com/winkjs) | [**Discussions**](https://github.com/winkjs/composer/discussions) |
+|:---:|:---:|:---:|
+| Support open-source streaming intelligence. | Stay updated on releases and ecosystem developments. | Questions, ideas, or feedback — all welcome. |
 
 
 ## About winkJS
 
-WinkComposer joins the winkJS family - production-grade open-source packages for Natural Language Processing, Machine Learning, and Statistical Analysis in JavaScript. Built for reliability with ~100% test coverage.
-
-
-## Copyright & License
-
-**Wink Composer** is copyright 2017-25 [GRAYPE Systems Private Limited](https://graype.in/).
-
-It is licensed under the terms of the MIT License.
+[winkJS](https://winkjs.org) is the open-source home of two high-performance, production-grade tools — built from first principles, tested to near-perfection, and trusted by thousands of projects worldwide.

package/package.json

@@ -1,30 +1,32 @@
 {
     "name": "@winkjs/composer",
-    "version": "0.0.2",
-    "description": "Composable Streaming Intelligence.",
+    "version": "0.4.0",
+    "description": "Composable Streaming Intelligence — turn streaming data into actionable insights, from edge to cloud",
     "keywords": [
+        "streaming",
+        "streaming-intelligence",
+        "real-time",
+        "edge",
         "iot",
-        "statistical-learning",
-        "stream-processing",
-        "statistical-analysis",
-        "event-driven",
-        "composable",
-        "real-time-analytics",
-        "anomaly-detection",
-        "edge-computing",
-        "edgi-ai",
-        "streaming-analytics",
-        "industrial-iot"
+        "time-series",
+        "signal-processing",
+        "mqtt",
+        "questdb",
+        "wink-composer",
+        "winkjs",
+        "wink"
     ],
     "main": "src/composer.js",
+    "module": "src/composer.js",
+    "exports": {
+        ".": "./src/composer.js"
+    },
     "scripts": {
         "pretest": "npm run lint",
-        "test": "nyc --reporter=html --reporter=lcov --reporter=text mocha ./test/",
-        "coverage": "nyc report --reporter=text-lcov | coveralls",
-        "sourcedocs": "docker -i src -o ./sourcedocs --sidebar yes",
-        "lint": "eslint ./src/*.js ./test/*.js",
-        "perf": "node benchmark/run.js",
-        "dtslint": "dtslint types",
+        "test": "mocha --recursive 'src/**/*.specs.js' --ignore 'src/**/slow-*.specs.js'",
+        "test:hardening": "node --expose-gc node_modules/.bin/mocha --recursive 'src/**/slow-*.specs.js' --timeout 300000 --exit",
+        "test:coverage": "c8 --reporter=html mocha --recursive 'src/**/*.specs.js' --ignore 'src/**/slow-*.specs.js'",
+        "lint": "eslint 'src/**/*.js'",
         "docs-serve": "docsify serve ./docs"
     },
     "repository": {
@@ -33,19 +35,41 @@
     },
     "author": "Sanjaya Kumar Saxena",
     "license": "MIT",
+    "type": "module",
+    "engines": {
+        "node": ">=22"
+    },
+    "files": [
+        "src/composer.js",
+        "src/core/**/*.js",
+        "src/flow/**/*.js",
+        "src/nodes/**/*.js",
+        "src/tools/**/*.js",
+        "src/windowing/**/*.js",
+        "!src/**/*.specs.js",
+        "!src/**/test/"
+    ],
     "bugs": {
         "url": "https://github.com/winkjs/composer/issues"
     },
-    "homepage": "http://winkjs.org/composer/#/",
+    "homepage": "https://composer.winkjs.org/",
+    "publishConfig": {
+        "access": "public"
+    },
     "devDependencies": {
-        "benchmark": "^2.1.4",
-        "chai": "^4.3.7",
-        "coveralls": "^3.1.1",
-        "docker": "^1.0.0",
-        "docsify-cli": "^4.4.4",
-        "dtslint": "^4.2.1",
-        "eslint": "^8.36.0",
-        "mocha": "^10.2.0",
-        "nyc": "^15.1.0"
+        "c8": "^10.1.3",
+        "chai": "^5.2.0",
+        "eslint": "^9.21.0",
+        "eslint-plugin-security": "^4.0.0",
+        "mocha": "^11.1.0",
+        "sinon": "^19.0.2"
+    },
+    "dependencies": {
+        "@questdb/nodejs-client": "^4.2.0",
+        "classic-level": "^3.0.0",
+        "glob": "^13.0.6",
+        "mqtt": "^5.15.1",
+        "msgpackr": "^1.11.10",
+        "pg": "^8.20.0"
     }
 }

package/src/composer.js

@@ -0,0 +1,75 @@
+// src/composer.js
+
+/**
+ * @fileoverview Main entry point for @winkjs/composer.
+ *
+ * Provides flat exports for the DSL, source adapters, emitter adapters,
+ * codecs, and tunable helpers.
+ *
+ * @example
+ * import { flow, csv, mqttEmitter } from '@winkjs/composer';
+ *
+ * flow('myPipeline')
+ *     .sanitize(...)
+ *     .threshold(...)
+ *     .source(csv, { path: './data.csv' })
+ *     .emitter(mqttEmitter, { brokerUrl: 'mqtt://localhost' })
+ *     .run();
+ */
+
+// DSL
+export { flow } from './flow/flow.js';
+
+// Headless driver — feed a flow that has no source (see docs/handbook/headless-flow.md)
+export { headlessDriver } from './flow/driver.js';
+
+// Emitters
+export * as mqttEmitter from './core/emitter-manager/mqtt/index.js';
+export * as terminal from './core/emitter-manager/terminal/index.js';
+
+// Sources
+export * as csv from './core/source-manager/csv/index.js';
+export * as mqttSource from './core/source-manager/mqtt/index.js';
+
+// Storage
+export { default as questdbAdapter } from './core/storage-manager/questdb/index.js';
+
+// Semantics
+export { loadSemantics } from './core/semantics/loader.js';
+
+// Codecs
+export { jsonCodec, msgpackCodec } from './core/codec/index.js';
+
+// Tunable helpers
+export {
+    lookupByField,
+    pickByField,
+    scaleBy,
+    chooseWhen,
+    clampTo,
+    fromField,
+    offsetBy
+} from './core/tunable/helpers.js';
+
+// Transform helpers
+export {
+    square,
+    abs,
+    sqrt,
+    log,
+    log10,
+    reciprocal,
+    negate
+} from './nodes/transform/helpers.js';
+
+// Training utilities
+export {
+    computeStandardParams,
+    computeMinMaxParams,
+    computeRobustParams,
+    scale,
+    standardize
+} from './tools/training/scale.js';
+export { sigmoid, train, predict, classify } from './tools/training/logistic.js';
+export { confusionMatrix, classificationMetrics, sweepThresholds } from './tools/training/metrics.js';
+

package/src/core/batch/aoo-encoder.js

@@ -0,0 +1,148 @@
+// core/batch/aoo-encoder/index.js
+// Purpose:
+//   Array-of-Objects (AoO) encoder for efficient batch transmission of tabular data.
+//   Optimized for downsampled time-series data where rows have consistent shape.
+//   Designed to work with msgpackr's structure learning for maximum compression.
+//
+// Design Philosophy:
+//   - Zero allocations in hot path - reuse all objects and arrays
+//   - Stable object shapes - enables msgpackr structure learning
+//   - Predictable field order - consistent compression ratios
+//   - Null preservation - maintains shape even with missing data
+//
+// Use Case:
+//   Downsampled sensor data often arrives as rows of readings:
+//   [{ timestamp: 1234, temp: 23.5, pressure: 101.3 }, ...]
+//   This encoder batches these rows efficiently for MQTT transmission.
+//
+// Compression Strategy:
+//   By maintaining stable object shapes and field order, msgpackr learns the
+//   structure after ~5 messages. Subsequent messages only send structure ID + values,
+//   achieving 80-90% size reduction compared to JSON.
+
+/**
+ * Create an Array-of-Objects encoder for batch data transmission.
+ *
+ * @param {Object} options - Encoder configuration
+ * @param {number} options.maxRows - Maximum rows per batch (pre-allocation size)
+ * @param {string[]} options.fieldOrder - Field names in consistent order
+ * @param {Object} options.codec - Codec instance from createCodec()
+ *
+ * @returns {Object} Encoder with encode() method and fieldOrder reference
+ *
+ * @example
+ * const encoder = createAooEncoder({
+ *   maxRows: 100,
+ *   fieldOrder: ['timestamp', 'temperature', 'pressure'],
+ *   codec: msgpackCodec
+ * });
+ *
+ * const { payload, props } = encoder.encode('sensor-01', 1, readings, 50);
+ * mqttClient.publish('telemetry/batch', payload, { properties: props });
+ */
+export const createAooEncoder = function ( { maxRows, fieldOrder, codec } ) {
+    // Input validation - fail fast on misconfiguration
+    if ( !Array.isArray( fieldOrder ) || fieldOrder.length === 0 ) {
+        throw new Error( 'fieldOrder must be non-empty array of field names' );
+    }
+    if ( !maxRows || maxRows <= 0 ) {
+        throw new Error( 'maxRows must be positive integer' );
+    }
+    if ( !codec || typeof codec.pack !== 'function' ) {
+        throw new Error( 'codec must have pack() method');
+    }
+
+    // Pre-allocate row objects with stable shape.
+    // Critical for msgpackr structure learning:
+    // - Same fields in same order = same structure ID
+    // - null instead of undefined = consistent serialization
+    // - Object.create(null) = no prototype pollution
+    const rows = new Array( maxRows );
+    for ( let i = 0; i < maxRows; i += 1 ) {
+        const r = Object.create( null );
+        // Initialize all fields to null (not undefined!)
+        // This ensures consistent object shape even when values are missing
+        for ( let k = 0; k < fieldOrder.length; k += 1 ) {
+            r[ fieldOrder[ k ] ] = null;
+        }
+        rows[ i ] = r;
+    }
+
+    // Pre-allocate batch array that references row objects.
+    // We'll adjust its length per batch but never reallocate.
+    // slice() here is a one-time shallow copy of references.
+    const batch = rows.slice();
+
+    // Cache MQTT properties to avoid repeated calls.
+    // These properties hint the wire format to subscribers.
+    const props = codec.properties || {};
+
+    /**
+     * Encode source rows into a compressed batch payload.
+     *
+     * Design decisions:
+     *   - Copy values field-by-field to maintain stable shape
+     *   - Preserve null but normalize undefined to null
+     *   - Reuse pre-allocated objects to avoid GC
+     *   - Temporarily adjust batch.length without reallocation
+     *
+     * @param {string} producerId - Identifies the data source (e.g., device ID)
+     * @param {number} seq - Sequence number for gap detection on receiver side
+     * @param {Array} srcRows - Source rows to encode (not modified)
+     * @param {number} count - Number of rows to encode (may be < srcRows.length)
+     *
+     * @returns {Object} { payload: Uint8Array|Buffer, props: Object }
+     *                   payload: Compressed binary data
+     *                   props: MQTT v5 properties for content type hint
+     */
+    const encode = function ( producerId, seq, srcRows, count ) {
+        // Validate count doesn't exceed pre-allocated capacity
+        if ( count > maxRows ) {
+            throw new Error( `Cannot encode ${count} rows, max capacity is ${maxRows}` );
+        }
+
+        // Copy source data into pre-allocated row objects
+        for ( let i = 0; i < count; i += 1 ) {
+            const src = srcRows[ i ];
+            const dst = rows[ i ];
+
+            // Copy only declared fields in consistent order
+            for ( let k = 0; k < fieldOrder.length; k += 1 ) {
+                const key = fieldOrder[ k ];
+                const v = src[ key ];
+                // FIXED: Normalize undefined to null for consistent serialization
+                dst[ key ] = ( v === undefined ) ? null : v;
+            }
+
+            // Point batch array to this row (reference, not copy)
+            batch[ i ] = dst;
+        }
+
+        // Temporarily adjust batch length for this encoding
+        const cap = batch.length;
+        batch.length = count;
+
+        // Pack the message with consistent structure
+        const payload = codec.pack( {
+            producerId: producerId,
+            seq: seq,
+            items: batch
+        } );
+
+        // Restore batch array to full capacity for next call
+        batch.length = cap;
+
+        return {
+            payload: payload,
+            props: props
+        };
+    }; // encode()
+
+    // Public API
+    // Expose encode function and field order for reference.
+    // slice() returns a defensive copy of fieldOrder.
+    return {
+        encode: encode,
+        fieldOrder: fieldOrder.slice()
+    };
+};

package/src/core/batch/index.js

@@ -0,0 +1,12 @@
+// core/batch/index.js
+// Purpose:
+//   Batch data handling subsystem for efficient transmission of tabular data.
+//   Provides sliding windows for history retention and encoders for compression.
+
+export { createAooEncoder } from './aoo-encoder.js';
+export { createWindow } from './sliding-window.js';
+
+// These work together:
+// 1. Window maintains recent history (sliding-window.js)
+// 2. Encoder compresses for transmission (aoo-encoder.js)
+// 3. Both use same field order for structure stability

package/src/core/batch/sliding-window.js

@@ -0,0 +1,91 @@
+// core/batch/sliding-window.js
+// Purpose:
+//   Fixed-capacity sliding window for retaining recent data snapshots.
+//   Designed for "first paint" scenarios where new subscribers need recent history.
+//   Maintains a circular buffer of rows with stable object shapes.
+
+export const createWindow = function ( capacity, fieldOrder ) {
+    // Input validation
+    if ( !capacity || capacity <= 0 ) {
+        throw new Error( 'capacity must be positive integer' );
+    }
+    if ( !Array.isArray( fieldOrder ) || fieldOrder.length === 0 ) {
+        throw new Error( 'fieldOrder must be non-empty array' );
+    }
+
+    // Pre-allocate all row objects with stable shape
+    const rows = new Array( capacity );
+    for ( let i = 0; i < capacity; i += 1 ) {
+        const r = Object.create( null );
+        // Initialize all fields to null for consistent shape
+        for ( let k = 0; k < fieldOrder.length; k += 1 ) {
+            r[ fieldOrder[ k ] ] = null;
+        }
+        rows[ i ] = r;
+    }
+
+    // Circular buffer state:
+    // - head: next write position [0, capacity)
+    // - count: total items in window (capped at capacity)
+    let head = 0;
+    let count = 0;
+
+    /**
+     * Add a new row to the window, evicting oldest if at capacity.
+     */
+    const put = function ( src ) {
+        // Get pre-allocated row at current position
+        const dst = rows[ head ];
+
+        // Copy only declared fields in order
+        for ( let k = 0; k < fieldOrder.length; k += 1 ) {
+            const key = fieldOrder[ k ];
+            const v = src[ key ];
+            // FIXED: Normalize undefined to null for consistent serialization
+            dst[ key ] = ( v === undefined ) ? null : v;
+        }
+
+        // Advance head with wraparound
+        head = ( head + 1 ) % capacity;
+
+        // Track fill level (stops growing at capacity)
+        if ( count < capacity ) count += 1;
+    };
+
+    /**
+     * Extract recent rows from window in FIFO order (oldest to newest).
+     * Returns the most recent 'max' rows or all available rows if less than max.
+     */
+    const toRows = function ( out, max ) {
+        // Determine how many rows we can actually provide
+        const take = Math.min( count, max );
+
+        if ( take === 0 ) return 0;
+
+        // Calculate starting position for oldest data we want to return
+        let idx;
+        if ( count < capacity ) {
+            // Window not full: we have 'count' items starting from 0
+            // To get the most recent 'take' items, start from (count - take)
+            idx = Math.max( 0, count - take );
+        } else {
+            // Window full: head points to next write position (oldest data)
+            // To get the most recent 'take' items, go back 'take' positions
+            idx = ( head - take + capacity ) % capacity;
+        }
+
+        // Copy row references to output array in chronological order
+        for ( let i = 0; i < take; i += 1 ) {
+            out[ i ] = rows[ idx ];
+            idx = ( idx + 1 ) % capacity;
+        }
+
+        return take;
+    };
+
+    // Public API
+    return {
+        put: put,
+        toRows: toRows
+    };
+};