wacrawl-dashboard 0.1.1 → 0.2.0

package/apps/api/dist/lib/rollupDb.js

@@ -0,0 +1,253 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import Database from 'better-sqlite3';
+import { getDb } from '../db.js';
+/**
+ * A precomputed index of what the archive says, so the text reports can stop
+ * guessing.
+ *
+ * The word cloud and the emoji report both work by pulling message bodies into
+ * JS and running a regex over every one. That does not scale, so both were
+ * capped — the newest 30,000 and 50,000 messages — and every number they
+ * produced was therefore a sample rather than an answer. `ScanNote` says so on
+ * screen, which is honest but not a fix.
+ *
+ * Counting each term once, up front, turns those reports into an indexed sum:
+ * exact over the whole archive, and faster than the capped version it replaces.
+ *
+ * The archive itself is opened readonly and belongs to the wacrawl CLI, so the
+ * counts live in a sidecar file beside it. Everything here degrades to `null`
+ * rather than throwing: a read-only directory, a disk with no room, an archive
+ * that moved — any of those should cost the exact numbers, not the dashboard.
+ */
+/** Bump to force a rebuild when the tokenizer or the schema changes. */
+const ROLLUP_VERSION = 1;
+const HOUR_SECONDS = 3600;
+/**
+ * Tokenizer, kept identical to the live one in stats.ts.
+ *
+ * If these ever disagree the rollup silently answers a different question than
+ * the fallback path, which is worse than having no rollup at all — so the
+ * version above must be bumped whenever this changes.
+ */
+const WORD_TOKEN_RE = /[\p{L}\p{N}]{3,}/gu;
+const EMOJI_REGEX = /[\p{Emoji_Presentation}\p{Extended_Pictographic}]/gu;
+let cached = null;
+/** One failed build per fingerprint is enough; do not retry on every request. */
+let failedFingerprint = null;
+function archiveFingerprint(primaryDb) {
+    const stat = fs.statSync(primaryDb);
+    return `${ROLLUP_VERSION}:${stat.mtimeMs}:${stat.size}`;
+}
+function rollupPath(primaryDb) {
+    const directory = path.dirname(primaryDb);
+    const base = path.basename(primaryDb, path.extname(primaryDb));
+    return path.join(directory, `${base}-rollups.db`);
+}
+function createSchema(db) {
+    db.exec(`
+    DROP TABLE IF EXISTS meta;
+    DROP TABLE IF EXISTS term_bucket;
+    DROP TABLE IF EXISTS emoji_bucket;
+    DROP TABLE IF EXISTS message_bucket;
+
+    CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL);
+
+    -- Every token, stop words included: the word cloud's all/useful toggle is
+    -- applied when the report is built, so filtering here would remove a
+    -- choice the reader still has.
+    CREATE TABLE term_bucket (
+      term TEXT NOT NULL,
+      chat_jid TEXT NOT NULL,
+      hour INTEGER NOT NULL,
+      count INTEGER NOT NULL,
+      PRIMARY KEY (term, chat_jid, hour)
+    ) WITHOUT ROWID;
+
+    -- person_jid is who sent it, which for my own messages is the chat rather
+    -- than me; it matches how getEmojiAnalytics attributes them.
+    CREATE TABLE emoji_bucket (
+      emoji TEXT NOT NULL,
+      person_jid TEXT NOT NULL,
+      from_me INTEGER NOT NULL,
+      hour INTEGER NOT NULL,
+      count INTEGER NOT NULL,
+      PRIMARY KEY (emoji, person_jid, from_me, hour)
+    ) WITHOUT ROWID;
+
+    -- How many messages each hour was built from, so a report can state its
+    -- coverage exactly instead of inferring it.
+    CREATE TABLE message_bucket (
+      hour INTEGER PRIMARY KEY,
+      messages INTEGER NOT NULL
+    ) WITHOUT ROWID;
+
+    CREATE INDEX idx_term_hour ON term_bucket(hour);
+    CREATE INDEX idx_emoji_hour ON emoji_bucket(hour);
+  `);
+}
+/**
+ * Count every term and emoji in the archive into the sidecar.
+ *
+ * Exported for the `optimize-db` script, which prebuilds so the first request
+ * after a sync does not pay for it.
+ */
+export function buildRollups(source, target) {
+    createSchema(target);
+    const rows = source.prepare(`
+    SELECT
+      chat_jid,
+      CASE WHEN from_me = 1 THEN chat_jid ELSE COALESCE(sender_jid, chat_jid) END AS person_jid,
+      from_me,
+      ts,
+      text
+    FROM messages
+    WHERE text IS NOT NULL AND TRIM(text) <> ''
+  `).all();
+    const terms = new Map();
+    const emoji = new Map();
+    const messages = new Map();
+    for (const row of rows) {
+        const hour = Math.floor(row.ts / HOUR_SECONDS);
+        messages.set(hour, (messages.get(hour) ?? 0) + 1);
+        // A tab separator cannot occur in a token, and JIDs do not contain one
+        // either, so splitting the key back apart is unambiguous.
+        for (const term of row.text.toLowerCase().match(WORD_TOKEN_RE) ?? []) {
+            const key = `${term}\t${row.chat_jid}\t${hour}`;
+            terms.set(key, (terms.get(key) ?? 0) + 1);
+        }
+        for (const glyph of row.text.match(EMOJI_REGEX) ?? []) {
+            const key = `${glyph}\t${row.person_jid}\t${row.from_me}\t${hour}`;
+            emoji.set(key, (emoji.get(key) ?? 0) + 1);
+        }
+    }
+    const insertTerm = target.prepare('INSERT INTO term_bucket (term, chat_jid, hour, count) VALUES (?, ?, ?, ?)');
+    const insertEmoji = target.prepare('INSERT INTO emoji_bucket (emoji, person_jid, from_me, hour, count) VALUES (?, ?, ?, ?, ?)');
+    const insertMessages = target.prepare('INSERT INTO message_bucket (hour, messages) VALUES (?, ?)');
+    target.transaction(() => {
+        for (const [key, count] of terms) {
+            const [term, chatJid, hour] = key.split('\t');
+            insertTerm.run(term, chatJid, Number(hour), count);
+        }
+        for (const [key, count] of emoji) {
+            const [glyph, personJid, fromMe, hour] = key.split('\t');
+            insertEmoji.run(glyph, personJid, Number(fromMe), Number(hour), count);
+        }
+        for (const [hour, count] of messages) {
+            insertMessages.run(hour, count);
+        }
+    })();
+    return rows.length;
+}
+function writeMeta(db, fingerprint, messages) {
+    const set = db.prepare('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)');
+    set.run('fingerprint', fingerprint);
+    set.run('messages', String(messages));
+    set.run('built_at', new Date().toISOString());
+}
+function readMeta(db, key) {
+    try {
+        const row = db.prepare('SELECT value FROM meta WHERE key = ?').get(key);
+        return row?.value ?? null;
+    }
+    catch {
+        // No meta table means an aborted build; treat it as absent.
+        return null;
+    }
+}
+/**
+ * The rollup for the current archive, building it if it is missing or stale.
+ *
+ * Returns null when the counts are unavailable for any reason, which is the
+ * caller's signal to fall back to scanning messages directly.
+ */
+export function getRollups(source = getDb()) {
+    // Derived from the handle we were given, never from ambient path state. An
+    // earlier version resolved the configured archive path instead, so any caller
+    // holding a different database — every test using an in-memory one — was
+    // silently served counts from somebody else's archive.
+    const primaryDb = source.name;
+    if (!primaryDb || primaryDb === ':memory:' || primaryDb === '')
+        return null;
+    let fingerprint;
+    try {
+        fingerprint = archiveFingerprint(primaryDb);
+    }
+    catch {
+        return null;
+    }
+    if (cached?.fingerprint === fingerprint)
+        return cached.handle;
+    if (failedFingerprint === fingerprint)
+        return null;
+    closeRollups();
+    try {
+        const db = new Database(rollupPath(primaryDb));
+        db.pragma('journal_mode = WAL');
+        let messages;
+        if (readMeta(db, 'fingerprint') === fingerprint) {
+            messages = Number(readMeta(db, 'messages') ?? 0);
+        }
+        else {
+            messages = buildRollups(source, db);
+            writeMeta(db, fingerprint, messages);
+        }
+        const handle = { db, messages };
+        cached = { fingerprint, handle };
+        return handle;
+    }
+    catch {
+        // Read-only directory, no disk space, a corrupt sidecar — none of these
+        // should cost more than the exactness they were buying.
+        failedFingerprint = fingerprint;
+        cached = null;
+        return null;
+    }
+}
+/**
+ * Build (or rebuild) the sidecar for an archive at a known path.
+ *
+ * The runtime decides a rollup is current by comparing fingerprints, so the
+ * prebuild has to stamp the fingerprint the same way — hence one function
+ * rather than two that have to agree.
+ */
+export function rebuildRollupsFor(primaryDb) {
+    const file = rollupPath(primaryDb);
+    const source = new Database(primaryDb, { fileMustExist: true, readonly: true });
+    const target = new Database(file);
+    try {
+        target.pragma('journal_mode = WAL');
+        const messages = buildRollups(source, target);
+        writeMeta(target, archiveFingerprint(primaryDb), messages);
+        return { file, messages };
+    }
+    finally {
+        target.close();
+        source.close();
+    }
+}
+/** The first hour bucket a period covers; buckets are whole hours of unix time. */
+export function hourBucket(since) {
+    return Math.floor(since / HOUR_SECONDS);
+}
+/** Messages the rollup holds at or after `since`, for honest coverage reporting. */
+export function messagesSince(handle, since) {
+    const row = handle.db
+        .prepare('SELECT COALESCE(SUM(messages), 0) AS total FROM message_bucket WHERE hour >= ?')
+        .get(hourBucket(since));
+    return row.total;
+}
+export function closeRollups() {
+    try {
+        cached?.handle.db.close();
+    }
+    catch {
+        // Already closed, or never opened.
+    }
+    cached = null;
+}
+/** Called after an import, when the sidecar describes an archive that is gone. */
+export function invalidateRollups() {
+    closeRollups();
+    failedFingerprint = null;
+}

