@mavware/bug-surveillance 0.1.0

package/src/replay.js

@@ -0,0 +1,175 @@
+// Renders trails and the animated replay over the reference photo. All
+// coordinates in the data are full-frame pixels; the canvas is drawn at the
+// frame's native resolution and scaled by CSS.
+export class Replay {
+    constructor({ canvas, data, referenceImage }) {
+        this.canvas = canvas;
+        this.ctx = canvas.getContext('2d');
+        this.data = data;
+        this.referenceImage = referenceImage;
+        this.duration = Math.max(1, ...data.tracks.map((track) => track.endOffsetMs));
+        this.playheadMs = null;
+        this.playing = false;
+        this.speed = 60;
+        this.showTrails = true;
+        this.highlightedTrackId = null;
+        this.lastFrameTime = null;
+
+        canvas.width = data.frameWidth || referenceImage?.naturalWidth || 1280;
+        canvas.height = data.frameHeight || referenceImage?.naturalHeight || 720;
+
+        this.draw();
+    }
+
+    trackColor(index, alpha = 1) {
+        return `hsla(${(index * 67) % 360}, 85%, 60%, ${alpha})`;
+    }
+
+    draw() {
+        const { ctx, canvas } = this;
+
+        if (this.referenceImage !== null) {
+            ctx.drawImage(this.referenceImage, 0, 0, canvas.width, canvas.height);
+            ctx.fillStyle = 'rgba(0, 0, 0, 0.35)';
+            ctx.fillRect(0, 0, canvas.width, canvas.height);
+        } else {
+            ctx.fillStyle = '#18181b';
+            ctx.fillRect(0, 0, canvas.width, canvas.height);
+        }
+
+        this.data.tracks.forEach((track, index) => {
+            const upTo = this.playheadMs === null ? Infinity : this.playheadMs;
+            this.drawTrack(track, index, upTo);
+        });
+
+        this.drawZones();
+    }
+
+    drawTrack(track, index, upToMs) {
+        const { ctx } = this;
+        const visible = track.points.filter(([t]) => t <= upToMs);
+
+        if (visible.length === 0) {
+            return;
+        }
+
+        const highlighted = this.highlightedTrackId === track.id;
+        const dimmed = this.highlightedTrackId !== null && !highlighted;
+
+        if (this.showTrails || highlighted || this.playheadMs !== null) {
+            ctx.beginPath();
+            ctx.moveTo(visible[0][1], visible[0][2]);
+            for (const [, x, y] of visible) {
+                ctx.lineTo(x, y);
+            }
+            ctx.strokeStyle = this.trackColor(index, dimmed ? 0.15 : 0.9);
+            ctx.lineWidth = highlighted ? 5 : 2.5;
+            ctx.stroke();
+
+            // Entry dot and exit arrow only once the track is fully drawn.
+            if (upToMs >= track.endOffsetMs) {
+                ctx.beginPath();
+                ctx.arc(visible[0][1], visible[0][2], highlighted ? 9 : 6, 0, Math.PI * 2);
+                ctx.fillStyle = this.trackColor(index, dimmed ? 0.15 : 1);
+                ctx.fill();
+                this.drawArrowhead(visible, index, dimmed, highlighted);
+            }
+        }
+
+        // Bright head dot while replaying.
+        if (this.playheadMs !== null && upToMs < track.endOffsetMs && visible.length > 0) {
+            const [, x, y] = visible[visible.length - 1];
+            ctx.beginPath();
+            ctx.arc(x, y, 8, 0, Math.PI * 2);
+            ctx.fillStyle = '#ffffff';
+            ctx.fill();
+            ctx.beginPath();
+            ctx.arc(x, y, 5, 0, Math.PI * 2);
+            ctx.fillStyle = this.trackColor(index);
+            ctx.fill();
+        }
+    }
+
+    drawArrowhead(points, index, dimmed, highlighted) {
+        if (points.length < 2) {
+            return;
+        }
+
+        const { ctx } = this;
+        const [, x2, y2] = points[points.length - 1];
+        const [, x1, y1] = points[points.length - 2];
+        const angle = Math.atan2(y2 - y1, x2 - x1);
+        const size = highlighted ? 18 : 12;
+
+        ctx.beginPath();
+        ctx.moveTo(x2, y2);
+        ctx.lineTo(x2 - size * Math.cos(angle - 0.4), y2 - size * Math.sin(angle - 0.4));
+        ctx.lineTo(x2 - size * Math.cos(angle + 0.4), y2 - size * Math.sin(angle + 0.4));
+        ctx.closePath();
+        ctx.fillStyle = this.trackColor(index, dimmed ? 0.15 : 1);
+        ctx.fill();
+    }
+
+    drawZones() {
+        const zones = [
+            ...(this.data.analytics?.entry_zones ?? []).map((zone) => ({ ...zone, kind: 'entry' })),
+            ...(this.data.analytics?.exit_zones ?? []).map((zone) => ({ ...zone, kind: 'exit' })),
+        ];
+
+        const { ctx } = this;
+
+        for (const zone of zones) {
+            const horizontal = zone.edge === 'top' || zone.edge === 'bottom';
+            const thickness = 10;
+            const [x, y, width, height] = horizontal
+                ? [zone.from, zone.edge === 'top' ? 0 : this.canvas.height - thickness, zone.to - zone.from, thickness]
+                : [zone.edge === 'left' ? 0 : this.canvas.width - thickness, zone.from, thickness, zone.to - zone.from];
+
+            ctx.fillStyle = zone.kind === 'entry' ? 'rgba(74, 222, 128, 0.65)' : 'rgba(248, 113, 113, 0.65)';
+            ctx.fillRect(x, y, width, height);
+        }
+    }
+
+    play() {
+        this.playing = true;
+        this.playheadMs = this.playheadMs === null || this.playheadMs >= this.duration ? 0 : this.playheadMs;
+        this.lastFrameTime = performance.now();
+        requestAnimationFrame((time) => this.tick(time));
+    }
+
+    pause() {
+        this.playing = false;
+    }
+
+    stopReplay() {
+        this.playing = false;
+        this.playheadMs = null;
+        this.draw();
+    }
+
+    seek(fraction) {
+        this.playheadMs = Math.round(fraction * this.duration);
+        this.draw();
+    }
+
+    tick(time) {
+        if (!this.playing) {
+            return;
+        }
+
+        this.playheadMs += (time - this.lastFrameTime) * this.speed;
+        this.lastFrameTime = time;
+
+        if (this.playheadMs >= this.duration) {
+            this.playheadMs = this.duration;
+            this.playing = false;
+        }
+
+        this.draw();
+        this.onFrame?.(this.playheadMs / this.duration);
+
+        if (this.playing) {
+            requestAnimationFrame((nextTime) => this.tick(nextTime));
+        }
+    }
+}

