heatspot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 heatspot contributors
+
+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,98 @@
+# heatspot
+
+`heatspot` is an ESM TypeScript library for capturing pointer heat data and rendering an embeddable heatmap web component.
+
+## Features
+
+- ESM package output with TypeScript declarations
+- Pointer heat tracking utility API
+- Reusable `<heat-map>` component with slot-based content
+- Built-in toggle icon (top-left) to show heat overlay
+- Configurable `toolbar` attribute: `simple` (default) or `hidden`
+
+## Installation
+
+```bash
+npm install heatspot
+```
+
+## Usage
+
+### 1. Import the library
+
+```ts
+import "heatspot";
+```
+
+The `heat-map` custom element is registered on import.
+
+### 2. Render the component
+
+```html
+<heat-map toolbar="simple">
+  <section>
+    <h2>Example Panel</h2>
+    <p>Move the mouse over this area, then click the icon in the top-left.</p>
+  </section>
+</heat-map>
+```
+
+`toolbar` options:
+
+- `simple` - show the heatmap toggle icon
+- `hidden` - hide the heatmap toggle icon
+
+Example with hidden toolbar:
+
+```html
+<heat-map toolbar="hidden">
+  <section>
+    <h2>Passive Tracking Panel</h2>
+    <p>The heatmap toggle icon is not rendered in this mode.</p>
+  </section>
+</heat-map>
+```
+
+### Example
+
+![example.jps](assets/example.jpg)
+
+### 3. Optional tracking API
+
+```ts
+import {
+  configureMouseHeatmap,
+  getMouseHeatmapData,
+  resetMouseHeatmap,
+  startMouseTracking,
+  stopMouseTracking
+} from "heatspot";
+
+configureMouseHeatmap({ mergeRadius: 24, maxHotspots: 450 });
+startMouseTracking();
+
+const snapshot = getMouseHeatmapData();
+console.log(snapshot.hotspots);
+
+stopMouseTracking();
+resetMouseHeatmap();
+```
+
+## Scripts
+
+- `npm run build` - compile library to `dist/`
+- `npm run test` - run Vitest tests
+- `npm run test:coverage` - run tests with coverage reports in `coverage/`
+- `npm run build:verify` - run tests and harness build
+- `npm run pack:check` - show package contents using `npm pack --dry-run`
+
+## Development
+
+```bash
+npm install
+npm start
+```
+
+## License
+
+MIT

package/dist/constants/constants.d.ts

@@ -0,0 +1,44 @@
+import { type HeatmapConfig } from "../contracts/heatmap-contracts.js";
+import { type HeatColor } from "../contracts/rendering-contracts.js";
+/**
+ * Default clustering configuration used by the global tracker API.
+ */
+export declare const DEFAULT_HEATMAP_CONFIG: HeatmapConfig;
+/** Minimum allowed hotspot merge radius in pixels. */
+export declare const MIN_MERGE_RADIUS = 4;
+/** Minimum allowed hotspot storage size for a tracker instance. */
+export declare const MIN_MAX_HOTSPOTS = 20;
+/**
+ * Tracker configuration used by the `heat-map` web component instance.
+ */
+export declare const ELEMENT_TRACKER_CONFIG: HeatmapConfig;
+/**
+ * Ordered heat palette from coolest to hottest.
+ */
+export declare const DEFAULT_HEAT_COLORS: readonly HeatColor[];
+/**
+ * Discrete contour levels used to pick the dominant output heat color.
+ */
+export declare const DOMINANT_HEAT_LEVELS: readonly [0.2, 0.35, 0.5, 0.65, 0.8, 1];
+/** Exponent used to bias relative hotspot strength scaling. */
+export declare const RELATIVE_STRENGTH_EXPONENT = 0.85;
+/** Max normalized distance multiplier for hotspot influence cutoff. */
+export declare const FIELD_DISTANCE_MULTIPLIER = 2.2;
+/** Falloff divisor controlling Gaussian-style strength decay around hotspots. */
+export declare const FIELD_FALLOFF_DIVISOR = 0.8;
+/** Strength below this value is treated as low-heat rendering. */
+export declare const LOW_HEAT_THRESHOLD = 0.05;
+/** Alpha used for low-heat visible floor color. */
+export declare const LOW_HEAT_ALPHA = 0.16;
+/** Base alpha for dominant contour color levels. */
+export declare const HEAT_ALPHA_BASE = 0.22;
+/** Additional alpha multiplier per dominant contour level. */
+export declare const HEAT_ALPHA_MULTIPLIER = 0.45;
+/** Alpha used for maximum heat color output. */
+export declare const MAX_HEAT_ALPHA = 0.68;
+/** Sampling step in pixels for rasterized heat field rendering. */
+export declare const DEFAULT_SAMPLE_STEP = 4;
+/** Minimum contour radius in pixels for visible heat blobs. */
+export declare const MIN_CONTOUR_RADIUS = 14;
+/** Height/width ratio used to derive contour radius from viewport size. */
+export declare const CONTOUR_RADIUS_RATIO = 0.07;