package/apps/api/dist/lib/searchFilters.js

@@ -0,0 +1,141 @@
+import { parsePeriod, sinceTimestamp } from './query.js';
+import { firstQueryString, resolveStatsTimeZone, tsModifierSql } from './timezone.js';
+/** Bad filter input, reported as a 400 rather than silently widening the results. */
+export class SearchFilterError extends Error {
+    code = 'VALIDATION_ERROR';
+}
+/** Longer than any JID or media type; only here so a junk URL fails clearly. */
+const MAX_VALUE_LENGTH = 256;
+const SECONDS_PER_DAY = 86_400;
+function parseText(value, name) {
+    const text = firstQueryString(value);
+    if (text && text.length > MAX_VALUE_LENGTH) {
+        throw new SearchFilterError(`${name} is too long.`);
+    }
+    return text;
+}
+/** A real calendar date as YYYY-MM-DD, returned as UTC-midnight epoch seconds alongside. */
+function parseDay(value, name) {
+    const day = firstQueryString(value);
+    if (!day)
+        return undefined;
+    const epochMs = /^\d{4}-\d{2}-\d{2}$/.test(day) ? Date.parse(`${day}T00:00:00Z`) : NaN;
+    // Date.parse rejects 2023-13-01 but rolls 2023-02-30 over to March, hence the round trip.
+    if (Number.isNaN(epochMs) || new Date(epochMs).toISOString().slice(0, 10) !== day) {
+        throw new SearchFilterError(`${name} must be a date in YYYY-MM-DD form.`);
+    }
+    return { day, epoch: epochMs / 1000 };
+}
+function parseIntegerInRange(value, name, max) {
+    const raw = firstQueryString(value);
+    if (!raw)
+        return undefined;
+    const parsed = /^\d{1,2}$/.test(raw) ? Number(raw) : NaN;
+    if (Number.isNaN(parsed) || parsed > max) {
+        throw new SearchFilterError(`${name} must be a whole number from 0 to ${max}.`);
+    }
+    return parsed;
+}
+/**
+ * Every spelling of one person in `messages`: the archive files them under a
+ * phone JID and an opaque `@lid`, and the reports merge the two, so a drill-down
+ * from a report has to as well or its count will not match.
+ */
+function identityJids(db, jid) {
+    const rows = db
+        .prepare('SELECT jid, lid FROM contacts WHERE jid = @jid OR lid = @jid')
+        .all({ jid });
+    const jids = new Set([jid]);
+    for (const row of rows) {
+        jids.add(row.jid);
+        if (row.lid)
+            jids.add(row.lid);
+    }
+    return JSON.stringify([...jids]);
+}
+/**
+ * Translate search filters into SQL, using the same expressions as the stats
+ * routes so a chart's bucket and the messages listed behind it stay in step:
+ *
+ *  - `sender` is who wrote the message (`me` for your own).
+ *  - `contact` is the Top Contacts definition, both directions: what they sent
+ *    anywhere plus what you sent in your direct chat with them.
+ *  - `period` is the dashboard's rolling window, not a calendar range.
+ *  - `from`, `to`, `hour` and `weekday` read the viewer's calendar via `timeZone`.
+ */
+export function parseSearchFilters(params, db) {
+    const conditions = [];
+    const bindings = {};
+    const localTs = tsModifierSql(resolveStatsTimeZone(params.timeZone), 'messages.ts');
+    const chat = parseText(params.chat, 'chat');
+    if (chat) {
+        conditions.push('messages.chat_jid = @chat');
+        bindings.chat = chat;
+    }
+    const sender = parseText(params.sender, 'sender');
+    if (sender === 'me') {
+        conditions.push('messages.from_me = 1');
+    }
+    else if (sender) {
+        conditions.push(`
+      messages.from_me = 0
+      AND COALESCE(messages.sender_jid, messages.chat_jid) IN (SELECT value FROM json_each(@senderJids))
+    `);
+        bindings.senderJids = identityJids(db, sender);
+    }
+    const contact = parseText(params.contact, 'contact');
+    if (contact) {
+        conditions.push(`
+      CASE WHEN messages.from_me = 1 THEN messages.chat_jid ELSE COALESCE(messages.sender_jid, messages.chat_jid) END
+        IN (SELECT value FROM json_each(@contactJids))
+    `);
+        bindings.contactJids = identityJids(db, contact);
+    }
+    const mediaType = parseText(params.mediaType, 'mediaType');
+    if (mediaType === 'any') {
+        conditions.push("messages.media_type IS NOT NULL AND messages.media_type <> ''");
+    }
+    else if (mediaType) {
+        conditions.push('messages.media_type = @mediaType');
+        bindings.mediaType = mediaType;
+    }
+    const rawPeriod = firstQueryString(params.period);
+    if (rawPeriod) {
+        const period = parsePeriod(rawPeriod);
+        if (period !== rawPeriod) {
+            throw new SearchFilterError('period must be day, week, month, year or all.');
+        }
+        if (period !== 'all') {
+            conditions.push('messages.ts >= @since');
+            bindings.since = sinceTimestamp(period);
+        }
+    }
+    const from = parseDay(params.from, 'from');
+    const to = parseDay(params.to, 'to');
+    if (from && to && from.day > to.day) {
+        throw new SearchFilterError('from must not be after to.');
+    }
+    // The raw `ts` bound is what lets these use the index; no zone is a full day
+    // from UTC plus a margin, and the `date()` test settles the exact edge.
+    if (from) {
+        conditions.push(`messages.ts >= @fromEpoch AND date(${localTs}) >= @from`);
+        bindings.from = from.day;
+        bindings.fromEpoch = from.epoch - SECONDS_PER_DAY;
+    }
+    if (to) {
+        conditions.push(`messages.ts < @toEpoch AND date(${localTs}) <= @to`);
+        bindings.to = to.day;
+        bindings.toEpoch = to.epoch + 2 * SECONDS_PER_DAY;
+    }
+    const hour = parseIntegerInRange(params.hour, 'hour', 23);
+    if (hour !== undefined) {
+        conditions.push(`CAST(strftime('%H', ${localTs}) AS INTEGER) = @hour`);
+        bindings.hour = hour;
+    }
+    const weekday = parseIntegerInRange(params.weekday, 'weekday', 6);
+    if (weekday !== undefined) {
+        conditions.push(`CAST(strftime('%w', ${localTs}) AS INTEGER) = @weekday`);
+        bindings.weekday = weekday;
+    }
+    return { conditions, bindings };
+}