package/src/reportControls.js

@@ -0,0 +1,108 @@
+// The replay controls behind both report pages: play, speed, scrub, trails and
+// row highlighting, over a Replay built from whatever loadData hands back. The
+// logged-in report reads its payload from a JSON island the server re-renders;
+// the local report reads it from the night store. Neither knows the other.
+import { formatClock } from './captureLogic.js';
+import { Replay } from './replay.js';
+
+/**
+ * @param {HTMLElement} root  The element holding the data-report controls.
+ * @param {{ loadData: () => Promise<{ data: object, referenceImage: HTMLImageElement | null }> }} options
+ * @returns {{ rebuild: () => Promise<void>, ready: Promise<void> }}
+ */
+export function mountReportControls(root, { loadData }) {
+    const el = (name) => root.querySelector(`[data-report="${name}"]`);
+
+    const canvas = el('canvas');
+    const playButton = el('play');
+    const speedSelect = el('speed');
+    const scrub = el('scrub');
+    const clock = el('clock');
+    const trailsToggle = el('trails');
+
+    let replay = null;
+
+    const rebuild = async () => {
+        replay?.pause();
+
+        const { data, referenceImage } = await loadData();
+
+        replay = new Replay({ canvas, data, referenceImage });
+        replay.speed = Number(speedSelect.value ?? 60);
+        replay.showTrails = trailsToggle.checked;
+        replay.draw();
+
+        replay.onFrame = (fraction) => {
+            scrub.value = Math.round(fraction * 1000);
+            clock.textContent = formatClock(replay.playheadMs);
+            if (!replay.playing) {
+                playButton.textContent = 'Replay';
+            }
+        };
+
+        scrub.value = 0;
+        clock.textContent = '–';
+        playButton.textContent = 'Replay';
+    };
+
+    playButton.addEventListener('click', () => {
+        if (replay.playing) {
+            replay.pause();
+            playButton.textContent = 'Replay';
+        } else {
+            replay.speed = Number(speedSelect.value ?? 60);
+            replay.play();
+            playButton.textContent = 'Pause';
+        }
+    });
+
+    speedSelect.addEventListener('change', () => {
+        replay.speed = Number(speedSelect.value);
+    });
+
+    scrub.addEventListener('input', () => {
+        replay.pause();
+        playButton.textContent = 'Replay';
+        replay.seek(Number(scrub.value) / 1000);
+        clock.textContent = formatClock(replay.playheadMs);
+    });
+
+    trailsToggle.addEventListener('change', () => {
+        replay.showTrails = trailsToggle.checked;
+        replay.draw();
+    });
+
+    // Delegated so listeners survive the table rows being re-rendered.
+    root.addEventListener('click', (event) => {
+        const row = event.target.closest('[data-track-id]');
+
+        if (row === null || event.target.closest('button') !== null || replay === null) {
+            return;
+        }
+
+        const trackId = trackIdFrom(row.dataset.trackId);
+        replay.highlightedTrackId = replay.highlightedTrackId === trackId ? null : trackId;
+        replay.draw();
+    });
+
+    return { rebuild, ready: rebuild() };
+}
+
+/**
+ * Server tracks have numeric ids and local ones have uuids; Replay compares
+ * with ===, so the id must come back as the same type the payload carries.
+ */
+export function trackIdFrom(raw) {
+    const numeric = Number(raw);
+
+    return raw !== '' && Number.isInteger(numeric) ? numeric : raw;
+}
+
+export function loadImage(url) {
+    return new Promise((resolve) => {
+        const image = new Image();
+        image.onload = () => resolve(image);
+        image.onerror = () => resolve(null);
+        image.src = url;
+    });
+}