package/dist/constants/constants.js

@@ -0,0 +1,56 @@
+/**
+ * Default clustering configuration used by the global tracker API.
+ */
+export const DEFAULT_HEATMAP_CONFIG = {
+    mergeRadius: 28,
+    maxHotspots: 400
+};
+/** Minimum allowed hotspot merge radius in pixels. */
+export const MIN_MERGE_RADIUS = 4;
+/** Minimum allowed hotspot storage size for a tracker instance. */
+export const MIN_MAX_HOTSPOTS = 20;
+/**
+ * Tracker configuration used by the `heat-map` web component instance.
+ */
+export const ELEMENT_TRACKER_CONFIG = {
+    mergeRadius: 24,
+    maxHotspots: 450
+};
+/**
+ * Ordered heat palette from coolest to hottest.
+ */
+export const DEFAULT_HEAT_COLORS = [
+    [20, 34, 120],
+    [0, 145, 255],
+    [0, 200, 125],
+    [255, 225, 70],
+    [255, 140, 30],
+    [225, 35, 30],
+    [255, 255, 255]
+];
+/**
+ * Discrete contour levels used to pick the dominant output heat color.
+ */
+export const DOMINANT_HEAT_LEVELS = [0.2, 0.35, 0.5, 0.65, 0.8, 1];
+/** Exponent used to bias relative hotspot strength scaling. */
+export const RELATIVE_STRENGTH_EXPONENT = 0.85;
+/** Max normalized distance multiplier for hotspot influence cutoff. */
+export const FIELD_DISTANCE_MULTIPLIER = 2.2;
+/** Falloff divisor controlling Gaussian-style strength decay around hotspots. */
+export const FIELD_FALLOFF_DIVISOR = 0.8;
+/** Strength below this value is treated as low-heat rendering. */
+export const LOW_HEAT_THRESHOLD = 0.05;
+/** Alpha used for low-heat visible floor color. */
+export const LOW_HEAT_ALPHA = 0.16;
+/** Base alpha for dominant contour color levels. */
+export const HEAT_ALPHA_BASE = 0.22;
+/** Additional alpha multiplier per dominant contour level. */
+export const HEAT_ALPHA_MULTIPLIER = 0.45;
+/** Alpha used for maximum heat color output. */
+export const MAX_HEAT_ALPHA = 0.68;
+/** Sampling step in pixels for rasterized heat field rendering. */
+export const DEFAULT_SAMPLE_STEP = 4;
+/** Minimum contour radius in pixels for visible heat blobs. */
+export const MIN_CONTOUR_RADIUS = 14;
+/** Height/width ratio used to derive contour radius from viewport size. */
+export const CONTOUR_RADIUS_RATIO = 0.07;

package/dist/contracts/heatmap-contracts.d.ts

@@ -0,0 +1,22 @@
+export interface ViewportSize {
+    width: number;
+    height: number;
+}
+export interface HeatmapConfig {
+    mergeRadius: number;
+    maxHotspots: number;
+}
+export type HeatmapToolbarMode = "simple" | "hidden";
+export interface HeatmapHotspot {
+    id: string;
+    x: number;
+    y: number;
+    count: number;
+    intensity: number;
+}
+export interface HeatmapSnapshot {
+    totalSamples: number;
+    trackedSince: number | null;
+    viewport: ViewportSize;
+    hotspots: HeatmapHotspot[];
+}

