@kntnt/engagement-metrics 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kntnt Sweden AB
+
+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,55 @@
+# @kntnt/engagement-metrics
+
+Lightweight client-side library that measures how deeply users engage with text content on web pages — distinguishing *reading* (pausing on visible content) from *scanning* (scrolling through). Zero runtime dependencies.
+
+## Installation
+
+```bash
+npm install @kntnt/engagement-metrics
+```
+
+## Usage
+
+### ESM (bundler)
+
+```js
+import { createMeasurer } from '@kntnt/engagement-metrics'
+
+const measurer = createMeasurer({
+  selector: 'p',
+  readingSpeed: 1380,
+})
+
+measurer.addListener({
+  update(metrics) {
+    console.log(`Reading: ${(metrics.readingRatio * 100).toFixed(0)}%`)
+  },
+})
+
+measurer.start()
+```
+
+### IIFE (script tag)
+
+```html
+<script src="https://unpkg.com/@kntnt/engagement-metrics/dist/kntnt-engagement-metrics.min.js"></script>
+<script>
+  KntntEngagementMetrics.measurer = KntntEngagementMetrics.start({ selector: 'article p' })
+</script>
+```
+
+## Add-ons
+
+Use the core with one or more analytics add-ons:
+
+- [`@kntnt/engagement-metrics-matomo`](https://www.npmjs.com/package/@kntnt/engagement-metrics-matomo) — Matomo Analytics
+- [`@kntnt/engagement-metrics-gtag`](https://www.npmjs.com/package/@kntnt/engagement-metrics-gtag) — Google Analytics 4
+- [`@kntnt/engagement-metrics-overlay`](https://www.npmjs.com/package/@kntnt/engagement-metrics-overlay) — Visual overlay for debugging and demos
+
+## Documentation
+
+See the [main repository](https://github.com/Kntnt/kntnt-engagement-metrics) for full documentation, configuration options, and the algorithm specification.
+
+## License
+
+[MIT](https://github.com/Kntnt/kntnt-engagement-metrics/blob/main/LICENSE) — Copyright (c) 2026 Kntnt Sweden AB

package/dist/element.d.ts

@@ -0,0 +1,49 @@
+import { Timer } from './timer.js';
+/**
+ * Tracks a single content element's visibility and reading state.
+ */
+export declare class TrackedElement {
+    #private;
+    readonly node: Element;
+    readonly timer: Timer;
+    readonly charCount: number;
+    /**
+     * @param node - The DOM element to track.
+     * @param readingSpeed - Reading speed in characters per minute.
+     */
+    constructor(node: Element, readingSpeed: number);
+    /** Current visibility ratio (0–1) as reported by IntersectionObserver. */
+    get visibilityRatio(): number;
+    /** Whether this element has ever been visible in the viewport. */
+    get hasBeenSeen(): boolean;
+    /** Whether the reading timer for this element has completed. */
+    get isFullyRead(): boolean;
+    /** Reading progress for this element (0–1). */
+    get readingProgress(): number;
+    /** Cumulative fraction (0–1) of this element that has ever been visible. */
+    get seenRatio(): number;
+    /** The merged seen intervals, for diagnostic/overlay use. */
+    get seenIntervals(): ReadonlyArray<readonly [number, number]>;
+    /** Start of the currently visible interval (0 = element top, 1 = element bottom). */
+    get visibleStart(): number;
+    /** End of the currently visible interval (0 = element top, 1 = element bottom). */
+    get visibleEnd(): number;
+    /**
+     * Precomputed targetRatio based on the visible interval at the time of the last
+     * IO callback. Snapshots timer progress so the ceiling doesn't slide as the
+     * timer advances between callbacks.
+     */
+    get computedTargetRatio(): number;
+    /**
+     * Record a visible interval for this element.
+     * @internal Used by Measurer — add-ons and external code must not call this.
+     */
+    addSeenInterval(start: number, end: number): void;
+    /**
+     * Update visibility state from an IntersectionObserver entry.
+     * Computes the visible interval, accumulates it into seen intervals, and
+     * snapshots the targetRatio based on current timer progress.
+     */
+    updateVisibility(entry: IntersectionObserverEntry): void;
+}
+//# sourceMappingURL=element.d.ts.map

package/dist/element.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element.d.ts","sourceRoot":"","sources":["../src/element.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAElC;;GAEG;AACH,qBAAa,cAAc;;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAS1B;;;OAGG;gBACS,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM;IAO/C,0EAA0E;IAC1E,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED,kEAAkE;IAClE,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,gEAAgE;IAChE,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,+CAA+C;IAC/C,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED,4EAA4E;IAC5E,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,6DAA6D;IAC7D,IAAI,aAAa,IAAI,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAE5D;IAED,qFAAqF;IACrF,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,mFAAmF;IACnF,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;;OAIG;IACH,IAAI,mBAAmB,IAAI,MAAM,CAEhC;IAED;;;OAGG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAIjD;;;;OAIG;IACH,gBAAgB,CAAC,KAAK,EAAE,yBAAyB,GAAG,IAAI;CA8BzD"}

package/dist/iife.d.ts

@@ -0,0 +1,6 @@
+/**
+ * IIFE entry point for browser script-tag usage.
+ * Exposes `window.KntntEngagementMetrics` global namespace.
+ */
+export {};
+//# sourceMappingURL=iife.d.ts.map

package/dist/iife.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"iife.d.ts","sourceRoot":"","sources":["../src/iife.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @kntnt/engagement-metrics
+ *
+ * Lightweight library that measures how deeply users engage with
+ * content on web pages — reading vs. scanning, time spent, and
+ * completion rate.
+ *
+ * @packageDocumentation
+ */
+import { Measurer } from './measurer.js';
+import type { MeasurerConfig } from './types.js';
+export { TrackedElement } from './element.js';
+export { IntervalSet } from './interval-set.js';
+export { Measurer } from './measurer.js';
+export type { EngagementMetrics, MeasurerConfig, MetricsListener } from './types.js';
+/**
+ * Convenience factory function that creates a new Measurer instance.
+ *
+ * @param config - Partial configuration (defaults are applied for missing values).
+ * @returns A new Measurer instance, ready to be started.
+ *
+ * @example
+ * ```ts
+ * import { createMeasurer } from '@kntnt/engagement-metrics'
+ *
+ * const measurer = createMeasurer({ selector: 'article p' })
+ * measurer.start()
+ * ```
+ */
+export declare function createMeasurer(config?: Partial<MeasurerConfig>): Measurer;
+//# 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;;;;;;;;GAQG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEpF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,QAAQ,CAEzE"}

package/dist/index.js

@@ -0,0 +1,435 @@
+// src/interval-set.ts
+class IntervalSet {
+  #intervals = [];
+  add(start, end) {
+    if (!Number.isFinite(start) || !Number.isFinite(end))
+      return;
+    const s = Math.max(0, Math.min(1, start));
+    const e = Math.max(0, Math.min(1, end));
+    if (s >= e)
+      return;
+    if (this.coverage >= 1)
+      return;
+    this.#intervals.push([s, e]);
+    this.#merge();
+  }
+  get coverage() {
+    let total = 0;
+    for (const [s, e] of this.#intervals) {
+      total += e - s;
+    }
+    return total;
+  }
+  get size() {
+    return this.#intervals.length;
+  }
+  get intervals() {
+    return this.#intervals.map(([s, e]) => [s, e]);
+  }
+  clear() {
+    this.#intervals.length = 0;
+  }
+  #merge() {
+    const iv = this.#intervals;
+    iv.sort((a, b) => a[0] - b[0]);
+    let write = 0;
+    for (let read = 1;read < iv.length; read++) {
+      const cur = iv[write];
+      const next = iv[read];
+      if (next[0] <= cur[1]) {
+        cur[1] = Math.max(cur[1], next[1]);
+      } else {
+        write++;
+        iv[write] = next;
+      }
+    }
+    iv.length = write + 1;
+  }
+}
+
+// src/timer.ts
+class Timer {
+  #initialDuration;
+  #remaining;
+  #targetRatio;
+  constructor(durationSeconds) {
+    this.#initialDuration = Math.max(0, durationSeconds);
+    this.#remaining = this.#initialDuration;
+    this.#targetRatio = 1;
+  }
+  get initialDuration() {
+    return this.#initialDuration;
+  }
+  get remaining() {
+    return this.#remaining;
+  }
+  get isComplete() {
+    return this.#remaining <= 0;
+  }
+  get progress() {
+    if (this.#initialDuration === 0)
+      return 1;
+    return 1 - this.#remaining / this.#initialDuration;
+  }
+  get targetRatio() {
+    return this.#targetRatio;
+  }
+  set targetRatio(value) {
+    if (!Number.isFinite(value) || value < 0 || value > 1)
+      return;
+    this.#targetRatio = value;
+  }
+  get isAtTarget() {
+    if (this.#initialDuration === 0)
+      return true;
+    return this.progress >= this.#targetRatio;
+  }
+  advance(seconds) {
+    const floor = this.#initialDuration * (1 - this.#targetRatio);
+    this.#remaining = Math.max(floor, this.#remaining - seconds);
+  }
+  recalibrate(newDurationSeconds) {
+    const currentProgress = this.progress;
+    this.#initialDuration = Math.max(0, newDurationSeconds);
+    this.#remaining = this.#initialDuration * (1 - currentProgress);
+  }
+}
+
+// src/element.ts
+class TrackedElement {
+  node;
+  timer;
+  charCount;
+  #visibilityRatio = 0;
+  #hasBeenSeen = false;
+  #seenIntervals = new IntervalSet;
+  #visibleStart = 0;
+  #visibleEnd = 0;
+  #computedTargetRatio = 0;
+  constructor(node, readingSpeed) {
+    this.node = node;
+    this.charCount = (node.textContent ?? "").length;
+    const durationSeconds = this.charCount > 0 ? this.charCount / readingSpeed * 60 : 0;
+    this.timer = new Timer(durationSeconds);
+  }
+  get visibilityRatio() {
+    return this.#visibilityRatio;
+  }
+  get hasBeenSeen() {
+    return this.#hasBeenSeen;
+  }
+  get isFullyRead() {
+    return this.timer.isComplete;
+  }
+  get readingProgress() {
+    return this.timer.progress;
+  }
+  get seenRatio() {
+    return this.#seenIntervals.coverage;
+  }
+  get seenIntervals() {
+    return this.#seenIntervals.intervals;
+  }
+  get visibleStart() {
+    return this.#visibleStart;
+  }
+  get visibleEnd() {
+    return this.#visibleEnd;
+  }
+  get computedTargetRatio() {
+    return this.#computedTargetRatio;
+  }
+  addSeenInterval(start, end) {
+    this.#seenIntervals.add(start, end);
+  }
+  updateVisibility(entry) {
+    this.#visibilityRatio = entry.intersectionRatio;
+    if (entry.isIntersecting && !this.#hasBeenSeen) {
+      this.#hasBeenSeen = true;
+    }
+    const rect = entry.boundingClientRect;
+    const rootBounds = entry.rootBounds;
+    if (rootBounds && rect.height > 0) {
+      const start = Math.max(0, Math.min(1, -rect.top / rect.height));
+      const end = Math.max(0, Math.min(1, (rootBounds.height - rect.top) / rect.height));
+      if (start < end) {
+        this.#visibleStart = start;
+        this.#visibleEnd = end;
+        this.#seenIntervals.add(start, end);
+        const progress = this.timer.progress;
+        const newReadable = Math.max(0, end - Math.max(start, progress));
+        this.#computedTargetRatio = Math.min(1, progress + newReadable);
+        return;
+      }
+    }
+    this.#visibleStart = 0;
+    this.#visibleEnd = 0;
+    this.#computedTargetRatio = this.timer.progress;
+  }
+}
+
+// src/measurer.ts
+var DEFAULTS = {
+  selector: "p",
+  exclude: "",
+  readingSpeed: 1380,
+  tickInterval: 200,
+  observerThresholds: [0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1],
+  scrollSpeedThreshold: 200,
+  scrollCooldown: 50
+};
+
+class Measurer {
+  #config;
+  #listeners = new Set;
+  #elements = [];
+  #elementMap = new Map;
+  #observer = null;
+  #animationFrameId = null;
+  #lastTickTime = 0;
+  #isScrolling = false;
+  #isPageVisible = true;
+  #isActive = false;
+  #scrollTimeoutId = null;
+  #lastScrollY = 0;
+  #lastScrollTime = 0;
+  #maxScanningDepth = 0;
+  constructor(config = {}) {
+    this.#config = { ...DEFAULTS, ...config };
+  }
+  get isActive() {
+    return this.#isActive;
+  }
+  addListener(listener) {
+    this.#listeners.add(listener);
+  }
+  removeListener(listener) {
+    this.#listeners.delete(listener);
+  }
+  start() {
+    if (this.#isActive)
+      return;
+    this.#elements.length = 0;
+    this.#elementMap.clear();
+    this.#maxScanningDepth = 0;
+    const nodes = this.#discoverNodes();
+    if (!nodes)
+      return;
+    for (const node of nodes) {
+      const tracked = new TrackedElement(node, this.#config.readingSpeed);
+      this.#elements.push(tracked);
+      this.#elementMap.set(node, tracked);
+    }
+    if (this.#elements.length === 0) {
+      console.warn("[kntnt-engagement-metrics] No content elements found for selector:", this.#config.selector);
+      return;
+    }
+    this.#observer = new IntersectionObserver((entries) => this.#handleIntersection(entries), {
+      threshold: this.#config.observerThresholds
+    });
+    for (const element of this.#elements) {
+      this.#observer.observe(element.node);
+    }
+    window.addEventListener("scroll", this.#handleScroll, { passive: true });
+    document.addEventListener("visibilitychange", this.#handleVisibilityChange);
+    this.#isActive = true;
+    this.#lastTickTime = performance.now();
+    this.#animationFrameId = requestAnimationFrame((t) => this.#tick(t));
+  }
+  stop() {
+    if (!this.#isActive)
+      return;
+    this.#isActive = false;
+    if (this.#animationFrameId !== null) {
+      cancelAnimationFrame(this.#animationFrameId);
+      this.#animationFrameId = null;
+    }
+    this.#observer?.disconnect();
+    this.#observer = null;
+    window.removeEventListener("scroll", this.#handleScroll);
+    document.removeEventListener("visibilitychange", this.#handleVisibilityChange);
+    if (this.#scrollTimeoutId !== null) {
+      clearTimeout(this.#scrollTimeoutId);
+      this.#scrollTimeoutId = null;
+    }
+  }
+  getMetrics() {
+    return this.#computeMetrics();
+  }
+  getElements() {
+    return this.#elements;
+  }
+  setReadingSpeed(charsPerMinute) {
+    if (!Number.isFinite(charsPerMinute) || charsPerMinute <= 0) {
+      console.warn("[kntnt-engagement-metrics] Invalid reading speed:", charsPerMinute);
+      return;
+    }
+    for (const element of this.#elements) {
+      const newDuration = element.charCount > 0 ? element.charCount / charsPerMinute * 60 : 0;
+      element.timer.recalibrate(newDuration);
+    }
+  }
+  setScrollCooldown(ms) {
+    if (!Number.isFinite(ms) || ms < 0) {
+      console.warn("[kntnt-engagement-metrics] Invalid scroll cooldown:", ms);
+      return;
+    }
+    this.#config = { ...this.#config, scrollCooldown: ms };
+  }
+  setScrollSpeedThreshold(pxPerSec) {
+    if (!Number.isFinite(pxPerSec) || pxPerSec <= 0) {
+      console.warn("[kntnt-engagement-metrics] Invalid scroll speed threshold:", pxPerSec);
+      return;
+    }
+    this.#config = { ...this.#config, scrollSpeedThreshold: pxPerSec };
+  }
+  #discoverNodes() {
+    let nodes;
+    try {
+      nodes = document.querySelectorAll(this.#config.selector);
+    } catch {
+      console.warn("[kntnt-engagement-metrics] Invalid selector:", this.#config.selector);
+      return null;
+    }
+    const { exclude } = this.#config;
+    const result = [];
+    for (const node of nodes) {
+      if (exclude && this.#isExcluded(node, exclude))
+        continue;
+      if (!("offsetHeight" in node) || node.offsetHeight === 0)
+        continue;
+      if ((node.textContent ?? "").length === 0)
+        continue;
+      result.push(node);
+    }
+    return result;
+  }
+  #isExcluded(node, exclude) {
+    try {
+      return node.closest(exclude) !== null;
+    } catch {
+      console.warn("[kntnt-engagement-metrics] Invalid exclude selector:", exclude);
+      return true;
+    }
+  }
+  #handleIntersection(entries) {
+    for (const entry of entries) {
+      const element = this.#elementMap.get(entry.target);
+      if (!element)
+        continue;
+      const wasSeen = element.hasBeenSeen;
+      element.updateVisibility(entry);
+      if (!wasSeen && element.hasBeenSeen && element.node.isConnected) {
+        const rect = element.node.getBoundingClientRect();
+        const elementBottom = rect.bottom + window.scrollY;
+        if (elementBottom > this.#maxScanningDepth) {
+          this.#maxScanningDepth = elementBottom;
+        }
+      }
+    }
+  }
+  #handleScroll = () => {
+    const now = performance.now();
+    const scrollY = window.scrollY;
+    const timeDelta = now - this.#lastScrollTime;
+    const distance = Math.abs(scrollY - this.#lastScrollY);
+    if (timeDelta > 0) {
+      const speed = distance / timeDelta * 1000;
+      if (speed > this.#config.scrollSpeedThreshold) {
+        this.#isScrolling = true;
+      }
+    }
+    this.#lastScrollY = scrollY;
+    this.#lastScrollTime = now;
+    if (this.#scrollTimeoutId !== null) {
+      clearTimeout(this.#scrollTimeoutId);
+    }
+    this.#scrollTimeoutId = setTimeout(() => {
+      this.#isScrolling = false;
+      this.#scrollTimeoutId = null;
+    }, this.#config.scrollCooldown);
+  };
+  #handleVisibilityChange = () => {
+    this.#isPageVisible = document.visibilityState === "visible";
+  };
+  #tick(timestamp) {
+    if (!this.#isActive)
+      return;
+    if (timestamp - this.#lastTickTime >= this.#config.tickInterval) {
+      this.#advanceTimers();
+      const metrics = this.#notifyListeners();
+      this.#lastTickTime = timestamp;
+      if (metrics.readingRatio >= 1 && metrics.scanningRatio >= 1) {
+        this.stop();
+        return;
+      }
+    }
+    this.#animationFrameId = requestAnimationFrame((t) => this.#tick(t));
+  }
+  #advanceTimers() {
+    if (!this.#isPageVisible || this.#isScrolling)
+      return;
+    const elapsed = this.#config.tickInterval / 1000;
+    for (const element of this.#elements) {
+      if (element.isFullyRead)
+        continue;
+      if (element.visibilityRatio === 0)
+        continue;
+      element.timer.targetRatio = element.computedTargetRatio;
+      if (element.timer.isAtTarget)
+        continue;
+      element.timer.advance(elapsed);
+      return;
+    }
+  }
+  #notifyListeners() {
+    const metrics = this.#computeMetrics();
+    for (const listener of this.#listeners) {
+      try {
+        listener.update(metrics);
+      } catch (e) {
+        console.warn("[kntnt-engagement-metrics] Listener error:", e);
+      }
+    }
+    return metrics;
+  }
+  #computeMetrics() {
+    let readingTime = 0;
+    let contentTime = 0;
+    let readingLength = 0;
+    let contentLength = 0;
+    for (const element of this.#elements) {
+      const timerProgress = element.readingProgress;
+      readingTime += element.timer.initialDuration * timerProgress;
+      contentTime += element.timer.initialDuration;
+      readingLength += element.charCount * timerProgress;
+      contentLength += element.charCount;
+    }
+    const scanningDepth = this.#maxScanningDepth;
+    const contentDepth = document.documentElement.scrollHeight - window.innerHeight;
+    const readingRatio = contentLength > 0 ? readingLength / contentLength : 0;
+    const scanningRatio = contentDepth > 0 ? Math.min(1, scanningDepth / contentDepth) : 0;
+    return {
+      readingTime,
+      contentTime,
+      readingLength,
+      contentLength,
+      scanningDepth,
+      contentDepth,
+      readingRatio,
+      scanningRatio,
+      isActive: this.#isActive
+    };
+  }
+}
+
+// src/index.ts
+function createMeasurer(config) {
+  return new Measurer(config);
+}
+export {
+  createMeasurer,
+  TrackedElement,
+  Measurer,
+  IntervalSet
+};

package/dist/interval-set.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Accumulates [start, end] intervals in the range 0–1 and merges overlapping
+ * or adjacent ones. Used to track which fraction of a content element has
+ * ever been visible in the viewport.
+ */
+export declare class IntervalSet {
+    #private;
+    /**
+     * Add a visible interval. Values are clamped to [0, 1].
+     * Degenerate, NaN, and Infinity inputs are silently ignored.
+     */
+    add(start: number, end: number): void;
+    /** Total covered fraction (0–1). */
+    get coverage(): number;
+    /** Number of disjoint intervals currently stored. */
+    get size(): number;
+    /** The merged intervals, for diagnostic/overlay use. */
+    get intervals(): ReadonlyArray<readonly [number, number]>;
+    /** Reset to empty. */
+    clear(): void;
+}
+//# sourceMappingURL=interval-set.d.ts.map

package/dist/interval-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interval-set.d.ts","sourceRoot":"","sources":["../src/interval-set.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,WAAW;;IAGtB;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAkBrC,oCAAoC;IACpC,IAAI,QAAQ,IAAI,MAAM,CAMrB;IAED,qDAAqD;IACrD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,wDAAwD;IACxD,IAAI,SAAS,IAAI,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAExD;IAED,sBAAsB;IACtB,KAAK,IAAI,IAAI;CAwBd"}

package/dist/kntnt-engagement-metrics.min.js

@@ -0,0 +1 @@
+var k="1.0.0";class X{#K=[];add(K,q){if(!Number.isFinite(K)||!Number.isFinite(q))return;let z=Math.max(0,Math.min(1,K)),G=Math.max(0,Math.min(1,q));if(z>=G)return;if(this.coverage>=1)return;this.#K.push([z,G]),this.#z()}get coverage(){let K=0;for(let[q,z]of this.#K)K+=z-q;return K}get size(){return this.#K.length}get intervals(){return this.#K.map(([K,q])=>[K,q])}clear(){this.#K.length=0}#z(){let K=this.#K;K.sort((z,G)=>z[0]-G[0]);let q=0;for(let z=1;z<K.length;z++){let G=K[q],H=K[z];if(H[0]<=G[1])G[1]=Math.max(G[1],H[1]);else q++,K[q]=H}K.length=q+1}}class Z{#K;#z;#q;constructor(K){this.#K=Math.max(0,K),this.#z=this.#K,this.#q=1}get initialDuration(){return this.#K}get remaining(){return this.#z}get isComplete(){return this.#z<=0}get progress(){if(this.#K===0)return 1;return 1-this.#z/this.#K}get targetRatio(){return this.#q}set targetRatio(K){if(!Number.isFinite(K)||K<0||K>1)return;this.#q=K}get isAtTarget(){if(this.#K===0)return!0;return this.progress>=this.#q}advance(K){let q=this.#K*(1-this.#q);this.#z=Math.max(q,this.#z-K)}recalibrate(K){let q=this.progress;this.#K=Math.max(0,K),this.#z=this.#K*(1-q)}}class _{node;timer;charCount;#K=0;#z=!1;#q=new X;#J=0;#H=0;#G=0;constructor(K,q){this.node=K,this.charCount=(K.textContent??"").length;let z=this.charCount>0?this.charCount/q*60:0;this.timer=new Z(z)}get visibilityRatio(){return this.#K}get hasBeenSeen(){return this.#z}get isFullyRead(){return this.timer.isComplete}get readingProgress(){return this.timer.progress}get seenRatio(){return this.#q.coverage}get seenIntervals(){return this.#q.intervals}get visibleStart(){return this.#J}get visibleEnd(){return this.#H}get computedTargetRatio(){return this.#G}addSeenInterval(K,q){this.#q.add(K,q)}updateVisibility(K){if(this.#K=K.intersectionRatio,K.isIntersecting&&!this.#z)this.#z=!0;let{boundingClientRect:q,rootBounds:z}=K;if(z&&q.height>0){let G=Math.max(0,Math.min(1,-q.top/q.height)),H=Math.max(0,Math.min(1,(z.height-q.top)/q.height));if(G<H){this.#J=G,this.#H=H,this.#q.add(G,H);let J=this.timer.progress,W=Math.max(0,H-Math.max(G,J));this.#G=Math.min(1,J+W);return}}this.#J=0,this.#H=0,this.#G=this.timer.progress}}var E={selector:"p",exclude:"",readingSpeed:1380,tickInterval:200,observerThresholds:[0,0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,0.9,1],scrollSpeedThreshold:200,scrollCooldown:50};class ${#K;#z=new Set;#q=[];#J=new Map;#H=null;#G=null;#Z=0;#_=!1;#$=!0;#Q=!1;#W=null;#j=0;#k=0;#X=0;constructor(K={}){this.#K={...E,...K}}get isActive(){return this.#Q}addListener(K){this.#z.add(K)}removeListener(K){this.#z.delete(K)}start(){if(this.#Q)return;this.#q.length=0,this.#J.clear(),this.#X=0;let K=this.#N();if(!K)return;for(let q of K){let z=new _(q,this.#K.readingSpeed);this.#q.push(z),this.#J.set(q,z)}if(this.#q.length===0){console.warn("[kntnt-engagement-metrics] No content elements found for selector:",this.#K.selector);return}this.#H=new IntersectionObserver((q)=>this.#Y(q),{threshold:this.#K.observerThresholds});for(let q of this.#q)this.#H.observe(q.node);window.addEventListener("scroll",this.#C,{passive:!0}),document.addEventListener("visibilitychange",this.#O),this.#Q=!0,this.#Z=performance.now(),this.#G=requestAnimationFrame((q)=>this.#U(q))}stop(){if(!this.#Q)return;if(this.#Q=!1,this.#G!==null)cancelAnimationFrame(this.#G),this.#G=null;if(this.#H?.disconnect(),this.#H=null,window.removeEventListener("scroll",this.#C),document.removeEventListener("visibilitychange",this.#O),this.#W!==null)clearTimeout(this.#W),this.#W=null}getMetrics(){return this.#E()}getElements(){return this.#q}setReadingSpeed(K){if(!Number.isFinite(K)||K<=0){console.warn("[kntnt-engagement-metrics] Invalid reading speed:",K);return}for(let q of this.#q){let z=q.charCount>0?q.charCount/K*60:0;q.timer.recalibrate(z)}}setScrollCooldown(K){if(!Number.isFinite(K)||K<0){console.warn("[kntnt-engagement-metrics] Invalid scroll cooldown:",K);return}this.#K={...this.#K,scrollCooldown:K}}setScrollSpeedThreshold(K){if(!Number.isFinite(K)||K<=0){console.warn("[kntnt-engagement-metrics] Invalid scroll speed threshold:",K);return}this.#K={...this.#K,scrollSpeedThreshold:K}}#N(){let K;try{K=document.querySelectorAll(this.#K.selector)}catch{return console.warn("[kntnt-engagement-metrics] Invalid selector:",this.#K.selector),null}let{exclude:q}=this.#K,z=[];for(let G of K){if(q&&this.#y(G,q))continue;if(!("offsetHeight"in G)||G.offsetHeight===0)continue;if((G.textContent??"").length===0)continue;z.push(G)}return z}#y(K,q){try{return K.closest(q)!==null}catch{return console.warn("[kntnt-engagement-metrics] Invalid exclude selector:",q),!0}}#Y(K){for(let q of K){let z=this.#J.get(q.target);if(!z)continue;let G=z.hasBeenSeen;if(z.updateVisibility(q),!G&&z.hasBeenSeen&&z.node.isConnected){let J=z.node.getBoundingClientRect().bottom+window.scrollY;if(J>this.#X)this.#X=J}}}#C=()=>{let K=performance.now(),q=window.scrollY,z=K-this.#k,G=Math.abs(q-this.#j);if(z>0){if(G/z*1000>this.#K.scrollSpeedThreshold)this.#_=!0}if(this.#j=q,this.#k=K,this.#W!==null)clearTimeout(this.#W);this.#W=setTimeout(()=>{this.#_=!1,this.#W=null},this.#K.scrollCooldown)};#O=()=>{this.#$=document.visibilityState==="visible"};#U(K){if(!this.#Q)return;if(K-this.#Z>=this.#K.tickInterval){this.#V();let q=this.#B();if(this.#Z=K,q.readingRatio>=1&&q.scanningRatio>=1){this.stop();return}}this.#G=requestAnimationFrame((q)=>this.#U(q))}#V(){if(!this.#$||this.#_)return;let K=this.#K.tickInterval/1000;for(let q of this.#q){if(q.isFullyRead)continue;if(q.visibilityRatio===0)continue;if(q.timer.targetRatio=q.computedTargetRatio,q.timer.isAtTarget)continue;q.timer.advance(K);return}}#B(){let K=this.#E();for(let q of this.#z)try{q.update(K)}catch(z){console.warn("[kntnt-engagement-metrics] Listener error:",z)}return K}#E(){let K=0,q=0,z=0,G=0;for(let Q of this.#q){let j=Q.readingProgress;K+=Q.timer.initialDuration*j,q+=Q.timer.initialDuration,z+=Q.charCount*j,G+=Q.charCount}let H=this.#X,J=document.documentElement.scrollHeight-window.innerHeight,W=G>0?z/G:0,O=J>0?Math.min(1,H/J):0;return{readingTime:K,contentTime:q,readingLength:z,contentLength:G,scanningDepth:H,contentDepth:J,readingRatio:W,scanningRatio:O,isActive:this.#Q}}}function C(K){return new $(K)}function N(K){let q=C(K);if(document.readyState==="loading")document.addEventListener("DOMContentLoaded",()=>q.start());else q.start();return q}var y=window.KntntEngagementMetrics;if(y)console.warn("[kntnt-engagement-metrics] Already loaded, skipping duplicate initialization");else{let K={createMeasurer:C,start:N,version:k,measurer:null};window.KntntEngagementMetrics=K}

package/dist/measurer.d.ts

@@ -0,0 +1,47 @@
+import { TrackedElement } from './element.js';
+import type { EngagementMetrics, MeasurerConfig, MetricsListener } from './types.js';
+/**
+ * Central orchestrator for engagement measurement.
+ *
+ * Discovers content elements in the DOM, tracks their visibility via
+ * IntersectionObserver, and runs a measurement tick loop that estimates
+ * reading progress. Notifies registered listeners on each tick.
+ */
+export declare class Measurer {
+    #private;
+    constructor(config?: Partial<MeasurerConfig>);
+    /** True if measurement is currently running. */
+    get isActive(): boolean;
+    /** Register a metrics listener. */
+    addListener(listener: MetricsListener): void;
+    /** Remove a previously registered listener. */
+    removeListener(listener: MetricsListener): void;
+    /** Start measuring. Call after the DOM is ready. */
+    start(): void;
+    /** Stop measuring and clean up all observers and listeners. */
+    stop(): void;
+    /** Get the current metrics snapshot. */
+    getMetrics(): EngagementMetrics;
+    /** Expose tracked elements for visualization or diagnostic purposes. */
+    getElements(): ReadonlyArray<TrackedElement>;
+    /**
+     * Change the reading speed and recalibrate all element timers.
+     * Preserves each element's current reading progress.
+     *
+     * @param charsPerMinute - New reading speed in characters per minute. Must be a positive number.
+     */
+    setReadingSpeed(charsPerMinute: number): void;
+    /**
+     * Change the scroll cooldown duration at runtime.
+     *
+     * @param ms - Cooldown in milliseconds. Must be a non-negative finite number.
+     */
+    setScrollCooldown(ms: number): void;
+    /**
+     * Change the scroll speed threshold at runtime.
+     *
+     * @param pxPerSec - Minimum scroll speed in pixels per second. Must be a positive finite number.
+     */
+    setScrollSpeedThreshold(pxPerSec: number): void;
+}
+//# sourceMappingURL=measurer.d.ts.map

package/dist/measurer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measurer.d.ts","sourceRoot":"","sources":["../src/measurer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAYpF;;;;;;GAMG;AACH,qBAAa,QAAQ;;gBAiBP,MAAM,GAAE,OAAO,CAAC,cAAc,CAAM;IAIhD,gDAAgD;IAChD,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,mCAAmC;IACnC,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAI5C,+CAA+C;IAC/C,cAAc,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAI/C,oDAAoD;IACpD,KAAK,IAAI,IAAI;IA+Cb,+DAA+D;IAC/D,IAAI,IAAI,IAAI;IAqBZ,wCAAwC;IACxC,UAAU,IAAI,iBAAiB;IAI/B,wEAAwE;IACxE,WAAW,IAAI,aAAa,CAAC,cAAc,CAAC;IAI5C;;;;;OAKG;IACH,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI;IAY7C;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAQnC;;;;OAIG;IACH,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;CA0KhD"}

package/dist/timer.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A countdown timer that represents the estimated reading time for a content element.
+ * Supports a target-ratio cap: advance() will not push progress beyond the
+ * configured targetRatio, modelling "read up to the visible boundary" semantics.
+ */
+export declare class Timer {
+    #private;
+    /**
+     * @param durationSeconds - Estimated reading time in seconds.
+     */
+    constructor(durationSeconds: number);
+    /** The original estimated reading time in seconds. */
+    get initialDuration(): number;
+    /** Remaining time in seconds. */
+    get remaining(): number;
+    /** Whether the timer has reached zero. */
+    get isComplete(): boolean;
+    /** Reading progress as a ratio (0–1). */
+    get progress(): number;
+    /**
+     * Maximum progress (0–1) that advance() is allowed to reach.
+     * Set by the measurer to match the element's visibility ratio.
+     *
+     * @internal Used by Measurer — add-ons and external code must not set this.
+     */
+    get targetRatio(): number;
+    /** @internal */
+    set targetRatio(value: number);
+    /** Whether progress has reached or exceeded the current targetRatio. */
+    get isAtTarget(): boolean;
+    /**
+     * Advance the timer by the given number of seconds.
+     * The timer will not go below zero, and remaining will not drop
+     * below `initialDuration * (1 - targetRatio)`.
+     */
+    advance(seconds: number): void;
+    /**
+     * Recalibrate the timer with a new duration, preserving current progress.
+     * If progress is 60% and new duration is 10s, remaining becomes 4s.
+     *
+     * @param newDurationSeconds - New estimated reading time in seconds.
+     */
+    recalibrate(newDurationSeconds: number): void;
+}
+//# sourceMappingURL=timer.d.ts.map

package/dist/timer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer.d.ts","sourceRoot":"","sources":["../src/timer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,qBAAa,KAAK;;IAKhB;;OAEG;gBACS,eAAe,EAAE,MAAM;IAMnC,sDAAsD;IACtD,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED,iCAAiC;IACjC,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,0CAA0C;IAC1C,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,yCAAyC;IACzC,IAAI,QAAQ,IAAI,MAAM,CAGrB;IAED;;;;;OAKG;IACH,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,gBAAgB;IAChB,IAAI,WAAW,CAAC,KAAK,EAAE,MAAM,EAG5B;IAED,wEAAwE;IACxE,IAAI,UAAU,IAAI,OAAO,CAGxB;IAED;;;;OAIG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK9B;;;;;OAKG;IACH,WAAW,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI;CAK9C"}

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Configuration for the engagement metrics measurer.
+ * All fields are optional — defaults are applied for missing values.
+ */
+export interface MeasurerConfig {
+    /** CSS selector for content elements. Default: `'p'` */
+    readonly selector: string;
+    /** CSS selector for elements to exclude. Any element matched by `selector` is excluded if it matches `exclude` itself or has an ancestor matching `exclude`. Default: `''` (no exclusions) */
+    readonly exclude: string;
+    /** Average reading speed in characters per minute. Default: `1380` */
+    readonly readingSpeed: number;
+    /** Milliseconds between measurement ticks. Default: `200` */
+    readonly tickInterval: number;
+    /** IntersectionObserver threshold steps (array of ratios 0–1). Default: `[0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0]` */
+    readonly observerThresholds: number[];
+    /** Minimum scroll speed (px/sec) to count as active scrolling. Default: `200` */
+    readonly scrollSpeedThreshold: number;
+    /** Milliseconds after last scroll event before reading resumes. Default: `50` */
+    readonly scrollCooldown: number;
+}
+/**
+ * Snapshot of engagement metrics at a point in time.
+ */
+export interface EngagementMetrics {
+    /** Estimated seconds of actual reading so far. */
+    readonly readingTime: number;
+    /** Total estimated reading time for all content (seconds). */
+    readonly contentTime: number;
+    /** Estimated characters read so far. */
+    readonly readingLength: number;
+    /** Total characters across all content elements. */
+    readonly contentLength: number;
+    /** Maximum vertical scroll position reached (pixels). */
+    readonly scanningDepth: number;
+    /** Total scrollable content height (pixels). */
+    readonly contentDepth: number;
+    /** `readingLength / contentLength` (0–1). */
+    readonly readingRatio: number;
+    /** `scanningDepth / contentDepth` (0–1, capped at 1). */
+    readonly scanningRatio: number;
+    /** True if measurement is still running. */
+    readonly isActive: boolean;
+}
+/**
+ * Interface for consumers of engagement metrics.
+ * Implement this to receive metric updates on each measurement tick.
+ */
+export interface MetricsListener {
+    /** Called on each measurement tick with a fresh metrics snapshot. */
+    update(metrics: EngagementMetrics): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IAEzB,8LAA8L;IAC9L,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IAExB,sEAAsE;IACtE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAE7B,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAE7B,mIAAmI;IACnI,QAAQ,CAAC,kBAAkB,EAAE,MAAM,EAAE,CAAA;IAErC,iFAAiF;IACjF,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAA;IAErC,iFAAiF;IACjF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAE5B,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAE5B,wCAAwC;IACxC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAE9B,oDAAoD;IACpD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAE9B,yDAAyD;IACzD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAE9B,gDAAgD;IAChD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAE7B,6CAA6C;IAC7C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAE7B,yDAAyD;IACzD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAE9B,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAA;CACzC"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@kntnt/engagement-metrics",
+  "version": "1.0.0",
+  "description": "Lightweight client-side library that measures how deeply users engage with content.",
+  "license": "MIT",
+  "author": "Thomas Barregren",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Kntnt/kntnt-engagement-metrics.git",
+    "directory": "packages/core"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./iife": {
+      "default": "./dist/kntnt-engagement-metrics.min.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc && bun build src/index.ts --outdir dist --target browser --format esm && bun build src/iife.ts --outfile dist/kntnt-engagement-metrics.min.js --target browser --minify",
+    "typecheck": "tsc",
+    "lint": "biome check src/",
+    "test": "bun test"
+  },
+  "sideEffects": false,
+  "keywords": [
+    "engagement",
+    "metrics",
+    "analytics",
+    "reading-time",
+    "scroll-depth",
+    "content-analytics"
+  ]
+}