package/src/sessionAnalytics.js

@@ -0,0 +1,194 @@
+// The night's analytics summary, computed in the browser for nights that never
+// reach the server. This is a line-for-line port of
+// App\Actions\Surveillance\ComputeSessionAnalytics: same margins, same bins,
+// same output shape (snake_case keys), so replay.js and the report read both
+// the server's and the browser's summaries without knowing which they got.
+// Keep the two in step — tests/js/surveillance/sessionAnalytics.test.js pins
+// the same cases as the PHP unit test.
+
+export const EDGE_BINS = 10;
+
+/**
+ * Classify a full-frame point as belonging to a frame edge or the interior.
+ * The margin is 5% of the dimension, never less than 8px. In a corner the
+ * nearer edge wins; on a tie the first of left, right, top, bottom wins, which
+ * is the order PHP's stable asort leaves them in.
+ */
+export function classifyEdge([x, y], width, height) {
+    const marginX = Math.max(8, Math.round(width * 0.05));
+    const marginY = Math.max(8, Math.round(height * 0.05));
+
+    const distances = [
+        ['left', x <= marginX ? x : null],
+        ['right', width - x <= marginX ? width - x : null],
+        ['top', y <= marginY ? y : null],
+        ['bottom', height - y <= marginY ? height - y : null],
+    ].filter(([, distance]) => distance !== null);
+
+    if (distances.length === 0) {
+        return 'interior';
+    }
+
+    let [nearestEdge, nearestDistance] = distances[0];
+
+    for (const [edge, distance] of distances.slice(1)) {
+        if (distance < nearestDistance) {
+            nearestEdge = edge;
+            nearestDistance = distance;
+        }
+    }
+
+    return nearestEdge;
+}
+
+/**
+ * Cluster edge points into zones by bucketing positions along each edge axis
+ * and merging adjacent non-empty buckets.
+ *
+ * @returns {Array<{edge: string, from: number, to: number, center: [number, number], count: number}>}
+ */
+export function clusterEdgePoints(points, width, height) {
+    if (width < 1 || height < 1) {
+        return [];
+    }
+
+    const byEdge = new Map();
+
+    for (const point of points) {
+        const edge = classifyEdge(point, width, height);
+
+        if (edge === 'interior') {
+            continue;
+        }
+
+        const axisPosition = edge === 'top' || edge === 'bottom' ? point[0] : point[1];
+
+        if (!byEdge.has(edge)) {
+            byEdge.set(edge, []);
+        }
+
+        byEdge.get(edge).push(axisPosition);
+    }
+
+    const zones = [];
+
+    for (const [edge, positions] of byEdge) {
+        const axisLength = edge === 'top' || edge === 'bottom' ? width : height;
+        const binSize = axisLength / EDGE_BINS;
+        const bins = new Array(EDGE_BINS).fill(0);
+
+        for (const position of positions) {
+            bins[Math.min(EDGE_BINS - 1, Math.floor(position / binSize))]++;
+        }
+
+        for (const [fromBin, toBin, count] of mergeAdjacentBins(bins)) {
+            const from = Math.round(fromBin * binSize);
+            const to = Math.round((toBin + 1) * binSize);
+            const centerAlongAxis = Math.round((from + to) / 2);
+
+            zones.push({
+                edge,
+                from,
+                to,
+                center: zoneCenter(edge, centerAlongAxis, width, height),
+                count,
+            });
+        }
+    }
+
+    // Array.prototype.sort is stable, as PHP 8's usort is, so equal counts keep
+    // their edge order.
+    return zones.sort((a, b) => b.count - a.count);
+}
+
+function zoneCenter(edge, centerAlongAxis, width, height) {
+    switch (edge) {
+        case 'top':
+            return [centerAlongAxis, 0];
+        case 'bottom':
+            return [centerAlongAxis, height];
+        case 'left':
+            return [0, centerAlongAxis];
+        default:
+            return [width, centerAlongAxis];
+    }
+}
+
+/** Merge runs of adjacent non-empty bins into [fromBin, toBin, totalCount] triples. */
+export function mergeAdjacentBins(bins) {
+    const runs = [];
+    let current = null;
+
+    bins.forEach((count, index) => {
+        if (count === 0) {
+            if (current !== null) {
+                runs.push(current);
+                current = null;
+            }
+
+            return;
+        }
+
+        if (current === null) {
+            current = [index, index, count];
+        } else {
+            current[1] = index;
+            current[2] += count;
+        }
+    });
+
+    if (current !== null) {
+        runs.push(current);
+    }
+
+    return runs;
+}
+
+/**
+ * Where a track came in and went out, from its first and last point. The
+ * server does this at insert time; the local sink does it here.
+ */
+export function trackEdges(points, width, height) {
+    if (points.length === 0) {
+        return { entryEdge: null, exitEdge: null };
+    }
+
+    const first = points[0];
+    const last = points[points.length - 1];
+
+    return {
+        entryEdge: classifyEdge([first[1], first[2]], width, height),
+        exitEdge: classifyEdge([last[1], last[2]], width, height),
+    };
+}
+
+/**
+ * The summary stored on a night. Dismissed tracks never count — this is the
+ * one place that rule lives for local nights, matching the confirmed() scope
+ * the server applies.
+ */
+export function computeNightAnalytics({ tracks, startedAt = null, endedAt = null, frameWidth = 0, frameHeight = 0 }) {
+    const confirmed = tracks.filter((track) => track.dismissedAt == null);
+    const entryPoints = [];
+    const exitPoints = [];
+
+    for (const track of confirmed) {
+        const points = track.points;
+
+        if (points.length === 0) {
+            continue;
+        }
+
+        entryPoints.push([points[0][1], points[0][2]]);
+        const last = points[points.length - 1];
+        exitPoints.push([last[1], last[2]]);
+    }
+
+    return {
+        track_count: confirmed.length,
+        total_points: confirmed.reduce((sum, track) => sum + (track.pointCount ?? track.points.length), 0),
+        duration_ms: startedAt !== null && endedAt !== null ? Math.max(0, endedAt - startedAt) : 0,
+        entry_zones: clusterEdgePoints(entryPoints, frameWidth, frameHeight),
+        exit_zones: clusterEdgePoints(exitPoints, frameWidth, frameHeight),
+    };
+}