package/dist/contracts/heatmap-contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/rendering-contracts.d.ts

@@ -0,0 +1,6 @@
+export type HeatColor = readonly [number, number, number];
+export interface HeatmapRenderOptions {
+    sampleStep?: number;
+    maxContourRadius?: number;
+    colors?: readonly HeatColor[];
+}

package/dist/contracts/rendering-contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/core/heatmap-tracker.d.ts

@@ -0,0 +1,29 @@
+import { type HeatmapConfig, type HeatmapSnapshot, type ViewportSize } from "../contracts/heatmap-contracts.js";
+/**
+ * Stores and aggregates pointer samples into clustered hotspots.
+ */
+export declare class HeatmapTracker {
+    private config;
+    private sampleCount;
+    private trackedSince;
+    private latestViewport;
+    private readonly trackedHotspots;
+    private nextHotspotId;
+    constructor(initialConfig?: Partial<HeatmapConfig>);
+    /**
+     * Updates clustering configuration.
+     */
+    configure(nextConfig: Partial<HeatmapConfig>): void;
+    /**
+     * Records a pointer position and merges it into the nearest hotspot.
+     */
+    recordPosition(x: number, y: number, viewport: ViewportSize): void;
+    /**
+     * Clears all tracked samples and hotspots.
+     */
+    reset(): void;
+    /**
+     * Returns a snapshot suitable for rendering or analytics.
+     */
+    getSnapshot(): HeatmapSnapshot;
+}

package/dist/core/heatmap-tracker.js

@@ -0,0 +1,111 @@
+import { DEFAULT_HEATMAP_CONFIG, MIN_MAX_HOTSPOTS, MIN_MERGE_RADIUS } from "../constants/constants.js";
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+function getDistanceSquared(aX, aY, bX, bY) {
+    const dX = aX - bX;
+    const dY = aY - bY;
+    return dX * dX + dY * dY;
+}
+/**
+ * Stores and aggregates pointer samples into clustered hotspots.
+ */
+export class HeatmapTracker {
+    config;
+    sampleCount = 0;
+    trackedSince = null;
+    latestViewport = { width: 0, height: 0 };
+    trackedHotspots = [];
+    nextHotspotId = 0;
+    constructor(initialConfig = {}) {
+        this.config = { ...DEFAULT_HEATMAP_CONFIG };
+        this.configure(initialConfig);
+    }
+    /**
+     * Updates clustering configuration.
+     */
+    configure(nextConfig) {
+        const mergeRadius = nextConfig.mergeRadius ?? this.config.mergeRadius;
+        const maxHotspots = nextConfig.maxHotspots ?? this.config.maxHotspots;
+        this.config = {
+            mergeRadius: Math.max(MIN_MERGE_RADIUS, mergeRadius),
+            maxHotspots: Math.max(MIN_MAX_HOTSPOTS, Math.floor(maxHotspots))
+        };
+    }
+    /**
+     * Records a pointer position and merges it into the nearest hotspot.
+     */
+    recordPosition(x, y, viewport) {
+        if (viewport.width <= 0 || viewport.height <= 0) {
+            return;
+        }
+        const clampedX = clamp(x, 0, viewport.width);
+        const clampedY = clamp(y, 0, viewport.height);
+        const mergeRadiusSquared = this.config.mergeRadius * this.config.mergeRadius;
+        let closest = null;
+        let closestDistance = Number.POSITIVE_INFINITY;
+        for (const hotspot of this.trackedHotspots) {
+            const distance = getDistanceSquared(clampedX, clampedY, hotspot.x, hotspot.y);
+            if (distance <= mergeRadiusSquared && distance < closestDistance) {
+                closest = hotspot;
+                closestDistance = distance;
+            }
+        }
+        if (closest) {
+            const nextCount = closest.count + 1;
+            closest.x = (closest.x * closest.count + clampedX) / nextCount;
+            closest.y = (closest.y * closest.count + clampedY) / nextCount;
+            closest.count = nextCount;
+        }
+        else {
+            this.trackedHotspots.push({
+                id: `hs-${this.nextHotspotId++}`,
+                x: clampedX,
+                y: clampedY,
+                count: 1,
+                intensity: 0
+            });
+        }
+        if (this.trackedHotspots.length > this.config.maxHotspots) {
+            this.trackedHotspots.sort((a, b) => a.count - b.count);
+            this.trackedHotspots.shift();
+        }
+        this.sampleCount += 1;
+        this.latestViewport = viewport;
+        if (this.trackedSince === null) {
+            this.trackedSince = Date.now();
+        }
+    }
+    /**
+     * Clears all tracked samples and hotspots.
+     */
+    reset() {
+        this.sampleCount = 0;
+        this.trackedSince = null;
+        this.latestViewport = { width: 0, height: 0 };
+        this.trackedHotspots.length = 0;
+    }
+    /**
+     * Returns a snapshot suitable for rendering or analytics.
+     */
+    getSnapshot() {
+        let maxCount = 0;
+        for (const hotspot of this.trackedHotspots) {
+            if (hotspot.count > maxCount) {
+                maxCount = hotspot.count;
+            }
+        }
+        const hotspots = this.trackedHotspots
+            .map((hotspot) => ({
+            ...hotspot,
+            intensity: maxCount === 0 ? 0 : hotspot.count / maxCount
+        }))
+            .sort((a, b) => b.count - a.count);
+        return {
+            totalSamples: this.sampleCount,
+            trackedSince: this.trackedSince,
+            viewport: { ...this.latestViewport },
+            hotspots
+        };
+    }
+}