package/apps/api/dist/lib/searchIndex.js

@@ -1,4 +1,4 @@
-import { cleanDisplayNameSql, contactDisplayNameSql, contactMatchSql } from './displayName.js';
+import { cleanDisplayNameSql, contactDisplayNameSql, contactLeftJoins } from './displayName.js';
 export const MESSAGE_SEARCH_FTS_TABLE = 'messages_fts';
 export function hasMessageSearchIndex(db) {
     const row = db.prepare(`
@@ -51,7 +51,7 @@ export function createSearchIndexes(db) {
       COALESCE(${contactDisplayNameSql('sender_contacts')}, '')
     FROM messages
     LEFT JOIN chats ON chats.jid = messages.chat_jid
-    LEFT JOIN contacts AS chat_contacts ON ${contactMatchSql('chat_contacts', 'messages.chat_jid')}
-    LEFT JOIN contacts AS sender_contacts ON ${contactMatchSql('sender_contacts', 'messages.sender_jid')};
+    ${contactLeftJoins('chat_contacts', 'messages.chat_jid')}
+    ${contactLeftJoins('sender_contacts', 'messages.sender_jid')};
   `);
 }

package/apps/api/dist/lib/selfIdentity.js

@@ -0,0 +1,42 @@
+/**
+ * Which roster entries are the archive's owner.
+ *
+ * Messages I send carry `from_me = 1` and, in a group, the *group's* JID as the
+ * sender — my own JID is never written down. So every group roster lists me as
+ * a member who has never spoken, and a lurker report proudly named the person
+ * reading it as the quietest member of all 100 of their groups.
+ *
+ * There is no self column to read, but there is a structural giveaway: I am a
+ * member of every group I post in, and nobody else is. Taking the participants
+ * present in *all* of them is decisive in practice — on a real archive the two
+ * hits (a phone JID and its `@lid` twin, both mine) covered 100 of 100 groups
+ * while the next-most-common member reached 33.
+ *
+ * Below MIN_GROUPS the intersection means little: in two shared groups a spouse
+ * is indistinguishable from the account owner, so the answer is "unknown" and
+ * callers fall back to counting me as an ordinary member.
+ */
+const MIN_GROUPS = 3;
+export function resolveSelfJids(db) {
+    const total = db.prepare(`
+    SELECT COUNT(DISTINCT messages.chat_jid) AS count
+    FROM messages
+    JOIN chats ON chats.jid = messages.chat_jid
+    WHERE messages.from_me = 1 AND chats.kind = 'group'
+  `).get().count;
+    if (total < MIN_GROUPS)
+        return new Set();
+    const rows = db.prepare(`
+    SELECT group_participants.user_jid AS jid
+    FROM group_participants
+    WHERE group_participants.group_jid IN (
+      SELECT DISTINCT messages.chat_jid
+      FROM messages
+      JOIN chats ON chats.jid = messages.chat_jid
+      WHERE messages.from_me = 1 AND chats.kind = 'group'
+    )
+    GROUP BY group_participants.user_jid
+    HAVING COUNT(DISTINCT group_participants.group_jid) = @total
+  `).all({ total });
+    return new Set(rows.map((row) => row.jid));
+}

