analytics improvements:

- keep visitor charts y-axis minimum range at 10
- keep 'all' chart x-axis minimum span at 30 days
- group crawler hits by (ip, ua) and list top pages visited, show crawler page load counts as N× prefix
- store and display geoip city, keep geoip country overwrite
- stream live updates over WebSocket /_api/ws/analytics
- include family ring arcs in transition map crop bounds
- remove top UA summary, limit crawlers to 10 and visits to 20
- human-readable relative timestamps with UTC tooltip

docs/analytics.md

@@ -8,8 +8,8 @@ Struct dumped to disk — separate from the kanta content database, path from
 - `pagerite/analytics.py` — data model (`Analytics`, `Visit`) and the `Store`
   (in-memory data + session map, atomic JSON persistence).
 - `pagerite/app.py` — entry-referer stashing in `show_page` (`_track_entry`),
-  the `POST /_a` ping endpoint, and `GET /_api/analytics` (admin-gated like
-  every `/_api` endpoint).
+  the `POST /_a` ping endpoint, and `WebSocket /_api/ws/analytics`
+  (admin-gated like every `/_api` endpoint).
 - `frontend/src/pagerite.js` — client navigation pings and the 📊 pen.
 - `frontend/src/AnalyticsView.vue` — viewer component rendered inside the
   normal site layout on the `/_a` analytics page.
@@ -59,7 +59,10 @@ The client (`pagerite.js`) POSTs fire-and-forget pings to `/_a` with
 - **Crawler hits**: every document GET is queued in RAM as a pending crawler
   hit.  If a ping from the same (IP, User-Agent) pair arrives within 10
   seconds the hit is discarded; otherwise it is written to `crawlers`.
-  Crawlers do not count as visits or views.
+  Crawlers do not count as visits or views.  In the analytics viewer, crawler
+  hits are grouped by the same (IP, User-Agent) pair and shown as a trail of
+  internal pages that crawler visited; the crawler table lists the most active
+  crawlers first rather than the most recent hits.
 
 ## Visits and sessions
 
@@ -86,6 +89,7 @@ Each `Visit` record:
 - `country` — two-letter country code.  Initially derived from the
   `Accept-Language` region subtag, but overwritten by the DB-IP MMDB result
   when a database is available,
+- `city` — city name from the DB-IP MMDB lookup, when available,
 - `ua` — raw `User-Agent` string from the initial ping,
 - `ua_pretty` — compact display form of the UA (browser/OS/device) when
   parsable, otherwise the raw string,
@@ -131,9 +135,9 @@ The 📊 pen in the banner corner (admins only, injected by pagerite.js next to
 the edit pens) links to `/_a`, the analytics page. It is a normal site page:
 the standard banner, navigation and footer stay in place, and the analytics
 content is rendered inside `#main`. The page itself is public, but the data
-still comes from `GET /_api/analytics`, which remains admin-gated like the
-rest of the management API; visitors without access see the viewer with a
-"could not be loaded" message.
+stream comes from `WebSocket /_api/ws/analytics`, which remains admin-gated
+like the rest of the management API; visitors without access see the viewer
+with a "could not be loaded" message.
 
 Because it is a real page, fetch-navigation handles it like any other internal
 link: clicking the 📊 pen (or any link to `/_a`) fetches the server-rendered