package/dist/heatmap-element.d.ts

@@ -0,0 +1,47 @@
+import { LitElement } from "lit";
+export declare class HeatMapElement extends LitElement {
+    static properties: {
+        heatmapVisible: {
+            state: boolean;
+        };
+        toolbar: {
+            type: StringConstructor;
+            reflect: boolean;
+        };
+    };
+    private heatmapVisible;
+    private toolbar;
+    private drawLoopId;
+    private readonly tracker;
+    static styles: import("lit").CSSResult;
+    constructor();
+    /**
+     * Stops frame rendering when element leaves the document.
+     */
+    disconnectedCallback(): void;
+    /**
+     * Starts or stops rendering based on the overlay visibility.
+     */
+    updated(): void;
+    /**
+     * Toggles heatmap overlay visibility.
+     */
+    private toggleHeatmap;
+    /**
+     * Tracks pointer motion while overlay is hidden.
+     */
+    private onPointerMove;
+    /**
+     * Creates a requestAnimationFrame loop for continuous heatmap drawing.
+     */
+    private startDrawLoop;
+    /**
+     * Stops the active requestAnimationFrame drawing loop.
+     */
+    private stopDrawLoop;
+    /**
+     * Renders the latest tracked hotspot data onto the overlay canvas.
+     */
+    private drawHeatmap;
+    render(): import("lit-html").TemplateResult<1>;
+}

package/dist/heatmap-element.js