package/apps/api/dist/lib/statsCache.js

@@ -0,0 +1,83 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import { getResolvedPaths } from '../runtimePaths.js';
+/**
+ * Stats responses are pure functions of (archive contents, query params) and the
+ * archive is opened read-only, so a result stays valid until the DB file changes.
+ *
+ * Two things can invalidate an entry:
+ *   - the archive fingerprint (path + mtime + size) changes — a re-sync, or the
+ *     user pointing the dashboard at a different DB via Settings;
+ *   - the time bucket rolls over — period windows like "last week" are relative
+ *     to now, so entries expire after STATS_CACHE_TTL_MS.
+ *
+ * Both live in the key prefix, so a change drops every stale entry at once.
+ */
+export const STATS_CACHE_TTL_MS = 5 * 60 * 1000;
+const MAX_ENTRIES = 100;
+const cache = new Map();
+let currentPrefix = '';
+function archiveFingerprint() {
+    const { primaryDb } = getResolvedPaths();
+    try {
+        const stat = fs.statSync(primaryDb);
+        return `${primaryDb}:${stat.mtimeMs}:${stat.size}`;
+    }
+    catch {
+        return `${primaryDb}:unavailable`;
+    }
+}
+/** Stable, collision-free encoding of the query params a route was called with. */
+function serializeParams(params) {
+    const entries = Object.entries(params)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => [key, JSON.stringify(value) ?? 'null'])
+        .sort(([a], [b]) => a.localeCompare(b));
+    return JSON.stringify(entries);
+}
+/**
+ * Build the cache key for a stats request, dropping the cache first if the
+ * archive or the time bucket has moved on since the last call.
+ */
+export function statsCacheKey(route, params, now = Date.now()) {
+    const prefix = `${archiveFingerprint()}|${Math.floor(now / STATS_CACHE_TTL_MS)}`;
+    if (prefix !== currentPrefix) {
+        cache.clear();
+        currentPrefix = prefix;
+    }
+    return `${prefix}|${route}|${serializeParams(params)}`;
+}
+/**
+ * Strong validator derived from the key. The key already pins the archive state
+ * and the params, so a matching If-None-Match means the client holds the current
+ * value — we can answer 304 without opening the database at all.
+ */
+export function etagFor(key) {
+    return `"${createHash('sha1').update(key).digest('base64url')}"`;
+}
+/** Memoize `compute` under `key`. Thrown errors are never cached. */
+export function getCached(key, compute) {
+    if (cache.has(key)) {
+        const hit = cache.get(key);
+        // Re-insert to refresh LRU position.
+        cache.delete(key);
+        cache.set(key, hit);
+        return hit;
+    }
+    const value = compute();
+    cache.set(key, value);
+    while (cache.size > MAX_ENTRIES) {
+        const oldest = cache.keys().next().value;
+        if (oldest === undefined)
+            break;
+        cache.delete(oldest);
+    }
+    return value;
+}
+export function clearStatsCache() {
+    cache.clear();
+    currentPrefix = '';
+}
+export function statsCacheSize() {
+    return cache.size;
+}