@@ -156,16 +160,19 @@ the smoothing time scale follows the unit: the month+ sigmas are 24× the
 hourly ones. The y max is derived from the smoothed curves so single-bucket
 spikes don't blow up the scale, and raw spikes are clamped into the plot.
 Axes always start at 0 and end at a multiple of a 1-2-5 major step (max 5
-labeled intervals, minor lines at fifths when integral; the floor is 1/h).
+labeled intervals, minor lines at fifths when integral; the minimum y-axis
+range is 10 so tiny values such as a single visit are not stretched to a
+fractional scale).
 The week range is aligned to Monday 00:00 UTC and overlays up to 8 previous
 weeks in the same accent color at decreasing opacity (the current week is
 truncated at the current bucket, never drawing fake zeroes for the future);
 its x labels are weekday names centered at midday UTC, without vertical grid
 lines (day boundaries would be misleading in the viewer's timezone). The
 month view labels days the same lineless way — day numbers at noon UTC,
-with the month name substituted for the 1st. Year and all are rolling
-windows ending at now, re-bucketed to daily points, with boundary lines at
-months/years. Below the charts: a radial **transition map** (all pages from
+with the month name substituted for the 1st. Year is a rolling 365-day window ending at now, re-bucketed to daily points,
+with boundary lines at months/years.  All uses the full data reach, but keeps
+at least the past 30 days so the chart never collapses to a tiny sliver when
+the site is young. Below the charts: a radial **transition map** (all pages from
 `/_api/pages` — front page at the center, each slug level on its own ring,
 siblings clockwise in navigation order from the top, radial gap equal to
 the arc spacing — opposite transition directions joined into organic
@@ -178,5 +185,7 @@ to the directional count with no in-flight limit, opposing directions
 offset onto parallel lanes. External referers show as a node row above the
 map, external exits as small nodes fanned outwards from their source
 page), per-page view
-counts, the top transitions and the 50 most recent visit trails. Data comes from `GET /_api/analytics`, which
-returns the raw JSON file contents.
+counts, the top transitions and the 50 most recent visit trails. Data is
+streamed live over `WebSocket /_api/ws/analytics`, which pushes the latest
+JSON snapshot on connect and again whenever the analytics file is updated
+(with a small server-side debounce to avoid flooding under high traffic).

frontend/src/AnalyticsView.vue

@@ -1,16 +1,14 @@
 <script setup>
-// Analytics viewer rendered as a normal page inside #main. Fetches the raw
-// collected data from /_api/analytics (admin-gated by the auth proxy) and
+// Analytics viewer rendered as a normal page inside #main. Receives live
+// analytics data over /_api/ws/analytics (admin-gated by the auth proxy) and
 // renders totals, smoothed visit/views curves, a transition map, and recent
 // visit/crawler tables. Read-only.
 // See docs/analytics.md for the data format.
-import { computed, onMounted, ref, watch } from 'vue'
+import { computed, onMounted, onUnmounted, ref, watch } from 'vue'
 import { RANGES } from './analytics/time.js'
 import {
   calcTotalViews,
   copyIp,
-  countCrawlerUas,
-  formatCounts,
   formatCrawlerRows,
   formatVisitRows,
 } from './analytics/format.js'
@@ -25,23 +23,54 @@ const props = defineProps({
 const data = ref(null)
 const pageTree = ref(null)
 const error = ref('')
+const now = ref(Date.now())
+let ws = null
+let reconnectTimeout = null
+let timeInterval = null
 
-onMounted(async () => {
-  try {
-    const res = await fetch('/_api/analytics')
-    if (!res.ok) throw new Error(res.statusText)
-    data.value = await res.json()
-  } catch {
+function connectAnalytics() {
+  if (ws) return
+  const proto = location.protocol === 'https:' ? 'wss:' : 'ws:'
+  ws = new WebSocket(`${proto}//${location.host}/_api/ws/analytics`)
+  ws.onopen = () => { error.value = '' }
+  ws.onmessage = (event) => {
+    try {
+      data.value = JSON.parse(event.data)
+    } catch {
+      error.value = 'analytics data could not be loaded'
+    }
+  }
+  ws.onerror = () => {
     error.value = 'analytics data could not be loaded'
   }
+  ws.onclose = () => {
+    ws = null
+    reconnectTimeout = setTimeout(connectAnalytics, 2000)
+  }
+}
+
+onMounted(async () => {
+  connectAnalytics()
+  now.value = Date.now()
+  timeInterval = setInterval(() => { now.value = Date.now() }, 30000)
   // The site tree for the transition map (all pages in menu order). Not
-  // fatal: without it the map falls back to transition endpoints only.
+  // fatal: without it the map just narrows to pages seen in transitions.
   try {
     const res = await fetch('/_api/pages')
     if (res.ok) pageTree.value = await res.json()
   } catch { /* map just narrows to pages seen in transitions */ }
 })
 
+onUnmounted(() => {
+  if (reconnectTimeout) clearTimeout(reconnectTimeout)
+  if (timeInterval) clearInterval(timeInterval)
+  if (ws) {
+    ws.onclose = null
+    ws.close()
+    ws = null
+  }
+})
+
 const visits = computed(() => data.value?.visits || [])
 const totalViews = computed(() => calcTotalViews(data.value?.views))
 
@@ -54,10 +83,9 @@ watch(range, (r) => {
   history.replaceState(null, '', url)
 })
 
-const visitRows = computed(() => formatVisitRows(visits.value, pageTree.value))
+const visitRows = computed(() => formatVisitRows(visits.value, pageTree.value, now.value))
 const crawlers = computed(() => data.value?.crawlers || [])
-const crawlerRows = computed(() => formatCrawlerRows(crawlers.value))
-const topCrawlerUas = computed(() => countCrawlerUas(crawlers.value).slice(0, 10))
+const crawlerRows = computed(() => formatCrawlerRows(crawlers.value, pageTree.value, now.value))
 
 function flagSvg(code) {
   return flagSvgs[code?.toUpperCase()] || ''
@@ -115,10 +143,10 @@ function countryName(code) {
               </thead>
               <tbody>
                 <tr v-for="(v, i) in visitRows" :key="i">
-                  <td class="when">{{ v.when }}</td>
+                  <td class="when" :title="v.whenTooltip">{{ v.when }}</td>
                   <td class="trail">
                     <a v-for="(s, si) in v.trail" :key="si"
-                       :href="s.path" :title="s.title" @click="emit('close')">
+                       :href="s.path" :title="s.title" @click="$emit('close')">
                       {{ s.slug }}
                     </a>
                   </td>
@@ -131,6 +159,8 @@ function countryName(code) {
                   <td>{{ v.lang }}</td>
                   <td class="country">
                     <span v-if="flagSvg(v.country)" class="flag" v-html="flagSvg(v.country)" :title="countryName(v.country) || v.country"></span>
+                    <template v-if="v.city !== '—'">{{ countryName(v.country) || v.country }}<br><small class="muted">{{ v.city }}</small></template>
+                    <template v-else-if="v.country !== '—'">{{ countryName(v.country) || v.country }}</template>
                     <template v-else>—</template>
                   </td>
                   <td class="ua" :title="v.uaRaw">{{ v.ua }}</td>
@@ -144,33 +174,32 @@ function countryName(code) {
 
         <section>
           <h2>Crawlers</h2>
-          <div v-if="topCrawlerUas.length" class="crawler-top-uas">
-            <p><strong>top UAs:</strong> {{ formatCounts(topCrawlerUas) }}</p>
-          </div>
           <div v-if="crawlerRows.length" class="visit-table-wrap">
             <table class="visit-table">
               <thead>
                 <tr>
                   <th>when</th>
-                  <th>entry</th>
+                  <th>pages</th>
                   <th>ip</th>
                   <th>ua</th>
-                  <th>referer</th>
-                  <th>query</th>
                 </tr>
               </thead>
               <tbody>
                 <tr v-for="(c, i) in crawlerRows" :key="i">
-                  <td class="when">{{ c.when }}</td>
-                  <td>{{ c.entry }}</td>
+                  <td class="when" :title="c.whenTooltip">{{ c.when }}</td>
+                  <td class="trail">
+                    <a v-for="(s, si) in c.pages" :key="si"
+                       :href="s.path" :title="`${s.title}${s.count > 1 ? ` (${s.count} hits)` : ''}`"
+                       @click="$emit('close')">
+                      <small v-if="s.count > 1" class="muted">{{ s.count }}×</small>{{ s.slug }}
+                    </a>
+                  </td>
                   <td>
                     <span class="clickable-ip"
                           :title="`Click to copy full IP: ${c.ip}`"
                           @click="copyIp(c.ip)">{{ c.ipDisplay }}</span>
                   </td>
                   <td class="ua" :title="c.uaRaw">{{ c.ua }}</td>
-                  <td>{{ c.referer }}</td>
-                  <td>{{ c.query }}</td>
                 </tr>
               </tbody>
             </table>
@@ -307,6 +336,12 @@ function countryName(code) {
   margin-left: 0.5rem;
 }
 
+.visit-table .trail small,
+.visit-table small.muted {
+  color: var(--muted);
+  font-size: 0.75em;
+}
+
 .visit-table .clickable-ip {
   cursor: pointer;
   text-decoration: underline;

frontend/src/analytics/chart.js

@@ -14,9 +14,9 @@ export const PAD_TOP = 14 // room above the highest point
 /**
  * Y always starts at 0; the max is a multiple of a 1-2-5 major step with at
  * most 5 intervals, so labeled ticks are always round and evenly divided.
- * Values are per-unit rates, so small scales are legitimate (a lone visit
- * smoothes to well under 1/unit) — the floor is 1, not 10. Minor lines
- * subdivide each major step in five when that yields integers.
+ * A minimum range of 10 keeps tiny near-zero values (e.g. a single visit)
+ * from being enlarged to a fractional scale; minor lines subdivide each
+ * major step in five when that yields integers.
  */
 export function yScale(maxValue) {
   let step = 1
@@ -27,9 +27,9 @@ export function yScale(maxValue) {
     }
   }
   let max = Math.ceil(maxValue / step) * step
-  if (max < 1) {
-    max = 1
-    step = 0.5
+  if (max < 10) {
+    max = 10
+    step = 2
   }
   const minor = step >= 5 && step % 5 === 0 ? step / 5 : null
   return { max, step, minor }

frontend/src/analytics/format.js

@@ -62,6 +62,59 @@ function slugOf(path) {
   return path === '/' ? '🏠' : path.split('/').pop()
 }
 
+/**
+ * Human-readable relative timestamp.  Adapted from cista-storage: uses
+ * ``Intl.RelativeTimeFormat`` for short intervals and a compact date for
+ * anything older than a week.
+ */
+export function formatWhen(ts, now = Date.now()) {
+  const date = new Date(ts)
+  const diff = date.getTime() - now
+  const adiff = Math.abs(diff)
+  const formatter = new Intl.RelativeTimeFormat('en', { numeric: 'auto' })
+  if (adiff <= 5000) return 'now'
+  if (adiff <= 60000) {
+    return formatter
+      .format(Math.round(diff / 1000), 'second')
+      .replace(' ago', '')
+      .replaceAll(' ', '\u202F')
+  }
+  if (adiff <= 3600000) {
+    return formatter
+      .format(Math.round(diff / 60000), 'minute')
+      .replace('utes', '')
+      .replace('ute', '')
+      .replaceAll(' ', '\u202F')
+  }
+  if (adiff <= 86400000) {
+    return formatter
+      .format(Math.round(diff / 3600000), 'hour')
+      .replaceAll(' ', '\u202F')
+  }
+  if (adiff <= 604800000) {
+    return formatter
+      .format(Math.round(diff / 86400000), 'day')
+      .replaceAll(' ', '\u202F')
+  }
+  let d = date
+    .toLocaleDateString('en-ie', {
+      weekday: 'short',
+      year: 'numeric',
+      month: 'short',
+      day: 'numeric',
+    })
+    .replace('Sept', 'Sep')
+  if (d.length === 14) d = d.replace(' ', ' \u2007')
+  d = d.replaceAll(' ', '\u202F').replace('\u202F', '\u00A0')
+  d = d.slice(0, -4) + d.slice(-2)
+  return d
+}
+
+/** Full UTC timestamp for tooltips, e.g. "2026-08-21 00:20:48 UTC". */
+export function formatWhenTooltip(ts) {
+  return new Date(ts).toISOString().replace('T', ' ').replace('Z', ' UTC')
+}
+
 /**
  * Format recent visits for display, newest first. Each step is a linked slug
  * pointing to its article; external referers/origins and direct entries are
@@ -133,31 +186,65 @@ export function countCrawlerUas(crawlers) {
 }
 
 /**
- * Format raw crawler hit records as rows for a technical table.  Missing
- * values become "—".
+ * Group raw crawler hits by the same (ip, ua) pair we use to tell a real
+ * visitor from a crawler, and format each group as a row showing every
+ * internal page that crawler visited.  Rows are sorted by total hits,
+ * most active crawler first, rather than by most recent hit.
  */
-export function formatCrawlerRows(crawlers) {
-  const dash = (s) => (s || '—')
-  return [...(crawlers || [])].reverse().map((c) => ({
-    when: new Date(c.start).toLocaleString(),
-    entry: dash(c.entry),
-    ip: c.ip || '',
-    ipDisplay: c.host || hostIP(c.ip) || c.ip || '—',
-    ua: c.ua_pretty || c.ua || '—',
-    uaRaw: c.ua || '',
-    referer: dash(c.referer),
-    query: dash(c.query),
-  }))
+export function formatCrawlerRows(crawlers, pageTree, now = Date.now()) {
+  const titles = buildTitleMap(pageTree)
+  const groups = new Map()
+  for (const c of crawlers || []) {
+    const key = `${c.ip}\0${c.ua}`
+    const g = groups.get(key) || {
+      ip: c.ip || '',
+      ua: c.ua_pretty || c.ua || '—',
+      uaRaw: c.ua || '',
+      lastStart: 0,
+      pages: new Map(),
+    }
+    const start = new Date(c.start).getTime()
+    if (start > g.lastStart) g.lastStart = start
+    if (c.entry?.startsWith('/')) {
+      g.pages.set(c.entry, (g.pages.get(c.entry) || 0) + 1)
+    }
+    groups.set(key, g)
+  }
+  const totalHits = (g) => {
+    let n = 0
+    for (const c of g.pages.values()) n += c
+    return n
+  }
+  return [...groups.values()]
+    .sort((a, b) => totalHits(b) - totalHits(a) || b.lastStart - a.lastStart)
+    .slice(0, 10)
+    .map((g) => ({
+      when: formatWhen(g.lastStart, now),
+      whenTooltip: formatWhenTooltip(g.lastStart),
+      pages: [...g.pages.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .map(([path, count]) => ({
+          path,
+          slug: slugOf(path),
+          title: titles.get(path) || '',
+          count,
+        })),
+      ip: g.ip,
+      ipDisplay: hostIP(g.ip) || g.ip || '—',
+      ua: g.ua,
+      uaRaw: g.uaRaw,
+      total: totalHits(g),
+    }))
 }
 
 /**
  * Format raw visit records as rows for a technical table.  Returns objects
  * with display strings; missing values become "—".  ``trail`` joins page
- * titles (when known) with " -> ".
+ * titles (when known) with " -> ". Only the 20 most recent visits are shown.
  */
-export function formatVisitRows(visits, pageTree) {
+export function formatVisitRows(visits, pageTree, now = Date.now()) {
   const titles = buildTitleMap(pageTree)
-  return [...(visits || [])].reverse().map((v) => {
+  return [...(visits || [])].reverse().slice(0, 20).map((v) => {
     const trail = [v.entry, ...(v.trail || [])]
       .filter((p) => p?.startsWith('/'))
       .map((p) => ({
@@ -170,7 +257,8 @@ export function formatVisitRows(visits, pageTree) {
       .join(', ')
     const dash = (s) => (s || '—')
     return {
-      when: new Date(v.start).toLocaleString(),
+      when: formatWhen(v.start, now),
+      whenTooltip: formatWhenTooltip(v.start),
       trail,
       referer: dash(v.referer),
       ip: v.ip || '',
@@ -178,6 +266,7 @@ export function formatVisitRows(visits, pageTree) {
       host: dash(v.host),
       lang: dash(v.lang),
       country: dash(v.country),
+      city: dash(v.city),
       ua: v.ua_pretty || v.ua || '—',
       uaRaw: v.ua || '',
       utm: utm || '—',

frontend/src/analytics/time.js

@@ -16,7 +16,7 @@ export const RANGES = {
   week: { label: 'week' },
   month: { label: 'month', span: 30 * DAY, bucket: 6 * HOUR },
   year: { label: 'year', span: 365 * DAY, bucket: DAY },
-  all: { label: 'all', span: null, bucket: DAY },
+  all: { label: 'all', span: null, bucket: DAY, minSpan: 30 * DAY },
 }
 
 /** Monday 00:00 UTC of the week containing t (epoch day 0 was a Thursday). */
@@ -89,16 +89,19 @@ export function weeklySeries(buckets) {
 /**
  * Rolling window for the non-week ranges (x max = now), counts converted
  * to per-day rates (the unit the month+ charts are read in).
+ * Ranges without a fixed span use the full data reach, but never less than
+ * their configured minSpan so the chart keeps a readable minimum x scale.
  */
 export function rollingSeries(buckets, rangeKey) {
   const raw = rawTimes(buckets)
   const times = Object.keys(raw).map(Number)
   if (!times.length) return null
-  const { span, bucket } = RANGES[rangeKey]
+  const { span, bucket, minSpan = 0 } = RANGES[rangeKey]
   const t1 = Math.floor(Date.now() / bucket) * bucket + bucket
+  const earliest = Math.floor(Math.min(...times) / bucket) * bucket
   const t0 = span != null
     ? t1 - span
-    : Math.floor(Math.min(...times) / bucket) * bucket
+    : Math.min(earliest, t1 - minSpan)
   const points = []
   for (let t = t0; t < t1; t += bucket) {
     points.push({ t, count: sumRange(raw, t, t + bucket) })

frontend/src/analytics/transitions.js

@@ -231,11 +231,33 @@ function buildFamilyArcs(nodes, radius) {
     arcs.push({
       d: `M ${Math.cos(a0) * r} ${Math.sin(a0) * r} `
        + `A ${r} ${r} 0 ${large} 1 ${Math.cos(a1) * r} ${Math.sin(a1) * r}`,
+      r,
+      a0,
+      a1,
     })
   }
   return arcs
 }
 
+/** Bounding box of a circular arc centred at the origin, sampled. */
+function arcBounds(r, a0, a1) {
+  let x0 = Infinity
+  let y0 = Infinity
+  let x1 = -Infinity
+  let y1 = -Infinity
+  const steps = 36
+  for (let i = 0; i <= steps; i++) {
+    const t = a0 + (a1 - a0) * (i / steps)
+    const x = Math.cos(t) * r
+    const y = Math.sin(t) * r
+    if (x < x0) x0 = x
+    if (y < y0) y0 = y
+    if (x > x1) x1 = x
+    if (y > y1) y1 = y
+  }
+  return { x0, y0, x1, y1 }
+}
+
 /** Collapse opposite transition directions into one unordered pair per page pair. */
 function aggregatePairs(internal) {
   const pairs = new Map() // unordered pair key -> [countAB, countBA]
@@ -584,8 +606,9 @@ export function buildTransitionGraph(data, pageTree) {
   const pairs = aggregatePairs(internal)
   const { edges, flows } = buildInternalEdges(pairs, byPath)
 
-  // Tight bounding box of the actual page nodes; internal edges and arcs
-  // stay within the node circles, so node bounds plus radius suffice.
+  // Tight bounding box of the actual page nodes; family ring arcs can sweep
+  // outside the node circle (e.g. a large arc between two siblings on the
+  // left side reaching around the right), so their geometry is included too.
   // External nodes extend the box below.
   const pad = 16
   const xs = nodes.map((n) => n.x)
@@ -596,6 +619,14 @@ export function buildTransitionGraph(data, pageTree) {
     x1: Math.max(...xs) + TNODE_R + pad,
     y1: Math.max(...ys) + TNODE_R + pad,
   }
+  for (const arc of arcs) {
+    if (arc.a0 == null) continue
+    const b = arcBounds(arc.r, arc.a0, arc.a1)
+    bounds.x0 = Math.min(bounds.x0, b.x0)
+    bounds.y0 = Math.min(bounds.y0, b.y0)
+    bounds.x1 = Math.max(bounds.x1, b.x1)
+    bounds.y1 = Math.max(bounds.y1, b.y1)
+  }
 
   const ext = buildExternal(external, byPath, radius, bounds)
   for (const xn of ext.extNodes) {

pagerite/analytics.py

@@ -17,6 +17,8 @@ rewritten atomically on every recorded event.
 import os
 import re
 import tempfile
+from collections.abc import Callable
+from contextlib import suppress
 from datetime import UTC, datetime, timedelta
 from pathlib import Path
 from urllib.parse import parse_qs, urlparse
@@ -67,7 +69,10 @@ class Visit(msgspec.Struct, omit_defaults=True):
     #: First Accept-Language tag, lowercased (e.g. "en-us").
     lang: str = ""
     #: Two-letter region subtag derived from ``lang`` (e.g. "US"), or "".
+    #: Overwritten by the DB-IP geoip lookup when a database is available.
     country: str = ""
+    #: City name from the DB-IP geoip lookup, or "".
+    city: str = ""
     #: Raw User-Agent header from the initial ping.
     ua: str = ""
     #: Compact display form of ``ua`` (browser/OS/device) when parsable.
@@ -196,6 +201,23 @@ class Store:
         #: Document GETs that have not yet been matched by a ping.  Kept
         #: in RAM only; expired entries are written to ``data.crawlers``.
         self.pending_crawlers: list[CrawlerHit] = []
+        #: Callables to notify when persisted data changes.  Registered by the
+        #: analytics WebSocket broadcaster.
+        self._on_change: list[Callable[[], None]] = []
+
+    def subscribe(self, callback: Callable[[], None]) -> None:
+        """Register a callback to be called after every persisted change."""
+        if callback not in self._on_change:
+            self._on_change.append(callback)
+
+    def unsubscribe(self, callback: Callable[[], None]) -> None:
+        """Remove a previously registered change callback."""
+        with suppress(ValueError):
+            self._on_change.remove(callback)
+
+    def _notify(self) -> None:
+        for callback in self._on_change:
+            callback()
 
     def _save(self) -> None:
         """Rewrite the JSON file atomically (temp file + rename)."""
@@ -208,6 +230,8 @@ class Store:
             os.replace(tmp, self.path)
         except OSError:
             pass  # analytics must never break page serving
+        else:
+            self._notify()
 
     def _flush_crawlers(self, now: datetime | None = None) -> None:
         """Move expired pending crawler hits into persistent ``data.crawlers``."""
@@ -268,6 +292,7 @@ class Store:
         *,
         host: str = "",
         country: str = "",
+        city: str = "",
     ) -> None:
         """Fill in host/geoip fields on an existing visit after async lookups."""
         if index < 0 or index >= len(self.data.visits):
@@ -280,6 +305,9 @@ class Store:
         if country:
             visit.country = country
             changed = True
+        if city:
+            visit.city = city
+            changed = True
         if changed:
             self._save()
 

pagerite/app.py

@@ -57,6 +57,10 @@ ANALYTICS_PATH = Path(
 )
 analytics_store = analytics.Store(ANALYTICS_PATH)
 
+# Live WebSocket clients for the analytics stream.
+_analytics_ws_clients: set[WebSocket] = set()
+_analytics_broadcast_task: asyncio.Task | None = None
+
 
 # Repository root from this file's location (pagerite/app.py -> ..).
 _REPO_ROOT = Path(__file__).resolve().parent.parent
@@ -121,6 +125,18 @@ class GeoIP:
             pass
         return ""
 
+    def city(self, ip: str) -> str:
+        """City name for ``ip``, or "" when unavailable."""
+        if not ip or self._reader is None:
+            return ""
+        try:
+            rec = self._reader.get(ip)
+            if rec:
+                return (rec.get("city") or {}).get("names", {}).get("en", "")
+        except Exception:
+            pass
+        return ""
+
 
 _geoip = GeoIP()
 
@@ -231,7 +247,9 @@ async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
     # Decompress/open the DB-IP MMDB once at startup.  Lookups are then
     # read-only and safe to run in background ``to_thread`` workers.
     await asyncio.to_thread(_geoip._load)
+    analytics_store.subscribe(_schedule_analytics_broadcast)
     yield
+    analytics_store.unsubscribe(_schedule_analytics_broadcast)
     await kanta.close()
 
 
@@ -615,13 +633,50 @@ async def _geoip_country(ip: str) -> str:
     return await asyncio.to_thread(_geoip.country, ip)
 
 
+async def _geoip_city(ip: str) -> str:
+    """Async wrapper around the DB-IP MMDB city lookup."""
+    return await asyncio.to_thread(_geoip.city, ip)
+
+
 async def _enrich_visit(index: int, ip: str) -> None:
     """Run non-blocking reverse-DNS and geoip enrichment for a new visit."""
     if not ip:
         return
     host = await _lookup_host(ip)
     country = await _geoip_country(ip)
-    analytics_store.enrich_visit(index, host=host, country=country)
+    city = await _geoip_city(ip)
+    analytics_store.enrich_visit(index, host=host, country=country, city=city)
+
+
+async def _broadcast_analytics() -> None:
+    """Send the current analytics snapshot to every connected WS client."""
+    if not _analytics_ws_clients:
+        return
+    payload = msgspec.json.encode(analytics_store.data).decode()
+    closed = set()
+    for ws in _analytics_ws_clients:
+        try:
+            await ws.send_text(payload)
+        except Exception:
+            closed.add(ws)
+    for ws in closed:
+        _analytics_ws_clients.discard(ws)
+
+
+async def _debounced_analytics_broadcast() -> None:
+    """Wait briefly, then broadcast the latest snapshot once."""
+    await asyncio.sleep(0.2)
+    await _broadcast_analytics()
+
+
+def _schedule_analytics_broadcast() -> None:
+    """Schedule a single debounced broadcast, ignoring duplicate triggers."""
+    global _analytics_broadcast_task
+    if _analytics_broadcast_task is not None and not _analytics_broadcast_task.done():
+        return
+    _analytics_broadcast_task = asyncio.get_running_loop().create_task(
+        _debounced_analytics_broadcast()
+    )
 
 
 class AnalyticsPing(BaseModel):
@@ -635,7 +690,7 @@ class AnalyticsPing(BaseModel):
 async def analytics_page(request: Request) -> HTMLResponse:
     """Render the analytics viewer as a normal site page at /_a.
 
-    The page itself is public, but the data endpoint (/_api/analytics) stays
+    The page itself is public, but the data stream (/_api/ws/analytics) stays
     admin-gated like the rest of /_api, so only authorized users see the
     statistics; others get the viewer with a "could not be loaded" message.
     """
@@ -727,16 +782,23 @@ def _check_reserved(path: str) -> None:
         )
 
 
-@app.get("/_api/analytics")
-async def get_analytics() -> Response:
-    """The collected visit analytics as JSON (see docs/analytics.md).
+@app.websocket("/_api/ws/analytics")
+async def analytics_websocket(ws: WebSocket) -> None:
+    """Stream the analytics snapshot, then push updates as they happen.
 
     Admin-only via the /_api forward-auth gate, like every management
     endpoint. Powers the analytics viewer rendered at /_a.
     """
-    return Response(
-        msgspec.json.encode(analytics_store.data), media_type="application/json"
-    )
+    await ws.accept()
+    await ws.send_text(msgspec.json.encode(analytics_store.data).decode())
+    _analytics_ws_clients.add(ws)
+    try:
+        while True:
+            await ws.receive_text()
+    except Exception:
+        pass
+    finally:
+        _analytics_ws_clients.discard(ws)
 
 
 @app.websocket("/_api/ws/editor")