geotimelapse 0.1.0

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/utils.d.ts

@@ -0,0 +1,9 @@
+/** Manual on purpose: the end-of-day marker 24:00:00 has no date-fns spelling. */
+export declare function formatDayTime(daySeconds: number): string;
+/** US-style clock time, e.g. "2:30 AM"; the end of day wraps to "12:00 AM". */
+export declare function formatDayTime12(daySeconds: number): string;
+/** Compact 24-hour time, e.g. "2:30" or "13:05". */
+export declare function formatDayTime24(daySeconds: number): string;
+/** Compact 24-hour label for a full hour, e.g. 2 → "2:00"; 24 marks the end of day. */
+export declare function formatHourLabel(hour: number): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAEA,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAOxD;AAQD,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,oDAAoD;AACpD,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,uFAAuF;AACvF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/dist/utils.js

@@ -0,0 +1,28 @@
+import { format } from 'date-fns';
+/** Manual on purpose: the end-of-day marker 24:00:00 has no date-fns spelling. */
+export function formatDayTime(daySeconds) {
+    const total = Math.max(Math.floor(daySeconds), 0);
+    const hours = Math.floor(total / 3600);
+    const minutes = Math.floor((total % 3600) / 60);
+    const seconds = total % 60;
+    const pad = (value) => String(value).padStart(2, '0');
+    return `${pad(hours)}:${pad(minutes)}:${pad(seconds)}`;
+}
+// An arbitrary DST-free local date carrying a time of day for date-fns.
+function dayTimeAsDate(daySeconds) {
+    const total = Math.max(Math.floor(daySeconds), 0);
+    return new Date(2000, 0, 1, Math.floor(total / 3600) % 24, Math.floor((total % 3600) / 60), total % 60);
+}
+/** US-style clock time, e.g. "2:30 AM"; the end of day wraps to "12:00 AM". */
+export function formatDayTime12(daySeconds) {
+    return format(dayTimeAsDate(daySeconds), 'h:mm a');
+}
+/** Compact 24-hour time, e.g. "2:30" or "13:05". */
+export function formatDayTime24(daySeconds) {
+    return format(dayTimeAsDate(daySeconds), 'H:mm');
+}
+/** Compact 24-hour label for a full hour, e.g. 2 → "2:00"; 24 marks the end of day. */
+export function formatHourLabel(hour) {
+    return hour === 24 ? '24:00' : formatDayTime24(hour * 3600);
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,kFAAkF;AAClF,MAAM,UAAU,aAAa,CAAC,UAAkB;IAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;IAClD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAChD,MAAM,OAAO,GAAG,KAAK,GAAG,EAAE,CAAC;IAC3B,MAAM,GAAG,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC9D,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;AACzD,CAAC;AAED,wEAAwE;AACxE,SAAS,aAAa,CAAC,UAAkB;IACvC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;IAClD,OAAO,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,GAAG,EAAE,CAAC,CAAC;AAC1G,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,eAAe,CAAC,UAAkB;IAChD,OAAO,MAAM,CAAC,aAAa,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,CAAC;AACrD,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,eAAe,CAAC,UAAkB;IAChD,OAAO,MAAM,CAAC,aAAa,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,CAAC;AACnD,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;AAC9D,CAAC"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "geotimelapse",
+  "version": "0.1.0",
+  "description": "Replay a day of geolocated events on a dark glowing map",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FranckErnewein/geotimelapse.git",
+    "directory": "packages/geotimelapse"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./duckdb": {
+      "types": "./dist/duckdb-source.d.ts",
+      "import": "./dist/duckdb-source.js",
+      "default": "./dist/duckdb-source.js"
+    },
+    "./synthetic": {
+      "types": "./dist/synthetic-source.d.ts",
+      "import": "./dist/synthetic-source.js",
+      "default": "./dist/synthetic-source.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "pnpm build",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test src/*.test.ts"
+  },
+  "peerDependencies": {
+    "deck.gl": ">=9.4.0",
+    "mapbox-gl": ">=3.0.0",
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0",
+    "react-map-gl": ">=8.0.0"
+  },
+  "dependencies": {
+    "@duckdb/duckdb-wasm": "1.33.1-dev57.0",
+    "@heroicons/react": "^2.2.0",
+    "date-fns": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "@types/react": "^19.0.0",
+    "deck.gl": "^9.4.0",
+    "mapbox-gl": "^3.30.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-map-gl": "^8.1.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.0"
+  }
+}