@@ -0,0 +1,176 @@
+import { LitElement, css, html } from "lit";
+import { HeatmapTracker } from "./core/heatmap-tracker.js";
+import { ELEMENT_TRACKER_CONFIG } from "./constants/constants.js";
+import { renderHeatmapOverlay } from "./rendering/renderer.js";
+export class HeatMapElement extends LitElement {
+    static properties = {
+        heatmapVisible: { state: true },
+        toolbar: { type: String, reflect: true }
+    };
+    drawLoopId = null;
+    tracker = new HeatmapTracker(ELEMENT_TRACKER_CONFIG);
+    static styles = css `
+    :host {
+      position: relative;
+      display: block;
+      min-height: 220px;
+      border-radius: 12px;
+      overflow: hidden;
+      isolation: isolate;
+      background: #f4f7ff;
+    }
+
+    .surface {
+      position: relative;
+      min-height: inherit;
+      width: 100%;
+      height: 100%;
+      z-index: 1;
+    }
+
+    .toggle {
+      position: absolute;
+      top: 0.55rem;
+      left: 0.55rem;
+      width: 1.9rem;
+      height: 1.9rem;
+      border-radius: 999px;
+      border: 1px solid rgba(255, 255, 255, 0.5);
+      background: rgba(15, 23, 42, 0.82);
+      color: #ffffff;
+      padding: 0;
+      line-height: 1;
+      font-size: 0.92rem;
+      font-weight: 700;
+      cursor: pointer;
+      z-index: 10001;
+    }
+
+    .toggle:hover {
+      background: rgba(2, 6, 23, 0.95);
+    }
+
+    .overlay {
+      position: absolute;
+      inset: 0;
+      width: 100%;
+      height: 100%;
+      pointer-events: none;
+      z-index: 10000;
+    }
+  `;
+    constructor() {
+        super();
+        this.heatmapVisible = false;
+        this.toolbar = "simple";
+    }
+    /**
+     * Stops frame rendering when element leaves the document.
+     */
+    disconnectedCallback() {
+        this.stopDrawLoop();
+        super.disconnectedCallback();
+    }
+    /**
+     * Starts or stops rendering based on the overlay visibility.
+     */
+    updated() {
+        if (this.toolbar !== "simple" && this.toolbar !== "hidden") {
+            this.toolbar = "simple";
+        }
+        if (this.heatmapVisible) {
+            this.startDrawLoop();
+            return;
+        }
+        this.stopDrawLoop();
+    }
+    /**
+     * Toggles heatmap overlay visibility.
+     */
+    toggleHeatmap() {
+        this.heatmapVisible = !this.heatmapVisible;
+    }
+    /**
+     * Tracks pointer motion while overlay is hidden.
+     */
+    onPointerMove(event) {
+        if (this.heatmapVisible) {
+            return;
+        }
+        const surface = this.renderRoot.querySelector(".surface");
+        if (!surface) {
+            return;
+        }
+        const rect = surface.getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0) {
+            return;
+        }
+        const x = Math.min(rect.width, Math.max(0, event.clientX - rect.left));
+        const y = Math.min(rect.height, Math.max(0, event.clientY - rect.top));
+        this.tracker.recordPosition(x, y, { width: rect.width, height: rect.height });
+    }
+    /**
+     * Creates a requestAnimationFrame loop for continuous heatmap drawing.
+     */
+    startDrawLoop() {
+        if (this.drawLoopId !== null) {
+            return;
+        }
+        const drawFrame = () => {
+            this.drawHeatmap();
+            this.drawLoopId = window.requestAnimationFrame(drawFrame);
+        };
+        this.drawLoopId = window.requestAnimationFrame(drawFrame);
+    }
+    /**
+     * Stops the active requestAnimationFrame drawing loop.
+     */
+    stopDrawLoop() {
+        if (this.drawLoopId === null) {
+            return;
+        }
+        window.cancelAnimationFrame(this.drawLoopId);
+        this.drawLoopId = null;
+    }
+    /**
+     * Renders the latest tracked hotspot data onto the overlay canvas.
+     */
+    drawHeatmap() {
+        const canvas = this.renderRoot.querySelector("#heatmap");
+        const surface = this.renderRoot.querySelector(".surface");
+        if (!canvas || !surface) {
+            return;
+        }
+        const width = Math.round(surface.clientWidth);
+        const height = Math.round(surface.clientHeight);
+        if (width <= 0 || height <= 0) {
+            return;
+        }
+        if (canvas.width !== width || canvas.height !== height) {
+            canvas.width = width;
+            canvas.height = height;
+        }
+        const context = canvas.getContext("2d");
+        if (!context) {
+            return;
+        }
+        const snapshot = this.tracker.getSnapshot();
+        renderHeatmapOverlay(context, width, height, snapshot.hotspots);
+    }
+    render() {
+        return html `
+      <div class="surface" @pointermove=${this.onPointerMove}>
+        <slot></slot>
+      </div>
+      ${this.toolbar === "hidden"
+            ? null
+            : html `<button class="toggle" @click=${this.toggleHeatmap} aria-label="Toggle heatmap">
+            ${this.heatmapVisible ? "x" : "*"}
+          </button>`}
+      ${this.heatmapVisible ? html `<canvas id="heatmap" class="overlay"></canvas>` : null}
+    `;
+    }
+}
+if (typeof customElements !== "undefined" && !customElements.get("heat-map")) {
+    customElements.define("heat-map", HeatMapElement);
+}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { HeatmapTracker } from "./core/heatmap-tracker.js";
+import { DEFAULT_HEATMAP_CONFIG } from "./constants/constants.js";
+import { HeatMapElement } from "./heatmap-element.js";
+import { type HeatmapConfig, type HeatmapSnapshot, type ViewportSize } from "./contracts/heatmap-contracts.js";
+export declare const hello = "hello";
+export { HeatMapElement };
+export { DEFAULT_HEATMAP_CONFIG, HeatmapTracker };
+export type { HeatmapConfig, HeatmapHotspot, HeatmapToolbarMode, HeatmapSnapshot, ViewportSize } from "./contracts/heatmap-contracts.js";
+/**
+ * Updates tracker settings for globally tracked mouse heatmap data.
+ */
+export declare function configureMouseHeatmap(nextConfig: Partial<HeatmapConfig>): void;
+/**
+ * Records a single mouse position sample into the global tracker.
+ */
+export declare function recordMousePosition(x: number, y: number, viewport?: ViewportSize): void;
+/**
+ * Starts browser pointer tracking for the global tracker.
+ */
+export declare function startMouseTracking(): void;
+/**
+ * Stops browser pointer tracking for the global tracker.
+ */
+export declare function stopMouseTracking(): void;
+/**
+ * Clears all currently tracked global heatmap data.
+ */
+export declare function resetMouseHeatmap(): void;
+/**
+ * Returns the latest global heatmap snapshot.
+ */
+export declare function getMouseHeatmapData(): HeatmapSnapshot;