package/src/tracker.js

@@ -0,0 +1,150 @@
+export const TRACKER_DEFAULTS = {
+    maxMatchDistance: 40, // proc-px per frame
+    confirmAfterHits: 3,
+    closeAfterMisses: 8,
+    minPoints: 5,
+    minDisplacement: 10, // proc-px; discard jitter that never went anywhere
+    maxPointsPerTrack: 3000,
+    maxTrackDurationMs: 5 * 60 * 1000,
+};
+
+// Associates per-frame blobs into tracks via nearest-neighbor matching, and
+// hands closed tracks (scaled to full-frame pixels) to the onTrackClosed
+// callback for upload.
+export class Tracker {
+    constructor({ scale, sessionStartTime, captureCrop, onTrackClosed, params = {} }) {
+        this.params = { ...TRACKER_DEFAULTS, ...params };
+        this.scale = scale;
+        this.sessionStartTime = sessionStartTime;
+        this.captureCrop = captureCrop;
+        this.onTrackClosed = onTrackClosed;
+        this.candidates = [];
+        this.active = [];
+        this.closedCount = 0;
+    }
+
+    update(blobs, now = Date.now()) {
+        const offsetMs = Math.max(0, Math.round(now - this.sessionStartTime));
+        const unmatched = new Set(blobs.map((_, index) => index));
+
+        for (const track of [...this.active, ...this.candidates]) {
+            const matchIndex = this.nearestBlob(track, blobs, unmatched);
+
+            if (matchIndex === null) {
+                track.misses++;
+                continue;
+            }
+
+            unmatched.delete(matchIndex);
+            const blob = blobs[matchIndex];
+            track.misses = 0;
+            track.hits++;
+            track.lastX = blob.cx;
+            track.lastY = blob.cy;
+            track.points.push([offsetMs, Math.round(blob.cx * this.scale), Math.round(blob.cy * this.scale)]);
+        }
+
+        for (const index of unmatched) {
+            const blob = blobs[index];
+            this.candidates.push({
+                id: crypto.randomUUID(),
+                points: [[offsetMs, Math.round(blob.cx * this.scale), Math.round(blob.cy * this.scale)]],
+                lastX: blob.cx,
+                lastY: blob.cy,
+                hits: 1,
+                misses: 0,
+                startCrop: null,
+                endCrop: null,
+            });
+        }
+
+        this.promoteCandidates();
+        this.closeStaleTracks(offsetMs);
+    }
+
+    promoteCandidates() {
+        const { confirmAfterHits, closeAfterMisses } = this.params;
+
+        this.candidates = this.candidates.filter((candidate) => {
+            if (candidate.hits >= confirmAfterHits) {
+                const [, x, y] = candidate.points[candidate.points.length - 1];
+                candidate.startCrop = this.captureCrop(x, y);
+                this.active.push(candidate);
+
+                return false;
+            }
+
+            return candidate.misses < closeAfterMisses;
+        });
+    }
+
+    closeStaleTracks(nowOffsetMs) {
+        const { closeAfterMisses, maxPointsPerTrack, maxTrackDurationMs } = this.params;
+
+        this.active = this.active.filter((track) => {
+            const durationMs = nowOffsetMs - track.points[0][0];
+            const stale = track.misses >= closeAfterMisses;
+            const oversized = track.points.length >= maxPointsPerTrack || durationMs >= maxTrackDurationMs;
+
+            if (!stale && !oversized) {
+                return true;
+            }
+
+            this.closeTrack(track);
+
+            return false;
+        });
+    }
+
+    closeTrack(track) {
+        const { minPoints, minDisplacement } = this.params;
+
+        if (track.points.length < minPoints || this.displacement(track) < minDisplacement * this.scale) {
+            return;
+        }
+
+        const [, endX, endY] = track.points[track.points.length - 1];
+        track.endCrop = this.captureCrop(endX, endY);
+        this.closedCount++;
+
+        this.onTrackClosed({
+            client_track_id: track.id,
+            start_offset_ms: track.points[0][0],
+            end_offset_ms: track.points[track.points.length - 1][0],
+            points: track.points,
+            start_crop: track.startCrop,
+            end_crop: track.endCrop,
+        });
+    }
+
+    // Close everything still open (used when the night ends).
+    flush() {
+        this.active.forEach((track) => this.closeTrack(track));
+        this.active = [];
+        this.candidates = [];
+    }
+
+    nearestBlob(track, blobs, unmatched) {
+        let best = null;
+        let bestDistance = this.params.maxMatchDistance;
+
+        for (const index of unmatched) {
+            const blob = blobs[index];
+            const distance = Math.hypot(blob.cx - track.lastX, blob.cy - track.lastY);
+
+            if (distance <= bestDistance) {
+                best = index;
+                bestDistance = distance;
+            }
+        }
+
+        return best;
+    }
+
+    displacement(track) {
+        const [, startX, startY] = track.points[0];
+        const [, endX, endY] = track.points[track.points.length - 1];
+
+        return Math.hypot(endX - startX, endY - startY);
+    }
+}

package/src/wakeLock.js

@@ -0,0 +1,34 @@
+// Keeps the screen awake for the whole night; the OS releases the lock when
+// the tab is hidden, so re-acquire it whenever the page becomes visible again.
+export class WakeLock {
+    constructor(onUnsupported) {
+        this.sentinel = null;
+        this.onUnsupported = onUnsupported ?? (() => {});
+        this.onVisibilityChange = () => {
+            if (document.visibilityState === 'visible' && this.sentinel !== null) {
+                this.acquire();
+            }
+        };
+    }
+
+    async acquire() {
+        if (!('wakeLock' in navigator)) {
+            this.onUnsupported();
+
+            return;
+        }
+
+        try {
+            this.sentinel = await navigator.wakeLock.request('screen');
+            document.addEventListener('visibilitychange', this.onVisibilityChange);
+        } catch {
+            this.onUnsupported();
+        }
+    }
+
+    async release() {
+        document.removeEventListener('visibilitychange', this.onVisibilityChange);
+        await this.sentinel?.release();
+        this.sentinel = null;
+    }
+}