package/src/bounds.tsx

@@ -0,0 +1,14 @@
+'use client';
+
+import { createContext, useContext } from 'react';
+
+import type { MapBounds } from './types.js';
+
+const BoundsContext = createContext<MapBounds | null>(null);
+
+export const MapBoundsProvider = BoundsContext.Provider;
+
+/** The map's current viewport bounds; null until the map has loaded. */
+export function useMapBounds(): MapBounds | null {
+  return useContext(BoundsContext);
+}

package/src/clock.tsx

@@ -0,0 +1,130 @@
+'use client';
+
+import type { PropsWithChildren } from 'react';
+import { createContext, useCallback, useContext, useEffect, useState, useSyncExternalStore } from 'react';
+
+export const DAY_SECONDS = 24 * 60 * 60;
+// Wall-clock duration of a full-day replay.
+const PLAYBACK_SECONDS = 180;
+const RATE = DAY_SECONDS / PLAYBACK_SECONDS;
+// Ticks are capped below the display refresh rate: extra updates are invisible
+// and would only waste re-renders on high-refresh screens.
+const MAX_TICKS_PER_SECOND = 24;
+const MIN_TICK_MS = 1000 / MAX_TICKS_PER_SECOND;
+// Bounds on the wall-clock delta applied per tick. The upper bound keeps a
+// hidden tab (rAF suspended) or a main-thread stall from fast-forwarding the
+// replay; the lower bound guards against the first rAF timestamp predating the
+// performance.now() sampled in play() (vsync time is stamped before input).
+const MAX_TICK_MS = 100;
+
+export interface TimelapseClock {
+  play: () => void;
+  pause: () => void;
+  toggle: () => void;
+  seek: (daySeconds: number) => void;
+  /** Seconds elapsed since the start of the replayed day, in [0, DAY_SECONDS]. */
+  getDaySeconds: () => number;
+  /** Increments on every time jump (seek, end-of-day restart): consumers use it to invalidate history. */
+  getEpoch: () => number;
+  isPlaying: () => boolean;
+  /** Notified up to MAX_TICKS_PER_SECOND times while playing, and on play/pause/seek. */
+  subscribe: (listener: () => void) => () => void;
+}
+
+function createClock(): TimelapseClock {
+  let daySeconds = 0;
+  let epoch = 0;
+  let playing = false;
+  let rafId = 0;
+  let lastTick = 0;
+  // Next tick due date, advanced on its own grid so the effective rate stays
+  // at the cap instead of snapping down to a divisor of the refresh rate.
+  let nextTickAt = 0;
+  const listeners = new Set<() => void>();
+
+  const notify = () => listeners.forEach((listener) => listener());
+
+  const tick = (now: number) => {
+    if (now < nextTickAt) {
+      rafId = requestAnimationFrame(tick);
+      return;
+    }
+    nextTickAt = Math.max(nextTickAt + MIN_TICK_MS, now);
+    daySeconds += (Math.min(Math.max(now - lastTick, 0), MAX_TICK_MS) / 1000) * RATE;
+    lastTick = now;
+    if (daySeconds >= DAY_SECONDS) {
+      daySeconds = DAY_SECONDS;
+      playing = false;
+    } else {
+      rafId = requestAnimationFrame(tick);
+    }
+    notify();
+  };
+
+  const play = () => {
+    if (playing) return;
+    if (daySeconds >= DAY_SECONDS) {
+      daySeconds = 0;
+      epoch += 1;
+    }
+    playing = true;
+    lastTick = performance.now();
+    nextTickAt = lastTick;
+    rafId = requestAnimationFrame(tick);
+    notify();
+  };
+
+  const pause = () => {
+    if (!playing) return;
+    playing = false;
+    cancelAnimationFrame(rafId);
+    notify();
+  };
+
+  return {
+    play,
+    pause,
+    toggle: () => (playing ? pause() : play()),
+    seek: (value: number) => {
+      daySeconds = Math.min(Math.max(value, 0), DAY_SECONDS);
+      epoch += 1;
+      notify();
+    },
+    getDaySeconds: () => daySeconds,
+    getEpoch: () => epoch,
+    isPlaying: () => playing,
+    subscribe: (listener: () => void) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}
+
+const ClockContext = createContext<TimelapseClock | null>(null);
+
+export function TimelapseClockProvider({ children }: PropsWithChildren) {
+  const [clock] = useState(createClock);
+  useEffect(() => () => clock.pause(), [clock]);
+  return <ClockContext.Provider value={clock}>{children}</ClockContext.Provider>;
+}
+
+export function useTimelapseClock(): TimelapseClock {
+  const clock = useContext(ClockContext);
+  if (!clock) throw new Error('useTimelapseClock must be used within a TimelapseClockProvider');
+  return clock;
+}
+
+export function useIsPlaying(): boolean {
+  const clock = useTimelapseClock();
+  return useSyncExternalStore(clock.subscribe, clock.isPlaying, () => false);
+}
+
+/**
+ * Current day time, quantized: the component only re-renders when the value
+ * crosses a quantum boundary, so each consumer picks its own refresh rate.
+ */
+export function useDaySeconds(quantum = 1): number {
+  const clock = useTimelapseClock();
+  const getSnapshot = useCallback(() => Math.floor(clock.getDaySeconds() / quantum) * quantum, [clock, quantum]);
+  return useSyncExternalStore(clock.subscribe, getSnapshot, () => 0);
+}

package/src/counter.tsx

@@ -0,0 +1,96 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+import { useDaySeconds, useTimelapseClock } from './clock.js';
+import type { GeoTimelapseSource, Totals } from './types.js';
+import { formatDayTime12 } from './utils.js';
+
+interface CounterProps {
+  source: GeoTimelapseSource;
+  ready: boolean;
+  error: string | null;
+  progress: { loadedBytes: number; totalBytes: number } | null;
+  scopeVersion: number;
+  dateLabel?: string;
+  timeZoneLabel?: string;
+  formatValue: (value: number) => string;
+  formatCount: (count: number) => string;
+}
+
+export default function Counter({
+  source,
+  ready,
+  error,
+  progress,
+  scopeVersion,
+  dateLabel,
+  timeZoneLabel,
+  formatValue,
+  formatCount,
+}: CounterProps) {
+  const clock = useTimelapseClock();
+  const daySeconds = useDaySeconds(60);
+  const [totals, setTotals] = useState<Totals | null>(null);
+  const [queryError, setQueryError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!ready) return;
+    let disposed = false;
+    let inFlight = false;
+    let lastQueried = -1;
+
+    // One query at a time: each tick tries, and is skipped while the previous
+    // query is still running, so the counter refreshes as fast as the source
+    // can answer and never queues up.
+    const query = async () => {
+      const second = Math.floor(clock.getDaySeconds());
+      if (inFlight || second === lastQueried) return;
+      inFlight = true;
+      try {
+        const result = await source.totals(second);
+        if (disposed) return;
+        lastQueried = second;
+        setQueryError(null);
+        setTotals(result);
+      } catch (totalsError) {
+        if (!disposed) setQueryError(totalsError instanceof Error ? totalsError.message : String(totalsError));
+      } finally {
+        inFlight = false;
+      }
+    };
+
+    void query();
+    const unsubscribe = clock.subscribe(() => void query());
+    return () => {
+      disposed = true;
+      unsubscribe();
+    };
+    // ready and scopeVersion re-run the effect so a re-scoped source is re-read.
+    // oxlint-disable-next-line react/exhaustive-effect-dependencies
+  }, [clock, source, ready, scopeVersion]);
+
+  return (
+    <div className="absolute top-4 right-4 h-24 w-64 rounded-lg bg-black/60 px-4 py-3 text-right font-mono text-white backdrop-blur-sm">
+      {(error ?? queryError) ? (
+        <div className="max-w-xs overflow-hidden text-xs text-red-400">{error ?? queryError}</div>
+      ) : ready && totals ? (
+        <>
+          <div className="text-xs text-white/50 tabular-nums">
+            {dateLabel && `${dateLabel}, `}
+            {formatDayTime12(daySeconds)}
+            {timeZoneLabel && ` ${timeZoneLabel}`}
+          </div>
+          <div className="text-2xl tabular-nums">{formatValue(totals.value)}</div>
+          <div className="text-xs text-white/70 tabular-nums">{formatCount(totals.count)}</div>
+        </>
+      ) : (
+        <div className="text-xs text-white/70 tabular-nums">
+          {progress
+            ? `loading day… ${Math.round(progress.loadedBytes / 1e6)}/${Math.round(progress.totalBytes / 1e6)} MB`
+            : 'loading…'}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/duckdb-source.ts

@@ -0,0 +1,238 @@
+import * as duckdb from '@duckdb/duckdb-wasm';
+
+import type { FramePoints, GeoTimelapseSource, MapBounds, Totals } from './types.js';
+
+export interface DuckDbSourceOptions {
+  /** URL of the day's parquet: day_second INT (seconds since the day's
+   *  midnight, sorted), a value column, lat/lon FLOAT. ~60M rows is fine. */
+  parquetUrl: string;
+  /**
+   * Where the duckdb-wasm engine files come from. Omitted: version-matched
+   * jsDelivr URLs (zero config, external CDN). A string: the base URL you
+   * serve `@duckdb/duckdb-wasm/dist` under — serve the copy THIS package
+   * resolves, so the wasm matches the JS. An object: full bundle control.
+   */
+  engine?: string | duckdb.DuckDBBundles;
+  /** Name of the parquet column summed into totals().value. */
+  valueColumn?: string;
+}
+
+function resolveBundles(engine: DuckDbSourceOptions['engine']): duckdb.DuckDBBundles {
+  if (!engine) return duckdb.getJsDelivrBundles();
+  if (typeof engine === 'string') {
+    const base = engine.replace(/\/$/, '');
+    return {
+      mvp: {
+        mainModule: `${base}/duckdb-mvp.wasm`,
+        mainWorker: `${base}/duckdb-browser-mvp.worker.js`,
+      },
+      eh: {
+        mainModule: `${base}/duckdb-eh.wasm`,
+        mainWorker: `${base}/duckdb-browser-eh.worker.js`,
+      },
+    };
+  }
+  return engine;
+}
+
+/**
+ * A GeoTimelapseSource backed by duckdb-wasm: the parquet is downloaded once
+ * and loaded into an in-browser table, then every read is a local query.
+ * Each source owns its own engine instance (worker), so two components never
+ * share state — at the price of one table copy per instance.
+ */
+export function createDuckDbSource({
+  parquetUrl,
+  engine,
+  valueColumn = 'value',
+}: DuckDbSourceOptions): GeoTimelapseSource {
+  let dbPromise: Promise<duckdb.AsyncDuckDB> | null = null;
+  let connPromise: Promise<duckdb.AsyncDuckDBConnection> | null = null;
+  let loadPromise: Promise<void> | null = null;
+  // Mutable slot so a load() call after the first (e.g. a React StrictMode
+  // remount) still gets progress reports from the single in-flight download.
+  let progressListener: ((loadedBytes: number, totalBytes: number) => void) | undefined;
+  let scopeFilter = 'TRUE';
+  let requestedFilter = 'TRUE';
+  let scopeChain: Promise<void> = Promise.resolve();
+
+  const getDB = () =>
+    (dbPromise ??= (async () => {
+      const bundle = await duckdb.selectBundle(resolveBundles(engine));
+      const workerUrl = bundle.mainWorker!;
+      // A same-origin worker loads directly (and its requests carry the
+      // page's cookies); cross-origin URLs (the jsDelivr default) need
+      // createWorker's same-origin blob wrapper or the browser blocks them.
+      const sameOrigin = new URL(workerUrl, globalThis.location.href).origin === globalThis.location.origin;
+      const worker = sameOrigin ? new Worker(workerUrl) : await duckdb.createWorker(workerUrl);
+      const db = new duckdb.AsyncDuckDB(new duckdb.ConsoleLogger(duckdb.LogLevel.WARNING), worker);
+      await db.instantiate(bundle.mainModule);
+      return db;
+    })());
+
+  const getConn = () => (connPromise ??= getDB().then((db) => db.connect()));
+
+  // Running totals per second, so counters read one row per tick.
+  const CREATE_TOTALS = `
+    CREATE OR REPLACE TABLE totals_by_second AS
+    SELECT day_second,
+           sum(events) OVER w AS events,
+           sum(value) OVER w AS value
+    FROM scope_seconds
+    WINDOW w AS (ORDER BY day_second)
+  `;
+
+  const load = (onProgress?: (loadedBytes: number, totalBytes: number) => void) => {
+    if (onProgress) progressListener = onProgress;
+    return (loadPromise ??= (async () => {
+      const response = await fetch(parquetUrl);
+      if (!response.ok || !response.body) throw new Error(`parquet download failed (${response.status})`);
+      const totalBytes = Number(response.headers.get('content-length') ?? 0);
+      const chunks: Uint8Array[] = [];
+      let loadedBytes = 0;
+      let lastReported = 0;
+      const reader = response.body.getReader();
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        chunks.push(value);
+        loadedBytes += value.byteLength;
+        if (loadedBytes - lastReported >= 8 * 1024 * 1024) {
+          lastReported = loadedBytes;
+          progressListener?.(loadedBytes, totalBytes);
+        }
+      }
+      const buffer = new Uint8Array(loadedBytes);
+      let offset = 0;
+      for (const chunk of chunks) {
+        buffer.set(chunk, offset);
+        offset += chunk.byteLength;
+      }
+      progressListener?.(loadedBytes, totalBytes);
+
+      const db = await getDB();
+      await db.registerFileBuffer('replay.parquet', buffer);
+      const conn = await getConn();
+      // The value column is normalized at ingest so every later query is
+      // schema-agnostic. The source order (sorted by day_second) is what
+      // gives the in-memory table its zonemap pruning.
+      await conn.query(`
+        CREATE OR REPLACE TABLE events AS
+        SELECT day_second, ${valueColumn} AS value, lat, lon
+        FROM read_parquet('replay.parquet')
+      `);
+      // Per-second counts within the current scope, the single base both
+      // aggregates derive from — so consumers never rescan the raw rows.
+      await conn.query(`
+        CREATE OR REPLACE TABLE scope_seconds AS
+        SELECT day_second, count(*) AS events, sum(value) AS value
+        FROM events
+        GROUP BY day_second
+      `);
+      await conn.query(CREATE_TOTALS);
+      await db.dropFile('replay.parquet');
+    })());
+  };
+
+  const frame = async (fromSecond: number, toSecond: number): Promise<FramePoints> => {
+    const conn = await getConn();
+    // Integer bounds keep the comparison on the INTEGER column: a double
+    // literal would disable zonemap pruning and full-scan the table.
+    const result = await conn.query(`
+      SELECT lon, lat, count(*)::DOUBLE AS weight FROM events
+      WHERE day_second >= ${Math.floor(fromSecond)} AND day_second < ${Math.floor(toSecond)}
+        AND lat IS NOT NULL AND lon IS NOT NULL
+      GROUP BY lon, lat
+    `);
+    const lon = result.getChild('lon')!.toArray() as Float32Array;
+    const lat = result.getChild('lat')!.toArray() as Float32Array;
+    const weight = result.getChild('weight')!.toArray() as Float64Array;
+    const positions = new Float32Array(lon.length * 2);
+    const weights = new Float32Array(lon.length);
+    for (let i = 0; i < lon.length; i++) {
+      positions[2 * i] = lon[i];
+      positions[2 * i + 1] = lat[i];
+      weights[i] = weight[i];
+    }
+    return { positions, weights, count: lon.length };
+  };
+
+  const totals = async (second: number): Promise<Totals> => {
+    const conn = await getConn();
+    const result = await conn.query(`
+      SELECT events::DOUBLE AS events, value::DOUBLE AS value
+      FROM totals_by_second
+      WHERE day_second < ${Math.floor(second)}
+      ORDER BY day_second DESC
+      LIMIT 1
+    `);
+    const row = result.numRows > 0 ? result.get(0) : null;
+    return { count: Number(row?.events ?? 0), value: Number(row?.value ?? 0) };
+  };
+
+  const activity = async (): Promise<Float32Array> => {
+    const conn = await getConn();
+    const result = await conn.query(`
+      SELECT (day_second // 60)::INT AS minute, sum(events)::DOUBLE AS events
+      FROM scope_seconds
+      GROUP BY minute
+    `);
+    const minutes = result.getChild('minute')!.toArray() as Int32Array;
+    const events = result.getChild('events')!.toArray() as Float64Array;
+    const counts = new Float32Array(24 * 60);
+    for (let i = 0; i < minutes.length; i++) counts[minutes[i]] = events[i];
+    return counts;
+  };
+
+  // The scan over the raw rows is chunked hour by hour (pruned on
+  // day_second) so playback tick queries interleave instead of queueing
+  // behind one long statement.
+  const setScope = (bounds: MapBounds | null): Promise<void> => {
+    const filter = bounds
+      ? `lat BETWEEN ${bounds.south} AND ${bounds.north} AND lon BETWEEN ${bounds.west} AND ${bounds.east}`
+      : 'TRUE';
+    requestedFilter = filter;
+    scopeChain = scopeChain
+      .then(async () => {
+        // Superseded while queued, or already active.
+        if (requestedFilter !== filter || filter === scopeFilter) return;
+        // The rebuild reads the events table: wait for the day to be loaded.
+        await load();
+        const conn = await getConn();
+        await conn.query(`
+          CREATE OR REPLACE TABLE scope_seconds_build AS
+          SELECT day_second, count(*) AS events, sum(value) AS value
+          FROM events WHERE false GROUP BY day_second
+        `);
+        for (let hour = 0; hour < 24; hour++) {
+          if (requestedFilter !== filter) return;
+          await conn.query(`
+            INSERT INTO scope_seconds_build
+            SELECT day_second, count(*), sum(value)
+            FROM events
+            WHERE day_second >= ${hour * 3600} AND day_second < ${(hour + 1) * 3600} AND ${filter}
+            GROUP BY day_second
+          `);
+        }
+        await conn.query(`CREATE OR REPLACE TABLE scope_seconds AS FROM scope_seconds_build`);
+        await conn.query(`DROP TABLE scope_seconds_build`);
+        await conn.query(CREATE_TOTALS);
+        scopeFilter = filter;
+      })
+      // A failed rebuild keeps the previous scope; never poison the chain.
+      .catch((error: unknown) => console.error('geotimelapse scope rebuild failed', error));
+    return scopeChain;
+  };
+
+  const dispose = async () => {
+    const conn = connPromise ? await connPromise.catch(() => null) : null;
+    connPromise = null;
+    await conn?.close().catch(() => {});
+    const db = dbPromise ? await dbPromise.catch(() => null) : null;
+    dbPromise = null;
+    loadPromise = null;
+    await db?.terminate().catch(() => {});
+  };
+
+  return { load, frame, totals, activity, setScope, dispose };
+}