package/dist/index.js

@@ -0,0 +1,66 @@
+import { HeatmapTracker } from "./core/heatmap-tracker.js";
+import { DEFAULT_HEATMAP_CONFIG } from "./constants/constants.js";
+import { HeatMapElement } from "./heatmap-element.js";
+export const hello = "hello";
+export { HeatMapElement };
+export { DEFAULT_HEATMAP_CONFIG, HeatmapTracker };
+const globalTracker = new HeatmapTracker(DEFAULT_HEATMAP_CONFIG);
+let moveListener = null;
+function getViewportFromWindow() {
+    if (typeof window === "undefined") {
+        return { width: 0, height: 0 };
+    }
+    return {
+        width: Math.max(0, window.innerWidth),
+        height: Math.max(0, window.innerHeight)
+    };
+}
+/**
+ * Updates tracker settings for globally tracked mouse heatmap data.
+ */
+export function configureMouseHeatmap(nextConfig) {
+    globalTracker.configure(nextConfig);
+}
+/**
+ * Records a single mouse position sample into the global tracker.
+ */
+export function recordMousePosition(x, y, viewport = getViewportFromWindow()) {
+    globalTracker.recordPosition(x, y, viewport);
+}
+/**
+ * Starts browser pointer tracking for the global tracker.
+ */
+export function startMouseTracking() {
+    if (moveListener || typeof window === "undefined") {
+        return;
+    }
+    moveListener = (event) => {
+        recordMousePosition(event.clientX, event.clientY, {
+            width: window.innerWidth,
+            height: window.innerHeight
+        });
+    };
+    window.addEventListener("pointermove", moveListener, { passive: true });
+}
+/**
+ * Stops browser pointer tracking for the global tracker.
+ */
+export function stopMouseTracking() {
+    if (!moveListener || typeof window === "undefined") {
+        return;
+    }
+    window.removeEventListener("pointermove", moveListener);
+    moveListener = null;
+}
+/**
+ * Clears all currently tracked global heatmap data.
+ */
+export function resetMouseHeatmap() {
+    globalTracker.reset();
+}
+/**
+ * Returns the latest global heatmap snapshot.
+ */
+export function getMouseHeatmapData() {
+    return globalTracker.getSnapshot();
+}

