@mavware/bug-surveillance 0.1.0

package/src/index.js

@@ -0,0 +1,72 @@
+// @mavware/bug-surveillance — overnight bug surveillance from a browser camera.
+//
+// Detection and tracking run entirely in the browser; a night can be kept in the
+// browser's own IndexedDB store and reported on without any server at all. The
+// consumer owns the page: it wires a camera, a detector and a tracker together,
+// hands closed tracks to a "sink" (the LocalNightSink here, or one of its own
+// that uploads them), and draws the report with Replay. Nothing in this package
+// assumes a framework, a route, or a piece of markup.
+
+// Seeing: the camera, calibration, and per-frame detection and tracking.
+export { Camera } from './camera.js';
+export { BRIGHTNESS_BLOCK, BRIGHTNESS_WARN, calibrate, toGrayscale } from './brightness.js';
+export { DEFAULT_PARAMS, Detector } from './detector.js';
+export { TRACKER_DEFAULTS, Tracker } from './tracker.js';
+export { WakeLock } from './wakeLock.js';
+
+// Deciding: what a capture page says and shows.
+export {
+    CAMERA_CHECK_MESSAGE,
+    DIM_MESSAGE,
+    LARGE_MOTION_MESSAGE,
+    LEAVE_ROOM_SECONDS,
+    PREFLIGHT_MESSAGE,
+    TOO_DARK_MESSAGE,
+    WATCHING_MESSAGE,
+    calibrationOutcome,
+    cameraCheckLabel,
+    countdownMessage,
+    formatClock,
+    overlayBoxes,
+    wakeLockMessage,
+    watchingState,
+} from './captureLogic.js';
+
+// Summarising: the night's analytics.
+export {
+    EDGE_BINS,
+    classifyEdge,
+    clusterEdgePoints,
+    computeNightAnalytics,
+    mergeAdjacentBins,
+    trackEdges,
+} from './sessionAnalytics.js';
+
+// Keeping: a night in the browser.
+export { IndexedDbNightStore, STORE_NAME, STORE_VERSION, openNightStore, upgradeSchema } from './nightStore.js';
+export { InMemoryNightStore } from './nightStoreMemory.js';
+export { HEARTBEAT_INTERVAL_MS, LocalNightSink } from './localNightSink.js';
+export {
+    LOCAL_ID_PLACEHOLDER,
+    LOCAL_STORAGE_NOTICE,
+    MISSING_NIGHT_MESSAGE,
+    NIGHT_BOUNDARY_HOUR,
+    VOLATILE_STORE_MESSAGE,
+    buildLocalNight,
+    buildLocalReportPayload,
+    finalizeInterruptedNight,
+    localTrackFromClosed,
+    nightAnalytics,
+    nightDateFor,
+    nightName,
+    nightRows,
+    referenceBlobKey,
+    reportHeader,
+    reportUrlFor,
+    sightingRows,
+    statTiles,
+} from './localNight.js';
+
+// Showing: the replay and its controls.
+export { Replay } from './replay.js';
+export { loadImage, mountReportControls, trackIdFrom } from './reportControls.js';

package/src/localNight.js