package/apps/api/dist/lib/timezone.js

@@ -24,15 +24,130 @@ export function resolveStatsTimeZone(raw) {
         return 'UTC';
     }
 }
+const formattersCache = new Map();
+function getFormatter(timeZone) {
+    let formatter = formattersCache.get(timeZone);
+    if (!formatter) {
+        formatter = new Intl.DateTimeFormat('en-GB', {
+            timeZone,
+            hour: 'numeric',
+            hourCycle: 'h23',
+        });
+        formattersCache.set(timeZone, formatter);
+    }
+    return formatter;
+}
 /** Calendar hour 0–23 for Unix epoch seconds in the given IANA time zone. */
 export function hourInTimezone(epochSeconds, timeZone) {
-    const parts = new Intl.DateTimeFormat('en-GB', {
-        timeZone,
-        hour: 'numeric',
-        hourCycle: 'h23',
-    }).formatToParts(new Date(epochSeconds * 1000));
+    if (timeZone === 'UTC') {
+        return new Date(epochSeconds * 1000).getUTCHours();
+    }
+    const formatter = getFormatter(timeZone);
+    const parts = formatter.formatToParts(new Date(epochSeconds * 1000));
     const value = Number(parts.find((p) => p.type === 'hour')?.value);
     if (!Number.isFinite(value))
         return 0;
     return Math.min(23, Math.max(0, value));
 }