package/dist/rendering/renderer.d.ts

@@ -0,0 +1,26 @@
+import { type HeatmapHotspot } from "../contracts/heatmap-contracts.js";
+import { type HeatColor, type HeatmapRenderOptions } from "../contracts/rendering-contracts.js";
+/**
+ * Converts an absolute hotspot count into a relative strength ratio.
+ */
+export declare function getRelativeStrength(count: number, maxCount: number): number;
+/**
+ * Interpolates the heat scale into a single RGB color.
+ */
+export declare function interpolateHeatColor(strength: number, colors?: readonly HeatColor[]): [number, number, number];
+/**
+ * Calculates merged field strength at a specific coordinate.
+ */
+export declare function calculateFieldStrength(x: number, y: number, hotspots: Array<{
+    x: number;
+    y: number;
+    count: number;
+}>, radius: number, maxHotspotCount: number): number;
+/**
+ * Maps field strength into a discrete dominant color and alpha.
+ */
+export declare function getDominantHeatColor(strength: number, colors?: readonly HeatColor[]): [number, number, number, number];
+/**
+ * Draws a contour-style heatmap overlay from hotspots onto a canvas context.
+ */
+export declare function renderHeatmapOverlay(context: CanvasRenderingContext2D, width: number, height: number, hotspots: HeatmapHotspot[], options?: HeatmapRenderOptions): void;

package/dist/rendering/renderer.js