@@ -0,0 +1,196 @@
+// The decisions behind a night that never reaches the server: what a stored
+// night looks like, how it is named, how its tracks and report are shaped, and
+// what the pages say about it. Pure, so it is tested in node; the pages and the
+// sink are plumbing that call it. Names and shapes mirror the server's so a
+// night claimed into an account later is indistinguishable from a live one.
+import { computeNightAnalytics, trackEdges } from './sessionAnalytics.js';
+
+/**
+ * A night begun after midnight still belongs to the evening before, the same
+ * rule SurveillanceSession::nightDateFor applies on the server.
+ */
+export const NIGHT_BOUNDARY_HOUR = 6;
+
+/**
+ * The uuid the watch report route is generated with, for the JS to swap out.
+ * Routes are named server-side and the page cannot know a night's id up front.
+ */
+export const LOCAL_ID_PLACEHOLDER = '00000000-0000-4000-8000-000000000000';
+
+export const LOCAL_STORAGE_NOTICE =
+    'Nights recorded here stay in this browser on this device. Clearing site data removes them. Create an account to keep them and see trends across nights.';
+
+export const VOLATILE_STORE_MESSAGE =
+    'This browser will not keep nights between visits — the report will be gone once this tab closes. Try a normal (non-private) window to keep them.';
+
+export const MISSING_NIGHT_MESSAGE =
+    'This night is not stored in this browser. Nights are kept only on the device that recorded them.';
+
+export function nightDateFor(ms) {
+    const date = new Date(ms - NIGHT_BOUNDARY_HOUR * 60 * 60 * 1000);
+    date.setHours(0, 0, 0, 0);
+
+    return date;
+}
+
+/** "Night of Sep 8", the shape the dashboard gives a session when it is created. */
+export function nightName(startedAt) {
+    return `Night of ${nightDateFor(startedAt).toLocaleDateString('en-US', { month: 'short', day: 'numeric' })}`;
+}
+
+export function buildLocalNight({ id, startedAt, frameWidth, frameHeight, settings }) {
+    return {
+        id,
+        name: nightName(startedAt),
+        status: 'active',
+        startedAt,
+        endedAt: null,
+        lastHeartbeatAt: startedAt,
+        frameWidth,
+        frameHeight,
+        settings,
+        analytics: null,
+        createdAt: startedAt,
+        claimedSessionId: null,
+        claimedAt: null,
+    };
+}
+
+export function referenceBlobKey(nightId) {
+    return `${nightId}/reference`;
+}
+
+export function reportUrlFor(template, nightId) {
+    return template.replace(LOCAL_ID_PLACEHOLDER, nightId);
+}
+
+/**
+ * A closed track from the tracker, as the store keeps it: the server's insert
+ * shape with edges classified up front, as CaptureController does.
+ */
+export function localTrackFromClosed(track, nightId, frameWidth, frameHeight) {
+    return {
+        nightId,
+        clientTrackId: track.client_track_id,
+        startOffsetMs: track.start_offset_ms,
+        endOffsetMs: track.end_offset_ms,
+        pointCount: track.points.length,
+        points: track.points,
+        ...trackEdges(track.points, frameWidth, frameHeight),
+        startCrop: track.start_crop ?? null,
+        endCrop: track.end_crop ?? null,
+        dismissedAt: null,
+    };
+}
+
+export function nightAnalytics(night, tracks) {
+    return computeNightAnalytics({
+        tracks,
+        startedAt: night.startedAt,
+        endedAt: night.endedAt,
+        frameWidth: night.frameWidth,
+        frameHeight: night.frameHeight,
+    });
+}
+
+/** The payload replay.js draws from, in exactly the shape the server's report page emits. */
+export function buildLocalReportPayload(night, tracks) {
+    return {
+        frameWidth: night.frameWidth,
+        frameHeight: night.frameHeight,
+        analytics: night.analytics ?? nightAnalytics(night, tracks),
+        tracks: tracks
+            .filter((track) => track.dismissedAt == null)
+            .sort((a, b) => a.startOffsetMs - b.startOffsetMs)
+            .map((track) => ({
+                id: track.clientTrackId,
+                startOffsetMs: track.startOffsetMs,
+                endOffsetMs: track.endOffsetMs,
+                points: track.points,
+                entryEdge: track.entryEdge,
+                exitEdge: track.exitEdge,
+            })),
+    };
+}
+
+function capitalise(value) {
+    return value === null || value === undefined ? '—' : value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+function clockAt(ms) {
+    return new Date(ms).toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit', second: '2-digit' });
+}
+
+/** One row per track for the sightings table, dismissed rows included but marked. */
+export function sightingRows(night, tracks) {
+    return [...tracks]
+        .sort((a, b) => a.startOffsetMs - b.startOffsetMs)
+        .map((track) => ({
+            clientTrackId: track.clientTrackId,
+            time: clockAt(night.startedAt + track.startOffsetMs),
+            durationSeconds: Math.round((track.endOffsetMs - track.startOffsetMs) / 100) / 10,
+            entered: capitalise(track.entryEdge),
+            exited: capitalise(track.exitEdge),
+            startCropSrc: track.startCrop ? `data:image/jpeg;base64,${track.startCrop}` : null,
+            endCropSrc: track.endCrop ? `data:image/jpeg;base64,${track.endCrop}` : null,
+            dismissed: track.dismissedAt != null,
+        }));
+}
+
+function topZoneLabel(zones) {
+    return zones && zones.length > 0 ? `${capitalise(zones[0].edge)} edge` : 'None';
+}
+
+export function statTiles(analytics) {
+    return {
+        trackCount: analytics?.track_count ?? 0,
+        topEntry: topZoneLabel(analytics?.entry_zones),
+        topExit: topZoneLabel(analytics?.exit_zones),
+    };
+}
+
+function dateRange(night) {
+    const format = (ms) => new Date(ms).toLocaleString('en-US', { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit', hour12: false });
+
+    return night.endedAt === null ? format(night.startedAt) : `${format(night.startedAt)} – ${format(night.endedAt)}`;
+}
+
+/** What the report header says about a night. */
+export function reportHeader(night) {
+    return {
+        title: night.name,
+        range: dateRange(night),
+        discarded: night.status === 'aborted',
+    };
+}
+
+const STATUS_LABELS = { active: 'Interrupted', completed: 'Completed', aborted: 'Discarded' };
+
+/** One row per stored night for the list on the watch page. */
+export function nightRows(nights, { reportUrlTemplate }) {
+    return nights.map((night) => ({
+        id: night.id,
+        name: night.name,
+        started: dateRange({ ...night, endedAt: null }),
+        status: STATUS_LABELS[night.status] ?? night.status,
+        sightings: night.analytics?.track_count ?? 0,
+        reportUrl: reportUrlFor(reportUrlTemplate, night.id),
+        claimed: night.claimedSessionId !== null,
+    }));
+}
+
+/**
+ * A night still marked active when a page loads is one whose tab died
+ * overnight. Close it at the last heartbeat, as the server's stale-device
+ * warning would have the user do, so its report can be read.
+ */
+export function finalizeInterruptedNight(night, tracks) {
+    if (night.status !== 'active') {
+        return null;
+    }
+
+    const endedAt = Math.max(night.startedAt, night.lastHeartbeatAt ?? night.startedAt);
+    const closed = { ...night, status: 'completed', endedAt };
+
+    return { status: 'completed', endedAt, analytics: nightAnalytics(closed, tracks) };
+}

package/src/localNightSink.js

@@ -0,0 +1,114 @@
+// The night sink for a guest: the same six calls capture.js makes on the
+// Uploader, answered by the browser's own store instead of the server. Nothing
+// here touches the network. The reference photo, every closed track and the
+// end-of-night summary land in the night store, and the report URL handed back
+// points at the local report page.
+import {
+    buildLocalNight,
+    localTrackFromClosed,
+    nightAnalytics,
+    referenceBlobKey,
+    reportUrlFor,
+} from './localNight.js';
+
+export const HEARTBEAT_INTERVAL_MS = 60000;
+
+export class LocalNightSink {
+    constructor({ store, reportUrlTemplate, onStatus }) {
+        this.store = store;
+        this.reportUrlTemplate = reportUrlTemplate;
+        this.onStatus = onStatus ?? (() => {});
+        this.nightId = null;
+        this.night = null;
+        this.pending = new Set();
+        this.retry = [];
+        this.timers = [];
+    }
+
+    /** Create the night and keep its reference photo. The night's clock starts here. */
+    async storeReference({ blob, frameWidth, frameHeight, settings }) {
+        this.nightId = crypto.randomUUID();
+        this.night = buildLocalNight({ id: this.nightId, startedAt: Date.now(), frameWidth, frameHeight, settings });
+
+        await this.store.putNight(this.night);
+        await this.store.putBlob({
+            key: referenceBlobKey(this.nightId),
+            nightId: this.nightId,
+            bytes: await blob.arrayBuffer(),
+            type: blob.type || 'image/jpeg',
+        });
+
+        // Ask the browser not to evict a night's worth of watching under storage
+        // pressure. Not every browser grants it, and there is nothing to do if not.
+        navigator.storage?.persist?.().catch(() => {});
+    }
+
+    /** A local heartbeat, so an interrupted night can be closed at the right time later. */
+    start() {
+        this.timers.push(setInterval(() => this.heartbeat(), HEARTBEAT_INTERVAL_MS));
+    }
+
+    stop() {
+        this.timers.forEach(clearInterval);
+        this.timers = [];
+    }
+
+    enqueue(track) {
+        this.write(localTrackFromClosed(track, this.nightId, this.night.frameWidth, this.night.frameHeight));
+    }
+
+    write(localTrack) {
+        const attempt = this.store
+            .putTrack(localTrack)
+            .catch((error) => {
+                // Kept for the next flush, as the uploader keeps a failed batch.
+                this.retry.push(localTrack);
+                this.onStatus({ queueDepth: this.pending.size + this.retry.length, lastError: String(error) });
+            })
+            .finally(() => {
+                this.pending.delete(attempt);
+                this.onStatus({ queueDepth: this.pending.size + this.retry.length });
+            });
+
+        this.pending.add(attempt);
+        this.onStatus({ queueDepth: this.pending.size + this.retry.length });
+    }
+
+    async flush() {
+        await Promise.allSettled([...this.pending]);
+
+        const leftovers = this.retry;
+        this.retry = [];
+        leftovers.forEach((localTrack) => this.write(localTrack));
+
+        if (leftovers.length > 0) {
+            await Promise.allSettled([...this.pending]);
+        }
+    }
+
+    async heartbeat() {
+        try {
+            await this.store.patchNight(this.nightId, { lastHeartbeatAt: Date.now() });
+        } catch {
+            // A missed heartbeat only shifts where an interrupted night is closed.
+        }
+    }
+
+    /** Close the night, summarise it, and say where its report is. */
+    async end({ endedAtOffsetMs, aborted }) {
+        await this.flush();
+
+        const endedAt = this.night.startedAt + endedAtOffsetMs;
+        const tracks = await this.store.listTracks(this.nightId);
+        const closed = { ...this.night, endedAt };
+
+        this.night = await this.store.patchNight(this.nightId, {
+            status: aborted ? 'aborted' : 'completed',
+            endedAt,
+            lastHeartbeatAt: endedAt,
+            analytics: nightAnalytics(closed, tracks),
+        });
+
+        return { ok: true, status: 200, reportUrl: reportUrlFor(this.reportUrlTemplate, this.nightId) };
+    }
+}

package/src/nightStore.js

@@ -0,0 +1,164 @@
+// Where a guest's nights live: an IndexedDB database in this browser profile.
+// Nothing here leaves the device. Three stores: nights, their tracks, and the
+// one binary per night (the reference photo, as an ArrayBuffer; crops stay as
+// base64 strings on the track, the same shape the server accepts, so claiming a
+// night later re-sends them untouched).
+//
+// The interface is shared with InMemoryNightStore, which is both the fallback
+// when IndexedDB is refused and the double the specs use. Keep the two in step.
+import { InMemoryNightStore } from './nightStoreMemory.js';
+
+export const STORE_NAME = 'bugtracker-local';
+export const STORE_VERSION = 1;
+
+/** Build the schema. Exported so a spec can run it against a fake factory. */
+export function upgradeSchema(db) {
+    if (!db.objectStoreNames.contains('nights')) {
+        db.createObjectStore('nights', { keyPath: 'id' }).createIndex('byStartedAt', 'startedAt');
+    }
+
+    if (!db.objectStoreNames.contains('tracks')) {
+        db.createObjectStore('tracks', { keyPath: ['nightId', 'clientTrackId'] }).createIndex('byNight', 'nightId');
+    }
+
+    if (!db.objectStoreNames.contains('blobs')) {
+        db.createObjectStore('blobs', { keyPath: 'key' }).createIndex('byNight', 'nightId');
+    }
+}
+
+/**
+ * Open the store, or fall back to memory when the browser has no IndexedDB or
+ * refuses to open it. The fallback is marked volatile so a page can warn that
+ * the night will not survive the tab.
+ */
+export async function openNightStore({ indexedDB = globalThis.indexedDB } = {}) {
+    if (indexedDB === undefined || indexedDB === null) {
+        return new InMemoryNightStore();
+    }
+
+    try {
+        const db = await new Promise((resolve, reject) => {
+            const request = indexedDB.open(STORE_NAME, STORE_VERSION);
+            request.onupgradeneeded = () => upgradeSchema(request.result);
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error);
+            request.onblocked = () => reject(new Error('IndexedDB open blocked'));
+        });
+
+        return new IndexedDbNightStore(db);
+    } catch {
+        return new InMemoryNightStore();
+    }
+}
+
+export class IndexedDbNightStore {
+    constructor(db) {
+        this.db = db;
+        this.volatile = false;
+    }
+
+    async putNight(night) {
+        await this.write('nights', (store) => store.put(night));
+    }
+
+    async getNight(id) {
+        return (await this.read('nights', (store) => store.get(id))) ?? null;
+    }
+
+    async patchNight(id, patch) {
+        return this.patch('nights', id, patch);
+    }
+
+    async listNights() {
+        const nights = await this.read('nights', (store) => store.getAll());
+
+        return nights.sort((a, b) => b.startedAt - a.startedAt);
+    }
+
+    /** Remove a night with its tracks and blobs in one transaction. */
+    async deleteNight(id) {
+        const transaction = this.db.transaction(['nights', 'tracks', 'blobs'], 'readwrite');
+
+        transaction.objectStore('nights').delete(id);
+        deleteByIndex(transaction.objectStore('tracks').index('byNight'), id);
+        deleteByIndex(transaction.objectStore('blobs').index('byNight'), id);
+
+        await settled(transaction);
+    }
+
+    async putTrack(track) {
+        await this.write('tracks', (store) => store.put(track));
+    }
+
+    async listTracks(nightId) {
+        const tracks = await this.read('tracks', (store) => store.index('byNight').getAll(nightId));
+
+        return tracks.sort((a, b) => a.startOffsetMs - b.startOffsetMs);
+    }
+
+    async patchTrack(nightId, clientTrackId, patch) {
+        return this.patch('tracks', [nightId, clientTrackId], patch);
+    }
+
+    async putBlob(blob) {
+        await this.write('blobs', (store) => store.put(blob));
+    }
+
+    async getBlob(key) {
+        return (await this.read('blobs', (store) => store.get(key))) ?? null;
+    }
+
+    async patch(storeName, key, patch) {
+        const transaction = this.db.transaction(storeName, 'readwrite');
+        const store = transaction.objectStore(storeName);
+        const existing = await request(store.get(key));
+
+        if (existing === undefined) {
+            return null;
+        }
+
+        const updated = { ...existing, ...patch };
+        store.put(updated);
+        await settled(transaction);
+
+        return updated;
+    }
+
+    read(storeName, operation) {
+        return request(operation(this.db.transaction(storeName, 'readonly').objectStore(storeName)));
+    }
+
+    async write(storeName, operation) {
+        const transaction = this.db.transaction(storeName, 'readwrite');
+        operation(transaction.objectStore(storeName));
+        await settled(transaction);
+    }
+}
+
+function request(idbRequest) {
+    return new Promise((resolve, reject) => {
+        idbRequest.onsuccess = () => resolve(idbRequest.result);
+        idbRequest.onerror = () => reject(idbRequest.error);
+    });
+}
+
+function settled(transaction) {
+    return new Promise((resolve, reject) => {
+        transaction.oncomplete = () => resolve();
+        transaction.onerror = () => reject(transaction.error);
+        transaction.onabort = () => reject(transaction.error ?? new Error('IndexedDB transaction aborted'));
+    });
+}
+
+function deleteByIndex(index, value) {
+    const cursorRequest = index.openKeyCursor(IDBKeyRange.only(value));
+
+    cursorRequest.onsuccess = () => {
+        const cursor = cursorRequest.result;
+
+        if (cursor) {
+            index.objectStore.delete(cursor.primaryKey);
+            cursor.continue();
+        }
+    };
+}

package/src/nightStoreMemory.js

@@ -0,0 +1,97 @@
+// The night store held in plain Maps. Two jobs: the runtime fallback when a
+// browser refuses IndexedDB (some private modes), where a night lives only as
+// long as the tab; and the double every spec above the store runs against.
+// Values are cloned on the way in and out so nothing can pass by aliasing.
+
+export class InMemoryNightStore {
+    constructor() {
+        this.nights = new Map();
+        this.tracks = new Map();
+        this.blobs = new Map();
+        this.volatile = true;
+    }
+
+    async putNight(night) {
+        this.nights.set(night.id, structuredClone(night));
+    }
+
+    async getNight(id) {
+        const night = this.nights.get(id);
+
+        return night === undefined ? null : structuredClone(night);
+    }
+
+    async patchNight(id, patch) {
+        const night = this.nights.get(id);
+
+        if (night === undefined) {
+            return null;
+        }
+
+        const updated = { ...night, ...structuredClone(patch) };
+        this.nights.set(id, updated);
+
+        return structuredClone(updated);
+    }
+
+    async listNights() {
+        return [...this.nights.values()]
+            .sort((a, b) => b.startedAt - a.startedAt)
+            .map((night) => structuredClone(night));
+    }
+
+    async deleteNight(id) {
+        this.nights.delete(id);
+
+        for (const [key, track] of this.tracks) {
+            if (track.nightId === id) {
+                this.tracks.delete(key);
+            }
+        }
+
+        for (const [key, blob] of this.blobs) {
+            if (blob.nightId === id) {
+                this.blobs.delete(key);
+            }
+        }
+    }
+
+    async putTrack(track) {
+        this.tracks.set(trackKey(track.nightId, track.clientTrackId), structuredClone(track));
+    }
+
+    async listTracks(nightId) {
+        return [...this.tracks.values()]
+            .filter((track) => track.nightId === nightId)
+            .sort((a, b) => a.startOffsetMs - b.startOffsetMs)
+            .map((track) => structuredClone(track));
+    }
+
+    async patchTrack(nightId, clientTrackId, patch) {
+        const key = trackKey(nightId, clientTrackId);
+        const track = this.tracks.get(key);
+
+        if (track === undefined) {
+            return null;
+        }
+
+        const updated = { ...track, ...structuredClone(patch) };
+        this.tracks.set(key, updated);
+
+        return structuredClone(updated);
+    }
+
+    async putBlob(blob) {
+        this.blobs.set(blob.key, structuredClone(blob));
+    }
+
+    async getBlob(key) {
+        const blob = this.blobs.get(key);
+
+        return blob === undefined ? null : structuredClone(blob);
+    }
+}
+
+function trackKey(nightId, clientTrackId) {
+    return `${nightId} ${clientTrackId}`;
+}