+const weekdayHourFormattersCache = new Map();
+const WEEKDAY_INDEX = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+/**
+ * Weekday (0 = Sunday) and hour 0–23 for Unix epoch seconds in `timeZone`.
+ *
+ * One formatter call yields both, which matters for the 168-cell rhythm grid:
+ * it reads every message in the period, and two Intl round-trips per row
+ * doubled the cost for no gain.
+ */
+export function weekdayHourInTimezone(epochSeconds, timeZone) {
+    const date = new Date(epochSeconds * 1000);
+    if (timeZone === 'UTC') {
+        return { weekday: date.getUTCDay(), hour: date.getUTCHours() };
+    }
+    let formatter = weekdayHourFormattersCache.get(timeZone);
+    if (!formatter) {
+        formatter = new Intl.DateTimeFormat('en-US', { timeZone, weekday: 'short', hour: 'numeric', hourCycle: 'h23' });
+        weekdayHourFormattersCache.set(timeZone, formatter);
+    }
+    const parts = formatter.formatToParts(date);
+    const weekday = WEEKDAY_INDEX[parts.find((p) => p.type === 'weekday')?.value ?? ''] ?? 0;
+    const hour = Number(parts.find((p) => p.type === 'hour')?.value);
+    return { weekday, hour: Number.isFinite(hour) ? Math.min(23, Math.max(0, hour)) : 0 };
+}
+const dateFormattersCache = new Map();
+function getDateFormatter(timeZone) {
+    let formatter = dateFormattersCache.get(timeZone);
+    if (!formatter) {
+        // en-CA renders as YYYY-MM-DD, which is the shape every bucket key uses.
+        formatter = new Intl.DateTimeFormat('en-CA', {
+            timeZone,
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit',
+        });
+        dateFormattersCache.set(timeZone, formatter);
+    }
+    return formatter;
+}
+/** Calendar date as YYYY-MM-DD for Unix epoch seconds in the given IANA time zone. */
+export function dateInTimezone(epochSeconds, timeZone) {
+    if (timeZone === 'UTC') {
+        return new Date(epochSeconds * 1000).toISOString().slice(0, 10);
+    }
+    return getDateFormatter(timeZone).format(new Date(epochSeconds * 1000));
+}
+/** Calendar month as YYYY-MM for Unix epoch seconds in the given IANA time zone. */
+export function monthInTimezone(epochSeconds, timeZone) {
+    return dateInTimezone(epochSeconds, timeZone).slice(0, 7);
+}
+/** Zone's UTC offset in minutes at a given instant (positive east of Greenwich). */
+export function timeZoneOffsetMinutes(timeZone, at = new Date()) {
+    if (timeZone === 'UTC')
+        return 0;
+    const parts = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        hourCycle: 'h23',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+    }).formatToParts(at);
+    const field = (type) => Number(parts.find((p) => p.type === type)?.value);
+    const asUtc = Date.UTC(field('year'), field('month') - 1, field('day'), field('hour'), field('minute'), field('second'));
+    if (!Number.isFinite(asUtc))
+        return 0;
+    // Sub-second drift between the two readings is irrelevant at minute resolution.
+    return Math.round((asUtc - Math.floor(at.getTime() / 1000) * 1000) / 60_000);
+}
+/** IANA zone the API process itself is running in. */
+export const SERVER_TIME_ZONE = Intl.DateTimeFormat().resolvedOptions().timeZone;
+/**
+ * SQLite modifiers that move a `ts` column into `timeZone`'s calendar.
+ *
+ * SQLite ships no IANA database, so only two conversions are exact: UTC, and
+ * the server's own zone via `'localtime'` — which *is* DST-correct because
+ * SQLite defers to the C library. This dashboard is served from the same
+ * machine as the browser, so the requested zone is the server zone in practice
+ * and that branch is the one that runs.
+ *
+ * Any other zone falls back to the zone's offset *right now*, applied uniformly.
+ * That misfiles messages sent within `offset` hours of midnight on historical
+ * dates whose DST state differs from today's — a far smaller error than the
+ * blanket UTC bucketing this replaces.
+ */
+export function timeZoneModifiers(timeZone) {
+    if (timeZone === 'UTC')
+        return [];
+    if (timeZone === SERVER_TIME_ZONE)
+        return ["'localtime'"];
+    const offset = timeZoneOffsetMinutes(timeZone);
+    if (offset === 0)
+        return [];
+    // Numeric, so it can never carry anything injectable into the SQL text.
+    return [`'${offset > 0 ? '+' : '-'}${Math.abs(offset)} minutes'`];
+}
+/** `date(...)`/`strftime(...)` argument list for a timestamp column in `timeZone`. */
+export function tsModifierSql(timeZone, column = 'ts') {
+    return [column, "'unixepoch'", ...timeZoneModifiers(timeZone)].join(', ');
+}