@@ -0,0 +1,105 @@
+import { CONTOUR_RADIUS_RATIO, DEFAULT_HEAT_COLORS, DEFAULT_SAMPLE_STEP, DOMINANT_HEAT_LEVELS, FIELD_DISTANCE_MULTIPLIER, FIELD_FALLOFF_DIVISOR, HEAT_ALPHA_BASE, HEAT_ALPHA_MULTIPLIER, LOW_HEAT_ALPHA, LOW_HEAT_THRESHOLD, MAX_HEAT_ALPHA, MIN_CONTOUR_RADIUS, RELATIVE_STRENGTH_EXPONENT } from "../constants/constants.js";
+/**
+ * Converts an absolute hotspot count into a relative strength ratio.
+ */
+export function getRelativeStrength(count, maxCount) {
+    if (maxCount <= 0) {
+        return 0;
+    }
+    return Math.pow(count / maxCount, RELATIVE_STRENGTH_EXPONENT);
+}
+/**
+ * Interpolates the heat scale into a single RGB color.
+ */
+export function interpolateHeatColor(strength, colors = DEFAULT_HEAT_COLORS) {
+    const segments = colors.length - 1;
+    const scaled = Math.max(0, Math.min(1, strength)) * segments;
+    const lowerIndex = Math.floor(scaled);
+    const upperIndex = Math.min(segments, lowerIndex + 1);
+    const localT = scaled - lowerIndex;
+    const low = colors[lowerIndex];
+    const high = colors[upperIndex];
+    return [
+        Math.round(low[0] + (high[0] - low[0]) * localT),
+        Math.round(low[1] + (high[1] - low[1]) * localT),
+        Math.round(low[2] + (high[2] - low[2]) * localT)
+    ];
+}
+/**
+ * Calculates merged field strength at a specific coordinate.
+ */
+export function calculateFieldStrength(x, y, hotspots, radius, maxHotspotCount) {
+    const radiusSquared = radius * radius;
+    let strength = 0;
+    for (const spot of hotspots) {
+        const dx = x - spot.x;
+        const dy = y - spot.y;
+        const distanceSquared = dx * dx + dy * dy;
+        if (distanceSquared > radiusSquared * FIELD_DISTANCE_MULTIPLIER) {
+            continue;
+        }
+        const localStrength = getRelativeStrength(spot.count, maxHotspotCount);
+        const falloff = Math.exp(-distanceSquared / (radiusSquared * FIELD_FALLOFF_DIVISOR));
+        strength += localStrength * falloff;
+    }
+    return Math.min(1, strength);
+}
+/**
+ * Maps field strength into a discrete dominant color and alpha.
+ */
+export function getDominantHeatColor(strength, colors = DEFAULT_HEAT_COLORS) {
+    if (strength <= 0) {
+        return [0, 0, 0, 0];
+    }
+    if (strength < LOW_HEAT_THRESHOLD) {
+        const [r, g, b] = interpolateHeatColor(0, colors);
+        return [r, g, b, LOW_HEAT_ALPHA];
+    }
+    for (const level of DOMINANT_HEAT_LEVELS) {
+        if (strength <= level) {
+            const [r, g, b] = interpolateHeatColor(level, colors);
+            return [r, g, b, HEAT_ALPHA_BASE + level * HEAT_ALPHA_MULTIPLIER];
+        }
+    }
+    const [r, g, b] = interpolateHeatColor(1, colors);
+    return [r, g, b, MAX_HEAT_ALPHA];
+}
+/**
+ * Draws a contour-style heatmap overlay from hotspots onto a canvas context.
+ */
+export function renderHeatmapOverlay(context, width, height, hotspots, options = {}) {
+    context.clearRect(0, 0, width, height);
+    if (hotspots.length === 0) {
+        return;
+    }
+    const sampleStep = options.sampleStep ?? DEFAULT_SAMPLE_STEP;
+    const maxContourRadius = options.maxContourRadius ?? Math.max(MIN_CONTOUR_RADIUS, Math.min(width, height) * CONTOUR_RADIUS_RATIO);
+    const colors = options.colors ?? DEFAULT_HEAT_COLORS;
+    const maxHotspotCount = hotspots.reduce((max, spot) => Math.max(max, spot.count), 1);
+    const sampleWidth = Math.ceil(width / sampleStep);
+    const sampleHeight = Math.ceil(height / sampleStep);
+    const image = context.createImageData(sampleWidth, sampleHeight);
+    for (let y = 0; y < sampleHeight; y += 1) {
+        for (let x = 0; x < sampleWidth; x += 1) {
+            const sampleX = x * sampleStep;
+            const sampleY = y * sampleStep;
+            const strength = calculateFieldStrength(sampleX, sampleY, hotspots, maxContourRadius, maxHotspotCount);
+            const [r, g, b, a] = getDominantHeatColor(strength, colors);
+            const index = (y * sampleWidth + x) * 4;
+            image.data[index] = r;
+            image.data[index + 1] = g;
+            image.data[index + 2] = b;
+            image.data[index + 3] = Math.round(a * 255);
+        }
+    }
+    const offscreen = document.createElement("canvas");
+    offscreen.width = sampleWidth;
+    offscreen.height = sampleHeight;
+    const offscreenContext = offscreen.getContext("2d");
+    if (!offscreenContext) {
+        return;
+    }
+    offscreenContext.putImageData(image, 0, 0);
+    context.imageSmoothingEnabled = true;
+    context.drawImage(offscreen, 0, 0, sampleWidth, sampleHeight, 0, 0, width, height);
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "heatspot",
+  "version": "0.1.0",
+  "description": "A tiny ESM TypeScript library.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prebuild": "rimraf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "build:verify": "npm run test:coverage && npm run build:harness",
+    "prepublishOnly": "npm run test && npm run build",
+    "pack:check": "npm pack --dry-run",
+    "start": "npm run build && vite --config harness/vite.config.ts",
+    "build:harness": "npm run build && vite build --config harness/vite.config.ts",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:check": "tsc -p tsconfig.json --noEmit",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "heatmap",
+    "lit",
+    "web-components",
+    "typescript",
+    "esm"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "lit": "^3.3.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.21.0",
+    "@types/node": "^25.3.5",
+    "@typescript-eslint/eslint-plugin": "^8.26.1",
+    "@typescript-eslint/parser": "^8.26.1",
+    "eslint": "^9.21.0",
+    "eslint-plugin-import": "^2.31.0",
+    "globals": "^16.0.0",
+    "jsdom": "^26.0.0",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "@vitest/coverage-v8": "^4.0.18",
+    "vitest": "^4.0.18"
+  }
+}